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

4. 验证加载与卸载：启动日志出现、停用时资源确实清理（references/plugin-anatomy.md）。

场景 B：给模型加一个工具

1. inject: ['tools']，用 defineTool 定义（name/description/parameters/output/execute）。
2. 按 references/tools.md 的 execute 约定实现：schema DSL 声明参数与输出、execute 返回规范值、遵守 exec.signal、可选 presentationMeta/UI 卡片。
3. 需要策略时挂 tools/* 事件（pre-execute/guard/execute/post-execute/result），不要把策略写死在工具体里（权限门禁示例见 references/plugin-forms.md）。
4. 重启后让模型实际调用验证。

场景 C：可替换能力（多种提供方）

1. 按 references/three-roles.md 拆 Definition / Provider / Consumer 三个包（按需合并角色，不要预防性拆分）。
2. Definition 拥有 Request/Result 类型与抽象 Service；Provider 实现；Consumer 暴露为工具或服务消费方。
3. 在 cordis.yml 只列 Provider 与 Consumer 行；换提供方只换一行。

场景 D：接入新的模型提供方

1. 继承 LlmAdapter 实现 stream()，按 StreamChunk 协议输出分片；错误用带稳定 code 的 LlmError（或在带内以 finish { kind: 'error' | 'aborted' } 结束）；每个 HTTP 请求合并 attributionHeaders() 并传递 signal。
2. ctx.llm.registerAdapter([''], adapter)；可选覆写 resolveModel()/listModels()。
3. 在组合中配置 agent-loop 的 provider/model 验证。详见 references/llm-adapter.md（含 7 条协议义务）。

场景 E：打包与安装交付

1. 建组合包：package.json 声明 dsh.bundle（指向 cordis.patch.yml），patch 行按包名引用插件；仅供 import 的库包不声明 dsh.bundle。
2. 安装：dsh plugin --profile add ；先 dsh --profile --dump-config 验证层，再启动。
3. 记住层顺序与整行替换语义（references/packaging.md）。

场景 F：在 DSH monorepo 内新建包

按 references/workspace-package.md 的逐文件清单执行：创建包（package.json 不变式/tsconfig/src/README）→ 根配置注册 → 包拓扑与命名（角色词表）→ README Model Experience 结构 → 验证命令。

决策速查

完成前检查清单

• 接口查过生成参考（服务/事件/ctx 键均以生成为准），没有凭名字猜 API。
• 所有注册走 ctx（事件/工具/适配器/effect），卸载可清理；顺序敏感的清理放在同一个 ctx.effect 里。
• 必需依赖注入声明正确；可选依赖有 undefined 处理。
• 有配置的插件：Config 用 Schemastery，默认值进 schema，无效配置在加载时响亮失败。
• 有工具：execute 返回规范 JSON 值；render 负责人类可读；策略走 tools/* 事件；遵守 exec.signal；并发安全声明了 isConcurrencySafe（未声明 → exclusive）。
• 有 waterfall 监听：调用并返回 next()（除非有意短路）。
• 有 LLM 适配器：StreamChunk 协议完整（块配对、index 按首次出现、usage 在 finish 前、arguments 全程原始 JSON 字符串）；错误走两条合法路径之一；不支持的字段抛 UNSUPPORTED；需要原生回放时发 finish.replayState；传了 attributionHeaders 与 signal。
• 组合行与层序正确；新增行在 --dump-config 中可见；HMR/重启后无残留注册。
• 若模型可见内容变化：落在日志可重建的机制内。
• 浏览器半设置面板：优先 ctx.connection.rpc.handle/call；禁止裸 @Remote、手写 typert manifest、createRequire 挂 harness 源码；完整 Typert generator + ./typert + ./remote 产物仍合法。
• 新建 workspace 包：package.json 不变式、恰一个 aggregate、命名符合角色词表、README 有 Model Experience 结构，且 constraints/typecheck/lint/build/hygiene 全绿。

参考文件（按需加载，不要一次全读）

完整索引与「何时读」对照表见 references/README.md。

• references/plugin-anatomy.md —— 写/改插件、处理生命周期或 HMR 时读
• references/services.md —— 定义或消费服务、注入依赖时读
• references/events.md —— 用事件通信、监听扩展点时读
• references/config.md —— 让插件可配置时读
• references/context-api.md —— 用作用域、服务存储或 Fiber API 时读
• references/three-roles.md —— 拆分可替换能力时读
• references/tools.md —— 开发模型工具时读
• references/llm-adapter.md —— 接入新模型提供方时读
• references/plugin-forms.md —— 写钩子/UI/协议桥插件时读
• references/connection-rpc.md —— npm 设置面板要调主进程方法时读；遇到裸 @Remote / 手写 manifest / createRequire 源码桥时也读
• references/packaging.md —— 打包安装、交付 plugin 时读
• references/workspace-package.md —— 在 monorepo 内新建包时读
• references/seams.md —— 查内置服务、归属位置或架构映射时读

验证

• 格式自检：name 为 kebab-case 且与目录名一致；description 非空且简洁（本技能控制在 500 字符内）；正文用标准 Markdown；所有引用的 references 文件真实存在。
• 目录命名：本技能名（name）为 dsh-plugin-dev，与托管仓库名 dsh-plugin-dev-skills 不同——克隆/解压后必须把文件夹命名为 dsh-plugin-dev（与 name 一致），否则按目录名寻址的加载器可能发现不了本技能。
• 有 skills-ref CLI 的环境可执行：skills-ref validate ./dsh-plugin-dev
• 触发回归：修改 description 后运行 evals/trigger-queries.json 评测集（方法见仓库 evals/README.md）。
• 行为验证：按场景 A 走通一个最小插件（加载日志 + 卸载清理），再按场景 B 走通一个 greet 工具。