档案诊断器 Allenllii/dsh-profile-doctor

dsh-profile-doctor

DeepSeek Harness 档案（profile）的只读取证工具。

DSH 插件出故障时是静默的：插件装着、列在列表里、显示已启用，但它的 host 半边从没挂载过；档案可以被组合出重复的 loader 条目 id 然后直接拒绝启动；一个注入提示词的插件看起来生效，而真正送进模型的系统提示词说的是另一回事。这个工具用证据回答这三种情况，而且它调用的是 DSH 自带的启动逻辑，不是重新实现一遍。

- 零运行时依赖
- 零写入（只有 install 会改档案，它自己会明说）
- 桌面 App 正在运行时也能用

$ npx dsh-profile-doctor doctor

dsh-profile-doctor 0.1.0
profile desktop (~/.dsh/profiles/desktop)
runtime 0.2.0-rc.2 (~/AppData/Roaming/npm/node_modules/@deepseek-ai/dsh)
app.asar ~/AppData/Local/Programs/DeepSeek Harness/resources/app.asar

== composition
layers 22 bundle layers, 13 user patches
entries 210 composed rows
duplicates none
skipped none
orphan refs github-workbench

== gate
gated 12 packages with @deepseek-ai/dsh* peers
blocked none

== roster
client entries 101
duplicate ids none
unresolved @deepseek-ai/dsh-client-ui-dockkit

== logs
boot failures 3 crash--web-boot.log file(s)
- crash-2026-09-30T01-20-18-896Z-web-boot.log
Error: web boot: 1 entry did not activate
culprit: dsh-better-overleaf

== findings
! [orphan-patch-ref] user patch references "github-workbench", which no layer inserts
! [recent-boot-failure] ...did not activate — dsh-better-overleaf

verdict: attention

环境要求

| Node | >= 22.15（会话存档取证依赖 node:zlib 的 zstd 支持） |
| DSH | 本地需要一份 @deepseek-ai/dsh 安装，供 compose / gate 复用真实启动逻辑 |

Doctor 会自己找到 Harness 安装位置。位置特殊时给一次环境变量即可：

DSH_INSTALL_ROOT=/path/to/node_modules/@deepseek-ai/dsh # 或 --dsh <dir>
DSH_APP_ASAR=/path/to/app.asar # 或 --app <file>
DSH_HOME=~/.dsh # 或 --home <dir>

命令

| 命令 | 回答什么 |
| doctor [profile] | 跑下面全部检查，归并成 findings 和一句结论 |
| compose [profile] | 重复 loader 条目 id、被闸门跳过的 bundle、孤儿补丁引用 |
| gate [profile] | 哪些已安装包过不了启动闸门，以及为什么 |
| roster | 哪个包注册了哪个 client factory id；解析不到的 require() |
| session [id] | 从会话存档里读回真正发出去的 system 消息 |
| asar ls\|cat\|find | 读 app.asar 内部——普通 Node 读不了 |
| logs | 客户端启动失败记录与插件市场操作流水 |
| install <spec> | 装进被保留的 desktop 档案 |

--json 输出机器可读结果，--strict 让警告也返回失败码，-h 看全部参数。
退出码：0 通过，1 失败（--strict 下警告也算），2 用法或内部错误。

它存在的三个理由

1. 装了，但从来没有挂载过

启动闸门只看名字为 @deepseek-ai/dsh 或 @deepseek-ai/dsh- 的 peer 依赖。只要有一个不满足， loadProfileDirectory 会抛出、自己接住，然后把包塞进 skippedBundles——host 半边不挂载， client 半边不组装，而在使用现场不会有任何报错。

$ dsh-profile-doctor gate
runtime = 0.2.0-rc.2 | gated packages: 12 | blocked: 1
BLOCKED dsh-some-plugin@1.4.0 (1 gated peer(s))
needs @deepseek-ai/dsh@^0.1.0-rc.6
ok dsh-better-sidebar@0.24.1 (14 gated peer(s))

最常见的成因是 0.x 的 caret 语义：^0.1.0-rc.6 等于 >=0.1.0-rc.6 <0.2.0，所以一个为 0.1.x 写的插件会被一条看起来很有远见的 caret 范围排除在 0.2.x 之外。
档案的 compatibility.json 里可以写精确版本豁免，工具会如实报告豁免状态，不替你猜。

2. 档案根本加载不起来

composeEntries 会把所有 overlay 补丁依次应用到空根上，产出真正会挂载的行。
两层插入同一个条目 id 是启动期的硬失败——而且很容易手动制造出来，因为插件的安装器可能追加一条 insert，而它的 bundle 层早就提供了同一条。

$ dsh-profile-doctor compose
duplicates system-prompt x2

3. 提示词其实没送到

Harness 把系统提示词以 in-history system 消息的形式落盘，所以会话存档就是事实依据。
存档不是单一 zstd 流，而是多个 zstd 帧首尾拼接，zstdDecompressSync 只会静默返回第一帧。
本工具按 zstd magic 切帧、逐帧解压。

$ dsh-profile-doctor session --needle "You are an AI agent powered by DeepSeek Harness"
== session 0f405c2d-…
system msgs 1
turn 1 19813 chars first line: "You are a coding agent powered by…"
count "You are an AI agent powered by DeepSeek Harness": 0

安全边界

doctor、compose、gate、roster、session、asar、logs 全部只读：不开网络连接、不写文件、不打印任何凭据——报告里只有路径、id 和计数，没有密钥材料。
唯一的例外是 install：它通过 DSH 自己的代码路径去驱动 dsh plugin，并且绝不替你猜。

同类工具

dsh-doctor 覆盖的是「坏掉之后怎么恢复」——检查点、回滚、启动探针，是个好搭档。本工具是其中诊断的那一半：精确重放档案组合、闸门裁决、客户端 roster，以及模型到底被告知了什么。

许可证

MIT