fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/brainstorms/2026-06-29-advanced-agent-g...

12 KiB
Raw Blame History

date topic type origin
2026-06-29 advanced-agent-gap-optimization feature 2026-06-24-004-feat-long-horizon-reliability-optimization-plan.md(增补);Qoder/Codex/Hermes/Trae Work 架构对比(2026-06-29)

Summary

为 2026-06-24-004 长程可靠性 plan 补齐 9 个真新缺口——对比 Qoder/Codex/Hermes/Trae Work 后未被覆盖的执行/反馈/效率短板。分 3 波按 ROI/风险交付:Wave 1 自包含快速补强(W1-1~W1-4),Wave 2 中等耦合(W2-1~W2-3),Wave 3 战略级重构(W3-1~W3-2)。每波独立 plan、独立验证、独立发布。

Problem Frame

2026-06-24-004 plan 已落地循环检测(U1)、Headroom 压缩(U3)、SharedWorkspace Redis 化(U4)、中间件管道(U6)、阶段级 checkpoint+resume(U7)等长程可靠性护栏。但对照 Qoder(Spec→Coding→Verify 闭环)、Codex(apply_patch+OS 沙箱)、Hermes(三级降级链+4层记忆)、Trae Work(SOLO 四阶段状态机+Trajectory 持久化)的工程实践,agentkit 仍存在 9 个已在生产/测试中观察到痛点的短板,横跨三个维度:

  • 反馈稳定性:verify 失败不回灌 ReAct 直接退出、工具调用无 schema 校验、主 agent 失败后仅静态 fallback、子任务失败不回滚已写文件
  • 响应效率:prompt cache 命中率低(记忆注入破坏前缀)、摘要/压缩用主模型、文件读取无函数级分片、token chunk 无节流
  • 执行能力:ReAct 循环无阶段约束(think 阶段即可 write_file)

验证器已核对 10 项仓库声明,9 项 confirmed,2 处修正(C5:agentkit 无独立 read_file 工具,文件读取走 tools/shell.py 的 cat;C6:PlanPhase 定义在 experts/plan.py:148 非 team.py)。

Key Decisions

KTD1:G1 verify 回灌一次后中断

verify 失败时自动把 errors 注入 conversation 继续 ReAct,但仅重试一次;二次失败则中断返回错误给用户(附 verify log)。平衡自动纠正与 token 成本,而非全自动循环到 max_steps 烧 token。

KTD2:3 波按 ROI/风险分次

Wave 1(G1/G2/G3/G8)自包含、低风险、可独立验证;Wave 2(G4/G7/G9)中等耦合,需触碰 LLM 层与编排层;Wave 3(G5/G6)战略级,引入新依赖或触 ReAct 核心。优先交付自包含补强,而非按维度或 LLM 层依赖分波。

KTD3:G2 三层 prompt 结构跨 provider,记忆注入移到 volatile

system prompt 重构为 stable(技能配置/系统指令)/ context(会话上下文)/ volatile(记忆检索+时间戳)三层。memory_retriever 当前在 react.py:1042-1059 把"## 参考信息"拼到 system prompt 末尾,每次随 query 变化破坏 cache 前缀——移到 volatile 层,stable 层保持不变以命中 prompt cache。cache 策略跨 provider 统一:Anthropic 用原生 cache_control 断点(system_and_3),OpenAI 等依赖自动前缀缓存(stable 层前置即命中),无需为每个 provider 单独适配。

KTD4:G7 复用 ReflexionEngine 作为 Recovery 层

主 agent 失败后触发 Recovery 层,复用现有 ReflexionEngine(core/reflexion.py:58,Evaluate→Reflect→Retry),而非新建 Recovery Agent。Recovery 仍失败则进入 Emergency 层(规则化 fallback,返回结构化错误+建议)。避免新基础设施,最大化复用现有反思机制。

KTD5:G9 阶段级 rollback,git checkout 机制

PlanPhase 增加 validation_command/rollback_command 可选字段,阶段失败时执行 rollback(默认 git checkout),与 U7 checkpoint 协同——checkpoint save 必须在 rollback validation 通过后。不做步骤级 rollback(粒度过细,实现复杂度高)。

KTD6:G5 函数级分片引入 tree-sitter(Wave 3 决策可延后)

Wave 3 的 G5 需要按 symbol/函数粒度分片读取文件,引入 tree-sitter 作为新依赖。具体集成方式(tree-sitter vs ANTLR4 vs 复用 quality 模块)延后到 Wave 3 自己的 plan 决策。

KTD7:G6 扩展 PLAN_EXEC 而非新建模式

G6 SOLO 四阶段状态机约束通过扩展现有 ExecutionMode.PLAN_EXEC 实现,而非新建独立模式。阶段约束(Planning 阶段只允许 think/search,Building 才允许 write_file)作为 PLAN_EXEC 的配置项。

Requirements

Wave 1 — 自包含快速补强(P0,低风险)

G1 Verify 失败回灌 ReAct

  • R1. verify 失败时,系统自动把 errors 作为新 user 消息注入 conversation,继续 ReAct 循环,而非直接抛 TaskResult.error_message 退出。
  • R2. 回灌后若二次 verify 仍失败,系统中断执行并返回错误给用户,附 verify log(测试输出/schema 错误明细)。
  • R3. 回灌最大重试次数可配置(默认 1 次),受 max_steps 上限约束。

G2 prompt cache 断点策略

  • R4. system prompt 重构为三层:stable(技能配置/系统指令)、context(会话上下文)、volatile(记忆检索+时间戳)。
  • R5. 记忆检索注入从 system prompt 末尾移到 volatile 层,stable 层保持不变以命中 prompt cache。
  • R6. 跨 provider 统一 cache 策略:Anthropic 显式插入 cache_control 断点(system_and_3,最多 4 个);OpenAI 等无原生断点的 provider 依赖自动前缀缓存,通过 stable 层前置保证命中。
  • R7. 多轮对话输入 token 成本降低(目标降低 ~50% 输入 token,跨 provider 均受益)。

G3 工具调用 schema 校验

  • R8. _execute_tool 调用工具前,基于 tool.input_schema 校验 LLM 传入参数(类型/必填)。
  • R9. 校验失败时返回类型化错误码(tool_call_invalid/schema_mismatch),不执行工具。
  • R10. 错误以 tool 角色消息回灌 conversation,给 LLM 自我修正机会。

G8 delta_flush_interval 调速

  • R11. execute_stream 的 token chunk yield 加可配置节流(默认 flush_interval_ms,如 50ms)。
  • R12. 节流配置化(agentkit.yaml 或 runtime 配置),允许客户端调高降低渲染开销。

Wave 2 — 中等耦合(P1)

G4 辅助 LLM 分流

  • R13. ContextCompressor 摘要任务路由到 auxiliary model(便宜模型,如 Gemini Flash/Doubao lite),而非主 model。
  • R14. auxiliary_model 配置化,与主 model 分离。
  • R15. 摘要质量不降级:auxiliary model 失败时回退主 model。

G7 三级降级链

  • R16. 主 agent 失败后触发 Recovery 层(复用 ReflexionEngine 做 Evaluate→Reflect→Retry)。
  • R17. Recovery 仍失败触发 Emergency 层(规则化 fallback,返回结构化错误+建议)。
  • R18. 降级链可配置(每层最大重试次数、是否启用 Recovery/Emergency)。

G9 原子化子任务 + rollback 绑定

  • R19. PlanPhase(experts/plan.py:148)增加 validation_command 和 rollback_command 可选字段。
  • R20. 阶段失败时自动执行 rollback_command(默认 git checkout),与 U7 checkpoint 协同。
  • R21. checkpoint save 必须在 rollback validation 通过后(避免持久化失败状态)。

Wave 3 — 战略级重构(P2,高风险)

G5 函数级代码分片

  • R22. 文件读取支持按 symbol/函数粒度分片(需引入 tree-sitter 或类似,具体方式延后到 Wave 3 plan)。
  • R23. 分片能力作为工具参数(如 symbol="function_name"),向后兼容整文件读取。

G6 SOLO 四阶段状态机约束

  • R24. ReAct 循环加阶段约束:Planning 阶段只允许 think/search,Building 阶段才允许 write_file。
  • R25. 阶段状态可配置(扩展 ExecutionMode.PLAN_EXEC,非新建独立模式)。

Cross-cutting

  • R26. 所有优化项配置化(agentkit.yaml 新增对应配置节,遵循 ServerConfig.from_dict 模式)。
  • R27. 每个优化项附最小自检测试(ponytail 规则,参考 test_pipeline_state.py 的 TestPipelineStateRedis 模式)。

Acceptance Examples

  • AE1(Covers R1, R2, R3):用户发起 ReAct 任务,verify 失败(测试不通过)→ 系统自动把 errors 注入 conversation 继续 ReAct → LLM 修正后二次 verify 通过 → 任务完成。若二次 verify 仍失败 → 中断返回错误,附 verify log。
  • AE2(Covers R4, R5, R6, R7):用户发起 50 轮长对话 → stable 层(技能配置)保持不变,volatile 层(记忆检索)随 query 变化 → Anthropic prompt cache 命中 stable 前缀 → 输入 token 成本降低 ~50%。
  • AE3(Covers R8, R9, R10):LLM 调用工具时传错参数类型(如 count: "abc" 应为 int)→ schema 校验失败 → 返回 tool_call_invalid 错误码 → 错误回灌 conversation → LLM 修正参数类型后重试成功。
  • AE4(Covers R16, R17, R18):主 agent 连续 3 次失败 → 触发 Recovery 层(ReflexionEngine 反思重试)→ Recovery 仍失败 → 触发 Emergency 层(规则化 fallback,返回结构化错误+建议)→ 用户收到清晰错误而非静态文案。
  • AE5(Covers R19, R20, R21):@team 任务阶段 3 失败 → 自动执行 rollback_command(git checkout 阶段 3 写入的文件)→ rollback validation 通过后才 save checkpoint → 阶段 4 从干净状态继续。
  • AE6(Covers R11, R12):弱网客户端连接 execute_stream → token chunk 按 50ms 节流批量 yield → 前端渲染开销降低,无卡顿。

Scope Boundaries

Deferred for later

  • Wave 3(G5/G6)的具体实现设计延后到 Wave 3 自己的 plan,本文档只锁定战略方向(KTD6/KTD7)。
  • G5 的具体集成方式(tree-sitter vs ANTLR4 vs 复用 quality 模块)延后到 Wave 3 plan 决策。
  • G7 Emergency 层的具体规则模板(返回什么错误结构、建议什么动作)延后到 Wave 2 plan。
  • 全局 LLM 并发限制(LLMGateway 内 semaphore)——本期只做工具层/编排层,LLM 层并发延后。

Outside this product's identity

  • 重写现有编排逻辑(拓扑排序/Board 辩论/4 层记忆保持不变)——继承自 2026-06-24-004 plan。
  • 节点级 checkpoint(ReAct 循环单步)——继承自 2026-06-24-004 KTD3,阶段级已满足核心需求。
  • DeerFlow 式磁盘文件系统——继承自 2026-06-24-004 KTD4,复用 Redis。
  • 全盘迁移 LangGraph——继承自 2026-06-24-004,自研架构保持灵活。
  • Docker 沙箱默认引入——仅文档化命令级安全边界,作为可选插件未来考虑。

Dependencies / Assumptions

  • 依赖:Wave 2 的 G9 rollback 依赖现有 U7 checkpoint 已落地(orchestrator/checkpoint.py + experts/orchestrator.py:265-268,335)。
  • 依赖:Wave 1 的 G2 prompt cache 断点依赖 Anthropic provider 已支持 cache_control(LiteLLM 适配层 U15)。
  • 假设:G4 auxiliary model 可用——agentkit.yaml 的 llm 段可配置多个 model,auxiliary 复用现有 provider 注册机制。若实际不可用,回退主 model(R15)。
  • 假设:G6 阶段约束不影响现有 DIRECT_CHAT/REACT 模式——仅作用于 PLAN_EXEC 模式,向后兼容。

Sources & Research

  • Qoder 架构研究(2026-06-29):Spec→Coding→Verify 闭环、SSE 事件成对约束、delta_flush_interval_ms、prompt cache、自动模型路由
  • Codex CLI 架构研究(2026-06-29):apply_patch 协议、Approval Policy 三层决策、OS 级沙箱、prompt caching 前缀匹配、/responses/compact 压缩
  • Hermes Agent 架构研究(2026-06-29):Pydantic+JSON Schema 双校验、validate_function_call_schema、三级降级链(主→Recovery→Emergency)、cache_control: system_and_3 断点(4 个,~75% token 节省)、auxiliary_client 分流
  • Trae Work 架构研究(2026-06-29):SOLO 四阶段状态机(Planning→Building→Verification→Delivery)、TrajectoryRecorder JSON 持久化、断点续跑、原子化子任务+rollback、函数级分片(ANTLR4+LLVM)
  • agentkit 现有架构(2026-06-29 验证器核对):verification_loop.py:111-145、react.py:1042-1059,1118-1134,1897-1916、compressor.py:45,123-154、reflexion.py:58-702、fallback.py:1-19、gateway.py:405-407、experts/plan.py:148、orchestrator/checkpoint.py、experts/orchestrator.py:265-268,335
  • 2026-06-24-004 plan(增补来源):U1-U7 长程可靠性护栏,KTD1-KTD5 决策,U7 阶段级 checkpoint+resume 已落地

Outstanding Questions

Resolve Before Planning

(已全部解决——OQ1 确认同 plan 内顺序执行 G2→G8;OQ2 确认跨 provider 统一 cache 策略。)

Deferred to Planning

  • G5 的具体集成方式(tree-sitter vs ANTLR4 vs 复用 quality 模块)。
  • G7 Emergency 层的具体规则模板与错误结构。
  • G6 阶段约束的精确边界(Planning 阶段允许哪些工具、Building 阶段允许哪些)。
  • G9 rollback_command 的默认值(git checkout 整文件 vs patch 级)。