AtomCode Rewind 设计与实现:以显式回退工作流替代"双击 Esc 误触 /undo"

原创2026-10-15 14:49:351,874 阅读
文章标签:人工智能AI 应用AI Agent代码智能体CLIAI 评测

AtomCode Rewind 设计与实现:以显式回退工作流替代"双击 Esc 误触 /undo"

导读

AtomCode(项目根目录)在 TUI 中引入了一套名为 Rewind 的显式回退工作流,用于取代旧版"快速双击 Esc 立即执行 /undo"的隐式手势:会话被回退到某个选定的提示词边界之前,而不是由一次误触决定。本文以设计文档 docs/plans/2026-07-28-rewind-design.md 为骨架,结合仓库中 TUI、宿主控制契约、会话快照与运行时源码,完整讲解 Rewind 的所有权边界、每回合检查点数据、回退事务语义、TUI 交互细节、失败语义与磁盘安全设计。读完你将掌握该功能的完整工作流、底层调用链、配置开关与运维注意事项。

背景:为什么要用显式工作流替换"双击 Esc 运行 /undo"

设计文档开篇点明了动机:旧版本存在一个不安全的手势——快速双击 Esc 会立即执行 /undo。这个手势把"取消当前输入/停止当前回合"与"回退上一回合"两种语义压在了同一个按键序列上,误触概率高、后果不可逆。Rewind 的设计目标是:

用一个显式的 Rewind 工作流,将会话状态恢复到某个被选中的提示词边界,而不是"双击 Esc 立即回退"。

关键的安全保证在于选择器(picker)打开时默认停在 (current)(当前状态)上,因此误触产生的"双击 Esc + Enter"是一个无操作(no-op)——面板升起来时没有瞄准任何历史回合,回车只会把面板关掉,什么都不会发生。这一点在 TUI 源码中也有直接体现:面板打开后调用 rest_at_current 把光标停在列表末尾的"当前"行(crates/atomcode-tui/src/rewind.rs),并在 crates/atomcode-tui/src/rewind.rs 的按键逻辑中规定:停在"当前"上按 Enter 返回 Step::Close,只关闭面板。

v5.0.5 安全状态:代码恢复被禁用,对话回退不受影响

设计文档明确记录了 v5.0.5 的安全状态(safety status),这是理解整个设计的基石:

  • 工作区/代码恢复(Workspace/code restoration)被禁用。原因:原先按会话独立维护的 shadow-Git 实现没有磁盘配额(disk quota)也没有对象回收(object collection),可能耗尽系统磁盘。
  • Rewind 点现在独立于 Git 树持久化,因此"对话回退"(conversation Rewind)保持可用,且不会创建 ~/.atomcode/rewind 对象。
  • 代码恢复只有在"有界(bounded)、项目共享的快照设计"被单独评审通过后才可能回归。
  • 保留的兼容后端:所有 Git 子进程通过 Windows 的 CREATE_NO_WINDOW 路由,这是纵深防御(defense in depth),并不会重新启用捕获。

当前仓库代码验证了这段设计并记录了后续演进:在 crates/atomcode-capabilities/src/session/rewind.rs 中,LEDGER_VERSION 被提升到 2——v5.0.5 起 before_tree/after_tree 变为可选字段(纯对话回退点不携带工作区树),而"仍然接受 1..=LEDGER_VERSION 之间的版本",保证旧二进制写入的账本在升级后仍可读。同一文件中 code_rewind_enabled() 的注释则表明,在此后的版本中,代码回退因"有界存储"设计而重新默认开启(详见下文"磁盘安全演进"一节),并以 ATOMCODE_CODE_REWIND 环境变量作为总开关。

所有权与边界:谁是 Rewind 的主人

设计文档明确了三条边界,避免重蹈"TUI 侧拼凑文件系统写入 + /undo"的覆辙:

  1. CodingRuntime 是活跃编码生命周期(live coding lifecycle)的唯一所有者。Rewind 是一个运行时操作(runtime operation),不是 TUI 侧的本地组合。
  2. TUI 只做四件事:列出目标、选择范围、提交一个请求、等待一个"成功或失败"的终态。屏幕不直接碰文件系统,也不自行执行 undo。
  3. 会话检查点元数据属于 atomcode-capabilities::session,它复用现有的 SnapshotHook::turn_start 和 turn_complete 接缝(seam),不引入第二套逐回合状态机;kernel 保持中立、不做任何修改。

在源码中这三条边界各有对应实现:

TUI 侧的两份代码刻意分离:atomcode-tui 的 crates/atomcode-tui/src/rewind.rs 只描述"数据 + 按键"(RewindView、Point、Scope、Stage、Step),而真正知道"这次会话走过哪些回合"的宿主侧端口 RewindPort 实现位于启动器 crate crates/atomcode-cli/src/tui_rewind.rs——它把 HostCommand::RewindPoints 的返回翻译成屏幕认识的 RewindView,把 Scope::Conversation/Scope::Both 映射为 kernel 的 RewindScope。注释中明确说明了这样拆分的原因:屏幕不认宿主控制契约,是刻意的分层(参见 ADR docs/adr/0021-host-contract.md 与 docs/adr/0022-tui-and-agent-in-separate-apps.md)。

每回合数据:Rewind 点记录什么

设计文档规定,每个被接受的用户回合(turn)记录一个 rewind 点,内容为:

prompt ordinal and preview      # 提示词序号与预览
conversation revision/boundary  # 会话修订号 / 边界

两个钩子分工如下:

  • turn_start:记录提示词元数据,不扫描工作树。对应实现见 crates/atomcode-capabilities/src/session/snapshot.rs:统计非合成(!synthetic)用户消息数得到 prompt_number,取最后一条用户消息的前 120 个字符作为 prompt_preview,同时把会话快照写入 inflight 检查点。
  • turn_complete:包括被取消(cancelled)和失败(failed)的回合在内,持久化对话点,但工作区树字段留空(absent)。这一点在 SnapshotHook 的文件头注释中得到印证——turn_complete 在每一个终态触发,所以可恢复的 <id>.snapshot 与 <id>.meta 无论如何结束都会被刷新(crates/atomcode-capabilities/src/session/snapshot.rs)。

历史账本兼容:旧账本(含 Git 树 ID)仍可读,但 v5.0.5 不对它们提供代码范围(code scopes)。在数据结构上,RewindPoint 的 before_tree / after_tree 被序列化为 Option<String> 并默认跳过(skip_serializing_if = "Option::is_none"),旧 ledger 的字符串字段会反序列化为 Some,而 v5.0.5 对纯对话点写 None(crates/atomcode-capabilities/src/session/rewind.rs)。

账本本身也有防御性校验:RewindLedger::validate 拒绝未知的更新版本、超过 100 个点、只带一棵树(before_tree/after_tree 必须成对或全无)以及不严格递增的 turn_id(crates/atomcode-capabilities/src/session/rewind.rs)。

Rewind 事务:idle-only 与多重校验

设计文档规定事务的接受条件与校验链:

Rewind 仅在运行时**空闲(idle)**时被接受。它校验 generation(代际)、会话绑定(session binding)、会话修订号(conversation revision)与所选目标,然后使用现有的 native undo 事务。仅代码(code-only)与组合(combined)请求在变更前就以显式的 CodeRewindUnavailable 原因失败。

对应实现链:rewind_from_catalog 在 crates/atomcode-coding/src/runtime.rs 中:

  1. 从 catalog 中查找 turn_id 对应的点,找不到返回 RuntimeError::RewindPointUnavailable;
  2. 若 scope 涉及代码恢复且 catalog 带有 code_unavailable,直接返回 CodeRewindUnavailable(在变更发生之前);
  3. 读取当前快照修订号,与 catalog 中保存的 revision 不一致则返回 Busy——这就是"过期的 catalog 不会被对活状态重新解释"(stale catalog 拒绝)的机制,对应测试 rewind_from_stale_catalog_is_not_reinterpreted_against_live_state;
  4. 按 scope 决定是否走 undo 计划(undo_target),随后发送 BeginRewind 控制消息开始事务;
  5. 事务成功则 commit_rewind,失败则 compensate_rewind(把工作区与点账本都补偿回去)。

设计文档还提到"为什么一次回退要带 based_on":屏幕看到的最后一条事实就是它据以下判断的那条。若中间又落了一个回合,这一下回退指向的就不是人看见的位置——宿主按 Stale 拒掉,而不是回到一个谁都没打算回的地方。宿主侧 fresh() 正是这个守卫的实现:它检查基于 based_on 之后是否出现了新的 TurnStart / UserMessage 事件,若有则返回 HostError::Stale(crates/atomcode-cli/src/host.rs)。

三档范围与两档呈现

kernel 与宿主契约层面是三档:Conversation(只回对话)、Code(只回工作区)、ConversationAndCode(对话与工作区一起回)。但面板只提供两档:Conversation 与 Both——把文件退回去却留着讨论它们的对话,得到的是一份和自己的历史对不上的工作区,所以"只回工作区"这一档不出现在面板上(crates/atomcode-tui/src/rewind.rs)。注释同时说明:/rewind N 代码 这种命令路径仍然能触达第三档,那条路在 tui::commands 中。

TUI 交互:从双击 Esc 到两步选择

设计文档给出的完整 TUI 交互流程是 Rewind 的核心,必须完整保留:

Agent 运行期间:Esc 只负责取消。取消会清除并抑制空闲态的回退手势(cancellation clears and suppresses the idle Rewind gesture),因此连续的 Esc 按键事件不可能泄漏成一次回退。

空闲状态下:

  1. 第一次裸 Esc:显示既有提示(hint);
  2. 第二次裸 Esc:打开 Rewind 面板;
  3. (current) 被初始选中;
  4. Up/Down 选择更早的提示词;
  5. 在 (current) 上按 Enter:关闭面板,无操作;
  6. 在某个提示词上按 Enter:进入范围(scope)步骤;
  7. 范围默认是"仅对话"(conversation only);
  8. Enter 提交;Esc 返回上一步或取消。

从源码看,双击 Esc 手势由 Moment::escape_again() 实现:第一次 Esc 调用 arm_escape 记录时间戳,第二次 Esc 若间隔不超过 ESC_AGAIN_MS(1000ms,定义于 crates/atomcode-tui/src/moment.rs)则判定为手势。同时 disarm_escape 会在任何非 Esc 动作时被调用,保证"一次按键后跟着真实工作,下一次 Esc 不会打开没人要的面板"(crates/atomcode-tui/src/moment.rs)。手势时间用注入的时钟读取而非 Instant::now(),遵循 ADR docs/adr/0008-animation-time-is-injected-not-read.md。

两个入口(双击 Esc 与 /rewind 无参数)落到同一个 Action::ToggleRewind(crates/atomcode-tui/src/rewind.rs)。面板是两步交互:

  • 第一步(Stage::Points):列出每个回合——两行一条:上面一行是"人说过的那句话",下面一行是"那一回合动过什么"(文件路径与 +N -M 计数)。两行设计有明确理由:"回到哪儿"靠人自己说过的话认,"要不要回"靠它改过多少东西判(crates/atomcode-tui/src/modules/rewind.rs)。多行提示词只取第一行,避免把列表撑开;没改过文件的回合第二行也要说"没有代码改动",因为一条只有一行的条目读起来是"还没算完"。
  • 第二步(Stage::Scope):选择范围。能连代码一起回时默认停在"两样都回"(人点开回退面板通常是想把刚才那下整个撤掉);代码回不去时只有"仅对话"一档,且不可选的档会画暗、按下去什么都不发生并说出原因——"代码回不去的时候不给选项",因为"按下去什么都不会发生的开关,比不给还糟"(crates/atomcode-tui/src/rewind.rs)。

目标(targets)以对话检查点的形式展示提示词预览。仅代码与组合范围在 v5.0.5 中以显式的磁盘安全原因(disk-safety reason)被禁用——这一点在面板渲染中也有对应处理:当 code_unavailable 存在时,面板在列表最上方说一次"工作区为什么回不去"(整段折行显示,不截断),并且逐条不再画"代码改动"明细——因为"那些回合可能改了一堆文件,只是这次会话没在记"(crates/atomcode-tui/src/modules/rewind.rs)。

面板的键位图例:第一步为 ↑↓ 选择 / ⏎ 继续 / esc 关闭,第二步为 ↑↓ 选择 / ⏎ 执行 / esc 返回;有活在外面跑(读点、回退进行中)时只认 Esc 和 Ctrl+C,其余键一律吞掉,避免在第一次往返未回来时派出第二次回退(crates/atomcode-tui/src/rewind.rs)。

失败语义:所有失败都可见,未决状态保持 fail-closed

设计文档的失败语义可以归纳为四条硬性约束:

  1. 所有失败可见(All failures are visible):过期的 generation、忙碌的运行时、修订号变化、持久化回滚失败,绝不能报告为成功。
  2. 禁用代码回退期间,任何普通回合不得扫描或写入工作区检查点。
  3. 挂起的审批/请求状态保持 fail-closed——因为回退只发生在空闲态,等待中的审批不会被动回退。
  4. 宿主拒绝的话必须说给人听:在 crates/atomcode-cli/src/tui_rewind.rs 中,Busy、Unavailable、NotFound、Stale、Failed 被分别映射为对应的界面消息;而"代码为什么回不去"只传分类(NotEnabled / NoSession / Failed(message)),具体措辞由屏幕按用户语言翻译(crates/atomcode-cli/src/tui_rewind.rs)。

此外,事务的崩溃恢复是完备的:begin_rewind 在改动工作区或点账本之前先把恢复日志(RewindTransactionJournal,含 recovery_tree、restored_files、target_snapshot、committed 标记)持久化;会话加载时 recover_pending_rewind 读取日志,若目标快照已提交则完成 commit,否则补偿回滚(crates/atomcode-capabilities/src/session/snapshot.rs、crates/atomcode-capabilities/src/session/snapshot.rs)。运行时侧对应的测试包括 cancelled_rewind_transaction_compensates_and_releases_runtime 与 abandoned_rewind_recovers_after_undo_advances_generation。

验证:测试覆盖清单

设计文档列出的验证范围与仓库测试一一对应:

  • 选择器默认/当前行为:it_rests_on_current_where_enter_does_nothing(当前行回车无操作);
  • Esc 取消隔离:nothing_but_esc_is_taken_while_a_rewind_is_out_there(回退在途时吞掉其余按键);disarm_escape 对应 escape_again 的非手势场景测试;
  • 目标选择:choosing_a_turn_then_a_scope_is_what_goes_out(两步交互);
  • 无工作区树创建对话点:运行时测试 rewind_catalog_and_conversation_scope_are_runtime_owned(crates/atomcode-coding/src/runtime.rs),验证 code scope 不可用时仅对话范围生效;
  • 显式拒绝代码范围:code_rewind_unavailable 分支与 TUI 的 a_turn_that_changed_no_file_refuses_to_put_code_back、a_workspace_that_cannot_go_back_says_the_hosts_own_words;
  • 过期 generation/修订号拒绝:rewind_from_stale_catalog_is_not_reinterpreted_against_live_state;
  • 会话恢复:combined_rewind_compensates_workspace_when_agent_rebuild_fails 等事务恢复测试;
  • TUI 转录重绘:a_turn_that_changed_nothing_still_says_so、a_session_that_is_not_recording_code_says_that_once_rather_than_lying_per_turn、the_height_it_asks_for_is_the_height_it_draws 等渲染测试。

历史工作区测试仍作为兼容性覆盖保留,但"并不暗示 v5.0.5 启用了后端"——设计文档特别强调,现有代码不得把旧对象库的存在当作"代码恢复可用"的证据。

磁盘安全演进:从"无界 shadow-Git"到有界快照

设计文档描述的 v5.0.5 状态是"代码恢复整体禁用",而仓库当前代码(rewind.rs 与 snapshot.rs 的注释)记录了此后的演进:有界(bounded)代码回退设计评审通过后,代码恢复重新默认开启,并配套了三条磁盘防线(crates/atomcode-capabilities/src/session/rewind.rs):

防线 常量 说明
空闲磁盘下限 DISK_FLOOR_BYTES = 2 GiB 捕获或恢复前检查;未知空间按低于下限处理(fail-safe),避免"恢复写到一半磁盘满了"留下半恢复的工作区
单文件上限 MAX_SNAPSHOT_FILE_BYTES = 5 MiB 只对未跟踪文件生效;被跟踪文件的 blob 通过 alternates 与真实仓库共享,占用约等于零
存储预算 STORE_BUDGET_BYTES = 500 MiB 超预算先执行 gc --prune=now,仍超则跳过本次捕获;注意旧点不会被自动 LRU 逐出(属后续特性)

存储位置从文档中的历史 v1 布局 ~/.atomcode/rewind/<project-hash>/ 演进为 <user tree>/rewind/<bucket>/<session_id>(bucket 由 project_hash 派生),且绝不放在工作区内。shadow store 是独立 Git 目录,每次命令显式携带 --git-dir 与 --work-tree,捕获/恢复不触碰用户的 branch、HEAD、index 或 stash;工作树本身必须属于 Git 仓库,以此保证忽略语义可预测、失败时能 fail-closed 而不是假装任意的文件系统副作用可逆(crates/atomcode-capabilities/src/session/rewind.rs)。

配置开关:ATOMCODE_CODE_REWIND 设为 0、false、off 或 no 时关闭代码回退,其余值或不设置则开启(crates/atomcode-capabilities/src/session/rewind.rs)。这是当前仓库的默认行为;若你希望复现 v5.0.5 的"仅对话回退"行为,设置该变量即可。

运维:历史对象库的保留与清理

设计文档对历史存储给出了明确的运维指引,值得完整保留:

  • v5.0.5 不会自动删除已存在的旧存储。在第一个受影响的会话加载时,它只会使用旧存储完成对一次被中断的 v5.0.3 代码回退事务的补偿,随后再次丢弃后端。
  • 只要 AtomCode 报告"pending-Rewind 恢复失败",或者 native sessions 根目录下仍存在任何 *.rewind.txn.json 侧车文件,操作者必须保留该存储。
  • 在这些事务侧车文件消失、且 AtomCode 已停止之后,才可以删除 $ATOMCODE_HOME/rewind(当 ATOMCODE_HOME 未设置时为 ~/.atomcode/rewind)。此删除只移除历史代码检查点;native 对话会话存储在其他位置,不受影响、仍然可用。

也就是说,对话回退与代码检查点是两套独立的持久化:Rewind 点独立于 Git 树,对话会话由 SessionManager 单独管理,二者生命周期互不牵连——这正是 v5.0.5 之后"对话回退始终可用"的结构性保证。

小结

Rewind 是 AtomCode 在"回退"这件事上的一次彻底重构:用显式、两步、默认落点在 (current) 无操作的工作流替代了危险的"双击 Esc 运行 /undo";把代码恢复与对话回退解耦,先以 v5.0.5 的"禁用代码恢复"守住磁盘安全底线,再通过有界快照设计让代码回退在配额约束下回归。贯穿始终的三条原则——运行时单一所有权、TUI 只提交一次请求并等待终态、所有失败必须可见且 fail-closed——在宿主控制契约(docs/adr/0021-host-contract.md)、分层前端(docs/adr/0022-tui-and-agent-in-separate-apps.md)、会话日志权威(docs/adr/0024-the-session-log-is-the-authority.md)三项 ADR 的框架下,落成了可从 crates/atomcode-capabilities/src/session/rewind.rs、crates/atomcode-capabilities/src/session/snapshot.rs、crates/atomcode-coding/src/runtime.rs 与 crates/atomcode-tui/src/rewind.rs 逐行追溯的完整实现。

登录后查看全文
atomcode