---
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前端配置
- 消息总线持久化