245 lines
20 KiB
Markdown
245 lines
20 KiB
Markdown
---
|
||
date: 2026-07-02
|
||
topic: complex-task-quality-loop
|
||
---
|
||
|
||
# 复杂任务质量闭环（verify → reflect → evolve）
|
||
|
||
## Summary
|
||
|
||
围绕"单次任务做对 + 失败学习"主线，把 agentkit 已有但未接通的 verification / reflexion / evolution 串成闭环：复杂任务（PLAN_EXEC/TEAM_COLLAB）跑完先 verify，不过就 reflexion 反思重试，任务结束自动 trigger evolution 记 pitfall + 优化 prompt。地基补结构化编辑工具和"keep working until done"偏置。
|
||
|
||
---
|
||
|
||
## Problem Frame
|
||
|
||
agentkit 在复杂任务上"压根无法达到预期"——失败形态包括跑不了、走几步就错、直接说没能力。根因不是缺机制，而是机制"声明了但没接通"：
|
||
|
||
- `verification_enabled` 默认 `False`（`src/agentkit/core/react.py:165`），VERIFICATION 阶段不强制测试
|
||
- `write_file` 在 `_DEFAULT_CORE_TOOLS` 但无实现类（`src/agentkit/core/react.py:150-156`），LLM 调用会失败
|
||
- reflexion 只在 `_fallback_chain.py` 的 Recovery 层兜底，不在主流程
|
||
- evolution 只能手动 trigger（`/api/v1/evolution/trigger`），任务后不自动跑
|
||
- REWOO/REFLEXION/TEAM_COLLAB fall back to REACT（`src/agentkit/server/routes/chat.py:1336`），AGENTS.md 说的"抛 not yet supported"已过时
|
||
- `max_steps=10` 硬上限，无"keep working until done"偏置，达到即返回 partial
|
||
|
||
上述症状分三类：(1) **未接通**——reflexion 仅 fallback、evolution 仅手动、REWOO/REFLEXION/TEAM_COLLAB fall back to REACT；(2) **bug**——write_file 无实现类；(3) **缺特性**——keep-working 偏置缺失、max_steps=10 硬上限。Approach B 仅直接解决第一类（组装闭环），后两类为附带修复。
|
||
|
||
用户感受是系统性失效：没有尝试机制、没有自我进化。单点修复不解决——需要把独立零件组装成闭环。
|
||
|
||
---
|
||
|
||
## Key Decisions
|
||
|
||
- **选闭环主线（Approach B）而非逐项接通（A）或全新 Task Runtime（C）。** A 不形成闭环，体验仍碎；C 太重且浪费现有 plan_exec 基础；B 复用现有机制组装闭环。
|
||
- **reflexion 仅复杂任务走。** PLAN_EXEC/TEAM_COLLAB 启用任务中反思，DIRECT_CHAT/REACT 不走，避免简单任务被拖慢。
|
||
- **step 预算从单一 max_steps 改成阶段配额。** think/verify/reflect 三阶段共用 10 步不够，需分阶段配额。
|
||
- **evolution 自动触发而非手动。** 任务结束（无论成败）自动 trigger，失败必跑，成功按采样率跑。
|
||
|
||
### Resolved Questions（原 OQ1-OQ4，ce-doc-review 阶段研究解决）
|
||
|
||
- **RQ1（原 OQ1）step 阶段配额：think=7 / verify=2 / reflect=1，总预算 10（向后兼容当前 max_steps=10）。** 依据：1 step = 1 个 Think→Act→Observe 循环（含 1 次 LLM 调用 + N 次并行工具）；当前 verify 通过 `max_reinjections=1` 额外消耗 1 step；reflexion 的 evaluate/reflect LLM 调用不消耗 step 只消耗 token。三者独立计数不共享：think 耗尽→强制 verify，verify 耗尽→返回最佳结果，reflect 耗尽→不再反思。**预算辩护：** 总预算保持 10 是向后兼容约束；Problem Frame 所述 max_steps=10 不足问题通过阶段配额重新分配解决——当前 verify 通过 `max_reinjections=1` 额外消耗 1 step，RQ1 将其显式化为 verify=2 配额，释放出 think=7 连续推理预算（此前 think 与 verify 共享 10 导致 verify 消耗压缩 think）。若 planning 验证发现 10 步仍不足，复杂任务可 opt-in 提高总预算（向后兼容：未设时行为同今天）。
|
||
- **RQ2（原 OQ2）evolution 成功任务采样率 = 0.1（折中 0.15）。** 依据：默认 `RuleBasedReflector` 是 0 LLM 调用且只在 `outcome=="failure" and quality<0.3` 时生成 suggestions（成功任务几乎不产生 suggestions，进化流程早退）；`BootstrapPromptOptimizer.min_examples=3`，10% 采样下约 30 次成功任务凑够优化样本。新增 `EvolutionConfig.success_sample_rate: float = 0.1`，在 `on_task_complete` 入口用 `random.random() < rate` 门控，镜像 `alignment.py:115` 的 `audit_sample_rate` 范式。失败任务保持 100% 反思不变。**已知限制：** (1) 默认 `RuleBasedReflector` 仅在 `outcome=='failure'` 时生成 suggestions，成功任务采样路径在默认 reflector 下 100% 早退——成功采样需升级到能在成功任务上产生学习信号的 reflector 实现，或移除成功采样路径仅保留失败路径。(2) 0.1 采样率假设约 30 次成功任务凑够 `min_examples=3`，实际激活时间取决于任务吞吐量；`success_sample_rate` 已设为可配置（`EvolutionConfig.success_sample_rate: float`），应按观察到的实际吞吐量校准。
|
||
- **RQ3（原 OQ3）reflexion 最大重试：主路径 2 次，Recovery 层保持 1 次。** 依据：主路径当前硬编码 `max_reflections=3`（config_driven.py:1047,835，无法配置），Recovery 层 `max_reflections=1`（_fallback_chain.py:118）。改为 2 拉开梯度（第 1 次最有效，第 2 次兜底），并改为可从配置读取。reflexion attempt 次数由 `max_reflections=2` 配置独立限制，不消耗 step 配额；think 配额(7) 由所有 attempt 的 ReAct 循环共享；evaluate/reflect 的 LLM 调用不计 step 配额只计 token。
|
||
- **RQ4（原 OQ4）新增 `spec_review_request` 事件，不复用 `confirmation_request`。** 依据：①前端连接的是 `portal.py`（`/api/v1/portal/ws`），但 confirmation 协议只在 `chat.py` 实现，portal.py 完全无 confirmation——复用度极低；②`SpecManager.confirm` 是同步数据层方法，只通过 REST API（`/specs/{spec_id}/confirm`）调用，不接入 chat 流程；③`plan_exec_engine.py:277` 生成 Spec 后立即执行，无暂停点；④语义差异大：工具确认是单条命令批准/拒绝（5min 超时），Spec 确认是完整计划审核（confirm/reject/edit），拒绝后触发重新规划，需 `parked` 状态 + resume-on-return。新增 `spec_review_request`（携带 spec_id/goal/steps）、`spec_review_reply`（携带 decision），在 PlanExecEngine 新增 `spec_review_handler` 参数。
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
### 地基（所有任务受益）
|
||
|
||
- R1. 修复 `write_file` 占位符，提供结构化文件编辑工具（`str_replace_editor` 语义：create / str_replace / insert_at_line），取代 shell `sed`/`cat` 改文件。
|
||
**安全要求：** 所有路径参数必须 resolve 后前缀校验限制在 workspace root 内，拒绝符号链接逃逸；与现有 6 层终端安全范式对齐。
|
||
- R2. `verification_enabled` 默认改为 `True`。
|
||
- R3. VERIFICATION 阶段强制运行项目测试（pytest / ruff），而非仅白名单允许 shell。
|
||
|
||
### 闭环主线（复杂任务）
|
||
|
||
- R4. reflexion 从 fallback 兜底升级为复杂任务（PLAN_EXEC/TEAM_COLLAB）的主流程反思循环：verify 不过 → 反思 → 重试。
|
||
- R5. 任务结束（无论成败）自动 trigger evolution：Reflector 记录 + PitfallDetector 检测 + PromptOptimizer 优化。
|
||
**质量门：** pitfall 入库前设 confidence 阈值（低置信丢弃或标记 observe-only）；PromptOptimizer 消费 pitfall 前需通过消费门控（如样本数 ≥ min_examples 且 confidence 达标）；observe-only 模式下只记录不喂 optimizer，避免噪声退化 prompt。
|
||
- R6. evolution 触发阈值：失败必跑；成功按采样率跑。
|
||
**完整性/授权：** evolution 产物（pitfall / optimized prompt）跨任务共享前需标注 actor（哪个 agent / expert 产生），跨任务共享的信任边界由 planning 定义（默认同 workspace 共享，跨 workspace 需显式 opt-in）。
|
||
|
||
### 能力接通
|
||
|
||
- R7. TEAM_COLLAB 不再 fall back to REACT，真正接入对应执行模式（REWOO/REFLEXION-as-mode 推迟到 Deferred，理由见 Scope Boundaries）。
|
||
- R8. Spec 确认闸门接入 chat 流程：首次生成 Spec 后通过新增 `spec_review_request` 事件暂停等人确认，确认后（`spec_review_reply`）才执行。
|
||
|
||
### 偏置与预算
|
||
|
||
- R10. 复杂任务启用"keep working until done"偏置：达到 step 预算前不因单次 verify 失败放弃，自动进入反思重试。
|
||
- R11. step 预算改成阶段配额（think / verify / reflect），取代单一 `max_steps`。
|
||
- R12. pitfall 检索/注入：任务规划阶段从 PitfallDetector 库按 goal/skill 相似度检索历史 pitfall 并注入 prompt 上下文。
|
||
|
||
---
|
||
|
||
## Key Flows
|
||
|
||
- F1. 复杂任务质量闭环
|
||
- **Trigger:** PLAN_EXEC / TEAM_COLLAB 任务执行
|
||
- **Actors:** ReActEngine, VerificationLoop, ReflexionEngine, evolution 模块
|
||
- **Steps:** 任务执行 → verify → 不过 → reflexion 反思 → 重试（受阶段配额约束）→ 任务结束 → evolution 自动 trigger（失败必跑 / 成功采样）
|
||
- **Covered by:** R2, R3, R4, R5, R6, R10, R11
|
||
|
||
- F2. Spec 确认闸门
|
||
- **Trigger:** PLAN_EXEC 生成 Spec
|
||
- **Actors:** SpecManager, chat handler, user
|
||
- **Steps:** Spec 生成 → 暂停 → 用户确认（confirm / reject）→ 确认后执行 / 拒绝后重新规划
|
||
- **Covered by:** R8
|
||
|
||
---
|
||
|
||
## Visualizations
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
A[复杂任务启动] --> B[执行: think/act/observe]
|
||
B --> C{verify}
|
||
C -->|通过| D[标记完成]
|
||
C -->|不过| E{阶段配额?}
|
||
E -->|有剩余| F[reflexion 反思]
|
||
F --> B
|
||
E -->|耗尽| G[标记失败]
|
||
D --> H[evolution 自动 trigger]
|
||
G --> H
|
||
H --> I[Reflector 记录]
|
||
I --> J[PitfallDetector 检测]
|
||
J --> K[PromptOptimizer 优化]
|
||
```
|
||
|
||
---
|
||
|
||
## Acceptance Examples
|
||
|
||
- AE1. 复杂任务 verify 失败后反思重试
|
||
- **Covers R2, R4, R10.**
|
||
- **Given:** PLAN_EXEC 任务执行完成，verify 运行 pytest 失败
|
||
- **When:** reflexion 触发，反思错误，生成修正方案
|
||
- **Then:** 在阶段配额内重试；若仍失败，标记任务失败并 trigger evolution
|
||
|
||
- AE2. 简单任务不走 reflexion
|
||
- **Covers R4.**
|
||
- **Given:** DIRECT_CHAT 模式执行简单任务
|
||
- **When:** 任务完成
|
||
- **Then:** 不触发 reflexion 反思循环，直接返回结果
|
||
|
||
- AE3. 任务失败后 evolution 自动记录
|
||
- **Covers R5, R6.**
|
||
- **Given:** 复杂任务最终失败（verify 不过且重试用尽）
|
||
- **When:** 任务结束
|
||
- **Then:** evolution 自动 trigger，Reflector 记录失败原因，PitfallDetector 检测模式
|
||
|
||
- AE4. Spec 确认闸门
|
||
- **Covers R8.**
|
||
- **Given:** PLAN_EXEC 生成 Spec
|
||
- **When:** Spec 首次生成
|
||
- **Then:** 暂停执行等待用户确认；用户确认后才继续执行
|
||
|
||
---
|
||
|
||
## Success Criteria
|
||
|
||
- 复杂任务"半完成就停"消失：verify 不过自动反思重试，而非直接返回 partial。
|
||
- 复杂任务结果可信任：verify 通过才标记完成。
|
||
- 失败有沉淀：每次失败触发 evolution 记录，pitfall 不重犯。
|
||
- 简单任务不受影响：DIRECT_CHAT / REACT 不走 reflexion，响应不拖慢。
|
||
|
||
---
|
||
|
||
## Scope Boundaries
|
||
|
||
### Deferred for later
|
||
|
||
- 分级沙箱（read-only / workspace-write / danger）——P2 优先级；本次最低沙箱层级（workspace-write, no network）作为 R3/R10 前置拉入 scope，完整分级留后续。
|
||
- REWOO/REFLEXION-as-mode（作为独立执行模式接入）——R7 缩窄为仅 TEAM_COLLAB 后推迟；理由：当前无目标服务（RV10），且与 reflexion-as-retry-mechanism 概念混淆（RV20）。
|
||
- R9 coding_harness（Worker-Verifier 对抗）接入 PLAN_EXEC DELIVERY 阶段——推迟理由：R3+R4 已满足目标（RV11），4 阶段 pipeline 到单阶段 PLAN_EXEC phase 映射未定义（RV12），且 R8/R9 无独立成功标准（RV13）。**信任边界：** coding_harness 执行不受信任代码需在沙箱内运行，依赖最低沙箱层级前置。
|
||
- 模型自主 compaction——现有阈值方案能用。
|
||
- 三层嵌套循环（submission / handler / turn）——收益不抵成本。
|
||
- Spec 输出人类可读 markdown——本次先用现有 YAML Spec + 确认闸门，markdown 化留后续。
|
||
|
||
### Outside this product's identity
|
||
|
||
- 工具极简主义（砍到 Bash + apply_patch）——agentkit 走技能 / 专家团队方向，25 个工具是业务需要。
|
||
- 全新 Task Runtime 概念——已有 plan_exec 基础，不引入新概念。
|
||
|
||
---
|
||
|
||
## Dependencies / Assumptions
|
||
|
||
- evolution 模块（Reflector / PitfallDetector / PromptOptimizer / ABTester）已实现，本次只做接入。
|
||
- ReflexionEngine 已实现，本次升级其在主流程的角色。
|
||
- VerificationLoop 已实现，本次改默认值 + 强制约束。
|
||
- SpecManager.confirm 已实现（REST API），本次新增 `spec_review_request`/`spec_review_reply` 事件接入 chat 流程。
|
||
- coding_harness.yaml 已配置，本次接入 DELIVERY 阶段。
|
||
- 假设：step 配额重设计不破坏现有 DIRECT_CHAT / REACT 语义。
|
||
|
||
---
|
||
|
||
## Outstanding Questions
|
||
|
||
### Resolved（见 Key Decisions → Resolved Questions）
|
||
|
||
- OQ1-OQ4 已在 ce-doc-review 阶段研究解决，决策见 `Resolved Questions`（RQ1-RQ4）。
|
||
|
||
### New（ce-doc-review 研究阶段发现）
|
||
|
||
- **OQ5.** DIRECT_CHAT 模式（chat.py:1245）直接调 `llm_gateway.chat()`，绕过 BaseAgent —— 是否需要为 DIRECT_CHAT 补接 evolution 触发？还是接受"DIRECT_CHAT 不进化"（简单任务进化价值低）？
|
||
- **OQ6.** `execute_stream()`（config_driven.py:686）绕过 `on_task_complete`/`on_task_failed` 钩子 —— R5 的自动触发在流式路径下不生效。是在 `execute_stream` 末尾补接钩子，还是改为异步 fire-and-forget（`asyncio.create_task`）避免阻塞流式返回？
|
||
|
||
### From 2026-07-02 review
|
||
|
||
以下来自 ce-doc-review（5 persona：coherence / feasibility / product-lens / scope-guardian / adversarial）。17 个可操作发现 + 5 个 FYI 观察，全部留 planning 处理。
|
||
|
||
**P1 — 必须在 planning 解决（阻塞实现）**
|
||
|
||
- RV1. R11 阶段配额是 R4/R10/AE1 的隐藏前置但值推迟到 OQ1（product-lens, 100）。F1 闭环无法端到端验证直到 OQ1 解决。**处理：** planning 必须先定阶段配额 v0 值，或 descope R4/R10 直到 R11 决定。
|
||
- RV2. R2 全局 `verification_enabled=True` 与简单任务性能目标冲突（scope-guardian, 100）。REACT 非代码任务（翻译/研究）在 final-answer 会跑 pytest/ruff。**处理：** R2 限定 `PLAN_EXEC/TEAM_COLLAB 默认 True；DIRECT_CHAT/REACT 保持 False`。
|
||
- RV3. Sandbox 推迟到 P2，但 R3+R10 增加不受信任代码执行（product-lens, 75）。安全态势相对当前"早停"是倒退。**处理：** 将最低沙箱层级（workspace-write, no network）拉入本 scope 作为 R3/R10 前置，或新增 reflexion 重试的 workspace-bounded 约束。
|
||
- RV4. R4 假设 ReflexionEngine 能驱动 PLAN_EXEC，但缺 phase_policy 支持（adversarial, 75）。`reflexion.py:88-92` 实例化 vanilla ReActEngine 无 phase_policy。**处理：** R4 加依赖说明——ReflexionEngine 需重构转发 phase_policy，或在 ReActEngine 内实现 verify→reflect→retry（已持有 phase_policy）。
|
||
- RV5. R11"不破坏 DIRECT_CHAT/REACT 语义"假设 load-bearing 且未验证（adversarial, 75）。DIRECT_CHAT/REACT 用同一 ReActEngine（max_steps=10），无 verify/reflect 阶段。**处理：** R11 明确兼容契约——`max_steps 保留为总预算；阶段配额是复杂任务 opt-in 参数；未设时行为同今天`。
|
||
- RV6. R1-R3 bug 修复与闭环架构捆绑，延迟即时价值（product-lens, 75）。**处理：** 考虑拆 R1/R2/R3 为 ship-first 切片独立验收；R4-R11 作为第二阶段。
|
||
- RV7. "Pitfall 不重犯"目标半服务——只记录不检索（product-lens, 75）。R5/R6 只覆盖记录，无检索/注入。**处理：** 新增 pitfall 检索注入要求，或 descope"不重犯"条款。
|
||
|
||
**P2 — 应在 planning 解决（影响正确性）**
|
||
|
||
- RV8. R3 强制 pytest/ruff 但无要求处理无测试/非 Python 项目（product-lens+adversarial, 100）。非代码任务会错误失败或空真。**处理：** 限定 R3 为 coding 任务；非 coding 由 Spec 声明验证命令。
|
||
- RV9. Mermaid 将 reflexion 门控在配额检查之后，与 F1/AE1/Summary 矛盾（coherence, 75）。**处理：** 重排 mermaid——verify 失败→reflexion→配额决策。
|
||
- RV10. R7 拉入 REWOO/REFLEXION 模式但未绑定任何目标（scope-guardian, 75）。REFLEXION 独立与 R4 冗余，REWOO 无目标服务。**处理：** 缩窄 R7 为仅 TEAM_COLLAB。
|
||
- RV11. R9 adversarial harness 与 R3 重叠但无目标级理由（scope-guardian, 75）。R3+R4 已满足目标。**处理：** 从本 requirements 移除 R9 或单独论证。
|
||
- RV12. R9 将 4 阶段 pipeline 映射到单阶段 PLAN_EXEC phase，无映射定义（adversarial, 75）。**处理：** 替换 R9 为具体集成契约或推迟 planning。
|
||
- RV13. R8/R9 是孤立需求——无成功标准（product-lens+scope-guardian, 100）。**处理：** 为 R8/R9 加成功标准或移 R9 到 Deferred。
|
||
- RV14. R5/R6 自动触发 evolution 无输出质量门（product-lens+adversarial, 100）。噪声 pitfall 喂 PromptOptimizer 会退化 prompt。**处理：** 新增 pitfall confidence 阈值 + PromptOptimizer 消费门控 + observe-only 模式。
|
||
- RV15. R4/R10 忽略 ReActEngine 已实现 verify→reinject→retry（adversarial, 75）。`react.py:1278-1308` 已有 reinjection，仅 max_reinjections=1 门控。**处理：** R4 加决策说明为何选 reflexion 而非提升 max_reinjections。
|
||
- RV16. R8 Spec 确认闸门假设同步用户可用性，无异步回退（adversarial, 75）。现有 5 分钟超时，PLAN_EXEC 长任务用户离开即超时。**处理：** R8 加超时策略 + resume-on-return（parked 非 failed）。
|
||
- RV17. 成功标准可能全过但"半完成就停"仍存在（adversarial, 75）。预算值推迟 OQ1。**处理：** 加定量成功标准——参考任务至少一次 green run。
|
||
|
||
**FYI 观察（无需决策，planning 知悉即可）**
|
||
|
||
- RV18. R10 使用"step 预算"一词但 R11 明确替换它（coherence, 50）。术语不一致。
|
||
- RV19. R8 Spec gate 在每次 PLAN_EXEC 加摩擦；定位转移未承认（product-lens, 50）。
|
||
- RV20. R7/R4 混淆 REFLEXION-as-mode 与 reflexion-as-retry-mechanism（adversarial, 50）。
|
||
- RV21. MVP 路径（仅 R1+R2+R3）未在承诺 Approach B 前评估（adversarial, 50）。
|
||
- RV22. R10"keep working"与 ReActEngine 循环检测器（threshold=2）冲突（adversarial, 50）。重试相同 fix 会触循环检测中断。
|
||
|
||
**Residual concerns（新信号，非发现重述）**
|
||
|
||
- R7 TEAM_COLLAB 可能与 ExpertTeamRouter 路径重叠（feasibility）。
|
||
- ReWOOAgent/ReflexionEngine 是否暴露 streaming 接口兼容 chat WebSocket（feasibility）。
|
||
- SpecManager.confirm 同步签名 vs 异步握手——是否需新 awaitable gate（feasibility）。
|
||
- "keep working" + 阶段配额可能烧 token 不收敛（product-lens）。
|
||
- str_replace_editor/coding_harness 的 buy-vs-build 未考虑——OpenHands/Aider 有成熟替代（product-lens）。
|
||
- evolution 模块运行时正确性未验证——文件存在≠端到端正确（adversarial）。
|
||
- ReflexionEngine 默认值（quality_threshold=0.7, max_reflections=3）继承未论证（adversarial）。
|
||
- PLAN_EXEC vs TEAM_COLLAB 集成面不同——后者用 TeamOrchestrator+SharedWorkspace（adversarial）。
|
||
- evolution 模块是否在真实失败上端到端跑过（adversarial）。
|
||
|
||
---
|
||
|
||
## Sources / Research
|
||
|
||
- 6 维架构调研（带行号）：`src/agentkit/core/react.py`、`src/agentkit/core/verification_loop.py`、`src/agentkit/core/phase.py`、`src/agentkit/core/spec_manager.py`、`src/agentkit/core/plan_exec_engine.py`、`src/agentkit/server/_fallback_chain.py`、`src/agentkit/evolution/`、`src/agentkit/server/routes/chat.py`
|
||
- AGENTS.md 与代码不一致点：`src/agentkit/server/routes/chat.py:1336` REWOO/REFLEXION/TEAM_COLLAB 实际 fall back to REACT，非"抛 not yet supported"。
|
||
- `write_file` 占位符：`src/agentkit/core/react.py:150-156` 的 `_DEFAULT_CORE_TOOLS` 含 `write_file` 但无实现类。
|
||
- 业界参照：Codex agent loop（单线程 ReAct + 强制 verify）、Qoder Quest（Spec → Code → Verify 闭环 + 自动 evolution）、Trae SOLO Spec mode（确认闸门）。
|