20 KiB

Raw Blame History

date	topic
2026-07-02	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

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（确认闸门）。

20 KiB Raw Blame History Unescape Escape