插件脚手架示例 xiaoziwenjie-code/dsh-plugin-demo-tool

dsh-plugin-demo-tool

由 create-dsh-plugin 生成的 DeepSeek Harness 工具插件。
由 create-dsh-plugin 生成的 DeepSeek Harness 工具插件。

通过 defineTool() 注册 xiaoziwenjie_code_demo_tool 工具。

快速开始 / 快速开始

pnpm install
pnpm run build # tsc → dist/index.js (pure ESM)

From the PARENT directory, install into a profile and boot:
dsh plugin --profile my-profile add ./dsh-plugin-demo-tool
dsh --profile my-profile # watch for: [xiaoziwenjie-code-demo-tool] registered "xiaoziwenjie_code_demo_tool" — listed=true

注意：dsh plugin add <dir> 的相对路径锚定「调用目录」，请在插件父目录执行。

无 key 验证 / 无 key 验证

dsh --profile my-profile --dump-config | grep xiaoziwenjie-code-demo-tool # 配置层含本行
dsh plugin --profile headless add ./dsh-plugin-demo-tool
dsh --profile headless "run a probe" # session/event 触发；模型调用会 MISSING_CREDENTIAL

依赖锁定 / 依赖锁定

- @deepseek-ai/dsh-tools：0.2.1-rc.2（精确锁定 —— 属于 next tag 线；npm 的 latest 已过期）。
- @deepseek-ai/cordis：^4.0.5（peerDependency —— 由宿主提供；代码里只引类型）。

主题与皮肤兼容 / 主题与皮肤兼容

本插件没有自有宿主 UI（工具结果走官方聊天面渲染），天然兼容。若以后加面板，请遵循 DSH Web 样式契约：颜色只用 --dsw-alias- 令牌，并输出 data-dsh-plugin / data-dsh-part / data-dsh-surface 语义属性（dsh-web skin-center 契约）。

本插件没有自有宿主 UI（工具结果走官方聊天面渲染），天然兼容。若以后加面板：颜色只用 --dsw-alias- 令牌，并输出 data-dsh- 语义属性（见上方契约链接）。

坑（从真实 spike 提炼，防呆）/ 坑（从真实 spike 提炼，防呆）

1. Node 版本：DSH 要求 Node ^22.19.0 || >=24.0.0。旧版本（如 v22.17）只告警 EBADENGINE，不阻断，但建议升级。
- Node 版本：DSH 要求 ^22.19.0 || >=24.0.0。旧版本（如 v22.17）只告警 EBADENGINE，不阻断，但建议升级。

2. npm dist-tag 坑（最大）：@deepseek-ai/dsh-tools 的 latest 是过期的 0.0.1-rc.1，正确版本在 next tag（0.1.0-rc.x）。本脚手架已锁 next 版本，勿再手动 npm i @deepseek-ai/dsh-tools 覆盖。
- npm dist-tag 坑（最大）：@deepseek-ai/dsh-tools 的 latest 是过期的 0.0.1-rc.1，正确版本在 next tag。本脚手架已锁 next 版本，勿再手动 npm i 覆盖。

3. 版本线对齐：所有 @deepseek-ai/dsh- 包统一用同一 0.1.0-rc.x 线，避免 pnpm 装两份模块。
- 版本线对齐：所有 @deepseek-ai/dsh-* 包统一用同一 0.1.0-rc.x 线，避免 pnpm 装两份模块。

4. @deepseek-ai/cordis 是 peerDependency：只 import type { Context }（编译期擦除）。运行时 ctx 由宿主传入 —— 绝不要在运行时 import cordis 的值。
- @deepseek-ai/cordis 是 peerDep：只 import type（编译期擦除），运行时 ctx 由宿主传入。
5. 纯 ESM：package.json 必须设置 "type": "module"；构建时用 module: esnext + moduleResolution: bundler，保留 bare specifier。
- 纯 ESM：package.json 必须 "type": "module"；tsc 用 module:esnext + moduleResolution:bundler 保留 bare specifier。

6. dsh plugin add <dir> 把相对路径锚定到调用目录 —— 要在插件的父目录执行，不要在插件内部执行。
- dsh plugin add <dir> 的相对路径锚定调用目录——要在插件的父目录执行。

7. bundle 的 cordis.patch.yml 里，name 是包名（通过 node_modules / $DSH_HOME/profiles/node_modules 解析），不是相对路径。
- bundle 的 cordis.patch.yml 里 name 用包名（走 node_modules 解析），不要用相对路径。

8. 注册即 effect：ctx.tools.register() / ctx.on() 在卸载时自动清理。你自己的资源（timer/连接）要包进 ctx.effect(() => { acquire; return cleanup })。
- 注册是 effect：ctx.tools.register()/ctx.on() 卸载自动清理；自己的资源（timer/连接）要包 ctx.effect(() => {…; return cleanup})。

9. 加载顺序看服务依赖，不看文件顺序：export const inject = ['tools'] 让插件等到 ctx.tools 就绪再加载。
- 加载顺序靠服务依赖（inject），不靠文件顺序。

10. 完整端到端（模型真正调用你的工具）需要 DEEPSEEK_API_KEY；没有它，--verify 只能证明加载/列出/事件，模型调用会以 MISSING_CREDENTIAL 失败。
- 端到端（模型真正调工具）需 DEEPSEEK_API_KEY；无 key 时 --verify 只能证明加载/列出/事件，模型调用会 MISSING_CREDENTIAL。