feat(examples): add evaluation optimization closed-loop example

[xyxhhhhh]

概述

Closes #91.

本次提交实现了一个可复现的 Evaluation + Optimization 自动闭环示例。该示例串联了 baseline 评测、失败归因、prompt 优化、验证集回归、可配置 gate 决策和审计报告生成。

默认支持无 API Key 的 fake / trace 运行模式，同时保留 --mode optimizer 路径，可委托 AgentOptimizer 执行候选 prompt 搜索。

主要改动

• 新增 examples/optimization/eval_optimize_loop/
• 新增 pipeline 入口脚本：run_pipeline.py
• 新增训练集和验证集 evalset，共 10 条公开 case
• 新增 router / system / skill 三类 prompt 源文件，并全部注册为 TargetPrompt
• 新增 optimizer.json、case_meta.json、README 和 sample reports
• 新增 optimization_report.json 和 optimization_report.md 示例输出
• 新增仓库级回归测试：tests/evaluation/test_eval_optimize_loop_example.py

Pipeline 覆盖范围

本示例实现了 issue 要求的全部阶段：

1. 使用 AgentEvaluator 分别对训练集和验证集执行 baseline 评测
2. 对失败 case 做归因聚类，覆盖六类失败类型：
   • final_response_mismatch
   • tool_call_error
   • parameter_error
   • llm_rubric_not_met
   • knowledge_recall_insufficient
   • format_violation
3. 通过 deterministic fake candidate 或 AgentOptimizer 执行 prompt 优化
4. 对候选 prompt 重新运行验证集，并生成逐 case delta：
   • new_pass
   • new_fail
   • score_improved
   • score_regressed
   • unchanged
5. 实现可配置 gate：
   • 验证集分数提升阈值
   • 不允许新增 hard fail
   • 关键 case 不允许退化
   • overfitting guard
   • 成本预算上限
6. 输出审计产物：
   • 每轮 prompt
   • 评测结果摘要
   • 接受/拒绝理由
   • 成本拆分
   • 耗时
   • 随机种子和配置快照
   • 输入文件 hash
   • prompt hash 和 diff preview

输入输出

输入包括：

• train.evalset.json
• val.evalset.json
• optimizer.json
• prompt 源文件：
  • agent/prompts/router.md
  • agent/prompts/system.md
  • agent/prompts/skill.md

输出包括：

• optimization_report.json
• optimization_report.md
• candidate_prompts/
• 原始 AgentEvaluator 输出目录
• 配置快照
• prompt / input 审计信息

JSON 报告包含 baseline 分数、candidate 分数、逐 case delta、gate decision、gate reasons、失败归因统计、prompt audit、input audit、成本、token usage 和 optimizer rounds。

无 API Key 运行

本示例支持无 API Key 跑通核心流程：

• --mode fake：deterministic fake model + 本地 exact-match fake judge
• --mode trace：生成 eval_mode: "trace" evalset，并回放 actual_conversation

fake 和 trace 模式均不需要真实 API Key。

运行示例：

cd examples/optimization/eval_optimize_loop
PYTHONPATH=../../.. python run_pipeline.py --mode fake
PYTHONPATH=../../.. python run_pipeline.py --mode trace

另外保留真实优化路径：

• --mode optimizer：委托 AgentOptimizer.optimize，用于接入真实模型环境；测试中通过 mock AgentOptimizer 验证 wiring，不依赖真实 API Key。

真实 optimizer 模式示例：

export TRPC_AGENT_API_KEY="<your-key>"
export TRPC_AGENT_BASE_URL="<your-endpoint>"
export TRPC_AGENT_MODEL_NAME="<your-model>"
PYTHONPATH=../../.. python run_pipeline.py --mode optimizer

优化场景

fake / trace 路径包含三个 deterministic 场景：

PYTHONPATH=../../.. python run_pipeline.py --mode fake --scenario overfit
PYTHONPATH=../../.. python run_pipeline.py --mode fake --scenario accepted
PYTHONPATH=../../.. python run_pipeline.py --mode fake --scenario cost_exceeded

• overfit：训练集提升，但验证集没有提升，且关键验证 case 退化，因此 gate 拒绝候选。
• accepted：训练集和验证集均提升，且没有新增 hard fail，因此 gate 接受候选。
• cost_exceeded：质量提升，但估算成本超过配置预算，因此 gate 拒绝候选。

CI 风格退出码：

PYTHONPATH=../../.. python run_pipeline.py --mode fake --scenario accepted --ci-exit-code
PYTHONPATH=../../.. python run_pipeline.py --mode fake --scenario overfit --ci-exit-code

开启 --ci-exit-code 后，accepted 返回 0，rejected 返回 1。

Case 覆盖

本示例包含 10 条公开 case：

• 5 条训练集 case
• 5 条验证集 case

覆盖以下情况：

• 可优化成功
• 优化无效 / 无变化
• 优化后退化
• 关键 case 退化
• 稳定通过 case
• 六类失败归因类型

超过 issue 要求的最少 6 条 case。

Hidden 样本准备

官方 hidden set 不在仓库内，因此无法在本地直接证明 hidden 接受/拒绝准确率 ≥ 80%。为提高该项可信度，本次实现增加了：

• gate decision contract 文档
• gate 边界测试
• hidden-like unknown-case 测试
• failure attribution matrix 测试
• accepted / overfit / cost-exceeded 端到端场景
• mock AgentOptimizer 的 optimizer-mode wiring 测试

其中 hidden-like 测试会使用不在公开 evalset 和 case_meta.json 中的 case id，验证 gate 和失败归因逻辑不依赖公开样例名称。

测试

.venv/bin/python -m pytest tests/evaluation/test_eval_optimize_loop_example.py -q

当前结果：

10 passed

同时已验证：

cd examples/optimization/eval_optimize_loop
../../../.venv/bin/python -m py_compile run_pipeline.py agent/agent.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@73655ab). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #130   +/-   ##
==========================================
  Coverage        ?   87.56135%           
==========================================
  Files           ?         467           
  Lines           ?       44008           
  Branches        ?           0           
==========================================
  Hits            ?       38534           
  Misses          ?        5474           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.