21 KiB

Raw Blame History

title	status	created	plan_type	depth	origin	branch
feat: AgentKit Phase 5 — 智能进化与多Agent协作	completed	2026-06-06	feat	deep	Phase 4 完成后成熟度评估 + L4/L5 级能力建设需求	feat/agentkit-phase5-intelligence

AgentKit Phase 5 — 智能进化与多Agent协作

Summary

基于 Phase 4 企业级生产化升级（整体 L3 级），Phase 5 聚焦三大核心能力跃迁：RAG 自纠正闭环（L3→L4）、多 Agent 协作编排（L3→L4）、GEPA 遗传算法进化（L3→L5）。同时完成国内 Provider 接入和 Contextual Retrieval 优化，以"GEO 系统 RAG 质量可度量、多 Skill 自动编排、Prompt 自主进化"为验收底线。

Problem Frame

Phase 4 完成后，AgentKit 达到 L3 级别（生产可用），但存在三个关键能力缺口：

三大能力缺口

RAG 不可自纠（L3 级）
- 检索结果无质量评估，错误检索直接传递给 LLM 生成
- 缺少"检索→评估→改写→重检索"闭环
- EpisodicMemory ORM 集成未完成（session_factory=None）
- 无 Contextual Retrieval，分块后上下文丢失
多 Agent 无法协作（L3 级）
- HandoffManager 仅支持单向转交，无双向协作通信
- 缺少中央编排器协调多 Agent 并行/串行执行
- 无共享工作空间，Agent 间只能通过 Handoff 传递 context
- GEO 8 个 Skill 缺少端到端 Pipeline 编排
进化系统非遗传（L3 级）
- 当前进化是单个体逐任务优化，无种群/代际概念
- 缺少交叉算子（Crossover），无法发现跨模块组合
- StrategyTuner 仅支持 2 个参数，无多维策略空间
- 缺少多目标适应度（准确率+延迟+成本）

成熟度目标

模块	Phase 4 后	Phase 5 目标
进化系统	75%	90%
记忆/RAG	85%	95%
核心引擎	90%	95%
LLM Gateway	85%	95%
Server	90%	92%
整体	L3	L4

Scope Boundaries

In Scope:

RAG 自纠正循环（CRAG 模式）
Contextual Retrieval（上下文增强分块）
多 Agent Orchestrator-Worker 编排
共享工作空间
GEPA 遗传算法进化框架
国内 Provider（文心/豆包/元宝）
Ragas 评估管线
GEO Pipeline 编排

Out of Scope:

前端 UI 开发（GEO Dashboard 属于独立项目）
分布式追踪（OpenTelemetry，Phase 6）
本地向量库（ChromaDB/FAISS，Phase 6）
多跳推理检索（Phase 6）
Agent 能力发现和动态路由（Phase 6）

Implementation Units

Phase A (P0) — RAG 质量闭环

U1: RAG 自纠正循环（CRAG）

Goal: 实现 Corrective RAG 模式，检索结果经评估后决定通过/改写/降级，形成自纠正闭环。

Files:

Create: src/agentkit/memory/rag_loop.py
Create: src/agentkit/memory/relevance_scorer.py
Modify: src/agentkit/memory/retriever.py
Create: tests/unit/test_rag_loop.py
Create: tests/unit/test_relevance_scorer.py

Approach:

实现 RelevanceScorer：轻量级评估器，对检索结果逐文档评分（0-1），基于查询-文档语义相似度 + 关键词重叠
实现 RAGSelfCorrectionLoop：状态机驱动的检索-评估-纠正循环
- 状态：RETRIEVE → EVALUATE → CORRECT/DEGRADE → GENERATE
- 评估：RelevanceScorer 评分，阈值判断（correct/ambiguous/incorrect）
- 纠正：QueryTransformer 改写查询，重新检索（最多 max_retries 次）
- 降级：超过重试次数，返回降级结果（标记 low_confidence）
集成到 MemoryRetriever：当 enable_self_correction=True 时，检索走 CRAG 循环
熔断器：max_retries=3，防止无限循环

Patterns to follow:

src/agentkit/memory/query_transformer.py — 策略模式（LLM/Rule/NoOp）
src/agentkit/llm/retry.py — CircuitBreaker 熔断模式
src/agentkit/core/react.py — 状态机驱动的循环

Verification:

单元测试：RelevanceScorer 评分准确性、RAGSelfCorrectionLoop 状态转换、熔断器触发
集成测试：低质量检索触发自纠正、高质量检索直接通过、超限降级

U2: Contextual Retrieval（上下文增强分块）

Goal: 在嵌入前为每个文档块添加 LLM 生成的上下文前缀，解决分块后上下文丢失问题。

Files:

Create: src/agentkit/memory/contextual_retrieval.py
Modify: src/agentkit/memory/http_rag.py
Create: tests/unit/test_contextual_retrieval.py

Approach:

实现 ContextualChunker：
- 输入：原始文档 + 分块列表
- 处理：对每个块，调用 LLM（优先用轻量模型）生成简洁上下文语句
- 输出：增强后的块（上下文前缀 + 原始内容）
- Prompt 模板："给定完整文档和文档中的一个特定块，请编写简短的上下文，帮助理解这个块在整体中的位置。仅输出上下文，不要解释。"
集成到 HttpRAGService：
- ingest() 方法可选启用 contextual_chunking
- 使用 EmbeddingCache 缓存上下文生成结果
成本优化：
- 文档级 Prompt Caching（同一文档的多个块共享文档前缀）
- 批处理（batch_size=8）

Patterns to follow:

src/agentkit/memory/embedder.py — EmbeddingCache 缓存模式
src/agentkit/memory/query_transformer.py — LLM 调用 + 模板模式

Verification:

单元测试：上下文生成正确性、缓存命中/失效、批处理逻辑
对比测试：有/无 Contextual Retrieval 的检索质量差异

U3: EpisodicMemory ORM 集成完成

Goal: 完成 EpisodicMemory 与 PostgreSQL 的完整 ORM 集成，替换当前的 session_factory=None 状态。

Files:

Modify: src/agentkit/memory/episodic.py
Modify: src/agentkit/server/app.py
Create: src/agentkit/memory/models.py
Modify: tests/unit/test_episodic_memory.py
Modify: tests/unit/test_episodic_vector_search.py

Approach:

定义 EpisodeModel ORM 模型（SQLAlchemy）：
- 字段：id, agent_id, task_type, content, embedding(vector), quality_score, created_at, metadata(JSON)
- pgvector 索引：ivfflat 或 hnsw
修改 EpisodicMemory：
- 注入 session_factory 和 EpisodeModel
- store() → INSERT INTO episodes
- retrieve() → pgvector 原生搜索（cosine distance）
- 移除客户端 O(N) 全量扫描降级路径
修改 Server 初始化：
- app.py 中创建真实的 session_factory 和 EpisodeModel
- 数据库表自动创建（alembic 迁移）

Patterns to follow:

src/agentkit/evolution/models.py — ORM 模型定义
src/agentkit/evolution/evolution_store.py — SQLAlchemy session 使用模式
src/agentkit/server/app.py — 服务初始化

Verification:

单元测试：ORM CRUD、pgvector 搜索、时间衰减评分
集成测试：Server 启动后 EpisodicMemory 可用

Phase B (P1) — 多 Agent 协作

U4: 多 Agent Orchestrator

Goal: 实现中央编排器，支持 Orchestrator-Worker 模式的多 Agent 协作。

Files:

Create: src/agentkit/core/orchestrator.py
Create: src/agentkit/core/shared_workspace.py
Modify: src/agentkit/core/protocol.py
Create: tests/unit/test_orchestrator.py
Create: tests/unit/test_shared_workspace.py

Approach:

定义 AgentRole 枚举：ORCHESTRATOR, WORKER, REVIEWER
实现 SharedWorkspace：
- 基于 Redis 的共享状态存储
- 操作：write(key, value, agent_id), read(key), subscribe(key), lock(key)
- 支持版本控制和冲突检测
实现 Orchestrator：
- 任务分解：LLM 驱动将复杂任务拆解为子任务
- Agent 分配：基于 Skill 能力匹配子任务到 Worker Agent
- 执行监控：跟踪子任务状态，处理超时/失败
- 结果聚合：汇总 Worker 结果，生成最终输出
扩展 Protocol：
- 新增 CollaborationMessage：agent_id, target_agent_id, message_type(request/response/broadcast), payload
- 新增 SubTask：task_id, parent_task_id, assigned_agent, status, result

Patterns to follow:

src/agentkit/core/base.py — BaseAgent 生命周期模式
src/agentkit/core/agent_pool.py — Agent 实例池管理
src/agentkit/core/dispatcher.py — Redis Queue 任务分发
src/agentkit/skills/pipeline.py — Pipeline 编排模式

Verification:

单元测试：任务分解、Agent 分配、结果聚合、超时处理
集成测试：2-3 个 Agent 协作完成复杂任务

U5: GEO Pipeline 编排

Goal: 实现 GEO 端到端工作流编排（检测→分析→优化→追踪），作为多 Agent 协作的实际应用。

Files:

Create: src/agentkit/skills/geo_pipeline.py
Create: configs/pipelines/geo_full_pipeline.yaml
Modify: src/agentkit/server/routes/tasks.py
Create: tests/unit/test_geo_pipeline.py

Approach:

定义 GEO Pipeline YAML 配置：

name: geo_full_pipeline
steps:
  - name: detect
    skill: citation_detector
    input_mapping: {brand: $.input.brand, platforms: $.input.platforms}
  - name: analyze_competitor
    skill: competitor_analyzer
    input_mapping: {brand: $.input.brand, detection_result: $.steps.detect.output}
    depends_on: [detect]
  - name: analyze_trend
    skill: trend_agent
    input_mapping: {brand: $.input.brand}
    depends_on: [detect]
    parallel_with: [analyze_competitor]
  - name: optimize
    skill: geo_optimizer
    input_mapping: {brand: $.input.brand, analysis: $.steps.analyze_competitor.output}
    depends_on: [analyze_competitor, analyze_trend]
  - name: schema
    skill: schema_advisor
    input_mapping: {brand: $.input.brand, optimization: $.steps.optimize.output}
    depends_on: [optimize]
  - name: monitor
    skill: monitor
    input_mapping: {brand: $.input.brand}
    depends_on: [optimize]

实现 GEOPipeline：
- 加载 YAML 配置，构建 DAG
- 拓扑排序确定执行顺序
- 并行执行无依赖的步骤
- 步骤间数据通过 SharedWorkspace 传递
集成到 Server：
- POST /api/v1/pipelines/execute 端点
- 支持 WebSocket 推送 Pipeline 进度

Patterns to follow:

src/agentkit/skills/pipeline.py — SkillPipeline 编排
src/agentkit/core/config_driven.py — 配置驱动模式
configs/skills/*.yaml — YAML 配置格式

Verification:

单元测试：DAG 构建、拓扑排序、并行执行、步骤间数据传递
集成测试：完整 GEO Pipeline 端到端执行

Phase C (P1) — GEPA 遗传算法进化

U6: GEPA 种群与遗传算子

Goal: 实现 GEPA（Genetic-Pareto Prompt Evolution）核心框架，包括种群管理、交叉/变异算子、Pareto 选择。

Files:

Create: src/agentkit/evolution/genetic.py
Modify: src/agentkit/evolution/lifecycle.py
Create: tests/unit/test_genetic_evolution.py

Approach:

定义核心数据结构：
- PromptChromosome：一个完整的 Prompt 变体（identity + instructions + demos + constraints）
- GEPAPopulation：种群管理（初始化、添加、淘汰、获取精英）
- FitnessScore：多目标适应度（accuracy, latency, cost）
实现遗传算子：
- CrossoverOperator：从两个父代 Prompt 生成子代
  - 指令段交叉：交换 instructions 的子段落
  - Demo 交叉：交换 few-shot 示例
  - 约束交叉：交换约束条件
- MutationOperator：基于 LLM 反思的结构化变异
  - 指令变异：LLM 重写指令段落
  - Demo 变异：替换/重排 few-shot 示例
  - 约束变异：增删约束条件
- SelectionStrategy：
  - 锦标赛选择（Tournament Selection）
  - 精英保留（Elitism）：保留 top-k 最优个体
Pareto 前沿维护：
- 多目标非支配排序
- 拥挤度距离计算
- 保留 Pareto 前沿上的最优解
集成到 EvolutionMixin：
- 当 evolution_mode=gepa 时，使用遗传进化替代逐任务优化
- 代际进化：每 N 个任务触发一代进化

Patterns to follow:

src/agentkit/evolution/prompt_optimizer.py — Prompt 优化模式
src/agentkit/evolution/ab_tester.py — A/B 测试和统计检验
src/agentkit/evolution/llm_reflector.py — LLM 驱动反思

Verification:

单元测试：CrossoverOperator 交叉正确性、MutationOperator 变异合理性、Pareto 前沿维护、锦标赛选择
集成测试：3-5 代进化后 Prompt 质量提升

U7: 多目标适应度与策略空间扩展

Goal: 实现多目标适应度评估和扩展的策略空间，使进化系统能优化准确率+延迟+成本的综合表现。

Files:

Create: src/agentkit/evolution/fitness.py
Modify: src/agentkit/evolution/strategy_tuner.py
Create: tests/unit/test_fitness.py

Approach:

实现 MultiObjectiveFitness：
- 维度：accuracy（0-1）、latency（ms，越低越好）、cost（token 数，越低越好）
- 归一化：各维度归一化到 [0, 1]
- 加权组合：可配置权重（默认 accuracy=0.6, latency=0.2, cost=0.2）
- Pareto 支配判断：a 支配 b ⟺ a 在所有维度 ≥ b 且至少一个维度 > b
扩展 StrategyTuner：
- 参数空间扩展：temperature, max_iterations, tool_weights, top_k, retrieval_mode
- Bayesian 优化升级：从 1D 升级到多维 Bayesian Optimization（使用高斯过程）
- 约束支持：参数范围约束（如 temperature ∈ [0, 2]）
适应度数据收集：
- 从 TraceRecorder 提取任务执行指标
- 从 UsageTracker 提取 token 使用量
- 从 QualityGate 提取质量评分

Patterns to follow:

src/agentkit/evolution/strategy_tuner.py — 当前 1D 优化模式
src/agentkit/core/trace.py — 执行轨迹记录
src/agentkit/llm/providers/tracker.py — Usage 追踪

Verification:

单元测试：多目标归一化、Pareto 支配判断、Bayesian 优化收敛性
集成测试：多目标进化后综合表现提升

Phase D (P2) — 生态扩展

U8: 国内 Provider 实现（文心/豆包/元宝）

Goal: 实现文心、豆包、元宝三个国内 LLM Provider，扩展 AgentKit 的 AI 引擎覆盖。

Files:

Create: src/agentkit/llm/providers/wenxin.py
Create: src/agentkit/llm/providers/doubao.py
Create: src/agentkit/llm/providers/yuanbao.py
Modify: src/agentkit/llm/providers/__init__.py
Modify: src/agentkit/llm/config.py
Create: tests/unit/test_wenxin_provider.py
Create: tests/unit/test_doubao_provider.py
Create: tests/unit/test_yuanbao_provider.py

Approach:

WenxinProvider（百度文心）：
- 鉴权：AK/SK → access_token（缓存 29 天）
- API：https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/{model}
- 模型映射：ernie-4.5-turbo-128k, ernie-5.0, ernie-x1.1
- 特有功能：web_search 联网搜索
- 流式：SSE
DoubaoProvider（字节豆包）：
- 鉴权：火山引擎 IAM（Bearer token）
- API：https://ark.cn-beijing.volces.com/api/v3/chat/completions
- 模型映射：doubao-pro-32k, doubao-lite
- 特有功能：Function Calling
- 流式：SSE
YuanbaoProvider（腾讯混元）：
- 鉴权：Bearer API Key
- API：https://api.hunyuan.cloud.tencent.com/v1/chat/completions（OpenAI 兼容）
- 模型映射：hunyuan-turbos-latest, hunyuan-2.0
- 特有功能：enable_enhancement 增强模式
- 流式：SSE
统一注册到 LLMGateway：
- 配置格式：wenxin/ernie-4.5-turbo-128k, doubao/doubao-pro-32k, yuanbao/hunyuan-turbos-latest
- 环境变量：WENXIN_AK/SK, DOUBAO_API_KEY, YUANBAO_API_KEY

Patterns to follow:

src/agentkit/llm/providers/openai.py — OpenAICompatibleProvider 模式
src/agentkit/llm/providers/anthropic.py — 原生 API Provider 模式
src/agentkit/llm/providers/gemini.py — 原生 API Provider 模式

Verification:

单元测试：鉴权流程、请求格式、响应解析、流式处理、错误处理
集成测试：通过 Gateway 调用各 Provider（mock 模式）

U9: Ragas 评估管线

Goal: 集成 Ragas 评估框架，为 RAG 质量提供可度量的指标体系。

Files:

Create: src/agentkit/evaluation/__init__.py
Create: src/agentkit/evaluation/ragas_evaluator.py
Create: src/agentkit/evaluation/dataset_builder.py
Create: tests/unit/test_ragas_evaluator.py

Approach:

实现 RagasEvaluator：
- 指标：Faithfulness, AnswerRelevancy, ContextPrecision, ContextRecall
- LLM Judge：使用配置的 LLM 作为 Judge
- 评估流程：构建评估数据集 → 调用 Ragas evaluate → 返回指标 DataFrame
实现 EvalDatasetBuilder：
- 从 TraceRecorder 提取历史任务数据
- 转换为 Ragas 格式：user_input, response, retrieved_contexts, reference
- 支持人工标注 reference 的导入
Server 集成：
- POST /api/v1/evaluation/run：触发评估
- GET /api/v1/evaluation/results：获取评估结果
评估触发策略：
- 手动触发：API 调用
- 定时触发：配置 cron 表达式
- 进化触发：每 N 代进化后自动评估

Patterns to follow:

src/agentkit/core/trace.py — 执行轨迹数据
src/agentkit/memory/retriever.py — 检索结果数据
src/agentkit/server/routes/evolution.py — API 路由模式

Verification:

单元测试：数据集构建、评估流程、指标计算
集成测试：端到端评估（使用 mock LLM Judge）

U10: Agent 状态锁优化与配置热加载完善

Goal: 完善 Phase 4 U12 的 Agent 状态锁和配置热加载，修复已知问题。

Files:

Modify: src/agentkit/core/base.py
Modify: src/agentkit/server/app.py
Modify: src/agentkit/server/config.py
Modify: tests/unit/test_base_agent.py

Approach:

状态锁优化：
- 当前 asyncio.Lock 在高并发下可能死锁，改用 asyncio.Event + 超时
- 增加锁状态查询 API（GET /api/v1/agents/{id}/lock-status）
配置热加载完善：
- 修复 _on_config_change 中 skill 配置变更不生效的问题
- 增加配置变更审计日志
- 增加配置回滚机制（保留最近 N 个配置版本）
优雅滚动更新：
- 等待当前任务完成后再应用配置变更
- 新任务使用新配置，进行中的任务继续使用旧配置

Patterns to follow:

src/agentkit/core/base.py — Agent 状态管理
src/agentkit/server/config.py — 配置加载

Verification:

单元测试：锁超时、配置变更生效、配置回滚
集成测试：运行中任务不受配置变更影响

Dependencies

U1 (CRAG) ─────────────────────────────────────┐
U2 (Contextual Retrieval) ──────────────────────┤
U3 (EpisodicMemory ORM) ───────────────────────┤
                                                ├──→ U9 (Ragas 评估)
U4 (Orchestrator) ──→ U5 (GEO Pipeline) ───────┤
                                                │
U6 (GEPA 种群) ──→ U7 (多目标适应度) ───────────┤
                                                │
U8 (国内 Provider) ────────────────────────────┤
                                                │
U10 (状态锁优化) ──────────────────────────────┘

U1, U2, U3 互相独立，可并行
U4 是 U5 的前置依赖
U6 是 U7 的前置依赖
U9 依赖 U1（需要 CRAG 的检索结果做评估）
U8, U10 独立，可随时执行

Test Strategy

新增测试文件

Unit	测试文件	预估用例数
U1	test_rag_loop.py, test_relevance_scorer.py	25
U2	test_contextual_retrieval.py	15
U3	test_episodic_memory.py (更新), test_episodic_vector_search.py (更新)	10
U4	test_orchestrator.py, test_shared_workspace.py	25
U5	test_geo_pipeline.py	15
U6	test_genetic_evolution.py	20
U7	test_fitness.py	15
U8	test_wenxin_provider.py, test_doubao_provider.py, test_yuanbao_provider.py	30
U9	test_ragas_evaluator.py	15
U10	test_base_agent.py (更新)	10

验收标准

所有测试通过（0 failed）
总测试数 ≥ 1500（当前 1353 + 新增 ~180）
新增代码测试覆盖率 ≥ 85%

Risk Assessment

风险	概率	影响	缓解措施
GEPA 进化效果不显著	中	中	保留 Phase 4 的逐任务优化作为 fallback
多 Agent 编排死锁	中	高	超时机制 + 死锁检测 + 优雅降级
国内 Provider API 变更	低	低	抽象层隔离 + 配置化端点
Ragas 评估成本过高	中	低	使用轻量模型做 Judge + 采样评估
Contextual Retrieval 延迟	低	中	Prompt Caching + 批处理 + 异步预处理

21 KiB Raw Blame History Unescape Escape

AgentKit Phase 5 — 智能进化与多Agent协作

Summary

Problem Frame

三大能力缺口

成熟度目标

Scope Boundaries

Implementation Units

Phase A (P0) — RAG 质量闭环

U1: RAG 自纠正循环（CRAG）

U2: Contextual Retrieval（上下文增强分块）

U3: EpisodicMemory ORM 集成完成

Phase B (P1) — 多 Agent 协作

U4: 多 Agent Orchestrator

U5: GEO Pipeline 编排

Phase C (P1) — GEPA 遗传算法进化

U6: GEPA 种群与遗传算子

U7: 多目标适应度与策略空间扩展

Phase D (P2) — 生态扩展

U8: 国内 Provider 实现（文心/豆包/元宝）

U9: Ragas 评估管线

U10: Agent 状态锁优化与配置热加载完善

Dependencies

Test Strategy

新增测试文件

验收标准

Risk Assessment

21 KiB

Raw Blame History