dsh-plugin-dev

开发 DSH 插件标准

本技能是开发 DeepSeek Harness（DSH）插件的唯一标准：它把 DSH 官方文档中分散在教程、参考手册与生成目录里的约定，收敛为可执行的工作流、硬规则与检查清单。DSH 的一切都是插件——模型适配器、工具注册表、会话日志乃至 agent loop 本身——因此按本技能行事，就是在按 DSH 自己的架构方式扩展它。

适用范围

• 仓库内、文件式的 DSH 插件开发：编写插件包、注册 cordis.yml 行、patch overlay、开发工具、接模型、打包安装。
• DSH monorepo 内的 workspace 包开发（packages//）也属本技能（references/workspace-package.md）。
• 本技能不覆盖：会话内动态插件（cordis_define/cordis_run 流）与 agent preset 组合编辑——这两类由各部署的专项技能或官方工具覆盖。

硬规则（任何场景都必须遵守）

1. 接口以生成参考为准。 服务名、公开方法、事件签名、ctx 键均以仓库自动生成的子系统页面与 TypeScript 接口为准；不要凭服务名、示例或旧代码推断完整 API，也不要维护另一份静态清单。
2. 所有贡献都是副作用。 通过 ctx 做的一切注册（事件监听、工具、适配器、ctx.effect）在插件卸载时自动撤销；不要在模块作用域创建进程级/页面级副作用；不返回 disposer 的第三方订阅要主动查清清理机制。
3. waterfall 监听器必须调用 next()。 不调用 next() 即有意短路下游（用于拦截/网关），不是可选项。
4. 失败要响亮。 apply 抛异常则进程终止；配置校验失败则明确报错；schema 应表达自身完备的约束，不要在运行时悄悄吞掉错误。
5. 必需依赖用 inject 声明，可选依赖用 ctx.get() 判空。 不要用 inject 规避 undefined 检查；也不要直接访问未声明注入的 ctx.xxx——未声明的服务经服务解析器求值可能得到 undefined。
6. 配置一律 Schemastery。 导出 interface Config 与同名 Schema，默认值写在 schema 里；不导出普通对象充当 Config；凡不同部署可能改值的参数都必须进配置。
7. 工具 execute 返回规范 JSON 值，不返回内容块。 面向人类的文本放 output.render；部署策略/钩子不要内建进工具体。
8. 模型可见即已记录。 新增任何模型可见输入，都要落在会话日志可重建的机制里（新增持久事件或经 agent.inject()），并有运行时不变式断言。
9. npm 设置面板优先 ctx.connection.rpc。 浏览器半设置面板调主进程方法，优先走 Connection RPC（ctx.connection.rpc.handle + ctx.connection.rpc.call），样板见 references/connection-rpc.md。禁止裸 @Remote、手写 typert manifest、createRequire 挂 harness 源码。完整 Typert generator 产出并经 package.json 导出 ./typert + ./remote、由 ctx.remote.$mount() 消费的路径仍然合法。

标准工作流

场景 A：新建一个插件

1. 确定插件要贡献什么（服务？工具？监听？），用 references/seams.md 的「新行为的归属位置」表选择机制。
2. 创建 src/.ts，导出 name、inject（可选）、apply(ctx, config?)。先写函数形态；要对外提供服务时再换 Service 类形态。
3. 本地开发回路（源码 checkout）：

mkdir -p scratch-plugin/src

# scratch-plugin/cordis.yml —— patch overlay；插件路径必须是绝对路径
- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

pnpm dsh web --patch ./scratch-plugin/cordis.yml   # 打开 http://127.0.0.1:3080