# 任务计划实际执行原理

## 核心设计思想

**任务计划没有专用执行引擎。** 计划的执行完全依赖 **system prompt 注入驱动 LLM 自主调用工具**。

## 一、生命周期

```
创建(子代理) → 等待审批(Web/外部) → 执行(system prompt 注入) → 逐步完成 → 归档
```

## 二、创建

主代理调用 `task_plan_create()` → 子代理 `generate_plan()` 返回 JSON → 校验 → 保存到 `users/<name>/task-plan/plan_xxxx.json`

## 三、审批

- Web UI: `POST /api/task-plan/<id>/resume` → status = "in_progress"
- 外部消息: `/plan approve plan_xxxx` → approve_plan() + chat("已批准，请继续执行")
- 每个端点都调用 `invalidate_prompt_cache()`

## 四、执行（核心）

### System Prompt 注入

```
## 活跃任务计划 [plan_xxxx]
**标题** — 执行中
  ✅ step_1: 已完成步骤
      结果: ...（截断 200 字）
  🔄 step_2: 当前步骤
  ⬜ step_3: 待执行

**请连续执行所有待完成的步骤，不要中断。完成每步后立即调用
task_plan_step_done(plan_id, step_id, result) 并接着执行下一步...**
```

### 执行循环
LLM 读到指令 → 调用工具执行步骤 → 调用 task_plan_step_done → prompt 更新 → 继续下一步

## 五、状态机

```
pending → in_progress → completed
             ↕
           paused → aborted
```

| 状态 | System Prompt 指令 |
|------|----------|
| pending | 等待用户审批，请勿执行 |
| in_progress | 请连续执行所有待完成的步骤 |
| paused | 不要主动执行步骤，等待用户确认 |

## 六、关键设计要点

1. **没有专用执行引擎** — 依赖主代理 run_chat_turn() 工具调用循环
2. **缓存失效驱动状态同步** — 状态变更 → invalidate_prompt_cache → LLM 读到最新状态
3. **步骤结果截断** — 只保留前 200 字
4. **防竞态保护** — 用户已中止的计划不再被覆写
5. **Web API 端点** — 列表/查看/暂停/恢复/中止/拒绝/编辑步骤/清理已完成
