yuque-ai-mcp 2.7.6 → 2.7.9

package/README.md

@@ -4,13 +4,13 @@
 
 <h1 align="center">yuque-ai-mcp</h1>
 <p align="center">
-  <b>61 fine-grained MCP tools for the full Yuque OpenAPI</b>
+  <b>63 fine-grained MCP tools for the full Yuque OpenAPI</b>
 </p>
 
 <p align="center">
-  <a href="https://github.com/yehuoshun/yuque-ai-mcp"><img src="https://img.shields.io/badge/version-2.7.4-blue" alt="version" /></a>
+  <a href="https://github.com/yehuoshun/yuque-ai-mcp"><img src="https://img.shields.io/badge/version-2.7.8-blue" alt="version" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="license" /></a>
-  <a href="https://github.com/yehuoshun/yuque-ai-skills"><img src="https://img.shields.io/badge/skills-61%20guides-orange" alt="skills" /></a>
+  <a href="https://github.com/yehuoshun/yuque-ai-skills"><img src="https://img.shields.io/badge/skills-63%20guides-orange" alt="skills" /></a>
 </p>
 
 <p align="center">
@@ -19,15 +19,15 @@
 
 ---
 
-A full-featured Yuque (语雀) MCP Server built on the [Model Context Protocol](https://modelcontextprotocol.io/). Provides 61 fine-grained tools across 15 domains — every Yuque OpenAPI endpoint as a dedicated tool.
+A full-featured Yuque (语雀) MCP Server built on the [Model Context Protocol](https://modelcontextprotocol.io/). Provides 63 fine-grained tools across 15 domains — every Yuque OpenAPI endpoint as a dedicated tool.
 
 ## Why
 
-- **19 → 61 tools** — 3x more coverage than the official [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server)
+- **19 → 63 tools** — 3x more coverage than the official [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server)
 - **Dual transport** — stdio + HTTP SSE, shared registry, zero downtime on reload
 - **Modular architecture** — 15 domains, barrel exports, single source of truth registry
 - **Full API coverage** — group, recycle, upload, statistics, versions, boards — all the missing pieces
-- **[Skill layer](https://github.com/yehuoshun/yuque-ai-skills)** — 61 usage guides for AI agents
+- **[Skill layer](https://github.com/yehuoshun/yuque-ai-skills)** — 63 usage guides for AI agents
 
 ## Table of Contents
 
@@ -61,10 +61,10 @@ npm run dev:http       # HTTP SSE mode (http://localhost:3099)
 
 | Domain | Tools | Highlights |
 |--------|-------|------------|
-| **doc** | 14 | CRUD, versions, diff, batch get, import URL/file, cross-book copy, export |
+| **doc** | 15 | CRUD, versions, diff, batch get, import URL/file, cross-book copy, export, resource download |
 | **repo** | 8 | CRUD, batch get, cross-book copy, full export (TOC-structure + INDEX/GRAPH) |
 | **toc** | 3 | Get, update, batch update (createTitle/appendNode/removeNode/moveNode) |
-| **search** | 2 | General search + RAG-enhanced search |
+| **search** | 3 | General search + RAG-enhanced search + Cookie web search |
 | **user** | 3 | User info, heartbeat, group list |
 | **group** | 3 | Member list, role change, delete member |
 | **statistic** | 4 | Group/member/repo/doc statistics |
@@ -76,21 +76,89 @@ npm run dev:http       # HTTP SSE mode (http://localhost:3099)
 | **rss** | 3 | Source list, fetch + dedup + save, schedule analysis |
 | **crawler** | 4 | Fetch, CSS extract, dedup save, schedule analysis |
 | **kv** | 4 | Get, set, delete, list — incremental sharding, 250KB/doc limit |
-| **Total** | **61** | |
-
-See [SKILL.md](SKILL.md) or [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills) for full tool documentation.
+| **Total** | **63** | |
+
+### All 63 Tools
+
+| Tool | Domain | Description |
+|------|--------|-------------|
+| `yuque_hello` | user | 心跳检测，验证 Token 有效性 |
+| `yuque_get_user` | user | 获取当前 Token 的用户详情 |
+| `yuque_get_user_groups` | user | 获取用户所属的团队列表 |
+| `yuque_search` | search | 通用搜索文档/知识库 |
+| `yuque_rag_search` | search | RAG 检索增强搜索 + 自动获取文档内容 |
+| `yuque_web_search` | search | Cookie 态 Web 搜索，返回完整文档对象 + 精确总数 + 高亮摘要 |
+| `yuque_get_group_users` | group | 获取团队成员列表 |
+| `yuque_update_group_user` | group | 变更团队成员角色 |
+| `yuque_delete_group_user` | group | 删除团队成员 |
+| `yuque_list_docs` | doc | 获取知识库文档列表 |
+| `yuque_create_doc` | doc | 创建文档 |
+| `yuque_get_doc` | doc | 获取文档详情（支持 ID 或 slug） |
+| `yuque_update_doc` | doc | 更新文档 |
+| `yuque_delete_doc` | doc | 删除文档 |
+| `yuque_batch_get_docs` | doc | 批量获取文档详情（max 20） |
+| `yuque_get_doc_versions` | doc | 获取文档历史版本列表 |
+| `yuque_get_doc_version_detail` | doc | 获取文档历史版本详情 |
+| `yuque_diff_doc_versions` | doc | 对比两个版本的行级差异 |
+| `yuque_copy_doc` | doc | 单文档跨库复制 |
+| `yuque_export_doc` | doc | 导出单篇文档为 Markdown 文件 |
+| `yuque_export_resources` | doc | 下载文档中的图片/附件到本地 |
+| `yuque_import_url` | doc | 从网页 URL 导入文档 |
+| `yuque_import_file` | doc | 从本地文件导入文档 |
+| `yuque_embed_url` | doc | 生成文档嵌入阅读器 URL |
+| `yuque_get_toc` | toc | 获取知识库目录 |
+| `yuque_update_toc` | toc | 更新知识库目录 |
+| `yuque_batch_update_toc` | toc | 批量更新目录（createTitle/appendNode/removeNode/moveNode/prependDoc） |
+| `yuque_list_repos` | repo | 获取知识库列表（用户/团队） |
+| `yuque_create_repo` | repo | 创建知识库 |
+| `yuque_get_repo` | repo | 获取知识库详情 |
+| `yuque_update_repo` | repo | 更新知识库 |
+| `yuque_delete_repo` | repo | 删除知识库 |
+| `yuque_batch_get_repos` | repo | 批量获取知识库详情（max 20） |
+| `yuque_copy_repo` | repo | 批量跨库复制（LLM 分类 + 目录重建） |
+| `yuque_export_repo` | repo | 批量导出知识库为 Markdown（按 TOC 目录结构） |
+| `yuque_get_group_statistics` | statistic | 获取团队汇总统计数据 |
+| `yuque_get_member_statistics` | statistic | 获取团队成员统计数据 |
+| `yuque_get_book_statistics` | statistic | 获取团队知识库统计数据 |
+| `yuque_get_doc_statistics` | statistic | 获取团队文档统计数据 |
+| `yuque_list_notes` | note | 获取小记列表 |
+| `yuque_get_note` | note | 获取小记详情 |
+| `yuque_create_note` | note | 创建小记 |
+| `yuque_update_note` | note | 更新小记 |
+| `yuque_list_recycles` | recycle | 列出回收站项目 |
+| `yuque_restore_recycle` | recycle | 恢复回收站项目 |
+| `yuque_destroy_recycle` | recycle | 彻底删除回收站项目 |
+| `yuque_upload_attachment` | upload | 上传文件到语雀 CDN |
+| `yuque_get_board` | board | 获取文档中的画板资源 |
+| `yuque_create_board` | board | 在文档中创建画板资源 |
+| `yuque_update_board` | board | 更新文档中的画板资源 |
+| `yuque_rss_list_sources` | rss | 列出所有可用 RSS 数据源及 feed 类型 |
+| `yuque_rss_fetch` | rss | 抓取 RSS/Atom Feed，解析后去重写入语雀 |
+| `yuque_rss_schedule` | rss | 分析更新频率，生成推荐抓取时间 |
+| `yuque_crawl_fetch` | crawler | 抓取网页原始 HTML |
+| `yuque_crawl_extract` | crawler | CSS 选择器从 HTML 提取内容 |
+| `yuque_crawl_save` | crawler | 去重 + 写入语雀 |
+| `yuque_crawl_schedule` | crawler | 分析爬虫抓取频率，生成推荐抓取时间 |
+| `yuque_get_book_stacks` | mine | 获取知识库分组（书架）列表 |
+| `yuque_get_editor_center` | mine | 获取个人编辑中心全景数据 |
+| `yuque_kv_get` | kv | 读取 KV 命名空间的完整 JSON map（分片合并） |
+| `yuque_kv_set` | kv | 增量设置 key-value，超 250KB 自动分片 |
+| `yuque_kv_delete` | kv | 遍历分片查找并删除 key |
+| `yuque_kv_list` | kv | 列出已配置的 KV 命名空间 |
+
+See [SKILL.md](SKILL.md) or [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills) for full tool documentation with parameters and examples.
 
 ## vs Official
 
 | Feature | Official yuque-mcp-server | yuque-ai-mcp |
 |---------|--------------------------|--------------|
-| Tools | 19 | **61** |
+| Tools | 19 | **63** |
 | Granularity | Coarse | **Fine-grained** (1 tool / endpoint) |
 | Group, Recycle, Upload, Statistics | ❌ | ✅ |
 | Versions, Diff, Cross-book Copy | ❌ | ✅ |
 | Transport | stdio only | **stdio + HTTP SSE** |
 | Config | Env var | **config.json** (token + cookie) |
-| Skill Layer | ❌ | ✅ 61 guides |
+| Skill Layer | ❌ | ✅ 63 guides |
 
 ## Architecture
 
@@ -98,7 +166,7 @@ See [SKILL.md](SKILL.md) or [yuque-ai-skills](https://github.com/yehuoshun/yuque
 server/src/
 ├── common/              # Shared: config, errors, types, format, validate,
 │                        # api-client, web-request, register-tools, copy/export/schedule common,
-│                        # repo-capacity (auto-expand), toc-cache (24h TTL), text-utils
+│                        # repo-capacity (auto-expand), toc-cache (configurable TTL), text-utils
 ├── user/ search/ group/ doc/ toc/ repo/ statistic/
 ├── note/ recycle/ upload/ board/ rss/ crawler/ mine/ kv/
 ├── index.ts             # stdio entry
@@ -127,8 +195,8 @@ server/src/
     },
     "namespaces": {
       "cnblogs": {
-        "book_id": [80197497],
-        "kv_slugs": ["80197550/274164064"],
+        "book_id": [0],
+        "kv_slugs": [],
         "schedule_slugs": []
       }
     }
@@ -137,8 +205,8 @@ server/src/
     "enabled": true,
     "namespaces": {
       "my-source": {
-        "book_id": [80197497],
-        "kv_slugs": ["80197550/274164064"],
+        "book_id": [0],
+        "kv_slugs": [],
         "schedule_slugs": []
       }
     }
@@ -149,6 +217,7 @@ server/src/
 - `book_id`: Target repo ID array — last element is the active repo. Auto-expands when full (5000 docs).
 - `kv_slugs`: KV dedup shard docs (`{book_id}/{doc_id}` format)
 - `schedule_slugs`: Schedule config docs
+- `toc_cache_ttl_minutes`: TOC cache TTL in minutes (default 60). Set higher to reduce API calls, lower for fresher data.
 
 ## Error Handling
 

package/README_CN.md

@@ -1,14 +1,14 @@
 <p align="center">
   <h1 align="center">yuque-ai-mcp</h1>
   <p align="center">
-    <b>61 个细粒度 MCP 工具，覆盖语雀 OpenAPI 全部能力</b>
+    <b>63 个细粒度 MCP 工具，覆盖语雀 OpenAPI 全部能力</b>
   </p>
 </p>
 
 <p align="center">
-  <a href="https://github.com/yehuoshun/yuque-ai-mcp"><img src="https://img.shields.io/badge/版本-2.7.4-blue" alt="version" /></a>
+  <a href="https://github.com/yehuoshun/yuque-ai-mcp"><img src="https://img.shields.io/badge/版本-2.7.8-blue" alt="version" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/许可-MIT-green" alt="license" /></a>
-  <a href="https://github.com/yehuoshun/yuque-ai-skills"><img src="https://img.shields.io/badge/skills-61%20指导-orange" alt="skills" /></a>
+  <a href="https://github.com/yehuoshun/yuque-ai-skills"><img src="https://img.shields.io/badge/skills-63%20指导-orange" alt="skills" /></a>
 </p>
 
 <p align="center">
@@ -17,15 +17,15 @@
 
 ---
 
-基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的语雀全功能 MCP Server。61 个工具，15 个域——每个语雀 OpenAPI 端点一个专用工具。
+基于 [Model Context Protocol](https://modelcontextprotocol.io/) 的语雀全功能 MCP Server。63 个工具，15 个域——每个语雀 OpenAPI 端点一个专用工具。
 
 ## 为什么选这个
 
-- **19 → 61 工具** — 比官方 [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) 多 3 倍覆盖
+- **19 → 63 工具** — 比官方 [yuque-mcp-server](https://github.com/yuque/yuque-mcp-server) 多 3 倍覆盖
 - **双传输模式** — stdio + HTTP SSE，共享注册中心，修改无需重启
 - **模块化架构** — 15 个域，barrel export，唯一注册中心
 - **完整 API 覆盖** — 团队、回收站、上传、统计、版本、画板——补全官方缺失
-- **[Skill 层](https://github.com/yehuoshun/yuque-ai-skills)** — 61 个 AI Agent 使用指导
+- **[Skill 层](https://github.com/yehuoshun/yuque-ai-skills)** — 63 个 AI Agent 使用指导
 
 ## 目录
 
@@ -60,10 +60,10 @@ npm run dev:http       # HTTP SSE 模式 (http://localhost:3099)
 
 | 域 | 工具数 | 亮点 |
 |--------|-------|------------|
-| **doc** | 14 | CRUD、版本管理、Diff、批量获取、URL/文件导入、跨库复制、导出 |
+| **doc** | 15 | CRUD、版本管理、Diff、批量获取、URL/文件导入、跨库复制、导出、资源下载 |
 | **repo** | 8 | CRUD、批量获取、跨库复制、全量导出（TOC 结构 + INDEX/GRAPH） |
 | **toc** | 3 | 获取、更新、批量更新（createTitle/appendNode/removeNode/moveNode） |
-| **search** | 2 | 通用搜索 + RAG 增强搜索 |
+| **search** | 3 | 通用搜索 + RAG 增强搜索 + Cookie Web 搜索 |
 | **user** | 3 | 用户信息、心跳、团队列表 |
 | **group** | 3 | 成员列表、角色变更、删除成员 |
 | **statistic** | 4 | 团队/成员/知识库/文档统计 |
@@ -75,21 +75,89 @@ npm run dev:http       # HTTP SSE 模式 (http://localhost:3099)
 | **rss** | 3 | 数据源列表、抓取+去重+写入、定时策略分析 |
 | **crawler** | 4 | 抓取、CSS 提取、去重写入、定时策略分析 |
 | **kv** | 4 | 增删查列——增量分片，单文档 250KB 上限 |
-| **合计** | **61** | |
-
-完整工具文档见 [SKILL.md](SKILL.md) 或 [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills)。
+| **合计** | **63** | |
+
+### 全部 63 个工具
+
+| 工具 | 域 | 说明 |
+|------|--------|-------------|
+| `yuque_hello` | user | 心跳检测，验证 Token 有效性 |
+| `yuque_get_user` | user | 获取当前 Token 的用户详情 |
+| `yuque_get_user_groups` | user | 获取用户所属的团队列表 |
+| `yuque_search` | search | 通用搜索文档/知识库 |
+| `yuque_rag_search` | search | RAG 检索增强搜索 + 自动获取文档内容 |
+| `yuque_web_search` | search | Cookie 态 Web 搜索，返回完整文档对象 + 精确总数 + 高亮摘要 |
+| `yuque_get_group_users` | group | 获取团队成员列表 |
+| `yuque_update_group_user` | group | 变更团队成员角色 |
+| `yuque_delete_group_user` | group | 删除团队成员 |
+| `yuque_list_docs` | doc | 获取知识库文档列表 |
+| `yuque_create_doc` | doc | 创建文档 |
+| `yuque_get_doc` | doc | 获取文档详情（支持 ID 或 slug） |
+| `yuque_update_doc` | doc | 更新文档 |
+| `yuque_delete_doc` | doc | 删除文档 |
+| `yuque_batch_get_docs` | doc | 批量获取文档详情（max 20） |
+| `yuque_get_doc_versions` | doc | 获取文档历史版本列表 |
+| `yuque_get_doc_version_detail` | doc | 获取文档历史版本详情 |
+| `yuque_diff_doc_versions` | doc | 对比两个版本的行级差异 |
+| `yuque_copy_doc` | doc | 单文档跨库复制 |
+| `yuque_export_doc` | doc | 导出单篇文档为 Markdown 文件 |
+| `yuque_export_resources` | doc | 下载文档中的图片/附件到本地 |
+| `yuque_import_url` | doc | 从网页 URL 导入文档 |
+| `yuque_import_file` | doc | 从本地文件导入文档 |
+| `yuque_embed_url` | doc | 生成文档嵌入阅读器 URL |
+| `yuque_get_toc` | toc | 获取知识库目录 |
+| `yuque_update_toc` | toc | 更新知识库目录 |
+| `yuque_batch_update_toc` | toc | 批量更新目录（createTitle/appendNode/removeNode/moveNode/prependDoc） |
+| `yuque_list_repos` | repo | 获取知识库列表（用户/团队） |
+| `yuque_create_repo` | repo | 创建知识库 |
+| `yuque_get_repo` | repo | 获取知识库详情 |
+| `yuque_update_repo` | repo | 更新知识库 |
+| `yuque_delete_repo` | repo | 删除知识库 |
+| `yuque_batch_get_repos` | repo | 批量获取知识库详情（max 20） |
+| `yuque_copy_repo` | repo | 批量跨库复制（LLM 分类 + 目录重建） |
+| `yuque_export_repo` | repo | 批量导出知识库为 Markdown（按 TOC 目录结构） |
+| `yuque_get_group_statistics` | statistic | 获取团队汇总统计数据 |
+| `yuque_get_member_statistics` | statistic | 获取团队成员统计数据 |
+| `yuque_get_book_statistics` | statistic | 获取团队知识库统计数据 |
+| `yuque_get_doc_statistics` | statistic | 获取团队文档统计数据 |
+| `yuque_list_notes` | note | 获取小记列表 |
+| `yuque_get_note` | note | 获取小记详情 |
+| `yuque_create_note` | note | 创建小记 |
+| `yuque_update_note` | note | 更新小记 |
+| `yuque_list_recycles` | recycle | 列出回收站项目 |
+| `yuque_restore_recycle` | recycle | 恢复回收站项目 |
+| `yuque_destroy_recycle` | recycle | 彻底删除回收站项目 |
+| `yuque_upload_attachment` | upload | 上传文件到语雀 CDN |
+| `yuque_get_board` | board | 获取文档中的画板资源 |
+| `yuque_create_board` | board | 在文档中创建画板资源 |
+| `yuque_update_board` | board | 更新文档中的画板资源 |
+| `yuque_rss_list_sources` | rss | 列出所有可用 RSS 数据源及 feed 类型 |
+| `yuque_rss_fetch` | rss | 抓取 RSS/Atom Feed，解析后去重写入语雀 |
+| `yuque_rss_schedule` | rss | 分析更新频率，生成推荐抓取时间 |
+| `yuque_crawl_fetch` | crawler | 抓取网页原始 HTML |
+| `yuque_crawl_extract` | crawler | CSS 选择器从 HTML 提取内容 |
+| `yuque_crawl_save` | crawler | 去重 + 写入语雀 |
+| `yuque_crawl_schedule` | crawler | 分析爬虫抓取频率，生成推荐抓取时间 |
+| `yuque_get_book_stacks` | mine | 获取知识库分组（书架）列表 |
+| `yuque_get_editor_center` | mine | 获取个人编辑中心全景数据 |
+| `yuque_kv_get` | kv | 读取 KV 命名空间的完整 JSON map（分片合并） |
+| `yuque_kv_set` | kv | 增量设置 key-value，超 250KB 自动分片 |
+| `yuque_kv_delete` | kv | 遍历分片查找并删除 key |
+| `yuque_kv_list` | kv | 列出已配置的 KV 命名空间 |
+
+完整工具文档（含参数和示例）见 [SKILL.md](SKILL.md) 或 [yuque-ai-skills](https://github.com/yehuoshun/yuque-ai-skills)。
 
 ## 与官方对比
 
 | 功能 | 官方 yuque-mcp-server | yuque-ai-mcp |
 |---------|--------------------------|--------------|
-| 工具数 | 19 | **61** |
+| 工具数 | 19 | **63** |
 | 粒度 | 粗粒度 | **细粒度**（1 端点 = 1 工具） |
 | 团队、回收站、上传、统计 | ❌ | ✅ |
 | 版本、Diff、跨库复制 | ❌ | ✅ |
 | 传输模式 | 仅 stdio | **stdio + HTTP SSE** |
 | 配置 | 环境变量 | **config.json**（token + cookie） |
-| Skill 层 | ❌ | ✅ 61 指导 |
+| Skill 层 | ❌ | ✅ 63 指导 |
 
 ## 架构
 
@@ -97,7 +165,7 @@ npm run dev:http       # HTTP SSE 模式 (http://localhost:3099)
 server/src/
 ├── common/              # 公共：config, errors, types, format, validate,
 │                        # api-client, web-request, register-tools, copy/export/schedule,
-│                        # repo-capacity（自动扩容）, toc-cache（24h TTL）, text-utils
+│                        # repo-capacity（自动扩容）, toc-cache（可配置 TTL）, text-utils
 ├── user/ search/ group/ doc/ toc/ repo/ statistic/
 ├── note/ recycle/ upload/ board/ rss/ crawler/ mine/ kv/
 ├── index.ts             # stdio 入口
@@ -126,8 +194,8 @@ server/src/
     },
     "namespaces": {
       "cnblogs": {
-        "book_id": [80197497],
-        "kv_slugs": ["80197550/274164064"],
+        "book_id": [0],
+        "kv_slugs": [],
         "schedule_slugs": []
       }
     }
@@ -136,8 +204,8 @@ server/src/
     "enabled": true,
     "namespaces": {
       "my-source": {
-        "book_id": [80197497],
-        "kv_slugs": ["80197550/274164064"],
+        "book_id": [0],
+        "kv_slugs": [],
         "schedule_slugs": []
       }
     }
@@ -148,6 +216,7 @@ server/src/
 - `book_id`：目标知识库 ID 数组，最后一个为当前活跃仓库。满 5000 篇自动扩容追加。
 - `kv_slugs`：KV 去重分片文档（`{book_id}/{doc_id}` 格式）
 - `schedule_slugs`：定时策略配置文档
+- `toc_cache_ttl_minutes`：TOC 缓存 TTL（分钟），默认 60。调大可减少 API 调用，调小可获取更新鲜的数据。
 
 ## 错误处理
 

package/SKILL.md

@@ -1,6 +1,6 @@
 # yuque-ai-mcp
 
-语雀全功能 MCP Server，61 个工具 / 15 个域。当用户提到「语雀」「yuque」「知识库」「文档」「团队」等关键词时触发。
+语雀全功能 MCP Server，63 个工具 / 15 个域。当用户提到「语雀」「yuque」「知识库」「文档」「团队」等关键词时触发。
 
 ## 触发场景
 
@@ -25,11 +25,12 @@
 | `yuque_get_user` | 获取当前 Token 的用户详情 |
 | `yuque_get_user_groups` | 获取用户所属的团队列表 |
 
-### search（2 工具）
+### search（3 工具）
 | 工具 | 说明 |
 |------|------|
 | `yuque_search` | 通用搜索文档/知识库 |
 | `yuque_rag_search` | RAG 检索增强搜索 + 自动获取文档内容 |
+| `yuque_web_search` | Cookie 态 Web 搜索，返回完整文档对象 + 精确总数 + 高亮摘要 |
 
 ### group（3 工具）
 | 工具 | 说明 |
@@ -38,7 +39,7 @@
 | `yuque_update_group_user` | 变更团队成员角色 |
 | `yuque_delete_group_user` | 删除团队成员 |
 
-### doc（14 工具）
+### doc（15 工具）
 | 工具 | 说明 |
 |------|------|
 | `yuque_list_docs` | 获取知识库文档列表 |
@@ -51,7 +52,8 @@
 | `yuque_get_doc_version_detail` | 获取文档历史版本详情 |
 | `yuque_diff_doc_versions` | 对比两个版本的行级差异 |
 | `yuque_copy_doc` | 单文档跨库复制 |
-| `yuque_export_doc` | 导出单篇文档为 Markdown（含图片下载） |
+| `yuque_export_doc` | 导出单篇文档为 Markdown 文件（不含资源下载，需调 yuque_export_resources） |
+| `yuque_export_resources` | 下载文档中的图片/附件到本地目录，返回 URL→本地路径映射 |
 | `yuque_import_url` | 从网页 URL 导入文档 |
 | `yuque_import_file` | 从本地文件导入文档（direct/upload_assets/embed_assets） |
 | `yuque_embed_url` | 生成文档嵌入阅读器 URL |
@@ -160,19 +162,19 @@
     "enabled": true,
     "namespaces": {
       "cnblogs": {
-        "book_id": 80197497,
-        "kv_slugs": ["80197550/274164064"],
-        "schedule_slugs": ["80278170/274357940"]
+        "book_id": 0,
+        "kv_slugs": [],
+        "schedule_slugs": []
       }
     }
   },
   "crawler": {
     "enabled": true,
     "namespaces": {
-      "cnblogs": {
-        "book_id": 80197497,
-        "kv_slugs": ["80197550/274164064"],
-        "schedule_slugs": ["80278170/274358465"]
+      "my-source": {
+        "book_id": 0,
+        "kv_slugs": [],
+        "schedule_slugs": []
       }
     }
   }

package/dist/board/create-board.js

@@ -5,7 +5,7 @@
  */
 import { apiPost } from "../common/api-client.js";
 import { handleApiCall } from "../common/format.js";
-import { requiredString } from "../common/validate.js";
+import { check, requiredString } from "../common/validate.js";
 export const boardCreate = {
     name: "yuque_create_board",
     description: "Create a board resource (mindmap/flowchart/architecture diagram) in a document. POST /yfm/boards. 详见 references/api/board_api.md",
@@ -22,7 +22,7 @@ export const boardCreate = {
     },
     async handler(args) {
         // @validate
-        const __v = requiredString(args?.dsl, "dsl");
+        const __v = check(requiredString(args?.type, "type"), requiredString(args?.dsl, "dsl"));
         if (__v)
             return __v;
         const docId = args?.doc_id;

package/dist/board/create-board.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-board.js","sourceRoot":"","sources":["../../src/board/create-board.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE,kIAAkI;IAE/I,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2CAA2C,EAAE;YACpF,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+CAA+C,EAAE;YACrF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gEAAgE,EAAE;YACvG,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2DAA2D,EAAE;YACjG,oBAAoB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sEAAsE,EAAE;SAC9H;QACD,QAAQ,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC;KAC1B;IAED,KAAK,CAAC,OAAO,CAAC,IAAI;QAChB,YAAY;QACZ,MAAM,GAAG,GAAG,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;QAC7C,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;QACpB,MAAM,KAAK,GAAG,IAAI,EAAE,MAA4B,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,EAAE,GAAyB,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,EAAE,IAAc,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAa,CAAC;QAChC,MAAM,WAAW,GAAG,IAAI,EAAE,oBAA0C,CAAC;QAErE,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;YACnB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,0CAA0C,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;gBAC1H,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAA4B,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAC/E,IAAI,KAAK;YAAE,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC;QAClC,IAAI,GAAG;YAAE,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC;QAC3B,IAAI,WAAW;YAAE,OAAO,CAAC,oBAAoB,GAAG,WAAW,CAAC;QAE5D,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,aAAa,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;QACnE,OAAO,aAAa,CAAC,IAAI,EAAE,SAAgB,CAAC,CAAC;IAC/C,CAAC;CACF,CAAC"}
+{"version":3,"file":"create-board.js","sourceRoot":"","sources":["../../src/board/create-board.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,CAAC,MAAM,WAAW,GAAY;IAClC,IAAI,EAAE,oBAAoB;IAC1B,WAAW,EAAE,kIAAkI;IAE/I,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ;QACd,UAAU,EAAE;YACV,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2CAA2C,EAAE;YACpF,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,+CAA+C,EAAE;YACrF,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gEAAgE,EAAE;YACvG,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,2DAA2D,EAAE;YACjG,oBAAoB,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,sEAAsE,EAAE;SAC9H;QACD,QAAQ,EAAE,CAAC,MAAM,EAAE,KAAK,CAAC;KAC1B;IAED,KAAK,CAAC,OAAO,CAAC,IAAI;QAChB,YAAY;QACZ,MAAM,GAAG,GAAG,KAAK,CACf,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAClC,cAAc,CAAC,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CACjC,CAAC;QACF,IAAI,GAAG;YAAE,OAAO,GAAG,CAAC;QACpB,MAAM,KAAK,GAAG,IAAI,EAAE,MAA4B,CAAC;QACjD,MAAM,GAAG,GAAG,IAAI,EAAE,GAAyB,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,EAAE,IAAc,CAAC;QAClC,MAAM,GAAG,GAAG,IAAI,EAAE,GAAa,CAAC;QAChC,MAAM,WAAW,GAAG,IAAI,EAAE,oBAA0C,CAAC;QAErE,IAAI,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;YACnB,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,0CAA0C,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;gBAC1H,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;QAED,MAAM,OAAO,GAA4B,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;QAC/E,IAAI,KAAK;YAAE,OAAO,CAAC,MAAM,GAAG,KAAK,CAAC;QAClC,IAAI,GAAG;YAAE,OAAO,CAAC,GAAG,GAAG,GAAG,CAAC;QAC3B,IAAI,WAAW;YAAE,OAAO,CAAC,oBAAoB,GAAG,WAAW,CAAC;QAE5D,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,aAAa,EAAE,OAAO,EAAE,cAAc,CAAC,CAAC;QACnE,OAAO,aAAa,CAAC,IAAI,EAAE,SAAgB,CAAC,CAAC;IAC/C,CAAC;CACF,CAAC"}

package/dist/common/api-client.d.ts

@@ -5,6 +5,8 @@
  * 减少工具文件中的重复代码。
  * 重试策略：指数退避 1s → 2s → 4s，最多 3 次。
  */
+/** 执行 fetch 并自动重试。导出供外部 URL 请求（crawler/rss/import-url）复用 */
+export declare function fetchWithRetry(url: string, options: RequestInit, context: string, attempt?: number, timeoutMs?: number): Promise<Response>;
 /** API 调用结果的类型 guard：检查是否是 MCP error */
 export declare function isErrorResult(result: unknown): result is {
     content: Array<{
@@ -21,6 +23,16 @@ export declare function apiPost(path: string, body: Record<string, unknown>, con
 export declare function apiPut(path: string, body: Record<string, unknown>, context?: string): Promise<unknown>;
 /** DELETE 请求 */
 export declare function apiDelete(path: string, context?: string): Promise<unknown>;
+/** 上传文件到语雀 CDN（FormData，不设 Content-Type 让浏览器自动设 boundary） */
+export declare function apiUpload(path: string, formData: FormData, context?: string): Promise<unknown>;
+/** 下载文件（返回 ArrayBuffer，用于导出文件下载） */
+export declare function apiDownload(path: string, params?: Record<string, string>, context?: string): Promise<ArrayBuffer | {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError: true;
+}>;
 /** POST 请求：支持 404 时 fallback 到备用路径（用于 user/group 端点自动切换） */
 export declare function apiPostWithFallback(path: string, fallbackPath: string, body: Record<string, unknown>, context?: string): Promise<unknown>;
 /** GET 请求：支持 404 时 fallback 到备用路径 */

package/dist/common/api-client.js

@@ -7,11 +7,12 @@
  */
 import { loadConfig } from "./config.js";
 import { handleApiError } from "./errors.js";
-const cfg = loadConfig();
 /** 最大重试次数 */
 const MAX_RETRIES = 3;
 /** 基延迟（ms） */
 const BASE_DELAY = 1000;
+/** 单次请求超时（ms） */
+const REQUEST_TIMEOUT = 30_000;
 /** 是否应该重试：网络异常、429、5xx */
 function shouldRetry(res) {
     if (!res)
@@ -22,17 +23,19 @@ function shouldRetry(res) {
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));
 }
-/** 执行 fetch 并自动重试 */
-async function fetchWithRetry(url, options, context, attempt = 1) {
+/** 执行 fetch 并自动重试。导出供外部 URL 请求（crawler/rss/import-url）复用 */
+export async function fetchWithRetry(url, options, context, attempt = 1, timeoutMs = REQUEST_TIMEOUT) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        const res = await fetch(url, options);
+        const res = await fetch(url, { ...options, signal: controller.signal });
         if (shouldRetry(res) && attempt <= MAX_RETRIES) {
             const delay = BASE_DELAY * Math.pow(2, attempt - 1);
             // 重试日志仅在 DEBUG 环境变量设置时输出
             if (process.env.DEBUG)
                 console.error(`[RETRY] ${context} 第 ${attempt} 次失败 (${res.status})，${delay}ms 后重试`);
             await sleep(delay);
-            return fetchWithRetry(url, options, context, attempt + 1);
+            return fetchWithRetry(url, options, context, attempt + 1, timeoutMs);
         }
         return res;
     }
@@ -42,10 +45,13 @@ async function fetchWithRetry(url, options, context, attempt = 1) {
             if (process.env.DEBUG)
                 console.error(`[RETRY] ${context} 第 ${attempt} 次网络异常，${delay}ms 后重试`);
             await sleep(delay);
-            return fetchWithRetry(url, options, context, attempt + 1);
+            return fetchWithRetry(url, options, context, attempt + 1, timeoutMs);
         }
         throw err;
     }
+    finally {
+        clearTimeout(timer);
+    }
 }
 /** API 调用结果的类型 guard：检查是否是 MCP error */
 export function isErrorResult(result) {
@@ -69,11 +75,11 @@ function networkError(context, err) {
 }
 /** 标准请求头（Token 认证） */
 function authHeaders(extra) {
-    return { "X-Auth-Token": cfg.token, ...extra };
+    return { "X-Auth-Token": loadConfig().token, ...extra };
 }
 /** 构建完整 URL */
 function buildUrl(path, params) {
-    const url = `${cfg.api_base}${path}`;
+    const url = `${loadConfig().api_base}${path}`;
     if (!params || Object.keys(params).length === 0)
         return url;
     const qs = new URLSearchParams(params);
@@ -97,7 +103,7 @@ export async function apiGet(path, params, context) {
 export async function apiPost(path, body, context) {
     const ctx = context ?? `POST ${path}`;
     try {
-        const url = `${cfg.api_base}${path}`;
+        const url = `${loadConfig().api_base}${path}`;
         const res = await fetchWithRetry(url, {
             method: "POST",
             headers: authHeaders({ "Content-Type": "application/json" }),
@@ -115,7 +121,7 @@ export async function apiPost(path, body, context) {
 export async function apiPut(path, body, context) {
     const ctx = context ?? `PUT ${path}`;
     try {
-        const url = `${cfg.api_base}${path}`;
+        const url = `${loadConfig().api_base}${path}`;
         const res = await fetchWithRetry(url, {
             method: "PUT",
             headers: authHeaders({ "Content-Type": "application/json" }),
@@ -133,7 +139,7 @@ export async function apiPut(path, body, context) {
 export async function apiDelete(path, context) {
     const ctx = context ?? `DELETE ${path}`;
     try {
-        const url = `${cfg.api_base}${path}`;
+        const url = `${loadConfig().api_base}${path}`;
         const res = await fetchWithRetry(url, {
             method: "DELETE",
             headers: authHeaders(),
@@ -146,19 +152,50 @@ export async function apiDelete(path, context) {
         return networkError(ctx, err);
     }
 }
+/** 上传文件到语雀 CDN（FormData，不设 Content-Type 让浏览器自动设 boundary） */
+export async function apiUpload(path, formData, context) {
+    const ctx = context ?? `UPLOAD ${path}`;
+    try {
+        const url = `${loadConfig().api_base}${path}`;
+        const res = await fetchWithRetry(url, {
+            method: "POST",
+            headers: authHeaders(),
+            body: formData,
+        }, ctx);
+        if (!res.ok)
+            return handleApiError(res, ctx);
+        return res.json();
+    }
+    catch (err) {
+        return networkError(ctx, err);
+    }
+}
+/** 下载文件（返回 ArrayBuffer，用于导出文件下载） */
+export async function apiDownload(path, params, context) {
+    const ctx = context ?? `DOWNLOAD ${path}`;
+    try {
+        const url = buildUrl(path, params);
+        const res = await fetchWithRetry(url, { headers: authHeaders() }, ctx);
+        if (!res.ok)
+            return handleApiError(res, ctx);
+        return res.arrayBuffer();
+    }
+    catch (err) {
+        return networkError(ctx, err);
+    }
+}
 /** POST 请求：支持 404 时 fallback 到备用路径（用于 user/group 端点自动切换） */
 export async function apiPostWithFallback(path, fallbackPath, body, context) {
     const ctx = context ?? `POST ${path}`;
     try {
-        const cfg = loadConfig();
-        let url = `${cfg.api_base}${path}`;
+        let url = `${loadConfig().api_base}${path}`;
         let res = await fetchWithRetry(url, {
             method: "POST",
             headers: authHeaders({ "Content-Type": "application/json" }),
             body: JSON.stringify(body),
         }, ctx);
         if (res.status === 404) {
-            url = `${cfg.api_base}${fallbackPath}`;
+            url = `${loadConfig().api_base}${fallbackPath}`;
             res = await fetchWithRetry(url, {
                 method: "POST",
                 headers: authHeaders({ "Content-Type": "application/json" }),
@@ -177,14 +214,13 @@ export async function apiPostWithFallback(path, fallbackPath, body, context) {
 export async function apiGetWithFallback(path, fallbackPath, params, context) {
     const ctx = context ?? `GET ${path}`;
     try {
-        const cfg = loadConfig();
         const qs = params && Object.keys(params).length > 0
             ? `?${new URLSearchParams(params)}`
             : "";
-        let url = `${cfg.api_base}${path}${qs}`;
+        let url = `${loadConfig().api_base}${path}${qs}`;
         let res = await fetchWithRetry(url, { headers: authHeaders() }, ctx);
         if (res.status === 404) {
-            url = `${cfg.api_base}${fallbackPath}${qs}`;
+            url = `${loadConfig().api_base}${fallbackPath}${qs}`;
             res = await fetchWithRetry(url, { headers: authHeaders() }, ctx);
         }
         if (!res.ok)