前言¶
DeepSeek Harness（DSH）采用「一切皆插件」的架构，宿主版本迭代快，插件作者往往只能在本机已安装的某一个 DSH 版本上验证 engines.dsh 或 @deepseek-ai/dsh* peer 是否匹配。升级前若未系统比对，可能出现插件在新宿主上直接无法加载；Windows/WSL 下的安装失败还可能留下半成品目录和锁文件。社区插件目录分散在独立站点，与 DeepSeek / 幻方无官方从属关系，宿主内置的 Discover 需要符合官方规范的 format-1 索引 JSON，而不是任意网页链接。
下面介绍维护者 EasonMWS 发布的 dsh-plugin-health（GitHub：EasonMWS/dsh-plugin-health，分类：工作流）。它面向插件作者与日常使用 DSH 的开发者，补齐三类能力：多宿主版本的静态兼容矩阵、经官方校验器验证的 format-1 市场索引构建，以及 Windows/WSL 安装诊断（默认只读）。安装为 DSH bundle 后，还会在 Web 配置里提供「插件健康」界面，把发现项写成可执行的下一步。
这是什么¶
dsh-plugin-health 是同时提供 CLI、可复用 GitHub Action 与 DSH bundle 的工具包。README 说明其按官方 DSH 0.2.1-rc.2 兼容规则与已发布的 @deepseek-ai/dsh-plugin-market-index 校验器构建；npm 包当前版本为 0.3.2（见仓库 package.json），要求 Node.js 20+，engines.dsh 为 >=0.1.0-rc.6 <0.3.0-0。
它不替代 DSH 自带的插件管理器，也不提供官方应用商店；而是帮助你在升级宿主、维护插件仓库或自建「发现」索引源时，用与宿主一致的语义做检查与产出物。
核心功能¶
多宿主兼容矩阵¶
matrix 子命令根据插件 manifest（engines.dsh 优先，否则检查 @deepseek-ai/dsh / @deepseek-ai/dsh-* peer，含 prerelease 与 workspace: 映射）判断插件在多个 @deepseek-ai/dsh 版本或 dist-tag（latest、next、alpha 等）上是否应能加载。README 明确说明：矩阵是静态评估，尚未对每个宿主做真实启动挂载；Git 源插件可用本地目录路径作为 spec 检查。
输出包括 matrix.json、matrix.md 及 badges/ 下的 SVG；--fail-on any|none|<host> 可用于 CI 门禁。
官方 format-1 市场索引¶
index 子命令把社区 catalog（当前范围以 npm 已发布条目为主）转成 DSH Plugins → 自定义插件市场 → 发现 → 添加索引源 可接受的 index.json（format 1），并用 @deepseek-ai/dsh-plugin-market-index 校验。维护者在 GitHub Pages 托管的示例如 index.json（README 写明约 300 个插件、每日重建）。索引可附带基于兼容矩阵的健康分、分类与多语言标题描述等字段（详见 README）。
Windows/WSL 安装诊断¶
工具提供只读默认可选的修复路径：处理隔离、残留 cordis.patch.yml、代理/registry、profile 漂移，以及与当前运行宿主版本不匹配的已装插件等（bundle 模式下通过 plugin_health agent 工具与设置 UI 呈现）。
DSH 内的「插件健康」设置 UI¶
以 bundle 安装到 profile 后，DSH Web 端会出现 Settings → 插件健康：无问题时不增加角标或侧栏入口；有问题时在账户菜单上方显示「插件有 N 个问题」并跳转。宿主侧仅提供 loopback 只读快照，插件不修改你的 profile。发现项附带一键修复前会先展示 dry-run 计划。
可复用的 GitHub Action¶
仓库提供 matrix-review.yml。在插件仓库添加工作流后，可在每个 Pull Request 上评论兼容矩阵、生成 job summary 并上传 artifact（示例见 README 中 examples/dsh-compat.yml）。
安装与启用¶
全局 CLI（任选其一）：
npm install -g dsh-plugin-health
在 DSH Web profile 中安装 bundle（同时启用设置 UI 与诊断能力）：
dsh plugin --profile web add dsh-plugin-health
README 另给出从仓库 checkout 后 npm ci 并执行 node bin/dsh-plugin-health.js --help 的方式；需 Node.js 20+。
典型用法¶
升级前批量检查多个宿主版本¶
README 建议在升级到 DSH 0.2.1 前先跑矩阵；其对生态前 120 个插件的扫描示例显示，有 3 个会因精确 pin @deepseek-ai/* peer 而在 0.2.1-rc.2 上无法加载（完整说明见仓库 docs/upgrade-0.2.1.md）。
dsh-plugin-health matrix \
--plugins examples/plugins.txt \
--versions latest,next,alpha,0.1.7-rc.2 \
--out dsh-health-out/matrix \
--fail-on any
--plugins 可为每行一个 spec 的文件（支持 # 注释）、逗号列表或重复 flag；spec 为 name、name@version 或本地插件目录。
在插件 PR 上自动贴兼容矩阵¶
将 README 中的示例复制为 .github/workflows/dsh-compat.yml，并按需调整 plugins 与 versions：
name: dsh plugin compatibility
on: pull_request
permissions:
contents: read
pull-requests: write
jobs:
matrix:
uses: EasonMWS/dsh-plugin-health/.github/workflows/matrix-review.yml@v0.1.5
with:
plugins: '.'
versions: 'latest,next,alpha'
comment: true
从 catalog 生成可导入 DSH 的索引¶
dsh-plugin-health index \
--catalog https://awesome-dsh-plugin.com/plugins.json \
--host 0.2.1-rc.2 \
--index-url https://easonmws.github.io/dsh-plugin-health/index.json \
--matrix dsh-health-out/matrix/matrix.json \
--limit 300 --out site
将 site 目录托管到静态站点（无重定向），把 index.json 的 URL 填入 DSH 发现页的索引源即可。
适用场景与注意¶
适合：维护 npm 或本地目录中的 DSH 插件、需要在多个宿主版本或 dist-tag 上做发布前检查的团队；希望自建 format-1 索引供 Discover 使用的社区维护者；在 Windows/WSL 上排查安装残留的用户；希望在 PR 流程中固定兼容矩阵门禁的仓库。
请注意：
- 兼容矩阵基于 manifest 与官方规则，不能替代真实启动冒烟测试（README 将其列为 roadmap）。
index当前主要处理 catalog 中的 npm 条目；仅 GitHub/tarball 的条目会被跳过并在报告中说明。- DSH 插件以当前 dsh 进程权限运行。安装任何第三方 bundle 前，应自行查看源码、许可证（本仓库为 MIT）与维护者信息，确认符合你的安全与合规要求。
结尾¶
dsh-plugin-health 把「能否在这个 DSH 版本上加载」「能否生成宿主认可的发现索引」「本机安装是否干净」三件事收敛到同一套 CLI、bundle UI 与 GitHub Action 里，减少只靠本机单一版本试错的成本。
- SkillHub 目录页：https://www.skillhub.cn/plugins/EasonMWS/dsh-plugin-health
- 源码与文档：https://github.com/EasonMWS/dsh-plugin-health
- npm：
dsh-plugin-health
