【临时解决方案】v1.22 ~ v1.24 会话重复/丢失/恢复风暴（recovery fork 循环）的规避与数据修复

[Linearl]

v1.22 ~ v1.24 不稳定：recovery 分支风暴的临时解决方案

适用版本：v1.22.0 / v1.23.0 / v1.24.0 / v1.24.1（桌面版 & CLI）
状态：临时方案（正式修复见 PR #8444，尚未合并；#8294 / #8342 / #8437 / #8443 等仍在跟踪）

一、现象（你遇到的是哪个？）

现象	关联 issue
会话列表出现大量重复对话（几乎一样的标题/内容），或多个重名/未命名会话	#8294 #8437 #8443 #8446 #8449 #8450 #8452
对话历史重复（同一会话内容重复多条/历史信息重复）	#8434 #8437 #8443 #8449
打开后左侧边栏为空 / 加载很慢（几分钟才能显示项目与会话）	#8415 #8445 #8423 #8321
打开会话只有部分轮次，后半段"消失"/内容不全	#8342 #7521 #6451 #8452
sessions 目录被 -recovery-* 文件灌满（数千~上万文件，单会话可达数百副本/数 GB），磁盘暴涨、启动变慢	#8342 #6622 #7323 #8420 #8421 #8451
会话内容被清空 / 变成 0 字节 / 加载已删除的历史会话	#8441 #7521 #8431
冲突副本提示 / 会话自我复制 / 恢复-压缩死循环（API token 消耗爆炸）	#8440 #8446 #8393
自定义会话名被覆盖 / 被拆分成大量 topic 文件	#8427 #8450

根因（社区已定位）：checkSnapshotWrite 对同 revision 的保存误判 diverged，每 ~30s fork 一个 recovery 分支；depth-cap 后隔离副本按内容 digest 命名、每保存一个文件，形成永不停歇的恢复风暴（详见 #8294 #8342 与 PR #8444）。侧边栏"空白/加载慢"的直接原因是会话目录被 recovery 文件灌满（启动时需扫描数千文件），"历史重复"是因为每个 recovery 分支都被当作独立会话/副本展示。

二、临时解决方案（已验证，2026-08-11）

⛔ 操作铁律（两条，务必遵守）

① 先备份 reasonix 数据目录 —— 操作涉及会话文件重建，务必先完整备份，避免操作过程中出现问题后无法回退：

# Windows（PowerShell）：整个数据目录复制一份
robocopy "$env:APPDATA\reasonix" "D:\backup\reasonix-backup-YYYYMMDD" /E /COPY:DAT /R:1 /W:1 /MT:16
# macOS/Linux
cp -r ~/.config/reasonix ~/reasonix-backup-YYYYMMDD

② 恢复/回退操作必须离线执行 —— 先完全关闭 Reasonix（含窗口 + 系统托盘图标，详见各方案"完全退出"步骤）。
若 Reasonix 仍在运行，其 autosave 会检测到会话文件被外部修改 → 触发新的 recovery fork / 覆盖重建结果 → 修复失败（实测：运行中执行恢复会导致当前会话被再次 fork，恢复结果被冲突副本覆盖）。

✅ 推荐方案：A（回退到稳定版）+ B（修复已有数据）

方案 A：回退到 v1.21.5 —— 停止产生新问题

v1.21.x 是最后一个无此 bug 的版本线（v1.22.0 引入回归）。

第 0 步：完全退出 Reasonix（铁律②，重要！）

• 退出桌面版窗口（关闭所有会话标签页）
• 同时退出系统托盘（Tray）图标：右键托盘图标 → 退出/Quit（仅关窗口、托盘进程仍在运行时，安装器可能无法覆盖文件，且运行中的 autosave 会在回退期间继续产生 recovery 分支）
• 确认进程已结束：
  • Windows: tasklist | findstr reasonix 应无输出；若有残留 taskkill /IM reasonix-desktop.exe /F
  • macOS/Linux: pgrep -fl reasonix 应无输出

第 1 步：备份数据目录（铁律①）

# Windows（PowerShell）：整个数据目录复制一份
robocopy "$env:APPDATA\reasonix" "D:\backup\reasonix-pre-fallback" /E /COPY:DAT /R:1 /W:1 /MT:16
# macOS/Linux
cp -r ~/.config/reasonix ~/reasonix-pre-fallback

第 2 步：安装 v1.21.5

桌面版：

1. 从 desktop-v1.21.5 release 下载对应平台 installer
2. 覆盖安装（versions/ 多版本布局会自动切换；不要选 v1.22.0，正是引入回归的版本）
3. 重启后确认无新 -recovery-* 分支产生

CLI：从 v1.21.5 release 下载替换二进制。

⚠️ 数据目录（%APPDATA%\reasonix 等）不受回退影响，配置/记忆/会话全部保留。

方案 B：修复已受影响会话 —— 找回丢失轮次

原理：被 fork 的会话，完整内容在 recovery 分支里，主 jsonl 停留在 fork 时刻。恢复 = 用最全分支重建主文件。

参考脚本（社区已验证，16 个会话全部恢复成功，含 102 行丢失找回）：
🔗 **https://gist.github.com/Linearl/bb2ae212e96b0bb10ca5d098e360a02b**（`restore_recovery_sessions.generic.py`，跨平台，无第三方依赖）

详细步骤（铁律①备份 + 铁律②离线执行贯穿全程）：

1. 完全退出 Reasonix（铁律②，关键！）：关闭桌面版窗口 + 托盘图标退出（右键托盘 → 退出）。运行中改文件会触发再次 fork，恢复会失败
2. 备份数据目录（铁律①）：

   # Windows（PowerShell）
   robocopy "$env:APPDATA\reasonix" "D:\backup\reasonix-pre-restore" /E /COPY:DAT /R:1 /W:1 /MT:16

3. 下载并运行参考脚本（先 dry-run）：

   python restore_recovery_sessions.generic.py
   # 输出每个受影响会话：主 X 行 → 分支裁剪后 Y 行（+N）

4. 确认 dry-run 结果合理后执行恢复：

   python restore_recovery_sessions.generic.py --apply
   # 也可只处理单个会话：
   python restore_recovery_sessions.generic.py --apply --session <会话前缀>

5. 脚本做了什么（可审计）：
   • 对每个会话，找到该前缀下行数最多的 -recovery-*.jsonl（内容最全的分支）
   • 裁剪噪音行：__reasonix_local_only__ 标记 / [snipped tool result 占位 / bash_output 空轮询 / 失效 job 查询
   • 校验：主文件消息必须全部出现在分支中（防分叉误判），不满足则跳过该会话
   • 重建三件套：主 *.jsonl + *.events.jsonl（单条 replace revision=1）+ *.jsonl.meta（revision=1、content_digest=sha256(消息数组)、清除 recovered/recovery_depth/parent_id 等字段）
   • 旧分支与 sidecar 移到 <数据目录>/recovery-restore-trash-<时间>/（不删除，可回滚）；重建前主文件组备份到 recovery-restore-pre-<时间>/
6. 重启桌面版验证：
   • 打开会话：内容完整（应显示恢复后的全部轮次）、首条为 system、无"冲突副本"提示
   • 确认 display-index.json 由桌面版自动重建（正常现象）
   • 确认无新 -recovery-* 分支产生（find <数据目录>/projects -name "*recovery*" -newermt "今天" 应无输出）
7. 回滚（万一异常）：把 recovery-restore-pre-<时间>/ 里的文件按原路径拷回即可

⚠️ 暂不推荐：方案 C（升级到 v1.24.x）

• v1.24.x 系列目前仍不稳定：issue 区持续有 v1.24.1 的重复对话/会话清空报告（[Bug]: 新版本 v1.24.1 项目对话重复多条 #8437 [Bug]: 更新到 v1.24.1 后，打开对话显示多份重复对话 #8443 [Bug]: 之前项目的会话被清空了！！！ #8441 [Bug]: 项目内空白，重启后会话多点就会自我复制，分别是各个轮次 #8446 等，截至 2026-08-12 仍在新增）
• v1.24.1 的 catalog RecoveryCopy 隐藏（Fix v1.24.1 recovery catalog and Windows startup / 修复 v1.24.1 恢复会话目录与 Windows 启动闪窗 #8425）只解决"显示重复"，不解决"继续产生"——仍会产生 -recovery-* 文件
• 正式修复 PR fix(session): stop false diverged forks and bound depth-cap recovery / 修复误判 diverged 与 depth-cap 隔离副本无限增长 #8444（SivanCola 提交，2026-08-12）已 open，尚未合并：Fixes [Bug]: [v1.22.0 regression, v1.23.0 still repro] Recovery branch forks on every snapshot save — diverged loop at 30s cadence, single window, chain grows unbounded until depth cap #8294 [Bug]: [v1.23.0] recovery_depth_cap_isolated 未终止循环——SaveConflictRecoveryBranch(shutdown=true) 绕过深度上限(save.go:779)，隔离分支每 30s 继续 fork，2 天累积 3330 个 recovery 文件 #8342，合并前不建议升级
• 结论：在 fix(session): stop false diverged forks and bound depth-cap recovery / 修复误判 diverged 与 depth-cap 隔离副本无限增长 #8444 合并并发布新版本、且 issue 区稳定前，建议停留在 v1.21.5（配合方案 B 修复数据）

三、验证是否已恢复

# 无新 recovery 分支产生（应无输出或只有少量旧文件）
find <你的reasonix数据目录>/projects -name "*recovery*" -newermt "2026-08-12" | head

# 会话列表无重复、内容完整

四、给维护者的信息（已提交）

• 根因源码定位：save.go:779 depth 检查 && !shutdown 被 SaveConflictRecoveryBranch 以 shutdown=true 绕过
• 触发源：capability-route 瞬时块持久化（withCapabilityRoute 写盘 vs StripTransientUserBlocks 内存剥离，同一消息 content 不一致 → 非纯 append → diverged）；bash 输出 GBK/UTF-8 乱码入库（[Bug]: [Critical] Infinite recovery loop and UI freeze caused by JSON truncation (GBK/UTF-8 encoding mismatch during Bash tool call) #8213）
• 期望修复点：① cap 后 isolated 分支停止 fork；② 快照保存先判定"无外部修改"再 fork；③ Windows 下 bash 输出按 UTF-8 转码入库

---

本帖为社区临时解决方案汇总，非官方文档。正式修复请关注 PR #8444 与 release notes。

[MDZZ-123]

你这个复制的时候会触发 Windows文件路径超长的问题，导致无法正常复制，需要针对性修复一下
建议 import LongPathShutil as shutil

[Linearl]

⚠️ 更正（2026-08-12）：v1.21.5 并非完美方案——存在独立的"恢复→压缩死循环"（#8190）

本帖此前推荐"回退 v1.21.5"作为临时方案。经实测与源码比对，需要更正：v1.21.5 虽然无 v1.22+ 的 fork 风暴（那是 v1.22.0 引入的回归），但它自己有一条独立的 recovery 死循环链路，触发机制完全不同：

问题：恢复路径强制压缩循环（#8190）

• 机制：v1.21.5 压缩触发使用 provider 真实 usage（u.LatestPromptTokens()，compact.go:107）；每次 recovery 恢复都强制触发一次压缩 fold → 压缩后快照与磁盘 diverged → 再次恢复 → 再次压缩，无限循环
• 实测数据：[Bug] Desktop：会话反复自动恢复（recovery），每次恢复触发一次压缩——单日 230 次 #8190 报告者单日产生 230 个 -recovery-*.events.jsonl，每个含 1 次 replace fold；本机同款实证 169 分支/687 文件，每次恢复带 1 次压缩
• 影响：每次压缩 = 一次 LLM 摘要调用 → API token 成本爆炸（cache-reset 频繁）；长会话（1000+ 条）打开/继续即触发，内容反复折叠
• 修复状态：feat(agent): content-driven context maintenance (single compact_ratio) / 内容驱动上下文维护（单一 compact_ratio） #8244（内容驱动 compact_ratio + Windows 原子写修复 re-summary 循环）v1.24.0 才合入；v1.23.0 只含中文估算器高估修复（cba4f9b7 等），不含 feat(agent): content-driven context maintenance (single compact_ratio) / 内容驱动上下文维护（单一 compact_ratio） #8244

版本矩阵更新（2026-08-12，当前无任何版本同时修好两个问题）

版本	恢复→压缩循环（#8190）	fork 风暴（#8294/#8342）
v1.21.5	❌ 未修（长会话成本爆炸）	✅ 无
v1.23.0	❌（#8244 未合入）	❌
v1.24.0/1	✅（#8244 合入）	❌（PR #8444 未合并）

临时方案修订

1. v1.21.5 用户：已存在的大长会话不要再打开继续（触发即压缩循环）；需要继续的工作拆分到新会话；如必须用长会话，调大 context_window 提升压缩触发线可显著降低压缩频率
2. 短会话日常使用下，v1.21.5 仍是当前最稳组合
3. 最终目标仍是 PR fix(session): stop false diverged forks and bound depth-cap recovery / 修复误判 diverged 与 depth-cap 隔离副本无限增长 #8444 合并后的版本（feat(agent): content-driven context maintenance (single compact_ratio) / 内容驱动上下文维护（单一 compact_ratio） #8244 + fix(session): stop false diverged forks and bound depth-cap recovery / 修复误判 diverged 与 depth-cap 隔离副本无限增长 #8444 齐备 = 两个问题全解）；合并时建议同时确认修复范围覆盖 [Bug] Desktop：会话反复自动恢复（recovery），每次恢复触发一次压缩——单日 230 次 #8190 链路（恢复路径压缩触发）

参考：#8190（v1.21.5 恢复→压缩循环）、#8294/#8342（v1.22+ fork 风暴）、#8244（压缩重构，v1.24.0 合入）、#8444（fork 风暴修复，未合并）

[MDZZ-123]

1.24.2看起来是修复了

[esengine]

感谢整理！recovery 分支风暴已在 v1.24.2 从根源修复（同 revision 不再误判分叉、恢复文件有界、覆盖副本自动进入 .trash），升级到最新版本即可，无需再用临时方案。