dsh-plugin-maker —— 插件开发工坊
中文 | English
一切皆插件，但不是所有人都是插件开发者。 —— 这个工坊就是来补后半句的。
先判断什么值得成为插件。 —— 这是它做一切事情的第一原则。
为什么需要它
DeepSeek Harness 的理念是 "Everything is a Plugin"：能力都可以被组合、替换、扩展。但自由是有代价的——插件化把原本由平台承担的工作转移给了使用者：
- 这个需求到底是什么？
- Harness 原生已经支持了吗？
- 社区里有没有现成插件？
- 这个接口现在到底是什么？哪些是固定契约？
- DSH 更新以后，这个插件还会不会继续工作？
对人类开发者，这些只是工程工作；对 Agent，这意味着每次都重新支付一遍认知成本：
读文档 → 查源码 → 找例子 → 猜 API → 写一点 → 跑一下 → 出错 → 再查 → 再试
为什么每一个 Agent，都要重新付一遍？
官方其实已经把方法论给齐了：docs/cordis-tutorial 七章从零教程、docs/cookbook 实操配方、docs/capability-seams 能力接缝全图。但教程教「怎么写」，不会替你盯住「这个接口现在到底是什么」——契约变化、易错点、发布门槛，每个 Agent 还是会各自重新踩一遍。
Maker 的差异化不是再写一遍教程，而是把教程机器化：教程里的契约 → check 规则，骨架 → scaffold 模板，装机步骤 → vet/adopt，官方文档地图 → 向导 references。它管理「插件化自由」带来的工程成本——不是单纯帮 AI 写插件，它更关心：这个东西到底应不应该成为插件。
核心原则
① Reuse before invent——在写之前，先问一次：真的需要写吗？
本机已经有？ → 生态已经有？ → DSH 原生已支持？ → 行业有更成熟做法？ → 最后才问：值不值得自己造？
开放生态最容易出现的问题，是插件越来越多、真正需要的能力却越来越不清楚。所以 Maker 最重要的结果有时不是「这是一个新插件」，而是：「不用做，底座已经解决了。」 一个好的开发工具，不应该只会告诉 Agent「怎么做」，还应该允许它明确地说「不需要做」。判据不只是「有没有」，还包括**「能不能接进你自己的工程运行链路」**——轮子存在但接不进你的实际流程，重合部分复用、接不上的缺口最小自建。
② 模型负责需要判断的事，确定性机制负责不值得消耗模型智能的事。
固定的目录结构、入口形式、导出要求、bundle 配置、已验证的 API 契约——这些如果每次都让模型自由生成，就等于每次都重新犯错的机会。于是：
| 机制 | 干什么 |
|---|
| Scaffold | 生成已验证的骨架，而不是从空目录开始猜 |
| Check | 把已知的 Harness 契约变成静态检查（含跨版本迁移事实卡：如 0.1.2 的 apiProxy 移除、0.1.3 的 SessionHandle/格式 v2，⚠️ 提示迁移路线） |
| Vet | 第三方插件先体检，而不是接进去再试错 |
| Adopt | 少量安全、确定性的修改直接自动应用 |
| Impact | 变更前扫引用关系，减少「我好像没影响别处」的猜测 |
| Surface | 工具面诊断：这个插件该不该把原语收窄成语义操作（判据是稳定组合，不是数量；结论可以是不建议） |
| Upstream | DSH 还在快速变化——盯住官方挂点，变了自动报警，不假设今天能跑明天就能跑 |
这些都不是凭空发明：scaffold、static check、codemod、dependency update、impact analysis 在传统软件工程里早有成熟先例。真正有意思的是，它们现在被重新放进一个可以自主行动的 Agent Harness 里。传统工程默认「人知道该怎么做，工具帮他做得更快」；Agent 工程多了一个问题：Agent 本身也需要被约束在正确的工程路径上。 Maker 试图解决的正是后者：不是让模型更聪明，而是减少它因环境不可靠而失去原有能力的机会。
怎么用
- 生成：
plugin_maker_scaffold —— 插件名 + 一句话描述，生成合规骨架。
- 校验：
plugin_maker_check —— 契约（bundle/自注册/id=包名/required）、发布合规、升级基线、跨版本迁移事实卡（0.1.2 破坏性变更 + 0.1.3 SessionHandle/格式 v2 ⚠️；升级前跑一遍，⚠️ 项即待迁移点），一目了然。
- 诊断工具面：
plugin_maker_surface —— 这个插件注册了多少模型可见工具、哪些像实现原语、值不值得收窄成语义操作。判据是有没有稳定组合；结论可以（而且经常应该）是「不建议做」。设计依据与实测证据见 docs/why-facade-cannot-hide-tools.md 与 docs/surface-evidence.md。
- 装：
pnpm pack + dsh plugin --profile web add；上生产前可用 scripts/verify-plugin.ps1 在一次性 profile 里隔离验证。
向导：两个自带 skill（/ 斜杠菜单可触发，模型也会按触发词自动调用）：
/plugin-studio-wizard —— 需求满足向导：先听懂需求（给谁用 × 为什么造两个前置问）→ 满足途径判断（本机已装 → 生态现成 → 自建），能推荐现成就不造；自建才走形态推导 → 调研 → 方案合规 → 交付。判断归向导，授权归用户。/five-step-research —— 分类调研（平台能力/同生态/行业参照/工程实践/需求验证）。
单独使用
maker 是纯开发期工具：七个工具 + 两个 skill 全部无硬依赖、独立可用；动作清单里的协作条目（跨会话协同）在未安装对应协作插件时自动隐藏。check/vet/surface 对任何插件目录工作（不只 maker 生成的）：vet 会附「挂靠建议」——插件用了哪些官方协议面、建议挂哪些上游路径（帮助形态，不代写）；surface 会出工具面诊断与（可选）起步声明。上游盯梢自动化默认日更（cron 频率可自改），没变化就零输出零提交。详见 docs/standalone.md 与 docs/upstream-watch.md。
为什么现在开源
Maker 已经完成了自己的一次解耦：它最初和作者的一些配套机制深度耦合，如今边界清楚、可以独立安装使用。继续闭门造车很难再获得新信息——它接下来需要的不是作者的更多想法，而是：陌生开发者会怎么使用它？ 他们最需要的是 Scaffold、Check、Vet、Research，还是别的没想到的东西？这些问题只有真实生态能回答。
所以这次开源不是「Maker 已经完成了」，而是：内部实验结束，外部实验开始。
已知缺口与路线
- 现阶段最完善 = 插件形态（生成 + 校验 + 向导）；workflow / 脚本 / skill / preset 等形态由向导按需求推导，不弹形态菜单。
- 向导以 skill 形态交付：结论以文本呈现、每步末尾一个「对 / 改」确认门（
ask_user_question 交互卡，实机可弹），全程无需额外界面；一步步点选的交互式表单卡片在路线图上，不在当前版本。
- 0.1.2 迁移事实卡已吸收 20 条（数据文件
facts/migrations.mjs，来源逐条标注；apiProxy 与依赖线两条已实测，其余社区验证、待随自测升级 verified 状态）；maker 自身已完成 0.1.2 适配（peer 放宽为 ^ 范围、模板与示例去掉 dsh-client-runtime 引用、自检零命中）；后续版本事实=新增数据段，不改代码。
- 0.1.3-alpha.2 适配：新增 0.1.2→0.1.3 事实段（SessionHandle / Session.events / ctx.agent / report / 格式 v2 / sqlite 后端 / persona 前缀后缀，逐条对照本机安装包实测），上游盯梢钉到
dsh-v0.1.3-alpha.2，挂靠建议清掉已移除的 apiProxy 与 dsh-client-runtime 路径。
目录
lib/ —— 工具（scaffold + check + vet/adopt + checklist + impact + surface）docs/ —— 知识库（独立使用、合规清单、UX 原则、上游盯梢、工具面证据；bugs/ 为历史档案，不再要求新增）skills/ —— 向导 skill + 调研 skill
状态
当前版本以 GitHub tags 为准（2026-08-30 起持续发版；首个公开版本 0.6.0；安装版见 package.json）
安装
pnpm pack && dsh plugin --profile web add file:<本目录>/dsh-plugin-maker-<版本>.tgz
