vlln/dsh-skills/make-dsh-plugin

创建 dsh 插件

dsh（DeepSeek Harness）是 agent harness——一个 Cordis 运行时加一套内置能力 （工具、会话、设置、Web GUI）。插件就是给它加能力的 npm 包：注册工具 / 服务 / 事件 / 命令 / prompt，或者往 Web GUI 里加界面。插件经 web profile 安装， 用户用 dsh plugin --profile web add <包> 装卸、在官方 Plugins 页查看与配置。

代码插件的分发形态有两种，选型只看是否需要"组合层"（判据见 Step 0）： bundle——声明 dsh.bundle.patch，自带一层组合 patch（多行 insert/config/disabled 随包分发）；纯 cordis——单个 Cordis 插件包，装完在 profile 的 cordis.patch.yml 里写一行 insert。两者都能带 client half（dsh.client）往 Web GUI 加界面。 纯 skill 包（无代码）走文件系统发现根，不属于这两类。注意：bundle 是分发单位， plugin 是功能单位——同一个包可以只当其一，也可以两者兼任（见 01-concepts.md L1）。

本 skill 的路线：Step 0 选形态 → Step 1 仓库布局 → Step 2 manifest → Step 2b 图标 → Step 3 Node half → Step 4 client half（可选）→ Step 5 安装与验证 → Step 5b 交付检查与发布 （发布可选）→ Step 6 README 与开发规范。要从零搭一个垂直 Agent，先读 [03-vertical-agent-recipe.md](references/03-vertical-agent-recipe.md) 的三步法。

权威契约内嵌在本 skill 的 `references/`，按主题编号取用（01 概念 · 02 装配 · 03 配方 · 04 契约 · 05 bundle · 06 UI · 07 设置 · 08 i18n · 09 纪律 · 10 验证 · 11 发布 · 12 生态 · 13 证据池 · 14 Desktop）——不必线性读，按第 2 节的边界地图取一篇即可； 开发不需要任何仓库文档（06-ui-style.md 是查阅型手册，按章查）。

0. 30 秒版（够开工）

一切皆插件：插件声明自己提供的服务与 inject 依赖，Cordis 牵线并管理生命周期。 在此之上只有五种装配单位：

两棵树——本 skill 里所有"该放哪"的判断都来自这里：

• 宿主树：一个进程一棵，由 profile 层栈决定。模型路由、Agent 循环、会话、设置、

沙箱/审批、工具注册表本体都在这里，所有 preset 共享。

• Agent 树：每个会话按选中的 preset 分出一棵隔离子树，装 persona、instructions、

工具行、技能——只有该 Agent 看得见。

一句话记住：profile 决定装了什么，preset 决定 Agent 看得见什么。 preset 不拥有模型与 Agent 循环（那是宿主）；权限预设是第三件事。展开见 01-concepts.md。

1. 先选一条路线（不必线性读）

每一步只需要读一个文件；读完就能动手，细节留到碰到时再展开。

2. 边界地图（一个问题 = 一个文件）

每个 reference 开头都有同样的「本文件回答 / 不回答」框；这里是一张总表。

3. Step → 文件

4. 纪律（11 条，动手前扫一眼）

逐条有反例与细节指针（09-dev-conventions.md）；违反其中任何一条 都会在真实装载时暴露，且大多不会在 mock 单测里暴露。

何时使用

• 用户想为 dsh 开发新插件（工具、skill 包、MCP server、事件监听、服务、

命令、prompt、浏览器 UI）。

• 用户要 bundle 插件 / 纯 cordis 插件的脚手架 / 示例 / 模板。
• 用户要新增一个 Agent 模式（preset），或把一套工具 + 提示词做成**垂直

Agent 产品**（读 03-vertical-agent-recipe.md）。

• 用户要安装 / 分发 / 升级插件，或理解 profile 层栈与重启边界（读

02-profile-and-preset.md）。

• 插件挂载失败且原因是 entry 契约或安装通道。

Step 0：选择插件形态

按插件分发什么选官方路径。dsh 字段 strict——能力面声明：

按三个判据选形态，按顺序问：

判据 A —— 有代码吗？ 纯 skill（无代码）走文件系统发现根；MCP server 是 patch 层配置，不是包 manifest 字段； 其余都是 npm 包 + Cordis entry。

判据 B —— 需要组合层吗？ 看包是否声明 dsh.bundle.patch。 声明 = 一层组合 patch（多行 insert/config/disabled，patch 可为数组）→ dsh plugin --profile web add 进层栈；无声明 = 单个 Cordis 插件 → profile cordis.patch.yml 写一行 insert。

先问一句：是原型还是产品？ 只给本机用、还在试形态 → 直接用产品内的创造模式（cordis preset）做 bundle 并 install_bundle（见 05-bundle-plugins.md「创造模式」）；要分发、要维护、要给别人装 → 按下面判据走仓库路径。

判据 C —— 给谁用？ 只给宿主加服务 / 界面 → Host 行即可；要影响 Agent 看见什么 （工具、人设、技能）→ 落在 preset 行（web 的内置工具行就是按模式拆开的）。 装完不等于新模式出现：新增模式 = 新增一条 `preset-<id>` 声明行。

三者都按目标运行时的配置协调 / HMR 能力实测生效情况，不预设必须重启。 带 UI 的独立插件两类皆可（自渲染 client 在 bundle 里照常工作）——选型看是否需要组合层，而非 UI 形态。

Step 1：仓库布局

my-plugin/ 根即 npm 包（bundle 形态包根 = 仓库根）：

my-plugin/
├── package.json            # name/version + main/exports + icon + dsh.bundle/dsh.client
├── icon.svg                # 必需：Plugins 页的插件标识（非功能截图）
├── cordis.patch.yml        # dsh.bundle 声明的组合层（insert 挂载自身）
├── index.mjs               # Node half 入口：完整 Cordis 插件（main/exports["."]）
├── client/  lib/client.js  # client bundle 源码 / 构建产物（dsh.client 通道）
└── scripts/                # 门禁 + 生成器（可选）

Step 2：package.json + 能力面

按 references/05-bundle-plugins.md 与 references/04-plugin-contract.md 的模板。 关键决策：

• dsh.bundle.patch → cordis.patch.yml（组合层，含 - insert: - id: <自身> name: <包名>）
• dsh.client 声明（platform web）+ exports["./client"]（有 client half 时）
• main/exports["."] 指向 Cordis entry（name/inject/Config/apply）
• dependencies/peerDependencies/devDependencies 三处都留空——官方包由挂载环境注入（理由与本地 link 配方见 13-gotchas.md 1）；唯一例外是 schema 要用 dsh 的 fork

@deepseek-ai/schemastery（公共 schemastery 没有 .volatile()），装成普通 dependencies

• inject 声明 ctx.get 用到的全部服务（webServer/jobs 等）。严格注入两个方向都会出事：
• 声明了但宿主没有（名字写错、或该服务已被新 rc 移除）→ 条目永久 pending，

boot 日志只有一行 warning: 1 entry did not activate，该插件的功能与 UI 一起消失；

• 用到了却没声明 → apply 开头即抛 cannot get property without inject。

两种都照不出来于 mock ctx 单测——必须真启动一次 profile 才算验证过（Step 5）

• 服务名与槽名以当前基线为准逐条核实：官方会跨 rc 改名（13-gotchas.md 7、8）
• 包显示元数据（Plugins 页里的标题与一句话描述）：locale/en.json + locale/zh.json 的

meta.title / meta.description，并把 "./locale/*.json" 同时加进 exports 与 files ——少了 files 发布出去就丢（写法与回退链见 08-i18n.md §2）

Skill 包（dsh.skills）与 MCP server（dsh.mcpServers）

声明写法（dsh.skills 相对路径列表 / dsh.mcpServers 的 server-id → 启动 配置映射）与 SKILL.md 写法规范（frontmatter / 正文模式 / <500 行，遵循 make-skill）见 references/04-plugin-contract.md 对应小节——不要发明竞争格式。

Step 2b：绘制插件图标（必做）

每个 npm 插件都要绘制并验证 Plugins 页图标，包括没有 client half 的插件； 仅走文件系统发现的纯 skill 包不适用。这是交付要求，不是运行时必填字段。

• 先看几个已发布插件的图标（官方 Plugins 页里的、或你自己别的插件），按其简洁风格绘制

能表达本插件功能的 SVG。观测样式是 36×36 透明画布、主体约在 8..28、少量蓝/青渐变， 不是硬 API；不要照搬别的插件身份。用户指定的标记优先，例如 autofork 的 ⑂ 仅是该插件 的标记，需画成路径/几何形状，不把它变成所有插件的模板。

• 使用显式填色/描边；SVG 作为 <img> 不继承宿主 `currentColor`。

不用字体字形、外链资源或脚本；不要把 README 功能截图当作插件图标。

• 在 `package.json` 顶层写 "icon": "./icon.svg"，不是 `dsh.icon`；图标限 SVG / PNG / JPEG / WebP、≤ 256 KiB，路径相对 manifest 且 realpath 后必须仍在包内；

files 打包白名单包含图标，并保留 exports["./package.json"] = "./package.json"。

• 完成前读 10-install-and-verify.md「插件图标：机械验证与视觉验收」，

验证打包结果、真实 Plugins 图片加载，并实际查看渲染图像；只证明文件存在不算完成。

Step 3：Node half——Cordis entry

index.mjs 导出完整 Cordis 插件（name/inject/apply）。用 defineTool 注册工具；服务/事件/命令/prompt 是完整 Cordis，无需声明。依赖解析是官方 运行时的职责（@deepseek-ai/*、cordis——profile pnpm 闭包注入，勿声明）。 在 ctx.effect()/ctx.on() 内注册，disable 时清理。

检查点：entry 可解析；工具已注册；inject 声明完整；在真实 profile 里启动过一次 （boot 不报 plugin tree failed to load）——缺 inject、服务名写错这类问题只有真启动才暴露。

Step 4：Client half（可选）——自渲染