插件开发技能 frederico-kluser/dsh-plugin-dev-agent-skill

dsh-plugin-dev-agent-skill

用于构建 DeepSeek Harness 插件的完整 agent 技能。

一个自包含、经实测验证的技能，教会 AI agent（及其人类）如何为 DeepSeek Harness（DSH）创建、扩展、加固、测试、打包和发布 Cordis 插件——基于真实测量出的 API 表面，而非基于文字描述。

language
license MIT
skill global

这是什么？

DeepSeek Harness 中的一切都是插件。面向用户的扩展路径是你自己发布的 Cordis 插件——绝不是向官方仓库提交 pull request，因为官方仓库不接受外部 PR。本技能就是这条路径的行动手册，其中每一条论断都锚定到经过验证的来源（verified in : 或官方 URL），每一条被驳斥或未经证实的社区说法都会被标记出来，绝不会被当作事实来教授。

本技能涵盖六项能力：

- 创建功能——通过类型化事件、ctx.effect 清理器、ControlIntent、长轮询子进程和 JSONL IPC 实现后端行为。
- 修改界面——四个前端杠杆：ctx.webServer 路由、dispatch 接管、tapIndex，以及 slots / client-export 系统。
- 安全——面向控制平面的插件所需的凭据 + 边界、故障关闭默认值、双轴允许列表、nonce、审计和速率限制。
- 测试——六层金字塔、带契约的测试替身、对抗性测试套件、契约测试和有目的的覆盖率。
- 打包——预编译 bundle、允许列表 tarball、publint + attw --pack . + 一个 check-tarball 脚本。
- 发布——changesets、OIDC provenance 和 CI 门禁。

快速安装（通过符号链接安装为全局技能）

该仓库就是技能目录：根目录的 SKILL.md、docs/、examples/ 和 scripts/ 共同构成一个可安装的技能。克隆到任意位置，并将其符号链接到你的 agent 技能目录中：

git clone https://github.com/frederico-kluser/dsh-plugin-dev-agent-skill.git ~/Projects/dsh-plugin-dev-agent-skill
mkdir -p ~/.agents/skills
ln -s ~/Projects/dsh-plugin-dev-agent-skill ~/.agents/skills/dsh-plugin-dev-agent-skill

- 技能目录就是整个仓库——根目录的 SKILL.md，加上 docs/、examples/ 和 scripts/。
- docs/.md 是规范参考，agent 按主题按需加载；它不会预先全部读取。
- 卸载时，删除符号链接即可：rm ~/.agents/skills/dsh-plugin-dev-agent-skill。克隆的仓库可以保留也可以删除。
- 其他 agent 工具从各自的路径读取技能（例如 ~/.claude/skills）；把同一个符号链接指向那里即可——本技能与后端无关。

工作原理

| 路径 | 内容 | 何时加载 |
| SKILL.md | 说明、API 真相、安全/测试/打包要点、反模式 | 始终 —— 从这里开始 |
| docs/.md | 深入参考（架构、接口、功能、安全、测试、打包） | 按需、按主题 |
| examples/minimal/ | 一个真实、可编译的 Cordis 插件骨架 | 研究它 / 运行它以快速上手 |
| scripts/check-skill.mjs | 零依赖自检校验器 | node scripts/check-skill.mjs |

快速开始：创建一个插件

这是该技能完整教授的单页流程。从空仓库到已安装的插件：

1. 对照真实的 .d.ts / tarball 验证 API（绝不要依据文字描述）—— 在你支持的 0.1.0-rc.7..0.1.1-rc.1 范围内确认 ctx.webServer / WebServer、ctx.subprocess / SubprocessRuntime 以及 spawn(spec)。锁定 harness 实际解析到的版本行。
2. package.json 需包含 type: "module"（仅 ESM）、engines.node >= 24，以及一个真实的 dsh.bundle.patch —— 空的 dsh.bundle: {} 不会激活任何东西。
3. cordis.patch.yml —— 一个使用你自己的 id 的单一 insert；绝不要针对另一个包的 id（解析是整条目替换）。
4. src/index.ts —— 一个导出 name、inject 数组、可选的 Config 以及 apply(ctx, config) 的模块，其中 apply 会断言配置（在加载时大声失败）并通过 ctx.effect 注册所有可逆内容。
5. Worker —— 通过 ctx.subprocess.spawn(spec) 将长轮询集成放在子进程中，使用 JSONL IPC 协议和死人开关。
6. 测试 —— 六层金字塔；对抗性测试套件必须尝试突破你的门禁；契约测试固定你镜像的类型。
7. 打包 —— publint + attw --pack . + check-tarball，将 tarball 加入允许列表，然后通过 CI 门禁发布。

// package.json（节选）—— dsh.bundle.patch 是激活开关 { "name": "dsh-my-plugin", "version": "0.1.0", "type": "module", "main": "./dist/index.js",
"engines": { "node": ">=24" },
"dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
"peerDependencies": { "@deepseek-ai/cordis": ">=4.0.0
ctx.webServer.register({ // WebServer 上的真实席位
kind: 'prefix',
path: '/__guard',
handler: (req, res) => { res.writeHead(200); res.end('guard up') },
}),
)
}

完整的拼写 —— 选项、边界情况、安全义务以及确切的 API 名称 —— 位于 SKILL.md 和所引用的文档中。

内容地图

每个参考文档涵盖的内容：

| 文档 | 涵盖 |
| SKILL.md | 端到端配方、经实践检验的 API 事实，以及强制性的章节布局（你将学到什么、安装、创建、接口、功能、安全、测试、打包、反模式） |
| docs/arquitetura.md | DSH 中的 Cordis：Context、fibers、effects、events、合并层，以及反模式清单 |
| docs/interface.md | 四个前端杠杆：routes、dispatch takeover、tapIndex、slots 和客户端导出 |
| docs/funcionalidade.md | 类型化事件、ControlIntent、tunnels、Telegram worker、子进程和 IPC |
| docs/seguranca.md | 威胁模型、边界 + 凭据、允许列表、nonce、审计、速率限制、验收清单 |
| docs/testes.md | 测试金字塔、带契约的替身、对抗性测试套件、变异测试、覆盖率、CI |
| docs/empacotamento.md | 构建、tarball、publint/attw/check-tarball、changesets、信任流水线、发布 |

这个技能不是什么：

- 不是 SDK。 它是文档和一个可运行的骨架；它不附带任何你接入自己插件的运行时代码。
- 不是 DeepSeek Harness。 DSH 是上游项目，不在本技能范围内——本技能读取其真实发布的包，但不修改它们。上游不接受外部 PR。
- 不能替代验证。 根据其诚实规则，每一个可教授的事实都经过对已发布的 .d.ts/tarball 的独立验证和实测实验；这里没有任何内容能让你的代码免于自身的契约测试。

诚实与溯源

这个技能对待论断的方式，就像优秀的测试套件对待行为一样：

- 已验证的事实带有来源——verified in :（指向真实测量 / 镜像类型）或官方 URL——可以安全教授。
- 被驳斥的论断（P-01..P-13 表格）标记为经真实测量驳斥，仅出现在反模式章节中，且始终紧邻已验证的正确替代方案。它们绝不会被当作真理教授。
- 不确定的论断明确标记为 [UNVERIFIED]。

它能捕捉到的例子：web seat 是 ctx.webServer / WebServer，而不是 ctx.httpServer；spawning 是 spawn(spec)，而不是 spawn(command, args, options)；空的 dsh.bundle: {} 不会激活插件——只有 dsh.bundle.patch 才会。API 名称会漂移，而文字描述滞后于 tarball，因此本技能的默认姿态是“先测量，再教授”。

开发 / 贡献

欢迎通过 pull request 贡献。几条内部规则让这个技能保持诚实：

- 在开 PR 之前运行验证器——node scripts/check-skill.mjs（零依赖；--strict 用于完整门禁）。它检查 frontmatter、强制性的章节布局、内部链接、被禁止的论断和占位符。
- 绝不教授被驳斥的论断。 每个 P-01..P-13 短语只保留在反模式章节中，且始终与已验证的正确行为配对。
- 为你的事实标注来源。 每个新的可教授论断都需要 verified in : 或官方 URL；任何你无法确认的内容都标记为 [UNVERIFIED]。
- 面向公众的内容使用英文；保持直接、技术性的语气。

许可证

MIT © 2026 Frederico Guilherme Klüser de Oliveira。参见 LICENSE。