dsh-all-usage 1.0.6 → 1.0.7

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `dsh-all-usage` are documented here.
+
+## [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.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；选择会保存到浏览器本地
+- **完整历史与增量重建**：基线扫描全部可读历史会话；独立用量账本同时作为每会话游标——未变化的会话直接复用账本，新增事件只增量回填，长历史重启不再全量重建
+- **Token 口径**：输入按「未含缓存命中」计，缓存命中 / 写入与推理独立成桶；全 0 用量的重放事件不会覆盖已记录的真实用量，仅缓存命中的请求也会计入
+
+### 最近更新
+
+**v1.0.7**
+
+- 增量游标：启动重扫只增量回填新增事件，未变化的会话直接从独立账本复用，不再全量重建
+- 全 0 用量防护：全 0 用量的重放事件不会覆盖已记录的真实用量；纯缓存命中的请求仍会计入
+- 结构化语义声明：API 返回机读的 token 口径（输入不含缓存命中，缓存与推理独立成桶）
+
+完整版本记录见 [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
+- **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.7**
+
+- Incremental scan cursor: restarts re-fold only newly appended events; unchanged sessions are seeded straight from the durable ledger instead of a full rebuild
+- All-zero usage guard: zero-usage replays no longer overwrite recorded usage, while pure cache-read requests still count
+- Structured token semantics: the API now declares a machine-readable accounting contract (input excludes cache; cache and reasoning are separate buckets)
+
+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

@@ -259,6 +259,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.
@@ -320,6 +324,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
@@ -563,15 +570,37 @@ function apply(ctx) {
           const snap = await ctx.sessionQuery.readSession(sid)
           if (disposed || generation !== aggregationGeneration) return
           if (snap && Array.isArray(snap.events)) {
+            // 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) {
+                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)
             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 +815,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.7",
   "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"
   ],