diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 0c03b24..d32e7dc 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,8 +1,7 @@ { "name": "yuque", "owner": { - "name": "yuque", - "email": "willchen.babydog@gmail.com" + "name": "yuque" }, "metadata": { "description": "语雀 AI 生态 — MCP Tools and Skills for Yuque", diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md index e7d4ca8..908319a 100644 --- a/AGENT-INSTALL.md +++ b/AGENT-INSTALL.md @@ -1,111 +1,185 @@ -# Yuque AI Ecosystem — Agent Installation Guide +# Yuque AI — Agent Installation Guide -> This document is designed for AI agents (Claude Code, OpenCode, OpenClaw, etc.) to read and automatically install Yuque integration. Human-readable but optimized for machine execution. +> One file for every client. Designed for AI agents to read and auto-install; human-readable too. +> +> **TL;DR for agents:** the canonical skills live in [`skills/`](./skills/) (standard SKILL.md format — frontmatter + markdown). Any client that supports skills can copy them directly. The MCP server is `npx -y yuque-mcp` with a Yuque token. Client-specific steps below. -## Step 1: Identify Your Environment - -Determine which AI coding client you are running in and follow the corresponding guide: - -- **Claude Code** → See [plugins/claude-code/AGENT-INSTALL.md](./plugins/claude-code/AGENT-INSTALL.md) -- **OpenCode** → See [plugins/opencode/AGENT-INSTALL.md](./plugins/opencode/AGENT-INSTALL.md) -- **Cursor / GitHub Copilot (VS Code) / Windsurf / Other Editors** → See [shared/mcp-config/AGENT-INSTALL.md](./shared/mcp-config/AGENT-INSTALL.md) -- **OpenClaw** → See [plugins/openclaw/README.md](./plugins/openclaw/README.md) +--- -### How to Detect Your Client +## Step 0: Prerequisites (all clients) ```bash -# Check if Claude Code is available -claude --version 2>/dev/null && echo "CLIENT=claude-code" +# Node.js >= 20 (18 is EOL) +node --version -# Check if OpenCode is available -opencode --version 2>/dev/null && echo "CLIENT=opencode" +# npx available +npx --version -# Check if running inside Cursor -[ -n "$CURSOR_SESSION" ] && echo "CLIENT=cursor" +# Yuque token set (get one at https://www.yuque.com/settings/tokens) +[ -n "$YUQUE_TOKEN" ] && echo "TOKEN=set" || echo "TOKEN=missing" +``` -# Check if running inside VS Code -[ -n "$VSCODE_PID" ] && echo "CLIENT=vscode" +Verify the token independently of any client: -# Check if GitHub Copilot extension is installed (required for MCP support in VS Code) -code --list-extensions 2>/dev/null | grep -i "github.copilot" && echo "COPILOT=installed" +```bash +curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/user +# ✅ JSON with your user profile ❌ 401 = invalid token, regenerate it ``` -## Step 2: Prerequisites +> Note for MCP configs: the `yuque-mcp` server process reads the token from `--token=...` or the `YUQUE_PERSONAL_TOKEN` env var (not `YUQUE_TOKEN` — configs below handle the mapping). + +--- + +## Claude Code (recommended path) -Before proceeding with any installation method, ensure the following: +The only formally packaged distribution — one command installs MCP server + all skills, with updates. ```bash -# Check Node.js version (>= 20 required; Node 18 is EOL) -node --version -# Expected output: v20.x.x or higher +# 1. Register the marketplace (this alone installs nothing) +claude plugin marketplace add yuque/yuque-ecosystem -# Check npm is available -npm --version +# 2. Install the plugin — required step +claude plugin install yuque-personal@yuque -# Check npx is available -npx --version +# 3. Token via env var +export YUQUE_TOKEN="your_token_here" # add to ~/.zshrc for persistence ``` -If Node.js is not installed or version is below 20: +Verify: ```bash -# Install via nvm (recommended) -curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash -source ~/.bashrc # or ~/.zshrc -nvm install 20 -nvm use 20 +claude plugin list | grep yuque-personal +# ✅ "yuque-personal" appears ❌ re-run step 2 and check its error output ``` -## Step 3: Get a Yuque API Token - -1. Navigate to -2. Click **"Create New Token"** -3. Grant the following permissions: - - ✅ Read documents - - ✅ Write documents - - ✅ Read knowledge bases - - ✅ Manage knowledge bases (optional, for create/delete operations) -4. Copy the generated token -5. Store it securely: +MCP-only alternative (no skills): ```bash -# Option A: Set as environment variable (recommended) -export YUQUE_TOKEN="your_token_here" +claude mcp add yuque-mcp -- npx -y yuque-mcp --token=$YUQUE_TOKEN +claude mcp list | grep -i yuque +``` + +Uninstall: `claude plugin uninstall yuque-personal`, `claude plugin marketplace remove yuque`, or `claude mcp remove yuque-mcp`. + +--- -# Option B: Add to your shell profile for persistence -echo 'export YUQUE_TOKEN="your_token_here"' >> ~/.zshrc # or ~/.bashrc -source ~/.zshrc +## OpenCode + +```bash +# 1. MCP server — global config uses {env:YUQUE_TOKEN}, resolved at runtime, +# so no plaintext token lands in the file +mkdir -p ~/.config/opencode +cat > ~/.config/opencode/opencode.json << 'EOF' +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + "yuque": { + "type": "local", + "command": ["npx", "-y", "yuque-mcp", "--token={env:YUQUE_TOKEN}"], + "enabled": true + } + } +} +EOF +# (merge the mcp.yuque entry instead if the file already exists) + +# 2. Skills — copy the canonical directory +REPO_DIR="/path/to/yuque-ecosystem" # cloned checkout +mkdir -p ~/.config/opencode/skills +cp -r "$REPO_DIR/skills/"* ~/.config/opencode/skills/ ``` -## Step 4: Verify Token +Project-level variants: `opencode.json` in the project root, skills in `.opencode/skills/`. Never write a literal token into a project-level config — it is too easy to commit. + +Verify: `opencode mcp list` shows `yuque`; `opencode mcp debug yuque` shows tools. + +--- + +## OpenClaw ```bash -# Quick test — should return your user info as JSON (401 = invalid token) -curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/user +# 1. Skills — copy the canonical directory into OpenClaw's skills dir +REPO_DIR="/path/to/yuque-ecosystem" +mkdir -p ~/.openclaw/skills +cp -r "$REPO_DIR/skills/"* ~/.openclaw/skills/ +``` + +2. MCP server — add to OpenClaw's `mcpServers` config: + +```json +{ + "mcpServers": { + "yuque-mcp": { + "command": "npx", + "args": ["-y", "yuque-mcp"], + "env": { "YUQUE_PERSONAL_TOKEN": "your-yuque-token" } + } + } +} ``` -## Step 5: Follow Client-Specific Guide +--- + +## Cursor / VS Code (Copilot) / Windsurf / other MCP editors + +Copy the matching template from [`shared/mcp-config/`](./shared/mcp-config/) and replace `YOUR_YUQUE_TOKEN`: + +| Client | Template | Destination | +|--------|----------|-------------| +| Cursor | `cursor.json` | `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) | +| VS Code (requires GitHub Copilot extension) | `vscode.json` | `.vscode/mcp.json` | +| Windsurf | `windsurf.json` | `.windsurf/mcp.json` | + +> **Security:** project-level configs contain a plaintext token after replacement — add them to `.gitignore`: +> +> ```bash +> printf '%s\n' '.cursor/mcp.json' '.vscode/mcp.json' '.windsurf/mcp.json' >> .gitignore +> ``` + +These editors get MCP tools only. If the client supports skills (SKILL.md), also copy [`skills/`](./skills/) into its skills directory. + +--- + +## Any other agent -Now proceed to the guide for your specific client (see Step 1 links above). +1. **MCP tools:** run `npx -y yuque-mcp --token=$YUQUE_TOKEN` as a stdio MCP server, or set `YUQUE_PERSONAL_TOKEN` in its env. +2. **Skills:** copy [`skills/`](./skills/) into wherever your client discovers SKILL.md files. Each skill is self-contained (frontmatter `name`/`description` + workflow instructions) and only assumes the `yuque-mcp` tools are available. --- -## Quick Reference: All Installation Methods +## Available After Installation + +### MCP Tools (from `yuque-mcp`) + +| Category | Tools | +|----------|-------| +| User | `yuque_get_user` | +| Search | `yuque_search` | +| Books (知识库) | `yuque_list_books`, `yuque_get_book`, `yuque_create_book`, `yuque_update_book` | +| Docs | `yuque_list_docs`, `yuque_get_doc`, `yuque_create_doc`, `yuque_update_doc` | +| TOC | `yuque_get_toc`, `yuque_update_toc` | +| Notes (小记) | `yuque_list_notes`, `yuque_get_note`, `yuque_create_note`, `yuque_update_note` | +| Boards (画板) | `yuque_get_resource`, `yuque_create_resource`, `yuque_update_resource` | + +### Skills (8) + +smart-search, smart-summary, daily-capture, reading-digest, note-refine, knowledge-connect, style-extract, stale-detector -| Client | Method | Command | -|--------|--------|---------| -| Claude Code | Marketplace | `claude plugin marketplace add yuque/yuque-ecosystem && claude plugin install yuque-personal@yuque` | -| Claude Code | MCP Direct | `claude mcp add yuque-mcp -- npx -y yuque-mcp --token=$YUQUE_TOKEN` | -| OpenCode | Config File | Add to `opencode.json` (see OpenCode guide) | -| Cursor | Config File | Add to `.cursor/mcp.json` (see MCP config guide) | -| VS Code | Config File | Add to `.vscode/mcp.json` (requires GitHub Copilot extension; see MCP config guide) | -| Windsurf | Config File | Add to `.windsurf/mcp.json` (see MCP config guide) | +Functional test inside any client session: + +``` +> Use the yuque_get_user tool to get my user info +``` + +--- ## Troubleshooting | Symptom | Cause | Fix | |---------|-------|-----| -| `node: command not found` | Node.js not installed | Install Node.js >= 18 via nvm or package manager | -| `npx: command not found` | npm/npx not in PATH | Reinstall Node.js or add to PATH | -| Token test fails with 401 | Invalid or expired token | Regenerate token at yuque.com/settings/tokens | -| Token test fails with network error | Firewall or proxy issue | Check network connectivity to `www.yuque.com` | +| `node: command not found` | Node.js not installed | Install Node.js >= 20 via nvm (`nvm install 20`) | +| Token test returns 401 | Invalid or expired token | Regenerate at | +| MCP server fails to start | Token not reaching the process | Pass `--token=...` or set `YUQUE_PERSONAL_TOKEN` in the server env | +| Plugin not found in marketplace | Marketplace not registered | Re-run `claude plugin marketplace add yuque/yuque-ecosystem` | +| Skills not discovered | Wrong skills directory | Check your client's skills path (see its section above) | +| `ECONNREFUSED` / timeout | Network blocking yuque.com | `curl -I https://www.yuque.com` | diff --git a/README.en.md b/README.en.md index 8de4e80..b712536 100644 --- a/README.en.md +++ b/README.en.md @@ -2,101 +2,76 @@ # Yuque AI Ecosystem -> The unified home for everything in the Yuque AI ecosystem — website, plugins, skills, and shared resources. +> The official distribution repository for Yuque AI integrations — one set of skills, ready to use in any AI client, plus the website that presents them. [![Website](https://img.shields.io/badge/Website-yuque.github.io-blue)](https://yuque.github.io/yuque-ecosystem/) [![npm](https://img.shields.io/npm/v/yuque-mcp)](https://www.npmjs.com/package/yuque-mcp) 📖 **[Yuque + AI: From Documentation Tool to Your Second Brain](https://www.yuque.com/yuque/ai/yuque-ai-ecosystem-final)** — Explore the full vision of the Yuque AI Ecosystem -## Architecture +## Positioning -This is a **Stripe-style monorepo**: one core SDK ([yuque-mcp-server](https://github.com/yuque/yuque-mcp-server)) + one ecosystem repository (this repo) containing all client integrations. +**Skills are the asset, client integrations are distribution, the website is the storefront.** Capability and experience live in separate repositories: [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) defines what the AI *can do* (MCP tools); this repository defines how users *get it* (skill workflows, install docs, and the website). -| Repository | Purpose | Stripe Analogy | +| Layer | Content | Location | |---|---|---| -| [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) | Core MCP Server (npm package) | stripe-node (SDK) | -| **yuque-ecosystem** (this repo) | Website + All Client Plugins + Skills | stripe-examples + docs | +| Capability | MCP Server (npm: `yuque-mcp`) | [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) | +| Asset | Knowledge-management skills (single source, standard SKILL.md format) | [`skills/`](./skills/) | +| Distribution | Claude Code Marketplace packaging + all-client install guide | [`plugins/yuque-personal/`](./plugins/yuque-personal/) · [`AGENT-INSTALL.md`](./AGENT-INSTALL.md) | +| Storefront | Website (showcase + install guides) | [`website/`](./website/) | + +SKILL.md is a cross-client format — OpenCode, OpenClaw, and any other skills-capable client can copy [`skills/`](./skills/) into their own skills directory directly; no dedicated adapter layer needed. Claude Code is the one channel with formal packaging (one-command marketplace install with updates). ## Repository Structure ``` yuque-ecosystem/ -├── website/ # Official website (GitHub Pages) +├── skills/ # ★ The asset: 8 knowledge-management skills (single source) +├── AGENT-INSTALL.md # All-client install guide (directly executable by agents) ├── plugins/ -│ ├── yuque-personal/ # Claude Code plugin (personal edition) — canonical skills source -│ │ ├── .claude-plugin/ # plugin.json -│ │ ├── .mcp.json # MCP server config -│ │ └── skills/ # 8 skills (canonical — other clients are synced by script) -│ ├── claude-code/ # Claude Code install docs -│ ├── opencode/ # OpenCode integration (MCP config + skills copies) -│ └── openclaw/ # OpenClaw plugin (skills copies) +│ └── yuque-personal/ # Claude Code Marketplace packaging +│ ├── .claude-plugin/ # plugin.json +│ ├── .mcp.json # MCP server config +│ └── skills/ # synced copy (do not edit; CI checks drift) ├── shared/ -│ └── mcp-config/ # MCP config templates for various editors -├── scripts/ # sync-skills.mjs — sync canonical skills to client copies -├── .claude-plugin/ # Claude Code Marketplace entry -└── package.json # npm workspaces root +│ └── mcp-config/ # MCP config templates for Cursor / VS Code / Windsurf, etc. +├── scripts/ # sync-skills.mjs — skills/ → plugin copy +├── website/ # Official website (GitHub Pages) +└── .claude-plugin/ # Claude Code Marketplace entry ``` > **The team edition (yuque-group) is temporarily withdrawn**: its skills depend on group-statistics MCP tools (`yuque_group_*`) that are not yet available in `yuque-mcp`. It will return once the underlying tools ship. See git history for the previous code. ## Quick Start -### Claude Code +### Claude Code (recommended — the formally packaged channel) ```bash -# Option 1: Install via Marketplace (MCP tools + skills) claude plugin marketplace add yuque/yuque-ecosystem claude plugin install yuque-personal@yuque export YUQUE_TOKEN="your_token" # the plugin reads the token from this env var - -# Option 2: Add MCP Server directly (MCP tools only, no skills) -claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN ``` -### OpenCode - -Add to your `opencode.json`: +MCP tools only, no skills: -```jsonc -{ - "mcp": { - "yuque": { - "type": "local", - "command": ["npx", "-y", "yuque-mcp", "--token=YOUR_TOKEN"] - } - } -} +```bash +claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN ``` -See [`plugins/opencode/`](./plugins/opencode/) for skills installation and the full setup guide. - -### Other Editors +### Any other client (OpenCode / OpenClaw / Cursor / VS Code / Windsurf …) -See [`shared/mcp-config/`](./shared/mcp-config/) for configuration templates for Cursor, Windsurf, GitHub Copilot (VS Code), and more. +Two generic steps: ① configure `yuque-mcp` using a template from [`shared/mcp-config/`](./shared/mcp-config/); ② if the client supports skills, copy [`skills/`](./skills/) into its skills directory. -## Modules - -| Module | Description | Link | -|---|---|---| -| 🌐 Website | Official ecosystem website | [`website/`](./website/) | -| 🔌 Claude Code Plugin | Claude Code Marketplace plugin | [`plugins/claude-code/`](./plugins/claude-code/) | -| 🟢 OpenCode Plugin | OpenCode MCP + Skills integration | [`plugins/opencode/`](./plugins/opencode/) | -| 🤖 OpenClaw Plugin | OpenClaw Agent integration | [`plugins/openclaw/`](./plugins/openclaw/) | -| 📋 MCP Config | Editor configuration templates | [`shared/mcp-config/`](./shared/mcp-config/) | +Per-client commands live in [`AGENT-INSTALL.md`](./AGENT-INSTALL.md) — hand that file to your AI agent and it will install everything. ## Development ```bash # Website development -cd website -npm install -npm run dev - -# OpenClaw Plugin development -cd plugins/openclaw -npm install -npm run build +cd website && npm install && npm run dev + +# After editing skills, sync the plugin copy (CI checks drift) +npm run sync-skills ``` ## Links diff --git a/README.md b/README.md index f00c1d4..b7ada9e 100644 --- a/README.md +++ b/README.md @@ -2,101 +2,76 @@ # Yuque AI Ecosystem — 语雀 AI 生态 -> The unified home for everything in the Yuque AI ecosystem — website, plugins, skills, and shared resources. +> 语雀 AI 集成的官方分发仓库 — 一套 Skills，任意客户端开箱即用，外加承载它们的官网。 [![Website](https://img.shields.io/badge/Website-yuque.github.io-blue)](https://yuque.github.io/yuque-ecosystem/) [![npm](https://img.shields.io/npm/v/yuque-mcp)](https://www.npmjs.com/package/yuque-mcp) 📖 **[语雀 + AI：从文档工具到你的第二大脑](https://www.yuque.com/yuque/ai/yuque-ai-ecosystem-final)** — 了解语雀 AI 生态的完整愿景 -## Architecture +## 定位 -This is a **Stripe-style monorepo**: one core SDK ([yuque-mcp-server](https://github.com/yuque/yuque-mcp-server)) + one ecosystem repository (this repo) containing all client integrations. +**Skills 是资产，客户端接入是分发，官网是门面。** 能力与体验分属两个仓库：[yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) 定义 AI *能做什么*（MCP 工具），本仓库定义用户*怎么用上*（Skills 编排、安装文档与官网）。 -| Repository | Purpose | Stripe Analogy | +| 层 | 内容 | 位置 | |---|---|---| -| [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) | Core MCP Server (npm package) | stripe-node (SDK) | -| **yuque-ecosystem** (this repo) | Website + All Client Plugins + Skills | stripe-examples + docs | +| 能力层 | MCP Server（npm: `yuque-mcp`） | [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) | +| 资产层 | 知识管理 Skills（唯一源，标准 SKILL.md 格式） | [`skills/`](./skills/) | +| 分发层 | Claude Code Marketplace 打包 + 全客户端安装指南 | [`plugins/yuque-personal/`](./plugins/yuque-personal/) · [`AGENT-INSTALL.md`](./AGENT-INSTALL.md) | +| 门面层 | 官网（展示 + 安装引导） | [`website/`](./website/) | + +SKILL.md 是跨客户端的通用格式——OpenCode、OpenClaw 等客户端直接把 [`skills/`](./skills/) 拷进各自的 skills 目录即可，无需专门的适配层。Claude Code 是唯一保留正式打包的渠道（marketplace 一键安装 + 更新机制）。 ## Repository Structure ``` yuque-ecosystem/ -├── website/ # Official website (GitHub Pages) +├── skills/ # ★ 资产：8 个知识管理 Skills（唯一源） +├── AGENT-INSTALL.md # 全客户端安装指南（agent 可直接执行） ├── plugins/ -│ ├── yuque-personal/ # Claude Code 插件（个人版）— skills 唯一源 -│ │ ├── .claude-plugin/ # plugin.json -│ │ ├── .mcp.json # MCP server 配置 -│ │ └── skills/ # 8 个 Skills（canonical，其余客户端由脚本同步） -│ ├── claude-code/ # Claude Code 安装文档 -│ ├── opencode/ # OpenCode 接入（MCP 配置 + skills 副本） -│ └── openclaw/ # OpenClaw 插件（skills 副本） +│ └── yuque-personal/ # Claude Code Marketplace 打包 +│ ├── .claude-plugin/ # plugin.json +│ ├── .mcp.json # MCP server 配置 +│ └── skills/ # 同步副本（勿直接修改，CI 校验漂移） ├── shared/ -│ └── mcp-config/ # MCP config templates for various editors -├── scripts/ # sync-skills.mjs — 同步 canonical skills 到各客户端 -├── .claude-plugin/ # Claude Code Marketplace entry -└── package.json # npm workspaces root +│ └── mcp-config/ # Cursor / VS Code / Windsurf 等 MCP 配置模板 +├── scripts/ # sync-skills.mjs — skills/ → 插件目录 +├── website/ # 官网（GitHub Pages） +└── .claude-plugin/ # Claude Code Marketplace 入口 ``` > **团队版（yuque-group）已暂时下线**：其 skills 依赖的团队统计类 MCP 工具（`yuque_group_*`）尚未在 `yuque-mcp` 中提供，待底层工具就绪后再重新上架。历史代码见 git 记录。 ## Quick Start -### Claude Code +### Claude Code（推荐，正式打包渠道） ```bash -# Option 1: Install via Marketplace（MCP Tools + Skills） claude plugin marketplace add yuque/yuque-ecosystem claude plugin install yuque-personal@yuque export YUQUE_TOKEN="your_token" # 插件通过该环境变量读取 Token - -# Option 2: Add MCP Server directly（仅 MCP Tools，无 Skills） -claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN ``` -### OpenCode +仅要 MCP 工具、不要 Skills： -Add to your `opencode.json`: - -```jsonc -{ - "mcp": { - "yuque": { - "type": "local", - "command": ["npx", "-y", "yuque-mcp", "--token=YOUR_TOKEN"] - } - } -} +```bash +claude mcp add yuque-mcp -- npx -y yuque-mcp --token=YOUR_TOKEN ``` -See [`plugins/opencode/`](./plugins/opencode/) for skills installation and full setup guide. - -### Other Editors +### 其他客户端（OpenCode / OpenClaw / Cursor / VS Code / Windsurf …） -See [`shared/mcp-config/`](./shared/mcp-config/) for configuration templates for Cursor, Windsurf, GitHub Copilot (VS Code), and more. +两步通用：① 用 [`shared/mcp-config/`](./shared/mcp-config/) 的模板配好 `yuque-mcp`；② 客户端若支持 skills，把 [`skills/`](./skills/) 拷进它的 skills 目录。 -## Modules - -| Module | Description | Link | -|---|---|---| -| 🌐 Website | Official ecosystem website | [`website/`](./website/) | -| 🔌 Claude Code Plugin | Claude Code Marketplace plugin | [`plugins/claude-code/`](./plugins/claude-code/) | -| 🟢 OpenCode Plugin | OpenCode MCP + Skills integration | [`plugins/opencode/`](./plugins/opencode/) | -| 🤖 OpenClaw Plugin | OpenClaw Agent integration | [`plugins/openclaw/`](./plugins/openclaw/) | -| 📋 MCP Config | Editor configuration templates | [`shared/mcp-config/`](./shared/mcp-config/) | +各客户端的具体命令见 [`AGENT-INSTALL.md`](./AGENT-INSTALL.md) —— 把这个文件直接丢给你的 AI agent，它就会装。 ## Development ```bash -# Website development -cd website -npm install -npm run dev - -# OpenClaw Plugin development -cd plugins/openclaw -npm install -npm run build +# 官网开发 +cd website && npm install && npm run dev + +# 修改 skills 后同步插件副本（CI 会校验漂移） +npm run sync-skills ``` ## Links diff --git a/package-lock.json b/package-lock.json index 75f3a67..85177a4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6,8 +6,7 @@ "": { "name": "yuque-ecosystem", "workspaces": [ - "website", - "plugins/openclaw" + "website" ], "devDependencies": { "conventional-changelog-cli": "^5.0.0" @@ -1856,10 +1855,6 @@ "resolved": "website", "link": true }, - "node_modules/@yuque/openclaw-plugin": { - "resolved": "plugins/openclaw", - "link": true - }, "node_modules/acorn": { "version": "8.16.0", "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz", @@ -3978,6 +3973,7 @@ "plugins/openclaw": { "name": "@yuque/openclaw-plugin", "version": "1.0.0", + "extraneous": true, "license": "MIT", "devDependencies": { "typescript": "^5.9.3" diff --git a/package.json b/package.json index 945d8c4..467e288 100644 --- a/package.json +++ b/package.json @@ -2,8 +2,7 @@ "name": "yuque-ecosystem", "private": true, "workspaces": [ - "website", - "plugins/openclaw" + "website" ], "scripts": { "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s", diff --git a/plugins/claude-code/AGENT-INSTALL.md b/plugins/claude-code/AGENT-INSTALL.md deleted file mode 100644 index a359f23..0000000 --- a/plugins/claude-code/AGENT-INSTALL.md +++ /dev/null @@ -1,153 +0,0 @@ -# Claude Code — Yuque Plugin Installation (Agent Guide) - -> For AI agents to auto-install. Human-readable but optimized for machine execution. - ---- - -## Prerequisites Check - -Run these commands to verify your environment: - -```bash -# Check Claude Code CLI is available -claude --version -# ✅ Expected: version string -# ❌ If "command not found": install via `npm i -g @anthropic-ai/claude-code` - -# Check Node.js version (>= 20 required; 18 is EOL) -node --version -# ✅ Expected: v20.x.x or higher -# ❌ If below 20: upgrade via nvm (`nvm install 20 && nvm use 20`) - -# Check npx is available -npx --version -# ✅ Expected: version string -# ❌ If missing: comes with npm, reinstall Node.js -``` - ---- - -## Installation Method 1: Marketplace Plugin (Recommended) - -Installs the `yuque-personal` plugin: MCP server + 8 skills. - -### Step 1: Add the Marketplace - -```bash -claude plugin marketplace add yuque/yuque-ecosystem -``` - -> **Important:** This only registers the marketplace. It does NOT install any plugin yet. - -### Step 2: Install the Plugin - -```bash -claude plugin install yuque-personal@yuque -``` - -### Step 3: Configure Token - -The plugin's MCP server reads your token from the `YUQUE_TOKEN` environment variable: - -```bash -export YUQUE_TOKEN="your_token_here" -``` - -Add it to your shell profile (`~/.zshrc` or `~/.bashrc`) for persistence. Get a token at . - -### Step 4: Verify Installation - -```bash -claude plugin list | grep yuque-personal -# ✅ Expected: "yuque-personal" appears in the list -# ❌ If not listed: re-run Step 2 and check its error output -``` - ---- - -## Installation Method 2: MCP Server Only - -Use this if you only need the MCP tools without skills, or if the marketplace is unavailable. - -### Install - -```bash -claude mcp add yuque-mcp -- npx -y yuque-mcp --token=$YUQUE_TOKEN -``` - -> **Important:** Make sure `$YUQUE_TOKEN` is set before running this command — the token value is captured at add time. - -### Verify MCP Connection - -```bash -claude mcp list | grep -i yuque -# ✅ Expected: "yuque-mcp" appears with a connected/configured status -# ❌ If not listed: check token and retry -``` - ---- - -## Post-Installation Verification - -### Verify the token itself (independent of Claude Code) - -```bash -curl -s -H "X-Auth-Token: $YUQUE_TOKEN" https://www.yuque.com/api/v2/user -# ✅ Expected: JSON with your Yuque user profile -# ❌ 401 response: token invalid or expired — regenerate it -``` - -### Functional test inside a Claude Code session - -``` -> Use the yuque_get_user tool to get my user info -``` - -Expected: Returns your Yuque user profile (username, avatar, etc.) - ---- - -## Available After Installation - -### MCP Tools (from `yuque-mcp`) - -| Category | Tools | -|----------|-------| -| User | `yuque_get_user` | -| Search | `yuque_search` | -| Books (知识库) | `yuque_list_books`, `yuque_get_book`, `yuque_create_book`, `yuque_update_book` | -| Docs | `yuque_list_docs`, `yuque_get_doc`, `yuque_create_doc`, `yuque_update_doc` | -| TOC | `yuque_get_toc`, `yuque_update_toc` | -| Notes (小记) | `yuque_list_notes`, `yuque_get_note`, `yuque_create_note`, `yuque_update_note` | -| Boards (画板) | `yuque_get_resource`, `yuque_create_resource`, `yuque_update_resource` | - -### Skills (Marketplace install only) - -**yuque-personal (8):** smart-search, smart-summary, daily-capture, reading-digest, note-refine, knowledge-connect, style-extract, stale-detector - ---- - -## Troubleshooting - -| Error | Cause | Fix | -|-------|-------|-----| -| `command not found: claude` | Claude Code CLI not installed | `npm i -g @anthropic-ai/claude-code` | -| MCP server fails to start | Token missing or invalid | Set `YUQUE_TOKEN` and regenerate at | -| `npx: command not found` | Node.js/npm not installed | Install Node.js >= 20 | -| Plugin not found in marketplace | Marketplace not added, or network issue | Re-run `claude plugin marketplace add yuque/yuque-ecosystem`; fallback to Method 2 | -| `ECONNREFUSED` or timeout | Network/firewall blocking `yuque.com` | Check connectivity: `curl -I https://www.yuque.com` | - ---- - -## Uninstall - -```bash -# Remove the plugin -claude plugin uninstall yuque-personal - -# Remove the marketplace -claude plugin marketplace remove yuque - -# Or remove the standalone MCP server (Method 2) -claude mcp remove yuque-mcp -``` diff --git a/plugins/claude-code/README.en.md b/plugins/claude-code/README.en.md deleted file mode 100644 index c5b97e6..0000000 --- a/plugins/claude-code/README.en.md +++ /dev/null @@ -1,43 +0,0 @@ -[中文](./README.md) | [English](./README.en.md) | [🤖 Agent Install](./AGENT-INSTALL.md) - -# Yuque Plugin for Claude Code - -> Yuque AI Ecosystem — MCP Tools and Skills for Claude Code - -## Plugins - -### yuque-personal - -AI-powered personal knowledge base integration — MCP Tools + 8 Skills. - -📂 [`../yuque-personal/`](../yuque-personal/) - -> **The team edition (yuque-group) is temporarily withdrawn**: its skills depend on group-statistics MCP tools that are not yet available in `yuque-mcp`. It will return once the underlying tools ship. - -## Installation - -```bash -# 1. Add the marketplace -claude plugin marketplace add yuque/yuque-ecosystem - -# 2. Install the plugin (marketplace add only registers the marketplace — the install step is required) -claude plugin install yuque-personal@yuque - -# 3. Set your token (the plugin reads it from the YUQUE_TOKEN env var) -export YUQUE_TOKEN="your_token_here" -``` - -Verify: - -```bash -claude plugin list | grep yuque-personal -``` - -## Links - -- [Yuque AI Ecosystem Website](https://yuque.github.io/yuque-ecosystem/) -- [yuque-mcp-server (npm)](https://www.npmjs.com/package/yuque-mcp) - -## License - -MIT © yuque diff --git a/plugins/claude-code/README.md b/plugins/claude-code/README.md deleted file mode 100644 index 0897e97..0000000 --- a/plugins/claude-code/README.md +++ /dev/null @@ -1,43 +0,0 @@ -[中文](./README.md) | [English](./README.en.md) | [🤖 Agent Install](./AGENT-INSTALL.md) - -# Yuque Plugin for Claude Code - -> 语雀 AI 生态 — MCP Tools and Skills for Claude Code - -## 插件 - -### yuque-personal（个人版） - -个人知识库 AI 集成 — MCP Tools + 8 Skills。 - -📂 [`../yuque-personal/`](../yuque-personal/) - -> **团队版（yuque-group）已暂时下线**：其依赖的团队统计类 MCP 工具尚未在 `yuque-mcp` 中提供，待底层工具就绪后再重新上架。 - -## 安装 - -```bash -# 1. 添加 marketplace -claude plugin marketplace add yuque/yuque-ecosystem - -# 2. 安装插件（marketplace add 只是注册市场，必须再执行 install） -claude plugin install yuque-personal@yuque - -# 3. 设置 Token（插件通过 YUQUE_TOKEN 环境变量读取） -export YUQUE_TOKEN="your_token_here" -``` - -验证： - -```bash -claude plugin list | grep yuque-personal -``` - -## 相关链接 - -- [Yuque AI Ecosystem Website](https://yuque.github.io/yuque-ecosystem/) -- [yuque-mcp-server (npm)](https://www.npmjs.com/package/yuque-mcp) - -## License - -MIT © yuque diff --git a/plugins/openclaw/README.en.md b/plugins/openclaw/README.en.md deleted file mode 100644 index 34f10e4..0000000 --- a/plugins/openclaw/README.en.md +++ /dev/null @@ -1,87 +0,0 @@ -[中文](./README.md) | [English](./README.en.md) - -# Yuque OpenClaw Plugin - -> Yuque Knowledge Management — Agent Skills for OpenClaw - -## Overview - -Integrates Yuque knowledge management into the OpenClaw Agent ecosystem with 8 ready-to-use personal knowledge management Skills. - -## Prerequisites - -- [OpenClaw](https://openclaw.ai) installed and running -- Yuque account with a [personal Token](https://www.yuque.com/settings/tokens) -- [yuque-mcp](https://www.npmjs.com/package/yuque-mcp) configured as MCP Server - -## Installation - -The plugin is not yet published to npm — install it from a local checkout: - -```bash -git clone https://github.com/yuque/yuque-ecosystem.git -openclaw plugins install ./yuque-ecosystem/plugins/openclaw -``` - -> For development, use `openclaw plugins install --link ./yuque-ecosystem/plugins/openclaw` to keep the install pointing at your checkout. - -## Skills - -| Skill | Description | -|-------|-------------| -| **smart-search** | Search personal knowledge bases with natural language, get summarized answers with source links | -| **smart-summary** | Generate summaries of any document or knowledge base at different granularity levels | -| **reading-digest** | Extract core insights, golden quotes, and action items into structured reading notes | -| **daily-capture** | Collect fleeting ideas throughout the day, organize into structured thematic notes | -| **note-refine** | Polish rough notes into high-quality documents with better structure and formatting | -| **knowledge-connect** | Discover hidden connections between documents, suggest cross-reference links | -| **style-extract** | Analyze writing style from documents, generate a reusable style profile | -| **stale-detector** | Scan knowledge bases for stale documents, generate maintenance reports | - -## MCP Server Configuration - -Add yuque-mcp to your OpenClaw `mcpServers` configuration: - -```json -{ - "mcpServers": { - "yuque-mcp": { - "command": "npx", - "args": ["-y", "yuque-mcp"], - "env": { - "YUQUE_PERSONAL_TOKEN": "your-yuque-token" - } - } - } -} -``` - -> Token is passed via MCP Server environment variables (`yuque-mcp` reads `YUQUE_PERSONAL_TOKEN`, or accepts `--token=...` as an argument). The plugin itself does not require token configuration. - -## Directory Structure - -``` -plugins/openclaw/ -├── openclaw.plugin.json # Plugin manifest -├── index.ts # Plugin entry point (loaded by jiti at runtime) -├── skills/ # 8 Agent Skills -│ ├── smart-search/ -│ ├── smart-summary/ -│ ├── reading-digest/ -│ ├── daily-capture/ -│ ├── note-refine/ -│ ├── knowledge-connect/ -│ ├── style-extract/ -│ └── stale-detector/ -├── package.json -└── README.md -``` - -## Links - -- [Yuque AI Ecosystem Website](https://yuque.github.io/yuque-ecosystem/) -- [yuque-mcp-server (npm)](https://www.npmjs.com/package/yuque-mcp) - -## License - -MIT © yuque diff --git a/plugins/openclaw/README.md b/plugins/openclaw/README.md deleted file mode 100644 index b79fc7d..0000000 --- a/plugins/openclaw/README.md +++ /dev/null @@ -1,87 +0,0 @@ -[中文](./README.md) | [English](./README.en.md) - -# 语雀 OpenClaw Plugin - -> 语雀知识管理 — Agent Skills for OpenClaw - -## 概述 - -将语雀知识管理能力集成到 OpenClaw Agent 生态，提供 8 个开箱即用的个人知识管理 Skills。 - -## 前置条件 - -- [OpenClaw](https://openclaw.ai) 已安装并运行 -- 语雀账号及 [个人 Token](https://www.yuque.com/settings/tokens) -- [yuque-mcp](https://www.npmjs.com/package/yuque-mcp) 已配置为 MCP Server - -## 安装 - -插件尚未发布到 npm，请从本地仓库安装： - -```bash -git clone https://github.com/yuque/yuque-ecosystem.git -openclaw plugins install ./yuque-ecosystem/plugins/openclaw -``` - -> 开发调试可用 `openclaw plugins install --link ./yuque-ecosystem/plugins/openclaw`，保持安装指向本地目录。 - -## Skills - -| Skill | 说明 | -|-------|------| -| **smart-search** | 自然语言搜索个人知识库，返回摘要答案和来源链接 | -| **smart-summary** | 对任意文档或知识库生成不同粒度的摘要 | -| **reading-digest** | 从文章中提取核心观点、金句和行动项，生成结构化阅读笔记 | -| **daily-capture** | 收集碎片想法，定期整理为结构化主题笔记 | -| **note-refine** | 将粗糙笔记打磨为高质量文档 | -| **knowledge-connect** | 发现文档间的隐藏关联，建议交叉引用链接 | -| **style-extract** | 分析写作风格，生成风格画像 | -| **stale-detector** | 扫描知识库中过时文档，生成维护报告 | - -## MCP Server 配置 - -在 OpenClaw 的 `mcpServers` 配置中添加 yuque-mcp： - -```json -{ - "mcpServers": { - "yuque-mcp": { - "command": "npx", - "args": ["-y", "yuque-mcp"], - "env": { - "YUQUE_PERSONAL_TOKEN": "your-yuque-token" - } - } - } -} -``` - -> Token 通过 MCP Server 的环境变量传入（`yuque-mcp` 读取的是 `YUQUE_PERSONAL_TOKEN`，也可用 `--token=...` 参数），插件本身不需要配置 Token。 - -## 目录结构 - -``` -plugins/openclaw/ -├── openclaw.plugin.json # 插件清单 -├── index.ts # 插件入口（jiti 运行时加载） -├── skills/ # 8 个 Agent Skills -│ ├── smart-search/ -│ ├── smart-summary/ -│ ├── reading-digest/ -│ ├── daily-capture/ -│ ├── note-refine/ -│ ├── knowledge-connect/ -│ ├── style-extract/ -│ └── stale-detector/ -├── package.json -└── README.md -``` - -## 相关链接 - -- [语雀 AI 生态官网](https://yuque.github.io/yuque-ecosystem/) -- [yuque-mcp-server (npm)](https://www.npmjs.com/package/yuque-mcp) - -## License - -MIT © yuque diff --git a/plugins/openclaw/index.ts b/plugins/openclaw/index.ts deleted file mode 100644 index b85e491..0000000 --- a/plugins/openclaw/index.ts +++ /dev/null @@ -1,25 +0,0 @@ -import type { OpenClawPluginApi } from "openclaw/plugin-sdk"; -import { emptyPluginConfigSchema } from "openclaw/plugin-sdk"; - -const plugin = { - id: "yuque", - name: "语雀 AI 生态", - description: "语雀知识管理 — Agent Skills for OpenClaw", - configSchema: emptyPluginConfigSchema(), - register(api: OpenClawPluginApi) { - api.registerCli(({ program }) => { - program - .command("yuque") - .description("Yuque knowledge management") - .command("status") - .description("Check yuque plugin status") - .action(async () => { - console.log("🟢 Yuque OpenClaw Plugin"); - console.log(" Skills: see plugins/openclaw/skills/"); - console.log(" MCP Server: yuque-mcp (configure via mcpServers)"); - }); - }, { commands: ["yuque"] }); - }, -}; - -export default plugin; diff --git a/plugins/openclaw/openclaw.plugin.json b/plugins/openclaw/openclaw.plugin.json deleted file mode 100644 index fd89e99..0000000 --- a/plugins/openclaw/openclaw.plugin.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "id": "yuque", - "name": "语雀 AI 生态", - "version": "1.0.0", - "description": "语雀知识管理 — Agent Skills for OpenClaw", - "skills": ["skills"], - "configSchema": { - "type": "object", - "additionalProperties": false, - "properties": {} - } -} diff --git a/plugins/openclaw/package.json b/plugins/openclaw/package.json deleted file mode 100644 index e9b9677..0000000 --- a/plugins/openclaw/package.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "name": "@yuque/openclaw-plugin", - "version": "1.0.0", - "description": "Yuque AI Ecosystem — OpenClaw Plugin", - "type": "module", - "main": "index.ts", - "scripts": { - "build": "tsc --noEmit" - }, - "keywords": [ - "yuque", - "openclaw", - "plugin", - "mcp", - "ai", - "knowledge-management" - ], - "author": "yuque", - "license": "MIT", - "openclaw": { - "extensions": [ - "./index.ts" - ] - }, - "devDependencies": { - "typescript": "^5.9.3" - } -} diff --git a/plugins/openclaw/skills/knowledge-connect/SKILL.md b/plugins/openclaw/skills/knowledge-connect/SKILL.md deleted file mode 100644 index 33f17e5..0000000 --- a/plugins/openclaw/skills/knowledge-connect/SKILL.md +++ /dev/null @@ -1,198 +0,0 @@ ---- -name: knowledge-connect -description: Analyze documents in your Yuque knowledge base, discover hidden connections between them (similar topics, complementary content), and suggest cross-reference links to build a knowledge network. For personal/individual use. -license: Apache-2.0 -compatibility: Requires yuque-mcp server connected to a Yuque account with personal Token -metadata: - author: chen201724 - version: "1.0" ---- - -# Knowledge Connect — Discover Links Between Your Notes - -Analyze documents in your Yuque knowledge base, find hidden connections between them — similar topics, complementary content, shared concepts — and suggest cross-reference links to help you build a connected knowledge network. - -## When to Use - -- User wants to find connections between their notes -- User says "帮我找找文档之间的关联", "哪些笔记是相关的", "connect my notes" -- User just finished writing a document and wants to link it to related ones -- User says "这篇文档和哪些笔记有关", "find related documents" -- User wants to build a knowledge graph from their existing notes - -## Required MCP Tools - -All tools are from the `yuque-mcp` server: - -- `yuque_list_books` — List user's knowledge bases -- `yuque_list_docs` — List all documents in a knowledge base -- `yuque_get_doc` — Read document content for analysis -- `yuque_search` — Search for potentially related documents -- `yuque_update_doc` — Add cross-reference links to documents - -## Workflow - -### Step 1: Determine the Scope - -Ask the user what to analyze: - -**Case A — Single document:** -User provides a specific document link. Find connections for this one document. - -**Case B — Entire knowledge base:** -User specifies a knowledge base. Analyze all documents within it. - -**Case C — Across knowledge bases:** -User wants cross-repo connections. Analyze documents across multiple repos. - -For Case B/C, first list available repos: - -``` -Tool: yuque_list_books -``` - -Then list documents in the target repo(s): - -``` -Tool: yuque_list_docs -Parameters: - repo_id: "" -``` - -### Step 2: Analyze Documents - -For each document in scope, fetch its content: - -``` -Tool: yuque_get_doc -Parameters: - repo_id: "" - doc_id: "" -``` - -Extract the following from each document: - -| Element | Description | -|---------|-------------| -| **Topics** | Main subjects the document covers | -| **Key Concepts** | Important terms, frameworks, or ideas | -| **Questions** | Questions raised but not fully answered | -| **References** | External sources or concepts mentioned | -| **Domain** | The knowledge area (tech, management, personal, etc.) | - -### Step 3: Discover Connections - -Compare documents pairwise and identify these types of connections: - -| Connection Type | Description | Example | -|----------------|-------------|---------| -| 🔄 **Same Topic** | Documents covering the same subject from different angles | Two articles about "distributed systems" | -| 🧩 **Complementary** | One document answers questions raised in another | A "why microservices" doc + a "microservices pitfalls" doc | -| 📚 **Sequential** | Documents that form a natural reading sequence | "Intro to X" → "Advanced X" → "X in Practice" | -| 🌱 **Evolution** | Earlier and later thinking on the same topic | A draft idea → a refined version months later | -| 🔗 **Shared Concept** | Documents that reference the same key concept | Multiple docs mentioning "second brain" methodology | - -For single-document analysis, also search for related documents: - -``` -Tool: yuque_search -Parameters: - query: "[key topics from the document]" - type: "doc" -``` - -### Step 4: Present Connection Map - -Present the discovered connections to the user: - -```markdown -## 🕸️ 知识关联分析 - -分析范围：[知识库名称] — [N] 篇文档 -发现 [X] 组关联 - -### 关联 1：[主题/概念名称] - -| 文档 | 关联类型 | 关联强度 | -|------|----------|----------| -| [文档 A 标题](链接) | 🔄 同主题 | ⭐⭐⭐ | -| [文档 B 标题](链接) | 🧩 互补 | ⭐⭐⭐ | -| [文档 C 标题](链接) | 🔗 共享概念 | ⭐⭐ | - -**关联说明**：[为什么这些文档相关，它们之间的具体联系是什么] - -**建议**：[具体的交叉引用建议，如 "在文档 A 的第二节末尾添加指向文档 B 的链接"] - -### 关联 2：[主题/概念名称] - -... - -### 🏝️ 孤岛文档 - -以下文档暂未发现明显关联： -- [文档标题](链接) — 可能需要补充更多内容后再分析 - -### 💡 建议 - -1. [建议 1：如 "建议创建一篇索引文档，串联关于 X 主题的 5 篇笔记"] -2. [建议 2：如 "文档 A 和文档 B 观点互补，可以合并成一篇完整的指南"] -``` - -### Step 5: Add Cross-References (Optional) - -Ask the user: "要自动在相关文档中添加交叉引用链接吗？" - -If confirmed, for each document that needs cross-references: - -``` -Tool: yuque_get_doc -Parameters: - repo_id: "" - doc_id: "" -``` - -Append a "Related Notes" section at the end: - -```markdown - ---- - -## 📎 相关笔记 - -- 🔄 [相关文档标题](链接) — [一句话说明关联] -- 🧩 [相关文档标题](链接) — [一句话说明关联] - -*由 AI 分析生成的关联推荐 — YYYY-MM-DD* -``` - -``` -Tool: yuque_update_doc -Parameters: - repo_id: "" - doc_id: "" - body: "" -``` - -Confirm: "已为 [N] 篇文档添加了交叉引用链接 ✅" - -## Guidelines - -- Always answer in the same language the user used (Chinese or English) -- Connection strength should be based on actual content overlap, not just title similarity -- Be specific about why documents are connected — vague "they're related" is not helpful -- Don't force connections — if two documents aren't meaningfully related, don't link them -- For large knowledge bases (> 50 docs), suggest analyzing in batches by topic area -- The "孤岛文档" section is valuable — it helps users identify notes that need more context -- When adding cross-references, never modify the original content — only append at the end -- Suggest creating index/hub documents for topics with 3+ related notes - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Document not found (404) | Skip the document and note it in the report | -| Permission denied (403) | Tell user they may lack permission to access this document | -| Knowledge base is empty | Inform user: "该知识库还没有文档，先写几篇笔记再来分析关联吧" | -| Knowledge base has < 3 documents | Inform user: "文档数量较少，建议积累更多笔记后再做关联分析，效果会更好" | -| `yuque_update_doc` fails | Present the suggested cross-references in chat for manual adding | -| Too many documents to analyze at once | Suggest narrowing scope: "知识库文档较多，建议先选一个主题方向分析" | diff --git a/plugins/openclaw/skills/note-refine/SKILL.md b/plugins/openclaw/skills/note-refine/SKILL.md deleted file mode 100644 index 5c85013..0000000 --- a/plugins/openclaw/skills/note-refine/SKILL.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -name: note-refine -description: Polish rough notes into high-quality documents — add structure, improve expression, and enhance formatting while preserving the original meaning. For personal/individual use. -license: Apache-2.0 -compatibility: Requires yuque-mcp server connected to a Yuque account with personal Token -metadata: - author: chen201724 - version: "1.0" ---- - -# Note Refine — Polish Rough Notes into Quality Documents - -Transform rough, unstructured notes into well-organized, readable documents. Adds proper headings, table of contents, improves expression, and enhances formatting — all while preserving the original meaning. - -## When to Use - -- User has a rough draft or messy notes they want to clean up -- User says "帮我整理一下这篇笔记", "polish my notes", "把这个文档排版优化一下" -- User wants to improve readability of an existing Yuque document -- User has bullet points or fragments they want turned into a proper document - -## Required MCP Tools - -All tools are from the `yuque-mcp` server: - -- `yuque_get_doc` — Read the original document content -- `yuque_update_doc` — Update the document with refined content - -## Workflow - -### Step 1: Get the Source Notes - -**Case A — Yuque document link:** -Extract `repo_id` and `doc_id` from the URL and fetch the content: - -``` -Tool: yuque_get_doc -Parameters: - repo_id: "" - doc_id: "" -``` - -**Case B — User pastes text directly:** -Use the provided text as the source content. No tool call needed. - -If the document is not found (404) or permission denied (403), inform the user and stop. - -### Step 2: Analyze the Current State - -Before refining, assess the notes on these dimensions: - -| Dimension | What to Check | -|-----------|---------------| -| **Structure** | Are there headings? Is there a logical flow? | -| **Completeness** | Are sentences complete? Are there dangling thoughts? | -| **Formatting** | Consistent use of lists, code blocks, emphasis? | -| **Readability** | Paragraph length, sentence clarity, jargon usage? | -| **Organization** | Is related content grouped together? | - -Mentally categorize the refinement level needed: - -- **Light polish** — Good structure, just needs formatting and minor wording fixes -- **Medium refine** — Has content but needs reorganization and better headings -- **Heavy restructure** — Fragments and bullet points that need to become a proper document - -### Step 3: Refine the Content - -Apply the following improvements while strictly preserving the original meaning: - -**Structure improvements:** -- Add a clear title if missing -- Add hierarchical headings (H2, H3) to break content into logical sections -- Reorder content so related ideas are grouped together -- Add a brief introduction paragraph if the document jumps straight into details - -**Expression improvements:** -- Complete sentence fragments into full sentences -- Fix grammatical errors and typos -- Replace vague language with precise terms -- Smooth transitions between sections -- Keep the author's voice and tone — don't make casual notes sound like academic papers - -**Formatting improvements:** -- Use bullet lists for parallel items -- Use numbered lists for sequential steps -- Use code blocks for code, commands, or technical content -- Use tables for structured comparisons -- Use bold for key terms on first mention -- Use blockquotes for important callouts -- Ensure consistent formatting throughout - -**What NOT to change:** -- Do not add new information or opinions not present in the original -- Do not remove content the author wrote (unless it's clearly a duplicate) -- Do not change technical terms or proper nouns -- Do not alter the author's conclusions or viewpoints -- Do not over-formalize casual notes if the user didn't ask for it - -### Step 4: Present the Refined Version - -Show the user a comparison summary and the refined document: - -```markdown -## ✨ 笔记优化完成 - -### 优化概览 - -| 项目 | 优化前 | 优化后 | -|------|--------|--------| -| 结构 | [e.g., 无标题，纯文本] | [e.g., 3 个章节，层级清晰] | -| 段落数 | X | Y | -| 字数 | ~X 字 | ~Y 字 | - -### 主要改动 - -1. [改动 1：e.g., 添加了三级标题结构] -2. [改动 2：e.g., 将零散要点整合为完整段落] -3. [改动 3：e.g., 统一了列表格式] - ---- - -[完整的优化后文档内容] -``` - -### Step 5: Save Changes (Optional) - -Ask the user: "要把优化后的内容更新到原文档吗？" - -**If the user confirms and the source was a Yuque document:** - -``` -Tool: yuque_update_doc -Parameters: - repo_id: "" - doc_id: "" - body: "" -``` - -After saving, confirm: "文档已更新：[文档链接]" - -**If the user wants to keep the original and save as a new version:** -Inform the user: "语雀会自动保留历史版本，更新后你仍然可以在版本历史中查看原始内容。" - -**If the source was pasted text:** -Just present the refined version in chat. If the user wants to save it, ask which knowledge base and use `yuque_create_doc`. - -## Guidelines - -- Always answer in the same language as the original notes (Chinese or English) -- The golden rule: **preserve meaning, improve form** -- Show the user what you changed and why — transparency builds trust -- For light polish, don't over-engineer — sometimes notes just need minor fixes -- For heavy restructure, confirm the proposed structure with the user before saving -- If the notes contain TODO items or unfinished thoughts, preserve them as-is (mark with `` if needed) -- Respect the author's writing style — don't turn informal notes into formal reports unless asked - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Document not found (404) | Inform user the document may have been deleted or the link is incorrect | -| Permission denied (403) | Tell user they may lack permission to access or edit this document | -| Document content is empty | Inform user: "该文档内容为空，没有可优化的内容" | -| `yuque_update_doc` fails | Present the refined content in chat and suggest the user copy-paste it manually | -| Content is already well-structured | Tell the user: "这篇文档结构已经很清晰了，只做了少量微调" — don't force unnecessary changes | -| Content is too short (< 50 chars) | Inform user the content is too brief to meaningfully refine, ask if they want to expand it instead | diff --git a/plugins/openclaw/skills/smart-search/SKILL.md b/plugins/openclaw/skills/smart-search/SKILL.md deleted file mode 100644 index 07c56a6..0000000 --- a/plugins/openclaw/skills/smart-search/SKILL.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -name: smart-search -description: Search your personal Yuque knowledge bases with natural language queries and provide summarized answers with key points and source links. For personal/individual use — searches across your own documents. -license: Apache-2.0 -compatibility: Requires yuque-mcp server connected to a Yuque account with personal Token -metadata: - author: chen201724 - version: "2.0" ---- - -# Smart Search — Yuque Personal Knowledge Base Search & Q&A - -Search across your personal Yuque knowledge bases using natural language, read relevant documents, and synthesize a clear answer with references. - -## When to Use - -- User asks a question that might be answered by their personal Yuque docs -- User wants to find specific information in their own knowledge base -- User says "搜一下我的文档", "search my Yuque", "我的知识库里有没有..." - -## Required MCP Tools - -All tools are from the `yuque-mcp` server: - -- `yuque_search` — Search documents by keyword -- `yuque_get_doc` — Read full document content by slug/id - -## Workflow - -### Step 1: Extract Search Keywords - -From the user's natural language query, extract 1-3 concise Chinese keywords. Yuque search works best with short, specific terms. - -Examples: -- "我的部署流程文档在哪？" → keywords: `部署流程` -- "How do I handle error logging?" → keywords: `错误日志` or `日志处理` -- "我之前写的技术评审笔记" → keywords: `技术评审` - -### Step 2: Search Documents - -Call `yuque_search` with the extracted keywords: - -``` -Tool: yuque_search -Parameters: - query: "" - type: "doc" -``` - -If the search returns no results: -1. Try alternative keywords (synonyms, broader terms) -2. Try splitting compound terms (e.g., "部署流程" → "部署" or "流程") -3. If still no results, tell the user honestly: "在你的语雀知识库中未找到相关文档，建议尝试其他关键词或确认文档是否存在。" - -### Step 3: Filter and Rank Results - -From the search results, select the top 3-5 most relevant documents based on: -- Title relevance to the query -- Document update time (prefer recent) -- Repository context (focus on user's personal repos) - -### Step 4: Read Document Content - -For each selected document, fetch the full content: - -``` -Tool: yuque_get_doc -Parameters: - repo_id: "" # e.g., "username/my-notes" (from search result's book.namespace) - doc_id: "" # e.g., "api" (from search result's target.slug) -``` - -Note: The search result contains nested data. Extract these key fields: -- `target.slug` → use as `doc_id` -- `target.book.namespace` → use as `repo_id` -- `target.title` → document title -- `target.updated_at` → last update time - -Read up to 3 documents. If the first document fully answers the question, you may skip the rest. - -### Step 5: Synthesize and Respond - -Compose the answer in the following format: - -```markdown -## 回答 - -[直接回答用户的问题，2-4 句话，简洁明了] - -## 关键要点 - -- **要点 1**：[从文档中提取的关键信息] -- **要点 2**：[从文档中提取的关键信息] -- **要点 3**：[从文档中提取的关键信息] - -## 参考文档 - -1. [文档标题](文档链接) — 来自「知识库名称」，更新于 YYYY-MM-DD -2. [文档标题](文档链接) — 来自「知识库名称」，更新于 YYYY-MM-DD -``` - -## Guidelines - -- Always answer in the same language the user used (Chinese or English) -- Quote specific content from documents when relevant — use `>` blockquotes -- If documents contain conflicting information, note the discrepancy and mention which doc is more recent -- If the answer is only partially found, say what you found and what's missing -- Never fabricate information not present in the documents -- Include document links so the user can read the full source -- This skill searches the knowledge bases accessible to the configured Yuque token - -## Error Handling - -| Situation | Action | -|-----------|--------| -| `yuque_search` returns empty | Try alternative keywords, then inform user | -| `yuque_get_doc` fails (404) | Skip this doc, note it may have been deleted | -| `yuque_get_doc` fails (403) | Tell user they may lack permission to access this doc | -| API timeout | Retry once, then inform user of connectivity issue | -| Too many results | Focus on top 3 by relevance, mention there are more results available | diff --git a/plugins/openclaw/skills/smart-summary/SKILL.md b/plugins/openclaw/skills/smart-summary/SKILL.md deleted file mode 100644 index 20f19f7..0000000 --- a/plugins/openclaw/skills/smart-summary/SKILL.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -name: smart-summary -description: Generate summaries of any Yuque document or knowledge base at different granularity levels — one-liner, key points, or detailed summary. For personal/individual use. -license: Apache-2.0 -compatibility: Requires yuque-mcp server connected to a Yuque account with personal Token -metadata: - author: chen201724 - version: "1.0" ---- - -# Smart Summary — Yuque Document & Knowledge Base Summarization - -Generate summaries at different granularity levels for any Yuque document or entire knowledge base. Supports one-liner, key points extraction, and detailed summary modes. - -## When to Use - -- User wants a quick summary of a Yuque document or knowledge base -- User says "帮我总结一下这篇文档", "summarize this doc", "这个知识库讲了什么" -- User shares a Yuque document link and asks for a summary -- User wants to quickly understand the content of a repo without reading everything - -## Required MCP Tools - -All tools are from the `yuque-mcp` server: - -- `yuque_get_doc` — Read full document content by slug/id -- `yuque_get_book` — Get knowledge base metadata -- `yuque_list_docs` — List all documents in a knowledge base -- `yuque_get_toc` — Get the table of contents of a knowledge base - -## Workflow - -### Step 1: Identify the Target - -Determine what the user wants summarized: - -**Case A — Single Document:** -The user provides a document link or specifies a document by name. Extract `repo_id` (namespace) and `doc_id` (slug) from the link. - -Yuque doc URL pattern: `https://www.yuque.com/{namespace}/{slug}` - -**Case B — Entire Knowledge Base:** -The user provides a knowledge base link or name. Extract `repo_id` (namespace). - -Yuque repo URL pattern: `https://www.yuque.com/{namespace}` - -If the user's input is ambiguous, ask: "你想总结单篇文档还是整个知识库？" - -### Step 2: Determine Summary Granularity - -Check if the user specified a granularity level. If not, default to **key points**. - -| Level | Trigger Phrases | Output | -|-------|----------------|--------| -| **one-liner** (一句话摘要) | "一句话总结", "简单说说", "TL;DR" | 1 sentence, ≤50 words | -| **key-points** (要点提取) | "要点", "关键点", "summarize" (default) | 5-10 bullet points | -| **detailed** (详细摘要) | "详细总结", "完整摘要", "deep summary" | Structured multi-section summary | - -### Step 3: Fetch Content - -**For a single document:** - -``` -Tool: yuque_get_doc -Parameters: - repo_id: "" - doc_id: "" -``` - -**For an entire knowledge base:** - -First, get the TOC to understand the structure: - -``` -Tool: yuque_get_toc -Parameters: - repo_id: "" -``` - -Then list all documents: - -``` -Tool: yuque_list_docs -Parameters: - repo_id: "" -``` - -For knowledge base summaries, read up to 10 key documents (prioritize by TOC order and recent updates). Do NOT try to read every document in a large repo. - -``` -Tool: yuque_get_doc -Parameters: - repo_id: "" - doc_id: "" -``` - -If `yuque_get_doc` returns a 404, skip the document and note it may have been deleted. -If `yuque_get_doc` returns a 403, note the user may lack permission. - -### Step 4: Generate Summary - -**One-liner format:** - -```markdown -📝 **一句话摘要**：[一句话概括文档/知识库的核心内容] -``` - -**Key-points format:** - -```markdown -## 📋 要点摘要 - -**文档**：[文档标题](文档链接) -**知识库**：[知识库名称] -**更新时间**：YYYY-MM-DD - -### 核心要点 - -1. **[要点标题]**：[简要说明，1-2 句话] -2. **[要点标题]**：[简要说明，1-2 句话] -3. **[要点标题]**：[简要说明，1-2 句话] -... - -### 一句话总结 - -[用一句话概括全文核心观点] -``` - -**Detailed format:** - -```markdown -## 📖 详细摘要 - -**文档**：[文档标题](文档链接) -**知识库**：[知识库名称] -**更新时间**：YYYY-MM-DD -**字数**：约 X 字 - -### 背景与目的 - -[文档的背景、写作目的，2-3 句话] - -### 主要内容 - -#### [章节 1 标题] -[该章节的核心内容摘要] - -#### [章节 2 标题] -[该章节的核心内容摘要] - -... - -### 核心结论 - -- [结论 1] -- [结论 2] -- [结论 3] - -### 一句话总结 - -[用一句话概括全文] -``` - -**For knowledge base summaries, use this format:** - -```markdown -## 📚 知识库摘要 - -**知识库**：[知识库名称](知识库链接) -**文档数量**：X 篇 -**最近更新**：YYYY-MM-DD - -### 知识库概览 - -[2-3 句话描述这个知识库的主题和用途] - -### 内容结构 - -1. **[分类/目录 1]**（X 篇）：[简要描述] -2. **[分类/目录 2]**（X 篇）：[简要描述] -... - -### 重点文档 - -1. [文档标题](链接) — [一句话描述] -2. [文档标题](链接) — [一句话描述] -3. [文档标题](链接) — [一句话描述] -``` - -## Guidelines - -- Always answer in the same language the user used (Chinese or English) -- For knowledge base summaries, focus on structure and key documents rather than trying to summarize every single doc -- Preserve the original document's terminology and key concepts -- If the document is very short (< 100 words), just present the content directly instead of summarizing -- Never fabricate content not present in the original document -- Include links back to the original document(s) so the user can read the full source -- When summarizing a knowledge base, respect the TOC order as it reflects the author's intended structure - -## Error Handling - -| Situation | Action | -|-----------|--------| -| Document not found (404) | Inform user the document may have been deleted or the link is incorrect | -| Permission denied (403) | Tell user they may lack permission to access this document | -| Knowledge base is empty | Inform user: "这个知识库目前没有文档" | -| Knowledge base has 50+ docs | Read only the top 10 by TOC order, note that summary covers key documents only | -| Document content is empty | Skip and note: "该文档内容为空" | -| API timeout | Retry once, then inform user of connectivity issue | diff --git a/plugins/openclaw/skills/style-extract/SKILL.md b/plugins/openclaw/skills/style-extract/SKILL.md deleted file mode 100644 index 8d8e562..0000000 --- a/plugins/openclaw/skills/style-extract/SKILL.md +++ /dev/null @@ -1,222 +0,0 @@ ---- -name: style-extract -description: Analyze a user's writing style from their Yuque documents — vocabulary habits, sentence patterns, tone characteristics — and generate a style profile that can be used to maintain consistent voice when writing new content. For personal/individual use. -license: Apache-2.0 -compatibility: Requires yuque-mcp server connected to a Yuque account with personal Token -metadata: - author: chen201724 - version: "1.0" ---- - -# Style Extract — Your Writing Style Profile - -Analyze your existing Yuque documents to extract your unique writing style — vocabulary habits, sentence structures, tone characteristics. Generate a reusable style profile that helps you (or AI) maintain a consistent voice when writing new content. - -## When to Use - -- User wants to understand their own writing style -- User says "分析一下我的写作风格", "我的文风是什么样的", "extract my writing style" -- User wants AI to write in their voice: "用我的风格写一篇...", "write like me" -- User wants to ensure consistency across documents -- User says "帮我生成一个风格画像", "create my style profile" - -## Required MCP Tools - -All tools are from the `yuque-mcp` server: - -- `yuque_list_books` — List user's knowledge bases -- `yuque_list_docs` — List documents in a knowledge base -- `yuque_get_doc` — Read document content for style analysis -- `yuque_search` — Find specific types of documents for analysis -- `yuque_create_doc` — Save the style profile as a document - -## Workflow - -### Step 1: Gather Writing Samples - -Ask the user for source material: - -**Case A — Specific documents:** -User provides links to documents they consider representative of their style. - -**Case B — Entire knowledge base:** -User specifies a knowledge base. Sample documents from it. - -**Case C — Auto-detect best samples:** -If the user isn't sure, search for their most substantial documents: - -``` -Tool: yuque_list_books -``` - -``` -Tool: yuque_list_docs -Parameters: - repo_id: "" -``` - -Select 5-10 documents that are: -- Written by the user (not copied/quoted content) -- Substantial in length (> 500 characters) -- Diverse in topic (to capture general style, not topic-specific patterns) - -For each selected document: - -``` -Tool: yuque_get_doc -Parameters: - repo_id: "" - doc_id: "" -``` - -### Step 2: Analyze Writing Dimensions - -Analyze the collected writing samples across these dimensions: - -#### Vocabulary (用词习惯) -- **Formality level** — Casual, semi-formal, or formal? -- **Jargon density** — Heavy use of domain terms or plain language? -- **Favorite words** — Recurring words or phrases the user gravitates toward -- **Filler patterns** — Common transitions, connectors, hedging words -- **Language mixing** — Do they mix Chinese/English? In what pattern? - -#### Sentence Structure (句式结构) -- **Average sentence length** — Short and punchy or long and flowing? -- **Complexity** — Simple sentences or nested clauses? -- **Paragraph length** — Brief paragraphs or dense blocks? -- **List usage** — Frequent bullet points or prose-heavy? -- **Question usage** — Do they use rhetorical questions? - -#### Tone & Voice (语气特点) -- **Perspective** — First person, second person, or impersonal? -- **Confidence level** — Assertive ("X is Y") or hedged ("X might be Y")? -- **Humor** — Dry wit, playful, or strictly serious? -- **Engagement style** — Conversational or lecture-like? -- **Emotional range** — Neutral/analytical or expressive/passionate? - -#### Structural Habits (结构习惯) -- **Opening style** — How do they start articles? (Question, statement, story, context) -- **Closing style** — How do they end? (Summary, call-to-action, open question) -- **Heading style** — Descriptive, concise, or creative headings? -- **Use of examples** — Frequent concrete examples or abstract reasoning? -- **Formatting preferences** — Heavy use of bold, quotes, code blocks, tables? - -### Step 3: Generate Style Profile - -Create a structured style profile: - -```markdown -# ✍️ 写作风格画像 - -> 基于 [N] 篇文档分析生成 -> 分析日期：YYYY-MM-DD - -## 一句话风格概括 - -[用一句话描述用户的整体写作风格，如 "简洁直接的技术写作者，偏好短句和大量代码示例，语气自信但不傲慢"] - -## 用词习惯 - -- **正式程度**：[描述 + 示例] -- **术语密度**：[描述 + 示例] -- **高频词汇**：[列出 5-10 个标志性用词] -- **过渡词偏好**：[常用的连接词和过渡表达] -- **中英混用**：[模式描述，如 "技术名词用英文，解释用中文"] - -## 句式特征 - -- **句子长度**：[平均字数/句，与参考值对比] -- **段落长度**：[平均句数/段] -- **复杂度**：[简单句为主 / 复合句为主] -- **标志性句式**：[用户常用的句式模式，附原文示例] - -## 语气画像 - -- **视角**：[第一人称 / 第二人称 / 无人称] -- **自信度**：[断言型 / 探讨型 / 谦逊型] -- **幽默感**：[描述] -- **互动性**：[对话式 / 独白式 / 教学式] - -## 结构偏好 - -- **开头方式**：[描述 + 示例] -- **结尾方式**：[描述 + 示例] -- **标题风格**：[描述] -- **举例频率**：[高 / 中 / 低] -- **格式偏好**：[常用的 Markdown 元素] - -## 风格指纹（供 AI 参考） - -当需要模仿此风格写作时，遵循以下规则： - -1. [具体规则 1，如 "每段不超过 4 句话"] -2. [具体规则 2，如 "技术概念首次出现时用中文解释 + 英文原词"] -3. [具体规则 3，如 "多用反问句引导思考"] -4. [具体规则 4，如 "避免使用'众所周知'等套话"] -5. [具体规则 5，如 "结尾倾向于提出开放性问题而非总结"] - -## 示例对比 - -### 原文片段 -> [从用户文档中摘取的典型段落] - -### 风格要素标注 -[标注该段落中体现的风格特征] -``` - -### Step 4: Present and Refine - -Show the style profile to the user and ask: - -"这个风格画像准确吗？有没有哪些地方需要调整？" - -Iterate based on user feedback. They might say: -- "我觉得我没那么正式" → Adjust formality assessment -- "这个高频词不是我的风格，是那篇文章特有的" → Remove outliers -- "我希望新内容比我现在的风格更简洁" → Note as a style aspiration - -### Step 5: Save Style Profile (Optional) - -Ask the user: "要把风格画像保存到语雀吗？以后写作时可以参考。" - -If confirmed: - -``` -Tool: yuque_create_doc -Parameters: - repo_id: "" - title: "✍️ 我的写作风格画像" - body: "