ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 Token 计量:TokenMeasurement 与上下文压力投影

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessToken 计量上下文压力TokenMeasurement
想提前判断上下文快满了,却只拿到一个 token 总数。本文讲 TokenMeasurement 六个字段的含义、baseline 锚点与 estimated 兜底、TokenSurfaceNode 的影子价,以及 measure 与 contextPressure 的分工。

“上下文快满了”这句话在 DSH plugin 里有三种含义:已发生的压力、下一次请求的预估、以及表层按路由的定价总量。 它们来自不同的字段,用错就会出现“显示还有余量,请求却被压缩”的错位。先把计量快照读明白,再谈阈值。 DSH插件 想在状态栏显示压力可以,但别把显示值当成门控依据。

计量是快照,不是实时累计

TokenMeasurement 是一份在某个日志修订上的分离不可变快照。(来源)

它不是一个会自己长大的计数器。logRevision 表示生成该计量中每个字段时消费的持久事件数量,等于下一个未读事件序号。快照不可变,也不会随底层回放折叠推进而增长——想要新数据,就再调一次 measure()。

这条设计对插件很重要:你可以安全地把一份计量挂到消息上、放进缓存、或者跨异步边界传下去,不用担心它在背后被改写。反过来,也不要长期缓存它当“当前压力”,因为它只描述生成那一刻。

六个字段分别回答什么

每个字段对应一个不同的问题,混用就会得到错误结论。(来源)

字段回答什么
logRevision这份快照基于多少条持久事件
baseline这次计量用了哪种锚点
surfaceDeltaTokens表层内容相对锚点的带符号重定价
totalTokens当前请求与响应的非负压力
surfaceTokens表层的路由定价总量
nodes当前表层节点,按位置从头到尾

surfaceDeltaTokens 是唯一允许为负的字段:它保留相对于匹配锚点的增长与缩减,且两侧按同一路由重新定价。surfaceTokens 等于所有节点价格之和,这一点在排查“为什么两个数对不上”时最有用——先把节点价加一遍。

nodes 的顺序是表层顺序,不是 seq 顺序。表层顺序具有权威性:替换节点的持久 seq 可能高于位置排在其后的节点,所以不要按 seq 排序后再计价。

baseline 是锚点,estimated 是兜底

能复用提供方 usage 就复用,不能就整份重估。(来源)

每次计量都会通过 ctx.llm 把生效信封的路由 provider/model 解析为该路由声明的请求图片定价。因此图片出现处按“请求实际发送的视觉 token + 模型可见文本”计价;未声明定价的路由与组合保持固定启发式规则。

baseline.kind === 'usage' 的条件很严:最近一次成功的提供方调用具有相同的规范请求 envelope,且该调用的总量不低于其完整路由定价锚点。两个条件缺一不可,后者是为了保守——不能拿一个更小的 usage 去压低当前压力。

estimated 表示不存在可复用的保守 usage 锚点,服务自行对完整信封与表层定价。后续成功请求会替换早先的锚点。这条替换语义解释了一个现象:连续几次请求后,totalTokens 会跳一下,因为锚点换了,不是内容突然变多。

TokenSurfaceNode:节点价与影子价

一个节点有两个价:按路由的请求价,和与路由无关的启发式价。(来源)

TokenSurfaceNode 只有三个字段:seq、tokens、heuristicTokens。

tokens 是在被测路由下,该节点投影出的确切消息的请求压力 token:图片出现处若路由适配器声明了视觉定价,就按声明计价,否则用固定启发式。触发、保留与范围选择都读这个价。

heuristicTokens 是同一消息的固定启发式 token,与任何路由无关。它存在的理由是影子价协议:替换用这个值计价,使 O(1) 的投影折叠与它自己的追加保持一致。换句话说,tokens 服务“这次请求要花多少”,heuristicTokens 服务“折叠内部怎么算才自洽”。

这也意味着你不能用 heuristicTokens 做预算判断,也不该用 tokens 做跨路由比较。前者与路由无关,后者与路由强绑定。

ContextPressureProjection:给显示用,不给门控

三个字段不是一次原子观测,而是不同时刻的最后值。(来源)

ctx.tokenMeter.contextPressure(session) 同步读取最新记录的 pressureTokens 与 contextWindow;客户端投影还根据表层变化派生 projectedTokens。

  • pressureTokens — 最近一次请求的提供方 prompt 大小:未缓存输入加缓存读写,不含输出,因此不会随当前轮次流式输出增长;在提供方报告 usage 之前缺失。
  • projectedTokens — 下一次请求的 prompt 成本:pressureTokens 加上表层自此样本以来增减的启发式重估。只估算增量,所以既锚定提供方,又能在压缩遮蔽一段时立刻反应——pressureTokens 单独做不到,因为压缩本身不上报 usage。
  • contextWindow — 最新记录的路由容量,没有适配器声明时缺失。

官方特意写明:这些字段不是一次原子请求观测,切换模型时可能把新容量与上一条路由的压力配在一起,直到下一次请求报告 usage。这是有意的取舍,它是面向用户的参考值,不是计费或门控输入。

所以状态栏可以用它,做硬门控不行。要判断“下一次请求会不会爆”,应当自己调 measure()。

measure 与 contextPressure 不能互相替代

显示值不为新请求计价,请求计价只认 measure()。(来源)

measure(session, requestHeader?) 通过持久尾部重放计量当前请求压力与表层。requestHeader 会替换最近记录的 envelope 用于压力与节点计价,但节点集合始终描述当前会话表层。每次调用都会克隆这些位置节点,所以开销是 O(surface)。

这解释了两条使用建议:频繁轮询状态用 contextPressure(),它只读已记录值;准备发请求或做压缩决策用 measure(),它才会按新 envelope 重算。需要给单条消息估个价时,用 estimateMessage(message),它返回固定服务启发式下的内容与角色框定 token。

还有一条容易踩的边界:measure() 的锚点包含 assistant 消息之前的所有表层节点,包括 step/start 之后准入的输入。你在请求前临时注入内容,它会计入压力。

验证:接近上限时的压力与压缩触发

验证要同时看“显示值”“请求计价”和“压缩后的变化”,三处对齐才算通过。(来源) 六步:

  1. 构造一个未报告 usage 的会话,断言 contextPressure() 的 pressureTokens 缺失,而 measure() 仍返回可用计量。
  2. 让一次请求成功上报 usage,断言 pressureTokens 出现,且 baseline.kind 为 usage。
  3. 追加几条长消息,断言 projectedTokens 上升而 pressureTokens 不变。
  4. 触发一次压缩,断言 projectedTokens 立即下降,pressureTokens 仍停在旧样本。
  5. 把节点价逐个相加,断言等于 surfaceTokens;确认顺序按表层而非 seq。
  6. 换一个声明了图片定价的路由再 measure(),断言同一图片节点的 tokens 变化而 heuristicTokens 不变。

如果第 4 步没有下降,先确认压缩是否真的遮蔽了表层区间——projectedTokens 只看增量,不推测未发生的替换。

压缩产物侧的字段与边界,可以对照压缩产物与剪枝;引用预算的截断规则见会话引用预算。

一句话收束: 计量是不可变快照,六个字段分工不同,tokens 看路由、heuristicTokens 看折叠,显示值不做门控,请求计价只认 measure()。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 TokenMeasurement 会随会话继续增长吗?

不会,DSH plugin 的计量是一份分离不可变的快照。DSH plugin 用 logRevision 记录生成各字段时消费的持久事件数,快照本身不会随底层回放折叠推进而变大。

DSH plugin 的 surfaceTokens 与 totalTokens 是一回事吗?

不是,DSH plugin 把两者分开定义。DSH plugin 的 totalTokens 是非负的请求与响应压力,surfaceTokens 是表层按路由计价的总量,等于所有节点价格之和。

DSH plugin 的 contextPressure 能用来做预算门控吗?

不建议,DSH plugin 明确说它是面向用户的参考值。DSH plugin 的三个字段分别是不同时刻的最后值,切换模型时可能把新容量与旧路由压力配在一起,不适合计费或门控。

DSH plugin 的 projectedTokens 为什么在压缩后还能变化?

因为 DSH plugin 只估算增量。DSH plugin 用最近一次请求的压力加表层增减的启发式重估,压缩遮蔽一段表层时增量会立即反映,而单纯的 pressureTokens 做不到这一点。

相关术语

TokenMeasurement
TokenMeasurement 是在某个已消费日志修订上的分离不可变请求压力与表层快照,含六个只读字段。— packages/llm/token-meter/src/types.ts
logRevision
logRevision 是生成该计量中每个字段时消费的持久事件数量,等于下一个未读事件序号。— packages/llm/token-meter/src/types.ts
TokenSurfaceNode
TokenSurfaceNode 是当前有序表层里的一个计价节点,含事件 seq、请求压力 tokens 与路由无关的 heuristicTokens。— packages/llm/token-meter/src/types.ts
ContextPressureProjection
ContextPressureProjection 是面向状态显示的压力近似值,含 pressureTokens、projectedTokens 与 contextWindow。— packages/llm/token-meter/src/projection.ts

来源