插件兼容预检FATE213/dsh-plugin-compat-check

dsh-plugin-compat-check

DSH 插件 × DeepSeek Harness 兼容性预检工具 —— 更新任何 DSH 插件之前，先跑它，避免装上一个与当前 Harness 不兼容的插件把配置档搞坏。

背景：@nanmicoder/dsh-agent-teams@0.1.15 的 peer 要求 @deepseek-ai/dsh-@^0.1.2-alpha.2，而当时 Harness 只提供 0.1.1-rc.2（0.1.1 @ 换成你要检查的插件；如遇执行策略限制：Set-ExecutionPolicy -Scope Process Bypass）
.\check-plugin-compat.ps1 -Specs '@'
例如：.\check-plugin-compat.ps1 -Specs 'some-plugin@1.2.3'（一次可检查多个，逗号分隔）

方式二：把链接喂给 DeepSeek（推荐给 DSH 用户）

你是 DeepSeek Harness（DSH）用户的话，不用自己跑命令——直接在 DSH 会话里把链接发给 agent 即可：

用 https://github.com/FATE213/dsh-plugin-compat-check 这个仓库，帮我预检
some-plugin@1.2.3 和 another-plugin@latest 是否与当前 DeepSeek Harness 兼容。
（插件名换成你实际想检查的）

Agent 会自己完成：读取 README 和脚本 → 克隆/下载仓库 → 在本机检测已安装的 Harness 版本 → 运行预检 → 给出 [OK] / [INCOMPATIBLE] 结论和原因。

要求：本机需已全局安装 DeepSeek Harness（npm i -g @deepseek-ai/dsh）和 Node.js/npm（agent 检测不到会告诉你）。

脚本参数速查
powershell
检查指定候选版本（逗号分隔 name[@version]，换成你要检查的插件）
.\check-plugin-compat.ps1 -Specs '@,@'

检查默认 web 配置档当前已装的插件
.\check-plugin-compat.ps1

指定其他配置档
.\check-plugin-compat.ps1 -Profile "$env:USERPROFILE\.dsh\profiles\dsh-tui"

输出示例（真实案例，仅演示输出格式；检查对象以你实际要更新的插件为准）

========== Plugin x DeepSeek Harness compatibility pre-check ==========
DeepSeek Harness : 0.1.1-rc.2
Harness location : C:\Users\xxx\AppData\Roaming\npm\node_modules\@deepseek-ai\dsh
Node             : 24.19.0

[INCOMPATIBLE] @nanmicoder/dsh-agent-teams@0.1.15
installed: 0.1.14
@deepseek-ai/dsh-agent   0.1.1-rc.2   ^0.1.2-alpha.2   FAIL (harness provides 0.1.1-rc.2, outside range ^0.1.2-alpha.2)
@deepseek-ai/dsh-session 0.1.1-rc.2   ^0.1.2-alpha.2   FAIL (harness provides 0.1.1-rc.2, outside range ^0.1.2-alpha.2)
...

Pre-check FAILED: 1 candidate(s) incompatible with the current Harness - do NOT update.

判定规则

1. 读取候选插件声明的 peerDependencies（重点 @deepseek-ai/）与 engines.node。
2. 把 Harness 实际提供的版本（如 0.1.1-rc.2）剥离 prerelease（→ 0.1.1），用 semver 数值窗口判断是否落在插件声明的版本区间内：
- ^0.1.0-rc.6 → 窗口 0.1.0, 0.2.0) 包含 0.1.1 → OK
- ^0.1.2-alpha.2 → 窗口 [0.1.2, 0.2.0) 不含 0.1.1 → FAIL
3. 任一 peer FAIL → 整包判 INCOMPATIBLE。
4. Harness 未提供的 @deepseek-ai/* peer → WARN（宿主运行时常注入这些客户端包，缺了不一定坏，但属于“面向更新 Harness 编写”的信号，需人工确认）。
5. engines.node 不满足 → FAIL。

退出码

| 码 | 含义 | 动作 |
|---|---|---|
| 0 | 全部通过（或仅有 WARN 需人工确认的 REVIEW） | 可以更新 |
| 1 | 存在 INCOMPATIBLE | 禁止更新 |
| 3 | 存在 UNKNOWN（npm 元数据没拉到） | 不得当通过，重试或修复网络 |

更新后的验证
powershell
pnpm --dir "$env:USERPROFILE\.dsh\profiles\web" outdated        # 应为空 {}
pnpm --dir "$env:USERPROFILE\.dsh\profiles\web" peers check      # 无冲突
.\check-plugin-compat.ps1                                         # 已装版本全部 OK/REVIEW

完整流程见 [PLUGIN-UPDATE-GUIDE.md。

已知限制

- peer 范围判定采用“数值窗口”启发式（Harness 版本剥离 prerelease 后求值），与实际运行时的 API 兼容性可能不完全一致；遇到 WARN 请人工确认。
- 在受文件沙箱限制的环境里，npm 元数据拉取可能间歇性失败；此时已装插件仍可用磁盘读取判定，新候选需等网络可用后重试（退出码 3 会明确提示）。
- 插件市场（dshmarket）UI 的“更新”按钮不经过本预检：市场只做发布年龄、禁止降级、装完试启动回滚等检查，不会比对 peerDependencies 与已装 Harness 的兼容性，可能装上不兼容的插件。建议：在 DSH 会话里让 agent 先跑本脚本预检，再更新；或更新前手动跑一次。

许可证

MIT