245 lines
8.4 KiB
Markdown
245 lines
8.4 KiB
Markdown
---
|
||
title: "feat: AgentKit 劣势项改进"
|
||
status: active
|
||
created: 2026-06-10
|
||
plan_type: 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前端配置
|
||
- 消息总线持久化
|