Plan 系统使用

当你给 AI 一个多步骤任务时，AI 会创建一个 Plan（计划）来组织和追踪工作进度。Plan 采用线性清单模型，由 AI 驱动执行。

什么是 Plan

Plan 是一个有序的步骤清单，AI 用它来：

• 分解复杂任务为可管理的步骤
• 追踪每个步骤的执行状态
• 在多轮对话中保持任务连贯性
• 让你能直观看到任务进度

Plan 的生命周期

创建

AI 通过 plan(action=create) 创建计划：

plan(action=create, steps=[
  "分析项目结构",
  "编写核心逻辑",
  "添加单元测试",
  "更新文档"
])

步骤状态流转

每个步骤有以下状态：

状态流转：pending → in_progress → done / skipped

完成

AI 通过 plan(action=complete) 标记计划完成。完成时，所有剩余的 pending 步骤会被自动收口。

Plan 的显示

在对话界面中，Plan 以进度条形式显示：

• 每个步骤的名称和当前状态
• 已完成步骤数 / 总步骤数（如 3/5）
• 步骤完成时的结果摘要

线性清单模型

wesclaw 的 Plan 系统采用线性清单设计：

• 步骤按数组顺序排列，没有依赖关系图
• 执行顺序由 AI 自行决定（通常按顺序，但可以灵活调整）
• 不存在 depends_on 字段或 DAG 结构
• AI 是 Plan 的唯一驱动者——引擎不会隐式推进步骤

步骤补标机制

AI 在执行工作后，可以在后续轮次中补标步骤完成状态：

• AI 先执行一批操作（read / grep / exec 等）
• 然后在下一轮通过 plan(action=update, task_id=0, status=done) 补标
• 引擎通过"工作账本"（Substantiated）记录哪些步骤有过实际工作

Run 异常终止时

如果 Run 异常终止（被中断、循环检测、预算耗尽等）：

• 正在进行的 Plan 会被标记为 terminated（附带终止原因）
• 未完成的步骤保持 pending 状态，不会被伪造为完成
• 前端会显示真实进度，而不是假装任务完成

与对话的关系

• Plan 是 SessionState 的子字段，随 CognitiveSettlement 一同持久化
• Plan 不独立持久化——它跟随会话生命周期
• 切换会话后，Plan 状态保留在原会话中

使用建议

1. 描述清晰的目标：告诉 AI 你要做什么，它会自动创建合适的 Plan
2. 不需要手动管理：Plan 由 AI 自主管理，你只需要在需要时给出反馈
3. 可以要求调整：如果 Plan 不合理，直接告诉 AI 修改
4. 中途停止是安全的：Plan 会记录真实进度，可以在新会话中继续

相关文档

• 上下文管理 → context-management.md
• 委派与子 Agent → delegation-subagent.md
• Run 生命周期 → run-lifecycle.md
• 错误恢复机制 → error-recovery.md