dsh-all-usage 1.0.6 → 1.0.8

package/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to `dsh-all-usage` are documented here.
+
+## [1.0.8] - 2026-08-23
+
+### Added
+
+- Added a restart read-avoidance cursor: on startup the plugin uses the persisted log revision (via `sessionPersistence.listSnapshots()`, a header-line + stat read) as a per-session change signal. Sessions whose log is unchanged since the last ledger write are applied straight from the durable ledger without reading their full event log; only changed or new sessions are read (incrementally).
+- Stored the log revision in each durable ledger record (`lastRevision`); existing rows without it are re-read once and backfilled, so behavior is backward compatible.
+
+### Fixed
+
+- Eliminated the per-session full-event read at restart for unchanged persisted sessions, so DSH restarts no longer re-read every session's history from scratch.
+
+## [1.0.7] - 2026-08-23
+
+### Added
+
+- Added an incremental ledger cursor: baseline rescans reuse the durable ledger as a per-session cursor, so unchanged sessions seed from the ledger instead of re-folding every historical event, and changed sessions fold only the new tail.
+- Added an all-zero usage guard: zero-token usage replays no longer overwrite already-recorded turn/step usage, while pure cache-read requests (billable cache hits with no input/output) are still counted.
+- Added a structured, machine-readable token semantics declaration (`tokenSemantics.semantics`) to the `/api/all-usage` snapshot: input is fresh (excludes cache), cache and reasoning are separate buckets.
+
+### Fixed
+
+- Reduced startup scan cost on long usage history: sessions whose events are unchanged since the last ledger write are no longer re-folded or rewritten.
+- Prevented a live retry of an already-recorded step from double-counting after a fresh-instance seed.
+
+## [1.0.6] - 2026-08-23
+
+### Added
+
+- Added a durable per-session usage ledger written at the awaited `session/flush` boundary.
+- Preserved successfully flushed turns and token usage after conversation logs are deleted.
+- Added automatic rebuilds from ledger records after session disposal or reconciliation detects missing logs.
+
+### Fixed
+
+- Prevented stale baseline snapshots from overwriting newer flushed ledger records.
+- Normalized duplicate ledger keys during hydration and guarded ledger writes during plugin disposal.
+- Prevented inactive Cordis timer contexts from escalating into fatal DSH load failures.
+- Replaced invalid hyphenated storage unit names with valid underscore names.
+
+## [1.0.5] - 2026-08-20
+
+### Added
+
+- Added custom start/end date ranges across all available historical daily data.
+- Kept the heatmap as a fixed latest-53-week view while allowing older range aggregation and CSV export.
+- Added distinct session counts for bounded ranges.
+
+### Fixed
+
+- Added baseline retry with backoff after transient session registry failures.
+- Stopped in-flight scans and stale polling responses after plugin disposal or refresh races.
+
+## [1.0.4] - 2026-08-19
+
+### Fixed
+
+- Hardened loopback, same-origin, method, and process-token checks for dashboard API routes.
+- Allowed same-origin browser balance GET requests that omit `Origin` while retaining token protection.
+- Standardized English date buckets, range filters, streaks, heatmap dates, and export timestamps on UTC.
+
+[1.0.8]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.8
+[1.0.7]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.7
+[1.0.6]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.6
+[1.0.5]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.5
+[1.0.4]: https://github.com/ParticleLight/dsh-all-usage/releases/tag/v1.0.4

package/README.md

@@ -17,6 +17,18 @@ DeepSeek Harness 全量用量看板：按模型、供应商、工作区和时间
 - **时间范围**：今日、近 30 天、近 90 天、全部，或在全部可扫描历史日数据中自定义起止日期；热力图始终展示最近 53 周
 - **工作区别名**：在侧栏入口打开看板后管理，持久化保存到 $DSH_HOME/storages 的 KV 单元 `all_usage_aliases`
 - **界面语言**：在看板顶部切换中文与 English；选择会保存到浏览器本地
+- **完整历史与增量重建**：基线扫描全部可读历史会话；独立用量账本同时作为每会话游标——未变化的会话直接复用账本，新增事件只增量回填，长历史重启不再全量重建
+- **重启免读**：用持久化日志的 revision 作为每会话的变更信号（只读头部行 + stat，不读全量）——日志未变的会话重启时连事件都不读，直接从账本复用；仅日志变化（新增/修改）的会话才做增量读取
+- **Token 口径**：输入按「未含缓存命中」计，缓存命中 / 写入与推理独立成桶；全 0 用量的重放事件不会覆盖已记录的真实用量，仅缓存命中的请求也会计入
+
+### 最近更新
+
+**v1.0.8**
+
+- 重启免读：用持久化日志的 revision 做每会话变更信号，未变化会话重启时完全不读事件，直接复用账本；仅在日志变化时增量读取
+- 账本记录持久化每会话的日志 revision（旧记录首次重读后自动回填）
+
+完整版本记录见 [CHANGELOG.md](CHANGELOG.md)。
 
 ### 截图 / Screenshots
 
@@ -26,7 +38,7 @@ DeepSeek Harness 全量用量看板：按模型、供应商、工作区和时间
 
 ### 安装
 
-本插件是标准的 DSH 社区插件包（声明 `dsh.bundle` manifest 与 Web Client），数据全部来自持久化会话日志，安装后自动回填历史。
+本插件是标准的 DSH 社区插件包（声明 `dsh.bundle` manifest 与 Web Client），数据来自持久化会话日志和独立用量账本，安装后自动回填历史。
 
 #### 官方插件命令（推荐）
 
@@ -68,6 +80,7 @@ dsh plugin --profile web add github:ParticleLight/dsh-all-usage
 - 按日范围统计会保留全部可读取历史会话的有使用记录日期；热力图仅作为最近 53 周的固定视图窗口
 - 会话删除后，已成功 flush 的用量仍从独立账本恢复；会话销毁提示和周期对账只负责触发重建，不会删除账本记录
 - 同一会话的同一 `turn / step` 只保留一份最终 usage；重试或替换消息会替换旧贡献，不重复累计
+- 输入 Token 按「未含缓存命中」计（缓存命中 / 写入独立成桶）；全 0 用量的重放事件不会覆盖已记录的真实用量，纯缓存命中的请求仍会计入
 - 看板中的总处理量 = 输入 + 输出 + 缓存读写 + 推理；缓存命中表示复用的上下文 Token，不等于新生成 Token 或实际费用
 - 余额查询走 DeepSeek 官方 `/user/balance` 接口；未配置 API Key 时卡片显示引导文案
 - 仅统计能归属到已注册工作区（按会话 cwd 匹配）的会话
@@ -90,10 +103,22 @@ A full usage dashboard for DeepSeek Harness. Analyze tokens, cache behavior, acc
 - **Time ranges**: today, last 30 days, last 90 days, all time, or a custom start/end date across all available historical daily data; the heatmap always shows the latest 53 weeks
 - **Workspace aliases**: manage aliases from the sidebar dashboard; values persist in the $DSH_HOME/storages KV cell `all_usage_aliases`
 - **Interface language**: switch between Chinese and English from the dashboard header; your choice persists locally in the browser
+- **Full history & incremental rebuild**: the baseline scans every readable historical session; the durable usage ledger doubles as a per-session cursor, so unchanged sessions are reused straight from the ledger and only newly appended events are folded — long histories restart without a full rebuild
+- **Restart with no re-read**: the persisted log revision (a header-line + stat via `sessionPersistence.listSnapshots()`) acts as a per-session change signal — sessions whose log is unchanged are applied from the ledger on restart without reading their events at all; only changed/new sessions are read incrementally
+- **Token accounting semantics**: input tokens are fresh (exclude cache hits/writes, which sit in separate buckets along with reasoning); all-zero usage replays never overwrite recorded usage, while cache-only requests still count
+
+### Latest Update
+
+**v1.0.8**
+
+- Restart with no re-read: the persisted log revision acts as a per-session change signal, so unchanged sessions are applied from the ledger on restart without reading any events; only changed logs are read incrementally
+- The ledger now stores each session's log revision; existing rows are re-read once and backfilled automatically
+
+See [CHANGELOG.md](CHANGELOG.md) for the complete version history.
 
 ### Installation
 
-This is a standard DSH community bundle. It declares a `dsh.bundle` manifest and a web client, and backfills its data from persisted session logs after installation.
+This is a standard DSH community bundle. It declares a `dsh.bundle` manifest and a web client, and backfills its data from persisted session logs and the durable usage ledger after installation.
 
 #### Official plugin command (recommended)
 
@@ -135,6 +160,7 @@ The profile patch layer hot-reloads; save the file and refresh the page.
 - Day-level range data retains every readable historical session date with tracked usage; the heatmap is only a fixed latest-53-week view
 - After a session is deleted, successfully flushed usage is restored from the separate ledger; disposal hints and periodic reconciliation trigger rebuilds without deleting ledger rows
 - For each session and logical `turn / step`, only the final usage contribution is kept; retries or replaced messages do not double-count
+- Input tokens are fresh (exclude cache hits/writes, which sit in their own buckets); all-zero usage replays do not overwrite recorded usage and pure cache-read requests still count
 - Processed tokens = input + output + cache read/write + reasoning; a cache hit means reused context, not newly generated tokens or actual cost
 - Balance data comes from DeepSeek’s official `/user/balance` endpoint; the card shows guidance when no API key is configured
 - English mode uses UTC for date buckets, range filters, streaks, heatmap dates, and export timestamps; Chinese mode uses local time

package/lib/index.js

@@ -3,7 +3,7 @@
 import { randomBytes, timingSafeEqual } from 'node:crypto'
 
 const name = 'dsh-all-usage'
-const inject = ['sessionQuery', 'workspaceRegistry', 'timer', 'storage']
+const inject = ['sessionQuery', 'workspaceRegistry', 'timer', 'sessionPersistence', 'storage']
 
 // webServer route handlers do not inherit the connection API fence; keep this plugin
 // local and require a browser-originated capability for state-changing reads/writes.
@@ -75,6 +75,10 @@ function apply(ctx) {
   const settings = ctx.get('settings')
   const storage = ctx.get('storage')
   const webServer = ctx.get('webServer')
+  // v1.0.8: optional sessionPersistence exposes listSnapshots() — a cheap per-session
+  // revision (header line + stat, no full-log read) that lets the baseline skip
+  // re-reading unchanged sessions after a DSH restart.
+  const sessionPersistence = ctx.get('sessionPersistence')
 
   // ---------- owned aggregation state ----------
   const wsMeta = new Map()
@@ -259,6 +263,10 @@ function apply(ctx) {
     const values = usageValues(usage)
     const modelId = typeof model === 'string' && model !== '' ? model : '未知模型（历史记录缺少路由）'
     const eventSeq = typeof seq === 'number' ? seq : -1
+    // v1.0.7: a usage event carrying no billable token in any bucket must not add a
+    // meaningless row nor wipe previously recorded real usage (cc-switch
+    // has_billable_tokens parity). Pure cache-read requests are billable and pass.
+    if (noValues(values)) return
     const key = usageStepKey(sid, data, seq)
     const previous = usageByStep.get(key)
     // A late replay of an older raw event cannot replace the canonical later step.
@@ -297,7 +305,7 @@ function apply(ctx) {
   function ledgerEventKey(event, index) {
     return typeof event.seq === 'number' ? String(event.seq) : 'event:' + index
   }
-  function buildLedgerRecord(session, workspaceId, source = 'scan') {
+  function buildLedgerRecord(session, workspaceId, source = 'scan', revision) {
     const sid = session && typeof session.id === 'string' ? session.id : ''
     const events = session && Array.isArray(session.events) ? session.events : []
     if (sid === '' || workspaceId === undefined) return null
@@ -320,6 +328,9 @@ function apply(ctx) {
       }
       if (event.type !== 'assistant/message' || data === null || typeof data !== 'object' || data.usage === undefined) continue
       const values = usageValues(data.usage)
+      // v1.0.7: all-zero usage rows carry no billable tokens and stay out of the
+      // durable ledger (cc-switch has_billable_tokens parity).
+      if (noValues(values)) continue
       const modelId = typeof modelFromMessage(data, currentModel) === 'string' && modelFromMessage(data, currentModel) !== ''
         ? modelFromMessage(data, currentModel) : '未知模型（历史记录缺少路由）'
       const eventSeq = typeof event.seq === 'number' ? event.seq : -1
@@ -328,7 +339,7 @@ function apply(ctx) {
       if (previous !== undefined && eventSeq >= 0 && previous.seq > eventSeq) continue
       usage.set(key, { key, seq: eventSeq, time: event.time, workspaceId, modelId, values })
     }
-    return { version: LEDGER_VERSION, sessionId: sid, workspaceId, lastSeq: lastSeqOf(events), source, updatedAt: nextLedgerRevision(), turns: Array.from(turns.values()), usage: Array.from(usage.values()) }
+    return { version: LEDGER_VERSION, sessionId: sid, workspaceId, lastSeq: lastSeqOf(events), source, updatedAt: nextLedgerRevision(), lastRevision: typeof revision === 'string' ? revision : undefined, turns: Array.from(turns.values()), usage: Array.from(usage.values()) }
   }
   function normalizeLedgerRecord(raw, key) {
     if (raw === null || typeof raw !== 'object' || raw.version !== LEDGER_VERSION || typeof raw.sessionId !== 'string' || raw.sessionId !== key) return null
@@ -346,7 +357,7 @@ function apply(ctx) {
     }
     const updatedAt = typeof raw.updatedAt === 'number' ? raw.updatedAt : 0
     ledgerRevision = Math.max(ledgerRevision, updatedAt)
-    return { version: LEDGER_VERSION, sessionId: raw.sessionId, workspaceId: raw.workspaceId, lastSeq: typeof raw.lastSeq === 'number' ? raw.lastSeq : -1, source: raw.source === 'flush' ? 'flush' : 'scan', updatedAt, turns: Array.from(turnMap.values()), usage: Array.from(usageMap.values()) }
+    return { version: LEDGER_VERSION, sessionId: raw.sessionId, workspaceId: raw.workspaceId, lastSeq: typeof raw.lastSeq === 'number' ? raw.lastSeq : -1, source: raw.source === 'flush' ? 'flush' : 'scan', updatedAt, lastRevision: typeof raw.lastRevision === 'string' ? raw.lastRevision : undefined, turns: Array.from(turnMap.values()), usage: Array.from(usageMap.values()) }
   }
   function applyLedgerRecord(record) {
     if (record === null || record === undefined) return
@@ -523,6 +534,22 @@ function apply(ctx) {
     } catch (err) {
       console.error('[all-usage] session list failed:', err)
     }
+    // v1.0.8: cheap per-session change signal (header line + stat, no full-log read)
+    let snapshots = null
+    if (sessionPersistence !== undefined && typeof sessionPersistence.listSnapshots === 'function') {
+      try {
+        const rows = await sessionPersistence.listSnapshots()
+        if (Array.isArray(rows)) {
+          snapshots = new Map()
+          for (const row of rows) {
+            const rid = row && row.header && typeof row.header.id === 'string' ? row.header.id : undefined
+            if (rid !== undefined && row && typeof row.revision === 'string') snapshots.set(rid, row.revision)
+          }
+        }
+      } catch (err) {
+        console.error('[all-usage] session persistence snapshots unavailable:', err)
+      }
+    }
     if (disposed || generation !== aggregationGeneration) return
     if (setupFailed || !Array.isArray(records)) {
       // A transient registry failure must not be reported as a completed empty scan.
@@ -560,18 +587,60 @@ function apply(ctx) {
         if (disposed || generation !== aggregationGeneration) return
         try {
           if (sessionSeq.has(sid)) return
+          // v1.0.8: when the persisted log revision is unchanged since the last ledger
+          // write, the whole readSession (full event transfer) is skipped — the ledger
+          // record is applied directly and the live feed keeps catching new events.
+          const previousRecord = ledgerRecords.get(sid)
+          const revision = snapshots === null ? undefined : snapshots.get(sid)
+          if (previousRecord !== undefined && typeof previousRecord.lastRevision === 'string' && typeof revision === 'string' && revision === previousRecord.lastRevision) {
+            applyLedgerRecord(previousRecord)
+            for (const item of previousRecord.usage) {
+              usageByStep.set(item.key, { seq: item.seq, wsId: item.workspaceId, time: item.time, values: item.values, modelId: item.modelId, sid })
+            }
+            sessionSeq.set(sid, previousRecord.lastSeq)
+            sessionCount.add(sid)
+            return
+          }
           const snap = await ctx.sessionQuery.readSession(sid)
           if (disposed || generation !== aggregationGeneration) return
           if (snap && Array.isArray(snap.events)) {
-            const ledger = buildLedgerRecord({ id: sid, header: record.header, events: snap.events }, wsId)
+            // v1.0.7: incremental seed — the durable ledger doubles as a per-session
+            // cursor (cc-switch session_log_sync mtime+offset parity). An unchanged
+            // session applies its canonical record directly and never re-folds;
+            // a changed session seeds the previous record once, then folds only the
+            // new tail (previously every listed session was re-read and fully rebuilt).
+            const currentLastSeq = lastSeqOf(snap.events)
+            const previous = ledgerRecords.get(sid)
+            if (previous !== undefined) {
+              applyLedgerRecord(previous)
+              // Seed usageByStep so a later live retry of an already-recorded step
+              // reverses the ledger contribution instead of double-counting it.
+              for (const item of previous.usage) {
+                usageByStep.set(item.key, { seq: item.seq, wsId: item.workspaceId, time: item.time, values: item.values, modelId: item.modelId, sid })
+              }
+              if (previous.lastSeq >= currentLastSeq) {
+                // Content unchanged despite a revision change (rare: ctime-only churn):
+                // refresh the stored revision so future restarts can skip the read.
+                if (revision !== undefined && previous.lastRevision !== revision) {
+                  previous.lastRevision = revision
+                  void persistLedgerRecord(previous)
+                }
+                sessionSeq.set(sid, previous.lastSeq)
+                sessionCount.add(sid)
+                return
+              }
+              foldEvents(wsId, snap.events, previous.lastSeq, sid)
+            } else {
+              foldEvents(wsId, snap.events, undefined, sid)
+            }
+            const ledger = buildLedgerRecord({ id: sid, header: record.header, events: snap.events }, wsId, 'scan', revision)
             const canonical = ledger === null ? ledgerRecords.get(sid) : storeLedgerRecord(ledger)
             if (canonical === ledger) {
               void persistLedgerRecord(ledger)
-              foldEvents(wsId, snap.events, undefined, sid)
             } else if (canonical !== undefined) {
               applyLedgerRecord(canonical)
             }
-            sessionSeq.set(sid, lastSeqOf(snap.events))
+            sessionSeq.set(sid, currentLastSeq)
             sessionCount.add(sid)
           }
         } catch (err) {
@@ -786,6 +855,18 @@ function apply(ctx) {
         processedTotal: 'input + output + cacheRead + cacheWrite + reasoning',
         cacheRead: 'reused context tokens; not newly generated output',
         cacheWrite: 'tokens written into a provider cache',
+        // v1.0.7: structured, machine-readable accounting semantics (cc-switch
+        // input_token_semantics parity). DSH reports input as fresh (cache read /
+        // cache write sit in their own buckets) — verified against real ledger data;
+        // reasoning is bucketed separately from output and assumed non-overlapping.
+        semantics: {
+          input: 'fresh (excludes cache-read and cache-write tokens, bucketed separately)',
+          buckets: ['input', 'output', 'cacheRead', 'cacheWrite', 'reasoning'],
+          inputIncludesCache: false,
+          cacheBucketed: true,
+          reasoningSeparate: true,
+          gate: 'all-zero usage rows are ignored; pure cache-read requests still count',
+        },
       },
       totals: { turns: totals.turns, sessions: sessionCount.size, input: totals.input, output: totals.output, cacheRead: totals.cacheRead, cacheWrite: totals.cacheWrite, reasoning: totals.reasoning },
       perWorkspace: Array.from(perWorkspace, (p) => ({ workspaceId: p[0], turns: p[1].turns, input: p[1].input, output: p[1].output, cacheRead: p[1].cacheRead, cacheWrite: p[1].cacheWrite, reasoning: p[1].reasoning })),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-all-usage",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "DeepSeek Harness usage dashboard with model, provider, workspace, cache, balance, and CSV insights",
   "repository": {
     "type": "git",
@@ -37,6 +37,7 @@
   "files": [
     "lib/index.js",
     "lib/client.js",
+    "CHANGELOG.md",
     "cordis.patch.yml",
     "assets"
   ],