---
date: 2026-06-15
topic: autonomous-task-execution
---

## Summary

打通 PlanExecEngine 和 TeamOrchestrator 的执行层，让 AgentKit 能真正自主拆解和执行多步任务。用户一句话描述复杂需求，Agent 自主生成可执行计划、逐步调用工具、返回完整结果。

## Problem Frame

AgentKit 已有完整的任务规划框架骨架——ReAct/PlanExec/ReWOO/Reflexion 四种推理引擎、TeamOrchestrator 多 Agent 协作、PipelineEngine DAG 编排——但执行层未跑通。TeamOrchestrator 的 `_execute_phase` 返回模拟字符串，PlanExecEngine 的步骤执行器功能简单，SharedWorkspace 未集成到执行层。结果是用户提出复杂需求后，Agent 只能简单对话回复，无法真正拆解执行。当前最需要的是把已有框架跑通，而不是新建能力。

---

## Key Decisions

**执行层对接优先于新能力建设。** 现有四种引擎和 TeamOrchestrator 框架已完整，最关键的差距是执行层模拟代码未替换为真实 Agent 调用。先跑通再迭代。

**验证场景选多步研究任务。** "帮我分析竞品并生成报告"这类任务天然需要搜索→分析→生成三步闭环，且不依赖本地开发环境，最能体现自主执行能力。

**步骤间状态通过 SharedWorkspace 传递。** PlanExecEngine 已有 `dependency_results` 机制但仅通过 prompt 注入，需要结构化状态管理。SharedWorkspace 已存在但未在执行层集成。

---

## Requirements

**执行层打通**

- R1. TeamOrchestrator._execute_phase 调用 Agent.execute() 执行真实任务，替代当前返回模拟字符串的实现
- R2. PlanExecEngine._LLMStepAgent 升级为完整 ReAct 循环执行器，支持工具调用和多步推理
- R3. SharedWorkspace 集成到 PlanExecEngine 和 TeamOrchestrator 执行层，步骤间可读写结构化状态
- R4. GoalPlanner 的 LLM prompt 调优，确保任务分解质量（子任务可执行、依赖关系正确、无遗漏）

**执行闭环**

- R5. 每个执行步骤完成后，结果自动写入 SharedWorkspace 并通知下游依赖步骤
- R6. 步骤执行失败时，PlanExecEngine 触发重规划（已有 PipelineReflector/PipelineReplanner，需集成）
- R7. TeamOrchestrator 的 COMPETITIVE_PARALLEL 模式下，合并策略（BEST/VOTE/FUSION）从真实执行结果中选择

**验证场景**

- R8. 多步研究任务端到端验证：用户输入"分析 X 竞品并生成报告"，Agent 自主拆解为搜索→分析→生成三步，逐步执行并返回完整报告
- R9. 执行过程通过 WebSocket 实时推送进度事件（plan_created / step_started / step_completed / plan_completed）

---

## Key Flows

- F1. 自主任务执行主流程
  - **Trigger:** 用户提交复杂任务（复杂度 > 0.7，路由到 TEAM_COLLAB 或 SKILL_REACT）
  - **Actors:** 用户, CostAwareRouter, GoalPlanner, PlanExecEngine/TeamOrchestrator, SharedWorkspace
  - **Steps:**
    1. CostAwareRouter 路由到合适的执行模式
    2. GoalPlanner 将目标分解为子任务计划（含依赖关系）
    3. PlanExecEngine 按依赖拓扑执行子任务，每个子任务通过 ReAct 循环调用工具
    4. 每步结果写入 SharedWorkspace，触发下游就绪检查
    5. 全部完成后综合结果返回用户
  - **Outcome:** 用户收到完整的任务执行结果，过程可观测

- F2. 执行失败重规划
  - **Trigger:** 某步骤执行失败（工具调用异常/LLM 返回无效结果/超时）
  - **Actors:** PlanExecEngine, PipelineReflector, PipelineReplanner
  - **Steps:**
    1. PlanExecEngine 捕获步骤失败
    2. PipelineReflector 分析失败原因
    3. PipelineReplanner 生成修正后的计划片段
    4. PlanExecEngine 用修正计划替换失败步骤，继续执行
  - **Outcome:** 任务从失败中恢复，无需用户手动干预

---

## Acceptance Examples

- AE1. **多步研究任务成功执行**
  - **Covers R1, R2, R3, R5, R8.**
  - **Given:** 用户输入"分析飞书和钉钉的竞品对比并生成报告"
  - **When:** Agent 自主执行搜索→分析→生成三步
  - **Then:** 返回包含竞品对比分析的完整报告，每步结果可在 SharedWorkspace 中追溯

- AE2. **步骤失败自动重规划**
  - **Covers R6.**
  - **Given:** Agent 执行"搜索竞品信息"步骤时搜索工具返回空结果
  - **When:** PlanExecEngine 触发重规划
  - **Then:** Agent 调整策略（如换搜索关键词/换搜索工具），重新执行该步骤

- AE3. **团队竞争模式真实执行**
  - **Covers R1, R7.**
  - **Given:** 两个 Expert 竞争执行同一分析任务
  - **When:** 各自独立执行并返回结果
  - **Then:** Lead Expert 根据合并策略选择/融合最佳结果

---

## Success Criteria

- 多步研究任务端到端成功率 > 80%（任务完成且结果包含所有子步骤输出）
- 执行过程通过 WebSocket 实时可观测（每个步骤有 started/completed 事件）
- 步骤失败时自动重规划成功率 > 50%（至少一次重规划后任务完成）

---

## Scope Boundaries

**Deferred for later:**
- 执行持久化与断点恢复（集成 PipelineState 到 PlanExecEngine）
- 自适应执行监控（token 预算控制、耗时趋势、策略动态调整）
- 人机协作规划 UI（用户实时调整计划）
- 计划模板库（复用历史成功计划）

**Outside this scope:**
- 动态工具发现与运行时组合（Agent 自主发现新工具）
- 跨任务长期记忆（任务间经验迁移）
- 多层级嵌套计划（子计划递归分解）

---

## Dependencies / Assumptions

- LLM Gateway 已配置且可用（至少一个 provider 有有效 API key）
- 搜索工具（WebSearchTool/BaiduSearchTool）已注册且可用
- SharedWorkspace 数据结构已定义（需确认与现有 `expert_team.SharedWorkspace` 的兼容性）
- GoalPlanner 的 LLM 分解质量足够支撑多步任务（可能需要 prompt 迭代）

---

## Outstanding Questions

- **Resolve Before Planning:** SharedWorkspace 的现有实现（`expert_team.SharedWorkspace`）是否可直接复用于 PlanExecEngine，还是需要新建？
- **Deferred to Planning:** TeamOrchestrator 的 `_execute_phase` 如何与 Agent.execute() 的异步签名对接（execute 是 async 方法，当前 _execute_phase 也是 async）

---

## Sources / Research

- `src/agentkit/core/react.py` — ReActEngine 完整实现，think-act-observe 循环
- `src/agentkit/core/plan_exec_engine.py` — PlanExecEngine，含 _LLMStepAgent 和 dependency_results
- `src/agentkit/experts/orchestrator.py` — TeamOrchestrator，_execute_phase 为模拟代码
- `src/agentkit/experts/team.py` — ExpertTeam 和 SharedWorkspace 定义
- `src/agentkit/orchestrator/pipeline_engine.py` — PipelineEngine，含反思-重规划闭环
- `src/agentkit/orchestrator/reflection.py` — PipelineReflector / PipelineReplanner
- `src/agentkit/core/goal_planner.py` — GoalPlanner，规则+LLM混合分解
