dsh-seam: [插件开发支持工具] DSH 兼容性检查及问题定位

[YMoose]

TL;DR：给 DSH 插件作者用的编译期兼容性检查工具，非 DSH 用户向。使用简单，接入友好。在插件目录跑一行命令，就可检查插件用到的 DSH 接口在新版本下有没有破坏性变更，并定位到源码具体行号。

仓库：https://github.com/YMoose/dsh-seam（MIT）· tested with DSH 0.2.2-rc.1 · npx github:YMoose/dsh-seam#v0.1.0

非官方社区项目，独立开发维护，未经 DeepSeek 官方审核。

---

一、已有工具与 dsh-seam 的定位

围绕 DSH 升级与插件兼容，社区里已经有几件工具，各自负责不同环节：

• dsh-plugin-health（@EasonMWS）：用户侧 / 运行时。在临时目录真装真启动插件，测试升级后还能不能正常加载；另有每日公开兼容表和 PR 兼容矩阵 Action（静态解析 engines/依赖声明生成矩阵，不安装不启动插件）。
• dsh-conservative-upgrade（@oldzhang82）、oh-my-dsh/dsh-plugin-upgrade-skill：用户侧 / 升级流程。提供升级 DSH 时的插件分级排查与回退操作手册。
• dsh-seam（本项目）：插件作者侧 / 编译期。不启动 DSH，从源码与类型定义层面检查“上游改了什么、坏在我源码的哪一行”。

dsh-seam 具体做两件事：

1. scan：从插件源码 AST 提取真实用到的依赖面——读了哪些字段、注入了哪些服务、监听和触发了哪些事件、哪些 as 断言绕过了类型检查——输出报告或生成 coupling.json 契约文件。
2. verify：按这份契约生成类型探针，对已安装的 @deepseek-ai/* 的 .d.ts 做编译检查，上游删字段、把非空改成可空、改事件签名，都会定位回你源码的 file:line。

边界（它不做什么）：

• 不执行插件代码、不启动 DSH，因此纯运行时的问题（时序、逻辑）查不了；
• 无类型标注的动态服务调用不硬报错（避免对合法的跨插件借用误报），改为列入隐含依赖清单，由作者决定是否补运行时测试；
• 启动级冲突（重复注册 id、模块替换）是 dsh-plugin-health 的领域。

两者是互补关系：dsh-plugin-health 回答“还能不能启动”，dsh-seam 回答“坏在我源码哪一行”。能启动不等于没坏——懒加载的命令、稍后才触发的事件回调，启动阶段不一定跑到，类型检查能覆盖全程序的调用面。

---

二、怎么接入使用

1. 本地跑一次检查（零配置）

在插件仓库根目录直接用 npx 跑，不需要改仓库文件：

# 1. 验证：在内存中扫描源码并对照当前安装的 DSH 版本做类型检查，定位破坏点行号
npx github:YMoose/dsh-seam#v0.1.0 verify

# 2. 扫描：查看完整的依赖接口报告 + 绕过类型检查的写法清单
npx github:YMoose/dsh-seam#v0.1.0 scan

# 3. （可选）把 package.json 里整套 @deepseek-ai/dsh-* 对齐到同一版本
npx github:YMoose/dsh-seam#v0.1.0 bump

当上游出现破坏性变更时（例如 @deepseek-ai/dsh-agent 将 Agent.session 从 Session 改成 Session | undefined），verify 的真实报错输出：

packages/socket/coupling.json: 20/24 probes compile clean
  ✖ [auto/field] @deepseek-ai/dsh-agent :: session (at src/sessions.ts:14)
    TS2322: Type 'Session | undefined' is not assignable to type 'Session'.   Type 'undefined' is not assignable to type 'Session'. (line 40)
  ✖ [auto/field] @deepseek-ai/dsh-agent :: session (at src/sessions.ts:41)
    TS2322: Type 'Session | undefined' is not assignable to type 'Session'.   Type 'undefined' is not assignable to type 'Session'. (line 47)
  ✖ [auto/field] event:agent/inbox/inserted :: agent.session (at src/index.ts:121 under payload.message.source.kind='user')
    TS2322: Type 'Session | undefined' is not assignable to type 'Session'.   Type 'undefined' is not assignable to type 'Session'. (line 67)
  ✖ [auto/field] event:agent/pre-step :: agent.session (at src/index.ts:127 under !payload.signal.aborted)
    TS2322: Type 'Session | undefined' is not assignable to type 'Session'.   Type 'undefined' is not assignable to type 'Session'. (line 94)

2. 挂进 CI 持续检查

先在插件目录生成并提交 coupling.json：

npx github:YMoose/dsh-seam#v0.1.0 scan --write
git add coupling.json

然后在 GitHub Actions 里加一步：

- run: |
    npx github:YMoose/dsh-seam#v0.1.0 scan --check
    npx github:YMoose/dsh-seam#v0.1.0 verify

这样每次 PR 都能自动拦住两件事：改了源码但忘了更新依赖契约、或者升级 @deepseek-ai/* 后破坏了插件依赖的接口类型（monorepo 支持加 --recursive 逐包检查）。如果需要连无类型标注的隐含依赖也一并锁住，可以用 sync 把契约测试同步进插件仓库配合单测跑，具体步骤见仓库 README。

---

我自己维护的两个插件（dsh-log-enhance、dsh-editor-socket）已经接入了这套检查。如果在你的插件上跑出误报或漏报，或者有其他 bug 和功能需求，欢迎直接提 issue。

[EasonMWS]

谢谢把两者的边界写得这么清楚——尤其是「能启动不等于没坏」这句。懒加载的命令、稍后才注册的事件回调，运行时确实覆盖不到；这一点我在 dsh-plugin-health 里是明确的盲区，dsh-seam 补的正是这块。

补充几点可能对你有用的事实，也顺便让找过来的人少踩坑。

一处需要修正的描述

并提供每日公开兼容表与 PR 启动测试 Action

这里容易让人以为它做的是「真启动」的 PR 检查。准确说是两件不同的事：

• PR 检查（action.yml）是静态的：给定插件列表和目标宿主版本，解析 engines.dsh / peerDependencies / 宿主实际发布过的版本，产出 matrix.json + matrix.md + badge，可以把表格评论到 PR 上，failOn 能让它在不兼容时失败。它不安装、不启动插件。
• 真启动是另一条路：verify（3.1.0 起）在隔离 profile 里逐个安装、启动，记录插件注册了哪些工具、激活还是卡在等服务，产出 verify.json。这条跑在定时任务里（宿主版本变化时触发），不是 PR 检查。

所以和 dsh-seam 的关系可以再精确一层：

	dsh-seam	dsh-plugin-health
检查对象	插件源码 → 上游 .d.ts	插件包 → 实际宿主
能否发现「你写了 agent.session 用错了可空性」	✅ 定位到行	❌ 运行时才知道崩不崩
能否发现「engines.dsh 写窄了 / 少了依赖 / 构建脚本没跑」	❌ 类型层面看不出来	✅ 装的时候就失败
覆盖时机	全程序调用面	只有启动阶段跑到的路径

两者失败模式不重叠，这点你判断对了。我这边测不到的正是「启动没跑到但代码是坏的」，你那边测不到的正是「包本身装不上」。

一个可以直接抄的做法

如果你的 verify 想覆盖多宿主版本，dsh-plugin-health 从 3.0.8 起遇到的一个坑值得抄：别用 dist-tags 猜用户跑的是哪个版本。有一段时间 alpha 指向的版本比 latest 早五天，按 tag 名收数据的结果是 135 个插件被统计成"被拒"，而实际上没人在那个版本上。

现在改成按 semver 排序 + 角色标注：最新版、高于最新版才纳入的 tag、上一条发布线。alpha 那种落后于 latest 的会被丢弃并记录原因。

对应到 dsh-seam：如果 bump 或 CI 里要选"当前 DSH 版本"，用实际安装的版本号，别用 tag 名。

关于互补

如果你愿意，我可以在 dsh-plugin-health 的 README 里加一行指向 dsh-seam（作者侧编译期检查），你那边也可以加一行指向我（用户侧运行时验证）。两边都不改代码，只是让找错地方的人能被指到对的地方。

顺便：dsh-seam 这个「非官方」声明写在开头第一句、后面跟仓库 + 许可证 + 一行 npx——这个格式我打算借用到自己的帖子里，很清楚。

---

dsh-plugin-health 这边近期修过一个和你这个方向相关的真实案例，可能对你有参考价值：doctor 有个告警说"配了代理但没设 NODE_USE_ENV_PROXY"，建议用户去设那个变量。实际上 Node 在跑任何 JS 之前就解析它，一个缺协议头的 127.0.0.1:6074 会让桌面应用在开窗之前 ERR_INVALID_URL 退出。检查本身和它给的建议两头都错，3.1.1 里整条移除了 → #7。

举这个例子是想说：作者侧工具如果给出会让用户改坏配置的建议，杀伤力比漏报大。你那边 bump 会改 package.json 里的版本对齐，值得考虑同样的风险——尤其它是在插件作者的仓库里动文件。

[YMoose]

感谢详尽的补充，尤其是对 PR Action 的纠正——我回头读了 action.yml，确认矩阵检查确实是静态解析、不安装不启动，是我在帖子里写混了，原文已改准确（第一节的描述已更新）。

关于 bump 的风险提醒，很有共鸣。目前它的防线是：--check 只读、--print-only 只输出计划；写入模式只改依赖版本号和 engines.dsh 两处，且注册表 next 指向比当前版本旧时直接拒绝（不降级）、--keep-floor 下目标超出既有兼容范围也拒绝。它不产生任何“建议你去改配置”的输出——你那个 NODE_USE_ENV_PROXY 案例说明这类建议才是最危险的，认同。

dist-tag 的坑也记下了。verify 锚定的是 node_modules 实际安装版本；bump 跟 next 是它的职责本身（对齐到最新预发布线）。不过你说的“按 tag 名收数据导致 135 个插件误判”的教训，对 baseline / bump --check 同样适用——tag 名只应该参与“跟随”，不应该参与任何“判断”，这点我们会持续自查。

互挂链接的提议很好，我这就在 README 的“检查边界与职责划分”一节加上指向 dsh-plugin-health 的一行（用户侧运行时验证），后续提交里可见。感谢借用格式的那句——非官方声明放在最前面确实值得。

[EasonMWS]

改得比我期待的还快——谢谢回头去读了 action.yml。新那句「静态解析 engines/依赖声明生成矩阵，不安装不启动插件」是准确的。

bump-upstream.mjs 的防线我看了：--check 只读、--print-only 出计划、注册表比当前旧时拒绝（不降级）、--keep-floor 下超范围拒绝、写入只碰依赖版本号和 engines.dsh 两处。bump-upstream.test.ts 18 KB 覆盖这些——四条都成立，我说那话的时候只是提个醒，现在看是我多虑了。

尤其「不产生任何『建议你去改配置』的输出」这一点是对的。这正是我那个案例的病灶：那条告警本身是误报，但它引导用户去改一个会让应用起不来的环境变量。工具有写入能力不可怕，可怕的是把判断错误包装成建议交给人去执行。

我这边已经做了

dsh-plugin-health 的 README 加了「它管不到的地方」一节，中英双语，指向 dsh-seam：

EasonMWS/dsh-plugin-health@46f6478

写的是具体的分工，不是客套：

	dsh-seam	这个包
读什么	你的源码 → 上游 .d.ts	已安装的包 → 真实宿主
你依赖的可空性变了	能发现，给 file:line	只有启动时走到才发现
engines.dsh 写窄、缺依赖、构建脚本被拦	看不出	能发现，在安装时就失败
覆盖面	整个调用面	启动路径

开头一句我特意写实了：启动试运行只覆盖 profile 启动时走到的路径，插件可以启动得很干净，却仍然被同一次升级弄坏。

关于 tag 名

你说「tag 名只应该参与『跟随』，不应该参与任何『判断』」——这个区分比我原话更准，我要借用。

我们踩的具体形态是：把 alpha 当成「另一个受支持的宿主线」去收数据，但它当时指向的版本比 latest 早五天。教训不是「别用 tag」，而是拿到 tag 指向的版本号之后，必须用 semver 判断它相对于其它版本的关系，而不能相信 tag 名的语义。next 未必比 latest 新，alpha 未必是新的预览线。

一件小事

scan 输出的 coupling.json 我看是纯 JSON——如果里面带一行 generator: "dsh-seam@x.y.z" 和 generatedAt，别人把它提交进仓库后，几个月后回看能知道是哪版工具、什么时候生成的。我们 verify.json / matrix.json 里有 schemaVersion 和生成时间，纯粹是因为被问过「这份数据是什么时候的、哪个版本产的」。不加也不影响功能。

祝顺利。有需要我这边配合验证的，直接说。

[YMoose]

感谢在 dsh-plugin-health README 里加的推荐——我也在 README 里加了指向 dsh-plugin-health 的互推链。

你的几条建议都很有建设性。建议安全红线进了开发契约（AGENTS.md）；tag 名只应参与「跟随」、不参与任何「判断」的原则固化成了设计决策；coupling.json 也加上了溯源字段。相关的开发我都已合入，非常感谢。

多版本 verify 的思路也不错，已列入开发计划，稍后实现。

[ChenYichener]

顺着「能启动不等于没坏」这句往下补一个维度：能启动、类型也对，但功能静默空转。

我是 dsh-nce（ChenYichener/dsh-nce，新概念英语学习插件）的作者，踩的就是这个面。说下它的形状和我的做法，给两位的工具定位做个参考，也供后来者抄。

这个维度的形状

我的 0.1.0 装完之后面板能打开、不报错，但是空的。
原因不在代码：教材数据在 .gitignore 里，发布时没带上。

• dsh-plugin-health 的真装真启动：装得上、起得来 ✅
• dsh-seam 的类型契约：源码用到的字段和 .d.ts 完全一致 ✅
• 用户看到：一个空列表 ❌

两个工具都没错，只是「数据/资源能不能被解析出来」既不在源码↔类型契约里，也不在启动行为里。而它的成本比启动失败更高：启动失败用户会来提 issue，空白用户会直接卸载且不吭声。

我的三道防线（可抄）

1. 每一级回退都要过内容校验，不是目录存在就算数

数据目录三级回退：env → 插件自身 node_modules/dsh-nce-data → 主包内 data/（旧版兼容）。
关键不是回退，是每一级都必须过 hasLessonIndex()：能解析 index.json 且 lessons.length > 0，否则继续往下一级。只判断 fs.existsSync(dir) 会在打包丢文件时把空目录误判成「有数据」。

2. 解析失败要抛错，不要返回空

resolveDataDir() 三级全失败时抛一个带三级路径明细的错误，而不是 return []。
return [] 就是 silent-empty 的源头——上层拿到空数组照常渲染，测试照常全绿。

3. E2E 断言「有内容」，而且跑在一次性 HOME 里

dsh plugin --profile e2e add dsh-nce     # 全新 HOME
# 然后直接读运行时 dataDir 下的 index.json，断言课程数 = 144

只断言「装上且能加载」测不出上面那个 bug，要断言装完之后的实际内容量。
隔离 HOME 顺带解决了另一个帖子里的恐惧（agent 写插件把 .dsh 清了）：插件开发期的安装/删除全部发生在一次性 HOME 和 --profile 里，真实 .dsh 全程没被打开过。

4. 数据包与主包解耦，让「缺数据」降级成「少内容」而不是「装坏」

教材走独立 npm 包 dsh-nce-data，主包内零教材内容。链路出问题时插件本体照样能装能用；真要下架数据，只需取消发布数据包。

边界（这套什么时候不该用）

• 三级回退本身是维护负担：路径逻辑一改三处都要重验。回退是为了兼容旧安装，不是为了优雅，分支越少越好。
• 只对资源型插件成立。纯逻辑插件没有这个面，硬造一个 hasXxxIndex() 是过度设计。
• 它只测「非空且可解析」，测不出内容正确性。我敢这么用，是因为我的失败模式是「空」不是「错」；如果你的失败模式是「错」，这条路不够。

给工具定位的一点想法

如果两位想把这一面也纳进去，最便宜的不是去检查资源文件，而是要求插件在 manifest 里声明一个就绪探针（比如 exports.probe：无副作用、返回 { ok, detail }），由 dsh-plugin-health 在真装之后调用一次并断言 ok === true。这样「装完是空壳」就从「靠作者自觉」变成「可门禁」，而且它天然是运行时的，正好接在你已有的真装真启动之后那一步。