dsh-recent-usage-metrics 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 更新记录
 
+## 0.2.2
+
+- 修复：切换模型后抽屉卡在旧的一轮。数据源的 target 曾被缓存，而会话重建
+  （换模型、重连、binding 释放）会替换掉它依赖的视图存储，旧闭包于是永远返回
+  最后一份快照。现在每次都取当前 target，并按秒重新绑定。
+
 ## 0.2.1
 
 - 发布流程改为 GitHub Actions 的 OIDC trusted publishing：推 `v*` 标签即自动发布，

package/README.en.md

@@ -281,14 +281,32 @@ built, and undated rows keep showing `--` — the previous behaviour, with no er
 
 ## Install
 
+Published to npm as `dsh-recent-usage-metrics`:
+
 ```powershell
-# from the dsh GUI's Plugin Manager, or:
-#   plugin_manager install_bundle with target = this directory
+# from the dsh GUI's Plugin Manager, or directly:
+npm install dsh-recent-usage-metrics
 ```
 
-The bundle links this directory into the profile, so editing `client/client.js` and
-reloading the page picks up the change. Host-side code never needs a restart because
-there is none.
+It can also be added to the profile's `package.json` dependencies and installed from there.
+
+**Development mode**: point the profile dependency at this directory with `link:`, so editing
+`client/client.js` and reloading the page picks up the change. Host-side code never needs a
+restart because there is none.
+
+## Release
+
+Pushing a `v*` tag publishes automatically through GitHub Actions, authenticated with OIDC
+trusted publishing — **no npm token is involved**.
+
+```powershell
+npm version patch          # bump the version and create the tag
+git push --follow-tags     # push, and the release publishes itself
+```
+
+The workflow first checks that the tag matches the `package.json` version and fails on a
+mismatch, so a wrong version cannot slip out. Published tarballs carry a provenance statement,
+visible on the package page.
 
 ## Layout
 
@@ -299,6 +317,8 @@ there is none.
 | `cordis.patch.yml` | The one inserted Loader row |
 | `locale/en.json`, `locale/zh.json` | Plugin Manager title and description |
 | `icon.svg` | Plugin icon |
+| `CHANGELOG.md` | What changed in each version |
+| `.github/workflows/publish.yml` | Publishes to npm when a tag is pushed |
 | `test/lifecycle.cjs` | Runs the real client against a DOM/hook shim: metrics, ten-row cap, insertion order, click/open, disposal |
 | `test/repro-coldstart.cjs` | Regression: a cold page must paint Chinese and stay switchable both ways |
 | `test/repro-hmr.cjs` | Regression: a reload must not collide with the live dictionary claim |
@@ -379,9 +399,32 @@ const target = uiConversation.binding(sessionId).target('stats')
 ```
 
 That data comes from the Host-side `sessionStats` fold over the session log, and each step
-carries `ttft`, `model`, `decode`, `tps`, `output` and `wall`. The Statistics page prints
-its first-token figure as `firstToken − step/start`, so the two agree row for row instead of
-being two parallel calculations kept in step by hand.
+carries `ttft`, `model`, `decode`, `tps`, `output` and `wall`.
+
+**How the columns map:**
+
+| Drawer column | Field | Note |
+| --- | --- | --- |
+| At | `startTime` | the `step/start` moment, same as the Statistics view |
+| TTFT | `ttft` | `firstToken − startTime` |
+| Speed | `tps` | `output ÷ decode` |
+| Tokens | `output` | the provider's reported usage |
+| **Time** | **`model`** | **model time, not the Statistics view's total** |
+| Amortised | `output ÷ model` | this plugin's own figure |
+
+**Why the total is `model` and not `wall`:**
+
+The Statistics view's total column is `wall = endTime − startTime`, which **includes the step's
+tool calls**. A step that thinks for 11.5 s and then runs a 31 s command shows `wall` 41.9 s but
+`model` 11.5 s. This plugin measures model output only, so it reports `model` — a figure that
+contains no tool time by construction, and is therefore final the moment the reply lands.
+
+**Why the figures carry `~` while streaming:**
+
+Until the model finishes, the Host has no `usage` from the provider, so `output` is `null`. The
+plugin falls back to a character estimate (coefficients fitted per content type), which is why
+those figures carry `~`. The moment `usage` arrives — which is essentially the same instant the
+reply completes — the measured value takes over and the `~` disappears.
 
 **Why the history is no longer stored locally:**
 

package/README.md

@@ -249,13 +249,30 @@ Chat 存储从实时 token 增量中累积它，而会话日志不存 live chunk
 
 ## 安装
 
+已发布到 npm，包名 `dsh-recent-usage-metrics`：
+
+```powershell
+# 在 dsh GUI 的插件管理器里搜索并安装，或直接：
+npm install dsh-recent-usage-metrics
+```
+
+也可以把它加进 profile 的 `package.json` 依赖，再由插件管理器安装。
+
+**开发模式**：把 profile 里的依赖改成 `link:` 指向本目录，这样改完 `client/client.js`
+刷新页面即可生效。宿主侧代码永远不需要重启，因为它本身就存在。
+
+## 发布
+
+推 `v*` 标签即由 GitHub Actions 自动发布，认证走 OIDC trusted publishing，
+**不需要任何 npm token**。
+
 ```powershell
-# 在 dsh GUI 的插件管理器中安装，或：
-#   plugin_manager install_bundle，target 指向本目录
+npm version patch          # 改版本号并打 tag
+git push --follow-tags     # 推送后自动发布
 ```
 
-该 bundle 把本目录链接进 profile，因此改完 `client/client.js` 刷新页面即可生效。
-宿主侧代码永远不需要重启，因为它本身就存在。
+工作流会先校验标签与 `package.json` 的版本一致，不一致直接失败，避免发错版本。
+发布产物带 provenance 签名，npm 上可在包页面看到来源证明。
 
 ## 目录结构
 
@@ -266,6 +283,8 @@ Chat 存储从实时 token 增量中累积它，而会话日志不存 live chunk
 | `cordis.patch.yml` | 唯一插入的那一行 Loader 条目 |
 | `locale/en.json`、`locale/zh.json` | 插件管理器里显示的标题与说明 |
 | `icon.svg` | 插件图标 |
+| `CHANGELOG.md` | 各版本改动 |
+| `.github/workflows/publish.yml` | 推标签时自动发布到 npm |
 | `test/lifecycle.cjs` | 在 DOM/hook shim 上跑真实的客户端：指标、十行上限、插入顺序、点击开合、清理 |
 | `test/repro-coldstart.cjs` | 回归：冷页面必须首屏中文，且双向可切换 |
 | `test/repro-hmr.cjs` | 回归：重载不得与存活的字典占用冲突 |
@@ -278,6 +297,8 @@ node test/repro-hmr.cjs
 $env:ELECTRON_RUN_AS_NODE='1'; & "C:\Cinstall\ProgramTools\DSH\DeepSeek Harness.exe" test\repro-log.cjs
 ```
 
+四套共 227 项检查。
+
 ## 用真实会话日志复核
 
 统计页的数字来自磁盘上的会话日志：
@@ -336,8 +357,31 @@ const target = uiConversation.binding(sessionId).target('stats')
 ```
 
 那份数据由宿主侧的 `sessionStats` fold 从会话日志算出，每步都带着 `ttft`、`model`、
-`decode`、`tps`、`output`、`wall`。统计页自己显示的首 token 就是
-`firstToken − step/start`，因此两边逐行一致，不再存在两套口径。
+`decode`、`tps`、`output`、`wall`。
+
+**字段对应关系：**
+
+| 抽屉的列 | 取自 | 说明 |
+| --- | --- | --- |
+| 时间 | `startTime` | `step/start` 的时刻，与统计页一致 |
+| 首字 | `ttft` | `firstToken − startTime` |
+| 速度 | `tps` | `output ÷ decode` |
+| 输出 Token | `output` | 上游返回的 usage |
+| **总用时** | **`model`** | **模型用时，不是统计页的「总用时」列** |
+| 折算速度 | `output ÷ model` | 本插件独有 |
+
+**总用时为何取 `model` 而不是 `wall`：**
+
+统计页的「总用时」列是 `wall = endTime − startTime`，它**把工具调用也算了进去**。
+一个思考 11.5 秒、随后跑 31 秒工具的步骤，`wall` 是 41.9 秒而 `model` 是 11.5 秒。
+本插件只统计模型输出性能，所以取 `model`——它天然不含工具时间，回复一落地就是最终值，
+不再随工具执行增长。
+
+**流式期间为什么带 `~`：**
+
+模型正在输出时，宿主还没拿到上游的 `usage`，此时 `output` 为 `null`。
+插件改用字符估算（按内容类型分别标定系数），所以那段数字带 `~`。
+`usage` 一到（几乎就是回复完成的同一刻），立刻切成实测值，`~` 消失。
 
 **为什么不再本地保存：**
 
@@ -348,16 +392,18 @@ const target = uiConversation.binding(sessionId).target('stats')
 现在：
 
 - 抽屉的行在每次渲染时从该会话自己的统计数据重建，没有本地副本可以过期
-- 收到会话切换的消息时立刻清空，避免新数据到达前短暂显示上一个会话的行
+- 快照带会话标记，切换会话的瞬间旧数据即失效，不会短暂显示上一个会话的行
 - 页面刷新后自动从日志重建，不需要额外的持久化
 
 **视图目标需要先订阅才会存在**（`getSnapshot` 在订阅前返回 `undefined`）。插件在
 `apply` 时按会话订阅一次；激活是永久且共享的，所以不会在统计页之外再跑一份 fold。
 
-**降级路径**：若某个组装没有统计页数据（`uiConversation` 不存在），抽屉退回原先的
-Chat 快照 + 轨迹域算法，并按估算标记 `~`。这条路径只在缺少统计数据时生效。
+**拿不到统计视图时**，插件自动退回 Chat 快照 + 轨迹域自行计算（兜底路径）。
+这条路径不落盘、也按会话隔离，但它读不到 `model`，所以三态会退化为两态。
+它的字符估算系数与主路径相同。决定走哪条路径的唯一依据是那份数据源在不在，
+没有任何开关参与。
 
-**流式期间不读统计数据**：那套 fold 每来一个 chunk 就会重建整张表。状态栏的实时读数
-走另一条更轻的路径（轨迹域的 `step/start` 时刻 + 每 150 ms 的本地 tick），
-只在步骤结算后读一次统计数据定稿。这样既保住了「数字从 0 开始爬」的观感，
-也不会在流式期间额外增加 fold 的负担。
+**流式期间不额外催动 fold**：那套 fold 每来一个 chunk 就会重建整张表，而它本来就由
+统计页或宿主驱动。状态栏的实时读数在回复完成前用字符估算与本地 tick，回复一落地
+（`model` 有值）就切到折叠给出的实测值。这样既保住了「数字从 0 开始爬」的观感，
+也不会因为插件而多跑一份 fold。

package/client/client.js

@@ -2155,12 +2155,12 @@ window.__ModuleLoader__.load({
        * subscribes. Reading it inline during render froze the rows at whatever the first
        * render saw — which is why the drawer showed timestamps minutes behind the log.
        */
-      /*
-       * The shipped Statistics view's data source for this session. `undefined` when that
-       * view is absent — a composition without it — which is what routes the drawer to its
-       * Chat-snapshot fallback. No switch decides this: the presence of the source does.
-       */
-      const statsSource = typeof props.statsSource === 'function' ? props.statsSource() : undefined
+      /*
+       * The shipped Statistics view's data source for this session. `undefined` when that
+       * view is absent — a composition without it — which is what routes the drawer to its
+       * Chat-snapshot fallback. No switch decides this: the presence of the source does.
+       */
+      const statsSource = typeof props.statsSource === 'function' ? props.statsSource() : undefined
       const statsSubscribe = useCallback(
         (listener) => {
           if (statsSource === undefined || typeof statsSource.subscribe !== 'function') {
@@ -2183,10 +2183,45 @@ window.__ModuleLoader__.load({
         [statsSource, sessionId],
       )
       const [statsSnapshot, setStatsSnapshot] = useState(statsRead)
+      /*
+       * Re-point the subscription at whatever target is current, then re-read.
+       *
+       * A conversation that is rebuilt underneath the drawer (a model switch, a reconnect, a
+       * released binding) replaces its `BoundConversation`, and with it the view store the old
+       * `target()` closure captured. Refreshing on every render rebinds the listener to the new
+       * target, so the drawer cannot keep rendering a retired snapshot while the Statistics page
+       * has already moved on.
+       */
+      if (statsSource !== undefined && typeof statsSource.refresh === 'function') {
+        statsSource.refresh()
+      }
       useEffect(() => {
         setStatsSnapshot(statsRead())
         return statsSubscribe(() => setStatsSnapshot(statsRead()))
       }, [statsRead, statsSubscribe])
+      /*
+       * Follow a conversation that is rebuilt underneath the drawer.
+       *
+       * A model switch, a reconnect, or a released binding replaces the session's
+       * `BoundConversation`, and with it the view store the old `target()` closure captured.
+       * That stale closure keeps returning its last snapshot forever — which is exactly how the
+       * drawer froze on one turn while the Statistics page moved on.
+       *
+       * On a slow tick this re-points the listener at the target that is current now and
+       * re-reads the snapshot. Both are cheap (a map lookup and a field read) and neither
+       * depends on the stale chain firing.
+       */
+      useEffect(() => {
+        if (statsSource === undefined) return undefined
+        const sync = () => {
+          if (typeof statsSource.refresh === 'function') statsSource.refresh()
+          const next = statsRead()
+          if (next !== undefined) setStatsSnapshot(next)
+        }
+        sync()
+        const timer = setInterval(sync, 1000)
+        return () => clearInterval(timer)
+      }, [statsSource, statsRead])
       /*
        * A snapshot only counts while it belongs to the session being shown.
        *
@@ -2940,82 +2975,115 @@ window.__ModuleLoader__.load({
        */
       const statsSources = new Map()
       /*
-       * The Statistics target for one session, created on first use.
+       * The Statistics target for one session.
+       *
+       * The target object is looked up FRESH on every call rather than cached alongside the
+       * source. `uiConversation.binding(id)` keeps a `BoundConversation` per session, and that
+       * object owns the assembler and the view store; when the conversation is rebuilt — a model
+       * switch, a reconnect, a released binding — the old `target()` closure keeps pointing at
+       * the retired store and returns its last snapshot forever. Caching it froze the drawer on
+       * one turn while the Statistics page moved on.
        *
-       * `uiConversation.binding(id)` throws once that session is released, so a cached source
-       * can become stale. The cache is therefore bounded and evicts oldest-first, releasing
-       * the evicted target's subscription: without that, a long session that visits many
-       * conversations would keep one live subscription per conversation visited, and each of
-       * those keeps the conversation's fold active.
+       * Only the subscriptions are cached, because those must be released on eviction and
+       * re-subscribing on every render would multiply listeners.
        */
       const STATS_SOURCE_LIMIT = 4
       const statsSourceFor = (sessionId) => {
         if (sessionId === null || sessionId === undefined) return undefined
-        if (statsSources.has(sessionId)) {
+        const uiConversation = ctx.get('uiConversation')
+        if (uiConversation === undefined || uiConversation === null) return undefined
+
+        /** The target that is current right now, or undefined when it cannot be resolved. */
+        const targetNow = () => {
+          try {
+            return uiConversation.binding(sessionId).target(STATS_TARGET) ?? undefined
+          } catch {
+            // The session was released (or is inactive) — no statistics for it right now.
+            return undefined
+          }
+        }
+
+        const cached = statsSources.get(sessionId)
+        if (cached !== undefined) {
           // Refresh recency so the active conversation is the last one evicted.
-          const existing = statsSources.get(sessionId)
           statsSources.delete(sessionId)
-          statsSources.set(sessionId, existing)
-          return existing
+          statsSources.set(sessionId, cached)
+          return cached.source
         }
-        const uiConversation = ctx.get('uiConversation')
-        if (uiConversation === undefined || uiConversation === null) return undefined
-        let source
-        try {
-          const target = uiConversation.binding(sessionId).target(STATS_TARGET)
-          if (target === undefined || target === null) return undefined
-          /*
-           * Track the listener/unsubscribe pairs this source handed to the target, so
-           * eviction can drop them. The target's `subscribe` returns its own unsubscribe,
-           * but nothing else would call it once the source leaves the cache.
-           */
-          const subscriptions = new Map()
-          source = {
-            getSnapshot: () => target.getSnapshot(),
-            subscribe: (listener) => {
-              const existing = subscriptions.get(listener)
-              if (existing !== undefined) return existing.dispose
-              const unsubscribe = target.subscribe(listener)
-              const dispose = () => {
-                if (subscriptions.get(listener)?.unsubscribe !== unsubscribe) return
-                subscriptions.delete(listener)
-                try {
-                  unsubscribe()
-                } catch {}
-              }
-              subscriptions.set(listener, { unsubscribe, dispose })
-              return dispose
-            },
-            release: () => {
-              for (const [listener, entry] of [...subscriptions]) {
-                subscriptions.delete(listener)
-                try {
-                  entry.unsubscribe()
-                } catch {}
-              }
-            },
+
+        /*
+         * Each listener is bound to the target that was current when it subscribed; a listener
+         * whose target has since been replaced is re-bound the next time it asks, which is what
+         * keeps a drawn row tracking the live fold instead of a retired one.
+         */
+        const subscriptions = new Map()
+
+        const bind = (listener) => {
+          const target = targetNow()
+          if (target === undefined) return
+          const entry = subscriptions.get(listener)
+          if (entry !== undefined && entry.target === target) return
+          if (entry !== undefined) {
+            try {
+              entry.unsubscribe()
+            } catch {}
+            subscriptions.delete(listener)
           }
-        } catch {
-          // The session was released (or is inactive) — no statistics for it.
-          return undefined
+          try {
+            subscriptions.set(listener, { target, unsubscribe: target.subscribe(listener) })
+          } catch {}
+        }
+
+        const dispose = (listener) => {
+          const entry = subscriptions.get(listener)
+          if (entry === undefined) return
+          subscriptions.delete(listener)
+          try {
+            entry.unsubscribe()
+          } catch {}
+        }
+
+        const source = {
+          /** Always the newest snapshot the session's own target holds. */
+          getSnapshot: () => {
+            const target = targetNow()
+            return target === undefined ? undefined : target.getSnapshot()
+          },
+          subscribe: (listener) => {
+            bind(listener)
+            return () => dispose(listener)
+          },
+          /**
+           * Re-point every listener at the target that is current now.
+           *
+           * Called on each render: one map lookup per listener, and it is what lets the drawer
+           * follow a conversation that was rebuilt underneath it.
+           */
+          refresh: () => {
+            for (const listener of [...subscriptions.keys()]) bind(listener)
+          },
+          release: () => {
+            for (const listener of [...subscriptions.keys()]) dispose(listener)
+          },
         }
-        statsSources.set(sessionId, source)
+
+        statsSources.set(sessionId, { source })
         while (statsSources.size > STATS_SOURCE_LIMIT) {
           const oldest = statsSources.keys().next()
           if (oldest.done === true) break
           const evicted = statsSources.get(oldest.value)
           statsSources.delete(oldest.value)
           try {
-            evicted?.release?.()
+            evicted?.source?.release?.()
           } catch {}
         }
         return source
       }
       ctx.effect(
         () => () => {
-          for (const source of statsSources.values()) {
+          for (const entry of statsSources.values()) {
             try {
-              source.release?.()
+              entry.source.release?.()
             } catch {}
           }
           statsSources.clear()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-recent-usage-metrics",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Geek level for the Performance & usage setting: a live reading of the newest request (first-token latency, speed, tokens, total, amortised) plus a drawer listing the last ten, all derived from the shipped Statistics view data",
   "repository": {
     "type": "git",