一、先理解架构：DSH = Cordis 插件系统 + 补丁式组合

DSH 不是单体应用，而是构建在 Cordis 插件框架（@deepseek-ai/cordis，Koishi 系）之上的分层插件树。

工具目录中几乎所有可见能力（run_code、pwsh、todo_write、subagent、workflow…）都是一个插件包，例如 dsh-tool-todo、dsh-tool-pwsh——这就是你插件的参照物。

二、插件的标准形态（源码确认的约定）

第一方插件使用 命名空间导出（无默认导出，docs/postmortem/0001 规定默认导出会丢失 inject）：

三条硬性规范（注册表强制校验）：

1. output: { schema, render } 必填——没有输出声明注册直接失败；
2. execute 只能返回输出 schema 声明的无损 JSON，通过 exec.signal 协作停止；
3. Config、name、inject、apply 四个导出缺一不可（Config 可省，但专业插件应带配置）。

三、五类插件（按你的需求选型）

工具自带 UI 呈现用 presentCall/presentResult 返回 card 意图（generic/terminal/read/diff/search/web），UI 无需按工具名写特例。

四、标准开发流程（六步）

1. 初始化工程

2. 写插件（见上文模板）

3. 构建

4. 本地安装到 profile（两种方式）

5. 注册进加载树——编辑~/.dsh/profiles/web/cordis.patch.yml

要点：id 是 patch 寻址键（后续可用 - id: my-plugin + config: 覆盖）；name 必须是 profile 依赖里真实存在的模块说明符。文件热重载（watchUserPatches），改了立即生效，无需重启——但首次安装包后需要重启 dsh web。

6. 验证

五、"专业标准完整"插件清单（对标dsh-tool-todo/dsh-tool-pwsh）

源码里第一方工具普遍具备以下工程素养，照做即是"专业标准"：

1. 名称纪律：包名 dsh-*（第三方常 dsh-* 或 dsh-plugin-*），插件 name kebab-case 唯一，工具名 snake_case 且描述首句就是完整指令（模型看到的第一句决定它会不会用）。
2. Config 带默认值 + 部署语义：z.object({ allowParallel: z.boolean().default(true) })——配置是部署者政策，不是插件内部细节；配置变更记录进描述（如 todo 的并行策略会改写工具描述）。
3. 类型化参数与严格 schema：defineTool 参数用 ParameterSchemaSpec；additionalProperties: false 封闭对象，让模型写错即失败（INVALID_ARGS），而不是静默吞掉。
4. 规范化输出契约：输出 { schema, render, presentationMeta? }；值（机器消费）与呈现（模型消费）分离；render 是纯函数，UI 流式回放时会反复调用。
5. 错误即结果：可预期的失败返回 { isError: true, error: { message, info } } 而不是抛异常；基础设施失败才抛 HarnessError（带 name/code）。
6. 协作取消：execute(args, exec) 必读 exec.signal，把 signal 透传给底层（readFile(path, { signal })、fetch(url, { signal })），绝不在已启动的 Promise 未结算时提前返回。
7. 并发安全声明：可并发的工具实现 isConcurrencySafe(args) 返回 true；共享状态竞态必须可交换，否则拒绝。
8. 状态写入会话日志而非内存：持久状态用 exec.agent.session.append('my/write', data)（事件溯源），重放/UI 都从事件渲染（todo 的 todos 投影就是这么做的）。
9. 文档与双语文案：README.md + README.zh.md（含配置表、公开 API、扩展点、模型体验、KV Cache 影响、已知限制）。
10. 测试与门禁：schema 验证、执行器单测、verify 门禁（如 verify-cordis-catalog 防止契约漂移）。

六、调试与快速原型三板斧

• 动态插件（零安装验证）：会话里让模型执行 cordis_define（提交 host 半 + 可选浏览器半）→ cordis_run 沙箱求值 → cordis_stop/cordis_undefine。原型验证用这个，正式落地再走上面六步。注意：动态包不跨重启、不写文件、不会自动变成正式插件。
• 配置排障：dsh web --dump-config 看最终组合树；--dump-default-config 看 bundle 层（不含你的 patch）。
• HMR：改 cordis.patch.yml 秒级生效；改插件源码需重新 build + 依赖引用为 file: 时自动跟随。

七、安全边界（必须知道，否则插件不合格）

• 沙箱：文件操作经 dsh-fs-sandbox（当前 workspace-write）；命令经 dsh-bash-sandbox/dsh-pwsh-sandbox。插件不能绕过，只能走 sandbox_permissions 升级通道（需用户批准）。
• 审批 seam：ctx.get('approval')（ask/deny/allow）；未部署时 ask 退化为拒绝——插件必须把拒绝当正常路径处理。
• 作用域：普通上下文注册 = 全局；agent.ctx 注册 = 仅该 agent 并遮蔽同名全局。ctx.tools.restrict() 是可见性组合，不是权限边界。
• 内容替换不是保密边界：编程消费方不能收到的值，要阻止或替换（post-execute），不能指望 finalizeContent 兜底。

八、实践路径

如果你的环境已就绪（dsh CLI、web profile、cordis_inspect 自省工具都在）。最省事的上手路线：

1. 用 cordis_define/cordis_run 在会话里验证一个 30 行的工具原型（比如"读 Excel 并统计"）；
2. 原型通过后，按第四节的六步把它工程化成一个 dsh-<name> npm 包，file: 依赖挂进 ~/.dsh/profiles/web；
3. 在 cordis.patch.yml 插入一行即可被当前 Web 会话加载。