EvalHarness 子系统设计

1. 职责定义

EvalHarness 承接 ADR-007 supplement 中评测体系（11 维度 + 7 MCA 桶 + Phase 5 治理）在工程层的实现（ADR-007 supplement §2.4 + Phase 5 治理机制）。

具体覆盖：

11 维度评测：D1 本体识别准确率（M1）/ D2 信息源对齐质量（M2）/ D3 跨时钟相位识别（M3 + M4）/ D4 场景命中 + 传导链路完整性（M4 + M5）/ D5 金融规律应用 + 规律不适用识别（M6）/ D6 偏差识别 + 不确定性量化（M7）/ D7 S1 叙事-数字一致性识别（S1 + 反向触发 M5 / M6 / M7）/ D8 金融历史可比性（M3 + M4 + M8 + MCA，R-A P1-2 新增）/ D9 跨市场对照推理（必须跨 ≥ 2 MCA 桶，R-A P1-2 新增）/ D10 数据可靠性鉴别（M1.3 + M2.2 + M7a + M6.4，R-A P1-2 新增）/ D11 风险预算与组合层（M6.2 协方差 + M5.3 + M7.uq，R-A P1-2 新增）。
7 MCA 桶分层：B1-B7 含 B5a / B5b 拆分（R1 拆 B5）；桶间归一化用「桶内满分」基准 + 跨桶比「桶内百分位」+ 最小样本量 ≥ 30 + bootstrap 标注「百分位带宽 ± X%」。
70 / 20 / 10 三集分集：dev 可公开 + test 仅事实层公开（标答 / 期望激活 / 关键洞察 / 事后演化撤回工程仓）+ holdout 完全私密 + holdout 桶位均匀。
IAA kappa ≥ 0.7 门槛（对齐 Phase 4 评测体系 D1 / D7 IAA 约束）+ D1 M1.3 IAA 门槛六字段拆「闭合类」与「开放分类类」开放类必须经 ≥ 2 专家 IAA kappa ≥ 0.7 方入分母。
半人工标注 SLA 承接（Phase 7 半人工标注 SLA 附录任务 A / B / C / D）：半人工标注产出进入评测样本的路径 + 标注质量基线评分 + 桶位均匀 holdout 要求。
Case Library 角色：作为回归追踪 + 退化定位载体，不作二元门禁（沿用架构主稿 §21 评估闭环的 Case Library 角色澄清）。

输入是 StructuredCognitionResult 1.1（含 10 要素 + 6 新顶层字段 + Task schema 元数据 mca_bucket）；输出是离线评测报告 + 退化追踪 + 触发 Phase 5 治理流程的信号。输入字段定义事实源为 ADR-008 supplement，派生 Pydantic schema 见 StructuredCognitionResult 1.1 契约源。

2. 接口契约

class EvalHarness:
    def evaluate_case(
        self,
        case_id: str,
        cognition_result: StructuredCognitionResult,
        ground_truth: GroundTruth,
        mca_bucket: MCABucket,
    ) -> CaseScore:
        """单 case 评测, 输出 11 维度评分 + 桶位标签 + 半人工标注质量基线."""
        ...

    def evaluate_batch(
        self,
        cases: list[CaseInput],
        split: Literal["dev", "test", "holdout"],
    ) -> BatchReport: ...

    def evaluate_dimension(
        self,
        dimension_id: Literal["D1", "D2", "D3", "D4", "D5", "D6", "D7",
                              "D8", "D9", "D10", "D11"],
        case_score: CaseScore,
    ) -> DimensionScore: ...

    def bucket_aggregate(
        self,
        scores: list[CaseScore],
        bucket: Literal["B1", "B2", "B3", "B4", "B5a", "B5b", "B6", "B7"],
    ) -> BucketReport:
        """桶内独立维护满分基准 + 跨桶比桶内百分位 + bootstrap 带宽."""
        ...

    def detect_degradation(
        self,
        current_report: BatchReport,
        baseline_report: BatchReport,
    ) -> list[DegradationFlag]:
        """对照上轮 baseline 检测每桶每维度退化, 退化 > 阈值触发 Phase 5 治理."""
        ...

    def run_iaa_calibration(
        self,
        annotated_cases: list[AnnotatedCase],
    ) -> IAAReport:
        """开放分类类字段需双 reviewer kappa >= 0.7 方入分母."""
        ...

    def report_semi_manual_quality_baseline(
        self,
        sla_window: SLAWindow,
    ) -> SemiManualQualityReport:
        """报告半人工标注延迟 / 准确率 / IAA / SLA 达标率 (Phase 7 SLA 附录 §六接口)."""
        ...

子模型类型 placeholder（M0 阶段简定义）

接口签名引用的下列类型在 ADR-008 supplement / 1.1 契约源中尚未给出字段定义，本节给 M0 阶段的最小 Pydantic v2 placeholder，目的仅是让 Codex import 链闭合。IAAReport 在 evaluation harness 公式包 §6 已有可执行定义，本节仅做 forward-reference 重述以保接口签名 import 闭合。字段细节留 M1+ 收紧路径见本子系统 §9 实现里程碑映射 + 后续 milestone-field-evolution-matrix.md 起草；事实源回写发生于 ADR-008 supplement v2 / 1.1 契约源后续 patch 段。

# M0 placeholder 段。M1+ 收紧字段定义;事实源在 ADR-008 supplement v2 / cognition-1.1-contract.md v1.2 时回写。
from pydantic import BaseModel


class GroundTruth(BaseModel):
    """M0 placeholder。承载单 case 的标答(14 case 锚位 + 4 EM 补充 + D7 外部源 + 半人工标答)。"""

    case_id: str
    source: str  # 标答来源,如 "case-library-14" / "damodaran" / "semi-manual-task-a"
    payload_blob: dict  # 标答内容的临时 dict,M1+ 按 11 维度拆强类型
    # 其它字段待 M1+ 锁定


class CaseInput(BaseModel):
    """M0 placeholder。承载单 case 的评测输入(cognition_result + ground_truth + mca_bucket 的引用)。"""

    case_id: str
    split: str  # "dev" / "test" / "holdout"
    cognition_result_ref: str  # 指向被测体系输出的引用 id
    ground_truth_ref: str  # 指向 GroundTruth 的引用 id
    # 其它字段待 M1+ 锁定


class AnnotatedCase(BaseModel):
    """M0 placeholder。承载双 reviewer 盲交叉标注产出,用于 IAA kappa 计算。"""

    case_id: str
    reviewer_id: str
    annotation_blob: dict  # 标注内容的临时 dict,M1+ 按开放分类字段拆强类型
    # 其它字段待 M1+ 锁定


class IAAReport(BaseModel):
    """M0 placeholder(forward reference)。完整定义见 evaluation harness 公式包 §6。
    本子系统接口签名以此 minimal 形态承接 import,不重复字段语义。
    """

    kappa: float  # ∈ [-1, 1]
    n_pairs: int  # 参与 IAA 的 reviewer pair 样本量
    # 其它字段以公式包 §6 IAAReport 为事实源


class SLAWindow(BaseModel):
    """M0 placeholder。承载半人工标注 SLA 报告的窗口元数据。"""

    start_ts: int  # Unix epoch ms
    end_ts: int  # Unix epoch ms
    task_ids: list[str]  # 半人工标注 4 任务 id 子集,如 ["task-a", "task-b"]
    # 其它字段待 M1+ 锁定


class SemiManualQualityReport(BaseModel):
    """M0 placeholder。承载半人工标注 4 任务(A/B/C/D)的 SLA 达标 / IAA / 准确率三维基线。"""

    window: SLAWindow
    sla_hit_rate: dict  # task_id -> [0, 1] 达标率
    iaa_kappa: dict  # task_id -> kappa 滚动均值
    accuracy: dict  # task_id -> [0, 1] 准确率
    # 其它字段待 M1+ 锁定

3. 数据流

输入源：
- StructuredCognitionResult 1.1 全字段（10 要素 + 6 新顶层字段 phase_evidence / causal_graph / regulation_status / applicability_flags / posterior / s1 + structured_result_version）。
- Task schema 元数据 mca_bucket（来自 MCAClassifier，评测系统强制下发，被测体系不允许自报）。
- 标答库（Ground Truth）：
  - 14 case 锚位 + 4 EM 补充 case（L1 / L2 / L9 / L13）反向校准库；
  - D7 外部独立标答源（Damodaran "Narrative & Numbers" / Howard Marks memo / Stratechery / FT Alphaville / NYU Stern 课程库）；
  - 半人工标注 case 标答（任务 A / B / C / D）。
- 70 / 20 / 10 划分元数据（dev / test / holdout 集标记）。
内部处理：
- 单 case 评测：对每条 StructuredCognitionResult 跑 11 维度独立评分；每维度按主映射机制（ADR-007 supplement §2.4 评测维度表）调用对应评测器。
- 桶位聚合：按 mca_bucket.bucket_label 分桶；每桶独立维护满分基准 + 跨桶比桶内百分位 + bootstrap 标注带宽。
- 退化检测：对照上一季度全量评估的 baseline 报告，每桶每维度退化 > 阈值（默认 15%，待校准）触发 Phase 5 治理流程的 mini-review。
- 半人工标注质量基线：每季度报告每项任务（A / B / C / D）的 IAA kappa 滚动均值 + 准确率 + SLA 达标率三项指标；半人工标注质量低于阈值的桶位评测结果不参与跨桶百分位对照，仅报告绝对分数。
- D4 链路相似度算法：节点 F1（0.35）+ 边 F1（0.35）+ 子图同构匹配率（0.30）；可选 Riesen-Bunke 编辑距离上界近似（替代 NP-hard 的 GED）。
- D6 多标签 F1 加权防 top-3 gaming：14 case 历史频率反向加权（高 ×0.5 / 低 ×2.0）+ 同时报告 macro-F1（差距 > 0.15 触发复审）+ 新增 ECE 校准指标（≤ 0.15 合格）。
- D3 相位 MAE 离散化粒度：明确「季度」为最小相位单元。
输出：
- BatchReport（桶分层 11 维评分 + 桶间归一化 + bootstrap 带宽 + 退化追踪）。
- SemiManualQualityReport（半人工标注 4 任务的 SLA 达标 / IAA / 准确率基线）。
- 触发 Phase 5 治理流程的退化信号（季度全量 + 月度增量 + 触发式专项三轨）。

4. 关键依赖

依赖类型	内容
外部数据源	D7 外部独立标答源（Damodaran / Marks / Stratechery / FT Alphaville / NYU Stern）/ 14 case 锚位 + 4 EM 补充 case 库 / 季度补 case 规模 15–20（R1 由 5–10 提至 15–20）
内部模块	MCAClassifier（评测分桶强制下发 `mca_bucket`）/ KnowledgeGraphService（消费 `causal_graph` + `phase_evidence` 作为 D3 / D4 评测输入）/ ConsistencyMiddleware（消费 `s1` 作为 D7 评测输入）/ State Management（持久化 Case Library + Audit Trail + 评测报告）/ Phase 5 治理工作流（接收退化信号）
持久化	Case Library 走嵌入式 SQLite + JSON 字段；70 / 20 / 10 三集划分用配置文件 + 文件命名约定；评测报告按季度 / 月度 / 触发式三类归档，保留 ≥ 8 季度 audit trail（沿用 ADR-009 立场降级 audit trail 范式）

5. 测试要求

EvalHarness 既是评测系统也需自身被测试 —— 元评测（meta-evaluation）层用合成 case + 已知标答验证评测器自身的正确性。

单元测试：
- 各维度评测器（D1–D11）输入约束 + 输出范围（评分 ∈ [0, 1] / F1 ∈ [0, 1] / kappa ∈ [-1, 1] / ECE ∈ [0, 1]）。
- 桶位聚合算法：桶内满分基准 + 桶内百分位 + bootstrap 带宽计算正确性。
- 退化检测阈值：默认 15% 退化触发 mini-review 的边界条件。
- 70 / 20 / 10 划分一致性：同一 case 在多次评测中划分稳定（避免数据泄漏）。
集成测试：
- 与 MCAClassifier 联动：mca_bucket 强制下发，被测体系不允许自报。
- 与 KnowledgeGraphService 联动：causal_graph.correlation_regime 作为 D9 跨市场对照推理的核心输入。
- 与 ConsistencyMiddleware 联动：s1 字段作为 D7 评测输入；D7 标答强制外部独立源。
- 与 Phase 5 治理流程联动：退化信号触发季度全量 / 月度增量 / 触发式专项三轨；7 MCA 桶 + 时间窗双重分层（禁止全集平均掩盖局部退化）。
元评测（meta-evaluation）：
- 合成 case 已知标答 → 评测器输出 vs 标答对照，验证评测器自身偏差。
- 半人工标注 4 任务的 IAA kappa 滚动监测，连续两季度低于阈值触发标注流程修订（Phase 7 SLA 附录 §四失效处理）。
回归追踪：
- Case Library 作为回归追踪载体，不作二元门禁；新 case 入库做「上轮 vN 体系冷启评测」基线对照（防过拟合）。
- 每 4 季度抽 ≥ 20% case 作 holdout 年度抽检（沿用 Phase 5 防退化机制）。

6. v1 工程回退

v1 阶段的评测降级路径（承接 ADR-008 supplement §3.1 版本兼容策略）：

1.0 / 1.1 混合 consumer 兼容：consumer 收到 structured_result_version = "1.0"（或缺省视为 1.0）的输出时，6 顶层字段 + 1 元数据以 None 缺省值处理；D4 / D6 / D7 在缺字段时降级为「文本层评测」并在评测元数据中标注 degraded-text-only，不阻断评测管线。
B7 EM 主权 + 货币危机扩展桶零样本处理：v1 起步 1–2 case anchor（L7 + L2）+ 单独基线（不参与百分位对照）+ v1→v2 不强制跨 B7 + v2 起补足 ≥ 10 case 后纳入百分位。
半人工标注质量低于阈值桶位：评测结果不参与跨桶百分位对照，仅报告绝对分数；防止「评测分数高但标注质量低」的过拟合标注 gaming 路径。
D8–D11 case 扩充延后：D9 必须跨 ≥ 2 MCA 桶 / D10 ≥ 5 事后被证实造假 case + ≥ 15 健康对照 / D11 待 M6.2.x 落地后扩 B4–B7 桶（ADR-007 supplement §5.1 Phase 7+ 路径）。

允许 reviewer 推翻 / 标注的字段范围（间接通过半人工标注 4 任务承接，本子系统消费但不直接产出）：

任务 A / B / C / D 标答（详见知识图谱服务 §6 / 一致性中间件 §6 / 市场上下文分类器 §6）。

7. 待解决问题 / 已知 trade-off

退化检测阈值 15% 的校准：v1 默认值，未经评测压测；待第一阶段 4 季度全量评估后由 Phase 5 治理拍板。
D10 数据可靠性鉴别 case 量不足：R-A P1-2 新增维度，需 ≥ 5 事后被证实造假 case + ≥ 15 健康对照，v1 起步可能 case 量不足；不足时该维度报告标注「样本量不足」+ 不进 baseline 对照。
D11 风险预算与组合层的依赖：依赖 M6.2.x（协方差延伸）落地，v1 起步该维度可能仅在 B1-B3 桶可计算；B4-B7 桶待 M6.2.x 落地后扩展。
Meta-evaluation 合成 case 质量：v1 起步合成 case 由领域专家手工构造，规模有限；待 Phase 7+ 评测器自身漂移监测机制成熟后扩规模。
跨季度评测报告归档的 audit trail 长度：ADR-009 立场降级 audit trail 范式要求 ≥ 8 季度，但 EvalHarness 季度全量评估报告 + 月度增量评估报告的累积数据量可能超出本地 SQLite 容量；v1 走 SQLite + 文件 archive 混合归档，v2 路径待评测压测后决议。
Case Library 回归报告驱动改进决策的具体阈值（架构主稿 OQ-002）：哪些退化必须修 / 哪些可记技术债 / 退化的判定阈值 —— 工程层目前不预设具体方法，避免在方法未确认时把「盲读」等不可重复的人工判读当成工程标准；本子系统的退化检测先报告 + 不做二元裁决。

8. 与其它子系统的接口对齐

KnowledgeGraphService：本子系统消费其 causal_graph / phase_evidence 输出作为 D3 / D4 / D9 评测输入；退化检测信号反向触发 KnowledgeGraphService 的子机制级修订（如 M5.5 反向力量召回阈值调整）。
ConsistencyMiddleware：本子系统消费其 s1 输出作为 D7 评测输入；退化检测信号反向触发 ConsistencyMiddleware 的失败模式分类标注流程修订。
MCAClassifier：本子系统的评测分桶强制使用 MCAClassifier 输出的 mca_bucket，不允许被测体系自报；半人工标注 4 任务（含任务 D · MCA 轴 4 N3）的标答由 reviewer 经 SLA 流程产出，本子系统直接消费不做二次判定。
既有子系统（State Management）：本子系统的 Case Library + 评测报告 + Audit Trail 写入由 State Management 持久化层承接；架构主稿 §21 评估闭环是本子系统的上位定义。
Phase 5 治理工作流：本子系统的退化追踪信号是 Phase 5 治理（季度全量 / 月度增量 / 触发式专项三轨）的法定触发源 A（评测体系缺口）；半人工标注质量基线是触发源 B（用户实战反馈）以外的独立质量基线。

9. 实现里程碑映射

承接架构主稿 §29 v1 实现路径建议与 M0 Walking Skeleton §3.5。

里程碑	本子系统落地范围	不落地（留下个里程碑）
M0	11 维评测的 M0 子集（D1 / D2 / D5 / D7 起步）落地；`runner.py` + `m0_subset.yaml` 接入 Mock fixture；IAA kappa 阈值表落档但仅在 1 桶（B1 基线桶）跑通；bootstrap 重采样按 evaluation harness 公式包实现	D3 / D4 / D6 / D8 / D9 / D10 / D11 全维度、7 MCA 桶分桶评测、Case Library 70/20/10 切分 + holdout 治理、退化追踪反向触发链路
M1	11 维 D3 / D4 / D6 / D8 评测维度上线；7 MCA 桶分桶评测（B5 拆 B5a / B5b 实际 8 label）；Case Library 70/20/10 切分接入；季度全量评测报告归档；M3.t1 / M3.t2 / M3.t5 三槽位强制评 + 其余 6 槽位抽样 IAA	D9 / D10 / D11（跨市场对照 / 造假识别 / B4-B7 扩桶）、跨季度 audit trail（≥ 8 季度）、退化检测自动反向触发
M2	D9 跨市场对照评测上线（依赖 KnowledgeGraphService M5 主干完整）；D10 造假识别评测扩到 ≥ 5 事后被证实 case + ≥ 15 健康对照；跨季度 audit trail 接入 SQLite + 文件 archive 混合归档	D11 B4-B7 扩桶（待 M6.2.x 落地）、退化驱动的具体阈值（OQ-002 待评测压测后决议）
M3	D11 B4-B7 扩桶评测全量上线；退化判定具体阈值锁定（OQ-002 闭环）；7 MCA 桶 + 9 时钟槽位 + 7 维度的完整笛卡尔积评测稳态运行；半人工标注 SLA 流程与季度治理评估闭环	跨工作流的 v2 体系演进项（按 Phase 5 治理流程节奏）

1. 职责定义​

2. 接口契约​

子模型类型 placeholder（M0 阶段简定义）​

3. 数据流​

4. 关键依赖​

5. 测试要求​

6. v1 工程回退​

7. 待解决问题 / 已知 trade-off​

8. 与其它子系统的接口对齐​

9. 实现里程碑映射​