dsh-yuque-kb

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

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

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

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

区域	元素	说明
① 连接区	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 引用保留

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

插件在每个对话回合自动判断：对话内容与你的语雀文档相关时，自动检索并注入文档片段。不需要任何特殊说法。注入内容以 [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 默认返回条数