Token 五类
非缓存输入、cache read、cache write、output、reasoning 是五类语义；cache write 在代码中进一步拆成 TTL 未知、5m、1h 三个互斥字段，因此当前共 7 个字段。reasoning 是 output 子集，不重复计数。
- 定义
- 本次调用中没有命中输入缓存的输入 token。它与 cache read、cache write、output 四桶互斥。
- 数据来源
- Claude 读取 usage.input_tokens；Codex 用 inputTokens − cachedInputTokens，并把结果截到不小于 0。
- 计算方式
- max(0, input − cached input)。Claude 的 input_tokens 已作为非缓存输入直接记录。
- 已知局限
- 不同提供商的 usage schema 不同；来源未验证时整组 token 会标为 unavailable，不会猜成 0。
- 出现位置
- Insights 总览、成本与缓存页、会话明细。
- 定义
- 由提供商报告、从已有 prompt cache 读取的输入 token。
- 数据来源
- Claude 的 cache_read_input_tokens；Codex 的 cachedInputTokens。
- 计算方式
- 逐个去重后的 usage event 相加；Codex 会限制 cachedInputTokens ≤ inputTokens。
- 已知局限
- “命中缓存”不等于免费；真实折扣取决于提供商、模型与合同。
- 出现位置
- Insights 的 token 分桶、缓存效率与会话明细。
- 定义
- 写入或创建 prompt cache、但来源没有提供 TTL 拆分的输入 token。
- 数据来源
- Claude 只有 cache_creation_input_tokens 且没有 5m/1h breakdown 时记录；Codex 的 cacheWriteTokens 也进入此桶。
- 计算方式
- 逐个去重后的 usage event 相加；一旦 Claude 提供 TTL breakdown，聚合桶归零，改入 5m/1h 两桶，避免重复。
- 已知局限
- TTL 未知时不能套用 Anthropic 的 5 分钟或 1 小时写入价，因此估值可能保持 unpriced。
- 出现位置
- Insights 的 token 分桶、缓存效率与会话明细。
条件可用
Cache write 5m Token
#
- 定义
- 明确标记为 5 分钟 TTL 的 prompt cache 写入 token。
- 数据来源
- Claude usage.cache_creation.ephemeral_5m_input_tokens。
- 计算方式
- 逐个去重后的 usage event 相加，并与 TTL 未知/1h 桶保持互斥。
- 已知局限
- 只有来源持久化 TTL breakdown 时可用；聚合字段与 breakdown 不闭合会产生 warning。
- 出现位置
- Insights 缓存拆分、成本与定价追溯。
条件可用
Cache write 1h Token
#
- 定义
- 明确标记为 1 小时 TTL 的 prompt cache 写入 token。
- 数据来源
- Claude usage.cache_creation.ephemeral_1h_input_tokens。
- 计算方式
- 逐个去重后的 usage event 相加，并与 TTL 未知/5m 桶保持互斥。
- 已知局限
- 只有来源持久化 TTL breakdown 时可用；缺失不等于没有 1h cache。
- 出现位置
- Insights 缓存拆分、成本与定价追溯。
- 定义
- 模型输出 token 总量；如果提供商把 reasoning 作为输出子集报告，这里已经包含它。
- 数据来源
- Claude 的 output_tokens；Codex 的 outputTokens。
- 计算方式
- 逐个去重后的 usage event 相加。reasoning 不会再加一次。
- 已知局限
- 不同提供商对隐藏 reasoning 的可见性不同，不能跨来源假设完全同质。
- 出现位置
- Insights 总览、成本与缓存页、会话明细。
- 定义
- 提供商单独报告的 reasoning token 元数据；在 Swob 当前口径里它属于 output 的子集。
- 数据来源
- 当前由 Codex reasoningTokens 提供；Claude Code 本地 usage 未统一提供独立桶。
- 计算方式
- min(outputTokens, reported reasoningTokens)；仅作拆分观察，不计入 processed total 的额外加项。
- 已知局限
- 不是“思考质量”，也不能与 Session Audit 的 thinking block 指标互换。
- 出现位置
- 支持该字段的会话 token 明细；无来源证据时不展示为 0。
汇总、估值与数据质量
- 定义
- 面向 CLI Insights 的窄口径：输入与输出之和，不含 cache creation/read。
- 数据来源
- CLI command registry 与生成的 /swob skill 共同声明该机器接口契约。
- 计算方式
- inputTokens + outputTokens。
- 已知局限
- 不能当作账单 token，也不能和 billing total 直接比较；两者是否包含缓存桶不同。
- 出现位置
- swob insights 的 JSON/summary 输出。
- 定义
- 提供商 usage 事件经去重后，被处理的输入、缓存读写与输出总和。
- 数据来源
- NormalizedTokenComponents 与每个 provider 的 usage event。
- 计算方式
- 非缓存输入 + cache read + cache write(TTL 未知 + 5m + 1h) + output；reasoning 不重复相加。
- 已知局限
- “billing”描述处理范围，不代表已付账单；价格、折扣和合同不在这个数里。
- 出现位置
- Insights 总览与全局 token 汇总。
- 定义
- 只统计主对话 scope 的 processed total。
- 数据来源
- usageEvents 中 scope === main 的事件。
- 计算方式
- 先过滤主线程事件，再按 billing total 的四桶公式求和。
- 已知局限
- 会排除 sidechain、subagent、继承视图；不同 harness 对 scope 的记录能力不同。
- 出现位置
- Insights 的 conversation 范围筛选与会话分析。
- 定义
- 说明 token 是 reported、derived、estimated，还是 unavailable。
- 数据来源
- 每个 TokenAccounting 与 UsageEvent 的 provenance 字段。
- 计算方式
- 原始 usage 为 reported；累计计数做差为 derived；当前无可靠 schema 为 unavailable。
- 已知局限
- 来源标记说明证据链，不代表 reported 数据绝对无误。
- 出现位置
- Insights 数据质量提示与 Session Audit 证据标记。
- 定义
- 把已覆盖的 token 按对应模型公开 API 单价折算的比较值；界面总额保留底层 mode 明细，不等于用户实际支出。
- 数据来源
- 逐请求 UsageEvent 的模型、billing provider、事件时间、缓存 TTL 与内置版本化官方价格快照；日志自带金额优先。
- 计算方式
- 每个可定价桶按百万 token 单价与可验证的长上下文倍数计算，再按去重事件求和。
- 已知局限
- 不等于订阅现金支出；batch、非标准 service tier/speed、区域价或请求级模型证据不足时保守 unpriced。
- 出现位置
- Insights 总览、成本与缓存、数据质量、会话排名、Audit Report 与 Session Audit。
- 定义
- reported 是日志自带金额；estimated-list-price 是显式 provider 的精确目录估算；api-equivalent 是从模型推断原厂后的等价估算；unpriced 表示不能可靠定价。
- 数据来源
- Valuation.mode、UsageEvent.reportedCostUsd 与 providerProvenance。
- 计算方式
- 日志金额优先；否则只有请求级模型、provider、时间和计价修饰符都满足保守门槛时才查价格目录。
- 已知局限
- reported 只表示来源日志报告，并不自动等于信用卡账单；混合聚合必须继续展示 modeBreakdown。
- 出现位置
- Insights 定价追溯、Audit Report 与 Session Audit 估值证据。
- 定义
- 有可靠价格匹配的 token，占有可靠 token 数据总量的比例。
- 数据来源
- 每个 Valuation 的 coveredTokens 与 totalBillableTokens，跨去重事件聚合。
- 计算方式
- coveredTokens ÷ totalBillableTokens × 100；无 billable token 时，有金额证据为 100，否则为 0。
- 已知局限
- 高覆盖率只表示更多 token 找到价格，不表示价格等于账单；必须与金额 mode、missing reasons 和分析范围同屏。
- 出现位置
- Insights 数据质量、成本卡、会话排名与 Audit Report。
- 定义
- 没有足够、可靠的来源数据，不能计算该数字。
- 数据来源
- TokenAccounting.provenance === unavailable，并附 unavailableReason。
- 计算方式
- 总量与 components 均为 null；聚合时排除，绝不把它补成 0。
- 已知局限
- “不可用”不代表实际使用量为零，也不代表会话坏了。
- 出现位置
- Insights 汇总、数据质量提示、来源能力说明。
- 定义
- token 数量可用，但缺少足够精确的价格匹配，所以无法折算价值。
- 数据来源
- Valuation 的 unpriced mode 与 missingReasons；常见原因是模型/provider/时间缺失、目录无规则或计价修饰符未建模。
- 计算方式
- usd 保持 undefined；未覆盖量取 totalBillableTokens 与 coveredTokens 的差，不以 0 美元混入金额。
- 已知局限
- unpriced 与 token unavailable 是两个不同失败层；部分覆盖时总金额只代表已定价部分。
- 出现位置
- Insights 成本卡、定价追溯、数据质量、报告与会话排名。
- 定义
- 本机 Swob 实际执行过的恢复尝试中，结果 ok 的比例。
- 数据来源
- Vault 根目录的隐私最小化 append-only 恢复尝试日志；不记录路径和诊断正文。
- 计算方式
- successes ÷ attempts；source-present、already-present、restored 都算成功，failed 算失败。
- 已知局限
- 它不是所有会话“可恢复率”；0 次尝试时底层值为 0，界面必须同时看 attempts=0，不能解读为 0% 成功。
- 出现位置
- Resume Audit / 恢复质量统计。
Session Audit 指标
全部实验 每项都应和 evidence、provenance、caveat 一起读。methodologyVersion 当前为 experimental-v2。
- 定义
- 读取工具次数 ÷ 编辑与写入工具次数。
- 数据来源
- 工具调用记录。
- 计算方式
- edits > 0 时 reads / edits；只有 reads 时取 reads；都没有时为 0。
- 已知局限
- 阈值未经验证，不能当成生产力或代码质量结论。
- 出现位置
- Session Audit 指标卡。
- 定义
- 把 Read/Edit 比映射为 healthy、degraded、critical 或 unavailable。
- 数据来源
- readEditRatio 与是否观察到读写工具。
- 计算方式
- ≥6 healthy；≥2 degraded；其余 critical；无读写为 unavailable。
- 已知局限
- 实验启发式，明确不进入健康分。
- 出现位置
- Session Audit 发现与指标卡。
- 定义
- 统计 thinking/signature block 的数量、签名/正文平均长度与脱敏数。
- 数据来源
- 转录中的 thinking block 形态。
- 计算方式
- 对可见 block 求数量和长度均值。
- 已知局限
- 只能说明记录形态，不能衡量推理深度或质量。
- 出现位置
- Session Audit 指标卡。
- 定义
- 相邻消息时间戳之差组成的逐轮序列。
- 数据来源
- 主线程用户/助手消息时间戳。
- 计算方式
- 只保留 0 到 1 小时内的正差。
- 已知局限
- 混合了排队、网络、工具和用户思考时间。
- 出现位置
- Session Audit 延迟明细。
- 定义
- 助手消息相对前一条消息的延迟分布。
- 数据来源
- 相邻消息延迟中的 assistant 项。
- 计算方式
- 排序后取 nearest-rank P50/P95 与最大值。
- 已知局限
- 不是端到端模型服务延迟，时间戳缺失时 unavailable。
- 出现位置
- Session Audit 指标卡与 findings。
- 定义
- 把会话 TokenAccounting 交给统一 Valuation 引擎，返回金额、mode、覆盖率、缺失原因与价格追溯。
- 数据来源
- 去重 UsageEvent 与内置版本化价格目录。
- 计算方式
- 逐请求按模型、provider、事件时间、缓存 TTL 和可验证的长上下文规则定价，再聚合。
- 已知局限
- API 等价值不是现金账单；无法精确匹配的请求保持 unpriced，不使用回退价。
- 出现位置
- Session Audit 估值卡与模型分布。
- 定义
- 只估算用户消息中可见的框架标签文本及其占可见用户文本的比例。
- 数据来源
- 转录里实际可见的 framework marker。
- 计算方式
- 字符数 ÷ 4 估 token，再除以同法估算的可见用户文本 token。
- 已知局限
- 绝不是隐藏 API context overhead，也不是 provider token attribution。
- 出现位置
- Session Audit 框架标记卡。
实验 · experimental-v2
会话类型
#
- 定义
- 按工具调用组合分类 coding/research/debugging/discussion/mixed。
- 数据来源
- 主线程工具调用计数与 Bash 错误。
- 计算方式
- 无工具为 discussion；编辑、搜索、报错 Bash、读取超过各自阈值时依次分类。
- 已知局限
- 代理分类且有顺序偏差，不是用户意图的事实标签。
- 出现位置
- Session Audit 概览。
- 定义
- 按模型汇总 assistant turn、input/output token 与静态估算成本。
- 数据来源
- assistant 消息 model 和 usage。
- 计算方式
- 按 model 分组求和并按 turns 降序。
- 已知局限
- 模型名和 usage 缺失会造成不完整；成本不是账单。
- 出现位置
- Session Audit 模型分布。
实验 · experimental-v2
工具效率
#
- 定义
- 对调用至少两次的工具统计次数、错误率和平均可观测延迟。
- 数据来源
- tool_use 与匹配的 tool_result。
- 计算方式
- errorRate = errorCount / count；平均延迟只使用可配对时间戳。
- 已知局限
- 缺失结果或时间戳不会被臆测；“效率”只是行为信号。
- 出现位置
- Session Audit 工具表。
- 定义
- 转录中命中中断标记的用户消息数量。
- 数据来源
- 可见用户文本中的 [Request interrupted 标记。
- 计算方式
- 逐条匹配并计数。
- 已知局限
- 依赖 harness 的持久化格式，未记录不代表没有中断。
- 出现位置
- Session Audit 交互指标。
- 定义
- 用可见用户消息数近似目标数，再计算平均轮数。
- 数据来源
- 主线程时间戳消息与用户消息计数。
- 计算方式
- turnIndex ÷ user message count；无用户消息时取 turnIndex。
- 已知局限
- 一条用户消息不一定等于一个目标，名称是启发式代理。
- 出现位置
- Session Audit 交互指标。
- 定义
- 检测重复读取和连续重编辑等工具行为模式。
- 数据来源
- 工具名、路径与 turn index。
- 计算方式
- 超过动态阈值的重复 Read，或相邻 Edit/Write 命中同一路径。
- 已知局限
- 可能是合理工作流；仅供调查，不能单独判错。
- 出现位置
- Session Audit findings 与证据列表。
- 定义
- 检测快速短纠正、关键词、重复指令和中断。
- 数据来源
- 可见用户文本与时间戳。
- 计算方式
- 基于固定中英文关键词和时间/重复规则。
- 已知局限
- 语言、语气和上下文会产生误报与漏报。
- 出现位置
- Session Audit findings 与证据列表。
- 定义
- 从 80 分基线按已触发的实验因子扣分，再限制在 0–100。
- 数据来源
- frustration、anti-pattern、redacted thinking 三类 scoreFactors。
- 计算方式
- 80 + impacts；当前 Read/Edit 健康带不扣分。
- 已知局限
- 未经验证的透明启发式，不是客观质量评分。
- 出现位置
- Session Audit 顶部总览。
- 定义
- 把健康分映射为 excellent/good/fair/poor。
- 数据来源
- healthScore。
- 计算方式
- ≥80 excellent；≥60 good；≥40 fair；否则 poor。
- 已知局限
- 继承健康分的全部实验性局限。
- 出现位置
- Session Audit 顶部总览。
- 定义
- 列出每个加减分原因、影响值和行级证据。
- 数据来源
- 审计规则命中结果。
- 计算方式
- 当前只生成扣分项并对 impact 求和。
- 已知局限
- 规则集会随 methodologyVersion 演进；跨版本不宜直接排名。
- 出现位置
- Session Audit 分数解释。
实验 · experimental-v2
审计发现
#
- 定义
- 把达到提示阈值的指标转成可读调查线索。
- 数据来源
- Read/Edit、挫败、反模式、脱敏 thinking、P95 延迟。
- 计算方式
- 按固定条件生成字符串列表。
- 已知局限
- 是线索摘要，不是新的独立测量，也不应脱离证据阅读。
- 出现位置
- Session Audit findings。
