dsh-plugin-dev

August 24, 2026 · View on GitHub

让 Claude Code / Codex / DSH 等 coding agent 按 DeepSeek Harness (DSH) cordis 插件制式，自动开发、审查、打包发布 DSH Web 插件的技能（skill）。

把官方插件仓库（deepseek-harness）的生产实践与官方文档的规范蒸馏成一份可执行的流程：你只提需求，agent 负责澄清、实现双端插件（或纯 Host 插件）、写测试、给验收清单，甚至生成发布工作流。

这是什么

DSH Web 是基于 cordis 的 agent 宿主。给它开发插件，本质是交付一个声明了 dsh 元数据、含 Host/Client 双端实现（需要设置 UI 时）、通过命名空间桥通信的 npm 包——而不是普通脚本或独立服务。本 skill 把这类插件的全部隐性制式约束显式化，并给出从需求到发布的工作流。

本 skill 完全自包含（SKILL.md + references 蒸馏了全部规范），不依赖本机特定路径。

目录结构

dsh-plugin-dev/
├── SKILL.md                  # 入口：触发描述、制式约束、三硬点、开发流程、验收要点
├── references/
│   ├── architecture.md       # 双端架构与命名空间桥、会话绑定、HMR
│   ├── tool-contract.md      # defineTool 契约、execute 固定管线、blocked 反例
│   ├── settings-and-credentials.md  # 设置注册、Schemastery Config、只写凭据
│   ├── client-card.md        # 浏览器设置卡片、ModuleLoader、常见错误
│   ├── packaging.md          # dsh 元数据、patch 对错例、npm Trusted Publishing 发布
│   ├── testing.md            # 测试分层、受限环境验证替代、验收清单
│   └── install.md            # 各 agent 安装位置
├── evals/evals.json          # 评测用例（3 个真实插件需求）
└── README.md                 # 本文档

安装

把整个 dsh-plugin-dev/ 目录复制到目标 agent 的 skills 目录：

Agent位置
DSH~/.dsh/skills/dsh-plugin-dev
Claude Code~/.claude/skills/dsh-plugin-dev（或项目级 .claude/skills/）
Codex~/.codex/skills/dsh-plugin-dev

验证安装：向 agent 输入一句触发语（如"为 DSH 开发一个插件，让 agent 能查询 XXX"），确认它加载了本 skill 并按流程执行。

使用方法

直接提需求即可。skill 的触发描述覆盖：为 DSH 开发/写插件、给 dsh web 加工具或设置卡片、写 cordis 插件、把某系统接进聊天、扩展 agent 能力并打包成插件、参照官方插件仓库开发类似插件、修复/审查已有插件。

示例需求：

为 DSH 开发一个插件，让 agent 能从聊天里查询 GitHub 仓库信息（只读）。需要 3 个工具：搜索仓库、按 owner/repo 查单个仓库、列 release。需要一个设置卡片配置 GitHub Personal Access Token（走 DSH 只写凭据系统）。禁止任何写操作。开发成完整可安装的插件包并配置好 npm 发布。

预期产出： 双端插件包（package.json + cordis.patch.yml + index.mjs + client.js + 功能模块 + tests + README + LICENSE），必要时含 .github/workflows/publish.yml。

能力范围

  • 两种形态：双端（Host + Client，需要设置页 UI 时）与纯 Host（标准 cordis 插件，无 UI 需求时）——skill 全程条件化，不强制 client
  • 开发：10 条不可协商制式约束（bundle patch、双端、inject、Schemastery Config、凭据只写、effect 清理、transport 封装、fail-closed 等）
  • 三硬点（评测中无规范时 100% 被漏的约定）：结构化 {kind:'blocked'} 失败、`ModuleLoader.load$ 客户端注册、\text{patch} 行 \text{name}=完整包名/\text{id}=短名
  • 打包发布：逐文件 \text{files} 白名单、\text{exports}、\text{LICENSE}、\text{npm} \text{pack} 核对清单、\text{npm} \text{Trusted} \text{Publishing}（\text{OIDC} 工作流模板，无 \text{token}/\text{OTP}）
  • 验证：理想环境三步（\text{npm} \text{test} + \text{dsh} \text{plugin} \text{add} + 冒烟）；受限环境（\text{CI}/沙箱/评测无 \text{dsh} \text{CLI}）提供 5 条离线替代路径

评测结果

两轮对比评测（3 个真实插件需求 \times 带/不带 \text{skill}），带 \text{skill} 均满分、无回归：

用例带 \text{skill}不带 \text{skill}（基线）
\text{eval}-1 · \text{github} 信息插件10/108/10
\text{eval}-2 · \text{weather} 插件9/96/9
\text{eval}-3 · \text{wiki} 检索插件11/117/11
合计30/30（100%）21/30（70%）

关键发现：基线的失败高度集中在隐性制式（\text{blocked} 结构、$ModuleLoader`、patch id），恰是 skill 显式化的内容——证明判别力来自规范本身，而非基线偏弱。

评测工作区（含 benchmark.json、review.html 审阅页）在 dsh-plugin-dev-workspace/，与 skill 目录同级。

开发与迭代

  • 评测用例：evals/evals.json（prompt + expectations）
  • 评分：工作区的 scripts/grade.mjs（程序化断言，跨迭代可复用）
  • 迭代流程：修改 SKILL.md/references → 重跑带 skill 用例 → 聚合 benchmark → 生成 viewer 审阅（skill-creator 标准流程）
  • 改完源文件后，记得把整个目录重新复制到三个安装位置保持同步。

版本记录

版本内容
v1（iteration-1）初版：制式约束 + 流程 + references；评测 30/30
v2（iteration-2）新增"最容易漏的三个硬点"（带对/错示例）、防过度工程引导、触发描述强化；评测 30/30 无回归
v2.1packaging.md 发布章节补强：完整 publish.yml 模板 + npm pack 核对清单
v2.2双端/纯 Host 条件化（client 从默认必需改为按需可选）；独立审查 10 缺口全修复（受限环境验证替代、files 对齐、patch id 语义统一、LICENSE 等）
v2.3新增「版本锚点」：标注规范对应的宿主版本与需核对的 API 调用点，宿主升级后强制核对，防规范老化

上游参考

  • DeepSeek Harness 官方文档 docs/user/develop/：basic/config、basic/tool、basic/publish、framework/service
  • 官方插件仓库：github.com/deepseek-ai/deepseek-harness（官方插件实现、示例与文档同源）