Task Orchestrator

任务编排器

🧠 Agent 内核 · 🏠 首页 › Task-Orchestrator

---

📑 本页目录

• 1. 为什么需要它
• 2. 组件地图
• 3. 任务状态机（真实转移）
• 4. 批量执行引擎（BatchExecutionEngine）
• 5. 失败分类与恢复
• 6. 循环检测（LoopDetector）
• 7. 任务持久化与历史
• 8. 调试建议
• 9. 相关页面

当任务复杂到"一次 ReAct 循环说不完"时，就上 DefaultTaskOrchestrator： 任务状态机 + 批量执行引擎 + 失败分类恢复 + 循环检测 + 用户交互门。 本文记录真实的代码级转移与组件职责。

1. 为什么需要它

直连 ReAct 的短板	编排器的补丁
计划未经用户确认就动手	Planning → AwaitingPlanConfirmation：计划/规格要先批准
一步一次 LLM 往返，慢	BatchExecutionEngine：一轮内的多个动作批量顺序执行
失败后要么重试要么崩	FailureClassifier + RecoveryPlanner：分类后再决定重试/换路/求助
模型反复做同一组动作	LoopDetector：检测环并打破
需要人工决策时会瞎猜	UserInteractionGate：ask_user 挂起等待
看不见任务进度	TaskLifecycleEvent（SharedFlow）+ TaskProgress

2. 组件地图

orchestrator/
├── TaskOrchestrator / DefaultTaskOrchestrator     主干编排逻辑
├── TaskStateMachine                              状态与合法转移的唯一裁决者
├── TaskState / TaskProgress / TaskLifecycleEvent  对外可见的任务视图
├── BatchExecutionEngine                          一轮内批量执行（首错即停）
├── LoopDetector                                  重复动作/重复输出检测
├── FailureClassifier                             错误 → 可重试 / 终态 / 需人工
├── RecoveryPlanner                               恢复动作生成（换策略、降级、重规划）
├── RetryPolicy                                   次数/退避策略
├── ToolCallGraph                                 依赖关系图（辅助批处理与可视化）
├── ToolCallRunner                                单次工具调用封装
└── UserInteractionGate                           挂起等待用户答复

task/
├── TaskRuntime               任务执行上下文
├── TaskModels                任务模型定义
├── TaskStore / FileTaskStore 任务持久化（可查历史）
├── TaskStatusMachine         任务级状态
├── RecoveryPolicy            恢复策略
├── ToolExecutionPolicy       工具级执行策略
└── DanglingToolCallRepair    tool_call 悬空修复

3. 任务状态机（真实转移）

stateDiagram-v2
    direction LR
    [*] --> Idle
    Idle --> Planning : execute(mode)
    Planning --> AwaitingPlanConfirmation : PlanGenerated
    AwaitingPlanConfirmation --> Planning : 确认 / 重规划
    Planning --> AwaitingSpecConfirmation : SpecGenerated
    AwaitingSpecConfirmation --> Planning : 确认 / 重规划
    Planning --> Acting : ToolCallScheduled
    Acting --> Observing : ToolCallFinished
    Observing --> Planning : 下一轮迭代
    Observing --> Responding : 无更多工具调用
    Acting --> AwaitingUserInput : ask_user / 权限门
    AwaitingUserInput --> Acting : 用户答复
    Responding --> Completed : ResponseComplete
    Planning --> Failed : 异常 / 重试耗尽
    Acting --> Failed : 批量执行失败
    Observing --> Failed : 恢复规划失败
    Responding --> Failed : LLM 错误
    Planning --> Aborted : cancel
    Acting --> Aborted : cancel
    Responding --> Aborted : cancel
    Completed --> [*]
    Failed --> [*]
    Aborted --> [*]

Loading

Note

图是 TaskStateMachine 与 DefaultTaskOrchestrator / BatchExecutionEngine 中所有 transitionTo(...) 调用的合并视图。 Finished 是 sealed 终态（Completed / Failed / Aborted），终态不可逆。

状态含义速查

状态	含义	UI 表现
Idle	未启动	空闲
Planning	调 LLM 决策下一步 / 生成计划	思考中 + 可能出计划卡
AwaitingPlanConfirmation	等用户批准计划	计划确认卡（批准 / 重规划 / 取消）
AwaitingSpecConfirmation	等用户批准需求规格	规格确认卡
Acting	正在执行工具（可能批量）	工具卡片流
Observing	已拿到结果，整理后回到 Planning	短暂的过渡态
AwaitingUserInput	ask_user / 权限门挂起	选项菜单，等待人工
Responding	生成最终答复	流式气泡
Completed / Failed / Aborted	终态	任务卡收尾，可重开

4. 批量执行引擎（BatchExecutionEngine）

与工具层的 ToolBatchRunner（见 工具系统）互补：

• 语义：严格顺序 + 首错即停，未执行步骤统一返回契约原文 "Not executed: an earlier action in this turn failed."；
• 步间引用 {n}：整引用 / 模板内插值，头截断 4KB 防爆炸；前向 / 越界引用在执行前就拒绝；
• 预算：整批墙钟预算默认 120s（上限 600s），步骤上限 16。

5. 失败分类与恢复

flowchart LR
    E["工具/LLM 失败"] --> C{"FailureClassifier"}
    C -->|权限/沙箱/参数类| T["终态：重发同 payload 无意义<br/>直接 Failed 或降级提示用户"]
    C -->|超时/IO/执行错误| R{"RecoveryPlanner"}
    R -->|次数未耗尽| RT["RetryPolicy：全抖动指数退避<br/>delay = random(0 .. base * 2^attempt)"]
    RT --> A["重试 Acting"]
    R -->|同类动作反复| L["LoopDetector 介入：改策略/换工具"]
    L --> P["回到 Planning 重规划"]
    R -->|不可自动恢复| H["UserInteractionGate：ask_user 求指示"]

Loading

要点：

• 全抖动指数退避（AWS 风格）避免恢复中后端的惊群；
• 只有 readOnly || idempotent 的动作才允许盲重试（来自 ToolAnnotations 的 retrySafe 派生）；
• 恢复动作会被记入 ToolTraceRecorder，可在运行日志屏里复盘。

6. 循环检测（LoopDetector）

检测维度	例子	处理
重复工具调用（同参数）	连续三次 read_file 同一路径	打断并要求模型换策略
重复输出	模型每轮都生成同一句	触发重规划 / 降温采样
无进展迭代	N 轮工具全失败且状体未变	终态 Failed，避免烧 token

7. 任务持久化与历史

• TaskStore / FileTaskStore 把任务写入应用私有目录，Tasks 屏（任务历史）读它；
• TaskRuntime 持有执行上下文（取消令牌、进度、事件缓冲）；
• 取消：用户点击取消 → 任意非终态转移到 Aborted。

8. 调试建议

现象	先看	再看
一直卡在 Planning	LLM 是否返回了畸形 tool_calls（看运行日志）	DanglingToolCallRepair 是否被触发
计划卡不出	是否真的在 Plan/Spec 模式	TaskStateMachine 是否收到 PlanGenerated
工具一步失败全批停	这是契约行为（首错即停），先看第一个失败	失败是否 retrySafe
反复重试同一动作	FailureClassifier 判成了可重试	LoopDetector 阈值合理性
卡在 AwaitingUserInput	UI 是否消费了 UserInputRequired	UserInteractionGate 是否在等待答复

9. 相关页面

• Agent 引擎 —— 直连路径
• 上下文压缩 —— 共享的水位防线
• 工具系统 —— 批量/重试/熔断的落点在工具层
• 测试体系 —— 编排器有 6 大类测试套件

---

🏠 返回首页 · 📚 文档索引 · ❓ FAQ · 🔧 故障排查 · 🗺️ 路线图 · 🐛 提 Issue

_{Android Guru Agent · v1.4.4 · Kotlin 2.0.21 · Compose · PRoot · Room}