dsh-plugin-dev-skills

一句话定位

这是一个专门给 AI agent 阅读的技能包，把 DeepSeek Harness 官方文档里散落在教程、参考手册与生成目录中的开发约定，收敛成可执行的标准。它让 agent 在你下达"开发一个 DSH 插件 / 写一个 DSH 工具"等指令时，按统一规则编写、审查或调试 Cordis 插件，而不是凭经验乱猜。

核心能力

• 提供 8 条开发硬规则（接口以生成参考为准、副作用必须可清理、watefall 监听器必须调用 next()、失败要响亮、注入依赖要分必需/可选、配置一律 Schemastery、工具 execute 返回规范 JSON、模型可见即已记录），agent 写任何插件都要遵守
• 提供 6 个标准场景工作流（新建插件 / 给模型加工具 / 拆可替换能力 / 接新模型提供方 / 打包安装 / 在 monorepo 内新建包），每个场景列出具体步骤与对应 SDK/工具名
• 提供 12 份按需加载的 references 详细标准文档（插件形态、服务、事件、配置、上下文 API、三种角色、工具、LLM 适配器、四种扩展形态、打包、workspace 包、seam 目录），按命中主题渐进式披露
• 内置 2 个最小可运行示例：hello-plugin 演示插件加载与 ctx.effect 自动清理，greet-tool 演示 defineTool 三段式写法的模型工具
• 提供 evals/trigger-queries.json 评测集（12 条正例 + 9 条负例），用于回归 description 的触发准确率
• 暴露一份可勾选的完成前检查清单，覆盖接口、副作用、可选依赖、Schemastery、execute 协议、watefall、StreamChunk 协议、组合层序等

技术实现

• 语言: Markdown（技能内容）+ 例子里含 ESM JavaScript（hello-plugin / greet-tool）
• 关键依赖: 所有引用都指向 DeepSeek Harness 仓库（@deepseek-ai/* 包）的自动生成参考；本仓库本身不打包任何运行时依赖
• 架构模式: Agent Skills 规范技能包；SKILL.md 的 frontmatter 声明 name: dsh-plugin-dev 与 metadata.version: 1.2.0，正文是渐进式披露的硬规则 + 场景工作流 + 检查清单。references/ 12 份文件按需加载，examples/ 提供可复制运行的最小骨架
• 入口文件: SKILL.md（技能入口与 frontmatter）

适用场景

正在用 DeepSeek Harness 或 Claude Code 等支持 Agent Skills 的 AI agent 编写 Cordis 插件的开发者。当你需要让 agent 帮你新建一个 DSH 插件、给模型加一个工具、接入新的模型提供方、拆分可替换能力、或者打包发布一个组合包时，先让 agent 加载这个技能，它就会按 8 条硬规则和 6 个场景工作流输出代码，而不是凭印象随便写。examples/ 里的两个最小示例还能直接 dsh plugin add 跑通，验证自己的开发环境是否正确。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:zimodzh/dsh-plugin-dev-skills

提示：该技能以 Agent Skills 规范内容为主，安装到 DSH profile 后，agent 在处理 DSH 插件开发相关问题时即可加载 SKILL.md。若克隆到其它 agent 的技能目录（Claude Code/Codex/Copilot 等），需按 README.md:79-94 把文件夹改名为 dsh-plugin-dev，与 SKILL.md frontmatter 中的 name 字段一致。

配置项

本插件无需额外配置。技能没有暴露任何配置项；所有内容（硬规则、场景工作流、references 子文档、示例）都是只读 Markdown。

常见问题

Q: 加了这个插件后我的 DSH 里会出现什么新功能？

A: 不会直接出现新功能。它本身是给 AI agent 读的"技能文档"，作用是让 agent 在你下达"开发一个 DSH 插件 / 写一个 DSH 工具"等指令时，按统一的标准来编写、审查或调试 Cordis 插件。

Q: 技能名 dsh-plugin-dev 跟仓库名 dsh-plugin-dev-skills 不一样有关系吗？

A: 有关系。SKILL.md:1 把 name 声明为 dsh-plugin-dev，Agent Skills 规范要求目录名与 name 一致，加载器是按目录名寻址的，所以克隆或解压后必须把文件夹改名为 dsh-plugin-dev，否则加载器可能发现不了它。

Q: 哪些 agent 可以加载这个技能？

A: 任何支持 Agent Skills 规范的 agent。SKILL.md:5 声明兼容 DeepSeek Harness、Claude Code、Codex、VS Code Copilot 等；每个 agent 的项目级与用户级技能目录映射见 README.md:88-94。

Q: 这个插件和 DSH 自带的插件开发文档有什么区别？

A: DSH 官方文档分散在教程、参考手册与生成目录里，且"接口以生成参考为准"；这个技能把官方扩散的内容蒸馏成 8 条硬规则、6 个场景工作流与一份可勾选的检查清单，并附带 2 个最小可运行示例（hello-plugin 生命周期示例与 greet-tool 模型工具示例）。

Q: examples 目录里的 hello-plugin 和 greet-tool 是做什么用的？

A: hello-plugin 演示插件加载与 ctx.effect 自动清理的标准骨架；greet-tool 演示 defineTool 三段式写法的最小模型工具。两者都是 references/* 文档配套的可复制运行示例，跑通它们就能验证自己的开发环境是否正确。

Q: 修改 SKILL.md 里的 description 之前要先做什么？

A: 先跑 evals/trigger-queries.json 回归评测集，记录通过率再改动。evals/README.md:13-23 规定了 12 条正例 + 9 条负例的打分方法，并要求按训练/验证集 6:4 划分，防止 description 调过头只匹配特定关键词。

Q: 这个技能适合用来开发会话内动态插件或 agent preset 吗？

A: 不适合。SKILL.md:18-19 明确划清了边界：本技能只覆盖仓库内、文件式的 DSH 插件开发与 monorepo workspace 包；会话内 cordis_define/cordis_run 流与 agent preset 组合编辑由各部署的专项技能或官方工具负责。

Q: 升级这个插件的命令是什么？

A: 跟安装命令一致，再次执行 dsh plugin --profile web add github:zimodzh/dsh-plugin-dev-skills 即可覆盖式更新。由于它是纯文档技能，不涉及迁移或 schema 变更。

上手难度

入门 — 技能本身是 Markdown 文档，无需构建、无需配置；安装后让 agent 加载并问"如何开发一个 DSH 插件"即可看到效果。后续若要真正跑通 references 里的示例，需要安装 Node.js、pnpm 与 DSH 的 dsh CLI。

已知问题与限制

• README.md:99 明确说明内容基于官方文档站 2026-08 快照，且遵循"接口以生成参考为准"原则；DSH 后续版本若 API 变化，技能内容可能与生成参考不一致（evidence: README.md:97-99）
• 技能名 dsh-plugin-dev 与托管仓库名 dsh-plugin-dev-skills 不同，克隆/解压后必须把文件夹重命名为 dsh-plugin-dev，否则按目录名寻址的加载器可能发现不了本技能（evidence: SKILL.md:135-137）
• 仓库根目录无 package.json，未声明 engines、peerDependencies、os、cpu 字段，Node.js 版本与宿主平台兼容性需由调用方自行保证（evidence: 仓库根目录 / SKILL.md:1-9）
• examples 目录的 hello-plugin 与 greet-tool 均无 engines 字段声明，DSH 版本兼容性与宿主版本对齐需由用户按 README.md:107-108 自行验证（evidence: examples/hello-plugin/package.json / examples/greet-tool/package.json）
• 评测方法要求每条查询跑 2-3 次取多数（触发本身有随机性），单次跑分不足以确认 description 改动效果（evidence: evals/README.md:22-23）

中文 · English

一套遵循 Agent Skills 规范 的技能，用于开发 DeepSeek Harness（DSH） 插件。

DSH 是一个插件化的 Agent Harness SDK：模型适配器、工具注册表、会话日志、甚至 agent loop 本身，全都是可以从配置里替换的 Cordis 插件。本技能把官方文档里散落在教程、参考手册与生成目录中的约定，收敛成一套可执行的标准——任何加载了它的 agent，都能用同一种方式开发 DSH 插件。

注意： 本技能为社区维护项目，与 DeepSeek 官方无隶属关系，亦未获官方背书。

技能里有什么

dsh-plugin-dev/
├── SKILL.md      # 入口：frontmatter、8 条硬规则、6 个场景工作流、决策速查表、完成前检查清单
├── references/   # 12 份详细标准，按需加载；索引见 references/README.md
├── examples/     # 两个可复制、可运行的最小示例
│   ├── hello-plugin/
│   └── greet-tool/
└── evals/        # description 的触发评测集与评测方法

references 覆盖：插件形态与生命周期 · 服务与依赖注入 · 五种事件分发模式 · 插件配置 · 上下文/Fiber/注册表 API · 三种角色能力设计（Definition/Provider/Consumer）· 工具开发 · LLM 适配器协议 · 插件形态扩展（工具/钩子/UI/协议桥）· 打包与安装 · 仓库内 workspace 包 · 完整能力 seam 目录。

目录结构

dsh-plugin-dev/
├── SKILL.md                        # 技能入口：frontmatter、8 条硬规则、6 个场景工作流、检查清单
├── LICENSE                         # MIT 许可证
├── README.md / README.en.md        # 本说明（中文主 / 英文附）
├── references/                     # 12 份详细标准（渐进式披露，按需加载）
│   ├── README.md / README.en.md    #   目录索引：文件｜内容｜何时读
│   ├── plugin-anatomy.md           #   插件形态、生命周期、Fiber、自动清理、HMR
│   ├── services.md                 #   服务定义/提供/消费、inject、隔离
│   ├── events.md                   #   五种事件分发模式、命名
│   ├── config.md                   #   插件配置与 cordis.yml 行
│   ├── context-api.md              #   上下文 API、Fiber 类、注册表、继承的框架 API
│   ├── three-roles.md              #   能力三种角色（seam）设计
│   ├── tools.md                    #   工具开发完整约定
│   ├── llm-adapter.md              #   LLM 适配器协议
│   ├── plugin-forms.md             #   四种扩展形态 + 功能→机制映射
│   ├── packaging.md                #   打包、安装与层序
│   ├── workspace-package.md        #   monorepo 内新建包的清单与命名
│   └── seams.md                    #   核心 seam 与能力服务全表、架构映射
├── examples/                       # 可复制、可运行的最小示例
│   ├── README.md / README.en.md    #   示例索引
│   ├── hello-plugin/               #   最小插件（生命周期 / 自动清理）
│   │   ├── README.md / README.en.md
│   │   ├── index.js
│   │   ├── package.json
│   │   └── cordis.patch.yml
│   └── greet-tool/                 #   最小模型工具（defineTool）
│       ├── README.md / README.en.md
│       ├── index.js
│       ├── package.json
│       └── cordis.patch.yml
└── evals/                          # description 触发评测集
    ├── README.md / README.en.md    #   评测方法（训练/验证集划分）
    └── trigger-queries.json        #   12 正例 + 9 负例

安装

技能名为 dsh-plugin-dev，Agent Skills 规范要求所在文件夹同名；本仓库名为 dsh-plugin-dev-skills。克隆时直接指定目标文件夹名即可一步到位：

git clone https://github.com/zimodzh/dsh-plugin-dev-skills.git ~/.claude/skills/dsh-plugin-dev

把目标目录换成你所用 agent 的对应路径（见下表）；也可以下载 release 压缩包，解压后把文件夹改名为 dsh-plugin-dev。

无需构建、无需脚本依赖、无需任何配置——以上说的是技能本身。实际开发 DSH 插件则需要一个可用的 DSH 环境：Node.js、pnpm，以及示例中用到的 dsh。

验证：向 agent 提问"开发一个 DSH 插件 / 写一个 DSH 工具"，技能应被触发；在 DSH 里也可以直接用 skill(dsh-plugin-dev) 工具加载确认。

版本对应

内容蒸馏自 DeepSeek Harness 官方文档站（2026-08 快照），并遵循官方「接口以生成参考为准」的原则：技能内容与仓库生成参考不一致时，以生成参考为准。发现偏差欢迎提 issue 或 PR。

触发评测

evals/trigger-queries.json 是 description 的回归评测集（12 条正例 + 9 条负例）。修改 description 前请先跑评测并记录通过率；方法论（含训练/验证集划分、防过拟合）见 evals/README.md。

示例

• examples/hello-plugin —— 最小插件（bundle 格式）：dsh plugin --profile demo add ./examples/hello-plugin 后 dsh --profile demo 启动，应看到加载日志和每 5 秒一次的心跳，卸载时自动清理。
• examples/greet-tool —— 最小模型工具：安装后对 agent 说 "Use the greet tool to greet Ada."，应收到 "Hello, Ada!"。

完整步骤见 examples/README.md。

范围边界

覆盖仓库内、文件式的 DSH 插件开发：插件包、cordis.yml 行、patch overlay、工具、适配器、组合包、profile、仓库内 workspace 包。不覆盖会话内动态插件（cordis_define/cordis_run 流）与 agent preset 组合编辑——这两类由各部署的专项技能或官方工具负责。

维护与贡献

• 更新任何 references 前，先核对官方文档对应页面（文档站或源码生成区块），并在 PR 中注明来源。
• 遵守 Agent Skills 约束：name 为 kebab-case 且与目录一致；description ≤ 1024 字符（DSH 目录注入提醒默认 500）；正文渐进式披露。
• 欢迎 PR：修正、更多示例、扩充评测集、其它语言版本。

License

MIT——见 LICENSE。