基于 Checklist 的 Code Agent 对比评测工具，支持同时评测多个 CLI Code Agent 并输出对比报告。

评测题 (requirement + checklist)
    → Code Agent (CLI) 根据 requirement 生成代码
    → 评测 LLM 根据 checklist 逐项检查代码
    → 输出评测报告 (通过率、对比排名)

• requirement：给 Code Agent 看的需求描述，Agent 据此生成代码
• checklist：评测用的检查点列表，不展示给 Code Agent，仅在评测阶段由评测 LLM 逐项验证

agent/
├── checklist_eval/       # Checklist 评测核心代码
│   ├── configs/          # 配置（提示词、参数等）
│   ├── data/             # 数据模型定义
│   ├── generator/        # 评测题生成、CLI 代码生成
│   ├── evaluator/        # Checklist 评测 Agent
│   ├── report/           # 结果汇总统计
│   ├── examples/         # 示例脚本和数据
│   ├── run_eval.py       # 单 Agent 评测入口
│   └── run_multi_eval.py # 多 Agent 对比评测入口
├── common/               # 公共组件（LLM Client、Logger）
├── ground_truth_eval/    # 基于 Ground Truth 的评测（独立方案）
├── .env                  # 环境变量配置
├── setup.py              # 安装配置
└── requirements.txt      # 依赖清单

cd evaluation/agent
pip install -r requirements.txt

支持三个 Code Agent，按需安装你要测试的即可：

Agent	CLI 命令	安装方式	验证命令
CodeBuddy Code	codebuddy	安装 CodeBuddy IDE 后自带 CLI	which codebuddy
Claude Code	claude	npm install -g @anthropic-ai/claude-code	which claude
Kiro CLI	kiro-cli	参考 Kiro 官方文档安装	which kiro-cli

安装后需要先完成各 CLI 工具自身的登录/认证，确保单独执行命令能正常工作：

# 测试 CodeBuddy
codebuddy -p "你好" -y

# 测试 Claude Code
claude -p "你好" --dangerously-skip-permissions --output-format text

# 测试 Kiro
kiro-cli chat --no-interactive --trust-all-tools "你好"

评测阶段需要一个 LLM 来读取生成的代码、逐项判断 checklist 是否通过。

在 agent/.env 中配置：

# 必填：评测 LLM 的 API Key
COPILOT_API_KEY=your_api_key

# 可选：API 地址（默认为腾讯 Copilot）
COPILOT_BASE_URL=https://your-api-endpoint/v1

# 可选：模型名称（默认 claude-4.5-codewise）
COPILOT_MODEL=your_model_name

支持任意 OpenAI 兼容 API，配置示例：

服务商	COPILOT_BASE_URL	COPILOT_MODEL	COPILOT_API_KEY
腾讯 Copilot（默认）	不用填	claude-4.5-codewise	Copilot API Key
OpenAI	https://api.openai.com/v1	gpt-4o	sk-xxx
DeepSeek	https://api.deepseek.com/v1	deepseek-chat	sk-xxx
自定义中转	https://gateway.xxx.ai/v1	按需填写	对应 Key

注意：此 API Key 仅用于评测 LLM（判断代码质量），与 Code Agent CLI 的认证无关。

cd evaluation/agent

PYTHONPATH=. python -m checklist_eval.run_multi_eval \
    --questions_file checklist_eval/examples/demo_data/generated_questions_by_category.json \
    --output_dir /tmp/eval_output \
    --agents <agent列表> \
    --num_questions <题目数>

测试单个 Agent（如 CodeBuddy），跑 1 题：

PYTHONPATH=. python -m checklist_eval.run_multi_eval \
    --questions_file checklist_eval/examples/demo_data/generated_questions_by_category.json \
    --output_dir /tmp/eval_output \
    --agents codebuddy_code \
    --num_questions 1

三个 Agent 对比评测，跑 5 题：

PYTHONPATH=. python -m checklist_eval.run_multi_eval \
    --questions_file checklist_eval/examples/demo_data/generated_questions_by_category.json \
    --output_dir /tmp/eval_output \
    --agents claude_code,codebuddy_code,kiro_cli \
    --num_questions 5

并行模式（代码生成并行 + 评测并行）：

PYTHONPATH=. python -m checklist_eval.run_multi_eval \
    --questions_file checklist_eval/examples/demo_data/generated_questions_by_category.json \
    --output_dir /tmp/eval_output \
    --agents claude_code,codebuddy_code,kiro_cli \
    --num_questions 5 \
    --parallel --eval_concurrency 4

跳过代码生成，仅对已有代码重新评测：

PYTHONPATH=. python -m checklist_eval.run_multi_eval \
    --questions_file checklist_eval/examples/demo_data/generated_questions_by_category.json \
    --output_dir /tmp/eval_output \
    --agents codebuddy_code \
    --skip_code_gen

从第 5 题开始跑 3 题：

PYTHONPATH=. python -m checklist_eval.run_multi_eval \
    --questions_file checklist_eval/examples/demo_data/generated_questions_by_category.json \
    --output_dir /tmp/eval_output \
    --agents codebuddy_code \
    --start_index 5 --num_questions 3

后台静默执行：

nohup env PYTHONPATH=. python -m checklist_eval.run_multi_eval \
    --questions_file checklist_eval/examples/demo_data/generated_questions_by_category.json \
    --output_dir /tmp/eval_output \
    --agents claude_code,codebuddy_code,kiro_cli \
    --num_questions 5 --parallel \
    > /tmp/eval_output/run.log 2>&1 &

参数	默认值	说明
--questions_file	必填	评测题 JSON 文件路径
--output_dir	必填	输出目录
--agents	全部三个	Agent 列表，逗号分隔：claude_code, codebuddy_code, kiro_cli
--num_questions	全部	评测题目数量
--start_index	0	起始题目索引
--code_gen_timeout	1800	代码生成超时（秒）
--eval_max_iterations	30	评测 Agent 最大工具调用次数
--skip_code_gen	False	跳过所有 Agent 的代码生成
--skip_agents_code_gen	无	跳过指定 Agent 的代码生成，逗号分隔
--parallel	False	并行模式：多个 Agent 同时生成代码，评测 checkpoint 也并行
--eval_concurrency	4	并行模式下评测的并发数

/tmp/eval_output/
├── codebuddy_code/
│   ├── task_000/
│   │   ├── index.html              # Agent 生成的代码
│   │   └── eval_result.json        # 逐项评测结果
│   ├── task_001/
│   │   └── ...
│   └── logs/                       # CLI 执行日志
├── claude_code/
│   └── ...
├── kiro_cli/
│   └── ...
├── logs/                           # 评测主日志
└── multi_eval_summary_*.json       # 对比汇总报告

指标	说明
pass_rate	检查点通过率（核心指标）
passed	通过的检查点数
failed	失败的检查点数
unknown	无法判定的检查点数（通常是评测 LLM 配置问题）

方案	适用场景	文档
Checklist 评测	端到端代码生成能力评估	checklist_eval/README.md
Ground Truth 评测	模型质量评估（蒸馏数据真值对比）	ground_truth_eval/README.md