feat(24_miracle): add evaluation adapter and matrix pipeline

[thugongheng]

内容

• 接入第24届 Miracle 外部 Judge
• 统一 Python/C++ 策略启动接口
• 支持换边、异常分类、进程树清理和可恢复评测
• 支持 Framework events、summary 与 AgentBenchResults 聚合
• 增加 Windows main.exe 和路径兼容
• 增加矩阵编排、协议及审计文档

验证

• Python 3.11：142 passed
• Python 3.13：142 passed
• 基础设施 smoke：4/4完成
• 正式 Plan A：32/32 attempts完成
• 0重跑、0基础设施异常、0残留进程
• Results schema、aggregate、summary和网页四向一致

实验结果

• 20 valid，12 invalid
• 有效战绩：2W–18L
• 有效胜率：10%
• 12 invalid均由对手AI超时或崩溃造成，不计入胜率
• 未修改人类策略或Judge

边界

• 未提交 .smoke/、Replay、编译产物或本机路径
• 未运行16×16、RL或hidden evaluation

[wkj2333666]

Request changes

这组改动目前不能合并。请先完成下面的必修修复，并重新运行完整测试。

必修修改

1. 修复矩阵输出的 Framework/CI 契约

write_run_compatible_output() 生成的 run.toml 缺少 [run].created，会被 agentbench data check 拒绝；复制到 events.jsonl 的矩阵记录也没有 event: "game"，通用事件读取器无法识别，CI 从事件重算会得到 0 局。

建议：

• 让矩阵事件复用统一的事件封装，至少补齐 event、timestamp、schema_version、run_id 等公共字段；
• 让 run.toml 补齐 run_id/game/agent/type/created；
• 添加一个矩阵输出经过 agentbench data check，并且从 events.jsonl 独立重算与 summary.json 一致的测试。

参考：matrix_runner.py

2. 实现真正的断点续跑

当前 prepare_session_for_existing() 遇到已有 session 直接抛出 FileExistsError，工具入口又始终创建新 session，因此进程中断后无法恢复。

建议：

• 增加明确的 --resume <session_id> 入口；
• 校验 manifest、代码/资产 hash、plan 和 run_id 后再打开旧 session；
• 对 running 状态保持保守停止；
• 对已有 done 记录不重跑，并验证 progress、events、audit 三者一致。

参考：matrix_runner.py

3. 修复 POSIX 进程清理

当前强制 kill 后没有回收 Popen，会留下 zombie PID；本地 Linux 运行中 test_proctree.py 的 6 项全部失败。

建议：

• 对自有 Popen 在 terminate/kill 后调用 wait()；
• 区分“进程已退出但尚未 reap”和“仍在运行”；
• 重新验证 parent、child、PID reuse、幂等清理和 residual check。

参考：proctree.py

4. 真正原子地写入 result JSON

文档和 match_runner.py 声称 result JSON 使用 temp + replace，但 vendor 实际直接 write_text()。超时或强杀可能留下半截 JSON。

建议使用同目录临时文件、UTF-8 编码、flush/fsync 后 os.replace()，并补充“写入中被终止”的测试。

参考：run_match.py

5. 保留完整的一手过程数据

MatchAttempt 中的 judge_exit/ai0_exit/ai1_exit/timeout/exception/replay_sha256/process_cleanup 等字段没有传入 GameOutcome，最终事件中会变成 null，不满足“框架保存一手数据、CI 负责计算指标”。

建议：

• 完整映射过程退出码、超时、异常、清理状态、Replay SHA、证据路径；
• 不要把真实 exception 覆盖成简单的 reason；
• 对关键字段增加非空/值一致性测试。

参考：runner.py、result.py

6. 不能忽略 vendor 异常和非零返回码

classify() 当前只看 end_info 和 Replay；当 result JSON 中已有 exception 或 run_match_returncode != 0 时，仍可能被判为 valid。这样会把基础设施失败包装成有效胜负。

建议：除明确允许的 AI 赛后清理非零码外，vendor exception、vendor 非零返回码、cleanup 失败都必须进入 invalid/infrastructure 分类，并增加对应回归测试。

参考：match_runner.py

重新验收

• 完整 pytest：无失败；
• agentbench data check 通过；
• 矩阵中断后可从同一 session 继续，成功局不重跑；
• CI 从一手 events.jsonl 重算出的 attempts/valid/win_rate 与 summary 一致；
• Linux/Windows 的进程清理和残留检查均通过。

[wkj2333666]

自动审阅结果：未调用模型。该 PR 包含 74 个文件、9204 行新增，完整 diff 超过当前 350000 字节上限，因此 trusted review 按 fail-closed 策略拒绝截断审阅。请按可独立验证的功能拆分为多个 PR，每个 PR 保持完整 diff 低于上限，再分别触发自动审阅。当前红色 AI check 表示输入规模不可完整审阅，不是模型对代码质量的结论。运行记录：https://github.com/SAST-agent/AgentBenchFramework/actions/runs/30259857003