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