Plan-and-Execute

本课交付结果

你将交付 TodoManager.create/start/complete/block/snapshot：任务获得稳定顺序 ID，同一时刻最多一个 in_progress，只允许合法转换；所有返回值和快照都是不可变副本。

岗位问题

自然语言清单不能支撑长任务：模型可能同时声称执行多个步骤、跳过 pending 直接 complete，或在 UI 修改返回对象后污染 Runtime。Plan-and-Execute 首先是状态机，不是漂亮的 Markdown 列表。

前置检查

前置知识快照

先理解第 5 课 Agent Loop 的终止状态：

bash

pnpm --filter @learn-traeai/coding-agent-bootcamp verify:lesson -- 05

区分任务身份、展示标题与生命周期状态。ID 一旦分配不得随数组位置变化。

任务ID用于Trace、事件日志、审批和恢复引用，标题只用于人类理解。删除、排序或改标题都不能改变身份，因此不能用数组索引作为ID。todo-001顺序编号在单进程Lab中可重复预测，持久化版本会从事件或检查点恢复下一编号。

状态机把“允许发生什么”写成代码：create只到pending，start只从pending到in_progress，complete和block只从in_progress出发。不存在的边表示非法操作，不靠提示词劝模型遵守。

原理拆解

create 只产生 pending；start 要先证明没有其他 in_progress；complete 与 block 只接受 in_progress。内部 Map 保存当前事实，对外始终复制并冻结，防止调用方绕过转换方法。

mermaid

stateDiagram-v2
  [*] --> pending: create
  pending --> in_progress: start
  in_progress --> completed: complete
  in_progress --> blocked: block(reason)
  completed --> [*]
  blocked --> [*]

同一时刻最多一个in_progress，是课程版Plan-and-Execute的核心不变量。它迫使Agent明确当前焦点，UI和恢复逻辑也无需推断多个并发步骤的依赖。需要并行任务时应引入显式依赖图和调度器，而不是删掉检查让状态变得含糊。

start先扫描现有任务是否有进行项，再验证目标pending。检查顺序影响错误信息，但不能让第二任务进入。单线程JavaScript内同步方法足够；跨进程持久化后，需要事务或compare-and-swap避免两个worker同时通过扫描。

complete不接受pending，因为“计划中直接完成”会丢失实际执行开始证据；blocked也只接受active并要求非空原因，让用户知道为什么停。若任务在开始前就不可行，可先start再block，或未来增加cancelled状态及明确转换。

状态转换构造新Todo，不原地修改内部对象。对外返回 Object.freeze({...todo})，snapshot冻结数组与每个条目。只冻结外层数组仍允许UI改 snapshot[0].status，绕过Manager并污染后续事实。

Map保留创建顺序，snapshot因此稳定按计划顺序返回。排序展示应由UI在副本上完成，不能修改内部顺序。状态更新用相同id替换Map value，不改变插入位置。

blocked reason先trim并保存清洁文本，空白拒绝。生产reason应结构化包含failure fingerprint、需要的用户动作与诊断id，避免自由文本成为唯一恢复依据。本Lab先证明非空解释契约。

代码实验

失败实现

普通可变数组允许任何调用方直接跳状态：

const todos: Todo[] = [];
function complete(index: number) {
  todos[index]!.status = "completed";
}

正确实现集中转换并返回冻结副本：

private transition(id: string, from: TodoStatus, to: TodoStatus, reason?: string): Todo {
  const current = this.get(id);
  if (current.status !== from) {
    throw new Error(`任务不能从 ${current.status} 转为 ${to}`);
  }
  const next: Todo = {
    id: current.id,
    title: current.title,
    status: to,
    ...(reason === undefined ? {} : { reason }),
  };
  this.todos.set(id, next);
  return Object.freeze({ ...next });
}

snapshot(): readonly Todo[] {
  return Object.freeze([...this.todos.values()].map((todo) => Object.freeze({ ...todo })));
}

打开本课 Lab

bash

pnpm --dir bootcamps/coding-agent/labs/21-plan-and-execute/starter test
pnpm --dir bootcamps/coding-agent/labs/21-plan-and-execute/solution test

Starter 应声明 实现任务状态转换；Solution 应通过 5 项测试。

不变量测试既检查错误也检查事实未变：

it("已有进行项时拒绝启动第二项", () => {
  const manager = new TodoManager();
  const first = manager.create("A");
  const second = manager.create("B");
  manager.start(first.id);
  expect(() => manager.start(second.id)).toThrow("已有进行中");
  expect(manager.snapshot().find((item) => item.id === second.id)?.status)
    .toBe("pending");
});

关键实现讲解

ID 使用 todo-001 顺序生成，便于 Trace 和恢复引用。转换函数统一验证来源状态并构造新对象；blocked 必须有非空原因。snapshot 冻结数组及每个 Todo，而不是只冻结外层。

create清理标题并先拒绝空值，只有成功后才递增nextId，避免失败创建留下编号洞。参考实现把递增写在对象构造中，但校验在前；并发持久化版本需要序列化ID分配。

未知ID错误应在任何转换前发生，且不泄露全部任务内容。生产API返回稳定code TODO_NOT_FOUND，message用于展示。状态冲突使用current/expected/target字段，方便调用方重新snapshot而非解析中文。

运行与验证

真实运行输出

bash

pnpm --filter @learn-traeai/coding-agent-bootcamp verify:lesson -- 21
pnpm --filter @coding-agent/state test

检查第二个任务无法在已有进行项时 start，pending 不能直接 complete，修改 snapshot 元素会抛 TypeError。

真实Solution五项应全部通过：

text

solution: 5 passed, 0 failed
覆盖: 稳定顺序ID / 单一进行项 / 合法转换 / 阻塞原因 / 深层不可变快照

再连续创建十二项确认补零与递增，尝试空标题、未知ID、重复complete、空reason和修改返回对象；每次失败后snapshot与next合法状态保持一致。

常见失败与排查

故障案例 1

两个步骤同时显示“进行中”。

症状：Agent开始B时A尚未完成，恢复后无法判断当前焦点。

根因：start只修改目标，没有检查全局in_progress不变量。

定位：创建两项依次start，检查第二次是否抛错以及B是否仍pending。

修复：在转换前扫描active任务；并发持久化时用事务或单writer序列化。

故障案例 2

任务从pending直接completed。

症状：计划看似全部完成，却没有任何开始、执行或验证事件。

根因：complete只写目标状态，没有校验来源。

定位：对新任务直接complete，查看是否成功以及Trace是否缺start。

修复：集中transition验证精确from，非法边拒绝且不改变状态。

故障案例 3

UI改标题导致Runtime事实变化。

症状：渲染层为了截断标题修改snapshot，后续日志出现被改文本。

根因：snapshot返回内部对象引用或只冻结数组外层。

定位：检查数组和元素Object.isFrozen，尝试赋值后重新snapshot。

修复：每次返回新对象并冻结，数组也冻结；生产嵌套details使用深拷贝schema。

ID 使用数组索引：删除或重排后身份漂移。
只冻结数组：元素仍能被外部改写。
complete 接受任意状态：状态机失去证据价值。
block 不记录原因：恢复时不知道缺少什么。

课后作业

增加取消和重新打开规则，并生成事件流而非只保存最终快照；写性质测试证明任何操作序列都不会出现两个 in_progress。

验收 Rubric

维度	通过标准	常见扣分
身份	ID 稳定且连续	使用可变数组位置
转换	只允许明确状态边	任意状态可跳转
并发语义	最多一个进行项	多任务同时 in_progress
不可变性	数组与元素都冻结	暴露内部对象

总项目增量

总项目包：@coding-agent/state

总项目路径：packages/state/src/todo-manager.ts

总项目验证命令：pnpm --filter @coding-agent/state test

本课让计划可执行；下一课把每次状态变化追加到可恢复 JSONL 会话。

Plan-and-Execute

本课交付结果

岗位问题

前置检查

前置知识快照

原理拆解

代码实验

失败实现

关键实现讲解

运行与验证

真实运行输出

常见失败与排查

故障案例 1

故障案例 2

故障案例 3

课后作业

验收 Rubric

总项目增量

延伸阅读

方案对比与工程取舍

下一课衔接

Plan-and-Execute ​

本课交付结果 ​

岗位问题 ​

前置检查 ​

前置知识快照 ​

原理拆解 ​

代码实验 ​

失败实现 ​

关键实现讲解 ​

运行与验证 ​

真实运行输出 ​

常见失败与排查 ​

故障案例 1 ​

故障案例 2 ​

故障案例 3 ​

课后作业 ​

验收 Rubric ​

总项目增量 ​

延伸阅读 ​

方案对比与工程取舍 ​

下一课衔接 ​

Plan-and-Execute

本课交付结果

岗位问题

前置检查

前置知识快照

原理拆解

代码实验

失败实现

关键实现讲解

运行与验证

真实运行输出

常见失败与排查

故障案例 1

故障案例 2

故障案例 3

课后作业

验收 Rubric

总项目增量

延伸阅读

方案对比与工程取舍

下一课衔接