# Token 对比

> Canonical path：`specs/daemon/token-comparison.md`
> 范围：用最小 comparability metadata 对比两份 Token analysis report；不负责自动运行 benchmark。
> 状态：已实现脱敏报告的描述性对比。缺少受控 fingerprint、cache 或 outcome 时不会声称因果。

## 1. 目标

Comparison 用于验证一个 AgentTeam Context 改动后：

- cumulative runtime input 是否下降；
- runtime 支持 invocation identity 时，average input per model invocation 和调用数是否变化；
- AgentTeam-controllable cumulative estimate 和 block contribution 是否下降；
- 由开发者在报告外验证的 task outcome 是否仍可接受。

第一版只比较已有报告，不自动启动 raw Codex/Claude、fixture runner 或重复实验。

## 2. Report Metadata

完整可比报告可以保存以下 comparability metadata：

- case fingerprint；
- runtime/model/version fingerprint；
- AgentTeam build/compiler fingerprint；
- repository/Workspace state fingerprint；
- tool/permission fingerprint；
- keyed task-payload fingerprint；
- cache state：`cold`、`warm` 或 `unknown`；
- outcome：`success`、`failure` 或 `unknown`；
- fixed analysis scope 和 window/run identity。

Portable report 删除 Agent/Run 明细，不暴露 exact model、repository path、task body
或 raw ID，只保留 aggregate evidence 和 fingerprint。

当前自然流量报告稳定提供 scope fingerprint；portable export 在本地报告有
runtime/model evidence 时派生 runtime fingerprint。build、case、Workspace、tools
等 fingerprint 仍为空，cache/outcome 为 `unknown`，因此当前结果通常只能是
`descriptive`，不会进入 `comparable`。

Scope fingerprint 必须能跨 daemon lifetime 和报告文件稳定比较，并且只能由
code-controlled window、scope kind 和 Agent 数量派生，不能编码 Agent/Run
identity。Machine-local Agent/Run ref 必须使用 daemon-lifetime 随机 salt，不能
承担 comparability。

Scope fingerprint 只描述 analysis selector，不能证明任务输入相同。`comparable`
还必须有相同的 task-payload fingerprint。该 fingerprint 由 model-visible 的
message/task/scope payload 派生，排除 message/run/turn/delivery/attachment 等
attempt-local ID 和时间戳，再使用 machine-persisted keyed hash 转成 portable
identity。Artifact 只保存 keyed fingerprint，不保存 payload、raw ID 或未加 key
的 body hash。由于现有 attachment metadata 不能证明附件内容相同，带附件的
payload 在没有 content identity 时标记为 identity unavailable。Attribution
必须显式区分 no task payload 与 task payload identity unavailable；聚合只能忽略
前者。一个 Run 含有 unavailable/非法 identity，或包含多个不同 payload identity
时，只能是 `descriptive`；两侧有效 identity 不同时为 `not_comparable`。

## 3. Comparability

Comparison state：

- `comparable`：所有 required fingerprint、cache state 和 analysis scope 一致；
- `descriptive`：自然流量或 outcome/cache 未受控，只能查看差异；
- `not_comparable`：关键 runtime/model、case、repository、tool/permission 或 scope 不一致。

`not_comparable` 只显示 mismatch reason，不计算 amplification 或 savings conclusion。
cold/warm cache、outcome 或受控 fingerprint 不同都属于 `not_comparable`。保存的
run-scoped artifact 已由 `snapshotAt` 冻结，因此常驻 interactive Run 在该时点仍
为 active 不会单独阻止比较；操作者仍必须在目标任务 outcome 已确定后导出。

`descriptive` 可以显示 raw delta，但必须明确“不构成因果或净节省证据”。

受控实验必须由操作者在 run-scoped analyze 时声明：

- 同一个 `case`；
- 唯一 `changedVariable`，例如 `platform.agentteam.exec`；
- 相同 Workspace revision 和 tool/permission profile；
- 相同受控 task payload；
- 分开运行且两侧相同的 `cacheState`（`cold` 或 `warm`）；
- 两侧相同且为 `success` 的 outcome；`failure` 只能诊断，不进入 comparable。

Candidate 的正常 build fingerprint 可以因唯一 declared variable 而不同；其余
fingerprint 必须一致。未声明 changed variable 时 build 仍必须一致，否则不可比。
自由文本 case/Workspace/tool 值在报告前哈希，不进入 portable artifact。

## 4. 输出

字段可用时 comparison 输出：

- cumulative input delta 和 ratio；
- uncached input delta 与 cache-read delta；
- root model invocation count delta；
- AgentTeam-controllable materialized estimate delta；
- complete block ledger delta；

当前不输出 average-input、invocation-cause、outcome 或 data-quality delta；相应
evidence 不完整时保持缺失，而不是编码为零。Input 分母为零时 ratio unavailable。

完整 block ledger 不依赖 Top-N opportunity。任一 report 的 ledger truncated 时，block comparison 为 `limited`。

Comparison 不输出自动 `improved/regressed` verdict。开发者根据 Token delta、request delta 和 outcome 选择下一步。

## 5. 文件和隐私

Schema：

- analysis：`agentteam-token-analysis/v2`；
- comparison：`agentteam-token-comparison/v2`。

Import 最大 1 MiB，strict decode，并限制 enum、array、string 和 numeric range。Unknown schema 显式失败。

Artifact 不包含 Prompt/task/tool/model output、source path、Agent/Run 明细、Agent
display name、exact model 或 raw runtime ID。

## 6. 非目标

Comparison 不运行 benchmark/raw runtime，不维护 experiment registry，不计算统计置信度或自动 verdict，也不承担 CI gate 和长期趋势。

## 7. 验证要求

- fingerprint、task-payload identity 或唯一 changed variable 缺失时保持 descriptive；
- 非 run scope、cache/outcome mismatch 与未声明的 build mismatch 拒绝比较；
- comparable/descriptive/not_comparable；
- missing denominator；
-完整 ledger comparison；
- truncated/incomplete evidence；
- hostile import bound；
- portable privacy；
-不产生自动因果 verdict。