dsh-tokenlens 1.7.8 → 1.7.9

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 **版本记录约定**：同一发布日只保留一个章节，标题取当日**最后一个**已发布版本号；当日多次发布的改动合并到该章节，并在标题下注明当日实际发布过的版本号（npm 上仍可安装这些独立版本）。若当日已有发布，后续小改动不再单独增加版本号，而是并入下一篇日志。这样日志按天规整、不出现同日多个小版本。
 
+## 1.7.9 — 2026-11-10
+
+（当日已发布版本：v1.7.7 / v1.7.8 / v1.7.9）
+
+- **feat(stats): TPS 分母改为「纯解码时长」**——从 `step/start → assistant/message` 改为 `首个流式 token → assistant/message`，与 DSH 原生会话统计、上下文洞察插件**完全同口径**。此前的分母含首 token 等待（prefill + 排队），导致本插件数字只有对方的一半
+  - 实测对照（12 个会话、8,414 个 step）：旧口径 72.3 tok/s，新口径 144.1 tok/s，平均首 token 等待 5.36 秒——**差距正好 2 倍**
+  - 实机验证：`2026-10-23` 的日均从 `30.5` 变为 `185.2 tok/s`
+- **feat(stats): 首 token 等待不再被吞掉**——同一个样本同时累加 `ttftSeconds`，卡片右上角显示「首 token 均值 X.Xs」，悬停读数里也带上该点的首 token 均值。口径统一了，但延迟这个真实成本仍然可见
+- **feat(stats): 首 token 的取法**——`step/start` 记录里没有这个字段，它藏在 `assistant/message.data.stream` 的 chunk 计时里（`time` 或增量组 `time0`），取其中最早的绝对时刻
+- 覆盖率实测：223 个会话、42,912 个 step 中 **99.99%** 有可用首 token 时间、覆盖 100% token；缺首 token 的 step 会被跳过而不是混入另一个分母（曲线不能有两种口径）
+- 缓存 schema 7 → 8，首次会重扫（223 文件约 15 秒）
+- 文档：`PROTOCOL.md` 的 `speed` 段更新为解码口径并补 `ttftSeconds`
+- 测试：377（口径与首 token 断言改写为解码窗口真值；新增「缺 stream 的 step 不得编造时长」）
+
 ## 1.7.8 — 2026-11-10
 
 （当日已发布版本：v1.7.7 / v1.7.8）

package/PROTOCOL.md

@@ -383,24 +383,28 @@ with `[path]`.
                            "hours": [0, 0, 0, 500, 734, …] }
         } }
     ],
-    // v1.7.0: output-speed (TPS) series. `tps` is output tokens over the summed
-    // model time of the steps that produced them (`step/start` ->
-    // `assistant/message`), so a step's tool calls — which are emitted after the
-    // message — do not dilute it. A day with no positive duration is omitted
-    // instead of being given an infinite rate. `total.tps` is null when the
-    // window holds no samples. Each provider row carries its own `speed` object
-    // with the same shape, following the same window as its tokens (v1.7.2).
+    // v1.7.0: output-speed (TPS) series. v1.7.9 CHANGED the denominator: `tps`
+    // is output tokens over the summed DECODE time of the steps that produced
+    // them (`first streamed token` -> `assistant/message`), which is the same
+    // pairing the harness's own session statistics and the 上下文洞察 plugin use.
+    // The prefill/queue wait it therefore excludes is reported separately as
+    // `ttftSeconds` (summed first-token waits for the bucket), so the card can
+    // show it instead of hiding it. A day with no positive decode time, or a
+    // step whose first-token instant is unknown, is omitted rather than given an
+    // invented duration. Each provider row carries its own `speed` object with
+    // the same shape, following the same window as its tokens (v1.7.2).
     "speed": {
       "byDay": [
-        { "day": "2026-11-05", "outputTokens": 516951, "seconds": 8493.1,
-          "tps": 60.9, "steps": 859,
+        { "day": "2026-11-05", "outputTokens": 516951, "seconds": 3201.4,
+          "tps": 161.5, "steps": 859, "ttftSeconds": 4604.1,
           // v1.7.7: 24 local-hour slots for the click-to-drill-down view. A slot
           // with no sample is null rather than a zero, so the curve breaks
           // instead of dipping to zero. Only provider-scoped series carry it.
           "hours": [ null, null, …, { "outputTokens": 600, "seconds": 5,
-                                      "tps": 120, "steps": 1 }, … ] }
+                                      "tps": 120, "steps": 1, "ttftSeconds": 4.5 }, … ] }
       ],
-      "total": { "outputTokens": 939643, "seconds": 14123.9, "tps": 66.5, "steps": 1424 }
+      "total": { "outputTokens": 939643, "seconds": 5819.8, "tps": 161.5,
+                 "steps": 1424, "ttftSeconds": 7676.3 }
     },
     "zcode": {                                  // extra-harness detail
       "dbPath": "C:\\Users\\…\\.zcode\\cli\\db\\db.sqlite",

package/client.js

@@ -230,7 +230,8 @@ window.__ModuleLoader__.load({
       statsLast30Days: '最近30天',
       statsSpeedTitle: '输出速度（TPS）',
       statsSpeedHint:
-        '输出 Token ÷ 模型自身耗时（step 开始到消息返回）；不含工具调用等待，但输出含思考 Token。点击曲线上的某一天可查看该日的小时级速度',
+        '输出 Token ÷ 纯解码时长（首个 token 到达 → 消息结束），与 DSH 会话统计同口径；首 token 等待单独列出。点击曲线上的某一天可查看该日的小时级速度',
+      statsSpeedTtft: '首 token 均值 {seconds}s',
       statsSpeedTotal: '均值 {tps} tok/s',
       statsSpeedPeak: '峰值 {tps} tok/s',
       statsSpeedEmpty: '暂无可计算的速度样本（需要 step 计时数据）',
@@ -513,7 +514,8 @@ window.__ModuleLoader__.load({
       statsLast30Days: 'Last 30 days',
       statsSpeedTitle: 'Output speed (TPS)',
       statsSpeedHint:
-        'Output tokens ÷ the model’s own request time (step start to message); tool waits excluded, reasoning tokens included. Click a day on the curve for that day’s hourly speed',
+        'Output tokens ÷ pure decode time (first token → message end), the same pairing as the harness session stats; the first-token wait is listed separately. Click a day on the curve for that day’s hourly speed',
+      statsSpeedTtft: 'first token avg {seconds}s',
       statsSpeedTotal: 'avg {tps} tok/s',
       statsSpeedPeak: 'peak {tps} tok/s',
       statsSpeedEmpty: 'No speed samples yet (needs step timing data)',
@@ -1638,6 +1640,7 @@ window.__ModuleLoader__.load({
                       seconds: numberOrNull(cell.seconds) ?? 0,
                       tps,
                       steps: numberOrNull(cell.steps) ?? 0,
+                      ttftSeconds: numberOrNull(cell.ttftSeconds) ?? 0,
                     }
                   })
                 : null
@@ -1647,6 +1650,8 @@ window.__ModuleLoader__.load({
                 seconds: numberOrNull(entry.seconds) ?? 0,
                 tps: numberOrNull(entry.tps),
                 steps: numberOrNull(entry.steps) ?? 0,
+                // v1.7.9: the first-token wait the decode-only rate excludes.
+                ttftSeconds: numberOrNull(entry.ttftSeconds) ?? 0,
                 hours: hours === null ? null : hours.slice(0, 24),
               }
             })
@@ -1660,6 +1665,7 @@ window.__ModuleLoader__.load({
           seconds: numberOrNull(totalRaw.seconds) ?? 0,
           tps: numberOrNull(totalRaw.tps),
           steps: numberOrNull(totalRaw.steps) ?? 0,
+          ttftSeconds: numberOrNull(totalRaw.ttftSeconds) ?? 0,
         },
       }
     }
@@ -3679,6 +3685,8 @@ window.__ModuleLoader__.load({
 .dsh-tokenlens-repo{display:inline-flex;align-items:center;gap:4px;color:inherit;text-decoration:none;flex:0 0 auto;border-radius:var(--dsw-radius-sm);transition:color .12s ease,opacity .12s ease}
 .dsh-tokenlens-repo:hover,.dsh-tokenlens-repo:focus-visible{color:var(--dsw-alias-label-primary,currentColor);opacity:1;text-decoration:underline}
 .dsh-tokenlens-version-text{flex:0 0 auto}
+/* v1.7.9: the first-token wait sits beside the rate, visually secondary. */
+.dsh-tokenlens-speed-ttft{margin-left:8px;opacity:.8;white-space:nowrap}
 /* Update status on the plugin-version line (dialog body): wraps on narrow screens. */
 .dsh-tokenlens-version-update{white-space:normal;overflow-wrap:anywhere}
 .dsh-tokenlens-version .dsh-tokenlens-update-link{color:inherit;font-size:inherit;vertical-align:baseline}
@@ -6239,6 +6247,21 @@ window.__ModuleLoader__.load({
                 'span',
                 { className: 'dsh-tokenlens-hint', 'data-speed-total': String(series.total.tps) },
                 t('statsSpeedTotal', { tps: series.total.tps.toFixed(1) }),
+                // v1.7.9: the wait the decode-only rate leaves out, stated rather
+                // than hidden — it is often several seconds per step.
+                series.total.steps > 0 && series.total.ttftSeconds > 0
+                  ? h(
+                      'span',
+                      {
+                        key: 'ttft',
+                        className: 'dsh-tokenlens-speed-ttft',
+                        'data-speed-ttft': String(series.total.ttftSeconds),
+                      },
+                      t('statsSpeedTtft', {
+                        seconds: (series.total.ttftSeconds / series.total.steps).toFixed(1),
+                      }),
+                    )
+                  : null,
               )
             : null
           : h(
@@ -6437,6 +6460,10 @@ window.__ModuleLoader__.load({
                   tokens: formatTokensPrecise(hovered.outputTokens),
                   seconds: hovered.seconds.toFixed(1),
                 })}`,
+                // v1.7.9: the first-token wait, when this bucket has samples.
+                hovered.steps > 0 && hovered.ttftSeconds > 0
+                  ? ` · ${t('statsSpeedTtft', { seconds: (hovered.ttftSeconds / hovered.steps).toFixed(1) })}`
+                  : null,
               )
         const axis = h(
           'div',

package/index.js

@@ -84,7 +84,7 @@ export const inject = []
 export const PLUGIN_NAME = 'dsh-tokenlens'
 
 /** Plugin version; mirrors package.json (kept here so diagnostics need no fs read). */
-export const PLUGIN_VERSION = '1.7.8'
+export const PLUGIN_VERSION = '1.7.9'
 
 /**
  * Providers whose monthly allowance depends on the SELECTED model (v1.7.6).

package/lib/usage-stats.mjs

@@ -61,7 +61,7 @@ const DECODES_CONCATENATED_FRAMES = (() => {
 const SESSION_FILE = 'session.v4.jsonl.zstd'
 
 /** Cache schema version; a mismatch discards the cache. */
-const CACHE_VERSION = 7
+const CACHE_VERSION = 8
 
 /**
  * How many days the daily series (and therefore the 图表 mode and the
@@ -109,6 +109,38 @@ function usageFromStream(stream) {
   return null
 }
 
+/**
+ * The instant the model emitted its FIRST streamed byte (v1.7.9), or null.
+ *
+ * Decode-only output speed divides by `message.time − firstToken`, which is the
+ * same pairing the harness's own session statistics and the 上下文洞察 plugin use;
+ * it therefore excludes prefill/queue (the "首 token 等待"). The timestamp is
+ * not on `step/start` — it lives in the message's own `data.stream`, either as
+ * an absolute `time` on a chunk entry or as `time0` on a delta-encoded group.
+ * The earliest one wins, so the wait is never understated.
+ */
+function firstTokenTime(stream) {
+  if (!Array.isArray(stream) || stream.length === 0) return null
+  let earliest = null
+  for (const item of stream) {
+    if (item === null || typeof item !== 'object') continue
+    const at =
+      typeof item.time === 'number' && Number.isFinite(item.time)
+        ? item.time
+        : typeof item.time0 === 'number' && Number.isFinite(item.time0)
+          ? item.time0
+          : null
+    if (at === null) continue
+    if (earliest === null || at < earliest) earliest = at
+  }
+  return earliest
+}
+
+/** One output-speed accumulator (v1.7.9): decode seconds + first-token seconds. */
+function emptySpeedSlot() {
+  return { output: 0, seconds: 0, ttftSeconds: 0, steps: 0 }
+}
+
 /**
  * A JSON-able usage record from one event, or null when it is not billable usage.
  *
@@ -331,27 +363,42 @@ export function foldSession(records) {
     addBucket(dayProvider, usage)
     addBucket((providers[attributedProvider] ??= emptyBucket()), usage)
     // v1.7.0: one speed sample per completed step.
+    // v1.7.9: the denominator is the DECODE window (first streamed token ->
+    // message end), matching the harness's own session stats and 上下文洞察. The
+    // first-token wait is kept separately as `ttftSeconds` so the card can show
+    // it instead of silently folding it into the rate.
     if (record.type === 'assistant/message' && usage.output > 0) {
       const turn = record.data?.turn
       const step = record.data?.step
-      const startedAt = Number.isSafeInteger(turn) && Number.isSafeInteger(step)
-        ? stepStarts.get(`${turn}:${step}`)
-        : undefined
-      const elapsedMs = startedAt === undefined ? null : time - startedAt
-      if (elapsedMs !== null && elapsedMs > 0) {
+      const key = Number.isSafeInteger(turn) && Number.isSafeInteger(step) ? `${turn}:${step}` : null
+      const startedAt = key === null ? undefined : stepStarts.get(key)
+      const firstTokenAt = firstTokenTime(record.data?.stream)
+      // A step whose first-token instant is unknown is SKIPPED rather than mixed
+      // in with the old step-based denominator: two denominators on one curve
+      // would be incomparable. Coverage is 99.99% of steps in practice.
+      if (
+        startedAt !== undefined &&
+        firstTokenAt !== null &&
+        firstTokenAt > startedAt &&
+        time > firstTokenAt
+      ) {
+        const decodeSeconds = (time - firstTokenAt) / 1000
+        const ttftSeconds = (firstTokenAt - startedAt) / 1000
         const daySpeed = (speed[day] ??= { providers: Object.create(null) })
-        const slot = (daySpeed.providers[attributedProvider] ??= { output: 0, seconds: 0, steps: 0 })
+        const slot = (daySpeed.providers[attributedProvider] ??= emptySpeedSlot())
         slot.output += usage.output
-        slot.seconds += elapsedMs / 1000
+        slot.seconds += decodeSeconds
+        slot.ttftSeconds += ttftSeconds
         slot.steps += 1
         // v1.7.7: the hour bucket reuses `hour`, already computed for the token
         // histogram, so both drill-downs describe exactly the same slot.
         const hourSpeed = (speedHours[hour] ??= { providers: Object.create(null) })
-        const hourSlot = (hourSpeed.providers[attributedProvider] ??= { output: 0, seconds: 0, steps: 0 })
+        const hourSlot = (hourSpeed.providers[attributedProvider] ??= emptySpeedSlot())
         hourSlot.output += usage.output
-        hourSlot.seconds += elapsedMs / 1000
+        hourSlot.seconds += decodeSeconds
+        hourSlot.ttftSeconds += ttftSeconds
         hourSlot.steps += 1
-        stepStarts.delete(`${turn}:${step}`)
+        stepStarts.delete(key)
       }
     }
     const modelKey = `${attributedProvider}/${attributedModel}`
@@ -386,9 +433,10 @@ function mergeFold(aggregate, fold) {
   for (const [day, daySpeed] of Object.entries(fold.speed ?? {})) {
     const target = (aggregate.speed[day] ??= { providers: Object.create(null) })
     for (const [provider, slot] of Object.entries(daySpeed.providers ?? {})) {
-      const into = (target.providers[provider] ??= { output: 0, seconds: 0, steps: 0 })
+      const into = (target.providers[provider] ??= emptySpeedSlot())
       into.output += slot.output
       into.seconds += slot.seconds
+      into.ttftSeconds += slot.ttftSeconds ?? 0
       into.steps += slot.steps
     }
   }
@@ -396,9 +444,10 @@ function mergeFold(aggregate, fold) {
   for (const [hour, hourSpeed] of Object.entries(fold.speedHours ?? {})) {
     const target = (aggregate.speedHours[hour] ??= { providers: Object.create(null) })
     for (const [provider, slot] of Object.entries(hourSpeed.providers ?? {})) {
-      const into = (target.providers[provider] ??= { output: 0, seconds: 0, steps: 0 })
+      const into = (target.providers[provider] ??= emptySpeedSlot())
       into.output += slot.output
       into.seconds += slot.seconds
+      into.ttftSeconds += slot.ttftSeconds ?? 0
       into.steps += slot.steps
     }
   }
@@ -588,18 +637,20 @@ export function createUsageStats(input) {
       for (const [hour, hourSpeed] of Object.entries(entry.speedHours ?? {})) {
         const target = (speedHoursAggregate[hour] ??= { providers: Object.create(null) })
         for (const [provider, slot] of Object.entries(hourSpeed.providers ?? {})) {
-          const into = (target.providers[provider] ??= { output: 0, seconds: 0, steps: 0 })
+          const into = (target.providers[provider] ??= emptySpeedSlot())
           into.output += typeof slot.output === 'number' ? slot.output : 0
           into.seconds += typeof slot.seconds === 'number' ? slot.seconds : 0
+          into.ttftSeconds += typeof slot.ttftSeconds === 'number' ? slot.ttftSeconds : 0
           into.steps += typeof slot.steps === 'number' ? slot.steps : 0
         }
       }
       for (const [day, daySpeed] of Object.entries(entry.speed ?? {})) {
         const target = (speedAggregate[day] ??= { providers: Object.create(null) })
         for (const [provider, slot] of Object.entries(daySpeed.providers ?? {})) {
-          const into = (target.providers[provider] ??= { output: 0, seconds: 0, steps: 0 })
+          const into = (target.providers[provider] ??= emptySpeedSlot())
           into.output += typeof slot.output === 'number' ? slot.output : 0
           into.seconds += typeof slot.seconds === 'number' ? slot.seconds : 0
+          into.ttftSeconds += typeof slot.ttftSeconds === 'number' ? slot.ttftSeconds : 0
           into.steps += typeof slot.steps === 'number' ? slot.steps : 0
         }
       }
@@ -670,9 +721,10 @@ export function createUsageStats(input) {
       const dayEntry = (daySpeedHours[dayKey(hourStart)] ??= Object.create(null))
       for (const [provider, sample] of Object.entries(bucket.providers ?? {})) {
         if (sample === null || typeof sample !== 'object') continue
-        const series = (dayEntry[provider] ??= Array.from({ length: 24 }, () => ({ output: 0, seconds: 0, steps: 0 })))
+        const series = (dayEntry[provider] ??= Array.from({ length: 24 }, () => emptySpeedSlot()))
         series[slot].output += typeof sample.output === 'number' ? sample.output : 0
         series[slot].seconds += typeof sample.seconds === 'number' ? sample.seconds : 0
+        series[slot].ttftSeconds += typeof sample.ttftSeconds === 'number' ? sample.ttftSeconds : 0
         series[slot].steps += typeof sample.steps === 'number' ? sample.steps : 0
       }
     }
@@ -1436,25 +1488,31 @@ export function createUsageStats(input) {
       const byDay = []
       let output = 0
       let seconds = 0
+      let ttftSeconds = 0
       let steps = 0
       for (const day of Object.keys(source).sort()) {
         if (day < fromDay) continue
         let dayOutput = 0
         let daySeconds = 0
+        let dayTtftSeconds = 0
         let daySteps = 0
         for (const [id, slot] of Object.entries(source[day].providers ?? {})) {
           if (providerId !== null && id !== providerId) continue
           dayOutput += slot.output
           daySeconds += slot.seconds
+          dayTtftSeconds += typeof slot.ttftSeconds === 'number' ? slot.ttftSeconds : 0
           daySteps += slot.steps
         }
         if (daySeconds <= 0 || dayOutput <= 0) continue
         const entry = {
           day,
           outputTokens: dayOutput,
+          // v1.7.9: the DECODE window (first streamed token -> message end).
           seconds: Math.round(daySeconds * 10) / 10,
           tps: Math.round((dayOutput / daySeconds) * 10) / 10,
           steps: daySteps,
+          // The prefill/queue wait this rate excludes, so the card can show it.
+          ttftSeconds: Math.round(dayTtftSeconds * 10) / 10,
         }
         // v1.7.7: the day's 24 local-hour slots, for the click-to-drill-down
         // chart. Only a provider-scoped series carries them: the combined series
@@ -1470,6 +1528,8 @@ export function createUsageStats(input) {
                 seconds: Math.round(cell.seconds * 10) / 10,
                 tps: Math.round((cell.output / cell.seconds) * 10) / 10,
                 steps: cell.steps,
+                ttftSeconds:
+                  typeof cell.ttftSeconds === 'number' ? Math.round(cell.ttftSeconds * 10) / 10 : 0,
               }
             })
           }
@@ -1477,6 +1537,7 @@ export function createUsageStats(input) {
         byDay.push(entry)
         output += dayOutput
         seconds += daySeconds
+        ttftSeconds += dayTtftSeconds
         steps += daySteps
       }
       return {
@@ -1486,6 +1547,7 @@ export function createUsageStats(input) {
           seconds: Math.round(seconds * 10) / 10,
           tps: seconds > 0 ? Math.round((output / seconds) * 10) / 10 : null,
           steps,
+          ttftSeconds: Math.round(ttftSeconds * 10) / 10,
         },
       }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tokenlens",
-  "version": "1.7.8",
+  "version": "1.7.9",
   "type": "module",
   "description": "dsh-TokenLens (词元透镜) — provider-aware plan capacity plus local token statistics (today/7d/30d/all-time, by harness/provider/model/workspace) for DSH.",
   "license": "MIT",