dsh-diagnostic-tools

dsh-diagnostic-tools —— 诊断取证工具组

English: README.en.md

一句话：一个仓、两个子目录，回答长期跑编码 agent 的人迟早会问的两个问题 —— 我的环境有没有坏（依赖闭包 / 解耦）· 我的数据缺不缺（会话图片实体）。

零 npm 依赖（只用 Node 标准库）· 默认只读（写操作要显式加 --apply，且留回滚清单）· 不联网 · 判据可复跑（每个子目录自带验证脚本，不需要相信维护者的自述）。

---

设计依据

本工具组是「ops-handoff-design」所述运维体系的一个实现， 设计依据（对应文档仓约定的固定四问）：

• 它为什么存在、边界在哪 → 见《只读监控面板的设计纪律》§2 显示纪律（不可探测 + 原因）、§5 数据来源三分类（「通用化」的天花板在哪）
• 它与宿主版本的兼容区间 → 见《多机交接与云中继》§4.5「兼容性要求」（另见本 README 第 6 节「现状与限度」）
• 本组件特有的坑与实测 → 见本 README 各子目录的「限度如实说」与「宿主版本适用性」两节；两个子目录都把宿主相关的名字集中在一个文件里，正是为了让升级时的回归面收敛
• 文档仓地址 → Gitee（镜像）https://gitee.com/kira905/ops-handoff-design ｜ GitHub（主）https://github.com/kira905/ops-handoff-design （文档仓的组件索引表回指本仓；两仓互链、版本各自独立）

设计稿里不写具体仓库地址（写死即死链），实现清单统一收在文档仓的组件索引表里——本仓只负责回链章节。

---

1. 你需要哪个？

两者的共同点：症状看着像别的问题（一个像"插件质量差"，一个像"网络故障"）， 按表面方向排障永远修不好 —— 所以各配一个只读工具，先把事实变成看得见的。

三个最反直觉的结论（先看这三条，再决定要不要往下读）：

1. "插件在宿主升级后崩了"多半不是插件烂，而是它 import 了宿主的运行时符号，而宿主把那个符号删了 / 改名 / 拆包了。
2. 多个安装共存时，一个安装启动会改写共享的依赖闭包链接 —— 于是"测试实例跑过之后，生产重启就崩"。
3. "含图会话续聊报传输错误"不是网络故障：图片实体只存在本机磁盘，同步方案默认不搬这些大二进制 ⇒ 换机后引用悬空。

---

2. 结构与安装

dsh-diagnostic-tools/
├─ README.md            仓级说明（本文件）
├─ LICENSE              仓级许可（MIT）
├─ CHANGELOG.md         仓级：只记结构级变更
├─ docs/RELEASING.md    仓级发布流程
├─ closure/             依赖闭包体检 4 件（解耦检查 / 闭包指向体检 / 修法 / 共享判据库）
│  ├─ README.md · CHANGELOG.md · LICENSE · docs/RELEASING.md
│  ├─ check-decoupling.mjs · closure-check.mjs · repair-closure-links.mjs
│  ├─ lib/ · scripts/ · examples/
└─ attachments/         会话图片附件对账二件（只读对账 + 按需取回）
   ├─ README.md · CHANGELOG.md · LICENSE · docs/RELEASING.md
   ├─ attachments-audit.mjs · attachments-fetch.mjs
   └─ lib/ · scripts/

安装（零依赖、无构建步骤）：

git clone https://github.com/kira905/dsh-diagnostic-tools
cd dsh-diagnostic-tools
node closure/closure-check.mjs --help        # 或 node attachments/attachments-audit.mjs --help

每个子目录的 README 里有完整的用法表 / 参数 / 退出码含义 / 已知限制。 --help 与 --dry-run 是安全的：所有写操作都必须显式加 --apply，且会先打印将要做的事与回滚清单。

---

3. 为什么合仓（而不是一件一仓）

理由

1. 同属「装一次就能自查两类问题」的心智：我的环境有没有坏（闭包 / 解耦）+ 我的数据缺不缺（附件实体）；
2. 共享仓级 README / LICENSE / 发布流程 / 自检脚本形态，维护成本更低；
3. 两类工具的受众高度重叠（都在多机、多安装、长期跑 agent 的场景里出现）。

代价与对策

• 两个子目录的版本号与退出码各自独立（判据不同、变更节奏不同）⇒ 保留子目录级 CHANGELOG.md， 仓级 CHANGELOG.md 只记结构级变更（新增子目录、仓名变更、许可变更）；
• 使用者 clone 一次会多拿一个用不上的工具 ⇒ §1 那张表负责分流，子目录 README 各自给「三行安装 + 用法表」。

---

4. 许可

AGPL-3.0-only + 商业授权（双许可；见仓根 LICENSE）。两个子目录各自也带一份同文本的 LICENSE，便于单独取用； 合仓后以仓根 LICENSE 为准，改许可必须三处一起改（见 docs/RELEASING.md §2）。

• ⚠️ AGPL 本身不禁商用：可自由使用、修改、再分发（含商用），但通过网络向他人提供修改版时，必须按 AGPL 一并提供对应源码；
• 「+ 商业授权」= 双许可：需在闭源 / 商业场景使用（AGPL 传染条款不适用）时另行取得商业授权 —— 本仓暂无公开联系邮箱，请通过本仓 Issue 联系；
• 许可变更记录：本仓 v0.1.0 ~ v0.1.3 的全部历史 tag 以 MIT 发布；自 v0.1.4 起（含两个子包 0.1.1）改为 AGPL-3.0-only + 商业授权。已经按 MIT 发布的版本授权收不回，变更只约束未来版本。

---

宿主兼容性（实测）

本仓是独立 CLI 工具组（两个子目录都不 import 任何 @deepseek-ai/dsh-* 包）⇒ 不声明 peerDependencies（声明会误导成"与宿主版本绑定"）。下表只记录实测过的环境。

5. 版本与发布

• 子目录各自 SemVer（当前均为 0.1.1：0.1.0 = 首个公开版本，0.1.1 = 许可变更）；
• 仓级用 tag 记录结构状态（当前 v0.1.4 = closure 0.1.1 / attachments 0.1.1，仓级 tag 只随仓根文档更新推进）；
• 发布流程与检查单见 docs/RELEASING.md；只发 Release，不发 npm。

6. 现状与限度

• closure/ —— 依赖闭包体检 4 件，已完成通用化改造；自带静态验证（语法 + 配置行为 + 脱敏扫描） 与干净夹具验证（4 种判定 + dry-run 不回退）。
• attachments/ —— 附件对账二件，同上，另外在隔离的真实实例上做过只读对账核对（不动生产数据）。
• 限度如实说：两个子目录的判据都基于当前宿主版本的事件名 / 服务名 / 目录形态。 宿主升级后这些字符串契约可能变化 —— 这正是 closure/ 要体检的对象，也是为什么 每个子目录都把宿主相关名字集中在一个文件（lib/host-protocol.* / lib/closure-links.mjs）里， 而不是散落在功能代码中。

---

7. 相关组件

同属 DSH 生态的伴生组件，各自独立仓、独立版本、许可各自独立；它们都回链到同一份文档仓 ops-handoff-design （Gitee 镜像 https://gitee.com/kira905/ops-handoff-design）：

组件之间没有代码依赖，也不共享运行时 —— 之所以互指，是因为它们回答的是同一类人的同一批问题 （长期在自有机器上跑 agent：装得下、找得到、看得见、查得清）。谁装谁不装，互不影响。