插件仓库体检 Tim-ReJet/dsh-plugin-doctor

dsh-plugin-doctor

一个 DeepSeek Harness 宿主插件兼命令行工具，用来对照 dsh-plugin 目录对提交内容强制执行的机械规则，审计仓库——这些规则，仓库可能在维护者读到它之前很久，就已经悄悄满足，或者悄悄违反了。

它注册一个面向模型的工具 plugin_doctor，并把同一套引擎打包成命令行工具。两者都是只读的：不会向被审计的仓库写入任何内容，除非 network 为 true，否则不会发起任何网络请求。

检查哪些内容

最多运行十五项检查。具体跑哪些，取决于仓库声明了什么——没有可解析清单的仓库跑得更少——其中两项只在条件成立时运行（补丁位于包目录之外，或者 peer 范围超出本检查器的建模能力）。

| 检查 id | 失败级别 | 读取内容 |
| manifest.package-json | error | 清单存在且可解析——根 package.json，或者声明了 dsh.bundle 的子包 |
| manifest.bundle | error | 声明了 dsh.bundle.patch——只声明 dsh.client 的包装不出任何可安装的东西 |
| manifest.bundle-patch-file | error | 声明的补丁文件存在、是文件、非空 |
| manifest.bundle-patch-location （条件性） | warn | 补丁位于包目录内，因此会随包一起发布 |
| manifest.bundle-patch-rows | error | 补丁是顶层 YAML 序列，其行是 id/name 对，且至少有一行指向本包 |
| manifest.peer-dependencies | warn | 没有官方 @deepseek-ai/ 包落在 dependencies 而不是 peerDependencies 里 |
| manifest.peer-prerelease | error | 每个 @deepseek-ai/dsh peer 范围都接受当前使用的 harness 构建，含预发布门槛；检测不到 harness 版本时，退回到结构性检查并说明这一点 |
| manifest.peer-range-parsed （条件性） | warn | 某个 peer 范围用了本检查器无法建模的语法（它会说明这一点，而不是瞎猜） |
| repo.age | error | 最早的根提交至少已有一天，从 git 历史读取 |
| repo.implementation | error | 清单目录中存在实现文件，通过 main、bin、exports、files，或 src/lib/index. 兜底路径找到 |
| packaging.meta-bundle | warn | 该 bundle 既发布补丁，又有自己的行为；仅有一份依赖列表不算 |
| description.substance | error | package.json 带有 description |
| description.marketing | error | description 说明插件做什么，而不是夸它（词表启发式） |
| packaging.repository | warn | 声明了 repository 且指向本仓库，或者说明没有 origin remote 就无法确认 |
| repo.topic | error | GitHub 仓库带有 dsh-plugin topic（需要 --network，否则报告为已跳过） |

每次失败都会给出具体修复方法。没有检查失败时，命令行工具退出码为 0（并且在 --strict 下，没有警告会失败），有一个失败时返回 1，用法错误时返回 2。

安装

发布到 npm 后，装进某个配置档：

dsh plugin --profile web add dsh-plugin-doctor

在 npm 发布之前，从本仓库安装：

dsh plugin --profile web add github:Tim-ReJet/dsh-plugin-doctor

两种方式都会把 bundle 层追加到该配置档的 dsh.profile.bundles；这一层会插入一行名为 plugin-doctor 的 host 行。确认这一层已组合：

dsh --profile web --dump-config | grep -A 3 plugin-doctor

如果要在本地针对源码检出做开发，跳过安装，用 patch overlay 加载入口点：

doctor.overlay.yml
- insert:
- id: plugin-doctor
name: '/absolute/path/to/dsh-plugin-doctor/src/index.js'
config:
path: '/absolute/path/to/the/repository/you/are/auditing'

dsh --profile web --patch ./doctor.overlay.yml

使用

只要插件已组合，在任何会话里都能用这个工具：

对这个仓库运行 plugin_doctor，然后修掉它报告的问题。

它返回 ok、errors、warnings 和 report。它的 path、strict、network 参数默认取 cordis.patch.yml 里的行配置。

命令行方式，从检出目录运行——无需安装：

node bin/dsh-plugin-doctor.mjs [path]

| 参数 | 作用 |
| --strict | 把警告也算作失败，计入退出状态 |
| --network | 校验 dsh-plugin GitHub topic（一次 GitHub 请求，走 gh 或 GH_TOKEN） |
| --harness-version <version> | 用指定的 harness 构建来测试 peer 范围，而不是自动检测 |
| --now <iso-date> | 覆盖时钟，用于仓库年龄检查（测试辅助） |
| --json | 把完整结果以 JSON 打印 |
| --verbose | 连通过的检查也一并列出 |
| --emit-entry | 打印目录期望的 data/plugins/<owner>__<repo>.yml 条目 |

--emit-entry 始终给描述加单引号并转义，因为裸标量遇到冒号、遇到 #（会被静默截断）、遇到 @ 这类开头的 YAML 指示符都会出错。在 monorepo 里，它会把条目指向声明了 dsh.bundle 的子包。

这个工具要解决的预发布陷阱

可安装插件的 peer 依赖指向 harness 包。几乎所有看起来正确的范围，对预发布版 harness 都是错的，因为 node-semver 只有在匹配分支的某个比较符于同一个 major.minor.patch 元组上带预发布标签时，才承认预发布版本：

// looks broad, silently excludes every 0.1.1- and 0.2.0-* build
"@deepseek-ai/dsh-tools": ">=0.1.0-rc.1 <0.3.0-0"
"@deepseek-ai/dsh-tools": "*"

// admitted: the branch names the tuple with a prerelease tag
"@deepseek-ai/dsh-tools": ">=0.1.1-rc.1 <0.1.2-0 || >=0.2.0-rc.1 <0.2.1-0"

manifest.peer-prerelease 会报告这两种失败里中的哪一种。这个检查器不是 semver 实现：它建模 caret、tilde、hyphen、x-range 和比较运算符，它的预期答案以 node-semver 自身为准，对应 tests/fixtures/node-semver-table.json 中记录的 450 组（range, version）配对。凡是它解析不了的内容，一律报告为 manifest.peer-range-parsed，绝不猜测。

它查不了什么

- 插件是否名副其实。 这要靠维护者读源码，任何检查器都替代不了。别把一次干净的运行当成这种审查。
- 安全性。 被收录不等于过了安全审查，这份审计也不是。审计读的是 manifest 和结构，不是行为。
- 提交面的其余部分：--emit-entry 打印之外的入口文件、screenshots.json 规则、tarball 托管规则，以及 bundle 的依赖是否指向原作者仓库而非二次上传。
- 代码是真是假，还是空壳。 一个什么都不导出的文件，在这里照样算实现文件。
- 分类是否合适，或者插件是否与已有条目重复。
- 项目是否在积极维护。 目录的定期扫描会标记已消失、已归档或长期沉寂的仓库；这份审计只读某一时刻的快照。
- npm 发布与下载量。 收录与否不看这些。

验证

- npm test 在 node:test 上跑 40 个测试，不联网：fixture 是临时目录里的一次性仓库，prerelease 门禁对照记录的 node-semver 表检查。包没有声明任何 dependencies —— 审计引擎和命令行都不需要；宿主插件需要它声明的 peer，当这些 peer 无法解析时，四个宿主插件测试会跳过。
- 仓库自审零错误，只有 repo.age 例外，它在仓库满一天之前一直失败 —— 这是目录自己的规则。所以 npm run doctor 今天退出码是 1，明天是 0；有个测试把时钟拨过门禁，覆盖同一次运行。
- 端到端，在真实 harness 中组合插件并由模型调用工具：已在 harness 0.1.1-rc.2 和 0.2.0-rc.2 上验证，这正是它 peer range 指定的两条线。
- 安装路径在 2026-10-04 手工走通，可用 npm run verify:install 复现（需要联网）：它把 github:Tim-ReJet/dsh-plugin-doctor 装进一次性配置档，检查 bundle 层已组合，然后删掉配置档。没有自动化测试覆盖它。

Peer 依赖

@deepseek-ai/dsh-tools 和 @deepseek-ai/schemastery 是 peerDependencies，所以配置档各提供一份；@deepseek-ai/cordis 是稳定的 4.x 线，声明为 ^4.0.1。harness range 按目录要求，为每个元组指定一条明确的 prerelease 分支。

如何被收录

目录是 awesome-dsh-plugin/awesome-dsh-plugin； contributing.md 就是这个插件检查的契约。上架只需要在 pull request 里提交一个文件——data/plugins/<owner>__<repo>.yml，用 --emit-entry 就能打印出来——再加上仓库上的 dsh-plugin 话题，以及仓库至少创建满一天。

dshmarket 只安装这份精选注册表里列出的来源，所以光带话题只能让仓库在话题下被搜到，没法从市场安装。

License

MIT