会话守护 54nanmiao/dsh-session-guard

DSH 会话事故防护包

一套小工具集，针对 DeepSeek Harness（DSH）：防止「改坏一个会话目录 → 整个应用下次启动白屏」这类事故。

非官方项目，与 DeepSeek 官方无关。所有工具默认只读，不删除任何会话，不改日志内容。

这类事故长什么样

DSH 的会话存储有硬性约束：

%USERPROFILE%\.dsh\sessions\<--cwd-->\\<id>\session.v4.jsonl.zstd

- 目录名必须等于日志头里的 id；
- 项目目录名必须等于 cwd 的编码形式（如 C:\Users\u\Documents\proj → --C-Users-u-Documents-proj--）。

只要有人把会话目录改名（比如清理脚本改成 xxx.bak、xxx.orphan）或挪到别的项目目录：

- 当时应用完全正常（文件句柄在内存里）；
- 下次冷启动时，DSH 按 cwd + id 反推规范路径，发现对不上，判为 corrupt session log；
- workspace 插件初始化失败 → 会话列表相关控制器全部 pending → 界面空白、宿主进程退出。

数据一个字节没丢，只是「目录名被判非法」。本项目就是为了在改坏的那一刻和启动之前各设一道闸。

三个组件

| 组件 | 作用 | 是否改数据 |
| dsh-session-doctor | 只读体检：目录名 vs id、项目目录 vs cwd、重复 id、日志可解码 | 否 |
| dsh-session-maint | 安全修复：能改成规范名的改名，改不了的移出 sessions（不删除）；默认 dry-run | 加 --apply 才改 |
| launch-dsh + install-guard | 启动守门：接管快捷方式，启动前先体检，不通过就弹窗拦住 | 只改快捷方式 |
| plugin/dsh-session-guard | 运行期守护插件：fs.watch 盯会话目录，改名/挪动 1 秒内告警；默认只读 | 否（可选自动隔离） |

三层互补：插件管运行期预防，守门管启动前拦截，脚本管事后修复。

快速开始

方式 A：一键安装（推荐给普通用户）

1. 下载本仓库（Code → Download ZIP）；
2. 解压到任意目录（别删，守门快捷方式会引用它）；
3. 双击 一键安装.cmd：
- 先体检一次；
- 把插件装进你自己的 %USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml（只追加一段，自动备份）；
- 询问是否顺便接管桌面/开始菜单/开机启动快捷方式；
4. 重启 DSH，用桌面快捷方式启动；
5. 验证：%USERPROFILE%\.dsh-session-guard\report.json 中出现 "scanMs" 即生效。

每台机器各自安装。 不要把别人的 cordis.patch.yml 复制过来——插件行含本机绝对路径，复制会导致那台机器加载失败。安装器已处理「路径失效自动重装」。

方式 B：只用命令行体检/修复

dsh-session-doctor.cmd :: 只读体检，退出码 0/1
dsh-session-maint.cmd :: 只看修复计划（dry-run）
dsh-session-maint.cmd --apply :: 执行：能改规范名就改，改不了移到隔离区
dsh-session-maint.cmd --apply --quarantine :: 非规范目录一律移出 sessions
dsh-session-doctor.cmd --root D:\test-sessions :: 检查别的目录

方式 C：只装插件（不动快捷方式）

install-plugin.cmd

插件默认只读告警；想让它自动隔离坏目录，把配置改成 autoQuarantine: true（仍然只移动不删除）。

验证与卸载

:: 体检
dsh-session-doctor.cmd

:: 卸载插件（会把 cordis.patch.yml 还原到安装前，字节级一致）
uninstall-plugin.cmd

:: 还原快捷方式（用最近一次备份）
install-guard.cmd -Revert

兼容性与限制

- Windows 10/11；DSH 0.2.x（自带支持 zstd 的 Node）。
- 若 DSH 的 Node 版本过老（无 zlib.zstdDecompressSync），插件只会在日志里 warn，不影响启动。
- 插件/守门只能在应用已启动后工作；目录已经坏到起不来时，请用 dsh-session-maint 修。
- 只检查「目录名 / header id / cwd」三类自洽性，不校验日志内容本身。
- 不依赖任何第三方包；插件只 import node:fs / path / os / zlib。

事故复盘

- 事故复盘.md：完整时间线、根因、最小复现
- 上游问题报告.md：可直接提交给 DSH 的 issue 文本（建议官方把「单个坏目录」从致命错误改为跳过并告警）
- 一页纸-守则.md：可打印的规则清单
- AGENTS.md 模板.md：让 AI/自动化也遵守这条铁律

仓库结构

.
├─ 一键安装.cmd 入口 ├─ 1-体检.cmd / 2-安装守门.cmd / 3-还原快捷方式.cmd ├─ dsh-session-doctor.mjs/.cmd 只读体检 ├─ dsh-session-maint.mjs/.cmd 安全修复 ├─ install-guard.ps1/.cmd 快捷方式接管 ├─ launch-dsh.ps1 / .vbs 守门本体（隐藏窗口） ├─ install-plugin.ps1/.cmd 插件安装 ├─ uninstall-plugin.ps1/.cmd 插件卸载 ├─ plugin/dsh-session-guard/ 运行期守护插件 ├─ 事故复盘.md / 上游问题报告.md / 一页纸-守则.md / AGENTS.md 模板.md └─ LICENSE

许可

MIT。欢迎提 issue / PR；如果你在别的平台上遇到同类问题（macOS/Linux 的 DSH），脚本里的路径判断需要相应调整。