【经验】从"双目录分裂 + 8 小时宕机"到一套可复制的工作区治理规范

[DaRin1403]

我的工作区被误建成了 w<工作区名>(多了个 w),UI 改名后底层 path 未同步 → 文件散落两处、会话绑死旧路径、系统反复自动重建旧目录。第一次迁移脚本引发 8 小时宕机(PS5.1 写 BOM + 只改会话目录名)。读源码重写后,现在三处(注册表/会话存储/物理目录)对齐,并沉淀出一套"目录分级标准 + AGENTS.md 注入 + 项目索引"的治理方案。分享给社区。

一、事故机制(源码级确认)

1. 会话身份强绑定:session.jsonl.zstd 是多帧 zstd 流,头帧(frame 0)是单行 JSON 会话头;启动时 assertStoredIdentity 校验"头帧 cwd 的转义名 ↔ 会话目录名"。只改目录名、不改头帧,必崩。
2. 注册表是派生的:工作区记录在启动时按 realpath(会话头 cwd) 分组重建——所以"只改 workspace.json 的 path"下次启动必然分裂出第二个工作区。
3. 整文件解压重压必崩:头帧要求"恰好一行头";整日志"解压→改→重压"会坍缩成单帧,启动即报 "first frame is not exactly one header line"(社区 2026-08-24 有相同案例;本仓库与 dsh-mv-session 都采用"只重写头帧")。
4. Windows 写配置的坑:PowerShell 5.1 Set-Content -Encoding UTF8 会写 BOM,Node JSON.parse 直接失败——配置文件必须字节级写入。

二、正确姿势(28 个会话实测通过)

停机(端口守卫)→ 备份 → 只重写每个会话的头帧 cwd(用 node:zlib 的 zstd API + 官方同款 scanZstdFrames 帧扫描,checksum 参数对齐)→ 逐文件全量解码校验(帧数/行数/id)→ 会话目录移到新转义名 → 删旧根(失败可安全重跑)→ 改注册表与缓存 → 旧目录可先用目录联接过渡 → 重启验证。

三、沉淀的治理方案

• 目录分级标准(L0-L4):根目录只放白名单索引;一项目一文件夹;备份/归档分离;红线(file: 链接插件源禁搬、删除必须确认);
• AGENTS.md 自动注入:全局 $DSH_HOME/AGENTS.md + 工作区 AGENTS.md,靠 DSH 官方的 dsh-agent-instructions 插件让每个新会话自动遵守(实测新文件一写入立即注入);
• 项目文件总索引:每个项目登记一行(项目 → 文件夹 → 一句话结论),纯对话项目用工具把结论落盘成纪要;
• 工具:session-dump.js(会话标题映射/解压)、workspace-migrate.js(frame-safe 迁移,dry-run/守卫/校验)。

以上已打包成开源仓库(脱敏版):agent-workspace-kit
https://github.com/DaRin1403/agent-workspace-kit

四、给官方/社区的三个建议

1. 内置一个"工作区路径变更"向导(改名/搬家时提示并引导正确迁移),从源头减少这类事故;
2. dsh-agent-instructions 很好用,希望在官方文档里更显眼地介绍(全局/项目/子目录三层 + local 覆盖);
3. 考虑提供路径级 deny 的官方能力(社区已有 dsh-path-guard 插件在补这个位)。

附:教训清单

• 迁移脚本必须:端口守卫、dry-run、自动备份、逐文件校验、失败可重跑、失败不动旧数据;
• 事故复盘值得写下来——它是后来者最快的路。

[xiaoyuyu6420]

这套治理规范很实在——尤其「会话身份绑死头帧、注册表是派生的」这两条源码级结论，值得后来人少走弯路。补一个和你经历互补的视角：第一次迁移脚本引发 8 小时宕机，本质是动手时没有退路——如果当时 ~/.dsh 有一份几分钟内的备份，改坏了直接整体还原，不用靠读源码救火。

我现在动工作区/迁移前必做：

dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
/backup            # 动手前 10 秒备份（dsh 版本变化时它还会自动打 dsh-pre-upgrade- 快照）
/backup restore latest --dry-run   # 改坏了先预览再还原，恢复失败自动回滚

你的三处对齐方案是「防患」（减少出事概率），一份随时可回退的备份是「兜底」（出事了能回去）——两层叠上，迁移这事才算真的稳。要求 DSH 0.1.1-rc.2 或兼容版本（安装时会校验 peer）。