description: "面向用户与维护者的具备回放感知的 token 与上下文压力计量说明：评估提示词规模或构建压缩（compaction）与占用显示。" kind: "package-reference"

@x1a0f3n9/dsh-token-meter

English | 中文

概述

使用 ctx.tokenMeter 估算会话当前的请求与上下文压力，或为单条消息计价。测量会回放持久会话日志，结果确定且不进行模型调用，因此压缩、占用显示与遥测可以共享同一结果。会话投影可用时，消费方可以读取 tokenUsage、contextPressure 与 contextBreakdown；文本和没有图片定价的路由采用近似的固定启发式规则，存在声明时应用视觉 token 定价，文件则按模型可见的句柄文本计价。只有请求 envelope 完全相同时才复用提供方报告的用量；本包不添加模型可见内容，也不在 loop 中做决策。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

当消费方需要为压缩决策、占用显示或遥测获取 token 或上下文压力时挂载本插件。估算器没有任何配置，也不添加模型可见表面；模型容量属于拥有精确提供方／模型路由的适配器，可通过 ctx.llm.resolveModelInfo().context 获取。

何时选择

当多个插件应该就同一种基于回放的测量达成一致时选择它——压缩规划、占用 UI 与压力检查都读取同一个 fold。测量回放持久会话日志，因此确定、无需模型调用，并精确反映已记录内容。文本和未声明图片定价的路由使用固定启发式规则；当部署需要精确到计费级别的计数时，使用提供方分词器。

测量压力

ctx.tokenMeter 暴露两个操作。measure(session, requestHeader?) 在同一个已消费日志 revision 上返回独立、深度不可变的快照：totalTokens 是请求与响应压力，surfaceTokens 是仅表面的路由定价总量，等于 nodes[].tokens 之和。可选 requestHeader 覆盖会选择计价路由与压力字段；节点集合仍描述当前会话。estimateMessage(message) 用固定启发式规则为一条消息计价。每次调用都会克隆带位置的表面节点，因此测量是 O(surface)。

const { totalTokens, surfaceTokens, nodes } = ctx.tokenMeter.measure(session)
const price = ctx.tokenMeter.estimateMessage(message)

每次测量都会通过可选的 llm 服务解析生效 envelope 的提供方／模型。适配器声明图片定价时，图片出现处使用路由请求的视觉 token 价格加模型可见文本，image/offload 事件选中的出现位置则按路由的占位文本计价，与表层实际发送的一致；其他路由保持固定启发式规则。文件出现处使用同一个 llm 服务为适配器分发解析的确切、与路由无关的 句柄文本，其中包含当前执行世界路径或明确的无路径说明。每个节点还携带与路由无关的 heuristicTokens，供替换影子价使用。只有当最新成功调用的规范请求 envelope 与已测量 envelope 匹配、且其总量不低于该调用完整路由定价锚点时，才复用提供方用量；否则会对完整当前 envelope 与表面做估算。表面变更保持相对于按同一路由重新定价的匹配锚点的带符号值，包括缩减替换后的负 delta。

测量锚点包含成功的 assistant/message 之前的已计价表面，包括 step/start 之后接纳的系统与用户消息，以及重试之前执行的替换。持久输出未变时，完成调用的表面增量为零：其提示词已包含在提供方用量中。后续表面变更仍是相对于该锚点的带符号增量。

会话投影

当组合提供 ctx.sessionProjections 时，token-meter 注册三个投影单元。tokenUsage 携带完整持久日志中的 uncachedInputTokens、outputTokens、cacheReadTokens 与 cacheWriteTokens。最终 assistant 消息样本会替换同一次尝试的流式用量；llm/retry-started 会结束该替换范围，因此同一步骤中的重试会贡献另一次计费用量。contextPressure 携带可选 pressureTokens（提供方报告的最新提示词规模）、可选 projectedTokens（下一个请求的提示词将花费多少）与来自最新一条 request/context 记录的可选 contextWindow。contextBreakdown 携带启发式 systemTokens、toolsTokens 与 messageTokens——上下文的构成，而非提供方计费规模。卸载插件会移除全部三个键。

图片省略重新计算现有节点的价格，同时保留此前的用量锚点。固定引用启发式规则不计入 offloaded 元数据，因此一次省略决定不改变 contextBreakdown 或标量启发式总量，按路由的测量则把所选图片的视觉价格换成占位文本价格。

contextBreakdown 把 surface 顺序中最后一个非空且存活的 system/message 归入 systemTokens；休眠的空节点不贡献 token，没有非空系统消息时为零。messageTokens 包含其余所有可见节点，包括被取代的提示词。在追加、已计量的压缩与裁剪、系统提示词改写或清空之后，两者之和等于 measure().nodes[].heuristicTokens；对非系统范围的未计量替换以零增量折叠，与 contextPressure 相同。toolsTokens 跟随最新 request/header。三个数字都使用固定启发式规则，而非路由图片定价或文件句柄投影；它们是近似构成，不是计费数据或 projectedTokens。

deriveTurnTokenUsage(events) 为浏览器消费方把一个完整轮次折叠为精确的逐次尝试与整轮用量。生命周期证据缺失、计数不安全或精确总量矛盾时不返回结果；只有每次参与的尝试都报告可选缓存、推理或路由值时，相应汇总才会出现。

组合

- name: '@x1a0f3n9/dsh-token-meter'
- name: '@x1a0f3n9/dsh-compaction-basic'

两个插件都有可用默认值。meter 只消费可选的 llm 服务，且仅用于解析路由声明的请求图片定价；压缩保持可选。部署会在 LLM（大语言模型）适配器上配置容量与图片定价，并在 dsh-compaction-basic 上配置压缩策略。

解读数字

占用是参考数字，不是计费记录：harness 中没有任何机制依据它做决定，压缩读取的是 measure()。UI 用测量压力除以所选模型独立解析的容量来计算占用。contextBreakdown 数字是估算值，其总和不会等于 projectedTokens；后者的提供方锚点恰好携带启发式误差——CJK 文本与 JSON schema 在每 token 四字符下严重低估。

理解实现

本节解释服务背后的设计；可观察行为已在使用本包中完整说明。

设计理念

服务建立在一个 fold 与一个锚点之上。每个会话都有隔离的回放状态——已消费事件游标、规范请求标头、已计价表面、步骤边界与测量锚点——通过折叠持久日志推进。只有当提供方用量的规范 envelope 匹配、且其总量不低于同一次调用的完整路由定价时，才用它锚定测量；否则会估算完整 envelope 与表面。与路由无关的 heuristicTokens 字段使替换影子价投影保持确定性。fold 是整体且分配全新的：格式错误事件会在任何变更前抛出，因此同一份日志每次重试都以相同方式失败。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | TokenMeter 服务：回放状态、fold、measure() 与 estimateMessage() | | src/estimate.ts | 固定启发式规则：每 token 四字符加块与角色开销 | | src/surface-fold.ts | 与 measure() 共享的位置表面 fold | | src/surface-projection.ts | O(1) 投影单元的影价协议 | | src/usage-projection.ts | tokenUsage 与 contextPressure 投影定义 | | src/breakdown-projection.ts | contextBreakdown 投影定义 | | src/client.ts | 面向投影消费方、可安全用于浏览器的客户端接口 | | src/turn-usage.ts | 精确逐次尝试与逐 Turn 用量的纯 fold |

Fold 流程

每次 measure() 调用都把 fold 同步到当前持久尾部，然后读取一份连贯快照。活日志截断若把日志缩短到已消费游标以下，会丢弃该会话的回放状态，并重新折叠保留前缀。fold 跟踪完整请求标头快照、步骤边界、表面追加与替换、成功 assistant 消息及提供方用量。用量锚点的提供方输出从 assistant 消息的精确内嵌流重新组装，与监听器对持久内容的改写相互独立；空的重组内容计价为零。

投影语义

contextBreakdown 只保留存活的 system/message 节点及其启发式价格、一个 surface 运行总量，以及至多一个已武装的影子价 claim；替换减去紧邻的 claim（其 shadowedSeqs 同时列出被移除的系统提示词），或减去被改写的那个系统提示词的保留价格（决策）。其状态取决于存活系统提示词的数量，而非消息数；状态版本 6 使位置检查点失效。contextPressure 是另一个标量影子价消费方：没有相邻 claim 的替换贡献零增量。用量 fold 保留一个最后样本槽，因为合法日志不会在更晚步骤报告用量后再次报告更早步骤的用量。

./estimate 导出无服务状态的文字与内容估算函数，供工具结果保留复用。图片的实际请求成本由模型适配器的 imageRequestPricing 提供。

进一步探索

当包级约定不够用时阅读以下页面。它们从计量服务逐步进入压缩消费方与共享类型。

• Token 计量子系统——ctx.tokenMeter 背后的测量语义。
• dsh-llm 服务——其容量元数据由 resolveModelInfo() 提供的模型调用服务。
• 压缩能力——读取 measure() 的压力敏感消费方。
• 投影 token 用量——projectedTokens 背后的设计与被否决的原子配对比较。
• LLM 流式子系统——本服务计价的消息与块类型。

模型体验

间接地，通过 dsh-compaction-basic 等消费方；服务本身不添加任何提示词、消息、schema、工具或模型调用。

KV Cache 影响

不直接失效；任何请求前缀变更都由点名的消费方负责。

已知限制与延期工作

这些限制说明计量在哪里停止、由未来工作接续。它们是当前包约束，不是通用 token 计量对比或任务积压。

• 固定启发式规则是近似值——没有可复用提供方用量的文本按字符数加结构开销计价，而非精确提供方分词器或请求序列化器；只有声明了定价的路由上的图片出现处携带提供方精确的视觉 token。

• 每次测量都克隆当前表面——连贯不可变快照让读取为 O(surface)，包括低于阈值的压力检查。

• 提供方用量只在规范 envelope 完全相同时可复用——工具、提供方、模型或调用配置变化会刻意回退到完整启发式估算；系统提示词变更在下一次成功调用之前按带符号的表面增量计量。

• 系统提示词改写不带影子价——循环替换 system 节点时没有紧邻的计量事件，因此 contextPressure.projectedTokens 以零增量折叠该替换，直到下一个用量样本；contextBreakdown.systemTokens 与 measure() 会立即按新提示词重新计价。

• 构成检查点保留当前 surface——精确的 system/message 分类需要位置条目；检查点大小和 surface 事件折叠成本为 O(当前保留 surface)。

• 窗口化恢复不能从存活尾巴恢复已被替换掉的 seq — ingestRestoredEvent 保留 usage 锚点和已被替换掉的 seq。缺少该 ingest 时，measure() 和 contextBreakdown 从存活尾巴和 prefixHot 快照当前 surface；它们不会重放已丢掉的 replace 区间。

开发备注

本开发备注是不具权威性的工作上下文：维护者备注与开放问题。已交付的行为与既定理由以上文、包代码和相关 Agent Note 为准。

• 固定每 token 四字符启发式规则会低估 CJK 文本与 JSON schema；复用用量时提供方锚点恰好携带该误差，请把构成行呈现为近似构成，绝不呈现为总量。
• 按提供方的精确分词器尚未决定；保持单一确定性启发式规则，正是让每个消费方的测量一致且回放稳定的原因。

用量 fold 在每次尝试内替换样本，总量不必单调。构成和测量共享位置替换规划器与固定估算器，因此启发式 surface 总量按构造一致。路由定价总量有意与之不同。