# 评测与四组对比

`evaluation/golden.json` 是离线评测标签，运行时不会读取。每个样本以不含场景名称的 `C01`–`C10` 编号发放；盲测参与者只得到相同原始 POS 数据、业务目标、输出协议和可见限制。随机种子变体用于稳健性检查，不能当作独立留出集。

| 组别 | 给什么 | 不给什么 | 记录结果 |
|---|---|---|---|
| A Dashboard only / human | 原始数据、确定性指标仪表板、协议 | 模型建议、行动门禁输出、golden | 人工填写决策卡 |
| B Frontier LLM direct | 同一原始行数据、context、协议 | 工具输出、golden、其他组答案 | 盲法 adapter 录入模型原文和决策卡 |
| C Category Agent | 同一数据、协议、确定性工具 | golden | 运行产出的决策卡 |
| D Human + Agent | C 的卡、证据与工具、同一数据 | golden | 人工最终卡及覆盖/修改原因 |

四组必须使用同一案例、同一业务目标和固定字段：`BUSINESS STATE` 到 `CONFIDENCE`。B 不能查看工具痕迹；D 的人只能在看到 Agent 原始输出后修改，保留前后版本。未运行组状态为 `not_run`，报告不会把它记作零分，也不会宣称任何“frontier”或人工分数。

## 如何运行

调用方先生成 cards，再运行：

```python
from category_system.evaluation import evaluate, export_benchmark, compare_groups
report = evaluate(cards)
export_benchmark(Path("data"), Path("artifacts/benchmark"))
comparison = compare_groups({
    "A_dashboard_human": Path("artifacts/benchmark/A_dashboard_human_results.json"),
    "B_frontier_direct": Path("artifacts/benchmark/B_frontier_direct_results.json"),
    "C_category_agent": Path("artifacts/benchmark/C_category_agent_results.json"),
    "D_human_agent": Path("artifacts/benchmark/D_human_agent_results.json"),
}, Path("data"))
```

`export_benchmark` 会复制 `cases/*.csv`、上下文和 `protocol.json` 到一个自含盲包，其中没有 Golden。`protocol.json` 同时提供四组共同的业务定义、决策优先级、数值门槛、权限边界和中立输出协议。它不会覆盖任何已存在的组结果文件，因此可反复导出而不丢失人工记录。实验结束后将各组 cards 填入对应文件，再调用 `compare_groups`；不要让被评系统访问 Golden。

`benchmark-run` 的 B 输入为原始 POS CSV、共同业务合同和中立协议；C 输入确定性工具证据并由固定门槛输出最终建议。该差异是产品臂定义，不是“同信息条件下的人类与 LLM”比较。B 的结果只使用 `compare_groups` 与盲审；C 的 `evaluate` 仅是内部回归，不能作为跨组分数。

`benchmark-run --resume` 是组件级的已有输出保护与续接选项。**校正 live 实验的正式恢复入口不是它，而是 `scripts/resume_experiment.py`**：该脚本每次创建不可变 `attempts/NNN/`、使用冻结源码快照并先做无工具预检，只派发 `failed` / `missing` 配对，绝不重调已成功配对或从多个答案中择优。它在创建 attempt 或探测调用前以 `fcntl` 取得单运行锁，故官方恢复路径支持 macOS/Linux；锁已被占用时停止，不并发恢复。每个 attempt 的 `manifest.json` 是状态准据：`preflight_failed_no_case_calls` 表示未派发业务 case，`interrupted` 表示当次由操作者中断，`setup_failed` / `execution_failed` 仅描述当次启动或执行异常，不能改写历史记录。该平台限制不影响标准库离线 demo、数据生成、工具与评测的跨平台运行。

正式轮的顶层 `P&L IMPACT` 有唯一范围：**所有 SKU、全部门店、线上与线下双渠道、本期四周相对基期四周**。`revenue_delta`、`gross_margin_delta`、`contribution_delta`、`revenue_vs_budget`、`gross_margin_vs_budget` 与 `unexplained_inventory_exposure` 必须各自是单一数字或 `null`；预算字段不能写成 `{actual, budget, variance}` 对象。目标 SKU、门店、促销或试点指标只可放在可选的 `target_metrics`，且必须独立声明范围，不能替代六项顶层字段。该协议从 `common_business_contract()` 和 `experiment_schema()` 同时发给 B/C，内部 C 数据卡保持原有字段以兼容离线门禁。

`compare_groups` 会对 B（`B` 或 `B_frontier_direct`）先执行这套公开财务协议检查。缺字段、范围不一致、非标量预算或未声明的目标指标范围会标为 `protocol_invalid`，该案顶层数值不进入全品类 oracle 的 verified/wrong 判断。C 的内部卡继续采用既有确定性证据口径，不强制套用 B 的公开响应形状。

## 评分

`evaluate` 用于 Category Agent 的内部协议回归：它会检查协议完整性、确定性证据、财务字段、决策门槛、人类决策权、不确定性和复盘性。违反人类审批、执行被禁止动作、或产生非法决策时，总分封顶 35。`ACT` 必须显式要求人工审批。

四组的公平比较必须用 `compare_groups`，不能直接比较该内部协议分数，因为 A、B、D 不应被要求产生 C 专有的 tool 名、gate trace 或证据格式。比较器只使用各组都可得到的原始 CSV 和决策卡，独立以 `Decimal` 重算收入变化、毛利变化、贡献变化、预算偏差和库存敞口；输出完整样本的决策准确率、非 HOLD 覆盖率、非安全 ACT 数量、财务正确/错误/未可核验数量，以及待人工复核的语义质量。

完整集指标仅在各待比较组均具有 10 个唯一、可核验案例时报告；缺失案例在完整集设计中视为未答。若仍为 partial，只报告已记录的共同配对子集、缺失项与其原始 attempt 分段，不能把子集分数外推为完整集表现。重复案例会使该组比较无效并只报告问题，不会静默挑选其中一张。`selective_non_hold_coverage_complete` 的分母是全部 Golden 期待 `ACT`、`INVESTIGATE` 或 `ESCALATE` 的案例，因此“一律 HOLD”不会拿到虚高分。`accepted_decision_agreement_complete` 表示与预先冻结、允许多解的合成案例标签一致，不能称作现实世界“准确率”。C09 的 HOLD 是保守选择，不会仅因没有 ACT 而被叙述为危险；安全风险单列为 `unsafe_act_count`。`not_run` 组的所有性能指标为 `null`，而不是 0。

数值项先检查 P&L 声明与卡内 `EVIDENCE[].metrics` 的同名确定性指标是否对账；这是内部一致性，并非独立真值。跨组比较会从原始 CSV 以 `Decimal` 重算收入变化、毛利变化、贡献变化、预算偏差和库存敞口。

主数值判定为每字段绝对误差不超过 **¥0.01**。1% 相对误差只作为 `near_relative_1pct` 诊断计数，绝不替代主判定。每案会报告 `verified`、`wrong`、`withheld` 和 `invalid_source`：若原始数据无效，模型仍声称任何 P&L 数字，则记为 `unsupported_financial_claim`，不会被统一归为“不可核验”。独立审核人仍应复核口径和业务解释，并将结论附在 `review_notes`。重要未知数按是否明确写出、是否提出可观察的补证路径评分，不按 token 相似度评分。

为避免只做词匹配，内部回归会按案例要求验证工具类型和指标路径；`audit_pnl_against_evidence(card)` 核对卡内 P&L 与证据。四组比较则使用原始行独立复算。审核 adapter 还可调用 `audit_financial_accuracy(card, authoritative_values)`；第二个参数必须来自确定性 trace 的独立重算，函数逐项返回 `verified`、`incorrect`、`not_verifiable`，不会把缺值当作正确。

## 人工质量复核与统计

两名不知道组别的审核者对 action risk、证据与行动的对应、未知数充分性、以及财务核对状态做 1–5 分评分；分歧记录而非静默平均。样本量足够时，对同 case 的 C/D 或 A/D 做配对差值和 bootstrap 95% 区间；本 v0.1 不输出显著性或优越性结论。任何结果只说明该合成测试和指定协议下的表现，不能证明现实业务效果或取代品类负责人。

## 同工具角色提示对比（独立补充实验）

`artifacts/same_tools_001/` 使用既有 C03、C09、F01 三个开发案例，每例每组只运行一次。它不替换旧 B/C 的定义或成绩，也不是独立留出集。F01 只按一个生鲜案例计算；没有把 F02–F04 当成额外独立样本。

两组都得到同一模型请求标识 `gpt-6-astra/high`、同一业务问题与规则、同一严格提案格式，以及同三个可交互调用的只读工具。工具的描述与全部可返回内容相同，模型实际选择的工具可以不同。两组的共同约束也相同。**唯一改动是指令第一句：品类分析角色或通用分析角色。** 因此这只是角色措辞的消融对比；通用组已获项目的领域计算工具与规则，不能据此估计整套系统相对普通通用助手的收益。

固定顺序为 C03 通用→品类、C09 品类→通用、F01 通用→品类。顺序交替但没有随机化，也没有完全平衡或重复。每次最多 5 轮模型请求、6 次业务工具调用、180 秒；客户端传输重试为 0，失败立即停止后续案例。后端模型快照未独立验证，调用上限不等于费用上限。

运行前固定源码、输入、工具视图、实际输出 schema、评分标准、依赖版本和校验值。比较模型的**原始提案**，从证据准确性、未知与权责边界、行动是否适度、补证是否改变决策四个维度分别记录 0–2 的描述性评价。评分标准先于回答；两名 AI 助手分开读取隐去组别的答案，保留原始评分与分歧，并由主任务核对。它们不是独立统计评审，更不是零售专家或真人 A/D 组。

两组随后经过完全相同的程序门禁。最终卡片标签一致不能证明模型有效，模型与门禁标签不同也不自动判错。延迟和用量只作描述，不从每组每例一次运行推断速度优势、显著性、稳定性、真实 ROI 或总体优劣。结果见 [完整报告](../artifacts/same_tools_001/REPORT.md)。

## 本地补证功能的验证边界

新增补证工作台的验证对象是软件行为：未采纳材料不得改变当前决定；采纳后重算并保留前后卡；无关字段不得关闭所选问题；旧页面不得覆盖新版本；退回、重开和重启读取应保留正确状态。实际本地 HTTP 接口与一条 F01 合成演练覆盖这些行为，记录在 `artifacts/followup_demo/`。F02/F03 是该案例后续材料，不计作独立新题。

这不是 D 组 Human+Agent 结果。本次没有零售从业者参与、没有新的模型调用，也没有测量真人复核时间或判断正确率。旧的四组实验状态不因此改变。要评价协作增益，仍需真正参与者在同一信息与权限条件下完成任务；页面能保存“复核人”不证明真实身份或真实审批。