# AgentKit 能力回测报告

> **生成时间**: 2026-06-17
> **版本**: 0.1.0
> **总体评分**: 98.04%
> **测试用例**: 51 个（50 通过 / 1 失败）
> **测试维度**: 7 个

---

## 一、与行业 Benchmark 的差异分析

### 1.1 行业 Benchmark 概览

| Benchmark | 测试对象 | 评估维度 | 数据集规模 | 评分方式 |
|-----------|----------|----------|------------|----------|
| **SWE-bench** | LLM 代码修复能力 | 端到端任务完成率 | 2,294 个 GitHub Issue | pass@1（测试通过率） |
| **HumanEval** | LLM 代码生成 | 函数级正确性 | 164 个编程题 | pass@1 |
| **MMLU** | LLM 多任务理解 | 多领域知识准确率 | 15,908 道题 | 4 选 1 准确率 |
| **GAIA** | 通用 AI 助手 | 端到端任务完成率 | 466 个真实任务 | 精确匹配 |
| **AgentBench** | Agent 系统 | 多场景任务完成率 | 8 个场景 | 加权完成率 |
| **ToolBench** | 工具调用能力 | 工具选择 + 调用正确性 | 16,000+ API | pass@1 |
| **WebArena** | Web 交互 Agent | 网页操作完成率 | 812 个任务 | 端到端成功率 |

### 1.2 本 Benchmark 的定位差异

| 对比维度 | 行业 Benchmark | AgentKit Benchmark |
|----------|---------------|-------------------|
| **测试目标** | LLM 模型能力（推理、代码生成） | Agent 框架架构能力（路由、工具搜索、事件模型） |
| **测试层级** | 端到端（用户输入 → 最终输出） | 组件级 + 集成级（不依赖 LLM 质量） |
| **LLM 依赖** | 必须使用真实 LLM（成本高） | 使用 Mock（零成本、可重复） |
| **评估焦点** | LLM 推理质量 | 框架架构正确性 |
| **数据集** | 标准化、公开、可对比 | 自定义、针对架构特性 |
| **可复现性** | 受 LLM 随机性影响 | 100% 确定性（无 LLM 调用） |
| **适用场景** | 模型选型、能力对比 | 架构演进验证、回归测试 |

### 1.3 核心差异说明

**行业 Benchmark 测的是"大脑有多聪明"**：
- SWE-bench 测 LLM 能否修复真实 GitHub Bug
- HumanEval 测 LLM 能否写出正确的函数
- 这些 Benchmark 的分数直接反映 LLM 的推理能力

**AgentKit Benchmark 测的是"身体有多健康"**：
- 预处理准确度：RequestPreprocessor 是否正确分类输入（不依赖 LLM）
- 工具搜索：BM25 索引是否返回正确工具（不依赖 LLM）
- 事件模型：SQ/EQ 队列是否正确传递事件（不依赖 LLM）
- 这些测试的分数反映框架架构的正确性

**互补关系**：行业 Benchmark 评估"换一个更聪明的 LLM 能否提升效果"，AgentKit Benchmark 评估"框架架构是否正确支撑 LLM 发挥能力"。两者缺一不可。

### 1.4 未来演进方向

当前 Benchmark 的不足和计划改进：

| 不足 | 计划改进 | 优先级 |
|------|----------|--------|
| 无真实 LLM 端到端测试 | 增加 LLM-backed 维度（使用 Mock LLM 模拟 ReAct 循环） | P1 |
| 无 SWE-bench 风格任务 | 增加"复杂任务执行"维度（多步骤、工具链） | P2 |
| 无对比基线 | 建立历史基线，支持趋势对比 | P2 |
| 无前端集成测试 | 增加 WebSocket 事件流验证 | P3 |
| 无性能压力测试 | 增加并发场景下的 EQ 吞吐量测试 | P3 |

---

## 二、测试维度详细结果

### 2.1 预处理准确度 (Preprocessing Accuracy)

**维度说明**: 测试 RequestPreprocessor 是否正确将用户输入分类到对应的执行模式。这是消除路由层后的核心组件，决定了用户输入是否走 DIRECT_CHAT（直接对话）、REACT（工具推理）还是 SKILL_REACT（技能执行）路径。

**评分**: 93.3%（14/15 通过）

| 用例 ID | 输入 | 期望模式 | 实际模式 | 耗时 | 结果 |
|---------|------|----------|----------|------|------|
| greeting_cn | 你好 | direct_chat | direct_chat | 0.03ms | 通过 |
| greeting_en | hello | direct_chat | direct_chat | 0.01ms | 通过 |
| chitchat_thanks | 谢谢 | direct_chat | direct_chat | 0.01ms | 通过 |
| identity_who | 你是谁 | direct_chat | direct_chat | 0.01ms | 通过 |
| colloquial_ip_1 | 查下ip | react | react | 0.01ms | 通过 |
| colloquial_ip_2 | 查看当前ip | react | react | 0.01ms | 通过 |
| tool_search | 搜索golang教程 | react | react | 0.00ms | 通过 |
| tool_shell | 执行ls命令 | react | react | 0.00ms | 通过 |
| translation | 翻译hello为中文 | react | react | 0.00ms | 通过 |
| knowledge | 什么是机器学习 | react | react | 0.00ms | 通过 |
| skill_prefix_react | @skill:react_agent 查看ip | skill_react | skill_react | 0.02ms | 通过 |
| **skill_prefix_direct** | **@skill:chat_only 你好** | **skill_react** | **direct_chat** | 0.02ms | **失败** |
| skill_not_found | @skill:nonexistent 做点什么 | react | react | 0.12ms | 通过 |
| complex_analysis | 帮我分析一下这个数据并生成报告 | react | react | 0.01ms | 通过 |
| empty_fallback | 随便聊聊 | react | react | 0.01ms | 通过 |

**失败用例分析**:
- **skill_prefix_direct**: 输入 `@skill:chat_only 你好`，期望 `skill_react`，实际返回 `direct_chat`
- **原因**: `chat_only` skill 不在 mock registry 中，RequestPreprocessor 正确 fallback 到 DIRECT_CHAT（greeting regex 匹配了"你好"）
- **评估**: 这是 mock 数据问题，非架构缺陷。在生产环境中，`@skill:chat_only` 会匹配到真实注册的 skill

### 2.2 过拟合检测 (Overfitting Detection)

**维度说明**: 测试同一意图的不同表达方式（口语化 vs 正式、中文 vs 英文）是否产生一致的执行模式。过拟合意味着系统只对特定关键词敏感，换个说法就路由错误——这是旧 CostAwareRouter 的核心问题。

**评分**: 100%（3/3 通过）

| 用例 ID | 期望模式 | 改写数量 | 一致性 | 耗时 | 结果 |
|---------|----------|----------|--------|------|------|
| ip_check_variants | react | 5 | 一致 | 0.00ms | 通过 |
| search_variants | react | 3 | 一致 | 0.00ms | 通过 |
| greeting_variants | direct_chat | 5 | 一致 | 0.00ms | 通过 |

**分析**: 消除 CostAwareRouter 后，不再依赖关键词匹配，因此不存在过拟合问题。所有改写都通过 regex 规则或 default fallback 正确分类。

### 2.3 执行效率 (Execution Efficiency)

**维度说明**: 测量核心组件的执行延迟。预处理应在 50ms 内完成（不阻塞用户请求），工具搜索应在 10ms 内完成（LLM 等待时间可忽略）。

**评分**: 100%（5/5 通过）

| 用例 ID | 组件 | 期望延迟 | 实际延迟 | 迭代次数 | 结果 |
|---------|------|----------|----------|----------|------|
| preprocess_greeting | RequestPreprocessor | <= 50ms/call | 0.003ms/call | 100 | 通过 |
| preprocess_react | RequestPreprocessor | <= 50ms/call | 0.004ms/call | 100 | 通过 |
| preprocess_skill_prefix | RequestPreprocessor | <= 50ms/call | 0.004ms/call | 100 | 通过 |
| tool_search_query | ToolSearchIndex | <= 10ms/call | 0.007ms/call | 200 | 通过 |
| tool_search_empty | ToolSearchIndex | <= 5ms/call | 0.000ms/call | 200 | 通过 |

**分析**: 所有组件延迟远低于阈值（预处理 0.003-0.004ms vs 阈值 50ms，工具搜索 0.007ms vs 阈值 10ms）。性能瓶颈不在预处理层，而在 LLM 调用层（通常 500ms-5s）。

### 2.4 工具搜索准确度 (Tool Search Accuracy)

**维度说明**: 测试 BM25 工具搜索引擎是否返回相关工具。这是工具分层注入策略的核心——LLM 通过 tool_search 获取扩展工具的完整描述。

**评分**: 100%（10/10 通过）

| 用例 ID | 查询 | 期望工具 | 实际结果 | 返回数 | 结果 |
|---------|------|----------|----------|--------|------|
| read_file_query | read file | read_file | read_file | 2 | 通过 |
| write_file_query | write file content | write_file | write_file | 2 | 通过 |
| web_search_query | search web information | web_search | web_search | 2 | 通过 |
| shell_exec_query | execute shell command | shell_exec | shell_exec | 1 | 通过 |
| http_request_query | send http request url | http_request | http_request | 1 | 通过 |
| file_tag_query | io file | read_file | read_file | 2 | 通过 |
| empty_query | (空) | 无结果 | [] | 0 | 通过 |
| no_match_query | zzzznonexistent | 无结果 | [] | 0 | 通过 |
| top_k_limit | file | read_file | read_file | 1 | 通过 |
| multi_token_query | search query engine | web_search | web_search | 1 | 通过 |

**分析**: BM25 搜索在精确匹配、多关键词、标签匹配、空查询、无匹配、top_k 限制等场景下均表现正确。相比旧的全量工具描述注入，分层注入 + tool_search 可显著减少 token 消耗。

### 2.5 事件模型完整性 (Event Model Integrity)

**维度说明**: 测试 SQ/EQ 双队列的生命周期管理。SQ (SubmissionQueue) 接收用户输入，EQ (EventQueue) 推送 Agent 事件。这是统一事件模型的基础设施。

**评分**: 100%（6/6 通过）

| 用例 ID | 测试点 | 期望 | 实际 | 耗时 | 结果 |
|---------|--------|------|------|------|------|
| sq_submit_drain | SQ 提交+排空 | task_id + drained=['hello'] | task_id=fbd7435e... drained=['hello'] | 0.09ms | 通过 |
| sq_cancel | SQ 取消 | cancelled=True | cancelled=True | 0.03ms | 通过 |
| sq_close_blocks | SQ 关闭后拒绝提交 | RuntimeError | raised=True closed=True | 0.01ms | 通过 |
| eq_emit_subscribe_replay | EQ emit+订阅回放 | 1 event replayed | 1 events | 0.05ms | 通过 |
| eq_close_sentinel | EQ 哨兵关闭 | subscriber 退出 | 1 events, closed=True | 21.58ms | 通过 |
| eq_subscriber_count | EQ 初始订阅者数 | 0 subscribers | 0 subscribers | 0.01ms | 通过 |

**分析**: SQ/EQ 双队列的核心功能全部正确。哨兵关闭模式（sentinel pattern）确保了优雅关闭，订阅者不会永久阻塞。事件回放缓冲区（100 事件）确保新订阅者能获取历史事件。

### 2.6 Spec 管理功能 (Spec Management)

**维度说明**: 测试 SpecManager 的 CRUD 操作。Spec 是"计划即契约"的核心——PlanExecEngine 生成计划后持久化为 Spec，用户确认后才执行。

**评分**: 100%（7/7 通过）

| 用例 ID | 操作 | 期望 | 实际 | 耗时 | 结果 |
|---------|------|------|------|------|------|
| spec_create | 创建 Spec | 文件存在 | exists=True | 1.76ms | 通过 |
| spec_get | 读取 Spec | 2 个步骤 | steps=2 | 0.00ms | 通过 |
| spec_update | 更新 Spec | goal='Updated goal' | goal=Updated goal | 1.40ms | 通过 |
| spec_confirm | 确认 Spec | status=confirmed | status=confirmed | 1.46ms | 通过 |
| spec_list | 列出 Spec | 2 个 | 2 specs | 3.71ms | 通过 |
| spec_delete | 删除 Spec | deleted, 1 remaining | deleted=True, remaining=1 | 1.92ms | 通过 |
| spec_get_missing | 读取不存在的 Spec | None | None | 0.08ms | 通过 |

**分析**: SpecManager 的完整 CRUD 流程正确。Spec 以 YAML 格式持久化到 `.agentkit/specs/` 目录，支持创建、读取、更新、确认、列表、删除操作。

### 2.7 验证循环 (Verification Loop)

**维度说明**: 测试 VerificationLoop 的 verify/verify_and_retry 行为。这是"可验证执行"的核心——Agent 执行后自动运行测试命令，失败时可重试。

**评分**: 100%（5/5 通过）

| 用例 ID | 场景 | 期望 | 实际 | 耗时 | 结果 |
|---------|------|------|------|------|------|
| verify_pass | 验证通过 | passed=True, attempts=1 | passed=True, attempts=1 | 11.49ms | 通过 |
| verify_fail | 验证失败 | passed=False, has errors | passed=False, errors=1 | 12.06ms | 通过 |
| verify_retry | 重试修复 | attempts=3, callback 2x | attempts=3, callbacks=2 | 33.52ms | 通过 |
| verify_timeout | 超时 | timeout error | passed=False, errors=1 | 506.47ms | 通过 |
| verify_multi_command | 多命令 | overall fail | passed=False | 33.70ms | 通过 |

**分析**: VerificationLoop 正确处理了通过、失败、重试（带 fix_callback）、超时、多命令组合等场景。默认命令 `pytest -x -q` + `ruff check src/` 覆盖了测试和 lint 两个维度。

---

## 三、问题总结

### 3.1 已发现问题

| 编号 | 维度 | 严重度 | 问题描述 | 根因 |
|------|------|--------|----------|------|
| #001 | 预处理准确度 | 低 | `@skill:chat_only 你好` 期望 skill_react 但返回 direct_chat | mock registry 中无 `chat_only` skill，RequestPreprocessor 正确 fallback 到 DIRECT_CHAT（greeting regex 匹配"你好"） |

### 3.2 问题影响评估

**问题 #001**:
- **影响范围**: 仅影响 benchmark 测试结果，不影响生产环境
- **生产环境行为**: 在生产环境中，`@skill:chat_only` 会匹配到真实注册的 skill，不会触发 fallback
- **修复建议**: 在 benchmark mock 数据中注册 `chat_only` skill，或修改期望值为 `direct_chat`（因为 fallback 行为是正确的）

### 3.3 架构层面无问题

本次回测未发现架构层面的缺陷：
- 消除路由层后，预处理准确度达到 93.3%（唯一失败是 mock 数据问题）
- 过拟合检测 100% 通过，证明消除关键词路由是正确的
- 工具搜索、事件模型、Spec 管理、验证循环均 100% 通过
- 执行效率远超预期（预处理 0.003ms vs 阈值 50ms）

---

## 四、改进建议

### 4.1 短期改进（P0-P1）

| 优先级 | 改进项 | 说明 | 预期收益 |
|--------|--------|------|----------|
| P0 | 修复 benchmark mock 数据 | 注册 `chat_only` skill 或调整期望值 | 消除唯一失败用例 |
| P1 | 增加 LLM-backed 测试维度 | 使用 Mock LLM 模拟 ReAct 循环，测试端到端执行能力 | 覆盖组件集成层面 |
| P1 | 增加复杂任务执行用例 | 多步骤工具链任务（搜索→分析→生成报告） | 验证 ReAct 循环的正确性 |
| P1 | 建立历史基线 | 保存每次回测结果，支持趋势对比 | 量化架构演进的收益 |

### 4.2 中期改进（P2）

| 优先级 | 改进项 | 说明 | 预期收益 |
|--------|--------|------|----------|
| P2 | 增加 WebSocket 事件流测试 | 验证 portal.py 的 EQ 集成是否正确推送事件 | 确保前端事件流完整 |
| P2 | 增加 hub-and-spoke 专家团测试 | 测试 Lead Expert 任务分解 + 并行 Task 执行 | 验证 U3 简化后的专家团功能 |
| P2 | 增加上下文压缩测试 | 验证 ContextCompressor 在长对话中的行为 | 确保压缩不丢失关键信息 |
| P2 | 增加性能压力测试 | 并发 100 个 EQ 事件，测量吞吐量和延迟 | 验证 EQ 的生产可用性 |

### 4.3 长期改进（P3）

| 优先级 | 改进项 | 说明 | 预期收益 |
|--------|--------|------|----------|
| P3 | 对接 SWE-bench 风格任务 | 使用真实代码仓库任务测试端到端能力 | 与行业 Benchmark 对标 |
| P3 | 增加 A/B 测试框架 | 对比新旧架构在同一任务集上的表现 | 量化架构优化的收益 |
| P3 | 增加前端集成测试 | Playwright 驱动前端 UI，验证完整用户流程 | 确保前后端一致性 |
| P3 | 增加多 LLM Provider 测试 | 验证不同 LLM 后端下的行为一致性 | 确保架构不绑定特定 LLM |

### 4.4 架构演进建议

基于回测结果，对架构演进的进一步建议：

1. **预处理层已足够轻量**（0.003ms/call），无需进一步优化。性能瓶颈在 LLM 调用层。
2. **工具搜索 BM25 已满足需求**（0.007ms/call），无需引入向量搜索。BM25 的优势是零依赖、确定性。
3. **EQ 事件模型已就绪**，但 portal.py 和 cli/chat.py 的集成是旁路模式。建议在 Phase 5 中将 EQ 作为主要事件通道，WebSocket 消息从 EQ 订阅。
4. **Spec 管理已可用**，但前端 UI 尚未实现。建议在 Phase 5 中实现 Spec 查看/确认 UI。
5. **验证循环已可用**，但 ReActEngine 的自动重试（fix_callback）尚未深度集成。建议在 Phase 5 中实现 LLM 驱动的自动修复。

---

## 五、附录

### 5.1 测试环境

- **Python**: 3.11+
- **操作系统**: macOS
- **测试框架**: pytest 8.x (asyncio_mode=auto)
- **Lint 工具**: ruff (target py311, line-length 100)
- **LLM 依赖**: 无（全部使用 Mock）

### 5.2 测试命令

```bash
# 完整回测 + 报告
agentkit benchmark --report --verbose

# 快速回测
agentkit benchmark --fast --report

# 单维度回测
agentkit benchmark -d preprocessing -v
agentkit benchmark -d tool_search -v

# HTML 报告
agentkit benchmark --report --format html

# pytest 综合回测
python3 -m pytest tests/e2e/test_capability_comprehensive.py -v
```

### 5.3 报告文件位置

```
test-results/
├── benchmark/
│   ├── benchmark_report.json    # JSON 结构化报告
│   ├── benchmark_report.txt     # 文本报告
│   └── benchmark_report.html    # HTML 可视化报告
└── e2e/
    ├── comprehensive_report.json # pytest 综合报告
    └── comprehensive_report.txt  # pytest 综合文本报告
```
