\r \r

语雀知识库双向同步\r

\r

概述\r

\r 语雀知识库与本地文件的双向同步工具。支持将本地文件导入语雀，也支持从语雀下载文档内容到本地保存。通过语雀 MCP 的 19 个工具实现完整的读写能力。\r \r

支持的文件格式\r

\r

导入（本地 → 语雀）\r

\r | 格式 | 导入方式 | 说明 |\r |------|---------|------|\r | .md | 直接导入 | 原文作为 body，format: markdown |\r | .docx | 读取转换后导入 | 使用 docx 技能读取内容，转 Markdown 导入 |\r | .xlsx | 读取转换后导入 | 使用 xlsx 技能读取数据，转 Markdown 表格导入，每个工作表单独创建文档 |\r | .html | 直接导入 | 原文作为 body，format: html |\r | .txt | 转换后导入 | 包裹为 Markdown 格式导入 |\r | .csv | 转换后导入 | 转为 Markdown 表格导入 |\r | .json | 转换后导入 | 转为格式化代码块导入 |\r | zip/文件夹 | 批量导入 | 解压后逐个处理内部文件，批量创建文档 |\r \r

下载（语雀 → 本地）\r

\r | 下载内容 | 输出格式 | 说明 |\r |---------|---------|------|\r | 单篇文档 | .md | 使用 yuque_get_doc + format: markdown，保存为 Markdown 文件 |\r | 整个知识库 | 多个 .md | yuque_list_docs + 逐篇 yuque_get_doc，每个文档一个文件 |\r | 指定目录 | 多个 .md | yuque_get_toc 筛选目录下文档，逐篇下载 |\r | 小记 | .md | yuque_list_notes + yuque_get_note，保存为 Markdown |\r \r ---\r \r

操作示例（附实际结果）\r

\r

示例 1：上传 Markdown 文件到语雀\r

\r 输入：用户说「把这个文件传到考试系统知识库」\r \r 执行步骤：\r

1. Read(file_path="C:/Users/Admin/报告/6月周报.md")  → 获取文件内容\r
2. DeferExecuteTool("mcp__yuque__yuque_get_doc", {repo_id: "78381340", ...})\r
   或直接 DeferExecuteTool("mcp__yuque__yuque_create_doc",\r
     {repo_id: "78381340", title: "6月周报", body: "\x3C文件内容>", format: "markdown"})\r
```\r
\r
**实际返回结果**：\r
```\r
文档创建成功\r
标题: 6月周报\r
文档ID: 272726945\r
slug: 6-zhou-bao\r
链接: https://www.yuque.com/jiuwu-tue7v/lerk9f/6-zhou-bao\r
```\r
\r
**用户拿到手的是**：一个可以直接点击打开的语雀文档链接，文档内容与本地 Markdown 一致。\r
\r
---\r
\r
### 示例 2：从语雀下载文档到本地\r
\r
**输入**：用户说「把语雀考试系统知识库里的「语雀知识库连接器配置技能」下载到本地」\r
\r
**执行步骤**：\r
```\r
1. DeferExecuteTool("mcp__yuque__yuque_get_doc",\r
     {repo_id: "78381340", doc_id: "yuque-connector-skill", format: "markdown"})\r
   → 返回 Markdown 格式的文档正文\r
2. Write(file_path="C:/Users/Admin/下载/语雀知识库连接器配置技能.md",\r
         content=\x3C返回的body>)\r
```\r
\r
**实际返回结果**：\r
```\r
已下载到本地\r
文件路径: C:/Users/Admin/下载/语雀知识库连接器配置技能.md\r
文件大小: 4.2 KB\r
来源: https://www.yuque.com/jiuwu-tue7v/lerk9f/yuque-connector-skill\r
```\r
\r
**用户拿到手的是**：本地 Markdown 文件，可在任意编辑器中打开编辑。\r
\r
---\r
\r
### 示例 3：批量下载整个知识库\r
\r
**输入**：用户说「把考试系统知识库所有文档都下载到本地」\r
\r
**执行步骤**：\r
```\r
1. DeferExecuteTool("mcp__yuque__yuque_list_docs", {repo_id: "78381340"})\r
   → 返回文档列表（含每篇文档的 id、title、slug）\r
2. 遍历每篇文档：\r
   DeferExecuteTool("mcp__yuque__yuque_get_doc",\r
     {repo_id: "78381340", doc_id: "\x3Cdoc_id>", format: "markdown"})\r
   → Write("C:/Users/Admin/下载/考试系统知识库/\x3Ctitle>.md", \x3Cbody>)\r
3. 批量间加 1 秒间隔（防 429）\r
```\r
\r
**实际返回结果**：\r
```\r
已下载 12 篇文档到 C:/Users/Admin/下载/考试系统知识库/\r
├── 语雀知识库连接器配置技能.md\r
├── 考试平台使用指南（第1章）.md\r
├── 考试平台使用指南（第2章）.md\r
├── ...\r
└── 定价方案说明.md\r
```\r
\r
**用户拿到手的是**：一个文件夹，里面是知识库全部文档的 Markdown 副本。\r
\r
---\r
\r
### 示例 4：上传 Excel 到语雀（多工作表拆分）\r
\r
**输入**：用户说「把这个 Excel 传到语雀」\r
\r
**执行步骤**：\r
```\r
1. Skill("xlsx") → 读取 Excel 所有工作表数据\r
2. 对每个工作表：\r
   - 将数据转为 Markdown 表格\r
   - 标题 = "{文件名} - {工作表名}"\r
   - DeferExecuteTool("mcp__yuque__yuque_create_doc",\r
       {repo_id: "78381340", title: "\x3C标题>", body: "\x3CMarkdown表格>", format: "markdown"})\r
```\r
\r
**实际返回结果**：\r
```\r
已导入 3 篇文档：\r
1. 销售数据.xlsx - Q1业绩 → https://www.yuque.com/jiuwu-tue7v/lerk9f/q1-ye-ji\r
2. 销售数据.xlsx - Q2业绩 → https://www.yuque.com/jiuwu-tue7v/lerk9f/q2-ye-ji\r
3. 销售数据.xlsx - Q3业绩 → https://www.yuque.com/jiuwu-tue7v/lerk9f/q3-ye-ji\r
```\r
\r
**用户拿到手的是**：3 个语雀文档链接，每个链接打开后是一张格式整齐的数据表格。\r
\r
---\r
\r
## 核心工作流\r
\r
### 导入：本地文件 → 语雀\r
\r
```\r
1. 读取源文件（Read 工具 / docx 技能 / xlsx 技能）\r
2. 转换内容为 Markdown 或 HTML\r
3. yuque_create_doc → 返回语雀链接\r
   参数: repo_id(必填), title(必填), body(内容), format("markdown"推荐), slug(可选), public(0/1)\r
```\r
\r
### 下载：语雀 → 本地\r
\r
```\r
1. yuque_get_doc(repo_id, doc_id, format: "markdown") → 获取文档正文\r
2. Write 保存到本地指定路径，文件名 = 文档标题 + ".md"\r
3. 返回保存路径给用户\r
```\r
\r
### 批量下载：整个知识库/目录\r
\r
```\r
1. yuque_list_docs(repo_id) 或 yuque_get_toc(repo_id) 获取文档列表\r
2. 循环: yuque_get_doc → Write，每篇间隔 1 秒\r
3. 汇总: 列出所有保存的文件路径\r
```\r
\r
### 同步检查：对比本地与语雀差异\r
\r
```\r
1. yuque_get_doc 获取语雀最新内容\r
2. Read 读取本地文件内容\r
3. 对比差异并报告：哪些文档语雀有更新、哪些本地有修改\r
4. 用户选择同步方向（上传/下载/双向合并）\r
```\r
\r
---\r
\r
## 下载功能详细说明\r
\r
### yuque_get_doc 参数\r
\r
```\r
repo_id:  知识库 ID（必填）\r
doc_id:   文档 ID 或 slug（必填）\r
format:   "markdown"（推荐，返回纯 Markdown）| "lake" | "html"\r
include_lake: true（同时返回 Lake 原始格式，保留 Mermaid 源码等）\r
```\r
\r
### 下载时文件名处理\r
\r
- 优先使用文档 `title` 作为文件名\r
- 清理非法字符（\/:*?"\x3C>|）\r
- 添加 `.md` 扩展名\r
- 如目标目录已有同名文件，追加序号：`标题(2).md`\r
\r
### 批量下载限流\r
\r
- 每篇文档下载后等待 1 秒（防止 429 限流）\r
- 如遇 429，等待 5 秒后重试，最多重试 3 次\r
- 可通过 `yuque_get_toc` 先获取目录结构，选择性下载特定目录\r
\r
---\r
\r
## 进阶功能\r
\r
### 1. 目录管理（组织知识库结构）\r
\r
```python\r
# 获取当前目录结构\r
yuque_get_toc(repo_id="78381340")\r
\r
# 在根目录下新建分组\r
yuque_update_toc(repo_id="78381340",\r
  toc_data='{"action":"appendNode","action_mode":"child","target_uuid":"","type":"TITLE","title":"月度报告"}')\r
\r
# 在指定分组下添加文档（需要先知道分组的 uuid）\r
yuque_update_toc(repo_id="78381340",\r
  toc_data='{"action":"appendNode","action_mode":"child","target_uuid":"\x3C分组uuid>","type":"DOC","title":"6月报告","doc_id":"\x3Cdoc_id>"}')\r
```\r
\r
**适用场景**：新知识库初始化、批量导入后整理目录、跨目录移动文档。\r
\r
### 2. 文档搜索与引用\r
\r
```python\r
# 搜索文档（全文搜索）\r
yuque_search(query="考试系统", type="doc")\r
\r
# 搜索知识库\r
yuque_search(query="培训", type="repo")\r
\r
# 搜索后获取全文\r
yuque_get_doc(repo_id="\x3Cid>", doc_id="\x3Cid>", format: "markdown")\r
```\r
\r
**适用场景**：查找历史文档、引用已有内容到新文档中。\r
\r
### 3. 文档更新（同步修改）\r
\r
```python\r
# 更新已有文档内容\r
yuque_update_doc(repo_id="78381340", doc_id="272726945",\r
  title="6月周报（修订版）", body="\x3C新内容>", format: "markdown")\r
```\r
\r
**适用场景**：本地文件修改后同步到语雀、修正已上传文档的内容。\r
\r
### 4. 小记（快速笔记）\r
\r
```python\r
# 创建小记\r
yuque_create_note(body="今天完成了语雀连接器的配置工作")\r
\r
# 列出小记\r
yuque_list_notes(limit=10)\r
\r
# 获取小记详情\r
yuque_get_note(note_id="\x3Cid>")\r
```\r
\r
**适用场景**：快速记录碎片想法、待办事项、临时笔记。\r
\r
### 5. 知识库创建与管理\r
\r
```python\r
# 创建新知识库\r
yuque_create_book(name="新项目文档", slug="new-project")\r
\r
# 获取知识库详情\r
yuque_get_book(repo_id="78381340")\r
\r
# 更新知识库信息\r
yuque_update_book(repo_id="78381340", name="新名称", description="更新后的描述")\r
```\r
\r
### 6. Board 资源创建（思维导图/流程图）\r
\r
```python\r
# 创建思维导图\r
yuque_create_resource(resource_type="board", type="mindmap",\r
  dsl="# 中心主题\
## 分支1\
### 细节\
## 分支2",\r
  doc_id=272726945)\r
\r
# 创建流程图\r
yuque_create_resource(resource_type="board", type="flowchart",\r
  dsl="A[开始] --> B[处理] --> C[结束]",\r
  doc_id=272726945)\r
```\r
\r
### 7. Markdown 内容处理注意事项\r
\r
- **代码块**：确保用 ``` 包裹，语雀渲染器支持语法高亮\r
- **图片链接**：外部图片 URL（https://）可在语雀中正常显示；本地图片路径不会生效\r
- **表格**：使用标准 Markdown 表格语法，语雀完全支持\r
- **Mermaid 图表**：使用 `include_lake: true` 获取原始 Mermaid 源码\r
- **数学公式**：语雀支持 LaTeX 语法（$...$ 和 $$...$$）\r
- **锚点链接**：语雀文档内部链接格式为 `((doc_id '显示文字'))`\r
\r
---\r
\r
## 错误处理与自动恢复\r
\r
### 常见错误及自动恢复策略\r
\r
| 错误码 | 含义 | 自动恢复 | 手动处理 |\r
|--------|------|---------|---------|\r
| **401** | Token 无效/过期 | 自动提示重新获取 | 前往 [设置页](https://www.yuque.com/settings/tokens) 重新生成 |\r
| **403** | 权限不足 | 提示检查知识库权限 | 确认账号是否有该知识库的读写权限 |\r
| **404** | 文档/知识库不存在 | 提示检查 ID 是否正确 | 用 `yuque_list_books` 确认正确的 repo_id |\r
| **422** | 参数验证失败 | 自动修正常见参数问题（如 format 大小写） | 检查传入参数是否符合 API 要求 |\r
| **429** | 请求频率超限 | **自动等待 5 秒后重试，最多 3 次** | 批量操作时主动加大间隔（2-3 秒） |\r
| **500** | 语雀服务异常 | **自动等待 10 秒后重试，最多 2 次** | 稍后再试，或检查 [语雀状态页](https://www.yuque.com) |\r
| **网络超时** | 连接超时 | **自动重试 1 次** | 检查网络连接 |\r
\r
### 重试机制（内置）\r
\r
所有 MCP 调用遇到以下情况时自动重试：\r
```\r
重试条件: 429（限流）/ 500（服务异常）/ 网络超时\r
重试次数: 最多 3 次\r
重试间隔: 429→5秒, 500→10秒, 超时→3秒（指数退避）\r
失败后: 停止操作，报告失败详情和建议\r
```\r
\r
### 配置写入失败恢复\r
\r
如果 `~/.workbuddy/mcp.json` 写入失败：\r
1. 检查文件是否存在 → 不存在则创建（含基础结构 `{}`）\r
2. 检查 JSON 是否合法 → 不合法则读取原文件内容，修复后重写\r
3. 检查磁盘空间 → 空间不足则提示清理\r
4. 写入前自动备份原文件为 `mcp.json.bak`\r
\r
### MCP 服务加载失败排查\r
\r
如果语雀 MCP 工具无法调用：\r
1. **验证 MCP 配置**：读取 `~/.workbuddy/mcp.json`，确认 yuque 条目存在且格式正确\r
2. **验证 Token**：调用 `yuque_get_user` 测试连通性，失败则 Token 有问题\r
3. **验证 npx**：Bash 执行 `npx -y yuque-mcp --help` 确认包可下载\r
4. **重写配置**：以上均正常则删除 yuque 条目后重新写入\r
5. **最终回退**：如 MCP 确实无法加载，降级使用 `urllib` 直接调语雀 REST API：\r
   ```\r
   Base URL: https://www.yuque.com/api/v2\r
   认证: X-Auth-Token header\r
   端点: /user, /users/{login}/repos, /repos/{id}/docs, /repos/{id}/docs/{id}\r
   ```\r
\r
### 批量操作断点续传\r
\r
批量导入/下载超过 10 篇文档时：\r
1. 每成功一篇记录 doc_id 到临时进度文件\r
2. 如中途失败，重启后从进度文件中读取已完成的 doc_id\r
3. 跳过已完成，从中断处继续\r
4. 全部完成后删除进度文件\r
\r
---\r
\r
## 全部可用工具速查\r
\r
### 文档操作（核心）\r
\r
| 工具 | 用途 | 必填参数 | 可选参数 |\r
|------|------|---------|---------|\r
| `yuque_create_doc` | 创建/导入文档 | repo_id, title | body, format, slug, public |\r
| `yuque_update_doc` | 更新已有文档 | repo_id, doc_id | title, body, format, slug, public |\r
| `yuque_get_doc` | 读取文档内容 | repo_id, doc_id | format, include_lake |\r
| `yuque_list_docs` | 列出知识库文档 | repo_id | - |\r
\r
### 知识库与目录\r
\r
| 工具 | 用途 | 必填参数 | 可选参数 |\r
|------|------|---------|---------|\r
| `yuque_list_books` | 列出知识库 | login | - |\r
| `yuque_get_book` | 知识库详情 | repo_id | - |\r
| `yuque_create_book` | 创建知识库 | name | slug, description, public |\r
| `yuque_update_book` | 更新知识库 | repo_id | name, description, public, slug |\r
| `yuque_get_toc` | 获取目录结构 | repo_id | - |\r
| `yuque_update_toc` | 更新目录结构 | repo_id, toc_data | - |\r
\r
### 搜索\r
\r
| 工具 | 用途 | 必填参数 |\r
|------|------|---------|\r
| `yuque_search` | 搜索文档或知识库 | query, type(doc/repo) |\r
\r
### 小记\r
\r
| 工具 | 用途 | 必填参数 | 可选参数 |\r
|------|------|---------|---------|\r
| `yuque_list_notes` | 列出小记 | - | limit, page, status |\r
| `yuque_get_note` | 获取小记详情 | note_id | - |\r
| `yuque_create_note` | 创建小记 | body | - |\r
| `yuque_update_note` | 更新小记 | note_id | body |\r
\r
### Board 资源\r
\r
| 工具 | 用途 | 必填参数 |\r
|------|------|---------|\r
| `yuque_create_resource` | 创建思维导图/流程图 | resource_type("board"), type, dsl |\r
| `yuque_get_resource` | 获取 Board 内容 | resource_type("board"), resource_id |\r
| `yuque_update_resource` | 更新 Board | resource_type("board"), resource_id, dsl |\r
\r
### 用户\r
\r
| 工具 | 用途 |\r
|------|------|\r
| `yuque_get_user` | 获取当前用户信息（用于验证 Token 有效性） |\r
\r
---\r
\r
## 配置指南\r
\r
> **首次使用必读**：本技能依赖语雀 MCP 连接器。每位使用者需要配置**自己的语雀 Token**，Token 不随技能分发。\r
\r
### 第一步：获取你的语雀 Token\r
\r
1. 打开 [语雀](https://www.yuque.com) 并登录**你自己的账号**\r
2. 点击右上角 **头像 → 设置 → Tokens**（直达：https://www.yuque.com/settings/tokens）\r
3. 点击 **新建令牌**\r
4. 权限勾选 **读取 + 写入**\r
5. 复制生成的 Token（**只显示一次，务必保存**）\r
\r
### 第二步：配置 MCP 连接器\r
\r
告知 AI 助手「配置语雀连接器」，并附上你的 Token。\r
\r
助手会自动完成以下操作：\r
1. 读取 `~/.workbuddy/mcp.json`（保留已有配置）\r
2. 写入语雀条目：\r
\r
```json\r
{\r
  "mcpServers": {\r
    "yuque": {\r
      "command": "npx",\r
      "args": ["-y", "yuque-mcp"],\r
      "env": {\r
        "YUQUE_PERSONAL_TOKEN": "\x3C你自己的Token>"\r
      }\r
    }\r
  }\r
}\r
```\r
\r
3. 写入前自动备份原文件为 `mcp.json.bak`\r
\r
### 第三步：验证连接\r
\r
配置后重启 WorkBuddy，助手会自动调用 `yuque_get_user` 验证连通性。返回你的用户名即表示成功。\r
\r
### 换电脑怎么办？\r
\r
- **Token**：跟随你的语雀账号，换电脑同样有效\r
- **MCP 配置**：需要重新写入（配置文件是本地的）\r
- **技能文件**：重新安装即可\r
- 只需把你的 Token 再贴给助手，一键恢复全部功能\r
\r
---\r
\r
## 已知限制\r
\r
| 限制 | 说明 | 替代方案 |\r
|------|------|---------|\r
| 图片上传 | MCP 不支持通用图片附件 | 外部图片 URL 可在 Markdown 中直接引用 |\r
| 二进制文件 | 视频、音频等需手动上传 | 语雀网页端手动上传 |\r
| yuque_create_resource | 仅支持 board 类型 | 二进制文件用网页端上传 |\r
\r
## 参考信息\r
\r
- **npm 包**: `yuque-mcp`\r
- **官方仓库**: https://github.com/yuque/yuque-mcp-server\r
- **API Base**: `https://www.yuque.com/api/v2`\r
- **Token 设置**: https://www.yuque.com/settings/tokens\r