Add evaluation architecture (doc 12)

Four-layer eval design (LLM tasks / skills / safety chain / end-to-end
decision quality), datasets built on event-log replay (I7), change
gates mapping each change type to required evals — envelope widening
approvable only on shadow/online L4 data — and measurable definitions
for the proposal's core KPIs.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019u5SLNweVio6ozJX7yfxQr

🔮 View transcript: https://logs.lojong.info/s/e8u90k3t33w590r7b5y7yzqh

docs/00-overview.md

@@ -121,3 +121,4 @@ flowchart TB
 | 09-runtime-implementation | Runtime 实现设计（Mastra 落地细节） | 2.3 建设内容 05 |
 | 10-federation | 省间协同联邦边界 | 3.3 二期推广 |
 | 11-contracts | 接口清单、业务对象总表、TS↔Python 契约策略 | 2.3 建设内容 02/05 |
+| 12-evaluation | 四层评测体系、数据集、变更门禁、KPI 口径 | 3.1 目标成果核心指标 |

docs/08-implementation.md

@@ -49,6 +49,7 @@ Agent 代码 → 能力接口（complete / plan / extract / explain, 统一消
    ——在确认前，抽象层按「OpenAI 兼容 + 8K 上下文 + 无原生工具调用」的保守假设设计降级路径；
 3. **评测集先行**：为意图解析、规则问答、申报说明生成等每个 LLM 任务建立评测集，
    换后端 = 跑评测集对比，而非人工感觉；这也是向评审证明「模型可替换、平台不锁定」的硬材料。
+   评测体系全貌（四层对象、数据集、变更门禁、KPI 口径）见 12 篇。
 
 ## 3. 部署形态
 

docs/12-evaluation.md

@@ -0,0 +1,110 @@
+# 12 · 评测体系（Evaluation）
+
+> 回答三个问题：评什么、拿什么数据评、评测结果门禁什么。
+> 基础事实：I7（任何决策可从证据重放）使事件日志 + 快照天然成为评测数据源——
+> **审计架构就是评测基础设施**，不另建数据管道。
+
+## 1. 评测对象分层（四层，各有不同的方法论）
+
+```
+L4  端到端决策质量     影子运行对比 · 历史回测收益 · 反事实分析
+L3  可信执行链正确性   政策包测试 · 红队用例 · 不变式验证
+L2  专业模型 Skill     预测精度 · 求解质量 · 辨识准确率（对应核心 KPI）
+L1  LLM 任务          意图路由 · 结构化输出 · RAG 忠实度 · 解释质量
+```
+
+**分层的意义**：L4 出问题时能定位到层。申报收益差，是电价预测偏了（L2）、
+持仓约束读错了（L3 校核漏检）、还是策略解释误导了审批人（L1）——混在一起评就无法归因。
+
+### L1 · LLM 任务评测
+
+| 任务 | 指标 | 方法 |
+|---|---|---|
+| 意图路由（路由 Agent） | 模板选择准确率、参数抽取 F1 | 标注集：真实运营提问 + 变体扩增 |
+| 结构化输出 | schema 合规率、工具引用完整率（数字必须是 `{toolCallId, path}` 引用） | 自动校验，零人工 |
+| RAG 规则问答 | 引用准确率、忠实度（答案是否被检索片段支持）、失效条目误引率 | 规则库标注集 + 政策包升版时回归 |
+| 申报说明 / 复盘报告生成 | 数字一致性（文中数字 vs 血缘工具输出，自动比对）；可读性走人工抽样评分 | LLM-as-judge **仅用于**可读性回归对比，永不裁决数字正确性 |
+
+**换模型 = 跑完 L1 全集**（08 篇 P6 的落点）：光明大模型接入验收即 L1 全集 + L4 影子对比
+达到商用 API 基线的规定比例，这是「模型可替换」主张的硬证据。
+
+### L2 · Skill 评测（对应 proposal 核心 KPI）
+
+| Skill | 指标（口径见 §4） | 数据 |
+|---|---|---|
+| 负荷/光伏预测 | MAPE、分位数覆盖率（P10–P90 区间实际覆盖率） | 滚动历史回测 + 在线逐日 |
+| 电价预测 | MAPE + **方向准确率**（高低价时段排序对——报价优化更依赖排序而非绝对值） | 同上 |
+| 可调潜力辨识 | 辨识准确率（预估可调量 vs 实际履约量） | 执行反馈回流 |
+| 报价优化 | 回测收益 vs 三基准：完美后见之明（上界）、人工历史决策、朴素策略（下界） | 历史行情重放 |
+| 指令分解 | 可行解率、分解后仿真通过率 | 历史场景库 |
+
+**区间校准单独考核**：预测点值准但区间虚（P10–P90 实际只盖住 60%）会让收益风险测算
+系统性乐观——这是比点值偏差更危险的失效模式。
+
+### L3 · 可信执行链评测
+
+- **政策包测试**（05 篇）：每条规则正/反用例，升版全绿才能发布；
+- **不变式测试**（01 篇 I1–I8）：每条不变式至少一个自动化用例
+  （AI 尝试自批 → 必须被拒；伪造数字的 Proposal → 血缘校验必须拦截；
+  过期 Permit → 网关必须拒收；LLM 服务下线 → 校核/审批/申报链路必须可用）；
+- **红队用例库**：越权工具调用、RAG 注入（规则文档里埋指令）、提示注入
+  （用户提问诱导路由到高权限流程）、包络边界探测（恰好压线/超线一分钱）。
+  红队集随攻击面演进持续扩充，进 CI 全量回归。
+
+### L4 · 端到端决策质量
+
+- **历史回测**：I7 重放——取历史某日的证据快照，让当前系统版本完整跑 07 篇场景，
+  对比当时的实际人工决策与实际市场结果；系统升级（提示词、模型、政策包、Skill）后
+  跑固定历史日集合，防决策质量回退；
+- **影子运行**（08 篇 M5）：线上持续评测——逐日记录影子决策 vs 人工决策 vs 事后最优，
+  形成三线对比曲线；这是包络放宽审批的**唯一合法依据**；
+- **反事实归因**：复盘流程中，收益偏差按层分解（预测贡献/策略贡献/执行贡献），
+  写入 ReviewFinding——L4 结果驱动 L1–L3 的改进优先级。
+
+## 2. 数据集体系
+
+| 数据集 | 来源 | 用途 | 维护 |
+|---|---|---|---|
+| 黄金标注集 | 运营真实提问/文档 + 人工标注 | L1 | 每季评审补充 |
+| 历史重放集 | 事件日志 + 快照（I7） | L2/L4 回测 | 自动沉淀，选代表日固化（高温日/大风日/价格异常日/节假日） |
+| 红队用例库 | 安全评审 + 演练发现 | L3 | 持续扩充，只增不删 |
+| 生产回流集 | **每条 ReviewFinding 自动生成评测用例候选**（失败案例是最贵的评测资产） | 全层 | 复盘流程内置步骤 |
+
+## 3. 评测即门禁（什么变更触发什么评测）
+
+| 变更 | 必须通过 | 附加 |
+|---|---|---|
+| 提示词 / Agent instructions | L1 相关任务集 | 固定历史日 L4 回测无回退 |
+| LLM 后端切换（含光明接入） | L1 全集 | L4 影子对比 ≥ 基线的约定比例 |
+| Skill 模型升版 | L2 该 Skill 全指标 | 下游 L4 回测 |
+| 政策包升版 | L3 政策包测试全绿 | 存量 Proposal 影响分析（05 篇） |
+| 包络放宽 | — | **仅凭 L4 影子/在线数据审批**（03 篇自治拨盘），无数据不放宽 |
+| 契约 schema 变更 | 双端黄金样例（11 篇） | 兼容性检查 |
+
+## 4. KPI 口径（proposal 核心指标 → 可测量定义）
+
+| proposal 指标 | 建议口径（待业务确认） |
+|---|---|
+| 预测平均误差 ≤ 8% | 聚合层面日前 96 点负荷 MAPE，月滚动均值；光伏单独统计（建议按装机归一的 nRMSE，逆天气日单列） |
+| 可调潜力辨识准确率 ≥ 90% | \|预估可调量 − 实际履约量\| / 预估可调量 ≤ 阈值的事件占比 |
+| 协同决策响应 ≤ 3 分钟 | 事件触发 → Proposal 进入待批/自动批准状态的 P95 时延（不含人工审批等待——人的时间不算系统的） |
+| 调度指令执行成功率 ≥ 98% | 收到有效 Permit 的指令中，按回执确认执行且偏差在带内的占比 |
+| 综合市场收益提升 15% | 影子/实盘 vs 同期人工基线的归一化收益差（需冻结基线口径，防「基线漂移」） |
+| 跨区域资源匹配准确率 ≥ 85% | 联邦工件层面：承诺容量 vs 交付确认（10 篇 §3） |
+
+> **TODO(业务)**：以上口径需运营团队确认后写入 07 篇场景与验收材料；
+> 特别是「收益提升 15%」的对照基线定义——这是验收时最容易被质询的指标。
+
+## 5. 基础设施与代码位置
+
+```
+packages/evals/
+├── datasets/          # 黄金集 · 红队库 · 代表日清单（重放集本体在事件日志，不复制）
+├── harness/           # 重放驱动器（读快照 → 起工作流 → 比对产出）、指标计算
+├── judges/            # 自动校验器（schema/数字一致性/引用完整）+ 抽样评分工具
+└── reports/           # 每次评测运行的留档（评测本身也留痕：跑了哪版模型/数据/口径）
+```
+
+- 评测运行记录进事件日志——「当时凭什么放宽包络」与「当时凭什么切换模型」同样可审计；
+- L2 在线指标（逐日预测误差、区间覆盖率）进运营看板，异常触发事件（喂给智能分析 Agent，
+  评测体系自身也被监测）。