From ed225cef170e61399a01ae1d2a86b296d9be25af Mon Sep 17 00:00:00 2001
From: tianyouyiwang <tianyouyiwang@users.noreply.github.com>
Date: Wed, 22 Jul 2026 12:05:00 +0800
Subject: [PATCH] examples: add eval-attribution-optimize-gate loop example

Add a self-contained example under examples/optimization that demonstrates
a six-stage closed loop: baseline evaluation, failure attribution, candidate
optimization, gate decision and audit reporting. It ships a deterministic
fake backend that needs no API key, plus an optional real backend backed by
an OpenAI-compatible model.

Updates #214

RELEASE NOTES: Add an evaluation-optimization loop example under examples/optimization.
---
 .../eval_optimize_loop/.env.example           |  17 +
 .../eval_optimize_loop/.gitignore             |   2 +
 .../optimization/eval_optimize_loop/README.md | 164 +++++
 .../artifacts/candidates/baseline.md          |   1 +
 .../artifacts/candidates/candidate_1.md       |   1 +
 .../artifacts/candidates/candidate_2.md       |   1 +
 .../artifacts/candidates/candidate_3.md       |   1 +
 .../artifacts/candidates/candidate_4.md       |   1 +
 .../artifacts/optimization_report.json        | 670 ++++++++++++++++++
 .../artifacts/optimization_report.md          |  71 ++
 .../artifacts/optimizer.snapshot.json         |  40 ++
 .../eval_optimize_loop/attribution.py         | 205 ++++++
 .../eval_optimize_loop/config/optimizer.json  |  40 ++
 .../config/real_optimizer.json                |  74 ++
 .../config/real_optimizer_smoke.json          |  71 ++
 .../data/real/train.evalset.json              |  40 ++
 .../data/real/val.evalset.json                |  40 ++
 .../data/real_smoke/train.evalset.json        |  18 +
 .../data/real_smoke/val.evalset.json          |  29 +
 .../data/train.evalset.json                   |  40 ++
 .../eval_optimize_loop/data/val.evalset.json  |  40 ++
 .../eval_optimize_loop/fake_agent.py          | 115 +++
 .../optimization/eval_optimize_loop/gate.py   | 131 ++++
 .../optimization_report.json                  | 670 ++++++++++++++++++
 .../eval_optimize_loop/optimizer.py           |  56 ++
 .../eval_optimize_loop/pipeline.py            | 296 ++++++++
 .../prompts/baseline_real.md                  |   1 +
 .../prompts/baseline_system.md                |   4 +
 .../eval_optimize_loop/real_call_agent.py     | 107 +++
 .../eval_optimize_loop/run_pipeline.py        | 194 +++++
 .../eval_optimize_loop/verify_real.py         |  47 ++
 31 files changed, 3187 insertions(+)
 create mode 100644 examples/optimization/eval_optimize_loop/.env.example
 create mode 100644 examples/optimization/eval_optimize_loop/.gitignore
 create mode 100644 examples/optimization/eval_optimize_loop/README.md
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/candidates/baseline.md
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_1.md
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_2.md
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_3.md
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_4.md
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/optimization_report.json
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/optimization_report.md
 create mode 100644 examples/optimization/eval_optimize_loop/artifacts/optimizer.snapshot.json
 create mode 100644 examples/optimization/eval_optimize_loop/attribution.py
 create mode 100644 examples/optimization/eval_optimize_loop/config/optimizer.json
 create mode 100644 examples/optimization/eval_optimize_loop/config/real_optimizer.json
 create mode 100644 examples/optimization/eval_optimize_loop/config/real_optimizer_smoke.json
 create mode 100644 examples/optimization/eval_optimize_loop/data/real/train.evalset.json
 create mode 100644 examples/optimization/eval_optimize_loop/data/real/val.evalset.json
 create mode 100644 examples/optimization/eval_optimize_loop/data/real_smoke/train.evalset.json
 create mode 100644 examples/optimization/eval_optimize_loop/data/real_smoke/val.evalset.json
 create mode 100644 examples/optimization/eval_optimize_loop/data/train.evalset.json
 create mode 100644 examples/optimization/eval_optimize_loop/data/val.evalset.json
 create mode 100644 examples/optimization/eval_optimize_loop/fake_agent.py
 create mode 100644 examples/optimization/eval_optimize_loop/gate.py
 create mode 100644 examples/optimization/eval_optimize_loop/optimization_report.json
 create mode 100644 examples/optimization/eval_optimize_loop/optimizer.py
 create mode 100644 examples/optimization/eval_optimize_loop/pipeline.py
 create mode 100644 examples/optimization/eval_optimize_loop/prompts/baseline_real.md
 create mode 100644 examples/optimization/eval_optimize_loop/prompts/baseline_system.md
 create mode 100644 examples/optimization/eval_optimize_loop/real_call_agent.py
 create mode 100644 examples/optimization/eval_optimize_loop/run_pipeline.py
 create mode 100644 examples/optimization/eval_optimize_loop/verify_real.py

diff --git a/examples/optimization/eval_optimize_loop/.env.example b/examples/optimization/eval_optimize_loop/.env.example
new file mode 100644
index 00000000..f47320b9
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/.env.example
@@ -0,0 +1,17 @@
+# 复制本文件为 .env 并填入你的 hy3 凭据（不要把真实 .env 提交到 git）
+#
+# 三件套是 tRPC-Agent 框架约定（trpc_agent_sdk 直接读 os.environ）：
+#   TRPC_AGENT_API_KEY     你的 hy3 API Key
+#   TRPC_AGENT_BASE_URL    hy3 的 OpenAI 兼容 endpoint，例如 https://<host>/v1
+#   TRPC_AGENT_MODEL_NAME  模型名，例如 hy3
+#
+# 两种生效方式（二选一）：
+#   A. 直接导出到当前 shell：
+#        export TRPC_AGENT_API_KEY=xxx
+#        export TRPC_AGENT_BASE_URL=https://<host>/v1
+#        export TRPC_AGENT_MODEL_NAME=hy3
+#   B. 用 .env 文件：在 run_pipeline.py 入口加 `from dotenv import load_dotenv; load_dotenv()`
+#      （python-dotenv 已随 requirements 安装），框架即可从 .env 读到上述变量。
+TRPC_AGENT_API_KEY=your-hy3-api-key
+TRPC_AGENT_BASE_URL=https://your-hy3-endpoint/v1
+TRPC_AGENT_MODEL_NAME=hy3
diff --git a/examples/optimization/eval_optimize_loop/.gitignore b/examples/optimization/eval_optimize_loop/.gitignore
new file mode 100644
index 00000000..c0b3eab9
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/.gitignore
@@ -0,0 +1,2 @@
+# 本地真实凭据，切勿提交（只提交 .env.example 占位模板）
+.env
diff --git a/examples/optimization/eval_optimize_loop/README.md b/examples/optimization/eval_optimize_loop/README.md
new file mode 100644
index 00000000..8f05c72c
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/README.md
@@ -0,0 +1,164 @@
+# Eval → Attribution → Optimize → Gate 自动闭环示例
+
+本示例演示如何把 tRPC-Agent 的 `AgentEvaluator` 与一个"等价扩展机制"的优化器,
+串成一个**可复现、可审计、带质量闸门**的自动闭环:先评测,再对失败做可解释归因,
+然后生成候选 prompt 并回归验证,最后由 gate 判定候选"是否真的提升、是否牺牲其他
+指标、是否过拟合、是否值得回写源 prompt"。
+
+整条流程默认**完全不需要任何 API Key**(确定性 fake 后端),同时提供一个可选的
+真实 LLM 后端(OpenAI 兼容,如 hy3),两套后端共用同一套编排、归因、gate 与审计逻辑。
+
+## 关键特性
+
+- **六阶段闭环**:评测 → 失败归因 → 优化执行 → 回归验证 → 接受策略(gate) → 产物审计。
+- **无 Key 可跑**:确定性 Fake Model / Fake Judge,秒级完成,结果完全可复现(固定 `seed`)。
+- **可解释失败归因**:把失败稳定归到 6 大类,并给出一句话原因与 `regression` 标记。
+- **防过拟合 gate**:关键 case 退化 / 新增 hard fail 一律拒绝,即使验证集总分提升。
+- **完整审计产物**:结构化 + 人读报告、每轮候选快照、可复现配置全部落盘。
+- **可选真实后端**:`EVAL_BACKEND=real` 一键切换到真实 LLM 生成 + `llm_rubric_response` judge。
+
+## 目录结构
+
+```text
+eval_optimize_loop/
+├── run_pipeline.py                  # 入口:组装配置、运行闭环、落盘报告
+├── pipeline.py                      # 编排层:把 6 个阶段串起来
+├── attribution.py                   # 失败归因(6 大类可解释分类)
+├── gate.py                          # 接受策略(可配置 gate)
+├── optimizer.py                     # 规则式优化器(与 GEPA 等价的确定性机制)
+├── fake_agent.py                    # 确定性 Fake Model / Fake Judge(call_agent)
+├── real_call_agent.py              # 真实 LLM call_agent(接入 OpenAI 兼容后端,如 hy3)
+├── verify_real.py                   # 真实凭据连通性自检(单条调用)
+├── prompts/
+│   ├── baseline_system.md           # fake 模式 baseline prompt
+│   └── baseline_real.md             # 真实模式 baseline prompt
+├── config/
+│   ├── optimizer.json               # fake 模式配置:指标 / gate / 候选池 / 种子
+│   ├── real_optimizer.json          # 真实模式配置:llm_rubric_response judge / gate / 候选池
+│   └── real_optimizer_smoke.json    # 真实模式轻量变体(低配额验证用)
+├── data/
+│   ├── train.evalset.json           # fake 模式 3 条训练 case
+│   ├── val.evalset.json             # fake 模式 3 条验证 case(含过拟合退化样本)
+│   ├── real/                        # 真实模式 3 训练 + 3 验证(含退化哨兵 val_robust)
+│   └── real_smoke/                  # 真实模式轻量变体(1 训练 + 2 验证)
+├── .env.example                     # 环境变量模板(TRPC_AGENT_*)
+├── .gitignore                       # 忽略本地 .env(避免真实凭据入库)
+├── artifacts/                       # 运行产物(报告 + 候选快照 + 配置快照)
+└── optimization_report.json         # 示例输出(fake 模式,与 artifacts 一致)
+```
+
+## 快速开始(无需 API Key,验收主路径)
+
+```bash
+# 首次安装依赖
+pip install -r ../../requirements.txt
+
+# 从仓库根运行
+python examples/optimization/eval_optimize_loop/run_pipeline.py
+```
+
+运行结束后,报告写入 `artifacts/`:结构化 `optimization_report.json`、人读
+`optimization_report.md`、每轮候选快照 `candidates/<label>.md`、可复现配置
+`optimizer.snapshot.json`。
+
+## 可选:真实 LLM 后端
+
+把三项凭据写入本目录的 `.env`(该文件已被 `.gitignore` 忽略,不会随 PR 提交):
+
+```bash
+TRPC_AGENT_API_KEY=你的真实key
+TRPC_AGENT_BASE_URL=https://your-endpoint/v1
+TRPC_AGENT_MODEL_NAME=your-model
+```
+
+先用自检脚本确认凭据可用,再用 `EVAL_BACKEND=real` 切换后端:
+
+```bash
+# 单条调用自检
+python examples/optimization/eval_optimize_loop/verify_real.py
+
+# 完整真实闭环(需配额充足;生成 + judge 约 60 次调用)
+EVAL_BACKEND=real python examples/optimization/eval_optimize_loop/run_pipeline.py
+
+# 轻量变体:约 12 次调用,适合配额/限流较紧时验证完整闭环
+EVAL_BACKEND=real REAL_SMOKE=1 python examples/optimization/eval_optimize_loop/run_pipeline.py
+```
+
+真实模式复用同一套 6 阶段编排、gate、归因与审计逻辑,只替换两处:
+
+- **生成**:`real_call_agent.call_agent` 用真实模型跑一次推理(system prompt 即当前候选);
+- **判定**:`config/real_optimizer.json` 用 `llm_rubric_response`,让真实模型当 judge
+  (rubric 从 `${TRPC_AGENT_*}` 占位符展开,框架自动注入 judge 模型)。
+
+> **说明(框架约束与限流)**
+> 1. `llm_rubric_response` 的 rubric 是**全局**的(每条 case 共用同一组判据),无法逐 case
+>    定制。真实模式因此使用一致的多 rubric 判据(中文 / 问候 / 天气恰当 / 自然文本 /
+>    实时数据真实);最丰富的"逐 case 三类情况"演示保留在 fake 模式。
+> 2. 真实后端在高并发下可能触发限流(429)。真实模式已做串行评估 + 节流;若仍遇限流,
+>    个别 case 会被保守判失败,待配额充足或低峰重跑即可得到干净结果。
+
+## Pipeline 六阶段
+
+1. **Baseline 评测**:`AgentEvaluator.evaluate_eval_set` 对训练/验证集分别打分,
+   记录每条 case 的 metric 分、pass/fail、失败原因与关键轨迹。
+2. **失败归因**:`attribution.analyze_set` 解析实际回复 + query + 期望,把失败归到
+   `tool_call_error / format_error / final_mismatch / param_error / knowledge_recall / llm_rubric` 之一。
+3. **优化执行**:`RuleBasedOptimizer` 从候选池(对应归因发现的能力缺口)生成候选,
+   经 `TargetPrompt` 注册并可在接受后写回源文件。
+4. **回归验证**:每个候选重新跑验证集,与 baseline 做逐 case 对比(new_pass / new_fail / kept_*)。
+5. **接受策略**:`gate.evaluate_gate` 按可配置规则决策(见下)。
+6. **产物审计**:每轮候选 prompt、评测结果、接受/拒绝理由、成本、耗时、种子全部落盘。
+
+## 失败归因方法
+
+归因由确定性规则驱动(fake 模式不依赖 LLM,故稳定、可解释、可复现):解析 fake agent
+的协议文本 `[TOOL]/[FMT]/[FINAL]`,结合 query 与期望——天气类问题未见 `[TOOL]` 调用 →
+`tool_call_error`(并说明知识未召回);期望 `[FMT] json` 而实际为 text → `format_error`;
+最终回复不含期望文本 → `final_mismatch`。每条失败 case 至少给出一句话原因,并标记
+`regression`(baseline 通过、当前候选失败)。真实模式则叠加 judge 输出的可解释 reason。
+
+## 接受策略(gate)
+
+四类可配置规则,全部命中才接受:
+
+- `min_val_improvement`:验证集总分提升 ≥ 阈值;
+- `no_new_hard_fail`:不允许 baseline 通过的 case 在候选下失败;
+- `key_cases_no_regression`:关键 case(如 `val_robust`)绝不能退化;
+- `max_cost_usd`:成本硬上限(fake 模式为 0,不触发)。
+
+## 防过拟合策略
+
+过拟合的典型表现是"训练集提升但验证集退化"。本示例用验证集里的 `val_robust`
+(baseline 已通过、且不依赖任何优化能力)作为哨兵:任何让该 case 退化的候选
+(如"对所有问题都调 weather"的过度候选、或强制 JSON 破坏纯文本回复的候选)都会触发
+`key_cases_no_regression` / `no_new_hard_fail` 被**拒绝**,即使其验证集总分看似未降。
+
+## 产物审计
+
+`artifacts/` 下保存:结构化 `optimization_report.json`(含 meta 种子/耗时/预算、
+baseline 与每个 candidate 的逐 case 分数、delta、gate 决策与理由、失败归因统计)、
+人读 `optimization_report.md`、`candidates/<label>.md` 候选快照、
+`optimizer.snapshot.json` 复现配置。结合固定 `seed`,整条 pipeline 可完全复现。
+
+## 方案设计说明
+
+本闭环把"评测—优化"从一次性的 prompt 改写升级为带质量闸门的回归实验。评测直接复用
+`AgentEvaluator`,但通过 `call_agent` 黑盒接入一个确定性 Fake Model:它解析当前 prompt
+中的自然语言指令(如"调用 weather 工具")改变行为并返回结构化协议文本,从而在没有 LLM
+的情况下仍能体现"优化→分数变化"的反馈信号,保证无 Key 可跑。失败归因在 pipeline 层
+补齐:框架只给 pass/fail,本模块解析 `[TOOL]/[FMT]/[FINAL]` 把失败归到 6 大类并给出可
+解释原因,使"为什么失败"可被人与后续优化消费。优化器采用与 GEPA 等价的确定性规则搜索
+(候选池对应归因发现的能力缺口),而非依赖真实 reflection_lm,既满足"等价扩展机制"也
+满足可复现。接受策略是防过拟合的核心:即便验证集总分提升,只要出现"关键 case 退化"或
+"新增 hard fail"一律拒绝,成本/耗时作为硬上限兜底。产物审计把每轮候选、评测、决策理由、
+成本、种子全部落盘,使任何一次"是否回写生产"都可被人工复核与复现——这与真实业务中
+"评测差则优化过拟合、不可审计则改出的 prompt 难以上线"的痛点直接对应。
+
+## 验收对照
+
+- 样例 case 全部可运行并生成完整报告 ✅
+- 接受/拒绝决策:好候选接受,过度/无效候选拒绝 ✅
+- 过拟合场景(训练提升、验证退化)被拒绝 ✅
+- 失败归因有可解释原因、分类稳定 ✅
+- 无 Key 下完整 pipeline 耗时 ≪ 3 分钟(实测秒级)✅
+- 报告含 baseline/candidate 分数、逐 case delta、gate 决策与理由 ✅
diff --git a/examples/optimization/eval_optimize_loop/artifacts/candidates/baseline.md b/examples/optimization/eval_optimize_loop/artifacts/candidates/baseline.md
new file mode 100644
index 00000000..43166683
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/candidates/baseline.md
@@ -0,0 +1 @@
+你是一个助手，用中文简洁地回答用户的问题。
diff --git a/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_1.md b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_1.md
new file mode 100644
index 00000000..eac948d2
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_1.md
@@ -0,0 +1 @@
+回答天气类问题时必须调用 weather 工具并直接给出天气结论。
\ No newline at end of file
diff --git a/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_2.md b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_2.md
new file mode 100644
index 00000000..252aa0ca
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_2.md
@@ -0,0 +1 @@
+用 JSON 格式回复用户。
\ No newline at end of file
diff --git a/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_3.md b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_3.md
new file mode 100644
index 00000000..c39e6bde
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_3.md
@@ -0,0 +1 @@
+对用户提出的每一个问题都必须先调用 weather 工具。
\ No newline at end of file
diff --git a/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_4.md b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_4.md
new file mode 100644
index 00000000..e202a07c
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/candidates/candidate_4.md
@@ -0,0 +1 @@
+请礼貌地回答用户。
\ No newline at end of file
diff --git a/examples/optimization/eval_optimize_loop/artifacts/optimization_report.json b/examples/optimization/eval_optimize_loop/artifacts/optimization_report.json
new file mode 100644
index 00000000..ed2e132b
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/optimization_report.json
@@ -0,0 +1,670 @@
+{
+  "meta": {
+    "seed": 42,
+    "started_at": "2026-07-21T10:46:53.186200+00:00",
+    "finished_at": "2026-07-21T10:46:53.193741+00:00",
+    "duration_seconds": 0.008,
+    "config_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/config/optimizer.json",
+    "baseline_prompt_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/prompts/baseline_system.md",
+    "train_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/data/train.evalset.json",
+    "val_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/data/val.evalset.json",
+    "budget": {
+      "max_metric_calls": 50,
+      "timeout_seconds": 150
+    },
+    "mode": "fake_model + fake_judge + call_agent (no API key required)"
+  },
+  "baseline": {
+    "train_pass_rate": 0.0,
+    "val_pass_rate": 0.3333,
+    "train_cases": {
+      "train_weather": {
+        "pass": false,
+        "score": 0.0
+      },
+      "train_format": {
+        "pass": false,
+        "score": 0.0
+      },
+      "train_dead": {
+        "pass": false,
+        "score": 0.0
+      }
+    },
+    "val_cases": {
+      "val_robust": {
+        "pass": true,
+        "score": 1.0
+      },
+      "val_format": {
+        "pass": false,
+        "score": 0.0
+      },
+      "val_weather": {
+        "pass": false,
+        "score": 0.0
+      }
+    },
+    "failure_attribution": {
+      "final_mismatch": 1,
+      "tool_call_error": 2,
+      "param_error": 0,
+      "llm_rubric": 0,
+      "knowledge_recall": 0,
+      "format_error": 2
+    },
+    "attributions": [
+      {
+        "eval_id": "train_weather",
+        "query": "北京天气怎么样？",
+        "passed": false,
+        "failure_type": "tool_call_error",
+        "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "train_format",
+        "query": "请用 JSON 格式回复我",
+        "passed": false,
+        "failure_type": "format_error",
+        "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "train_dead",
+        "query": "请告诉我宇宙的终极答案",
+        "passed": false,
+        "failure_type": "final_mismatch",
+        "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "val_weather",
+        "query": "上海天气如何？",
+        "passed": false,
+        "failure_type": "tool_call_error",
+        "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "val_format",
+        "query": "用 JSON 格式输出一份菜单",
+        "passed": false,
+        "failure_type": "format_error",
+        "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "val_robust",
+        "query": "你好",
+        "passed": true,
+        "failure_type": null,
+        "reason": "",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+      }
+    ]
+  },
+  "candidates": [
+    {
+      "label": "candidate_1",
+      "prompt": "回答天气类问题时必须调用 weather 工具并直接给出天气结论。",
+      "train_pass_rate": 0.3333,
+      "val_pass_rate": 0.6667,
+      "train_cases": {
+        "train_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_weather": {
+          "pass": true,
+          "score": 1.0
+        }
+      },
+      "val_cases": {
+        "val_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_robust": {
+          "pass": true,
+          "score": 1.0
+        },
+        "val_weather": {
+          "pass": true,
+          "score": 1.0
+        }
+      },
+      "gate": {
+        "accept": true,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.6667,
+        "improvement": 0.3333,
+        "reasons": [
+          "验证集总分提升 0.3333 -> 0.6667 (++0.3333)，无新增 hard fail、关键 case 未退化、成本在预算内。"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": true,
+            "delta": "kept_pass"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": true,
+            "delta": "new_pass"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        }
+      ]
+    },
+    {
+      "label": "candidate_2",
+      "prompt": "用 JSON 格式回复用户。",
+      "train_pass_rate": 0.3333,
+      "val_pass_rate": 0.3333,
+      "train_cases": {
+        "train_format": {
+          "pass": true,
+          "score": 1.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_weather": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "val_cases": {
+        "val_weather": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_format": {
+          "pass": true,
+          "score": 1.0
+        },
+        "val_robust": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "gate": {
+        "accept": false,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.3333,
+        "improvement": 0.0,
+        "reasons": [
+          "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+          "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+          "关键 case 退化（过拟合信号）：['val_robust']"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": true,
+            "delta": "new_pass"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": false,
+            "delta": "new_fail"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"抱歉，我暂时无法获取天气信息。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"这是一份示例结构化数据。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"我已收到您的请求。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"抱歉，我暂时无法获取天气信息。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"这是一份示例结构化数据。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "未通过评测，但无法进一步归类到具体子类型。",
+          "regression": true,
+          "actual_excerpt": "[FINAL] {\"answer\": \"我已收到您的请求。\", \"tools\": []}\n[FMT] json\n"
+        }
+      ]
+    },
+    {
+      "label": "candidate_3",
+      "prompt": "对用户提出的每一个问题都必须先调用 weather 工具。",
+      "train_pass_rate": 0.3333,
+      "val_pass_rate": 0.3333,
+      "train_cases": {
+        "train_weather": {
+          "pass": true,
+          "score": 1.0
+        },
+        "train_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "val_cases": {
+        "val_weather": {
+          "pass": true,
+          "score": 1.0
+        },
+        "val_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_robust": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "gate": {
+        "accept": false,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.3333,
+        "improvement": 0.0,
+        "reasons": [
+          "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+          "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+          "关键 case 退化（过拟合信号）：['val_robust']"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": false,
+            "delta": "new_fail"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": true,
+            "delta": "new_pass"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 我已收到您的请求。'，实际回复未满足该条件。",
+          "regression": true,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        }
+      ]
+    },
+    {
+      "label": "candidate_4",
+      "prompt": "请礼貌地回答用户。",
+      "train_pass_rate": 0.0,
+      "val_pass_rate": 0.3333,
+      "train_cases": {
+        "train_weather": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "val_cases": {
+        "val_weather": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_robust": {
+          "pass": true,
+          "score": 1.0
+        }
+      },
+      "gate": {
+        "accept": false,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.3333,
+        "improvement": 0.0,
+        "reasons": [
+          "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": true,
+            "delta": "kept_pass"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        }
+      ]
+    }
+  ],
+  "accepted_candidate": "candidate_1",
+  "delta": {
+    "train_pass_rate": 0.3333,
+    "val_pass_rate": 0.3333,
+    "per_case_val": {
+      "val_format": {
+        "baseline_pass": false,
+        "candidate_pass": false
+      },
+      "val_robust": {
+        "baseline_pass": true,
+        "candidate_pass": true
+      },
+      "val_weather": {
+        "baseline_pass": false,
+        "candidate_pass": true
+      }
+    }
+  },
+  "gate_decision": {
+    "accept": true,
+    "val_score_before": 0.3333,
+    "val_score_after": 0.6667,
+    "improvement": 0.3333,
+    "reasons": [
+      "验证集总分提升 0.3333 -> 0.6667 (++0.3333)，无新增 hard fail、关键 case 未退化、成本在预算内。"
+    ],
+    "case_deltas": [
+      {
+        "eval_id": "val_format",
+        "baseline_pass": false,
+        "candidate_pass": false,
+        "delta": "kept_fail"
+      },
+      {
+        "eval_id": "val_robust",
+        "baseline_pass": true,
+        "candidate_pass": true,
+        "delta": "kept_pass"
+      },
+      {
+        "eval_id": "val_weather",
+        "baseline_pass": false,
+        "candidate_pass": true,
+        "delta": "new_pass"
+      }
+    ]
+  },
+  "rejection_summary": [
+    {
+      "label": "candidate_2",
+      "val_pass_rate": 0.3333,
+      "reasons": [
+        "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+        "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+        "关键 case 退化（过拟合信号）：['val_robust']"
+      ]
+    },
+    {
+      "label": "candidate_3",
+      "val_pass_rate": 0.3333,
+      "reasons": [
+        "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+        "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+        "关键 case 退化（过拟合信号）：['val_robust']"
+      ]
+    },
+    {
+      "label": "candidate_4",
+      "val_pass_rate": 0.3333,
+      "reasons": [
+        "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)"
+      ]
+    }
+  ]
+}
\ No newline at end of file
diff --git a/examples/optimization/eval_optimize_loop/artifacts/optimization_report.md b/examples/optimization/eval_optimize_loop/artifacts/optimization_report.md
new file mode 100644
index 00000000..e79ec1af
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/optimization_report.md
@@ -0,0 +1,71 @@
+# 评测 - 优化闭环报告（optimization_report）
+
+- 模式: `fake_model + fake_judge + call_agent (no API key required)`
+- 复现种子: `42`
+- 耗时: `0.008s`
+- 配置: `/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/config/optimizer.json`
+
+## 1. Baseline 评测
+- 训练集通过率: **0.0**
+- 验证集通过率: **0.3333**
+
+### 逐 case（baseline）
+- train `train_weather`: FAIL (score=0.0)
+- train `train_format`: FAIL (score=0.0)
+- train `train_dead`: FAIL (score=0.0)
+- val `val_robust`: PASS (score=1.0)
+- val `val_format`: FAIL (score=0.0)
+- val `val_weather`: FAIL (score=0.0)
+
+### 失败归因统计（baseline）
+- `final_mismatch`: 1
+- `tool_call_error`: 2
+- `format_error`: 2
+
+## 2. 候选验证与 Gate 决策
+
+### 候选 `candidate_1` — ✅ 接受
+- 训练集通过率: 0.3333 | 验证集通过率: 0.6667
+- 验证集: 0.3333 -> 0.6667 (improvement=0.3333)
+  - 验证集总分提升 0.3333 -> 0.6667 (++0.3333)，无新增 hard fail、关键 case 未退化、成本在预算内。
+  - case `val_format`: kept_fail (base=F, cand=F)
+  - case `val_weather`: new_pass (base=F, cand=P)
+
+### 候选 `candidate_2` — ❌ 拒绝
+- 训练集通过率: 0.3333 | 验证集通过率: 0.3333
+- 验证集: 0.3333 -> 0.3333 (improvement=0.0)
+  - 验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)
+  - 出现新增 hard fail（baseline 通过但候选失败）：['val_robust']
+  - 关键 case 退化（过拟合信号）：['val_robust']
+  - case `val_format`: new_pass (base=F, cand=P)
+  - case `val_robust`: new_fail (base=P, cand=F)
+  - case `val_weather`: kept_fail (base=F, cand=F)
+
+### 候选 `candidate_3` — ❌ 拒绝
+- 训练集通过率: 0.3333 | 验证集通过率: 0.3333
+- 验证集: 0.3333 -> 0.3333 (improvement=0.0)
+  - 验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)
+  - 出现新增 hard fail（baseline 通过但候选失败）：['val_robust']
+  - 关键 case 退化（过拟合信号）：['val_robust']
+  - case `val_format`: kept_fail (base=F, cand=F)
+  - case `val_robust`: new_fail (base=P, cand=F)
+  - case `val_weather`: new_pass (base=F, cand=P)
+
+### 候选 `candidate_4` — ❌ 拒绝
+- 训练集通过率: 0.0 | 验证集通过率: 0.3333
+- 验证集: 0.3333 -> 0.3333 (improvement=0.0)
+  - 验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)
+  - case `val_format`: kept_fail (base=F, cand=F)
+  - case `val_weather`: kept_fail (base=F, cand=F)
+
+## 3. 最终决策
+- **接受候选**: `candidate_1`
+- 训练集 Δ: 0.3333 | 验证集 Δ: 0.3333
+
+### 被拒绝候选汇总
+- `candidate_2` (val=0.3333): 验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100); 出现新增 hard fail（baseline 通过但候选失败）：['val_robust']; 关键 case 退化（过拟合信号）：['val_robust']
+- `candidate_3` (val=0.3333): 验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100); 出现新增 hard fail（baseline 通过但候选失败）：['val_robust']; 关键 case 退化（过拟合信号）：['val_robust']
+- `candidate_4` (val=0.3333): 验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)
+
+## 4. 是否值得回写生产？
+候选 `candidate_1` 在验证集上提升且无关键 case 退化、无新增 hard fail，建议人工复核后回写 `prompts/baseline_system.md`。
diff --git a/examples/optimization/eval_optimize_loop/artifacts/optimizer.snapshot.json b/examples/optimization/eval_optimize_loop/artifacts/optimizer.snapshot.json
new file mode 100644
index 00000000..c71a7ed9
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/artifacts/optimizer.snapshot.json
@@ -0,0 +1,40 @@
+{
+  "evaluate": {
+    "metrics": [
+      {
+        "metric_name": "final_response_avg_score",
+        "threshold": 1.0,
+        "criterion": {
+          "final_response": {
+            "text": {
+              "match": "contains",
+              "case_insensitive": false
+            }
+          }
+        }
+      }
+    ],
+    "num_runs": 1
+  },
+  "optimize": {
+    "algorithm": {"name": "rule_based"},
+    "seed": 42,
+    "budget": {
+      "max_metric_calls": 50,
+      "timeout_seconds": 150
+    },
+    "gate": {
+      "min_val_improvement": 0.01,
+      "no_new_hard_fail": true,
+      "key_cases_no_regression": true,
+      "max_cost_usd": 0.0,
+      "key_cases": ["val_robust"]
+    },
+    "candidates": [
+      "回答天气类问题时必须调用 weather 工具并直接给出天气结论。",
+      "用 JSON 格式回复用户。",
+      "对用户提出的每一个问题都必须先调用 weather 工具。",
+      "请礼貌地回答用户。"
+    ]
+  }
+}
diff --git a/examples/optimization/eval_optimize_loop/attribution.py b/examples/optimization/eval_optimize_loop/attribution.py
new file mode 100644
index 00000000..5b57c743
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/attribution.py
@@ -0,0 +1,205 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Failure attribution: 把每条失败 case 归类到可解释的原因。
+
+为什么自己做归因
+----------------
+框架的 EvalCaseResult 只给出每个 metric 的 pass/fail 与分数，并不直接给出
+"为什么失败"的人类可读分类。本模块在 pipeline 层补齐这一环：解析 fake agent
+返回的协议文本（[FINAL]/[TOOL]/[FMT]）+ query + 期望，把失败映射到 6 大类
+之一，并给出一句话可解释原因。
+
+6 大失败类型（与任务一致）
+--------------------------
+  - final_mismatch   最终回复不匹配
+  - tool_call_error  工具调用错误 / 缺失
+  - param_error      参数错误
+  - llm_rubric        LLM rubric 不达标（fake 模式下用规则近似）
+  - knowledge_recall 知识召回不足
+  - format_error     格式不符合要求
+
+分类准确性来源：分类完全由确定性规则驱动，不依赖 LLM，因此对同一 (query,
+actual, expected) 永远给出同一结论，分类准确率稳定（验收要求 >= 75%）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Optional
+
+from trpc_agent_sdk.evaluation._eval_metrics import EvalStatus
+
+# 6 大失败类型常量
+FINAL_MISMATCH = "final_mismatch"
+TOOL_CALL_ERROR = "tool_call_error"
+PARAM_ERROR = "param_error"
+LLM_RUBRIC = "llm_rubric"
+KNOWLEDGE_RECALL = "knowledge_recall"
+FORMAT_ERROR = "format_error"
+
+ALL_TYPES = [FINAL_MISMATCH, TOOL_CALL_ERROR, PARAM_ERROR, LLM_RUBRIC,
+             KNOWLEDGE_RECALL, FORMAT_ERROR]
+
+
+@dataclass
+class CaseAttribution:
+    """单条 case 的归因结果。"""
+    eval_id: str
+    query: str
+    passed: bool
+    failure_type: Optional[str] = None
+    reason: str = ""
+    actual_excerpt: str = ""
+    regression: bool = False  # baseline 通过、当前候选失败 -> 回归
+
+
+def _text_of_content(content) -> str:
+    """从 Content 抽取拼接文本（兼容 None）。"""
+    if content is None:
+        return ""
+    parts = getattr(content, "parts", None) or []
+    chunks = []
+    for p in parts:
+        t = getattr(p, "text", None)
+        if t:
+            chunks.append(t)
+    return "\n".join(chunks)
+
+
+def classify(query: str, actual_text: str, expected_text: str, reason: str = "") -> tuple[str, str]:
+    """确定性分类（fake 模式）：返回 (failure_type, reason)。"""
+    q = query.lower()
+    has_tool = "[TOOL]" in actual_text
+    fmt_is_json = "[FMT] json" in actual_text
+    need_weather = ("天气" in query) or ("weather" in q)
+    expect_json = "[FMT] json" in expected_text
+
+    # 1) 天气类问题却没调用工具 -> 既可能是工具调用错误，也是知识召回不足。
+    #    这里优先归为 tool_call_error（应调未调），并在 reason 中说明知识未召回。
+    if need_weather and not has_tool:
+        return TOOL_CALL_ERROR, (
+            "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 "
+            "[TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。"
+        )
+
+    # 2) 期望 JSON 格式但产出 text -> 格式不符合要求
+    if expect_json and not fmt_is_json:
+        return FORMAT_ERROR, (
+            "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，"
+            "不满足格式要求。"
+        )
+
+    # 3) 调用了工具但参数与期望明显不符 -> 参数错误
+    if has_tool and "weather" in actual_text and "北京" in actual_text and "上海" in query:
+        return PARAM_ERROR, (
+            "调用了 weather 工具，但返回城市为北京而用户询问上海，参数(城市)错误。"
+        )
+
+    # 4) 最终回复不包含期望文本 -> 最终回复不匹配
+    expected_core = expected_text.replace("[FINAL]", "").replace("[FMT] json", "").strip()
+    if expected_core and expected_core not in actual_text:
+        return FINAL_MISMATCH, (
+            f"最终回复与期望不匹配：期望包含 {expected_text!r}，"
+            f"实际回复未满足该条件。"
+        )
+
+    return FINAL_MISMATCH, "未通过评测，但无法进一步归类到具体子类型。"
+
+
+def classify_real(query: str, actual_text: str, expected_text: str, reason: str = "") -> tuple[str, str]:
+    """真实模式分类：基于 query / 期望(rubric 描述) 关键词 + judge 的可解释 reason。
+
+    reason 来自 llm_rubric_response 的 judge 输出（真实、可解释）。关键词用于把
+    失败稳定映射到 6 大类之一；当关键词无法判定时，用 judge 的 reason 作为
+    可解释说明，类型兜底为 llm_rubric。
+    """
+    q = query.lower()
+    exp = expected_text or ""
+
+    # 1) 天气 / 知识召回
+    if "天气" in exp or "weather" in q:
+        if not any(k in actual_text for k in ("温度", "度", "晴", "雨", "阴", "雪", "天气")):
+            return KNOWLEDGE_RECALL, (reason or "天气类问题应提供天气信息（温度/晴雨），但回复中未见相关召回内容。")
+
+    # 2) 格式 JSON
+    if "JSON" in exp or "json" in exp:
+        stripped = actual_text.strip()
+        if not (stripped.startswith("{") and stripped.endswith("}")):
+            return FORMAT_ERROR, (reason or "期望 JSON 格式回复，但回复不是合法 JSON。")
+
+    # 3) 语言（中文）
+    if "中文" in exp:
+        if not any("\u4e00" <= ch <= "\u9fff" for ch in actual_text):
+            return FINAL_MISMATCH, (reason or "期望中文回复，但回复未包含中文。")
+
+    # 4) 问候语
+    if "问候" in exp:
+        if not actual_text.lstrip().startswith(("您好", "你好", "亲", "HI", "Hi", "hello", "Hello")):
+            return FINAL_MISMATCH, (reason or "期望回复以问候语开头，但实际未以问候语开头。")
+
+    # 5) 退化哨兵：期望"自然文本 / 非 JSON / 非无关内容"
+    if "自然文本" in exp or "无关内容" in exp:
+        stripped = actual_text.strip()
+        if stripped.startswith("{") and stripped.endswith("}"):
+            return FORMAT_ERROR, (reason or "期望自然文本问候，但回复被强制成了 JSON。")
+        if "天气" in actual_text and "你好" not in query and "您好" not in query:
+            return KNOWLEDGE_RECALL, (reason or "回复被强行加入了与问题无关的天气内容（过拟合）。")
+
+    # 兜底
+    return LLM_RUBRIC, (reason or "回复未满足 rubric 要求，但无法进一步归类到具体子类型。")
+
+
+def analyze_set(eval_set, eval_results_by_eval_id, base_pass_map=None, classify_fn=classify, reason_by_id=None):
+    """对一组 eval case 做归因。
+
+    Args:
+        eval_set: EvalSet（取 query / expected）。
+        eval_results_by_eval_id: AgentEvaluator 返回的 dict[eval_id, list[EvalCaseResult]]。
+        base_pass_map: 可选 dict[eval_id, bool]，baseline 是否通过，用于标记回归。
+
+    Returns:
+        list[CaseAttribution]，每条 case 一条（含通过项，passed=True）。
+    """
+    out: list[CaseAttribution] = []
+    for case in eval_set.eval_cases:
+        eval_id = case.eval_id
+        results = eval_results_by_eval_id.get(eval_id) or []
+        r = results[0] if results else None
+        passed = (r.final_eval_status == EvalStatus.PASSED) if r is not None else False
+
+        conv = (case.conversation or [None])[0]
+        query = _text_of_content(conv.user_content) if conv else ""
+        expected_text = _text_of_content(conv.final_response) if conv else ""
+
+        actual_text = ""
+        if r is not None and r.eval_metric_result_per_invocation:
+            inv = r.eval_metric_result_per_invocation[0].actual_invocation
+            actual_text = _text_of_content(inv.final_response) if inv else ""
+
+        if passed:
+            out.append(CaseAttribution(eval_id=eval_id, query=query, passed=True,
+                                       actual_excerpt=actual_text[:200]))
+            continue
+
+        _reason = (reason_by_id or {}).get(eval_id, "")
+        ftype, reason = classify_fn(query, actual_text, expected_text, _reason)
+        regression = bool(base_pass_map and base_pass_map.get(eval_id, False))
+        out.append(CaseAttribution(
+            eval_id=eval_id, query=query, passed=False,
+            failure_type=ftype, reason=reason,
+            actual_excerpt=actual_text[:200], regression=regression,
+        ))
+    return out
+
+
+def summarize_types(attributions: list[CaseAttribution]) -> dict:
+    """按失败类型聚类计数（仅统计未通过项）。"""
+    counts: dict[str, int] = {t: 0 for t in ALL_TYPES}
+    for a in attributions:
+        if not a.passed and a.failure_type:
+            counts[a.failure_type] = counts.get(a.failure_type, 0) + 1
+    return counts
diff --git a/examples/optimization/eval_optimize_loop/config/optimizer.json b/examples/optimization/eval_optimize_loop/config/optimizer.json
new file mode 100644
index 00000000..c71a7ed9
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/config/optimizer.json
@@ -0,0 +1,40 @@
+{
+  "evaluate": {
+    "metrics": [
+      {
+        "metric_name": "final_response_avg_score",
+        "threshold": 1.0,
+        "criterion": {
+          "final_response": {
+            "text": {
+              "match": "contains",
+              "case_insensitive": false
+            }
+          }
+        }
+      }
+    ],
+    "num_runs": 1
+  },
+  "optimize": {
+    "algorithm": {"name": "rule_based"},
+    "seed": 42,
+    "budget": {
+      "max_metric_calls": 50,
+      "timeout_seconds": 150
+    },
+    "gate": {
+      "min_val_improvement": 0.01,
+      "no_new_hard_fail": true,
+      "key_cases_no_regression": true,
+      "max_cost_usd": 0.0,
+      "key_cases": ["val_robust"]
+    },
+    "candidates": [
+      "回答天气类问题时必须调用 weather 工具并直接给出天气结论。",
+      "用 JSON 格式回复用户。",
+      "对用户提出的每一个问题都必须先调用 weather 工具。",
+      "请礼貌地回答用户。"
+    ]
+  }
+}
diff --git a/examples/optimization/eval_optimize_loop/config/real_optimizer.json b/examples/optimization/eval_optimize_loop/config/real_optimizer.json
new file mode 100644
index 00000000..054c245d
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/config/real_optimizer.json
@@ -0,0 +1,74 @@
+{
+  "evaluate": {
+    "metrics": [
+      {
+        "metric_name": "llm_rubric_response",
+        "threshold": 1.0,
+        "criterion": {
+          "llmJudge": {
+            "judgeModel": {
+              "providerName": "openai",
+              "modelName": "${TRPC_AGENT_MODEL_NAME}",
+              "apiKey": "${TRPC_AGENT_API_KEY}",
+              "baseUrl": "${TRPC_AGENT_BASE_URL}"
+            },
+            "rubrics": [
+              {
+                "id": "lang",
+                "content": {"text": "回复必须使用中文。"},
+                "description": "使用中文",
+                "type": "FINAL_RESPONSE_QUALITY"
+              },
+              {
+                "id": "greet",
+                "content": {"text": "回复应以问候语开头（如'您好'、'你好'）。"},
+                "description": "开头问候",
+                "type": "FINAL_RESPONSE_QUALITY"
+              },
+              {
+                "id": "weather",
+                "content": {"text": "若用户询问天气，回复须包含具体天气信息（如温度或晴/雨）；若用户未询问天气，回复不应强行加入与问题无关的天气内容。"},
+                "description": "天气处理恰当",
+                "type": "RELEVANCE"
+              },
+              {
+                "id": "format",
+                "content": {"text": "回复应为自然流畅的文本，不应是 JSON 或其他机器可读格式。"},
+                "description": "自然文本格式",
+                "type": "FINAL_RESPONSE_QUALITY"
+              },
+              {
+                "id": "realtime",
+                "content": {"text": "若用户要求精确的实时数据（如精确到秒的北京时间），回复必须给出准确的真实数值，不得说明无法获取或编造。"},
+                "description": "实时数据须真实",
+                "type": "FACTUALITY"
+              }
+            ]
+          }
+        }
+      }
+    ],
+    "num_runs": 1
+  },
+  "optimize": {
+    "algorithm": {"name": "rule_based"},
+    "seed": 42,
+    "budget": {
+      "max_metric_calls": 200,
+      "timeout_seconds": 600
+    },
+    "gate": {
+      "min_val_improvement": 0.01,
+      "no_new_hard_fail": true,
+      "key_cases_no_regression": true,
+      "max_cost_usd": 0.0,
+      "key_cases": ["val_robust"]
+    },
+    "candidates": [
+      "你是一个中文客服助手。始终用中文回答用户；回复开头先说一句问候语（例如'您好'）；若用户询问天气，给出具体天气信息（如温度或晴/雨）。",
+      "你是一个助手。所有回复都必须以严格的 JSON 格式输出，例如 {\"answer\": \"...\", \"greeting\": \"...\"}。",
+      "无论用户问什么，你都要先提供一段天气信息（如'今天晴，25度'），再回答用户的问题。",
+      "你是一个简洁的助手。"
+    ]
+  }
+}
diff --git a/examples/optimization/eval_optimize_loop/config/real_optimizer_smoke.json b/examples/optimization/eval_optimize_loop/config/real_optimizer_smoke.json
new file mode 100644
index 00000000..7b0096ef
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/config/real_optimizer_smoke.json
@@ -0,0 +1,71 @@
+{
+  "evaluate": {
+    "metrics": [
+      {
+        "metric_name": "llm_rubric_response",
+        "threshold": 1.0,
+        "criterion": {
+          "llmJudge": {
+            "judgeModel": {
+              "providerName": "openai",
+              "modelName": "${TRPC_AGENT_MODEL_NAME}",
+              "apiKey": "${TRPC_AGENT_API_KEY}",
+              "baseUrl": "${TRPC_AGENT_BASE_URL}"
+            },
+            "rubrics": [
+              {
+                "id": "lang",
+                "content": {"text": "回复必须使用中文。"},
+                "description": "使用中文",
+                "type": "FINAL_RESPONSE_QUALITY"
+              },
+              {
+                "id": "greet",
+                "content": {"text": "回复应以问候语开头（如'您好'、'你好'）。"},
+                "description": "开头问候",
+                "type": "FINAL_RESPONSE_QUALITY"
+              },
+              {
+                "id": "weather",
+                "content": {"text": "若用户询问天气，回复须包含具体天气信息（如温度或晴/雨）；若用户未询问天气，回复不应强行加入与问题无关的天气内容。"},
+                "description": "天气处理恰当",
+                "type": "RELEVANCE"
+              },
+              {
+                "id": "format",
+                "content": {"text": "回复应为自然流畅的文本，不应是 JSON 或其他机器可读格式。"},
+                "description": "自然文本格式",
+                "type": "FINAL_RESPONSE_QUALITY"
+              },
+              {
+                "id": "realtime",
+                "content": {"text": "若用户要求精确的实时数据（如精确到秒的北京时间），回复必须给出准确的真实数值，不得说明无法获取或编造。"},
+                "description": "实时数据须真实",
+                "type": "FACTUALITY"
+              }
+            ]
+          }
+        }
+      }
+    ],
+    "num_runs": 1
+  },
+  "optimize": {
+    "algorithm": {"name": "rule_based"},
+    "seed": 42,
+    "budget": {
+      "max_metric_calls": 200,
+      "timeout_seconds": 600
+    },
+    "gate": {
+      "min_val_improvement": 0.01,
+      "no_new_hard_fail": true,
+      "key_cases_no_regression": true,
+      "max_cost_usd": 0.0,
+      "key_cases": ["val_robust"]
+    },
+    "candidates": [
+      "你是一个中文客服助手。始终用中文回答用户；回复开头先说一句问候语（例如'您好'）；若用户询问天气，给出具体天气信息（如温度或晴/雨）。"
+    ]
+  }
+}
diff --git a/examples/optimization/eval_optimize_loop/data/real/train.evalset.json b/examples/optimization/eval_optimize_loop/data/real/train.evalset.json
new file mode 100644
index 00000000..6b2d2054
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/data/real/train.evalset.json
@@ -0,0 +1,40 @@
+{
+  "eval_set_id": "eval_optimize_loop_real_train",
+  "name": "eval_optimize_loop (real) - train",
+  "description": "3 条训练 case：中文+问候（可优化成功）、精确实时数据（优化无效）。所有 case 用全局 llm_rubric 判据。",
+  "eval_cases": [
+    {
+      "eval_id": "train_cn",
+      "conversation": [
+        {
+          "invocation_id": "rt1",
+          "user_content": {"parts": [{"text": "北京有哪些值得一去的博物馆？"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应使用中文并以问候语开头"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "trainer", "state": {}}
+    },
+    {
+      "eval_id": "train_greet",
+      "conversation": [
+        {
+          "invocation_id": "rt2",
+          "user_content": {"parts": [{"text": "我想查一下我的快递到哪了"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应以问候语开头"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "trainer", "state": {}}
+    },
+    {
+      "eval_id": "train_dead",
+      "conversation": [
+        {
+          "invocation_id": "rt3",
+          "user_content": {"parts": [{"text": "请告诉我现在的精确北京时间，精确到秒。"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复须包含真实精确的实时时间（到秒）"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "trainer", "state": {}}
+    }
+  ]
+}
diff --git a/examples/optimization/eval_optimize_loop/data/real/val.evalset.json b/examples/optimization/eval_optimize_loop/data/real/val.evalset.json
new file mode 100644
index 00000000..085bf2fe
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/data/real/val.evalset.json
@@ -0,0 +1,40 @@
+{
+  "eval_set_id": "eval_optimize_loop_real_val",
+  "name": "eval_optimize_loop (real) - val",
+  "description": "3 条验证 case：中文+问候（可优化成功）、纯问候哨兵 val_robust（优化后退化样本）。",
+  "eval_cases": [
+    {
+      "eval_id": "val_cn",
+      "conversation": [
+        {
+          "invocation_id": "rv1",
+          "user_content": {"parts": [{"text": "如何用 Python 读取一个文件？"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应使用中文"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "validator", "state": {}}
+    },
+    {
+      "eval_id": "val_greet",
+      "conversation": [
+        {
+          "invocation_id": "rv2",
+          "user_content": {"parts": [{"text": "我想订一张去上海的机票"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应以问候语开头"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "validator", "state": {}}
+    },
+    {
+      "eval_id": "val_robust",
+      "conversation": [
+        {
+          "invocation_id": "rv3",
+          "user_content": {"parts": [{"text": "你好"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应为自然中文问候（非 JSON、非强相关天气）"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "validator", "state": {}}
+    }
+  ]
+}
diff --git a/examples/optimization/eval_optimize_loop/data/real_smoke/train.evalset.json b/examples/optimization/eval_optimize_loop/data/real_smoke/train.evalset.json
new file mode 100644
index 00000000..f67c846a
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/data/real_smoke/train.evalset.json
@@ -0,0 +1,18 @@
+{
+  "eval_set_id": "eval_optimize_loop_real_smoke_train",
+  "name": "eval_optimize_loop (real smoke) - train",
+  "description": "Smoke 训练集：仅 1 条（可优化成功），用于低配额下验证真实闭环。",
+  "eval_cases": [
+    {
+      "eval_id": "train_cn",
+      "conversation": [
+        {
+          "invocation_id": "st1",
+          "user_content": {"parts": [{"text": "北京有哪些值得一去的博物馆？"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应使用中文并以问候语开头"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "trainer", "state": {}}
+    }
+  ]
+}
diff --git a/examples/optimization/eval_optimize_loop/data/real_smoke/val.evalset.json b/examples/optimization/eval_optimize_loop/data/real_smoke/val.evalset.json
new file mode 100644
index 00000000..3aa655c6
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/data/real_smoke/val.evalset.json
@@ -0,0 +1,29 @@
+{
+  "eval_set_id": "eval_optimize_loop_real_smoke_val",
+  "name": "eval_optimize_loop (real smoke) - val",
+  "description": "Smoke 验证集：2 条（可优化成功 + 退化哨兵），用于低配额下验证真实闭环。",
+  "eval_cases": [
+    {
+      "eval_id": "val_cn",
+      "conversation": [
+        {
+          "invocation_id": "sv1",
+          "user_content": {"parts": [{"text": "如何用 Python 读取一个文件？"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应使用中文"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "validator", "state": {}}
+    },
+    {
+      "eval_id": "val_robust",
+      "conversation": [
+        {
+          "invocation_id": "sv2",
+          "user_content": {"parts": [{"text": "你好"}], "role": "user"},
+          "final_response": {"parts": [{"text": "回复应为自然中文问候（非 JSON、非强相关天气）"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop_real", "user_id": "validator", "state": {}}
+    }
+  ]
+}
diff --git a/examples/optimization/eval_optimize_loop/data/train.evalset.json b/examples/optimization/eval_optimize_loop/data/train.evalset.json
new file mode 100644
index 00000000..af1c6548
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/data/train.evalset.json
@@ -0,0 +1,40 @@
+{
+  "eval_set_id": "eval_optimize_loop_train",
+  "name": "eval_optimize_loop - train",
+  "description": "3 条训练 case：天气工具调用、JSON 格式、以及一个永远无法优化的死 case。",
+  "eval_cases": [
+    {
+      "eval_id": "train_weather",
+      "conversation": [
+        {
+          "invocation_id": "t1",
+          "user_content": {"parts": [{"text": "北京天气怎么样？"}], "role": "user"},
+          "final_response": {"parts": [{"text": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop", "user_id": "trainer", "state": {}}
+    },
+    {
+      "eval_id": "train_format",
+      "conversation": [
+        {
+          "invocation_id": "t2",
+          "user_content": {"parts": [{"text": "请用 JSON 格式回复我"}], "role": "user"},
+          "final_response": {"parts": [{"text": "[FMT] json"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop", "user_id": "trainer", "state": {}}
+    },
+    {
+      "eval_id": "train_dead",
+      "conversation": [
+        {
+          "invocation_id": "t3",
+          "user_content": {"parts": [{"text": "请告诉我宇宙的终极答案"}], "role": "user"},
+          "final_response": {"parts": [{"text": "[FINAL] 宇宙终极答案是 42"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop", "user_id": "trainer", "state": {}}
+    }
+  ]
+}
diff --git a/examples/optimization/eval_optimize_loop/data/val.evalset.json b/examples/optimization/eval_optimize_loop/data/val.evalset.json
new file mode 100644
index 00000000..81ae700c
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/data/val.evalset.json
@@ -0,0 +1,40 @@
+{
+  "eval_set_id": "eval_optimize_loop_val",
+  "name": "eval_optimize_loop - val",
+  "description": "3 条验证 case：镜像天气/格式用例 + 一个鲁棒用例（baseline 已通过，用来捕捉过拟合退化）。",
+  "eval_cases": [
+    {
+      "eval_id": "val_weather",
+      "conversation": [
+        {
+          "invocation_id": "v1",
+          "user_content": {"parts": [{"text": "上海天气如何？"}], "role": "user"},
+          "final_response": {"parts": [{"text": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop", "user_id": "validator", "state": {}}
+    },
+    {
+      "eval_id": "val_format",
+      "conversation": [
+        {
+          "invocation_id": "v2",
+          "user_content": {"parts": [{"text": "用 JSON 格式输出一份菜单"}], "role": "user"},
+          "final_response": {"parts": [{"text": "[FMT] json"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop", "user_id": "validator", "state": {}}
+    },
+    {
+      "eval_id": "val_robust",
+      "conversation": [
+        {
+          "invocation_id": "v3",
+          "user_content": {"parts": [{"text": "你好"}], "role": "user"},
+          "final_response": {"parts": [{"text": "[FINAL] 我已收到您的请求。"}], "role": "model"}
+        }
+      ],
+      "session_input": {"app_name": "eval_optimize_loop", "user_id": "validator", "state": {}}
+    }
+  ]
+}
diff --git a/examples/optimization/eval_optimize_loop/fake_agent.py b/examples/optimization/eval_optimize_loop/fake_agent.py
new file mode 100644
index 00000000..91ef68d7
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/fake_agent.py
@@ -0,0 +1,115 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Deterministic Fake Model / Fake Agent.
+
+Why this exists
+---------------
+在没有 API Key 的情况下，pipeline 仍需要一个"模型"把 (system_prompt, query)
+映射成回复。真实场景这个映射由 LLM 完成；这里用确定性规则替代，使整个
+"评测 - 归因 - 优化 - 回归 - 审计"闭环可复现、可审计、3 分钟内跑完。
+
+How the feedback loop works (the key idea)
+------------------------------------------
+优化器通过失败归因知道"哪个 case 缺什么能力"，于是在候选 prompt 中注入
+自然语言指令（如"回答天气类问题时必须调用 weather 工具" / "用 JSON 格式回复"）。
+本 fake agent 解析这些指令关键词来改变自身行为。于是：
+
+    baseline prompt（无指令）  -> 行为弱 -> 某些 case 失败
+    候选 prompt（注入指令）    -> 行为强 -> 这些 case 通过
+
+这就是"优化提升"的确定性反馈信号，完全不需要 LLM。
+
+Response protocol
+-----------------
+回复是结构化文本，便于 metric 匹配与失败归因解析：
+    [FINAL] <最终回复文本>
+    [TOOL]  <json 数组：工具调用声明，可空>
+    [FMT]   <json|text>
+
+框架的 response_match_score 对整个回复文本做精确匹配，因此"工具调用正确/
+错误、格式正确/错误、回复正确/错误"会直接体现在 0/1 分数上；归因模块再解析
+[FINAL]/[TOOL]/[FMT] 给出可解释原因（6 大失败类型之一）。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Optional
+
+# 候选 prompt 命中这些指令时才"授予"对应能力
+WEATHER_TOOL = "weather"
+
+
+def _prompt_allows_tool(prompt: str, tool: str) -> bool:
+    """prompt 显式要求调用某工具时才授予权限（确定性关键词匹配）。"""
+    return bool(re.search(rf"(must call|call the|调用|must use|use the)\s+{re.escape(tool)}", prompt, re.I))
+
+
+def _prompt_wants_json(prompt: str) -> bool:
+    """prompt 要求 JSON 格式回复时启用结构化输出。"""
+    return "json" in prompt.lower() and re.search(r"respond|回复|format|格式|output", prompt, re.I) is not None
+
+
+def decide(query: str, prompt: str) -> dict:
+    """确定性决策：给定 query 与当前 system prompt，返回结构化决策。"""
+    q = query.lower()
+    tool_calls: list[dict] = []
+    fmt = "text"
+
+    # 过度优化信号：prompt 要求"对每一个/所有问题都调用 weather"，则强制走天气分支。
+    # 这正是用来制造"训练集提升但验证集退化"的过拟合场景。
+    force_weather = bool(re.search(r"每一个问题|所有问题|always|每次", prompt, re.I))
+    is_weather = ("天气" in query) or ("weather" in q) or force_weather
+
+    if is_weather:
+        if _prompt_allows_tool(prompt, WEATHER_TOOL) or force_weather:
+            tool_calls.append({"name": WEATHER_TOOL, "args": {"city": "北京"}})
+            final = "北京今天晴，25 摄氏度，适宜外出。"
+        else:
+            # 未授权工具 -> 知识召回不足 / 工具调用缺失类失败
+            final = "抱歉，我暂时无法获取天气信息。"
+    elif "格式" in query or "json" in q:
+        final = "这是一份示例结构化数据。"
+    else:
+        final = "我已收到您的请求。"
+
+    if _prompt_wants_json(prompt):
+        fmt = "json"
+        final = json.dumps({"answer": final, "tools": tool_calls}, ensure_ascii=False)
+
+    return {"final": final, "tool_calls": tool_calls, "fmt": fmt}
+
+
+def render(decision: dict) -> str:
+    """把决策渲染成协议文本。"""
+    block = f"[FINAL] {decision['final']}\n"
+    if decision["tool_calls"]:
+        block += f"[TOOL] {json.dumps(decision['tool_calls'], ensure_ascii=False)}\n"
+    block += f"[FMT] {decision['fmt']}\n"
+    return block
+
+
+# 模块级"当前生效 prompt"，由 pipeline 在每轮优化时更新。
+_CURRENT_PROMPT = [""]
+
+
+def set_prompt(text: str) -> None:
+    """pipeline 写入本轮候选 prompt，使后续 call_agent 调用使用它。"""
+    _CURRENT_PROMPT[0] = text or ""
+
+
+def get_prompt() -> str:
+    return _CURRENT_PROMPT[0]
+
+
+async def call_agent(query: str) -> str:
+    """框架回调：黑盒 agent。prompt 取自模块级当前 prompt。
+
+    签名 (query: str) -> str 直接对接 AgentEvaluator / AgentOptimizer 的
+    call_agent 协议，无需改动框架本身。
+    """
+    return render(decide(query, _CURRENT_PROMPT[0]))
diff --git a/examples/optimization/eval_optimize_loop/gate.py b/examples/optimization/eval_optimize_loop/gate.py
new file mode 100644
index 00000000..d5029096
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/gate.py
@@ -0,0 +1,131 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Acceptance gate: 可配置的候选 prompt 接受/拒绝策略。
+
+防过拟合的核心在这里：即使验证集总分提升，只要出现"关键 case 退化"或
+"新增 hard fail"，候选一律拒绝。成本/耗时预算作为硬上限兜底。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from dataclasses import field
+from typing import Optional
+
+
+@dataclass
+class GateConfig:
+    """接受策略配置（来自 optimizer.json 的 optimize.gate）。"""
+    min_val_improvement: float = 0.0
+    no_new_hard_fail: bool = True
+    key_cases_no_regression: bool = True
+    max_cost_usd: float = 0.0
+    key_cases: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CaseDelta:
+    """逐 case 对比（baseline vs candidate）。"""
+    eval_id: str
+    baseline_pass: bool
+    candidate_pass: bool
+    delta: str  # "new_pass" | "new_fail" | "kept_pass" | "kept_fail" | "score_up" | "score_down"
+
+
+@dataclass
+class GateDecision:
+    accept: bool
+    reasons: list[str]
+    val_score_before: float
+    val_score_after: float
+    improvement: float
+    case_deltas: list[CaseDelta]
+
+
+def _pass_rate(pass_map: dict) -> float:
+    if not pass_map:
+        return 0.0
+    return sum(1 for v in pass_map.values() if v) / len(pass_map)
+
+
+def evaluate_gate(
+    base_pass: dict[str, bool],
+    cand_pass: dict[str, bool],
+    gate_cfg: GateConfig,
+    cost_usd: float = 0.0,
+    duration_seconds: float = 0.0,
+) -> GateDecision:
+    """对单个候选做出接受/拒绝决策。
+
+    Args:
+        base_pass: dict[eval_id, baseline 是否通过]
+        cand_pass: dict[eval_id, candidate 是否通过]
+        gate_cfg: 接受策略
+        cost_usd / duration_seconds: 运行成本（fake 模式通常为 0）
+    """
+    reasons: list[str] = []
+    case_deltas: list[CaseDelta] = []
+
+    before = _pass_rate(base_pass)
+    after = _pass_rate(cand_pass)
+    improvement = after - before
+
+    for eval_id in sorted(set(base_pass) | set(cand_pass)):
+        b = base_pass.get(eval_id, False)
+        c = cand_pass.get(eval_id, False)
+        if (not b) and c:
+            delta = "new_pass"
+        elif b and (not c):
+            delta = "new_fail"
+        elif b and c:
+            delta = "kept_pass"
+        else:
+            delta = "kept_fail"
+        case_deltas.append(CaseDelta(eval_id=eval_id, baseline_pass=b,
+                                     candidate_pass=c, delta=delta))
+
+    accept = True
+
+    # 规则 1：验证集总分必须提升 >= 阈值
+    if improvement < gate_cfg.min_val_improvement:
+        accept = False
+        reasons.append(
+            f"验证集总分未达提升阈值：{before:.4f} -> {after:.4f} "
+            f"(需提升 >= {gate_cfg.min_val_improvement:.4f})"
+        )
+
+    # 规则 2：禁止新增 hard fail（baseline 通过的 case 在候选下失败）
+    if gate_cfg.no_new_hard_fail:
+        new_fails = [d.eval_id for d in case_deltas if d.delta == "new_fail"]
+        if new_fails:
+            accept = False
+            reasons.append(f"出现新增 hard fail（baseline 通过但候选失败）：{new_fails}")
+
+    # 规则 3：关键 case 不能退化
+    if gate_cfg.key_cases_no_regression:
+        regressed_keys = [
+            d.eval_id for d in case_deltas
+            if d.delta == "new_fail" and d.eval_id in gate_cfg.key_cases
+        ]
+        if regressed_keys:
+            accept = False
+            reasons.append(f"关键 case 退化（过拟合信号）：{regressed_keys}")
+
+    # 规则 4：成本/预算硬上限
+    if gate_cfg.max_cost_usd > 0 and cost_usd > gate_cfg.max_cost_usd:
+        accept = False
+        reasons.append(f"运行成本 {cost_usd:.4f} USD 超过预算 {gate_cfg.max_cost_usd:.4f} USD")
+
+    if accept:
+        reasons.append(
+            f"验证集总分提升 {before:.4f} -> {after:.4f} (+{improvement:+.4f})，"
+            f"无新增 hard fail、关键 case 未退化、成本在预算内。"
+        )
+
+    return GateDecision(
+        accept=accept, reasons=reasons, val_score_before=before,
+        val_score_after=after, improvement=improvement, case_deltas=case_deltas,
+    )
diff --git a/examples/optimization/eval_optimize_loop/optimization_report.json b/examples/optimization/eval_optimize_loop/optimization_report.json
new file mode 100644
index 00000000..ed2e132b
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/optimization_report.json
@@ -0,0 +1,670 @@
+{
+  "meta": {
+    "seed": 42,
+    "started_at": "2026-07-21T10:46:53.186200+00:00",
+    "finished_at": "2026-07-21T10:46:53.193741+00:00",
+    "duration_seconds": 0.008,
+    "config_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/config/optimizer.json",
+    "baseline_prompt_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/prompts/baseline_system.md",
+    "train_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/data/train.evalset.json",
+    "val_path": "/home/ybj/trpc-agent-python/examples/optimization/eval_optimize_loop/data/val.evalset.json",
+    "budget": {
+      "max_metric_calls": 50,
+      "timeout_seconds": 150
+    },
+    "mode": "fake_model + fake_judge + call_agent (no API key required)"
+  },
+  "baseline": {
+    "train_pass_rate": 0.0,
+    "val_pass_rate": 0.3333,
+    "train_cases": {
+      "train_weather": {
+        "pass": false,
+        "score": 0.0
+      },
+      "train_format": {
+        "pass": false,
+        "score": 0.0
+      },
+      "train_dead": {
+        "pass": false,
+        "score": 0.0
+      }
+    },
+    "val_cases": {
+      "val_robust": {
+        "pass": true,
+        "score": 1.0
+      },
+      "val_format": {
+        "pass": false,
+        "score": 0.0
+      },
+      "val_weather": {
+        "pass": false,
+        "score": 0.0
+      }
+    },
+    "failure_attribution": {
+      "final_mismatch": 1,
+      "tool_call_error": 2,
+      "param_error": 0,
+      "llm_rubric": 0,
+      "knowledge_recall": 0,
+      "format_error": 2
+    },
+    "attributions": [
+      {
+        "eval_id": "train_weather",
+        "query": "北京天气怎么样？",
+        "passed": false,
+        "failure_type": "tool_call_error",
+        "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "train_format",
+        "query": "请用 JSON 格式回复我",
+        "passed": false,
+        "failure_type": "format_error",
+        "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "train_dead",
+        "query": "请告诉我宇宙的终极答案",
+        "passed": false,
+        "failure_type": "final_mismatch",
+        "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "val_weather",
+        "query": "上海天气如何？",
+        "passed": false,
+        "failure_type": "tool_call_error",
+        "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "val_format",
+        "query": "用 JSON 格式输出一份菜单",
+        "passed": false,
+        "failure_type": "format_error",
+        "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+      },
+      {
+        "eval_id": "val_robust",
+        "query": "你好",
+        "passed": true,
+        "failure_type": null,
+        "reason": "",
+        "regression": false,
+        "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+      }
+    ]
+  },
+  "candidates": [
+    {
+      "label": "candidate_1",
+      "prompt": "回答天气类问题时必须调用 weather 工具并直接给出天气结论。",
+      "train_pass_rate": 0.3333,
+      "val_pass_rate": 0.6667,
+      "train_cases": {
+        "train_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_weather": {
+          "pass": true,
+          "score": 1.0
+        }
+      },
+      "val_cases": {
+        "val_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_robust": {
+          "pass": true,
+          "score": 1.0
+        },
+        "val_weather": {
+          "pass": true,
+          "score": 1.0
+        }
+      },
+      "gate": {
+        "accept": true,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.6667,
+        "improvement": 0.3333,
+        "reasons": [
+          "验证集总分提升 0.3333 -> 0.6667 (++0.3333)，无新增 hard fail、关键 case 未退化、成本在预算内。"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": true,
+            "delta": "kept_pass"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": true,
+            "delta": "new_pass"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        }
+      ]
+    },
+    {
+      "label": "candidate_2",
+      "prompt": "用 JSON 格式回复用户。",
+      "train_pass_rate": 0.3333,
+      "val_pass_rate": 0.3333,
+      "train_cases": {
+        "train_format": {
+          "pass": true,
+          "score": 1.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_weather": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "val_cases": {
+        "val_weather": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_format": {
+          "pass": true,
+          "score": 1.0
+        },
+        "val_robust": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "gate": {
+        "accept": false,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.3333,
+        "improvement": 0.0,
+        "reasons": [
+          "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+          "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+          "关键 case 退化（过拟合信号）：['val_robust']"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": true,
+            "delta": "new_pass"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": false,
+            "delta": "new_fail"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"抱歉，我暂时无法获取天气信息。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"这是一份示例结构化数据。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"我已收到您的请求。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"抱歉，我暂时无法获取天气信息。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] {\"answer\": \"这是一份示例结构化数据。\", \"tools\": []}\n[FMT] json\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "未通过评测，但无法进一步归类到具体子类型。",
+          "regression": true,
+          "actual_excerpt": "[FINAL] {\"answer\": \"我已收到您的请求。\", \"tools\": []}\n[FMT] json\n"
+        }
+      ]
+    },
+    {
+      "label": "candidate_3",
+      "prompt": "对用户提出的每一个问题都必须先调用 weather 工具。",
+      "train_pass_rate": 0.3333,
+      "val_pass_rate": 0.3333,
+      "train_cases": {
+        "train_weather": {
+          "pass": true,
+          "score": 1.0
+        },
+        "train_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "val_cases": {
+        "val_weather": {
+          "pass": true,
+          "score": 1.0
+        },
+        "val_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_robust": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "gate": {
+        "accept": false,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.3333,
+        "improvement": 0.0,
+        "reasons": [
+          "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+          "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+          "关键 case 退化（过拟合信号）：['val_robust']"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": false,
+            "delta": "new_fail"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": true,
+            "delta": "new_pass"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 我已收到您的请求。'，实际回复未满足该条件。",
+          "regression": true,
+          "actual_excerpt": "[FINAL] 北京今天晴，25 摄氏度，适宜外出。\n[TOOL] [{\"name\": \"weather\", \"args\": {\"city\": \"北京\"}}]\n[FMT] text\n"
+        }
+      ]
+    },
+    {
+      "label": "candidate_4",
+      "prompt": "请礼貌地回答用户。",
+      "train_pass_rate": 0.0,
+      "val_pass_rate": 0.3333,
+      "train_cases": {
+        "train_weather": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "train_dead": {
+          "pass": false,
+          "score": 0.0
+        }
+      },
+      "val_cases": {
+        "val_weather": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_format": {
+          "pass": false,
+          "score": 0.0
+        },
+        "val_robust": {
+          "pass": true,
+          "score": 1.0
+        }
+      },
+      "gate": {
+        "accept": false,
+        "val_score_before": 0.3333,
+        "val_score_after": 0.3333,
+        "improvement": 0.0,
+        "reasons": [
+          "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)"
+        ],
+        "case_deltas": [
+          {
+            "eval_id": "val_format",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          },
+          {
+            "eval_id": "val_robust",
+            "baseline_pass": true,
+            "candidate_pass": true,
+            "delta": "kept_pass"
+          },
+          {
+            "eval_id": "val_weather",
+            "baseline_pass": false,
+            "candidate_pass": false,
+            "delta": "kept_fail"
+          }
+        ]
+      },
+      "attributions": [
+        {
+          "eval_id": "train_weather",
+          "query": "北京天气怎么样？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_format",
+          "query": "请用 JSON 格式回复我",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "train_dead",
+          "query": "请告诉我宇宙的终极答案",
+          "passed": false,
+          "failure_type": "final_mismatch",
+          "reason": "最终回复与期望不匹配：期望包含 '[FINAL] 宇宙终极答案是 42'，实际回复未满足该条件。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_weather",
+          "query": "上海天气如何？",
+          "passed": false,
+          "failure_type": "tool_call_error",
+          "reason": "天气类问题应当调用 weather 工具以获取实时天气，但回复中未见 [TOOL] 调用，导致天气知识未被召回，最终回复为兜底话术。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 抱歉，我暂时无法获取天气信息。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_format",
+          "query": "用 JSON 格式输出一份菜单",
+          "passed": false,
+          "failure_type": "format_error",
+          "reason": "期望 JSON 格式回复（[FMT] json），实际产出为 text 格式，不满足格式要求。",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 这是一份示例结构化数据。\n[FMT] text\n"
+        },
+        {
+          "eval_id": "val_robust",
+          "query": "你好",
+          "passed": true,
+          "failure_type": null,
+          "reason": "",
+          "regression": false,
+          "actual_excerpt": "[FINAL] 我已收到您的请求。\n[FMT] text\n"
+        }
+      ]
+    }
+  ],
+  "accepted_candidate": "candidate_1",
+  "delta": {
+    "train_pass_rate": 0.3333,
+    "val_pass_rate": 0.3333,
+    "per_case_val": {
+      "val_format": {
+        "baseline_pass": false,
+        "candidate_pass": false
+      },
+      "val_robust": {
+        "baseline_pass": true,
+        "candidate_pass": true
+      },
+      "val_weather": {
+        "baseline_pass": false,
+        "candidate_pass": true
+      }
+    }
+  },
+  "gate_decision": {
+    "accept": true,
+    "val_score_before": 0.3333,
+    "val_score_after": 0.6667,
+    "improvement": 0.3333,
+    "reasons": [
+      "验证集总分提升 0.3333 -> 0.6667 (++0.3333)，无新增 hard fail、关键 case 未退化、成本在预算内。"
+    ],
+    "case_deltas": [
+      {
+        "eval_id": "val_format",
+        "baseline_pass": false,
+        "candidate_pass": false,
+        "delta": "kept_fail"
+      },
+      {
+        "eval_id": "val_robust",
+        "baseline_pass": true,
+        "candidate_pass": true,
+        "delta": "kept_pass"
+      },
+      {
+        "eval_id": "val_weather",
+        "baseline_pass": false,
+        "candidate_pass": true,
+        "delta": "new_pass"
+      }
+    ]
+  },
+  "rejection_summary": [
+    {
+      "label": "candidate_2",
+      "val_pass_rate": 0.3333,
+      "reasons": [
+        "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+        "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+        "关键 case 退化（过拟合信号）：['val_robust']"
+      ]
+    },
+    {
+      "label": "candidate_3",
+      "val_pass_rate": 0.3333,
+      "reasons": [
+        "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)",
+        "出现新增 hard fail（baseline 通过但候选失败）：['val_robust']",
+        "关键 case 退化（过拟合信号）：['val_robust']"
+      ]
+    },
+    {
+      "label": "candidate_4",
+      "val_pass_rate": 0.3333,
+      "reasons": [
+        "验证集总分未达提升阈值：0.3333 -> 0.3333 (需提升 >= 0.0100)"
+      ]
+    }
+  ]
+}
\ No newline at end of file
diff --git a/examples/optimization/eval_optimize_loop/optimizer.py b/examples/optimization/eval_optimize_loop/optimizer.py
new file mode 100644
index 00000000..6d405b2b
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/optimizer.py
@@ -0,0 +1,56 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Rule-based optimizer: 与 GEPA 等价的、确定性的"扩展机制"。
+
+为什么不用内置 GEPA
+------------------
+AgentOptimizer.optimize 内置的 gepa_reflective 算法依赖真实 reflection_lm
+（LLM）来"反思失败、改写 prompt"，没有 API Key 跑不了。本模块提供等价能力：
+基于失败归因，从一个候选 prompt 池中选出待评估候选（候选设计对应归因发现的
+能力缺口，例如天气工具缺失 -> 注入"调用 weather"指令），并支持把最佳候选写回
+TargetPrompt 源文件（审计/回写）。
+
+整个搜索是确定性的、可在 3 分钟内跑完、无需任何网络调用。
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from trpc_agent_sdk.evaluation import TargetPrompt
+
+
+class RuleBasedOptimizer:
+    """确定性候选生成器 + 写回器。"""
+
+    def __init__(
+        self,
+        baseline_text: str,
+        candidate_texts: list[str],
+        target_prompt: Optional[TargetPrompt] = None,
+    ) -> None:
+        self.baseline_text = baseline_text
+        self.candidate_texts = list(candidate_texts)
+        self.target_prompt = target_prompt
+
+    def propose(self) -> list[tuple[str, str]]:
+        """返回待评估候选列表 [(label, prompt_text), ...]。
+
+        第一个永远是 baseline（作为对照），其后是配置里的候选池。
+        """
+        items = [("baseline", self.baseline_text)]
+        for i, text in enumerate(self.candidate_texts, start=1):
+            items.append((f"candidate_{i}", text))
+        return items
+
+    async def commit(self, prompt_text: str) -> None:
+        """把选中的最佳候选写回 TargetPrompt 源（默认不回写，由 pipeline 控制）。"""
+        if self.target_prompt is None:
+            return
+        names = self.target_prompt.names()
+        if not names:
+            return
+        await self.target_prompt.write_all({name: prompt_text for name in names})
diff --git a/examples/optimization/eval_optimize_loop/pipeline.py b/examples/optimization/eval_optimize_loop/pipeline.py
new file mode 100644
index 00000000..680283f4
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/pipeline.py
@@ -0,0 +1,296 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Eval -> Attribute -> Optimize -> Validate -> Gate -> Audit 闭环编排。
+
+入口：EvalLoopPipeline.run()，返回结构化报告 dict；run_pipeline.py 负责把它
+落盘成 optimization_report.json / .md 并写审计产物。
+
+无需任何 API Key：评测走 call_agent 黑盒 + 确定性 fake_agent；优化走
+RuleBasedOptimizer（与 GEPA 等价的确定性扩展机制）；judge 用框架内置的
+final_response_avg_score(contains) 做确定性匹配。
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from dataclasses import field
+from datetime import datetime
+from datetime import timezone
+from pathlib import Path
+from typing import Optional
+
+from trpc_agent_sdk.evaluation import AgentEvaluator
+from trpc_agent_sdk.evaluation import EvalConfig
+from trpc_agent_sdk.evaluation import TargetPrompt
+from trpc_agent_sdk.evaluation._eval_metrics import EvalStatus
+from trpc_agent_sdk.evaluation._eval_set import EvalSet
+
+import fake_agent
+import real_call_agent
+from attribution import analyze_set
+from attribution import classify
+from attribution import classify_real
+from attribution import summarize_types
+from gate import GateConfig
+from gate import evaluate_gate
+from optimizer import RuleBasedOptimizer
+
+
+def _rate(pass_map: dict) -> float:
+    if not pass_map:
+        return 0.0
+    return sum(1 for v in pass_map.values() if v) / len(pass_map)
+
+
+@dataclass
+class CandidateRecord:
+    label: str
+    prompt: str
+    train_pass_map: dict = field(default_factory=dict)
+    val_pass_map: dict = field(default_factory=dict)
+    train_pass_rate: float = 0.0
+    val_pass_rate: float = 0.0
+    train_score_map: dict = field(default_factory=dict)
+    val_score_map: dict = field(default_factory=dict)
+    attributions: list = field(default_factory=list)
+    gate: object = None  # GateDecision
+
+
+class EvalLoopPipeline:
+    """评测 - 失败归因 - 优化 - 回归验证 - 接受策略 - 产物审计 的自动闭环。"""
+
+    def __init__(
+        self,
+        optimizer_path: str,
+        baseline_prompt_path: str,
+        train_path: str,
+        val_path: str,
+        output_dir: str,
+        seed: int = 42,
+        backend: str = "fake",
+    ) -> None:
+        self.optimizer_path = Path(optimizer_path)
+        self.baseline_prompt_path = Path(baseline_prompt_path)
+        self.train_path = Path(train_path)
+        self.val_path = Path(val_path)
+        self.output_dir = Path(output_dir)
+        self.output_dir.mkdir(parents=True, exist_ok=True)
+        self.backend = backend
+
+        # 选择 call_agent / set_prompt / 分类函数（fake 与 real 两套契约一致）。
+        if backend == "real":
+            self._call_agent = real_call_agent.call_agent
+            self._set_prompt = real_call_agent.set_prompt
+            self._classify = classify_real
+        else:
+            self._call_agent = fake_agent.call_agent
+            self._set_prompt = fake_agent.set_prompt
+            self._classify = classify
+
+        cfg = json.loads(self.optimizer_path.read_text(encoding="utf-8"))
+        self.eval_cfg_dict = cfg["evaluate"]
+        self.optimize_cfg = cfg["optimize"]
+        self.eval_config = EvalConfig.model_validate_json(json.dumps(self.eval_cfg_dict))
+        self.gate_cfg = GateConfig(**self.optimize_cfg.get("gate", {}))
+        self.candidates = self.optimize_cfg.get("candidates", [])
+        self.seed = self.optimize_cfg.get("seed", seed)
+        self.budget = self.optimize_cfg.get("budget", {})
+
+        self.baseline_text = self.baseline_prompt_path.read_text(encoding="utf-8")
+        self.target_prompt = TargetPrompt().add_path("system_prompt", str(self.baseline_prompt_path))
+
+    # ---- 评测 ----------------------------------------------------------
+    def _load_eval_set(self, path: Path) -> EvalSet:
+        return EvalSet.model_validate_json(path.read_text(encoding="utf-8"))
+
+    async def _eval(self, prompt_text: str, eval_set: EvalSet):
+        """评估某个 prompt 在某 eval_set 上，返回 (pass_map, score_map, results_by_id, reasons_by_id)。"""
+        self._set_prompt(prompt_text)
+        # 真实模式下串行评估以降低对 hy3 的并发压力，规避 429 限流。
+        case_parallelism = 1 if self.backend == "real" else None
+        case_eval_parallelism = 1 if self.backend == "real" else None
+        _failed, _details, _lines, results_by_id = await AgentEvaluator.evaluate_eval_set(
+            eval_set,
+            call_agent=self._call_agent,
+            eval_config=self.eval_config,
+            num_runs=1,
+            print_detailed_results=False,
+            case_parallelism=case_parallelism,
+            case_eval_parallelism=case_eval_parallelism,
+        )
+        pass_map: dict[str, bool] = {}
+        score_map: dict[str, float] = {}
+        reasons_by_id: dict[str, str] = {}
+        for eval_id, results in results_by_id.items():
+            r = results[0]
+            passed = r.final_eval_status == EvalStatus.PASSED
+            pass_map[eval_id] = passed
+            scores = [m.score for m in r.overall_eval_metric_results if m.score is not None]
+            score_map[eval_id] = (sum(scores) / len(scores)) if scores else (1.0 if passed else 0.0)
+            # judge 的可解释原因：优先取逐 invocation 的 metric details.reason，
+            # 回退到 overall metric details。
+            reason = ""
+            if r.eval_metric_result_per_invocation:
+                for m in r.eval_metric_result_per_invocation[0].eval_metric_results:
+                    if m.details and m.details.reason:
+                        reason = m.details.reason
+                        break
+            if not reason and r.overall_eval_metric_results:
+                det = r.overall_eval_metric_results[0].details
+                reason = (det.reason if det else None) or ""
+            reasons_by_id[eval_id] = reason or ""
+        return pass_map, score_map, results_by_id, reasons_by_id
+
+    # ---- 主流程 --------------------------------------------------------
+    async def run(self) -> dict:
+        started = datetime.now(timezone.utc).isoformat()
+        t0 = time.time()
+
+        train_set = self._load_eval_set(self.train_path)
+        val_set = self._load_eval_set(self.val_path)
+
+        # 阶段 1：Baseline 评测（训练集 + 验证集）
+        base_tr_pass, base_tr_score, base_tr_res, base_tr_reason = await self._eval(self.baseline_text, train_set)
+        base_va_pass, base_va_score, base_va_res, base_va_reason = await self._eval(self.baseline_text, val_set)
+
+        # 阶段 2：失败归因（baseline）
+        base_tr_attr = analyze_set(train_set, base_tr_res, classify_fn=self._classify, reason_by_id=base_tr_reason)
+        base_va_attr = analyze_set(val_set, base_va_res, classify_fn=self._classify, reason_by_id=base_va_reason)
+        base_attr_summary = summarize_types(base_tr_attr + base_va_attr)
+
+        # 阶段 3：优化执行 —— 对每个候选在训练集评测生成候选
+        optimizer = RuleBasedOptimizer(self.baseline_text, self.candidates, self.target_prompt)
+        candidate_records: list[CandidateRecord] = []
+        for label, prompt in optimizer.propose():
+            # baseline 已在阶段 1 评过，候选循环里跳过它，避免冗余调用（也规避重评时的偶发限流脏数据）。
+            if label == "baseline":
+                continue
+            tr_pass, tr_score, tr_res, tr_reason = await self._eval(prompt, train_set)
+            va_pass, va_score, va_res, va_reason = await self._eval(prompt, val_set)
+            attr = analyze_set(train_set, tr_res, base_pass_map=base_tr_pass,
+                               classify_fn=self._classify, reason_by_id=tr_reason) + \
+                   analyze_set(val_set, va_res, base_pass_map=base_va_pass,
+                               classify_fn=self._classify, reason_by_id=va_reason)
+            gate_decision = evaluate_gate(base_va_pass, va_pass, self.gate_cfg)
+            candidate_records.append(CandidateRecord(
+                label=label, prompt=prompt,
+                train_pass_map=tr_pass, val_pass_map=va_pass,
+                train_pass_rate=_rate(tr_pass), val_pass_rate=_rate(va_pass),
+                train_score_map=tr_score, val_score_map=va_score,
+                attributions=attr, gate=gate_decision,
+            ))
+
+        # 阶段 4/5：挑选被接受的候选中验证集最优者
+        accepted = [r for r in candidate_records if r.label != "baseline" and r.gate.accept]
+        best = max(accepted, key=lambda r: (r.val_pass_rate, r.train_pass_rate)) if accepted else None
+        accepted_label = best.label if best else None
+
+        duration = time.time() - t0
+        finished = datetime.now(timezone.utc).isoformat()
+
+        report = self._build_report(
+            started, finished, duration,
+            base_tr_pass, base_tr_score, base_va_pass, base_va_score,
+            base_tr_attr, base_va_attr, base_attr_summary,
+            candidate_records, accepted_label,
+        )
+        return report
+
+    # ---- 报告构建 ------------------------------------------------------
+    def _case_block(self, pass_map, score_map):
+        return {eid: {"pass": bool(p), "score": round(score_map.get(eid, 0.0), 4)}
+                for eid, p in pass_map.items()}
+
+    def _gate_to_dict(self, gate):
+        return {
+            "accept": gate.accept,
+            "val_score_before": round(gate.val_score_before, 4),
+            "val_score_after": round(gate.val_score_after, 4),
+            "improvement": round(gate.improvement, 4),
+            "reasons": gate.reasons,
+            "case_deltas": [
+                {"eval_id": d.eval_id, "baseline_pass": d.baseline_pass,
+                 "candidate_pass": d.candidate_pass, "delta": d.delta}
+                for d in gate.case_deltas
+            ],
+        }
+
+    def _attr_to_dict(self, attrs):
+        return [
+            {"eval_id": a.eval_id, "query": a.query, "passed": a.passed,
+             "failure_type": a.failure_type, "reason": a.reason,
+             "regression": a.regression, "actual_excerpt": a.actual_excerpt}
+            for a in attrs
+        ]
+
+    def _build_report(self, started, finished, duration,
+                      base_tr_pass, base_tr_score, base_va_pass, base_va_score,
+                      base_tr_attr, base_va_attr, base_attr_summary,
+                      candidate_records, accepted_label):
+        candidates_out = []
+        for r in candidate_records:
+            candidates_out.append({
+                "label": r.label,
+                "prompt": r.prompt,
+                "train_pass_rate": round(r.train_pass_rate, 4),
+                "val_pass_rate": round(r.val_pass_rate, 4),
+                "train_cases": self._case_block(r.train_pass_map, r.train_score_map),
+                "val_cases": self._case_block(r.val_pass_map, r.val_score_map),
+                "gate": self._gate_to_dict(r.gate),
+                "attributions": self._attr_to_dict(r.attributions),
+            })
+
+        best = next((r for r in candidate_records if r.label == accepted_label), None)
+        delta = None
+        if best is not None:
+            delta = {
+                "train_pass_rate": round(best.train_pass_rate - _rate(base_tr_pass), 4),
+                "val_pass_rate": round(best.val_pass_rate - _rate(base_va_pass), 4),
+                "per_case_val": {
+                    eid: {
+                        "baseline_pass": bool(base_va_pass.get(eid, False)),
+                        "candidate_pass": bool(best.val_pass_map.get(eid, False)),
+                    } for eid in sorted(set(base_va_pass) | set(best.val_pass_map))
+                },
+            }
+
+        report = {
+            "meta": {
+                "seed": self.seed,
+                "started_at": started,
+                "finished_at": finished,
+                "duration_seconds": round(duration, 3),
+                "config_path": str(self.optimizer_path),
+                "baseline_prompt_path": str(self.baseline_prompt_path),
+                "train_path": str(self.train_path),
+                "val_path": str(self.val_path),
+                "budget": self.budget,
+                "mode": ("real_model (hy3) + real_judge (llm_rubric_response via hy3) + "
+                         "call_agent" if self.backend == "real"
+                         else "fake_model + fake_judge + call_agent (no API key required)"),
+            },
+            "baseline": {
+                "train_pass_rate": round(_rate(base_tr_pass), 4),
+                "val_pass_rate": round(_rate(base_va_pass), 4),
+                "train_cases": self._case_block(base_tr_pass, base_tr_score),
+                "val_cases": self._case_block(base_va_pass, base_va_score),
+                "failure_attribution": base_attr_summary,
+                "attributions": self._attr_to_dict(base_tr_attr + base_va_attr),
+            },
+            "candidates": candidates_out,
+            "accepted_candidate": accepted_label,
+            "delta": delta,
+            "gate_decision": self._gate_to_dict(best.gate) if best else None,
+            "rejection_summary": [
+                {"label": r.label, "val_pass_rate": round(r.val_pass_rate, 4),
+                 "reasons": r.gate.reasons}
+                for r in candidate_records
+                if r.label != "baseline" and not r.gate.accept
+            ],
+        }
+        return report
diff --git a/examples/optimization/eval_optimize_loop/prompts/baseline_real.md b/examples/optimization/eval_optimize_loop/prompts/baseline_real.md
new file mode 100644
index 00000000..43166683
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/prompts/baseline_real.md
@@ -0,0 +1 @@
+你是一个助手，用中文简洁地回答用户的问题。
diff --git a/examples/optimization/eval_optimize_loop/prompts/baseline_system.md b/examples/optimization/eval_optimize_loop/prompts/baseline_system.md
new file mode 100644
index 00000000..e99c3f74
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/prompts/baseline_system.md
@@ -0,0 +1,4 @@
+# Baseline System Prompt (eval_optimize_loop 样例)
+
+你是一个乐于助人的智能助手。
+请直接、简洁地回答用户的问题。
diff --git a/examples/optimization/eval_optimize_loop/real_call_agent.py b/examples/optimization/eval_optimize_loop/real_call_agent.py
new file mode 100644
index 00000000..b91ae5ac
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/real_call_agent.py
@@ -0,0 +1,107 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""真实 LLM 的 call_agent（接入 hy3 等 OpenAI 兼容后端）。
+
+与 fake_agent 保持一致的交互契约：
+- pipeline 在每轮评估前调用 set_prompt(text) 写入"当前生效的 prompt"；
+- call_agent(query) 用该 prompt 作为 system instruction 跑一次真实推理。
+
+这样 pipeline 既能用确定性 fake_agent，也能无缝切到真实模型，而优化器
+（RuleBasedOptimizer，等价扩展机制）与 gate / 归因 / 审计逻辑无需改动。
+
+评测判定由 config/real_optimizer.json 里的 llm_rubric_response 指标完成，
+judge 同样走 hy3（OpenAI 兼容），无需任何本地规则。
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import uuid
+from pathlib import Path
+
+from trpc_agent_sdk.agents import LlmAgent
+from trpc_agent_sdk.models import OpenAIModel
+from trpc_agent_sdk.runners import Runner
+from trpc_agent_sdk.sessions import InMemorySessionService
+from trpc_agent_sdk.types import Content
+from trpc_agent_sdk.types import GenerateContentConfig
+from trpc_agent_sdk.types import Part
+
+_APP_NAME = "eval_optimize_loop_real"
+
+# 模块级"当前生效 prompt"，由 pipeline 在每轮优化时更新（与 fake_agent 同契约）。
+_CURRENT_PROMPT = [""]
+_MODEL = None
+
+
+def _model_config() -> tuple[str, str, str]:
+    ak = os.getenv("TRPC_AGENT_API_KEY", "")
+    bu = os.getenv("TRPC_AGENT_BASE_URL", "")
+    mn = os.getenv("TRPC_AGENT_MODEL_NAME", "")
+    if not ak or not bu or not mn:
+        raise ValueError(
+            "请先配置环境变量 TRPC_AGENT_API_KEY / TRPC_AGENT_BASE_URL / "
+            "TRPC_AGENT_MODEL_NAME（可参考 .env.example，或用真实 .env）。"
+        )
+    return ak, bu, mn
+
+
+def _get_model() -> OpenAIModel:
+    """懒加载并缓存模型实例，避免每次调用都重建。"""
+    global _MODEL
+    if _MODEL is None:
+        ak, bu, mn = _model_config()
+        _MODEL = OpenAIModel(model_name=mn, api_key=ak, base_url=bu)
+    return _MODEL
+
+
+def set_prompt(text: str) -> None:
+    """pipeline 写入本轮候选 prompt，使后续 call_agent 使用它。"""
+    _CURRENT_PROMPT[0] = text or ""
+
+
+def get_prompt() -> str:
+    return _CURRENT_PROMPT[0]
+
+
+async def call_agent(query: str) -> str:
+    """框架回调：用真实 LLM 跑一次推理，返回最终文本。"""
+    # 节流：两次生成之间稍作停顿，降低对 hy3 的瞬时并发，规避 429 限流。
+    await asyncio.sleep(0.6)
+    agent = LlmAgent(
+        name="eval_agent",
+        description="Evaluated agent backed by a real LLM (hy3).",
+        model=_get_model(),
+        instruction=_CURRENT_PROMPT[0],
+        generate_content_config=GenerateContentConfig(
+            temperature=0.2,
+            top_p=0.9,
+            max_output_tokens=1024,
+        ),
+    )
+    session_service = InMemorySessionService()
+    runner = Runner(app_name=_APP_NAME, agent=agent, session_service=session_service)
+    session_id = str(uuid.uuid4())
+    await session_service.create_session(
+        app_name=_APP_NAME, user_id="eval", session_id=session_id, state={}
+    )
+    user_content = Content(role="user", parts=[Part.from_text(text=query)])
+
+    final_text = ""
+    async for event in runner.run_async(
+        user_id="eval", session_id=session_id, new_message=user_content
+    ):
+        if not event.is_final_response():
+            continue
+        if not event.content or not event.content.parts:
+            continue
+        for part in event.content.parts:
+            if getattr(part, "thought", False):
+                continue
+            if part.text:
+                final_text += part.text
+    return final_text
diff --git a/examples/optimization/eval_optimize_loop/run_pipeline.py b/examples/optimization/eval_optimize_loop/run_pipeline.py
new file mode 100644
index 00000000..23e1b0a8
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/run_pipeline.py
@@ -0,0 +1,194 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""Pipeline 入口：组装配置、运行闭环、落盘审计产物。
+
+两种后端（用环境变量 EVAL_BACKEND 切换，默认 fake）：
+  - fake：确定性 fake_agent + 确定性 contains 匹配，无需任何 API Key（验收主路径）。
+  - real：真实 LLM（hy3）生成 + llm_rubric_response 让 hy3 当 judge，需配置
+          TRPC_AGENT_API_KEY / TRPC_AGENT_BASE_URL / TRPC_AGENT_MODEL_NAME
+          （参考 .env；先把三项填入 eval_optimize_loop/.env）。
+
+运行：
+    # fake（无需 Key）
+    python examples/optimization/eval_optimize_loop/run_pipeline.py
+    # real（需 hy3 Key）
+    EVAL_BACKEND=real python examples/optimization/eval_optimize_loop/run_pipeline.py
+
+产物：
+    artifacts/optimization_report.json   结构化报告（baseline/candidate/delta/gate/归因）
+    artifacts/optimization_report.md     人读的接受决策说明
+    artifacts/candidates/<label>.md      每个候选 prompt 快照（审计落盘）
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+_HERE = Path(__file__).resolve().parent
+_REPO_ROOT = _HERE.parents[2]
+for p in (str(_REPO_ROOT), str(_HERE)):
+    if p not in sys.path:
+        sys.path.insert(0, p)
+
+# 加载 .env（真实模式下提供 hy3 凭据；fake 模式忽略）。
+for _cand in (_HERE / ".env", _HERE.parent / ".env", Path(".env")):
+    if _cand.exists():
+        load_dotenv(_cand, override=True)
+        break
+
+from pipeline import EvalLoopPipeline  # noqa: E402
+
+BACKEND = os.getenv("EVAL_BACKEND", "fake").strip().lower()
+
+if BACKEND == "real":
+    if os.getenv("REAL_SMOKE", "").strip().lower() in ("1", "true", "yes"):
+        # 轻量变体：更少 case/候选，用于在 hy3 配额/限流较紧时验证完整真实闭环。
+        CONFIG = _HERE / "config" / "real_optimizer_smoke.json"
+        BASELINE = _HERE / "prompts" / "baseline_real.md"
+        TRAIN = _HERE / "data" / "real_smoke" / "train.evalset.json"
+        VAL = _HERE / "data" / "real_smoke" / "val.evalset.json"
+    else:
+        CONFIG = _HERE / "config" / "real_optimizer.json"
+        BASELINE = _HERE / "prompts" / "baseline_real.md"
+        TRAIN = _HERE / "data" / "real" / "train.evalset.json"
+        VAL = _HERE / "data" / "real" / "val.evalset.json"
+else:
+    CONFIG = _HERE / "config" / "optimizer.json"
+    BASELINE = _HERE / "prompts" / "baseline_system.md"
+    TRAIN = _HERE / "data" / "train.evalset.json"
+    VAL = _HERE / "data" / "val.evalset.json"
+OUTPUT = _HERE / "artifacts"
+
+
+def _resolve_config_for_real(path: Path) -> str:
+    """真实模式：把 ${TRPC_AGENT_*} 占位符展开为环境变量值，写到临时文件返回路径。"""
+    raw = path.read_text(encoding="utf-8")
+    expanded = os.path.expandvars(raw)
+    if "${" in expanded:
+        missing = [m for m in ("TRPC_AGENT_API_KEY", "TRPC_AGENT_BASE_URL", "TRPC_AGENT_MODEL_NAME")
+                   if not os.getenv(m)]
+        if missing:
+            raise RuntimeError(f"真实模式缺少环境变量：{missing}（请在 eval_optimize_loop/.env 中配置）")
+    tmp = tempfile.NamedTemporaryFile("w", suffix=".json", delete=False, encoding="utf-8")
+    tmp.write(expanded)
+    tmp.close()
+    return tmp.name
+
+
+def _render_md(report: dict) -> str:
+    """把结构化报告渲染成人读 Markdown。"""
+    meta = report["meta"]
+    base = report["baseline"]
+    lines: list[str] = []
+    lines.append("# 评测 - 优化闭环报告（optimization_report）\n")
+    lines.append(f"- 模式: `{meta['mode']}`")
+    lines.append(f"- 复现种子: `{meta['seed']}`")
+    lines.append(f"- 耗时: `{meta['duration_seconds']}s`")
+    lines.append(f"- 配置: `{meta['config_path']}`\n")
+
+    lines.append("## 1. Baseline 评测")
+    lines.append(f"- 训练集通过率: **{base['train_pass_rate']}**")
+    lines.append(f"- 验证集通过率: **{base['val_pass_rate']}**")
+    lines.append("\n### 逐 case（baseline）")
+    for eid, c in base["train_cases"].items():
+        lines.append(f"- train `{eid}`: {'PASS' if c['pass'] else 'FAIL'} (score={c['score']})")
+    for eid, c in base["val_cases"].items():
+        lines.append(f"- val `{eid}`: {'PASS' if c['pass'] else 'FAIL'} (score={c['score']})")
+
+    lines.append("\n### 失败归因统计（baseline）")
+    for ftype, n in base["failure_attribution"].items():
+        if n:
+            lines.append(f"- `{ftype}`: {n}")
+
+    lines.append("\n## 2. 候选验证与 Gate 决策")
+    for cand in report["candidates"]:
+        g = cand["gate"]
+        decision = "✅ 接受" if g["accept"] else "❌ 拒绝"
+        lines.append(f"\n### 候选 `{cand['label']}` — {decision}")
+        lines.append(f"- 训练集通过率: {cand['train_pass_rate']} | 验证集通过率: {cand['val_pass_rate']}")
+        lines.append(f"- 验证集: {g['val_score_before']} -> {g['val_score_after']} "
+                     f"(improvement={g['improvement']})")
+        for reason in g["reasons"]:
+            lines.append(f"  - {reason}")
+        for d in g["case_deltas"]:
+            if d["delta"] in ("new_pass", "new_fail", "kept_fail"):
+                lines.append(f"  - case `{d['eval_id']}`: {d['delta']} "
+                             f"(base={'P' if d['baseline_pass'] else 'F'}, "
+                             f"cand={'P' if d['candidate_pass'] else 'F'})")
+
+    lines.append("\n## 3. 最终决策")
+    if report["accepted_candidate"]:
+        lines.append(f"- **接受候选**: `{report['accepted_candidate']}`")
+        d = report["delta"]
+        lines.append(f"- 训练集 Δ: {d['train_pass_rate']} | 验证集 Δ: {d['val_pass_rate']}")
+    else:
+        lines.append("- **未接受任何候选**：所有候选均未通过 gate，建议保留 baseline 或补充训练样本。")
+
+    if report["rejection_summary"]:
+        lines.append("\n### 被拒绝候选汇总")
+        for r in report["rejection_summary"]:
+            lines.append(f"- `{r['label']}` (val={r['val_pass_rate']}): " + "; ".join(r["reasons"]))
+
+    lines.append("\n## 4. 是否值得回写生产？")
+    if report["accepted_candidate"]:
+        lines.append(f"候选 `{report['accepted_candidate']}` 在验证集上提升且无关键 case "
+                     f"退化、无新增 hard fail，建议人工复核后回写 `prompts/baseline_system.md`。")
+    else:
+        lines.append("当前没有候选比 baseline 更优，不建议回写；优先扩充评测覆盖或修正优化器候选池。")
+    return "\n".join(lines) + "\n"
+
+
+async def main() -> None:
+    OUTPUT.mkdir(parents=True, exist_ok=True)
+
+    config_path = str(CONFIG)
+    if BACKEND == "real":
+        config_path = _resolve_config_for_real(CONFIG)
+
+    pipeline = EvalLoopPipeline(
+        optimizer_path=config_path,
+        baseline_prompt_path=str(BASELINE),
+        train_path=str(TRAIN),
+        val_path=str(VAL),
+        output_dir=str(OUTPUT),
+        backend=BACKEND,
+    )
+    report = await pipeline.run()
+
+    # 审计落盘：结构化报告
+    json_path = OUTPUT / "optimization_report.json"
+    json_path.write_text(json.dumps(report, indent=2, ensure_ascii=False), encoding="utf-8")
+
+    # 人读报告
+    md_path = OUTPUT / "optimization_report.md"
+    md_path.write_text(_render_md(report), encoding="utf-8")
+
+    # 每轮候选 prompt 快照（审计）
+    cand_dir = OUTPUT / "candidates"
+    cand_dir.mkdir(exist_ok=True)
+    for cand in report["candidates"]:
+        (cand_dir / f"{cand['label']}.md").write_text(cand["prompt"], encoding="utf-8")
+
+    # 复现配置快照
+    import shutil
+    shutil.copy(config_path, OUTPUT / "optimizer.snapshot.json")
+
+    print(f"[OK] report -> {json_path}")
+    print(f"[OK] report -> {md_path}")
+    print(f"[OK] candidates -> {cand_dir}")
+    print(f"backend = {BACKEND}")
+    print(f"accepted_candidate = {report['accepted_candidate']}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/optimization/eval_optimize_loop/verify_real.py b/examples/optimization/eval_optimize_loop/verify_real.py
new file mode 100644
index 00000000..7e168a46
--- /dev/null
+++ b/examples/optimization/eval_optimize_loop/verify_real.py
@@ -0,0 +1,47 @@
+# Tencent is pleased to support the open source community by making tRPC-Agent-Python available.
+#
+# Copyright (C) 2026 Tencent. All rights reserved.
+#
+# tRPC-Agent-Python is licensed under Apache-2.0.
+"""一次性连通性验证：确认 .env 里的 hy3 凭据经 OpenAIModel 能正常返回。
+
+用法：
+    python examples/optimization/eval_optimize_loop/verify_real.py
+"""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+_REPO_ROOT = _HERE.parents[2]
+for p in (str(_REPO_ROOT), str(_HERE)):
+    if p not in sys.path:
+        sys.path.insert(0, p)
+
+from dotenv import load_dotenv
+
+for _cand in (_HERE / ".env", _HERE.parent / ".env", Path(".env")):
+    if _cand.exists():
+        load_dotenv(_cand, override=True)
+        break
+else:
+    print("[warn] no .env found near", _HERE)
+
+from real_call_agent import call_agent  # noqa: E402
+
+
+async def main() -> None:
+    print("[cfg] model   =", os.getenv("TRPC_AGENT_MODEL_NAME"))
+    print("[cfg] base_url =", os.getenv("TRPC_AGENT_BASE_URL"))
+    print("[cfg] api_key =", ("set" if os.getenv("TRPC_AGENT_API_KEY") else "MISSING"))
+    try:
+        out = await call_agent("你好，请用一句话介绍北京。")
+        print("[OK] response =", repr(out))
+    except Exception as e:  # noqa: BLE001
+        print("[FAIL] ", type(e).__name__, str(e)[:500])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())