Checkpoint 基线权威化与空闲期 Drift 防护方案

[Yumiue]

Summary

• 目标：彻底消除“回退后下一轮仍用旧 checkpoint”与“空闲期外部改动后复用过时基线”的问题。
• 核心思路：把“本轮回退基线”从前端推断改为后端权威下发；前端只消费，不再猜。
• 分两层落地：
  1. P1（必须）：后端在 run 级 diff 返回权威 baseline checkpoint id，前端完全按它绑定文件回退基线。
  2. P2（增强）：run 开始时做轻量 drift 检测并打标，必要时触发“基线重建/降级提示”。

Implementation Changes

• 后端（runtime/checkpoint）
  1. 在 checkpoint.diff(scope=run) 结果中始终填充 prev_checkpoint_id（当前结构已有字段，无需改协议结构）。
  2. prev_checkpoint_id 定义为“本 run 的权威起始基线 checkpoint”，与 run 聚合 patch 的 before-side 一致。
  3. 若 run 基线不存在（历史缺失/首次会话），返回空值并附带可诊断 warning（日志 + 事件）。
  4. 增加 run 基线一致性校验：target checkpoint、run_id、prev_checkpoint_id 必须来自同一会话时间线。
• 前端（eventBridge / fileChanges）
  1. 文件项 checkpoint_id 绑定优先级改为：
     • run diff prev_checkpoint_id（权威）
     • 已有条目的 checkpoint_id（同 run 稳定）
     • 无（禁用回退）
  2. 移除/降级“依赖 _latestCheckpointId 和事件时序推断基线”的路径，仅作为极端 fallback。
  3. 保留 run 边界缓存隔离与 restore 并发序号机制，但不再承担“决定基线”的职责。
• Drift 防护（P2）
  1. run 开始前对工作区做轻量 fingerprint（推荐：git status + tracked file mtime/hash 抽样）。
  2. 与上次 run 结束指纹不一致时标记 workspace_drifted=true：
     • 继续执行，但在 UI 给出“基线可能被外部改动影响”的提示；
     • 若可获取权威 prev_checkpoint_id，仍以它为准，不让前端漂移。
  3. 后续可选：在 drift 严重时自动创建 manual 基线 checkpoint（配置开关，默认关闭）。

Public API / Interface Changes

• 不新增 RPC 方法。
• 行为变更：
  1. checkpoint.diff(scope=run) 的 prev_checkpoint_id 从“可空且常缺失”变为“权威基线（尽可能非空）”。
  2. 前端文件回退基线来源切换为后端下发，不再由事件顺序推断。
• 可选扩展（P2）：
  • 新增运行时告警事件字段 workspace_drifted（或沿用 warning 文本），仅用于提示，不阻断。

Test Plan

• 后端测试
  1. scope=run 返回中 prev_checkpoint_id 正确且与 patch before-side 一致。
  2. restore 后下一 run 的 prev_checkpoint_id 指向回退后的 checkpoint，而非 guard/旧点。
  3. 连续 restore 乱序请求下，最终 run diff 基线仍为最后一次 restore 生效结果。
  4. 无可用基线场景返回空 prev_checkpoint_id 且具备 warning。
• 前端测试
  1. 文件项回退基线优先取 prev_checkpoint_id，不受 _latestCheckpointId 干扰。
  2. 缺失 InputNormalized、事件乱序、跨 run 同路径编辑，基线仍稳定。
  3. isGenerating || isRestoringCheckpoint 禁用“接受/回退”保持不变。
• 端到端回归
  1. 空闲期外部删除文件后继续对话，文件回退基线不复用旧 run 推断值。
  2. 回退后立即下一轮修改，回退按钮对应基线为“回退后点”。

Assumptions

• 优先保证“基线一致性正确”而非“每轮强制完整工作区快照”性能最优。
• prev_checkpoint_id 语义固定为 run 聚合 diff 的 before-side 权威基线。
• P1 先落地闭环；P2 漂移检测作为增强，不阻塞主修复。