Dsh Plugin Dev

DSH 插件开发规范

DeepSeek Harness 是插件化的：几乎所有能力都是 npm 包插件，遵循 Cordis 契约。新增功能 = 新增插件包（+ agent preset + 配置），不改 DSH 核心源码。

三个核心事实

1. 插件契约：每个插件包导出 { name, inject, apply }；inject 声明依赖的 Cordis 服务名，apply(ctx) 里注册能力。伴生 invariant 用 ctx.invariants.register(PACKAGE_NAME, install) 声明包所有权。
2. 双平面：

• HOST 平面（三个 bundle 包 dsh-base / dsh-web-app / dsh-headless 各自的 cordis.patch.yml，经 package.json 的 dsh.bundle.patch 声明，再加 profile 的 cordis.patch.yml / $DSH_HOME/cordis.patch.yml / --patch）：注册表、沙箱、审批、持久化、模型路由、客户端 shell——跨会话共享。注意：没有名为 base.cordis.yml / web.cordis.yml 的文件，那是 shipped preset 注释里的概念指代。
• AGENT PRESET 平面（agent.cordis.yml）：某个会话专属的工具、人设、提示词段、子代理工具——按会话挂载。

1. 新增「模式」= 新增 agent preset 目录（/agent.cordis.yml + /preset.yml），放在 ~/.dsh/.agent-presets//；preset 列表自动发现它。

崩溃陷阱（违反必崩，逐条遵守）

1. client 插件必须打成 window.__ModuleLoader__ 手接格式

浏览器端插件不是裸 ESM。必须用 rolldown 打成：

window.__ModuleLoader__.load({ id: "pkg", factory: (require) => { / ... / return module.exports } })

把 react 与所有 @deepseek-ai/* 设为 external（交给 loader 的 require）。直接用 tsdown 打出的 .mjs 会让 web 端崩溃。用 scripts/build-client.mjs（已含正确 external + handoff 包装）。

2. 新 settings namespace 必须加入白名单

DSH rc.6 的 dsh-host-apiproxy 只对 WEBSETTINGSNAMESPACES 白名单里的 namespace 开放给客户端；否则客户端 settingsScope.bind({namespace}) 返回 settings-not-exposed（设置页读不到）。把 namespace 名追加进 nodemodules/@deepseek-ai/dsh-host-apiproxy/lib/index.js 的 WEBSETTINGS_NAMESPACES（见 scripts/deploy.ps1 里的 patch 步骤）。

3. cordis.patch.yml 新增插件行用 - insert: 格式

• insert:
• id: omd

name: dsh-omd

• id: omd-client

name: dsh-omd-client

不是裸的顶层 - id: ... / name: ... 行。

4. dsh.client.inject 必须列全 apply 用到的服务提供包

客户端 apply(ctx) 里用到的每个服务（如 ctx.settingsScope、ctx.slots、UI 原语）都要把它的提供包写进 dsh.client.inject，否则加载顺序错、服务未就绪即崩。例如用了 settings 就加 @deepseek-ai/dsh-client-ui-settings，用了 UI 就加 @deepseek-ai/dsh-client-ui-primitives。

5. WebUI 用 DSH 原语，不要手搓 div/input

一律从 @deepseek-ai/dsh-client-ui-primitives 引入 Menu / Button / Input / DisclosureRow / Pill 等（走 --dsw-* token，自动匹配主题）。权限选择器（Read Only / Workspace Write / Full access）用的就是 Menu + Button，做同类下拉直接复用这两个。手写 会与 DSH UI 格格不入。

6. 类型与值导入必须分开

用 import type { X } 导类型、import { y } 导值。tsdown/rolldown 对「把类型当值导入」报 MISSING_EXPORT。tsconfig 开 verbatimModuleSyntax: true 让 tsc 先抓住。

7. 注册必须唯一（重复即抛错）

同作用域层里 systemPrompt.section 的 name、settings.register 的 namespace、commands.register 的 name 都必须唯一。host 插件与 agent 插件不要注册同名 section。

8. 部署用本地 file: 依赖（junction），重建即生效，无需卸载

npm install 在 profile 里生成 junction（软链）指向源码目录；改代码后只需重新构建（软链自动读到新产物），不需要 uninstall/reinstall。

开发流程（每步都要做）

1. 先镜像现有插件：写之前必读 node_modules/@deepseek-ai//lib/types/*.d.ts（编译后的类型即权威 API）+ 其 agent.cordis.yml / package.json。绝不凭空猜 API。
2. 写代码：遵守上面的陷阱规则。
3. 类型检查：npx tsc --noEmit -p tsconfig.check.json（strict + verbatimModuleSyntax）。
4. 编译：host/agent 包 npx tsdown；client 包 npm run build（= tsdown + node build-client.mjs）。
5. 冒烟测试：用 mock ctx 调 apply(mockCtx)，断言注册了正确的 settings/section/command/service/slot，且不抛错。
6. 部署：见 references/deployment.md。
7. 重启 host 端到端验证（重启会中断当前会话，需用户执行）。

参考

• 架构、服务 API、preset 格式、slot 名：references/architecture.md
• 部署步骤、patch/白名单/junction 细节：references/deployment.md
• 高级注意事项（子代理 capability、isolate 规则、inject/ctx.get、session projection、complete 段、--dump-config）：references/gotchas.md
• 对照源码的事实纠偏与增量（必读）：references/spec-supplement.md —— Cordis 精确 Context API（无 ctx.scope/name/parent/dispose/baseDir，有 isolate/effect/fiber/baseUrl）、inject vs ctx.get、ctx.effect 生命周期、事件 dispatch 模式、单文件工具插件模式（apply(ctx, config) + Config + defineTool）、完整 slot 清单（single/list/keyed/chain + root/session/session-maybe）、host 组合物理结构、settings/schemastery 完整 API、agent presets roster（copy/standingKeyFor）、动态插件（cordis_* 工具集）、Client→Host RPC（harness.handle/host.call）。
• 完整规范（极致详细版，含 omd/vision-read 逐文件解读与端到端验收）：工作区根 DSH插件开发规范.md
• 可复用脚本：scripts/build-client.mjs（client 手接打包）、scripts/deploy.ps1（构建+装包+patch+白名单+preset）

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: abab996
• Source: abab996/dsh-plugin-dev
• License: MIT

Install and usage instructions live in the source repository linked above.