dsh-plugin-demo-tool

dsh-plugin-demo-tool

A DeepSeek Harness tool plugin generated by create-dsh-plugin. 由 create-dsh-plugin 生成的 DeepSeek Harness 工具插件。

Registers the xiaoziwenjie_code_demo_tool tool via defineTool().

Quick start / 快速开始

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> 的相对路径锚定「调用目录」，请在插件父目录执行。

Verify without an API 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

Dependencies pinned / 依赖锁定

• @deepseek-ai/dsh-tools: 0.2.1-rc.2 (exact — the next-tag line; npm latest is stale).
• @deepseek-ai/cordis: ^4.0.5 (peerDependency — host provides it; types-only in code).

Theme & Skin Compatibility / 主题与皮肤兼容

This plugin has no host-rendered UI of its own (tool results render through the official chat surface), so it is compatible by construction. If you later add a panel, follow the DSH Web styling contract: colors via --dsw-alias-* tokens only, and emit data-dsh-plugin / data-dsh-part / data-dsh-surface semantic attributes (dsh-web skin-center contracts).

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

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

1. Node version: DSH requires Node ^22.19.0 || >=24.0.0. Older Node (e.g. v22.17) only warns EBADENGINE but may hit runtime issues — upgrade if you can.

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

2. npm dist-tag trap (the big one): @deepseek-ai/dsh-tools latest is a STALE 0.0.1-rc.1; the real line is under the next tag (0.1.0-rc.x). This scaffold pins the next-tag version for you — never npm i @deepseek-ai/dsh-tools over it.

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

3. Version-line alignment: keep every @deepseek-ai/dsh-* package on the same 0.1.0-rc.x line so pnpm does not install two module copies.

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

4. @deepseek-ai/cordis is a peerDependency: import only type { Context } (erased at compile). At runtime the host hands you ctx — never import cordis values at runtime.

   • @deepseek-ai/cordis 是 peerDep：只 import type（编译期擦除），运行时 ctx 由宿主传入。

5. Pure ESM: package.json must set "type": "module"; build with module: esnext + moduleResolution: bundler to keep bare specifiers.

   • 纯 ESM：package.json 必须 "type": "module"；tsc 用 module:esnext + moduleResolution:bundler 保留 bare specifier。

6. dsh plugin add <dir> anchors relative paths to the INVOKING directory — run it from the parent directory, not from inside the plugin.

   • dsh plugin add 的相对路径锚定调用目录——要在插件的父目录执行。

7. In the bundle cordis.patch.yml, name is a package name (resolved via node_modules / $DSH_HOME/profiles/node_modules), not a relative path.

   • bundle 的 cordis.patch.yml 里 name 用包名（走 node_modules 解析），不要用相对路径。

8. Registrations are effects: ctx.tools.register() / ctx.on() auto-dispose on unload. Wrap your OWN resources (timers/connections) in ctx.effect(() => { acquire; return cleanup }).

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

9. Load order = service dependencies, never file order: export const inject = ['tools'] makes the plugin wait until ctx.tools is ready.

   • 加载顺序靠服务依赖（inject），不靠文件顺序。

10. Full end-to-end (model actually calls your tool) needs DEEPSEEK_API_KEY; without it --verify proves load/list/event, and the model call fails with MISSING_CREDENTIAL.

• 端到端（模型真正调工具）需 DEEPSEEK_API_KEY；无 key 时 --verify 只能证明加载/列出/事件，模型调用会 MISSING_CREDENTIAL。