Context · Measurement contract

上下文统计口径

面向使用者和实现者，定义底部 Context 面板如何报告真实总量、可分类内容和无法直接重建的差额。

状态：已实现范围：Web / App 共用接口不包含：新的 UI 样式

01 · 结果必须回答三个问题

总共占用了多少？

优先使用 provider 返回的真实 input token；没有实测时才使用本地估算。

内容来自哪里？

按互斥分类展示 system、tools、MCP、skills、memory、messages，禁止重复计数。

哪些无法还原？

实测总量与已分类估算之间的正差额显示为“其他上下文（估算）”，不隐藏。

02 · 单次快照

当前分支
读取已压缩后的 rendered history、最近一次 system prompt 和冻结工具集。

本地分类
计算消息结构、工具 schema、Skills、Memory；嵌套项从父分类扣除。

provider 校准
合并同一 HEAD 的最近实测总量并计算未分类差额。

一个 API 响应只计算一次本地 breakdown。面板不能在同一响应中再次读取动态工具注册表，否则分类和 estimated 可能来自两个不同时间点。

03 · 互斥分类

分类	原料	精度与边界
Messages	rendered history；可见文本、thinking、tool input/result、memory prefetch	文本可重建；未持久化的原始图片按差额处理。
System prompt	最近一次实际记录的完整 system prompt	先计算完整值，再扣除 Skills、常驻 Memory 和 deferred catalog，避免重复。
Skills / Memory	实际注入 system prompt 的索引与常驻块	它们是 System prompt 的子组成，不得再次增加总量。
System tools / MCP tools	本轮冻结工具集的 provider schema	按工具的 `_mcp_server` 归入二者之一。
Deferred tools	system prompt 内的工具名目录	按实际发送的名称目录计，不按完整 description/schema 计。
Other context (estimated)	`provider total - classified estimate`	包含未持久化图片、provider 包装开销、临时 surface prompt 等无法可靠重建内容。

04 · 计算规则

classified = system_other + skills + memory + tools + mcp + deferred + messages other = max(0, provider_total - classified) displayed_used = provider_total if measured else classified free = max(0, window - displayed_used)

若本地分类估算高于 provider 实测，保留 provider 总量作为占用真值，并按统一比例收缩分类显示值；响应同时保留原始估算和校准系数，不能显示负数差额。

05 · 验收条件

同一响应中的 estimated 与分类原始合计来自同一次计算。
实测状态下，各展示分类之和等于 total_used；估算状态下等于 input_used。
切换分支或图发生变化后，旧 provider 实测不复用到新的 HEAD。
切换模型后立即使用新模型的 context window，并将旧模型实测降级为当前模型下的重新估算；下一次请求完成后再采用新模型的 provider 实测。
工具 input/result、thinking 和 memory prefetch 会改变 Messages 数值。
App 与 Web 只消费同一个 /api/sessions/{id}/context 合同，不各自重新估算。

06 · 实施证据

记录真实输入

system_prompt_node.py 按分支 HEAD 读取实际 system prompt；tool_snapshot_node.py 保存本轮冻结工具及其计价结果。

统一计算与校准

session_stats.py 负责分类、去重和 provider 总量校准；budget.py 负责冻结工具 schema 的估算。

同一接口消费

tree.py 只计算一次 breakdown，App 与 Web 由 context-breakdown-panel.tsx 展示同一响应。

test_session_stats_accuracy.py 覆盖结构化消息、未分类差额、超额校准、分支 ancestry、旧快照兼容、非推进 HEAD 子 Agent、冻结工具、动态注册表和模型切换；相关 Context 定向测试共 51 项通过。