dsh-plugin-maker —— 插件开发工坊

中文 | English

一切皆插件，但不是所有人都是插件开发者。 —— 这个工坊就是来补后半句的。 先判断什么值得成为插件。 —— 这是它做一切事情的第一原则。

为什么需要它

DeepSeek Harness 的理念是 "Everything is a Plugin"：能力都可以被组合、替换、扩展。但自由是有代价的——插件化把原本由平台承担的工作转移给了使用者：

• 这个需求到底是什么？
• Harness 原生已经支持了吗？
• 社区里有没有现成插件？
• 这个接口现在到底是什么？哪些是固定契约？
• DSH 更新以后，这个插件还会不会继续工作？

对人类开发者，这些只是工程工作；对 Agent，这意味着每次都重新支付一遍认知成本：

▼
text
复制代码
读文档 → 查源码 → 找例子 → 猜 API → 写一点 → 跑一下 → 出错 → 再查 → 再试

为什么每一个 Agent，都要重新付一遍？

官方其实已经把方法论给齐了：docs/cordis-tutorial 七章从零教程、docs/cookbook 实操配方、docs/capability-seams 能力接缝全图。但教程教「怎么写」，不会替你盯住「这个接口现在到底是什么」——契约变化、易错点、发布门槛，每个 Agent 还是会各自重新踩一遍。

Maker 的差异化不是再写一遍教程，而是把教程机器化：教程里的契约 → check 规则，骨架 → scaffold 模板，装机步骤 → vet/adopt，官方文档地图 → 向导 references。它管理「插件化自由」带来的工程成本——不是单纯帮 AI 写插件，它更关心：这个东西到底应不应该成为插件。

核心原则

① Reuse before invent——在写之前，先问一次：真的需要写吗？

▼
text
复制代码
本机已经有？ → 生态已经有？ → DSH 原生已支持？ → 行业有更成熟做法？ → 最后才问：值不值得自己造？

开放生态最容易出现的问题，是插件越来越多、真正需要的能力却越来越不清楚。所以 Maker 最重要的结果有时不是「这是一个新插件」，而是：「不用做，底座已经解决了。」 一个好的开发工具，不应该只会告诉 Agent「怎么做」，还应该允许它明确地说「不需要做」。判据不只是「有没有」，还包括**「能不能接进你自己的工程运行链路」**——轮子存在但接不进你的实际流程，重合部分复用、接不上的缺口最小自建。

② 模型负责需要判断的事，确定性机制负责不值得消耗模型智能的事。

固定的目录结构、入口形式、导出要求、bundle 配置、已验证的 API 契约——这些如果每次都让模型自由生成，就等于每次都重新犯错的机会。于是：

机制	干什么
Scaffold	生成已验证的骨架，而不是从空目录开始猜
Check	把已知的 Harness 契约变成静态检查（含跨版本迁移事实卡：如 0.1.2 的 apiProxy 移除、0.1.3 的 SessionHandle/格式 v2，⚠️ 提示迁移路线）
Vet	第三方插件先体检，而不是接进去再试错
Adopt	少量安全、确定性的修改直接自动应用
Impact	变更前扫引用关系，减少「我好像没影响别处」的猜测
Upstream	DSH 还在快速变化——盯住官方挂点，变了自动报警，不假设今天能跑明天就能跑

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

怎么用

1. 生成：plugin_maker_scaffold —— 插件名 + 一句话描述，生成合规骨架。
2. 校验：plugin_maker_check —— 契约（bundle/自注册/id=包名/required）、发布合规、升级基线、跨版本迁移事实卡（0.1.2 破坏性变更 + 0.1.3 SessionHandle/格式 v2 ⚠️；升级前跑一遍，⚠️ 项即待迁移点），一目了然。
3. 装：pnpm pack + dsh plugin --profile web add。

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

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

单独使用

maker 是纯开发期工具：六个工具 + 两个 skill 全部无硬依赖、独立可用；动作清单里的协作条目（跨会话协同、教训沉淀指引）在未安装对应协作插件时自动隐藏。check/vet 对任何插件目录工作（不只 maker 生成的）：vet 会附「挂靠建议」——插件用了哪些官方协议面、建议挂哪些上游路径（帮助形态，不代写）；上游盯梢自动化默认日更（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）
• docs/ —— 知识库（独立使用、合规清单、UX 原则、上游盯梢、bug 修复档案）
• skills/ —— 向导 skill + 调研 skill

状态

当前版本以 GitHub tags 为准（2026-08-30 起持续发版；首个公开版本 0.6.0；安装版见 package.json）

安装

▼
text
复制代码
pnpm pack && dsh plugin --profile web add file:<本目录>/dsh-plugin-maker-<版本>.tgz