RFC: official plugin scaffold — template repo + pnpm create dsh-plugin to unblock the ecosystem

[zoahdev]

CONTRIBUTING.md encourages community plugins and states community packages are as important as official ones. The publish guide describes the bundle format well, but the manual setup still creates real friction:

• Plugin authors must hand-write package.json (dsh.bundle manifest), cordis.patch.yml, prepare script, tsconfig, and tests with no official starting point. The publish guide points to turtle-ui as an example, but there is no canonical template.
• Version-train confusion is blocking people in practice: @deepseek-ai/dsh-tools's npm latest points at the broken 0.0.1-rc.1 train (see discussion dsh-type-meta is missing from npm, blocking pnpm installs for community plugin development #984), while the working release is 0.1.0-rc.6. A scaffold that pins the current train would have prevented this class of failure.
• The ecosystem already has 1700+ plugins (per discussion DSH 插件已经 1700+ 了,怎么快速找到「适合我」的那一个? #1597) but no consistent layout, which makes review/discovery/reuse harder.

Proposed scope (MVP)

1. Official template repository (under deepseek-ai or a documented community org) containing:
   • package.json with dsh.bundle.patch manifest, prepare build script, files allowlist;
   • cordis.patch.yml plugin row;
   • one minimal defineTool example with schema, render, presentCall, and exec.signal handling;
   • vitest example + one smoke test;
   • bilingual README with install/publish instructions;
   • CI that runs pnpm build, pnpm test, and a dsh plugin --profile web add . smoke load.
2. Optional pnpm create dsh-plugin scaffolding CLI that generates the above and pins peer versions to the current release train.
3. A short "plugin checklist" doc (naming, dsh-plugin topic, version pinning, README requirements).

Why now

The project is in a fast-iteration developer preview with huge early community energy. A scaffold is cheap to maintain and directly lowers the barrier for the exact contribution path CONTRIBUTING.md asks for.

Happy to help review or test a template if one is created.

[yun520-1]

作为 dsh 插件作者（我们发布了 deepseek-heartflow，197 个工具），这个 RFC 的两个痛点都踩过，支持标准化：

1. 手写 manifest 的真实摩擦：没有官方模板时，dsh.bundle manifest、cordis.patch.yml、prepare 脚本的格式只能靠反推 turtle-ui 示例。我们当时花了一天调试 bundle 格式——不是功能问题，是"格式约定"问题。一个 pnpm create dsh-plugin 脚手架能消灭整类"格式对但结构不对"的失败。

2. 版本火车混乱是真实事故源：我们发布插件时锁 @deepseek-ai/dsh-tools 版本，npm latest 指向的 train 和实际工作版本不一致，导致用户安装后工具调用静默失败（类 #1633 的现象）。脚手架里钉住当前 train 并写入 peerDependencies 范围（比如 >=0.1.0-rc.6 <0.2）能直接预防。

3. 一个 RFC 里没提但值得加的：插件健康检查约定。社区插件质量参差（1700+ 插件），官方脚手架如果能带一个默认的 dsh plugin check（验证 manifest 结构、bundle 可加载、核心依赖版本匹配），会比靠 review 更可扩展——每个插件作者本地就能自检，不用等维护者发现。

另外建议脚手架默认带 2 个文件：一个最小可运行示例（1 个工具，读完就能跑），一个 CI 模板（build + 冒烟加载测试）。示例是文档的替代品——我们写插件时最缺的就是"最小可运行起点"。

[zoahdev]

Thanks for the detailed field report from deepseek-heartflow — "格式对但结构不对" is exactly the failure mode I was worried about, and the version-train silent-failure story (like #1633) makes the case for pinning even stronger.

I went ahead and prototyped the scaffold as a real, verified community template so the RFC has something concrete to react to:

https://github.com/zoahdev/dsh-plugin-template

It includes the two files you suggested: a minimal runnable example (one hello tool with schema, render, presentCall, and cancellation) and a CI workflow that does build → test → pnpm pack → dsh plugin --profile web add → --dump-config → boot dsh web + HTTP check. So "loads in dsh" is proven by CI, not assumed.

On your dsh plugin check idea: I agree it is the scalable answer — a local check (manifest structure, bundle loadability, peer version match) beats maintainer review for 1700+ plugins. Until an official command exists, the template's CI performs exactly those three checks, and the README's publishing checklist mirrors them so authors can self-verify locally:

1. pnpm build + pnpm test pass
2. dsh plugin add + dsh web boot succeed
3. peers pinned to the current train (0.1.0-rc.6)

Happy to fold any of this into an official template if the team picks up the RFC. Also fine to keep iterating on the community version — PRs/issues welcome.

---

谢谢 deepseek-heartflow 的实战反馈！我把 RFC 里的脚手架先做成了一个可运行的社区模板（链接见上），包含最小示例 + CI 冒烟加载。dsh plugin check 的建议非常对，官方命令落地前，模板的 CI 已经在做这三项检查（manifest 结构 / bundle 可加载 / 依赖版本对齐）。

[yun520-1]

模板很扎实，peerDependencies 钉住 ^0.1.0-rc.6 + CI 里 "loads in dsh" 由实际 boot 证明——这正是我建议的核心。补充两个实测中值得注意的细节：

1. ^0.1.0-rc.6 的 caret 对 RC 版本有个 npm 语义陷阱。^0.1.0-rc.6 按 semver 规则等价于 >=0.1.0-rc.6 <0.2.0，看起来合理，但 npm 处理 rc 预发布标签时有个坑：caret 范围不会自动匹配同版本号的预发布。比如用户环境装了 0.1.0-rc.5（比模板钉的 rc.6 低），npm 不会把 rc.5 升级到 rc.6（因为 caret 匹配 >=0.1.0-rc.6 不满足就报 ERESOLVE，而不是自动选一个满足的）。这会导致：用户本地已有旧 RC 时，装插件直接失败，而不是优雅降级。建议在 README 里加一行：如果 ERESOLVE 冲突，先 pnpm add -D @deepseek-ai/dsh-tools@0.1.0-rc.6。

2. CI 的 boot 检查可以加一个"工具可调用"断言。现在的 CI 验证了"插件加载 + web 起来"，但没验证工具真的能调（hello 工具在会话里 call 一次）。加载成功 ≠ 调用成功——我们插件发布时遇到过：manifest 对、加载对，但工具函数里一个运行时错误（引用了一个没打的包），只有真调用才暴露。建议 CI 加一个 headless 调用测试（比如直接 node -e require bundle 后调 hello 的 handler），把"能调"也纳入证明。

模板整体方向完全正确——这两个都是边角优化，不影响核心价值（最小可运行起点 + CI 证明加载）。

[zoahdev]

Following up on the review thread: both concrete pieces are now shipped.

1. dsh plugin check as a real tool — dsh-plugin-doctor

• Checks manifest structure, patch validity, entry points, files allowlist
• --build runs the real build; --full packs, installs into a brand-new DSH_HOME profile, and verifies the plugin id in --dump-config
• --json + exit code for CI; verified --full PASS against the template

2. The template CI now proves real tool callability — dsh-plugin-template

• scripts/integration-test.mjs installs the actual packed tarball, registers hello through apply() / ctx.tools.register, executes the real handler, and asserts Hello, Ada! (plus a guard-rejection scenario against an incompatible older RC)
• scripts/dsh-smoke.sh boots dsh web in a fresh profile (Windows runner; the upstream npm CLI currently lacks the linux-x64 pty.node prebuild — discussion #1686)
• CI is green end to end

On the version-train concern: we verified empirically (pnpm 11) that neither caret nor exact ranges make pnpm auto-upgrade an older RC in the host — it silently links the old version with only a generic warning. The template therefore keeps an honest ^0.1.0-rc.6 range and refuses to load at runtime when the resolved @deepseek-ai/dsh-tools does not satisfy it, so the silent case becomes a loud, actionable error. Full details in the template README Troubleshooting.

Happy to keep iterating — an official dsh plugin check would still be the right long-term home for this logic.