smart-agent-kit

适用于由MCP驱动的AI代理的启动工具包：包括示例客户端、评估工具以及与Claude Code及更多内容的简单集成指南。

概述

此工具包提供了一个全面的评估框架，用于测试由模型上下文协议（MCP）工具驱动的AI代理。它包括：

• 数据集管理：用于测试AI代理能力的结构化真实数据集
• 自动化评估：copilot_evaluator.py用于运行Claude Code对抗测试问题
• Web可视化：copilot_web_visualizer.py用于评估结果的交互式分析

数据集结构

评估数据集在datasets/目录下按照特定结构组织。根据需要更新，添加带有提示和预期结果的问题项。

datasets/
└── copilot/
    ├── groundtruth.json          # 主数据集配置
    ├── Question1/
    │   └── Prompt.txt            # Question1的测试提示
    └── Question2/
        └── Prompt.txt            # Question2的测试提示

数据集配置（groundtruth.json）

主数据集文件定义了测试问题及其结构：

{
  "questions": [
    {
      "question_id": "Question1",
      "prompt": "Question1/Prompt.txt",
      "input": [],
      "output": [
      ],
      "snapshots": [
      ]
    }
  ]
}

字段：

• question_id：问题的唯一标识符
• prompt：提示文件的路径（相对于数据集目录）
• input：输入文件列表（当前未使用）
• output：预期输出文件列表，用于比较（当前未使用）
• snapshots：参考截图列表（当前未使用）

问题结构

每个问题目录包含：

• Prompt.txt：将发送给AI代理的测试提示
• Output/：包含预期输出文件（如XML、JSON等）的目录
• Snapshot/：包含用于视觉比较的参考截图的目录

Copilot Evaluator (copilot_evaluator.py)

评估器运行Claude Code对抗来自真实数据集的问题，并执行自动化评估。

使用方法

python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json [选项]

命令行参数

参数	描述	默认值
--dataset	真实数据集JSON文件的路径	必需
--question-ids	要运行的具体问题ID（使用'all'表示所有问题）	[]
--output	结果的基本输出目录	output
--mcp-config	MCP配置文件的路径	conf/.mcp.json
--claude-md	CLAUDE.md文件的路径	conf/CLAUDE.md
--log-level	日志级别（DEBUG, INFO, WARNING, ERROR）	INFO
--timeout	每次执行的超时时间（例如，'600s', '5m', '1h'）	10m
--debug	启用调试模式	True
--max-turns	每次执行的最大对话轮数	50
--checkpoint	恢复用的checkpoint.json路径	None
--skip-eval	跳过运行评估	False
--force-eval	强制重新计算所有评估	False

示例

# 运行所有问题
python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json

# 运行特定问题
python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json --question-ids Question1 Question2

# 使用自定义超时时间和最大轮数运行
python copilot_evaluator.py --dataset datasets/copilot/groundtruth.json --timeout 15m --max-turns 100

# 从检查点恢复
python copilot_evaluator.py --checkpoint output/copilot_evaluator_20250113_120000/checkpoint.json

输出结构

评估器创建带有时间戳的输出目录：

output/
└── copilot_evaluator_20250113_120000/
    ├── checkpoint.json                    # 进度跟踪
    ├── results_20250113_120500.json      # 总结结果
    ├── logs/
    │   └── claude_code_runner_20250113_120000.log
    ├── Question1/
    │   ├── .claude/
    │   │   └── settings.local.json       # Claude配置
    │   ├── .mcp.json                     # MCP配置
    │   ├── CLAUDE.md                     # 生成的文档
    │   ├── claude_code_result.json       # 执行结果
    │   └── [生成的文件]                  # AI代理输出
    ├── Question1_eval/
    │   ├── claude_code_result.json       # 评估执行
    │   ├── eval_result.json              # 评估分数
    │   └── eval_validation_tools.json    # 验证工具使用情况
    └── Question2/
        └── [类似结构]

评估指标

评估器衡量四个关键维度上的性能：

1. 准确性：正确回答问题的比例
2. 完整性：完全回答问题的比例
3. 验证：通过MCP工具验证的比例（例如SSL语法、XFD表单验证）

每个指标评分范围为0-1，并提供详细的Markdown格式推理。

Web可视化器 (copilot_web_visualizer.py)

交互式的基于Web的仪表板，用于通过图表、详细分解和导出功能分析评估结果。

使用方法

python copilot_web_visualizer.py results.json [选项]

命令行参数

参数	描述	默认值
results_file	结果JSON文件的路径	必需
--port	运行服务器的端口	3002
--no-browser	不自动打开浏览器	False
--no-debug	禁用调试模式和自动重载	False

示例

# 查看结果并自动打开浏览器
python copilot_web_visualizer.py output/copilot_evaluator_20250113_120000/results_20250113_120500.json

# 在自定义端口上运行且不打开浏览器
python copilot_web_visualizer.py results.json --port 8080 --no-browser

仪表板功能

Web可视化器提供了四个主要视图：

📊 概览标签

• 直方图图表：所有指标得分分布
• 汇总统计：总问题数量、成功率、平均得分
• 性能指标：颜色编码的指标（红色 < 0.25，橙色 < 0.5，黄色 < 0.75，绿色 ≥ 0.75）

🎯 雷达标签

• 雷达图：多维性能可视化
• 平均得分：所有评估指标的综合视图
• 交互式：悬停查看详细得分分解

📈 时间线标签

• 性能趋势：按问题序列显示指标的折线图
• 多个指标：准确性、完整性、真实数据、验证、待办事项完成
• 模式分析：识别性能趋势和异常值

📋 分析标签

• 详细表格：逐个问题分解
• 交互元素：
  • 悬停提示芯片以查看完整提示
  • 点击成功指示器查看错误详情
  • 查看步骤计数和工具使用分解
  • 访问单独问题的详细页面
• 导出选项：下载单独结果或整个数据集

单个问题详细信息

点击任意问题ID以查看详细分析：

• 📈 概览：带推理的得分分解
• 💬 提示：完整的测试提示文本
• 🔄 步骤：详细的执行步骤和工具使用
• 🗂️ 输出：生成的文件和内容
• 🎯 真实数据：用于比较的预期输出文件
• ✅ 待办事项：任务完成跟踪
• 🧾 完整结果：带有树/文本视图的完整JSON数据

关键特性

• 实时工具提示：悬停任何元素获取详细信息
• Markdown支持：推理文本支持完整的Markdown格式
• 响应式设计：适用于桌面和移动设备
• 导出功能：下载结果为JSON或单独文件
• 交互式图表：由Plotly提供丰富的数据可视化

设置和依赖项

先决条件

• Python 3.8+
• 已安装并配置好的Claude Code CLI
• 正确配置的MCP工具
• .env文件中的ANTHROPIC_API_KEY

安装

pip install -r requirements.txt

必需依赖项

• flask>=2.3.0 - 视觉化的Web服务器
• plotly>=5.15.0 - 交互式图表
• python-dotenv>=1.0.0 - 环境变量管理
• aiohttp>=3.9.0 - 异步HTTP操作
• markdown>=3.4.0 - Markdown渲染

工作流程

1. 准备数据集：在datasets/copilot/中创建或修改问题
2. 运行评估：使用您的数据集执行copilot_evaluator.py
3. 分析结果：使用copilot_web_visualizer.py查看和分析结果
4. 迭代：根据需要修改提示、添加问题或调整评估标准

配置

MCP配置

确保您的MCP配置文件（通常是conf/.mcp.json）已正确设置：

• 所需的MCP服务器
• API密钥的环境变量
• 工具权限

环境变量

创建一个.env文件：

ANTHROPIC_API_KEY=your_api_key_here

故障排除

常见问题

1. 找不到Claude Code：确保Claude Code CLI已安装并在PATH中
2. MCP工具无法工作：验证MCP配置和服务器状态
3. 权限错误：检查输出目录的文件权限
4. 超时问题：增加复杂问题的超时值