前言¶
在 DeepSeek Harness（DSH）里做 bundle 插件，常见摩擦不在「能不能写工具」，而在三个时间点：从零开目录时缺 manifest、patch、测试与 CI；本地能跑，贴进 Plugins 却被 incompatible-version 或 patch 结构挡住；别人给的 npm 包或 GitHub 链接，装进 profile 前没有只读手段先看 tarball 哈希、install 脚本与兼容性。手动对照 @deepseek-ai/dsh-app-boot 的规则既慢又容易漏。
下面介绍维护者 Joker2377 发布的 dsh-plugin-devkit（GitHub：Joker2377/dsh-plugin-devkit，社区目录分类 admin-security）。它是纯 host 端插件：没有 UI、没有常驻服务、不改 profile，提供三支工具对应插件生命周期的三个时刻，同一套逻辑也包成 CLI，不安装 DSH 插件也能在取得源码后用 node scripts/cli.mjs 调用。
这是什么¶
一句话：用一个指令生成可测试的插件骨架，用 doctor 复现 DSH 安装时的结构与兼容性判定，用 audit 在把别人包装进 profile 之前做只读供应链核查。
| 工具 | 作用 |
|---|---|
plugin_scaffold |
开插件骨架；产物预期能跑、能过测试、能通过 doctor |
plugin_doctor |
读本地目录，说出 DSH 安装时会被哪一条拦下 |
plugin_audit |
读已发布包 spec，判断现在装进 profile 是否合理 |
运行环境要求（README 原文）：Node.js >=22.19，DeepSeek Harness >=0.1.1-rc.2 <0.3.0；纯 JavaScript，无原生模块。包版本在 package.json 中为 0.2.0，许可证 MIT。
核心功能¶
骨架一次到位¶
plugin_scaffold 会产出 package.json（含 dsh.bundle.patch）、cordis.patch.yml、入口 lib/index.js、工具定义 lib/tools.js、示例测试 test/bundle.test.mjs、面向使用者的 README.md、LICENSE、.gitignore 以及 .github/workflows/test.yml。骨架自带一个工具与测试，README 说明 npm test 不需安装依赖即可通过。目标文件已存在时默认跳过并回报，可用 dryRun 先看会写哪些文件。
与 DSH 安装一致的 doctor¶
plugin_doctor 只读检查 manifest、patch（含 insert 合法性）、入口 apply、README 是否含安装段、LICENSE、测试与 CI 等。兼容性规则与 host 一致：存在 engines.dsh 时只看它；否则逐条检查 @deepseek-ai/dsh* peers；prerelease 参与比较（例如 0.3.0-rc.5 落在 <0.3.0 内）。未传 hostVersion 时不做兼容性判定。
安装前 audit（供应链）¶
plugin_audit 回答「别人写的包现在装进我的 profile 可不可以」：比对 tarball 哈希、扫 install 脚本（含 tarball 内依赖的 preinstall / install / postinstall）、依赖面与 provenance、判 engines.dsh 兼容性、比对 profile 内版本等。只读：不写文件、不安装、不执行包代码。allow 只代表已核查的供应链信号对得上，不代表代码无恶意行为。
安装与启用¶
官方方式是在 DSH 侧边栏 Plugins 贴仓库首页网址并 Install，然后重新加载 App。步骤如下。
1、复制仓库网址：
https://github.com/Joker2377/dsh-plugin-devkit
2、在 Plugins 安装栏贴上上述网址，按 Install。
3、重新加载 App 后，对话中可使用 plugin_scaffold、plugin_doctor、plugin_audit。
注意：须贴仓库首页网址；形如 https://github.com/.../tree/main 的页面会被拒绝（a URL must point at a git repository or a tarball）。
不安装插件时，在取得源码后可用：
node scripts/cli.mjs doctor <目录>
node scripts/cli.mjs audit <spec>
CLI 与三支工具共用同一核心；也可使用 bin 名称 dsh-plugin-devkit（见 README 命令行一节）。
典型用法¶
开一个新插件¶
在对话中请 agent 使用 plugin_scaffold 建立例如 dsh-foo，确认名称与目录后，先做本地验证：
cd dsh-foo
npm test
node scripts/cli.mjs doctor .
再将 lib/tools.js 中的示例工具换成实际需求，在 README 安装段补上你的仓库网址，推送到 GitHub 后即可用相同「贴首页 URL」方式分发。
命令行等价示例：
dsh-plugin-devkit scaffold dsh-foo --desc "一行说明" --author "你的名字"
dsh-plugin-devkit scaffold dsh-foo --dry-run
检查本地 bundle¶
工具调用示例（README）：
plugin_doctor(dir: "C:/path/to/dsh-foo", hostVersion: "0.2.1-rc.5")
命令行：
dsh-plugin-devkit doctor . --host-version 0.2.1-rc.5
dsh-plugin-devkit doctor . --json
结束码：0 通过，1 有 error，2 指令本身失败。
安装前核查远端包¶
适用时机包括：贴未知 npm 或 GitHub 插件进 Plugins 前、大版本升级前、或收到 github:owner/repo 想先看兼容性。
node scripts/cli.mjs audit lodash@4.17.21
node scripts/cli.mjs audit dsh-foo-bar@^0.2 --host=0.2.1-rc.5 --json
node scripts/cli.mjs audit github:owner/repo --registry=https://registry.npmmirror.com
audit 结束码：0 allow，1 block，2 参数或环境问题，3 not-audited（例如部分 spec 无 registry 侧数据，不能当成通过）。报告第一行为 spec，第二行为 可以安装 / 不可以安装 / 未核查；未给 hostVersion 且环境无 DSH_VERSION 时，兼容性项目不会被算作通过。
适用场景与注意¶
适合谁： 正在维护 DSH bundle 插件的开发者，以及需要在 profile 里引入第三方包、希望先对齐 DSH 安装规则与基本供应链信号的管理员场景。
权限与信任： 与其他 DSH 插件一样，devkit 在当前 DSH host 进程权限下运行；plugin_audit 虽不执行对方代码，但会从 registry 读取 tarball。安装任何插件前仍应自行查看源码与 LICENSE，并理解 audit 的界限（非沙箱、非完整恶意代码分析）。
疑难排解（README 摘要）： DSH 沙箱内若 npm test 出现 spawn EPERM，可改 npm run test:sandbox 或直接 node test/bundle.test.mjs；安装被拒 incompatible-version 时，用 plugin_doctor(hostVersion: ...) 对照是哪一条范围；工具未出现时确认已重载 App 并用 doctor 检查 patch insert。
结尾¶
dsh-plugin-devkit 把「开骨架、对齐安装规则、装别人包前先读 registry」收进三支 host 工具与同一 CLI，规则来源对应 DSH 实际的 unmetRequirements() 与 bundle patch 检查，而不是主观 lint 清单。
