AtomCode v5.0.9 新子系统深度分析 — 会话回退（Rewind）

基于 strings 结构体元数据 + Git 内部命令串的还原分析 2026-09-09 前置报告：05-version-diff-v4.25.5-to-v5.0.9.md

---

1. 源码模块（全新）

crates/atomcode-capabilities/src/session/rewind.rs      ← 回退引擎
crates/atomcode-capabilities/src/session/snapshot.rs    ← 快照引擎
crates/atomcode-tuix/src/modals/rewind.rs               ← TUI 回退模态框
crates/atomcode-capabilities/src/session/manager.rs     ← 会话管理（回退接入）

---

2. 数据模型（strings 类型元数据）

2.1 RewindPoint（回退点）

struct RewindPoint
  prompt_number / prompt_preview   ← 触发该点的提示词
  before_tree / after_tree          ← 回退点前后的 Git tree id

2.2 RewindLedger（回退台账，2 字段）

struct RewindLedger
  points        ← 全部回退点
  ...

2.3 RewindTransactionJournal（回退事务日志）

struct RewindTransactionJournal
  previous_points / retained_points   ← 回退前后保留点
  recovery_tree / restored_files      ← 恢复树与还原文件
  target_snapshot / committed         ← 目标快照与提交状态

→ 回退是带事务日志的：记录前/后状态，支持失败恢复。

2.4 内部版本协议

atomcode-rewind-version / atomcode-rewind-v1

→ 回退台账带版本头，跨版本演进可迁移。

---

3. Git 驱动的代码快照

3.1 工作树快照（核心机制）

code rewind requires a Git worktree          ← 前置条件
Failed to run git worktree add / remove
git worktree add --no-renames ...
refs/atomcode/update-ref --stdin              ← 专用 ref 命名空间
read-tree --empty / update-index --add / write-tree
git returned an empty tree id / write rewind tree
piped git stdin / list workspace files --name-only

机制还原：每个回退点 = 一次 Git worktree 代码快照：

1. git worktree add 创建隔离工作树
2. git read-tree --empty + update-index --add + write-tree 将文件内容写入对象库，得到 tree id
3. tree id 存入 RewindPoint.before_tree / after_tree
4. 快照 ref 写入 refs/atomcode/ 专用命名空间（不污染用户 refs）

3.2 快照信息

### GIT STATUS (snapshot at session start, not live)

→ 会话开始即打快照，作为回退的基线。

3.3 磁盘保护

Code Rewind is temporarily disabled in v5.0.5 to protect disk

→ 回退功能曾在 v5.0.5 因磁盘占用被临时禁用，v5.0.9 恢复。

---

4. 状态机与错误面

4.1 前置校验

rewind requires a persistent session        ← 临时会话不可回退
Can't rewind while the agent is working     ← 代理工作中禁止
code rewind is unavailable:                 ← 不可用状态

4.2 事务完整性

rewind transaction requires an active session lease   ← 需要会话租约
conversation rewind must have an undo plan            ← 必须预生成撤销计划
code rewind compensation lost its workspace checkpoint ← 补偿机制丢失检查点
rewind compensation lost its session checkpoint
$workspace changed after checkpoint:                  ← 检查点后工作区被改动

4.3 台账校验

more than 100 rewind points               ← 单会话回退点上限 100
retained rewind points are not a prefix of previous points   ← 保留点必须是前缀
rewind point has only one workspace tree
rewind turn ids are not strictly increasing
restored files require a recovery tree
rewind point has no code snapshot

4.4 快照完整性

session snapshot changed while preparing undo      ← 并发保护
session snapshot changed while preparing compaction
live session snapshot commit failed:
is missing its snapshot

4.5 用户界面

Rewind: restore the conversation to an earlier checkpoint
Could not start Rewind
Failed to load Rewind points
This session has no Rewind points yet.
Enter rewind

---

5. 与 /undo 的关系

a turn (/undo or /undo N)   ← 单回合撤销（轻量）
Rewind: restore the conversation to an earlier checkpoint   ← 会话级回退（重量）

机制	粒度	数据支撑
/undo [N]	单回合	回合边界
/rewind	会话检查点	RewindPoint + Git tree 快照

→ /undo 是回合级重放，/rewind 是带代码快照的会话级回退。

---

6. 逆向方法论备注

1. Git 管道命令串（read-tree --empty / update-index --add / write-tree）完整暴露了快照实现 = Git 对象库写树
2. refs/atomcode/ ref 命名空间是快照隔离的关键证据
3. RewindTransactionJournal 的字段名直接暴露事务语义（previous/retained/recovery/committed）
4. 版本头 atomcode-rewind-v1 + legacy rewind store 串揭示旧版兼容路径
5. v5.0.5 禁用声明说明该功能为 v5 系列新增，且经历过磁盘问题迭代

---

本报告由持续分析循环生成 — v5.0.9 会话回退（Rewind）深度分析