AI Coding Agent 的时间推理：长线任务规划、异步等待与 Checkpoint-Restore 设计

问题示例：构建并部署到测试环境

用户："把这个服务部署到测试环境，然后等它启动完成后跑一套冒烟测试"

Agent 的实际行为：
  Step 1: 执行部署命令（docker-compose up -d）
  Step 2: 立即执行冒烟测试
  Step 3: 测试失败（服务还没启动完成）
  Step 4: 报告"部署有问题"
  
正确行为应该是：
  Step 1: 执行部署命令
  Step 2: 轮询服务健康检查，直到返回 200
  Step 3: 执行冒烟测试

执行：发送 HTTP POST 创建资源
等待：服务器返回 201 Created
继续：基于返回的 resource_id 执行下一步

触发：启动 CI 流水线（返回 pipeline_id）
轮询：每隔 30 秒检查 pipeline 状态
等待：直到 pipeline 状态为 success 或 failure
继续：根据最终状态决定下一步（成功则发布，失败则回滚）

触发："明早 9:00 发送报告"
处理：记录任务到 todo list，附上触发时间
等待：外部调度器（如 cron）在 9:00 触发 Agent 执行

能力一：时序依赖建模
  → 把任务分解为时序图（哪些必须等哪些）
  
能力二：异步状态追踪
  → 追踪异步操作的中间状态，知道"现在在哪一步"
  
能力三：断点恢复
  → 在中途失败后，能够从最后一个已知状态恢复，而不是从头开始

任务列表（平面视角）：
  1. 初始化数据库
  2. 启动服务
  3. 运行迁移脚本
  4. 执行冒烟测试

时序依赖图（有向无环图）：
         [初始化数据库] ──────→ [运行迁移脚本]
                │                      │
                ↓                      ↓
         [启动服务] ───────────→ [执行冒烟测试]
         
时序约束：
  - [运行迁移脚本] 必须等待 [初始化数据库] 完成
  - [启动服务] 必须等待 [初始化数据库] 完成（服务依赖数据库）
  - [执行冒烟测试] 必须等待 [运行迁移脚本] AND [启动服务] 都完成

A 依赖 B，B 依赖 C，C 依赖 A
→ 无法开始，任何任务都没有起点了
→ 检测到后需要报告人类，让人类重新设计

Agent 认为任务 3 可以和任务 1 并行
但实际上任务 3 的输出文件是任务 1 的输入
→ 任务 3 执行失败，返回"文件不存在"
→ 浪费了任务 3 的时间和 token

任务 A 和任务 B 都需要数据库连接池
如果并发执行，连接池耗尽，两个任务都失败
→ 需要在时序图上标注"资源约束"，强制串行

伪代码：
  start_time = now()
  timeout = 300  # 5 分钟
  interval = 30  # 每 30 秒检查一次
  
  while now() - start_time < timeout:
      status = check_async_status(pipeline_id)
      if status == "success":
          return Result(success=True)
      if status == "failure":
          return Result(success=False, reason="pipeline failed")
      sleep(interval)
  
  return Result(success=False, reason="timeout")

场景：部署新版本服务
  Step 1: 启动新版本容器（新版本 running）
  Step 2: 等待健康检查（超时 2 分钟）
  Step 3a: 健康检查通过 → 切换流量到新版本
  Step 3b: 超时 → 回滚（停止新版本容器，启动旧版本）

Agent 不主动轮询，而是：
  1. 注册 webhook 回调 URL 到外部系统
  2. 挂起当前任务，进入等待状态
  3. 外部系统在状态变更时 POST 到回调 URL
  4. Agent 收到回调后恢复执行

场景：重构整个后端（预计 3 小时）
  Step 1-20: 顺利进行（1.5 小时）
  Step 21: Claude Code session 因为 token 限制被重置
  问题：Agent 失去了所有上下文，不知道从哪继续

Restore 流程：
  1. 读取 Checkpoint 文件
  2. 重建当前任务状态（识别"我在哪"）
  3. 检查阻塞项状态（"什么东西在等我"）
  4. 处理阻塞项（向人类确认 / 等待 webhook / 继续）
  5. 从最后一步的下一条指令继续执行

关键原则：
  - 如果阻塞项已解决（人类已确认 / webhook 已到达）→ 立即继续
  - 如果阻塞项未解决 → 报告状态并等待，不自行绕过
  - 永远不"猜测"之前执行的正确性，必须基于 Checkpoint 的记录继续

Checkpoint 触发条件（满足任一）：
  - 完成一个阶段性里程碑（每 5-10 个步骤）
  - 遇到需要人类确认的决策点
  - 执行了不可逆操作（如 ALTER TABLE、删除文件）
  - Token 使用量达到当前 Session 的 70%

Checkpoint 不写入：
  - 纯计算步骤（如遍历数据生成报告）
  - 简单的文件修改（不涉及架构变更）
  - 读取操作（不会改变任何状态）

Architect 的输出（在标准 PRD 之外）：

## ⏱️ 时间规划

总预计时长：3 小时（估算，置信度：中）

关键路径（决定总时长）：
  init-db → run-migrations → smoke-test (100s 串行段)

可并行区域（理论加速比）：
  init-db 执行期间，start-service 可同时进行 → 节省 5s

异步任务清单：
  - CI 流水线：触发后需要轮询，最长等待 10 分钟
  - 部署：健康检查超时 2 分钟，超时回滚

Checkpoint 计划（每 10 Steps 写入一次）：
  - 位置：Shared Brain 的 ⏱️ 时间线 Section

Coder 执行规范：

遇到异步触发时：
  1. 立即将任务状态写入 ⏱️ 时间线 Section
  2. 选择适当的等待模式（轮询 / 事件驱动）
  3. 定期更新轮询进度（至少每 3 次轮询更新一次）
  4. 超时时触发回滚（如果已定义回滚计划）

遇到需要等待人类确认时：
  1. 写入 ⏸️ 阻塞项 Section
  2. 通知 Architect（写入 Coder → Architect 反馈）
  3. 不阻塞其他可执行的任务（如果有）

Checkpoint 写入：
  1. 完成阶段性里程碑时主动写入
  2. 不可逆操作前主动写入
  3. Architect 特别要求时写入

问题 1：任务是否涉及异步操作？
  是 → 需要时间推理（选择轮询 / 事件驱动）
  否 → 不需要，可以立即执行

问题 2：任务的预计时长是否超过 30 分钟？
  是 → 需要 Checkpoint（防止中途失败从头开始）
  否 → 标准 Session 管理足够

问题 3：任务是否有不可逆操作？
  是 → 需要回滚计划 + Checkpoint（在操作前写）
  否 → 可以不需要回滚计划，但 Checkpoint 仍然建议保留