语雀知识库 NyaaCaster/dsh-yuque-kb

dsh-yuque-kb — 把语雀文档变成你的外部记忆

对话时自动检索你的语雀文档并注入相关内容 —— 你不需要记得自己写过什么，也不需要点名任何插件。

dsh-yuque-kb 把你在语雀（yuque.com）里的个人知识库接入 DeepSeek Harness：当对话内容与你的语雀文档相关时，插件会在当前回合自动检索，并把相关文档片段送进对话（消息标注 [yuque-kb-auto]，回答自带出处「语雀：《标题》」）；你也可以随时显式点名搜索、阅读某篇文档。

| 能力 | 带来的变化 |
| 被动注入（外部记忆） | 用户不需要知道/想起自己有对应文档 —— 对话内容触发关键词即自动检索并注入片段，回答可引用并标出处 |
| 树形目录管理 | 设置面板「语雀知识库」页展示全部知识库与文档层级，每个库/每篇文档独立开关，禁用即刻生效 |
| 目录快照零额度检索 | kb_search 按标题/路径检索本地目录快照（不消耗语雀 API 额度） |
| 在线全文兜底 | kb_search_remote 云端全文搜索 + kb_read 在线分块读正文 —— 永远最新，未同步的新文档也能读到 |
| 安全合规 | 只读语雀、增量目录同步约 17 个请求、正文按需在线读取 —— 实测规避语雀短窗风控 |

安装

[!NOTE]
使用前请确保已安装 DeepSeek Harness。

标准方式：从 npm 安装到 web profile
dsh plugin --profile web add dsh-yuque-kb

检查组合配置无误后，重启 dsh web 并在浏览器硬刷新（Ctrl+Shift+R）：

dsh --profile web --dump-config # 应看到 dsh-yuque-kb 层

从源码开发时也可以直接链接本地目录、或安装打包产物：

dsh plugin --profile web add link:/path/to/dsh-yuque-kb # 本地开发目录
dsh plugin --profile web add ./dsh-yuque-kb-0.1.0.tgz # tarball

第一步：获取语雀 Token

语雀开放 API 使用个人 Token 鉴权：

1. 登录语雀（电脑网页版），点击右上角头像 → 个人设置（或直接打开 https://www.yuque.com/settings/tokens）
2. 在「Token」页面点击生成 Token，复制生成的一串字符
3. Token 是机密凭据，只粘贴到下面设置的输入框，不要发到任何聊天/仓库里

[!IMPORTANT]
个人 Token 属于语雀超级会员权益；如果你的账号无法生成 Token，需要先开通超级会员。
Token 代表你账号在该知识库上的全部权限（本插件只做只读操作，但 Token 本身请妥善保管）。

第二步：在设置页配置并连接

1. 打开 dsh web 设置面板，左侧导航点击 「语雀知识库」（在「插件/模型」等条目的附近，以你安装时的排序为准）
2. 在连接区：把 Token 粘贴进 Access Token 输入框 → 点击保存（输入框是密码框，保存后不显示明文，只会显示「已配置」徽章）
3. 点击 连接测试 —— 成功后会显示：连接成功：你的语雀昵称（登录名），知识库 N 个；失败会给出原因（Token 无效 / 语雀临时限流等）

第三步：同步目录并开始对话

1. 在同步状态区点击 立即同步（首次约十几秒：拉取全部知识库的目录树与文档清单；之后每次同步只做增量，通常几秒完成）
2. 同步区会显示：上次同步时间、语雀剩余额度、已索引文档总数；同步中显示进度条与当前库
3. 回到聊天窗口，正常提问即可 —— 涉及你的语雀文档内容时，插件会自动注入相关片段，例如：

我想知道 qinyapi 的兑换码各档性价比

模型会先收到自动检索注入的文档片段（标注 [yuque-kb-auto] 与出处），据此作答；若片段不足以回答，模型会继续调用 kb_read 读完整文档。

设置页使用说明（界面一览）

「语雀知识库」设置页自上而下四个区域：

| 区域 | 元素 | 说明 |
| ① 连接区 | Access Token 输入框 + 保存；连接测试；刷新目录 | Token 已配置时显示绿色「已配置」徽章；刷新目录 = 从语雀重新拉取最新目录树 |
| ② 同步状态行 | 上次同步时间 / 剩余额度 / 已索引文档数；立即同步 | 剩余额度 = 语雀每小时 5000 次的共享配额剩余 |
| ③ 同步进度条 | 正在同步的库 + 完成数 + 错误数 | 仅同步进行中显示 |
| ④ 树形目录 | 工具条：全部展开 / 全部折叠 / 按名称过滤输入框；每个知识库为一行（开关 + 文档数），展开后按分组显示文档（每篇也有开关） | 开关即时生效：关掉某库/某文档后，本地检索、云端检索、被动注入都不会再命中它（索引保留，重新打开立即恢复） |

对话中使用方式

被动使用（推荐，零学习成本）

插件在每个对话回合自动判断：对话内容与你的语雀文档相关时，自动检索并注入文档片段。不需要任何特殊说法。注入内容以 [yuque-kb-auto] 开头、带文档标题与来源，模型会引用并注明出处。

显式使用（按需）

| 说法示例 | 触发行为 |
| 「在语雀里搜一下 关键词」 | kb_search 本地目录检索（标题/路径，零额度） |
| 「搜索语雀云端：关键词」 | kb_search_remote 语雀云端全文搜索（消耗少量额度，能搜到未同步的新文档） |
| 「读一下语雀里《标题》这篇文档」 | kb_read 在线读取正文（分块返回，消耗少量额度） |
| 「先同步一下语雀目录」 | kb_sync 增量同步目录（约 17 个请求） |

使用边界

- 本地只存目录快照，不存正文：kb_read / kb_search_remote 为在线读取，每次消耗语雀 API 额度（单篇 1-2 个请求，日常使用远低于 5000/小时限额）
- 语雀风控：语雀对短时间内大量连续请求有风控（一次约 25 连发即触发、数小时不解）。插件已按只读、节流、增量、按需在线的设计规避；如果短时间内反复大量同步/阅读，仍可能短暂触发，此时界面会提示限流，等待数小时即可恢复
- 开关语义：禁用 = 对该库/文档的全部检索（本地 + 云端 + 被动注入）不再命中，立即生效；启用后无需重新同步
- 团队知识库暂不支持（个人账号 + 个人知识库）；图片以 URL 引用保留

高级配置（可选）

默认配置即可直接使用。以下键可在 profile 的 cordis.patch.yml 或设置页配置（多数键在设置页可见）：

- id: yuque-kb
config:
autoInject: true # 被动注入总开关（默认开） autoInjectRemote: true # 本地未命中时是否回退语雀云端搜索（每次探测 1 请求） autoInjectIntervalMs: 30000 # 同一会话内被动注入的最小间隔（毫秒） syncOnStartup: false # 启动时自动增量同步目录 rateLimitPerSec: 3 # 语雀请求节流（每秒） searchLimit: 8 # kb_search 默认返回条数

常见问题

- 连接测试报 rate-limited: Too Many Requests：语雀当前对该账号处于临时风控（短时间请求过多触发），等待数小时会自动解除；期间勿反复点击测试
- 自动注入没有出现：确保已同步目录（立即同步）、该文档未被禁用、且消息长度/间隔满足触发条件；也可以直接点名方式验证（见上表）
- 同步后树里文档数是旧的：点「刷新目录」从语雀重新拉取最新清单（不消耗正文额度）
- 想彻底关闭该插件：设置页 enabled: false 或 dsh plugin --profile web remove dsh-yuque-kb

开发者信息

- 构建：pnpm build（tsc + tsdown，宿主 ESM + 浏览器 bundle）；测试：pnpm test（当前 100/100）
- 发布：npm publish（需要 npmjs 登录与 2FA/恢复码）

许可证

AGPL-3.0