fischer
/
fischer-agentkit
1
0
Fork 0
Code Issues Pull Requests Actions 87 Packages Projects Releases Wiki Activity
fischer-agentkit/docs/plans/2026-06-10-019-feat-agentki...

8.4 KiB
Raw Blame History

title status created plan_type
feat: AgentKit 劣势项改进 active 2026-06-10 feat

feat: AgentKit 劣势项改进

Summary

针对代码审查后识别的 6 个延后劣势项进行改进：Soul演变多维度触发、中文分词增强、端到端可观测性、测试覆盖补充、ReWOO渐进回退、Agent间通信协议。

Problem Frame

当前 AgentKit 的多Agent架构已基本成型，但存在 6 个影响生产就绪度的劣势项。这些项不阻塞核心功能，但会随使用规模扩大而暴露问题。

Scope Boundaries

In Scope

  • Soul演变多维度触发（时间衰减+质量梯度+场景权重）
  • 中文分词增强（2-gram+停用词，零依赖）
  • 端到端可观测性（OpenTelemetry埋点）
  • 集成测试补充（多模块交互测试）
  • ReWOO渐进回退链
  • Agent间通信协议（消息总线）

Out of Scope

  • jieba分词集成（可选依赖，后续按需）
  • 分布式消息总线（Redis实现，后续按需）
  • Live测试（需要真实API Key，CI中标记跳过）
  • UI可视化trace（Jaeger/Zipkin前端，运维配置）

Key Technical Decisions

KTD1: 中文分词采用2-gram+停用词方案（零依赖）

jieba虽精准但是额外依赖，2-gram方案对"数据分析""代码生成"等复合词已有足够捕获率。后续可按需引入jieba作为可选依赖。

KTD2: 可观测性基于OpenTelemetry标准

各引擎已有 trace_recorder 参数，只需实现 OTel 导出器。配置通过 telemetry.otlp_endpoint 启用。

KTD3: Agent间通信采用请求-响应+广播+协商三模式

基于 AgentMessage 数据类和 MessageBus 接口。先实现 InMemoryMessageBus，后续扩展 RedisMessageBus。

KTD4: ReWOO回退链为 ReWOO简化→PlanExec→ReAct→Direct

渐进式降级，每一步保留更多结构化能力。

Implementation Units

U1. Soul演变多维度触发

Goal: 扩展Soul演变触发条件，支持时间衰减、质量梯度、场景权重

Dependencies: None

Files:

  • Modify: src/agentkit/evolution/lifecycle.py
  • Modify: src/agentkit/evolution/config.py (新增 SoulEvolutionConfig)
  • Test: tests/unit/test_soul_evolution.py

Approach:

  1. 新增 SoulEvolutionConfig dataclass，包含 reflection_window_seconds、time_decay_factor、task_type_weights、quality_gradient_threshold
  2. 修改 evolve_soul 方法：时间衰减计算 effective_count = sum(factor^age_hours) 替代 len(reflections)
  3. 新增质量梯度检测：追踪最近N次评分趋势，连续下降超过阈值时提前触发
  4. 场景权重：高风险任务降低触发阈值

Test scenarios:

  • 时间衰减：1小时内的3次反思触发，超过窗口的不计入
  • 质量梯度：连续3次评分下降0.15触发，即使总反思次数<3
  • 场景权重：code_generation任务2次即触发（权重1.5），chat任务需4次（权重0.5）
  • 兼容性：无config时行为与现有一致

Verification: 新增测试全部通过，现有Soul演变测试不受影响

U2. 中文分词增强

Goal: 替换空格分词为2-gram+停用词方案，提升中文能力关键词提取

Dependencies: None

Files:

  • Modify: src/agentkit/chat/skill_routing.py
  • Test: tests/unit/test_cost_aware_router.py

Approach:

  1. 提取 _tokenize_content() 为独立方法
  2. 标点分割 → 对长中文段补充2-gram → 停用词过滤
  3. Layer 2 路由调用新方法

Test scenarios:

  • 中文："帮我做数据分析" → 提取 ["数据分析", "帮我"]
  • 英文："help with code generation" → 提取 ["code generation", "help"]
  • 混合："用python做data analysis" → 提取 ["python", "data analysis"]
  • 停用词过滤："的了一个" → 过滤后为空

Verification: 中文分词测试通过，现有路由测试不受影响

U3. 端到端可观测性（OpenTelemetry埋点）

Goal: 为核心组件添加OTel trace/metrics埋点

Dependencies: None

Files:

  • Create: src/agentkit/telemetry/__init__.py
  • Create: src/agentkit/telemetry/tracer.py (OTel导出器)
  • Modify: src/agentkit/chat/skill_routing.py (路由埋点)
  • Modify: src/agentkit/core/react.py (ReAct埋点)
  • Modify: src/agentkit/core/rewoo.py (ReWOO埋点)
  • Modify: src/agentkit/core/reflexion.py (Reflexion埋点)
  • Modify: src/agentkit/quality/alignment.py (Guard埋点)
  • Test: tests/unit/test_telemetry.py

Approach:

  1. 定义 TelemetryConfig 和 get_tracer() 工厂
  2. 实现 OTelTraceRecorder 适配器，桥接现有 TraceRecorder 接口
  3. 各组件在关键节点创建 Span：路由决策、引擎执行、约束检查
  4. 配置通过 telemetry.otlp_endpoint 启用，未配置时为 no-op

Test scenarios:

  • 未配置时：所有埋点为 no-op，不影响功能
  • 配置endpoint时：Span正确创建，属性包含 layer/complexity/status 等
  • 路由埋点：Layer 0/1/2 各产生带属性的 Span
  • 引擎埋点：执行完成后 Span 记录 steps_count/total_tokens/status

Verification: 新增测试通过，无OTel依赖时功能正常

U4. 集成测试补充

Goal: 补充多模块交互集成测试，覆盖核心链路

Dependencies: U1, U2

Files:

  • Create: tests/integration/test_router_engine_chain.py
  • Create: tests/integration/test_rewoo_fallback.py
  • Create: tests/integration/test_reflexion_loop.py
  • Create: tests/integration/test_soul_evolution_trigger.py

Approach:

  1. 路由→执行→审计全链路测试（仅mock LLM）
  2. ReWOO规划失败→回退测试
  3. Reflexion多轮循环测试
  4. Soul演变触发条件测试

Test scenarios:

  • 全链路：CostAwareRouter路由到ReActEngine → AlignmentGuard检查通过
  • 全链路违规：AlignmentGuard检查失败，返回violations
  • ReWOO回退：规划异常时正确回退到ReAct
  • Reflexion：3轮循环后返回最佳结果
  • Soul触发：3次低质量反思后触发update_soul

Verification: 集成测试全部通过

U5. ReWOO渐进回退链

Goal: ReWOO规划失败时渐进降级，而非直接回退ReAct

Dependencies: None

Files:

  • Modify: src/agentkit/core/rewoo.py
  • Test: tests/unit/test_rewoo_engine.py

Approach:

  1. 新增 FALLBACK_CHAIN 配置：simplified_rewoo → plan_exec → react → direct
  2. 规划失败时先尝试简化规划（max_plan_steps=3）
  3. 简化仍失败则按链降级
  4. 回退信息记录在 ReWOOResult 中

Test scenarios:

  • 正常规划成功：无回退
  • 规划失败→简化规划成功：结果标记 fallback=simplified
  • 规划失败→简化失败→ReAct回退：结果标记 fallback=react
  • 所有回退都失败：返回错误结果

Verification: 回退链测试通过

U6. Agent间通信协议

Goal: 实现轻量级消息总线，支持Agent间请求-响应、广播、协商

Dependencies: None

Files:

  • Create: src/agentkit/bus/__init__.py
  • Create: src/agentkit/bus/message.py (AgentMessage数据类)
  • Create: src/agentkit/bus/interface.py (MessageBus接口)
  • Create: src/agentkit/bus/memory_bus.py (InMemoryMessageBus实现)
  • Modify: src/agentkit/server/app.py (初始化MessageBus)
  • Test: tests/unit/test_agent_bus.py

Approach:

  1. 定义 AgentMessage dataclass：sender, recipient, msg_type, content, correlation_id, timestamp, ttl
  2. 定义 MessageBus 抽象接口：publish, subscribe, request
  3. 实现 InMemoryMessageBus：基于 asyncio.Queue
  4. 与 AlignmentGuard 集成：消息经过约束检查
  5. 与 CascadeDetector 集成：消息传递计入级联检测

Test scenarios:

  • 请求-响应：Agent A发送请求，Agent B响应，correlation_id匹配
  • 广播：Agent A广播，所有订阅者收到
  • 协商：Agent A发起协商，Agent B回复建议
  • TTL过期：超时消息被丢弃
  • 级联检测：超过阈值的消息链触发 CascadeAlert

Verification: 消息总线测试通过，与Guard/Cascade集成正确

Risks & Mitigations

Risk Impact Mitigation
OTel依赖增加包体积 Low OTel为可选依赖，未配置时no-op
消息总线内存泄漏 Medium TTL过期清理 + 定期GC
ReWOO回退链增加延迟 Low 每步设置timeout，总回退时间上限5s
2-gram分词噪声 Low 停用词过滤 + 长度阈值

Deferred to Follow-Up Work

  • jieba分词集成（可选依赖）
  • RedisMessageBus分布式实现
  • Live测试（需真实API Key）
  • Jaeger/Zipkin前端配置
  • 消息总线持久化