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、static check、codemod、dependency update、impact analysis 在传统软件工程里早有成熟先例。真正有意思的是，它们现在被重新放进一个可以自主行动的 Agent Harness 里。传统工程默认「人知道该怎么做，工具帮他做得更快」；Agent 工程多了一个问题：Agent 本身也需要被约束在正确的工程路径上。 Maker 试图解决的正是后者：不是让模型更聪明，而是减少它因环境不可靠而失去原有能力的机会。

怎么用

1. 生成：plugin_maker_scaffold —— 插件名 + 一句话描述，生成合规骨架。
2. 校验：plugin_maker_check —— 契约、发布合规、升级基线、跨版本迁移事实卡（⚠️ 项即待迁移点），升级前跑一遍。
3. 接盘（改别人的插件时）：plugin_maker_vet 出可照做的改造清单 → plugin_maker_adopt 自动应用其中安全、确定的那部分。
4. 诊断工具面（可选）：plugin_maker_surface —— 注册了多少模型可见工具、哪些像实现原语、值不值得收窄；propose:true 会附上候选操作的起步声明。判据是有没有稳定组合，结论可以（而且经常应该）是「不建议做」。设计依据与实测证据见 docs/why-facade-cannot-hide-tools.md 与 docs/surface-evidence.md。
5. 装：pnpm pack + dsh plugin --profile web add；上生产前用 scripts/verify-plugin.ps1 在一次性 profile 里隔离验证（组合 + 真机 boot），不会碰你正在用的 profile。

向导：两个自带 skill（/ 斜杠菜单可触发，模型也会按触发词自动调用）：

• /plugin-studio-wizard —— 需求满足向导：先听懂需求（给谁用 × 为什么造两个前置问）→ 满足途径判断（本机已装 → 生态现成 → 自建），能推荐现成就不造；自建才走形态推导 → 调研 → 方案合规 → 交付。判断归向导，授权归用户。
• /five-step-research —— 分类调研（平台能力/同生态/行业参照/工程实践/需求验证）。

边界：Maker 不做什么

• 不是自动生成器：需求、架构、形态由向导和你一起定，Maker 不替你决定。
• 不做运行时收窄：facade 藏不掉已经暴露的工具（DSH 用单一视野解析器做呈现/查找/派发），所以 surface 只诊断、不改写。证据见 docs/why-facade-cannot-hide-tools.md、docs/surface-evidence.md。
• 不沉淀教训/踩坑记录：运行期错误与经验归 dsh-retro；那类记录会随版本过期变有害。Maker 对 bug 的要求只有一条机器可验证的——修复同一 commit 带回归测试。
• 不碰 preset / cordis 组合、动态 Cordis 插件：那是运行时组合层与会话层的活。Maker 只管常驻插件包（可发布、可验证、跟得上上游）与 skill / 脚本 / 工作流。

单独使用

maker 是纯开发期工具：七个工具 + 两个 skill 全部无硬依赖、独立可用；动作清单里的协作条目（跨会话协同）在未安装对应协作插件时自动隐藏。check / vet / surface 对任何插件目录工作（不只 maker 生成的）：vet 会附「挂靠建议」——插件用了哪些官方协议面、建议挂哪些上游路径（帮助形态，不代写）。详见 docs/standalone.md 与 docs/upstream-watch.md。

为什么现在开源

Maker 已经完成了自己的一次解耦：它最初和作者的一些配套机制深度耦合，如今边界清楚、可以独立安装使用。继续闭门造车很难再获得新信息——它接下来需要的不是作者的更多想法，而是：陌生开发者会怎么使用它？ 他们最需要的是 Scaffold、Check、Vet、Research，还是别的没想到的东西？这些问题只有真实生态能回答。

所以这次开源不是「Maker 已经完成了」，而是：内部实验结束，外部实验开始。

已知缺口与路线

• 现阶段最完善 = 插件形态（生成 + 校验 + 向导）；workflow / 脚本 / skill 等形态由向导按需求推导，不弹形态菜单。preset / cordis 组合与动态 Cordis 插件不在 maker 范围内（见上「边界」）。
• 向导以 skill 形态交付：结论以文本呈现、每步末尾一个「对 / 改」确认门（ask_user_question 交互卡，实机可弹），全程无需额外界面；一步步点选的交互式表单卡片在路线图上，不在当前版本。

目录

• lib/ —— 七个工具（scaffold / check / vet / adopt / impact / checklist / surface）
• skills/ —— 向导 skill + 调研 skill
• facts/ —— 跨版本迁移事实卡（check 的数据源，逐条标注来源、可实测复核）
• scripts/ —— 上游盯梢 + 隔离验证脚本
• docs/ —— 知识库（独立使用、合规清单、UX 原则、上游盯梢、工具面证据；bugs/ 为历史档案，不再要求新增）

安装

pnpm pack && dsh plugin --profile web add file:<本目录>/dsh-plugin-maker-<版本>.tgz

状态

当前版本以 GitHub tags / Releases 为准（2026-08-30 起持续发版，首个公开版本 0.6.0；逐版本变更见 Releases）。跨版本迁移事实卡随 DSH 版本更新，不改代码只加数据段。