前言¶
DeepSeek Harness（DSH）把会话历史存成逐批追加、带校验和的 zstd 帧。这条日志是人与 DSH 之间交换记忆的唯一介质：一旦某条记录在加载阶段无法通过形状校验，整条历史会报 SessionPersistenceCorruptionError，界面常见「history unavailable … must contain one tool-result block」——相当于人和系统一起「失忆」。
问题往往出在写入与加载不对称：写入路径不校验消息形状，第三方插件在 output.render() 返回裸字符串等违规形态时，写入不会报错，直到下次加载才暴露。社区维护的 dsh-session-doctor（imtokenxinluo）针对这类已落库的损坏做体检、备份后无损修复，并在 v1.1 起提供实时 watch 告警、v1.2 起提供 blame 事故归因。下面介绍它是什么、能做什么、如何安装与使用。
这是什么¶
dsh-session-doctor 是会话体检与修复工具，面向 DeepSeek Harness：用与 DSH 加载路径相同的规则扫描存储的会话日志，找出会导致历史加载失败的损坏记录，对已支持的那类形状漂移做无损修复；每次修复前自动备份。维护者为 imtokenxinluo，在 SkillHub 社区目录中归类为「记忆」，仓库见 GitHub，许可证 MIT。当前 npm 包版本为 0.2.3（以 package.json 为准）。
它与内核侧「写路径守卫」、兄弟插件 dsh-contract-check 等形成互补：contract-check 偏事前静态检查，本工具的 watch 偏实时告警，scan/repair 偏事后修复，装不装互不影响。
核心功能¶
scan：按 loader 同款规则体检¶
遍历 sessions 根目录或单个 .jsonl.zstd 文件，校验每条事件，报告损坏会话、行号、seq、事件类型、涉及的 tool 名与原因。
repair：备份后无损修复（限定形态）¶
对单个损坏文件：先备份为 <file>.<ts>.bak，再修复 tool-result 块中 content 不是数组的记录，帧级重写（未损坏帧字节不变）；重写产物复验 0 失败才落盘。未知损坏形态只报告、不自动修。
当前支持且不改字的三种形态：
| 形态 | 修法 |
|---|---|
content 为裸字符串 |
包成 [{type:"text",text:…}] |
content 为 null 或缺失 |
置为 [] |
content 为单个对象 |
包成 [obj] |
数字、布尔等无法安全推断的形态一律不修。
watch（v1.1）：实时哨兵¶
订阅 DSH session/event，对 live 会话新写入的消息事件即时做 loader 同款校验，违规立刻告警。事件在 append 后才发布，watch 不阻止写入、不改 live 文件；修复交给冷会话的 repair。
blame（v1.2）：突然关闭是不是 agent 干的¶
只读分析会话日志：定位中断断点，回看断点前工具调用链，匹配杀进程、关浏览器、自重启 harness 等危险模式。双重证据门槛下判定 AGENT-CAUSED、EXTERNAL 或 NO-ACCIDENT；日志尾部 torn frame 会标注证据缺失。
safeguard（0.2.2 起）¶
一条命令串联：冷备整棵 sessions 树 → 体检 → 修复 → 回读校验。冷备失败则中止，绝不进入修复。
设置面板「会话体检」（0.2.2 起）¶
GET /session-doctor/report 只读展示结论；POST /session-doctor/repair 需显式触发修复。0.2.1 及更早装进 profile 后仅有实时哨兵，无面板与上述路由；CLI 的 scan/repair/blame 仍可用。判断是否含面板：看 node_modules/dsh-session-doctor/package.json 的 version，或该目录下是否存在 lib/client.js。
完整损坏形态与「能修 / 只报告」说明见仓库 docs/DEFECT-CATALOG.md。
安装与启用¶
README 写明：独立包，暂不注册进 profile。CLI 不依赖 DSH 运行环境，需 Node >= 22，零运行时依赖（仅用 Node 内置模块）。
在克隆或解压仓库后于项目根目录执行：
npm link
也可直接运行：
node bin/dsh-session-doctor.js
作为 DSH cordis 服务插件时，接缝在 src/，可通过 profile 注册以启用 watch；默认不装。安装任何 DSH 插件前，应自行查看源码与 MIT 许可证；插件在 DSH 进程权限下运行，与宿主同权。
典型用法¶
扫描与修复单文件：
dsh-session-doctor scan <sessions-root>
dsh-session-doctor scan-file <file>
dsh-session-doctor repair <file> [--dry-run]
dsh-session-doctor blame <file|root>
动手前全局快照（先 dry-run，确认后再 apply）：
dsh-session-doctor safeguard <sessions-root> --backup-to <backup-dir>
dsh-session-doctor safeguard <sessions-root> --backup-to <backup-dir> --apply
顺序固定为：冷备 → 体检 → 修复（每文件仍留 .bak）→ 重扫校验。清单写在 <backup-dir>/doctor-backup-manifest.json。
GUI 报 history unavailable 且提示 tool-result block 时：对该会话文件 scan-file 确认，再 repair。想查哪个插件违反 render 契约，可用仓库脚本 scripts/audit-render-contract.mjs <插件 src/lib>。
适用场景与注意¶
| 场景 | 建议 |
|---|---|
| 历史无法加载，怀疑 tool-result 形状错误 | scan-file → repair |
| 担心插件再次写坏记录 | profile 启用 watch，或定期 scan |
| DSH 升级后怀疑旧会话 | 按仓库 docs/PATCHES.md 核对 |
| 浏览器或 DSH 突然关闭 | blame 只读归因 |
repair 只处理上述 content 非数组一族；其它损坏请依赖报告与冷备，勿指望自动改写。长期增量冷备可与 dsh-session-backup 等分工并用；safeguard 侧重「本次修复前」的就地快照。
SkillHub（https://www.skillhub.cn/plugins/imtokenxinluo/dsh-session-doctor）是社区插件目录，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，本工具是社区在记忆与会话持久化边界上的补充，而非官方内置能力。
结尾¶
dsh-session-doctor 把「加载时才爆炸」的会话损坏变成可扫描、可备份、可有限无损修复、可实时告警、可 blame 归因的问题，适合长期跑 DSH、依赖历史连续性的开发者。详情与更新以仓库 README 为准。
- 社区目录：https://www.skillhub.cn/plugins/imtokenxinluo/dsh-session-doctor
- GitHub：https://github.com/imtokenxinluo/dsh-session-doctor
