@gamegeek-saikel/dsh-cost-meter 0.3.0-alpha.1 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@
 
 **DSH Cost Meter** is a DeepSeek conversation cost-tracking plugin for the DeepSeek Harness (DSH) Web GUI — **price-snapshot-anchored per-turn cost** (peak/off-peak aware), **account balance**, a **cost view tab**, **per-message cost chips**, and a **header pill with live streaming estimates**. Every step's cost, price band, and snapshot version are computed *once* from the pricebook snapshot effective at the usage event's own time and then never recomputed — a later price change never rewrites an already-written conversation row.
 
-- Host half (`src/`): DeepSeek `GET /user/balance` query, the persisted snapshot-anchored pricebook, the `sessionCost` projection, subagent cost aggregation, and the trust-fenced `/cost-meter` route.
+- Host half (`src/`): DeepSeek `GET /user/balance` query, the persisted snapshot-anchored pricebook, the `sessionCost` projection plus the pricebook-free `sessionCostIndex` message index, subagent cost aggregation, and the trust-fenced `/cost-meter` route.
 - Client half (`src/client/`): composer-dock readout, Cost tab, per-reply chip, header pill, and the plugin configuration card — in Simplified Chinese and English.
 
 ---
@@ -29,11 +29,11 @@ Then start the harness:
 npx @deepseek-ai/dsh web
 ```
 
-If you have the DSH CLI installed globally, you can also use `dsh` instead of `npx @deepseek-ai/dsh`. To install into another profile, replace `web` with your profile name. The plugin declares and is verified against DSH `>=0.1.1-rc.1 <0.2.0` (current local version `0.1.1-rc.1`). The host half requires Node `^22.19.0 || >=24.0.0` and pnpm `11.7.0` for development.
+If you have the DSH CLI installed globally, you can also use `dsh` instead of `npx @deepseek-ai/dsh`. To install into another profile, replace `web` with your profile name. The plugin declares and is verified against DSH `^0.1.5-alpha.1`. The host half requires Node `^22.19.0 || >=24.0.0` and pnpm `11.7.0` for development.
 
 ## Overview
 
-Chat costs in DeepSeek pricing change over time (list prices, USD→CNY exchange, and the 2026-08-17 peak/off-peak rollout; on 2026-08-21 the official zh/en pages were redesigned into a combined table with three model columns and OFF-PEAK/PEAK cells), and a conversation spans many turns with cache-hit, cache-miss, cache-write, and output token buckets. Naively recomputing costs at *current* prices makes history drift every time the price table changes.
+Chat costs in DeepSeek pricing change over time (list prices, USD→CNY exchange, the 2026-08-17 peak/off-peak rollout, and the 2026-09-10 model rename to `deepseek-flash` with its V4.1-Flash price cut), and a conversation spans many turns with cache-hit, cache-miss, cache-write, and output token buckets. Naively recomputing costs at *current* prices makes history drift every time the price table changes.
 
 **Cost Meter** solves this with an **append-only pricebook**: every price/fx/band-table change starts a new immutable `PricebookSnapshot` (monotonic `version`, `effectiveAt`), and each usage event anchors to the snapshot effective at its own time. The result is an immutable per-step cost ledger that only grows — it never mutates. Live streaming estimates are explicitly labeled 估算/estimate because they use *current* prices; they are replaced by the exact anchored value once the step settles.
 
@@ -43,11 +43,12 @@ Chat costs in DeepSeek pricing change over time (list prices, USD→CNY exchange
 |---|---|
 | Cost anchoring | Append-only pricebook snapshots; step cost computed once at the event's own time |
 | Price sources | Manual override > official pricing page > built-in fallback > OpenRouter (fallback only, USD→CNY) > none |
-| Official page | Parses both the 2026-08-21 combined zh/en tables (including the `deepseek-v4-flash-vision-exp` column and the English UTC schedule) and the legacy split tables; the built-in historical list still anchors `single` when the page no longer carries one |
-| Peak pricing | 2026-08-17 00:00 Beijing rollout; peak windows apply Monday–Friday only (the zh and en pages may state different timezones; fallback 09:00–12:00 / 14:00–18:00 Beijing), weekends and all other hours off-peak at half price |
+| Official page | Parses the current 2026-09-10 combined zh/en tables (the `deepseek-flash` / `deepseek-v4-pro` columns with OFF-PEAK/PEAK cells per bucket row, and the English UTC schedule) as well as the earlier combined and legacy split tables; the retired `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` ids have no column of their own and bill at the Flash price, exactly as the page states. The built-in list still anchors `single` when the page no longer carries a pre-rollout table |
+| Peak pricing | 2026-08-17 00:00 Beijing rollout; peak windows apply Monday–Friday only (the zh and en pages may state different timezones; fallback 09:00–12:00 / 14:00–18:00 Beijing), so Saturdays, Sundays, and all other hours are off-peak at half price |
 | Cost formula | Uncached input + cache reads (hit rate) + cache writes (billed at uncached input rate) + output, per 1M tokens, CNY |
 | Account balance | Official `GET /user/balance`, cached 60 s, single in-flight request, trust-fenced route |
-| Subagent support | BFS over the live agent tree; conversation totals = main session + descendants |
+| Subagent support | Enumerates the conversation's durable subagent tree through `subagents.listDescendants` (nested delegations, settled children, and cold subagent sessions included, with no depth cap); falls back to a BFS over the live agent tree when that service is not mounted |
+| Conversation total | Main session + every descendant subagent (any depth); subagent totals still render while the main session's own ledger is not materialized |
 | UI surfaces | Composer dock · Cost tab · per-reply chip · header pill (live estimate) · settings card |
 | Locale | Simplified Chinese (source) + English |
 | Complexity | Fully synchronous fold; O(1) price lookups via in-memory mirror |
@@ -59,8 +60,8 @@ Once installed, the plugin contributes five browser surfaces (all text shown in
 | Surface | Slot | Description |
 |---|---|---|
 | Composer dock readout | `conversation.composer.dock` | Anchored session spend + account balance, refreshed every minute; hover for the category breakdown and snapshot info |
-| Cost view tab | `conversation.view` | Whole-conversation totals (main + subagents), category totals, per-subagent list, and the per-reply anchored ledger |
-| Per-reply cost chip | `conversation.chat.assistant-actions` | The anchored cost of one finalized reply (dash `—` when unpriced) |
+| Cost view tab | `conversation.view` | Whole-conversation totals (main + every subagent nesting level), category totals, the per-subagent list with its depth, and the per-reply anchored ledger |
+| Per-reply cost chip | `conversation.chat.assistant-actions` | The anchored cost of one finalized reply as the row's own stat capsule — the same trigger + anchored dialog the shipped 用量 and 用时 capsules use (28px pill, hover fill, `aria-expanded` dialog above the trigger). It closes the row's stat run: after 用量 and 用时, before the timestamp, spaced by the row's own gap, and coloured by the band that priced it (green off-peak, red peak). The dialog lists the three billed categories, the band with its multiplier, the model, and the snapshot version; the slot hands over the message id, which the `sessionCostIndex` projection resolves to ledger coordinates (dash `—` when unpriced) |
 | Header pill | `conversation.session.header.utilities` | Anchored total, or a live `≈ ¥x.xx (estimate)` while streaming; click for the detail panel |
 | Plugin card | `settings.plugin.item` | Per-model overrides, OpenRouter aliases, cache-read discount, FX mode, toggles, and manual refresh |
 
@@ -73,7 +74,7 @@ The pricebook (`src/pricebook.ts`) is the durable price source, persisted on the
 - **Priority chain** — per canonical model key (`provider/model`, bare model, or the `flash`/`pro` pricing key for DeepSeek-family models): manual override > official page > built-in fallback > OpenRouter (fallback only, USD→CNY, cache reads at the configured discount) > none.
 - **Snapshot selection** — `snapshotForTime` picks the newest snapshot with `effectiveAt <= event time` (pre-install sessions anchor to the first snapshot once).
 - **Peak/off-peak** — before the 2026-08-17 rollout all steps price at the single list price; after it, the band is chosen by the EVENT's own time against the schedule of the pricebook's own page (the zh and en pages each parse their own peak windows — the redesigned English page states UTC — falling back to Beijing 09:00–12:00 / 14:00–18:00, everything else off-peak). The official pages restrict peak windows to Monday–Friday, so Saturdays and Sundays are off-peak all day in the schedule's own timezone. When the combined page has no legacy single-price column, `single` keeps anchoring to the built-in historical list; a page that still carries a separate legacy table wins. Each step's band is anchored once at fold time, so the per-reply cards and chips always show the band that round was billed at — never the band of the moment you are looking.
-- **Immutable ledger** — the `sessionCost` projection (`src/session-cost-projection.ts`) folds `request/header` (model) and usage-carrying events into per-step rows; a second usage sample for the same (turn, step) replaces the first (same-step finalization, not a re-price), with O(1) incremental totals.
+- **Immutable ledger** — the `sessionCost` projection (`src/session-cost-projection.ts`) folds `request/header` (model) and usage-carrying events into per-step rows; a second usage sample for the same (turn, step) replaces the first (same-step finalization, not a re-price), with O(1) incremental totals. The companion `sessionCostIndex` projection (`src/session-cost-index.ts`) maps each finalized assistant-message id to its ledger coordinates; it reads no pricebook and computes no cost, so folding it can never re-price a session.
 
 ## Project Structure
 
@@ -84,7 +85,8 @@ src/
   pricing.ts                    # Official pricing-page parser, peak pricing, Beijing bands
   pricebook.ts                  # Append-only snapshots, priority chain, storage domain
   session-cost-projection.ts    # sessionCost projection (immutable per-step ledger)
-  subagent-cost.ts              # BFS subagent cost aggregation
+  session-cost-index.ts         # sessionCostIndex: message id → ledger coordinates
+  subagent-cost.ts              # Subagent cost aggregation (durable tree + live-registry fallback)
   invariant.ts                  # Route-disposer symmetry invariant companion
   client/                       # Browser half: 5 slot components + math/format/locales
 shared/
@@ -103,11 +105,11 @@ pnpm test        # vitest run (hermetic, network stubbed)
 pnpm build       # tsc -b && tsdown (lib/ + lib/client.js)
 ```
 
-The test suites are fully offline: pricing-page HTML, OpenRouter models, and the FX endpoint are all stubbed. Tests cover the trust fence, balance parsing, the pricebook priority chain and snapshot selection, the immutable ledger fold (including same-step replacement and peak/off-peak band selection at the *event* time), subagent BFS aggregation, and the client surfaces (jsdom).
+The test suites are fully offline: pricing-page HTML, OpenRouter models, and the FX endpoint are all stubbed. Tests cover the trust fence, balance parsing, the pricebook priority chain and snapshot selection, the immutable ledger fold (including same-step replacement and peak/off-peak band selection at the *event* time), the subagent aggregation (nested and cold children, listing-failure fallback, and a multi-level chain over a real `SessionStore` plus projection registry), and the client surfaces (jsdom).
 
 ## Documentation
 
-- [`src/pricing.ts`](src/pricing.ts), [`src/pricebook.ts`](src/pricebook.ts), [`src/session-cost-projection.ts`](src/session-cost-projection.ts) — detailed module docs on parsing, anchoring, and the ledger contract
+- [`src/pricing.ts`](src/pricing.ts), [`src/pricebook.ts`](src/pricebook.ts), [`src/session-cost-projection.ts`](src/session-cost-projection.ts), [`src/session-cost-index.ts`](src/session-cost-index.ts) — detailed module docs on parsing, anchoring, and the ledger contract
 - [`README.zh-CN.md`](README.zh-CN.md) — 简体中文版本
 
 ## License

package/README.zh-CN.md

@@ -8,7 +8,7 @@
 
 **DSH Cost Meter** 是为 DeepSeek Harness（DSH）Web GUI 打造的对话成本追踪插件——**价格快照锚定**的逐轮成本（感知**峰值/闲时**）、**账户余额**、**花费标签页**、**每条回复成本小标签**，以及带**流式实时估算**的**头部胶囊**。每一步的成本、价格档位与快照版本都**只计算一次**——锚定到该用量事件自身时刻生效的价格快照，此后永不重算——因此后续价格变动绝不会改写已写入的对话记录。
 
-- Host 半区（`src/`）：DeepSeek `GET /user/balance` 余额查询、持久化的快照锚定价格簿、`sessionCost` 投影、子代理成本聚合，以及带信任围栏的 `/cost-meter` 路由。
+- Host 半区（`src/`）：DeepSeek `GET /user/balance` 余额查询、持久化的快照锚定价格簿、`sessionCost` 投影与不读价格簿的 `sessionCostIndex` 消息索引、子代理成本聚合，以及带信任围栏的 `/cost-meter` 路由。
 - Client 半区（`src/client/`）：输入框下方读数、花费标签页、每条回复成本小标签、头部胶囊，以及插件配置卡——内置简体中文与英文。
 
 ---
@@ -29,11 +29,11 @@ npx @deepseek-ai/dsh plugin --profile web add @gamegeek-saikel/dsh-cost-meter
 npx @deepseek-ai/dsh web
 ```
 
-如果已全局安装 DSH CLI，也可以使用 `dsh` 代替 `npx @deepseek-ai/dsh`。安装到其他 profile 时，把 `web` 替换成你的 profile 名称即可。插件声明并已验证兼容 DSH `>=0.1.1-rc.1 <0.2.0`（当前本地版本 `0.1.1-rc.1`）。开发环境要求 Node `^22.19.0 || >=24.0.0` 与 pnpm `11.7.0`。
+如果已全局安装 DSH CLI，也可以使用 `dsh` 代替 `npx @deepseek-ai/dsh`。安装到其他 profile 时，把 `web` 替换成你的 profile 名称即可。插件声明并已验证兼容 DSH `^0.1.5-alpha.1`。开发环境要求 Node `^22.19.0 || >=24.0.0` 与 pnpm `11.7.0`。
 
 ## 概述
 
-DeepSeek 的价格随时间变化（官方价目表、USD→CNY 汇率、以及 2026-08-17 上线的峰值/闲时分时计价；2026-08-21 官方又把中英文页面改为一张三模型列、空闲/高峰列的价格表），而一次对话跨越很多轮，且每轮都含缓存命中、缓存未命中、缓存写入与输出等 token 桶。若按"当前价格"重算成本，每次价目变动都会让历史记录漂移。
+DeepSeek 的价格随时间变化（官方价目表、USD→CNY 汇率、2026-08-17 上线的峰值/闲时分时计价，以及 2026-09-10 的模型改名——Flash 列更名为 `deepseek-flash` 并下调为 V4.1-Flash 价），而一次对话跨越很多轮，且每轮都含缓存命中、缓存未命中、缓存写入与输出等 token 桶。若按"当前价格"重算成本，每次价目变动都会让历史记录漂移。
 
 **Cost Meter** 用**只追加的价格簿**解决这一问题：每次价格/汇率/分时表变化都会开启一个新的不可变 `PricebookSnapshot`（单调 `version`、`effectiveAt`），每个用量事件锚定到其自身时刻生效的快照。结果是一个**只增长、永不改写**的不可变逐步成本账本。流式实时估算明确标注为"估算"——因为它使用*当前*价格；一旦该步结算，即被精确的锚定值取代。
 
@@ -43,11 +43,12 @@ DeepSeek 的价格随时间变化（官方价目表、USD→CNY 汇率、以及
 |---|---|
 | 成本锚定 | 只追加价格簿快照；步成本在事件自身时刻只计算一次 |
 | 价格来源 | 手动覆盖 > 官方价格页 > 内置回退 > OpenRouter（仅回退，USD→CNY）> 无 |
-| 官方页适配 | 同时解析 2026-08-21 新版中英文页面（含 `deepseek-v4-flash-vision-exp` 第三列与英文 UTC 时段）和旧版分表；无旧单价的页面继续用内置历史单价锚定 |
-| 峰值定价 | 2026-08-17 00:00 北京生效；高峰窗口仅周一至周五（中英文页面时区可能不同，缺省 09:00–12:00 / 14:00–18:00 北京），周六、周日全天及其余时段为半价闲时 |
+| 官方页适配 | 解析当前 2026-09-10 版中英文页面（`deepseek-flash` / `deepseek-v4-pro` 两列、每个 token 桶行内的空闲/高峰单元格，以及英文 UTC 时段），同时兼容此前的合并表与旧版分表；已下线的 `deepseek-v4-flash`、`deepseek-v4-flash-vision-exp` 不再有独立列，按页面说明直接以 Flash 价格计费；页面不再提供旧单价表时继续用内置历史单价锚定 `single` |
+| 峰值定价 | 2026-08-17 00:00 北京生效；高峰窗口仅周一至周五（中英文页面时区可能不同，缺省 09:00–12:00 / 14:00–18:00 北京），因此周六、周日全天及其余时段均为半价闲时 |
 | 成本公式 | 未命中输入 + 缓存命中（命中价）+ 缓存写入（按未命中输入价计）+ 输出，每百万 tokens，CNY |
 | 账户余额 | 官方 `GET /user/balance`，缓存 60 秒，单飞请求，路由带信任围栏 |
-| 子代理支持 | 沿活跃代理树 BFS；对话总花费 = 主会话 + 全部后代 |
+| 子代理支持 | 沿 `subagents.listDescendants` 枚举本会话持久子代理树（子代理再派生的孙代理、已结束或已冷启动的子会话都计入，无层数上限）；未挂载该服务时回退到活跃代理树 BFS |
+| 对话总花费 | 主会话 + 全部后代子代理（任意层数）；主会话自身账本尚未就绪时仍展示子代理合计 |
 | UI 表面 | 输入框读数 · 花费标签页 · 回复小标签 · 头部胶囊（实时估算）· 设置卡 |
 | 本地化 | 简体中文（键源）+ 英文 |
 | 复杂度 | 全同步折叠；经内存镜像 O(1) 查价 |
@@ -59,8 +60,8 @@ DeepSeek 的价格随时间变化（官方价目表、USD→CNY 汇率、以及
 | 表面 | 插槽 | 说明 |
 |---|---|---|
 | 输入框下方读数 | `conversation.composer.dock` | 锚定的本会话花费 + 账户余额，每分钟刷新；悬停查看分类明细与快照信息 |
-| 花费标签页 | `conversation.view` | 全对话总花费（主会话 + 子代理）、分类小计、子代理列表与逐回复锚定账本 |
-| 每条回复成本小标签 | `conversation.chat.assistant-actions` | 单条已定稿回复的锚定成本（无价格时显示 `—`） |
+| 花费标签页 | `conversation.view` | 全对话总花费（主会话 + 任意层级的子代理）、分类小计、带层级的子代理列表与逐回复锚定账本 |
+| 每条回复成本小标签 | `conversation.chat.assistant-actions` | 单条已定稿回复的锚定成本，做成与官方「用量」「用时」完全同形的统计胶囊（28px 药丸、悬停底色、`aria-expanded` 展开锚定在触发件上方的对话框）；位置收在统计串末：在「用量」「用时」之后、末尾时刻文本之前，间距沿用行自身的 gap；按计价档位着色（闲时绿、高峰红）；对话框列出三类计费、档位与倍率、模型与快照版本；插槽只给出消息 id，由 `sessionCostIndex` 投影解析为账本坐标（无价格时显示 `—`） |
 | 头部胶囊 | `conversation.session.header.utilities` | 锚定总花费；流式中显示 `预计 ¥x.xx（估算）`；点击展开详情面板 |
 | 插件配置卡 | `settings.plugin.item` | 按模型覆盖价、OpenRouter 别名、缓存折扣、汇率模式、开关与立即刷新 |
 
@@ -73,7 +74,7 @@ DeepSeek 的价格随时间变化（官方价目表、USD→CNY 汇率、以及
 - **优先级链**——按规范模型键（`provider/model`、裸模型名，或 DeepSeek 系模型的 `flash`/`pro` 定价键）：手动覆盖 > 官方页面 > 内置回退 > OpenRouter（仅回退，USD→CNY，缓存读按配置折扣）> 无。
 - **快照选取**——`snapshotForTime` 取 `effectiveAt <= 事件时间` 的最新快照（安装前的会话一次性锚到首个快照）。
 - **峰值/闲时**——2026-08-17 上线前所有步按单一价目计费；上线后按事件自身时刻与该价格簿页面的时段表选档（中英文页面各自解析自己的高峰窗口，英文新版为 UTC，抓取失败时回退到北京 09:00–12:00 / 14:00–18:00，其余闲时）。官方页面限定高峰仅周一至周五，因此北京时间周六、周日全天为闲时。新版合并表没有旧单价列时，`single` 继续锚定内置历史单价；页面若有独立旧表，则优先用它。每步的档位在折叠时锚定一次，逐回复卡片与回复小标签永远显示该轮对话当时被计价的档位，而不是查看时刻的档位。
-- **不可变账本**——`sessionCost` 投影（`src/session-cost-projection.ts`）把 `request/header`（模型）与携带用量的事件折叠为逐步记录；同一 (turn, step) 的第二次用量样本**替换**第一条（同一步终结，而非重新计价），总计以 O(1) 增量维护。
+- **不可变账本**——`sessionCost` 投影（`src/session-cost-projection.ts`）把 `request/header`（模型）与携带用量的事件折叠为逐步记录；同一 (turn, step) 的第二次用量样本**替换**第一条（同一步终结，而非重新计价），总计以 O(1) 增量维护。配套的 `sessionCostIndex` 投影（`src/session-cost-index.ts`）把每条已定稿助手消息 id 映射到其账本坐标；它不读价格簿、不算成本，因此折叠它绝不会重新计价任何会话。
 
 ## 项目结构
 
@@ -84,7 +85,8 @@ src/
   pricing.ts                    # 官方价格页解析、峰值定价、北京时段
   pricebook.ts                  # 只追加快照、优先级链、存储域
   session-cost-projection.ts    # sessionCost 投影（不可变逐步账本）
-  subagent-cost.ts              # BFS 子代理成本聚合
+  session-cost-index.ts         # sessionCostIndex：消息 id → 账本坐标
+  subagent-cost.ts              # 子代理成本聚合（持久子代理树 + 活跃代理树回退）
   invariant.ts                  # 路由释放对称性 invariant 伴生插件
   client/                       # 浏览器半区：5 个插槽组件 + 数学/格式化/本地化
 shared/
@@ -103,11 +105,11 @@ pnpm test        # vitest run（封闭式，网络 stub）
 pnpm build       # tsc -b && tsdown（lib/ + lib/client.js）
 ```
 
-测试套件完全离线：价格页 HTML、OpenRouter 模型目录与汇率接口全部 stub。覆盖：信任围栏、余额解析、价格簿优先级链与快照选取、不可变账本折叠（含同一步替换与按*事件时间*选峰值/闲时档）、子代理 BFS 聚合，以及客户端表面（jsdom）。
+测试套件完全离线：价格页 HTML、OpenRouter 模型目录与汇率接口全部 stub。覆盖：信任围栏、余额解析、价格簿优先级链与快照选取、不可变账本折叠（含同一步替换与按*事件时间*选峰值/闲时档）、子代理聚合（持久子代理树的嵌套/冷会话/失败回退，以及真实 `SessionStore` + 投影注册表上的多层链路），以及客户端表面（jsdom）。
 
 ## 文档
 
-- [`src/pricing.ts`](src/pricing.ts)、[`src/pricebook.ts`](src/pricebook.ts)、[`src/session-cost-projection.ts`](src/session-cost-projection.ts)——解析、锚定与账本契约的详细模块注释
+- [`src/pricing.ts`](src/pricing.ts)、[`src/pricebook.ts`](src/pricebook.ts)、[`src/session-cost-projection.ts`](src/session-cost-projection.ts)、[`src/session-cost-index.ts`](src/session-cost-index.ts)——解析、锚定与账本契约的详细模块注释
 - [`README.md`](README.md) — English version
 
 ## 许可证