@sonor-liang/dsh-docs-center-client

English | 中文

DeepSeek Harness 插件:把独立 skill docs-center-client(docs-center 的三方 Agent 客户端 CLI)暴露成 ctx.skills 上的 bundled skill,并附带一段 system prompt 引导,让任何 profile 中的会话都能通过自然语言驱动它。

仅 Host 端(无浏览器端):通过单条 cordis.patch.yml insert 挂入宿主进程,注册一个 docs-center-client skill provider(rank BUNDLED_SKILL_RANK = 600),并改写 systemPrompt 提醒 agent 该 skill 的存在和 CLI 调用方式。

用户视角拿到的能力

1. 模型侧 catalog 多一条 skill:docs-center-client。agent 在请求涉及搜索/上传/管理/分享文档时,会调用 skill(name="docs-center-client") 加载完整指引。
2. 内置 Python CLI 位于 <plugin>/skills/docs-center-client/scripts/docs_center_client.py。每次 CLI 调用都走宿主的 bash/bash-persistent 工具,自动继承当前 profile 的 sandbox 与审批策略。Agent 在加载 skill 后从 <skill_resources> 段读到具体路径(Base directory for this skill: …)。
3. Web GUI 插件设置页(docs-center-client 命名空间)暴露 announceToAgent / exposeSettings 两个开关。真正的 API Key 由 CLI 从 ~/.docs-center-client/keys.json(项目 md5 → default)读取,缺失时交互式提示人类粘贴 ak_ 落盘;CLI 不接受 --api-key、不读 DOCS_CENTER_AGENT_KEY 环境变量,插件也不存储 Key。
4. 一段 system prompt 段落(plugin:docs-center-client,order 240)告诉模型:本插件存在、Key 优先级、限流/分享过期规则。

插件不做的事

• 不存 API Key、不接受注入。Agent 应当只持有"人类用户在 docs-center 前端 /my/agents 自助签发、写进本地 ~/.docs-center-client/keys.json"的 Key。CLI 严格从该 store(项目 md5 → default)读取,缺失时交互式提示人类粘贴;没有 --api-key 参数,也不读 DOCS_CENTER_AGENT_KEY 环境变量。Web Settings 页面只用于插件级别开关。
• 不注册新的 model-facing tool。skill body 直接告诉 agent 怎么调用 Python CLI。所有交互走宿主已有的 bash/bash-persistent 工具,审计与权限一致;避免另起一套 API 客户端。
• 不会自动扫描插件 skills/ 目录之外的文件。skills/docs-center-client/SKILL.md 是默认唯一入口,Config.skillDir 可以覆盖供高级用户和测试使用。

作为 bundle 装入 profile

# 本地 checkout
dsh plugin --profile <name> add link:/path/to/dsh-docs-center-client

# 或发布到 npm 后
dsh plugin --profile <name> add @sonor-liang/dsh-docs-center-client

dsh plugin 会把包 pnpm 装到 profile 的 node_modules 并加入 dsh.profile.bundles。然后 dsh --profile <name>(或 web profile 直接 dsh web)启动即可:模型侧 catalog 出现 docs-center-client,全局 system prompt 出现本插件的引导段落。

Config

字段	默认值	含义
announceToAgent	true	是否把"本机已安装 dsh-docs-center-client"引导段落写入全局 system prompt。
skillDir	<pkg>/skills	覆盖内置 skills 根;用于 fork / 测试。
exposeSettings	true	是否在 Web GUI 插件设置页暴露本插件的设置区。

三者都可以在 Web 插件设置页面上修改;loader 默认 schema 在 settings section 为空时生效。

agent 如何使用 skill

挂载后,模型会在初始 catalog 看到 docs-center-client。标准流程:

1. agent 读 catalog,发现 docs-center-client 匹配用户请求,调用 skill 工具 name="docs-center-client"。
2. DSH skill registry 加载 <pkg>/skills/docs-center-client/SKILL.md,渲染为 <skill_content>(body 与原 docs-center-client SKILL.md 完全一致)。
3. agent 执行 python3 <pkg>/skills/docs-center-client/scripts/docs_center_client.py search "…"(或 upload / doc / share)—— 四个子命令的参数与输出约定在加载后的 skill body 中已经讲清楚,本 README 不重复。

skill body 是子命令与输出约定的唯一权威来源;刻意不在 README 里复述,以免漂移。

架构要点

• lib/index.js 导出一个 Cordis plugin 行(name、inject、Config、apply)。apply(ctx, config) 在 ctx.skills 注册一个 provider,在 ctx.systemPrompt 注册一段 section(可选前置 settings section)。
• skill provider 扫描内置 skills/<name>/SKILL.md 和 skills/<name>.md(一层深度,与 @deepseek-ai/dsh-skill-filesystem 的发现形态对齐),用同样的 YAML frontmatter 解析,把发现的 skill 以 rank BUNDLED_SKILL_RANK 暴露出去。
• provider 与宿主 filesystem provider 故意分开:本插件只暴露自己的内置 skill,不会污染宿主文件系统 skill 根,后续若新增 skill 也只挂在本 provider 下。
• 内置 SKILL.md 给 description 加了引号,因为 [email protected](宿主 @deepseek-ai/dsh-skill-filesystem 解析到的版本)会把 https://… 里的 : 当成 nested mapping。这与宿主 provider 的处理完全一致——双方用同一个解析器。

测试

node test/unit.mjs

17 个 in-process 用例,不需要 dsh 宿主。覆盖范围:

• frontmatter 解析(规范、畸形、legacy key、500 字符 cap)
• 发现(discoverSkills 返回 { candidates, complete },I/O / 解析失败时标 incomplete)
• provider 生命周期(list()、get()、abort signal 转发、文件缺失)
• apply() 副作用(provider 注册、system-prompt section 安装 + effect 驱动的 teardown、announceToAgent: false 抑制)
• metadata 白名单(只放过 owner / version / tier / category)
• 真实内置 skills/docs-center-client/SKILL.md 经过 parseFrontmatter 和 discoverSkills 完整 round-trip

从旧包名迁移

如果你之前装过 @sonor/dsh-docs-center-client(已废弃),先卸载旧包再装新包:

dsh plugin --profile <name> remove @sonor/dsh-docs-center-client
# 确认 node_modules 里的旧 symlink 也清掉
rm -rf ~/.dsh/profiles/<name>/node_modules/@sonor
# 装新包
dsh plugin --profile <name> add @sonor-liang/dsh-docs-center-client
# 验证只有一条记录
dsh web --dump-config | grep -A3 "docs-center-client"

漏掉旧包会导致 duplicate loader entry id: docs-center-client 错误。

inotify watcher 上限(dsh 全局问题)

dsh web 依赖 chokidar 文件监听。如果系统 fs.inotify.max_user_instances 太低,会触发 ENOSPC:

# 立即生效
sudo sysctl -w fs.inotify.max_user_watches=524288
sudo sysctl -w fs.inotify.max_user_instances=8192

# 持久化(重启不丢)
sudo tee /etc/sysctl.d/99-inotify.conf > /dev/null <<'EOF'
fs.inotify.max_user_watches=524288
fs.inotify.max_user_instances=8192
EOF
sudo sysctl -p /etc/sysctl.d/99-inotify.conf

License

MIT,见 LICENSE。