feat: add Evaluation + Optimization closed-loop example (#91)

.gitignore

@@ -27,3 +27,5 @@ pyrightconfig.json
 
 # spec-workflow tool artifacts
 .spec-workflow
+
+.claude/settings.local.json

examples/optimization/eval_optimize_loop/.gitignore

@@ -0,0 +1,12 @@
+# Runtime artifact output
+runs/
+optimization_report.json
+optimization_report.md
+
+# Local model credentials (never commit)
+.env
+
+# Python
+__pycache__/
+*.pyc
+.pytest_cache/

examples/optimization/eval_optimize_loop/DESIGN.md

@@ -0,0 +1,33 @@
+# 方案设计（Issue #91：Evaluation + Optimization 闭环）
+
+## Champion–Challenger 与数据隔离
+
+管线把当前源 prompt 定义为 Champion，把 `AgentOptimizer.optimize(update_source=False)`
+产出的最佳 prompt（或 fake 模式下的显式候选）定义为 Challenger。训练集只供优化器发现
+问题；验证集是独立裁判，只参与回归与门禁，失败细节不回喂优化器。fake 模式由 prompt 内
+公开的 `FAKE_CONTROLS` 控制项生成可评测轨迹，仅验证流程本身，不证明泛化能力。
+
+## 失败归因方法
+
+归因完全基于 evaluator 证据，不读场景标签：先用 `error_message` / `NOT_EVALUATED`
+区分 infrastructure_failure；再按失败 metric 名与 reason 识别 knowledge_fail /
+rubric_fail；然后对比期望与实际工具轨迹区分 tool_call_error（缺调用或调错工具）与
+param_error（同名工具参数不一致，附参数 diff）；最后对比 actual/expected 文本，核心
+数值一致判 format_fail，否则 reply_mismatch；证据不足时输出 insufficient_evidence，
+不臆造类别。每个失败 case 至少给出一条可解释原因和原始证据。
+
+## 接受策略与防过拟合
+
+Gate 为纯规则、逐条单测：G1 验证集提升 ≥ min_val_lift；G2 train 升而 val 降视为过拟
+合，直接拒绝；G3 不新增 high-risk hard fail；G4 protected case 不退化；G5 slice 平均
+退化不超 tolerance；G6 成本证据完整且不超预算，成本未知一律禁止自动接受；G7 epsilon
+内的微小波动不算有效提升。防过拟合由 train/val 物理隔离 + G2 + G4/G5 共同保证。
+
+## 产物审计
+
+每次运行生成唯一 `runs/<UTC时间>-<随机后缀>/` 目录，`frozen.json` 冻结 prompt、数据
+集、评测/优化/gate 配置与随机种子的 sha256；落盘 Champion/Challenger 快照、完整
+evaluator 结果、优化轮次、调用审计、耗时与成本。`optimization_report.{json,md}` 记录
+baseline / candidate 分数、逐 case delta、归因统计、gate 决策与理由、复现命令。默认
+dry-run；仅 ACCEPT 且显式 `--apply` 时经 `TargetPrompt` 原子写回，优化失败也会落盘可
+审计的 REJECT 报告。

examples/optimization/eval_optimize_loop/README.md

@@ -0,0 +1,78 @@
+# Evaluation + Optimization 闭环示例
+
+本示例把 `AgentEvaluator` 与 `AgentOptimizer` 串成可复现的
+Champion–Challenger 流程：冻结输入、评测基线、归因失败、生成候选、
+重新评测、执行 Gate，并保存 JSON/Markdown 报告。默认 dry-run；只有
+显式传入 `--apply` 且全部 Gate 通过时才更新源 Prompt。
+
+## 无 API Key 的管线回归
+
+```powershell
+python .\examples\optimization\eval_optimize_loop\pipeline.py --mode fake --scenario success
+python .\examples\optimization\eval_optimize_loop\pipeline.py --mode fake --scenario no_effect
+python .\examples\optimization\eval_optimize_loop\pipeline.py --mode fake --scenario overfit
+```
+
+| 场景 | 明文 `FAKE_CONTROLS` | 预期结果 |
+|---|---|---|
+| `success` | `ADD_STEPS=true` | train/val 均提升，ACCEPT |
+| `no_effect` | 两项均为 `false` | 无有效提升，REJECT G1 |
+| `overfit` | `MEMORIZE_TRAIN=true` | train 提升、val 退化，REJECT G2 |
+
+Fake 模式根据 Prompt 内的公开控制项生成 trace，再交给真实
+`AgentEvaluator` 评分；它只用于确定性管线回归，不证明隐藏样本泛化能力，
+也不替代原生优化器。
+
+## 原生 optimize
+
+```powershell
+$env:TRPC_AGENT_API_KEY="..."
+$env:TRPC_AGENT_BASE_URL="https://..."
+$env:TRPC_AGENT_MODEL_NAME="..."
+python .\examples\optimization\eval_optimize_loop\pipeline.py --mode optimize --optimizer-config optimizer.json
+```
+
+该路径使用真实模型回调并实际调用
+`AgentOptimizer.optimize(..., update_source=False)`。Optimizer 仅看到训练集；
+返回的 `best_prompts["system"]` 作为 Challenger，再用同一 train/val 数据和
+Gate 做回归。缺少配置、优化异常或未产出 Candidate 时仍会生成
+`OPTIMIZER_FAILURE + G6` 的 REJECT 报告。模型端未返回可信 token/费用时，
+报告写 `cost_status="unavailable"`、数值为 `null`，并禁止自动写回。
+
+## Gate 与写回
+
+G1 验证集最小提升；G2 训练涨而验证跌；G3 不新增高风险失败；G4 protected
+case 不退化；G5 slice 退化不超阈值；G6 成本证据完整且不超预算；G7
+过滤 epsilon 内的微小变化。阈值见 `run.json`。
+
+```powershell
+# 只有 ACCEPT 才会通过 TargetPrompt 原子写回
+python .\examples\optimization\eval_optimize_loop\pipeline.py --mode fake --scenario success --apply
+```
+
+REJECT 加 `--apply` 返回退出码 2，Champion 保持不变。评测临时切换和测试恢复
+也统一使用 `TargetPrompt.read_all/write_all`。
+
+## 数据、证据与产物
+
+- `data/train.evalset.json`、`data/val.evalset.json`：各 3 条，eval_id 互斥。
+- `data/attribution_holdout.json`：公开标注证据集，不是官方隐藏集。
+- `optimization_report.json/.md`：最新决策及逐 case 证据。
+- `optimization_report.example.json`：已脱敏的报告结构示例。
+- `runs/<UTC时间>-<随机后缀>/`：冻结清单、Prompt 快照、完整 evaluator
+  结果、优化轮次、调用审计与报告；该目录被 Git 忽略。
+
+逐 case 报告保存 actual/expected response、metric reason、tool use/response、
+参数差异和 trace 引用，并区分 agent-quality、infrastructure failure 与
+`insufficient_evidence`。官方隐藏集未提供，因此不声称满足隐藏样本准确率；
+公开归因 holdout 的实际统计由测试计算。
+
+## 验证
+
+```powershell
+python -m pytest .\examples\optimization\eval_optimize_loop\tests -q
+python -m compileall -q .\examples\optimization\eval_optimize_loop
+```
+
+测试包含三种 fake 场景、mock native optimizer 完整闭环、真实 evaluator
+工具/参数证据、成本不可用拒绝 apply、Prompt 恢复、Gate 和报告 schema。