Dsh Plugin Development

DSH 插件开发

版本适用范围：本文主体保留 2026-08-13 的历史模板，不代表当前 Harness 的 API。在 AgentTeams 仓库内处理升级时，先读项目根目录 skills/README.md，再使用项目内 dsh-upgrade-audit、plugin-upgrade 和 plugin-test。独立安装此 skill 时不要求这些同伴文件，仍按 §2 取证。下文的 dsh-client-runtime、conversationEvents 等旧接口须按目标精确 tag 与 npm 产物重新核实，不能直接用于 Alpha.2 或后续版本。

这是正式版导向的执行清单。先判断运行面，再选择官方模板，实现后必须从真实组合和用户安装路径验证。不要把某个项目的偶然实现当成框架契约。

1. 开始前

1. 用 pwd、git rev-parse --show-toplevel、git status --short --branch 确认项目与用户改动。
2. 读取 package.json、cordis.patch.yml、tsconfig*.json、构建配置、相关 src/ 和测试。
3. 不覆盖用户改动，不操作用户明确排除的 profile、端口或实例。
4. 判断最小运行面：
   • 工具、system prompt、HTTP、持久化、provider：host。
   • slot、Conversation Node、浏览器状态和浮层：client。
   • host 能力且需要 Web 可视化：host + client。
   • 没有 Web 需求：不要声明 dsh.client，也不要构建 client bundle。
5. 写下插件唯一职责、依赖的 service、贡献的配置行、持久化 owner 和用户可见验证面，再开始编码。

2. 证据与官方参考

2.1 取证顺序

行为不确定时按顺序取证，不猜：

1. 当前项目及已安装 node_modules/@deepseek-ai/* 的 package.json、exports、types、README。
2. 环境明确提供的 DeepSeek Harness checkout；只读分析，不修改。
3. 克隆官方仓库取证（见 §2.3）。
4. 信息仍不足时，以当前正式版 exports/types 为边界，选择可安全失败的最小实现并标注假设。

不要写死本机绝对路径，也不要访问或转述未授权的私有仓库内容。

2.2 官方模板选择

若提供了 Harness checkout（环境提供或按 §2.3 克隆），优先按插件形态阅读这些模板；路径以 checkout 根目录为基准：

复杂插件只用于补证据，不作为起步模板。若要委派只读调研，提示词必须要求给出文件、行区间、契约与最小建议。

2.3 官方仓库兜底层

官方仓库 https://github.com/deepseek-ai/deepseek-harness 是公开、MIT 许可的可引用证据源。取证须明确目标版本、对应 tag/commit 和 npm 发布状态；不要把默认分支等同于用户安装版本。需要兜底取证时：

1. 选临时目录：用用户或环境提供的目录，例如 SCRATCH="$(mktemp -d)"；不要写死本机绝对路径。

2. 复用已有 checkout：核对 remote、HEAD 和工作区状态；用 git show <exact-tag>:<path> 等只读方式检查目标版本，不重置已有 checkout。需要补齐版本对象时 fetch 明确 tag，并保留已有改动。

3. 没有 checkout 时克隆到临时目录（只读取证，无需 pnpm install），随后通过精确 tag/commit 读取文件：

   git clone --filter=blob:none https://github.com/deepseek-ai/deepseek-harness.git "$SCRATCH/dsh-official"

4. 只克隆官方 deepseek-ai/deepseek-harness；不要访问或转述未授权的私有仓库内容。对克隆内容同样只读分析，不修改。

进入后定位：

1. 先读根 AGENTS.md（CLAUDE.md 是它的符号链接）：仓库布局、命令与约定一次讲清，是官方给 agent 的入口。
2. 再用 packages/README.md 的 group 表确认目标包位于哪个 packages/<group>/<pkg>。
3. 按 §2.2 模板表读对应包的 README.md 与 src/；取证结论给出文件与行区间。

演进兜底：§2.2 的历史模板路径只是索引，一切以目标版本的实际代码和发布产物为准；路径或名称漂移时，用目标版本的 packages/README.md 定位新位置并回报修正。记录目标 tag、解析后的 commit 和实际安装依赖版本；GitHub 有 tag 不等于 npm 已发布，也不代表本项目已通过该版本验收。

3. Bundle、Profile 与 package 契约

3.1 两个概念

• Bundle 是作者分发的包：package.json.dsh.bundle.patch 指向配置层。
• Profile 是用户运行的组合：$DSH_HOME/profiles/<name>/package.json.dsh.profile.bundles 保存有序 bundle 列表。
• 插件作者写 bundle；dsh plugin 创建和维护 profile。不要手写用户 profile manifest。

3.2 最小双面 package

{
  "name": "dsh-my-plugin",
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "exports": {
    ".": { "types": "./lib/types/index.d.ts", "default": "./lib/index.js" },
    "./client": { "types": "./lib/types/client/index.d.ts", "default": "./lib/client.js" },
    "./cordis.patch.yml": "./cordis.patch.yml",
    "./package.json": "./package.json"
  },
  "files": ["lib", "cordis.patch.yml", "README.md"], // 目录或显式清单均可；官方仓库常用显式文件清单
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "client": {
      "platform": "web",
      "inject": ["@deepseek-ai/dsh-client-runtime"]
    }
  }
}

规则：

• Host-only 包删除 ./client 与 dsh.client。
• Client 包必须同时有 dsh.client.platform: "web" 和真实存在的 exports["./client"]。
• dsh.client.inject 是随图下发的信息性元数据（预检展示 / HMR diff 用），不决定 client fiber 的激活顺序；预取由 dsh.client.immediately 驱动，真正的依赖等待来自 client bundle 导出的 export const inject（§5.1），两者互不替代。
• dsh.client.immediately 是仅供启动关键入口使用的可选预取标记；普通第三方插件不要默认开启。
• 当前权威字段是 dsh.client；历史兼容字段只有在目标正式部署仍明确读取时才添加。
• exports、files 和 Git/发布产物必须一致；任何入口都不能指向不存在的文件。
• DSH、Cordis、React 等共享运行时优先声明为 peer，避免复制 runtime identity；版本范围从目标正式版 package metadata 取证。

3.3 Patch 层

cordis.patch.yml 必须是顶层数组：

- insert:
    - id: my-plugin
      name: dsh-my-plugin
      config: {}

注意：

• id 是配置树中稳定的行身份；name 是 Node 可解析的包名或导出路径。
• 后层按 id 覆盖前层；目标行的 config 是整段替换，不是深合并，因此覆盖时要重述所需键。
• 生效顺序是 profile bundles → profile cordis.patch.yml → $DSH_HOME/cordis.patch.yml → 命令行 --patch；后者获胜。
• 包没有 dsh.bundle 时只会成为普通依赖，不会自动成为 profile 层。

4. Host 面实现

4.1 函数插件

普通插件通常导出：

export const name = 'my-plugin'
export const inject = ['tools']
export interface Config { enabled: boolean }
export const Config = z.object({ enabled: z.boolean().default(true) })
export function apply(ctx: Context, config: Config): void {}

• z 从 @deepseek-ai/schemastery 导入（不是 zod）；static Config = Config 引用导出的 schema，与官方内联的 static Config: z<Config> = z.object({...}) 等价。
• inject 是必需 service；未满足时 fiber 保持 pending，框架会在服务就绪后激活，不要用轮询模拟依赖注入。
• Config 默认值放 schema；任何部署可能需要改变的值都应成为配置，而不是源码常量。
• 可选 service 用 ctx.get() 判断或 ctx.inject([...], childCtx => ...) 惰性挂载；不要在 apply() 中抢跑兄弟 provider。

4.2 Service 插件

当插件提供稳定 service 时，参考 host/webserver：

export class MyService extends Service {
  static Config = Config
  constructor(ctx: Context, config: Config) {
    super(ctx, 'myService')
  }
  async [Service.init](): Promise<void> {}
}

• 构造器声明 service key；异步启动放在 Service.init。
• 初始化失败应让 fiber 失败并由启动方报告，不要吞掉组合错误。
• 注册方法返回 disposer；拥有资源的一方负责关闭资源。

4.3 Effect 所有权

所有长生命周期资源必须归当前 fiber：

• route、listener、watcher、timer、React root、DOM、socket、临时 service 都必须可清理。
• 用 ctx.on() 或 ctx.effect(() => disposer, label)。
• disposer 顺序通常是：停止外部入口/注销 registry → 等待或取消在途工作 → 关闭资源。
• 需要服务后绑定时，用“立即尝试 + service 事件/ctx.inject 重试 + 幂等 guard”，不要重复注册。

4.4 工具

使用 ctx.tools.register(defineTool(...))：

• description 写清何时调用、必要前置条件、失败语义和副作用。
• parameters 与 output.schema 都用 @deepseek-ai/dsh-tools 的 value-schema DSL（编译后是受支持的 JSON Schema 子集）：parameters 是隐式开放对象根、必填用属性内联 required: true；output.schema 声明 canonical 返回值并在注册时被 assertSupportedJsonSchema 强制校验。二者是同一 DSL 的两个面，不是两套语言。
• output.render 给模型稳定、紧凑、可判定的文本。
• 从 exec.agent 获取当前会话、工作区和 owner，不从全局进程状态猜。
• 异步工作观察或转发 exec.signal；写操作要有幂等、锁或冲突策略。

4.5 HTTP

• 注入当前正式版 Web server service，并用结构化最小接口降低耦合。
• 路由通过 ctx.effect(() => ctx.webServer.register({ kind: 'exact' | 'prefix', path, handler })) 注册；重复 (kind, path) 会抛错。
• 状态接口显式设置缓存策略：敏感或实时快照优先 Cache-Control: no-store，可重验证资源使用 no-cache；静态资源使用明确白名单和正确 content type。
• path decode、请求体解析和 handler rejection 都要转成明确 4xx/5xx，不能成为未处理 rejection。
• exact route、最长 prefix、fallback 的所有权不能冲突；未知插件资源返回 404，不落入 SPA fallback。
• 涉及权限或本机能力时采用最小暴露、回环/信任边界和方法白名单。

4.6 持久化与并发

先判断应复用正式版 storage/session persistence service，还是插件拥有独立介质。无论哪种：

• 路径配置显式指定；不要用 process.cwd() 默认值散落用户数据。
• 状态按 workspace、session、owner 或业务 id 建立清晰隔离维度。
• 同一资源的读改写串行化；并发创建采用 no-clobber 语义。
• 人可读 JSON 要用同目录临时文件 + fsync + 原子发布；追加日志要处理 torn tail。并发创建用 link()+unlink() 的 no-clobber 协议，勿用 rename() 静默覆盖。
• Registry backend 的清理顺序是 unregister 再 close。
• 恢复与 HMR 不能假设创建事件会重放；需要时显式扫描和回填已有对象。

5. Client 面实现

5.1 最小入口

import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
import type {} from '@deepseek-ai/dsh-client-ui-conversation/client'

export const inject = ['slots']
export function apply(ctx: ClientContext): void {}

• 类型贡献使用 type-only import 拉入 Context/SlotMap merge。
• client 注册、controller、listener、style 和 DOM 都必须随 client fiber dispose。
• per-session 状态按 SessionId 分桶；连接重置时只重同步已经读过的对象。

5.2 Slot 四步契约

1. 声明：从提供 slot 的官方包拉入类型；自定义 owner 才通过 module augmentation 扩展 SlotMap。
2. 认领：父 entry 的 children 表声明子 slot；声明即占有渲染权，不要争抢别人的 seat。
3. 注册：owner 与贡献者的激活顺序不保证，使用 ctx.slots.inject(key, () => ctx.slots.register({ name, children?, store?, locale?, inject?, ...kind 参数 }, Component)) 等待声明；children 同时是子 slot 的认领表（认领即占有渲染权）。kind 参数：keyed 必填 key、list 必填 id（可加 order/label）、chain 必填 select；single/keyed/list 可加 priority 做 cell 隐藏（同 cell 同 priority 会抛错）。向未声明 slot 直接 register 会抛错。
4. 渲染：owner 使用 renderSlot/renderSlotChain；贡献者不 import owner 的实现组件。

选择接缝时先检查当前正式版类型。常见会话 UI 接缝包括：conversation.session.header.actions/.utilities、conversation.view、conversation.chat.node、conversation.chat.commandview、conversation.chat.assistant-actions、conversation.chat.turnTail、conversation.input.dock、conversation.composer.dock、conversation.composer.bar、conversation.input.left/conversation.input.right/conversation.input.plan/conversation.input.model。全局浮层用 shell.overlay（list/root），不要碰 root 单槽。不要仅凭旧文档写 slot 名，以当前正式版 ui-conversation/src/client/contract/slots.ts 的 SlotMap 为准。

5.3 Conversation Node

Conversation Node 是“事件折叠 + keyed slot renderer”的组合：

1. 定义共享事件类型，并 merge 到 session event map。
2. 将 uiConversation 放入 inject，并调用 ctx.uiConversation.events.register(definition)：
   • match 选择事件；
   • start 创建节点状态；
   • update 按 seq 确定性折叠；
   • buildViewNode 生成稳定的 view node。
3. merge ChatNodeDataMap/节点 kind 类型。
4. 向 conversation.chat.node 注册相同 key 的 renderer。

红线：

• 重放同一事件序列必须得到同一节点，不读时间、随机数或当前磁盘状态。
• match 返回稳定业务 id 和 start|update 角色；节点引擎在当前会话内使用 conversationContextKey(kind, businessId) 去重。跨会话持久化缓存另行把 owner session 纳入 key，不能混成引擎契约。
• 事件写入业务 owner 会话；共享 host/client 事件文件保持 type-only、最好零运行时 import，避免双 tsconfig 的 Context augmentation 相互污染。
• 磁盘/服务端快照可作为实时 UI 真相；事件流用于对话投影、审计和确定性历史，两者职责不要混淆。