dsh-token-bill 0.0.0-stage → 2.0.1

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 2.0.1 — 2026-11-07
+
+### Changed
+
+- **Renamed to `dsh-token-bill`** (repository `leecisen/dsh-token-bill`, row id `dsh-token-bill`, projection key `dshTokenBill`). The npm name `dsh-token-cost` belongs to a different author's plugin, so installing by that bare name never reached this one. Install with `github:leecisen/dsh-token-bill`.
+- If you installed 2.0.0 (then named `dsh-token-cost`), uninstall it on the Plugins page before installing 2.0.1.
+- Sharper 2x README screenshots in Chinese and English; panel notes keep "9–12" on one line and drop the stray space after Chinese full stops.
+
+## 2.0.0 — 2026-11-07
+
+A rewrite of the v1 `@local/token-cost` plugin, published as `dsh-token-cost`.
+
+### Added
+
+- **Per-model pricing.** Usage is tracked per provider + model, read from each message's source (or the latest request header for failed attempts), and priced with that model's rates.
+- **Built-in official DeepSeek prices** for `deepseek-flash` and `deepseek-v4-pro` in CNY and USD (checked 2026-11-07); the retired names `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` bill as Flash.
+- **Peak / off-peak pricing.** Each call is priced by its Beijing time: weekdays 09:00–12:00 and 14:00–18:00 are peak, everything else (weekends and the built-in 2026 public holidays) is half price. `holidays` adds more days; `timeOfDayPricing: false` turns it off.
+- **Breakdown panel** on click: cost per token bucket with a proportion bar, cache hit rate, model calls, thinking tokens, last turn, compaction, off-peak savings, subagents with a grand total, and per-model rows. It follows the built-in context meter's look and closes on Escape or an outside click.
+- **Sidebar costs**: every conversation in the session list shows its cost beside its time (`showInSessionList`).
+- **Compaction calls are billed** (`compaction/summary`), which the built-in token meter does not count.
+- **Forked sessions** no longer re-bill the events they inherited from their parent.
+- `models` overrides keyed by `model` or `provider/model`, optional `offPeak` and `cacheWrite` prices, and a `fallback` price for unknown models; models without a price are shown as unpriced instead of guessed.
+- Chinese and English UI, plugin title / description / detail document for the Plugins page.
+- Unit tests for the fold, the pricing, the Host entry, and a Node smoke test of the browser components.
+
+### Changed
+
+- Package renamed to `dsh-token-cost`; row id `dsh-token-cost`, projection key `dshTokenCost`, so v1 and v2 can be installed side by side during an upgrade.
+- The projection stores tokens only and prices them in the view, so price edits apply to every past session.
+- Registration is awaited and checkpoint state is validated on restore, as the session-projection contract asks.
+
+### Compatibility
+
+- v1's `inputPrice`, `cacheHitPrice`, and `outputPrice` are still read, as the fallback price for models without their own.
+
+## 1.0.0
+
+- First version (`@local/token-cost`): one cost badge next to the context ring, a single price table for the whole session.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 leecisen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,158 @@
+# dsh-token-bill · Conversation cost
+
+[中文](README.md)
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that estimates **what every conversation costs**.
+
+- **Under the composer**: the session's estimated cost sits left of the context ring; click it for a breakdown.
+- **In the sidebar**: every conversation shows its cost next to its time, without opening it.
+- **Per-model pricing**: built-in official DeepSeek prices (`deepseek-flash`, `deepseek-v4-pro`, in CNY and USD); price any other model (for example one routed through pi-ai) in the config.
+- **Peak / off-peak aware**: DeepSeek charges peak rates on Beijing weekdays 09:00–12:00 and 14:00–18:00 and half price at all other times (weekends and Chinese public holidays included). Each call is priced by **when it happened**, and the panel shows how much off-peak hours saved.
+- **More complete**: counts the model calls made by context compaction (the built-in token meter does not), lists subagent costs with a grand total, and never re-bills the history a forked conversation inherited.
+- **Price edits apply at once**: sessions store tokens only and prices are applied when the view is built, so changing a price re-prices every past conversation.
+- Chinese and English UI, follows the light / dark theme; no dependencies, no build step.
+
+> Costs are estimated from provider-reported token usage and a price table. Your bill is authoritative.
+
+## Screenshots
+
+| Breakdown panel (light) | Breakdown panel (dark) | Sidebar |
+|---|---|---|
+| <img src="docs/panel-light-en.png" width="362" alt="Cost breakdown panel in the light theme"> | <img src="docs/panel-dark-en.png" width="362" alt="Cost breakdown panel in the dark theme"> | <img src="docs/sidebar-en.png" width="300" alt="Each conversation's cost in the sidebar list"> |
+
+<sub>2x preview renders of the plugin's code with the DSH theme; the plugin follows DSH's language setting. Sample data: one peak-hour exchange, one night-time (off-peak) exchange, one compaction, one subagent, and one unpriced model (hy4).</sub>
+
+What the panel shows:
+
+| Row | Meaning |
+|---|---|
+| Input · cache miss / cache hit / Output | Tokens and cost per bucket; the bar shows each bucket's share of the cost. A "Cache write" row appears when there are cache writes. |
+| Cache hit rate | Cached input ÷ all input. |
+| Model calls | Billed model calls (a failed attempt that was retried counts too). |
+| Thinking (in output) | Thinking (reasoning) tokens, already included in Output. |
+| Last turn | Cost of the most recent turn. |
+| Compaction | Cost of the model calls made while compacting the context. |
+| Off-peak savings | What you saved compared with paying peak prices throughout. |
+| Subagents / Total incl. subagents | Cost of the subagents this session started, and the total with them. |
+| By model | Tokens and cost per model; models without a price show "no price". |
+
+- A trailing `+` means some model has no price configured and is left out of the total (marked "no price").
+- The subagent lines appear only when the session started subagents and the sidebar has loaded their data.
+
+## Install
+
+Requires DeepSeek Harness **0.2.2-rc.1 or newer**.
+
+### From GitHub (recommended)
+
+DeepSeek Harness sidebar → **Plugins** → **Add plugin**, then enter:
+
+```text
+github:leecisen/dsh-token-bill
+```
+
+When it finishes, click **Enable now**.
+
+> Enter the whole `github:leecisen/dsh-token-bill`. A bare name makes DeepSeek Harness look for an npm package of that name, which may be someone else's plugin.
+
+> Can't reach GitHub? Download the ZIP from [Releases](https://github.com/leecisen/dsh-token-bill/releases) or the repository page, extract it somewhere permanent, and enter that folder's **absolute path** in **Add plugin** (for example `D:\dsh-plugins\dsh-token-bill`).
+
+### Upgrading from v1 (`@local/token-cost`)
+
+v2 is a separate package (package `dsh-token-bill`, row id `dsh-token-bill`) and does not clash with v1. Install and enable v2, then turn off or remove `@local/token-cost` on the **Plugins** page. v1's `inputPrice` / `cacheHitPrice` / `outputPrice` fields still work as the fallback price for unknown models.
+
+Version 2.0.0 was named `dsh-token-cost` (`github:leecisen/dsh-token-cost`). If you installed it, uninstall it on the **Plugins** page first, then install as above.
+
+## Configuration
+
+It works without any configuration: CNY, peak / off-peak pricing, costs in the sidebar. To change that, add an entry to your profile's `cordis.patch.yml` (on Windows usually `%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml`):
+
+```yaml
+- id: dsh-token-bill
+  config:
+    currency: CNY            # CNY or USD use the built-in DeepSeek prices; other codes use only your `models`
+    timeOfDayPricing: true   # DeepSeek peak / off-peak tiers; false = everything at peak (an upper bound)
+    showInSessionList: true  # show each conversation's cost in the sidebar
+    holidays:                # extra public holidays (Beijing dates), off-peak all day
+      - '2027-01-01'
+    models:                  # prices per million tokens, in `currency`
+      hy4:                   # key: a model id, or provider/model id
+        input: 0.8           # input, cache miss
+        cacheHit: 0.2        # input, cache hit (defaults to input)
+        output: 2            # output
+        # cacheWrite: 1      # cache write (defaults to input)
+        # offPeak:           # optional off-peak card; missing fields inherit from above
+        #   output: 1
+      deepseek-account/deepseek-v4-pro:   # e.g. override one provider's copy of a model
+        input: 9
+        cacheHit: 0.3
+        output: 27
+    fallback:                # optional: price for every model without one; omit to show "no price"
+      input: 2
+      cacheHit: 0.5
+      output: 8
+```
+
+Note: this `config` **replaces** the plugin's own config as a whole (DeepSeek Harness does not merge them); fields you leave out take the defaults below.
+
+| Field | Default | Meaning |
+|---|---|---|
+| `currency` | `CNY` | Currency code. `CNY` / `USD` have built-in DeepSeek prices. |
+| `symbol` | by currency (`¥`, `$`, …) | Symbol shown before amounts. |
+| `timeOfDayPricing` | `true` | Price DeepSeek peak and off-peak hours separately. |
+| `showInSessionList` | `true` | Show each conversation's cost in the sidebar list. |
+| `holidays` | built-in 2026 days off | Extra holidays as `YYYY-MM-DD` (Beijing time). |
+| `models` | none | Custom or overriding prices. Lookup: `provider/model` → `model` → built-in → `fallback`. |
+| `fallback` | none | Fallback price. v1's `inputPrice` / `cacheHitPrice` / `outputPrice` mean the same. |
+
+### Built-in prices
+
+From the [official DeepSeek price page](https://api-docs.deepseek.com/quick_start/pricing), checked **2026-11-07**, per million tokens.
+
+| Model | Hours | Input (cache hit) | Input (cache miss) | Output |
+|---|---|---|---|---|
+| `deepseek-flash` | peak | ¥0.04 / $0.006 | ¥2 / $0.30 | ¥8 / $1.20 |
+| `deepseek-flash` | off-peak | ¥0.02 / $0.003 | ¥1 / $0.15 | ¥4 / $0.60 |
+| `deepseek-v4-pro` | peak | ¥0.30 / $0.044 | ¥9 / $1.32 | ¥27 / $3.96 |
+| `deepseek-v4-pro` | off-peak | ¥0.15 / $0.022 | ¥4.5 / $0.66 | ¥13.5 / $1.98 |
+
+- The retired names `deepseek-v4-flash` and `deepseek-v4-flash-vision-exp` are billed as `deepseek-flash`, as the official page states.
+- Peak hours: Beijing time Monday to Friday (except Chinese public holidays) 09:00–12:00 and 14:00–18:00 (01:00–04:00 and 06:00–10:00 UTC); all other hours are off-peak. The 2026 holidays are built in; add 2027's with `holidays` once announced, or update the plugin.
+- Through the DeepSeek account provider (`deepseek-account`) the cost is the API-equivalent price. If your account runs on a quota or plan, set `deepseek-account/<model>` under `models` to 0 or to your real rate.
+- Prices can change; the official page wins. Issues and PRs for outdated prices are welcome.
+
+## How it works
+
+- The **Host half** registers the session projection `dshTokenBill`, which replays every billed model call in the session log: `assistant/message`, `assistant/attempt` (a failed attempt that was retried is billed too), and `compaction/summary`. Tokens are bucketed per provider + model and per peak / off-peak tier: uncached input, cached input, cache writes, output (and the thinking tokens within it).
+- Within one attempt the final message's usage replaces the streaming sample; after `llm/retry-started` the retry is billed separately — the same rule the built-in token meter follows.
+- The tier comes from each event's timestamp in Beijing time, so the fold is deterministic and replay-stable.
+- Forked sessions: events inherited from the parent (below `inheritedEventCount`) are not billed again.
+- The projection stores tokens only; the **view** applies the current prices, so a price edit applies to every session at once.
+- The **browser half** puts the badge and panel into the `conversation.composer.dock` slot (reading this session's projection) and the per-conversation label into `sidebar.session.row.trailing` (reading the session list's summary rows). Subagent costs come from `subagentCatalog` and the session list.
+
+## Known limitations
+
+- It is an estimate from reported usage and a price table. Per-request services such as web search / fetch are not included, nor are auxiliary calls like session-title generation (those calls are not written to the session log).
+- The sidebar shows costs only for sessions with summary data; a conversation from before the plugin was installed may need to be opened once.
+- Subagent costs depend on the child sessions the sidebar has loaded; until then the amount carries a `+`.
+- Holidays are built in through 2026.
+
+## Development
+
+```bash
+git clone https://github.com/leecisen/dsh-token-bill.git
+cd dsh-token-bill
+node --test "test/*.test.js"
+```
+
+- `index.js`: Host entry, registers the projection.
+- `lib/fold.js`: the projection fold (pure).
+- `lib/pricing.js`: price tables, peak / off-peak tiers, and the priced view (pure).
+- `client.js`: the browser half, plain JS without a build step; it requires only DSH's shared `react`, `react-dom`, and `@deepseek-ai/dsh-client-ui-primitives`.
+- `test/`: `node --test` unit tests, including a smoke test that renders the browser components under Node.
+
+To try local changes, enter the repository folder's absolute path in DeepSeek Harness's **Add plugin**; restart DSH after editing.
+
+## License
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# dsh-token-bill · 对话费用
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.en.md)
+
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：估算**每个对话花了多少钱**。
+
+- **输入框下方**：上下文圆环左边显示本会话的估算费用，点一下展开明细。
+- **侧边栏**：会话列表里，每个对话的时间旁边直接显示它的费用，不用点进去。
+- **按模型计价**：内置 DeepSeek 官方价格（`deepseek-flash`、`deepseek-v4-pro`，人民币 / 美元两套）；其他模型（例如通过 pi-ai 接入的模型）在配置里补上价格即可。
+- **区分高峰 / 空闲时段**：DeepSeek 官方在北京时间工作日 9:00–12:00、14:00–18:00 收高峰价，其余时段（含周末、法定节假日全天）半价。插件按**每次调用发生的时间**分别计价，并显示「空闲时段节省」了多少。
+- **算得更全**：上下文压缩（compaction）时的模型调用也计入（内置的 token 计量不含这部分）；子代理的费用单独列出并给出合计；从别的会话分叉出来的会话，不会重复计算继承来的部分。
+- **改价立即生效**：会话里只记录 token 数，价格在显示时才套用，改了价格后所有历史会话都按新价格重算。
+- 中英文界面，跟随浅色 / 深色主题；零依赖、无需构建。
+
+> 费用由模型返回的 token 用量 × 价格表估算，仅供参考，以实际账单为准。
+
+## 效果
+
+| 明细面板（浅色） | 明细面板（深色） | 侧边栏 |
+|---|---|---|
+| <img src="docs/panel-light.png" width="362" alt="浅色主题下的费用明细面板"> | <img src="docs/panel-dark.png" width="362" alt="深色主题下的费用明细面板"> | <img src="docs/sidebar.png" width="300" alt="侧边栏会话列表里每个对话的费用"> |
+
+<sub>以上为插件代码在 DSH 主题样式下的 2 倍分辨率预览渲染，示例数据：一次高峰时段对话 + 一次夜间（空闲）对话 + 一次上下文压缩 + 一个子代理 + 一个未定价模型 hy4。</sub>
+
+面板里有什么：
+
+| 行 | 含义 |
+|---|---|
+| 输入 · 未命中缓存 / 命中缓存 / 输出 | 各类 token 数与对应费用；彩条是费用占比。有缓存写入时会多一行「缓存写入」。 |
+| 缓存命中率 | 命中缓存的输入 ÷ 全部输入。 |
+| 模型调用 | 计费的模型调用次数（失败后重试的那次也算）。 |
+| 其中思考 | 输出里的思考（推理）tokens，已包含在「输出」中。 |
+| 最近一轮 | 最近一轮对话的费用。 |
+| 上下文压缩 | 压缩上下文时的模型调用费用。 |
+| 空闲时段节省 | 和全部按高峰价相比省下的钱。 |
+| 子代理 / 合计 | 本会话启动的子代理的费用，以及加上它们之后的合计。 |
+| 按模型 | 每个模型的 token 与费用；没有价格的模型显示「未定价」。 |
+
+- 金额后面的 `+` 表示有模型没有配置价格，这部分没有计入总额（明细里标为「未定价」）。
+- 「子代理」「合计」只在本会话启动过子代理、并且侧边栏已加载它们的数据时出现。
+
+## 安装
+
+需要 DeepSeek Harness **0.2.2-rc.1 或更新版本**。
+
+### 从 GitHub 安装（推荐）
+
+DeepSeek Harness 侧边栏 → **插件** → **添加插件**，填入：
+
+```text
+github:leecisen/dsh-token-bill
+```
+
+安装完成后点 **立即启用**。
+
+> 请填完整的 `github:leecisen/dsh-token-bill`。只填名字的话，DeepSeek Harness 会去 npm 上找同名的包，那可能是别人的插件。
+
+> 如果连不上 GitHub：在 [Releases](https://github.com/leecisen/dsh-token-bill/releases) 或仓库首页下载 ZIP，解压到一个固定位置，然后在「添加插件」里填这个文件夹的**绝对路径**（例如 `D:\dsh-plugins\dsh-token-bill`）。
+
+### 从旧版（`@local/token-cost`）升级
+
+新版是一个独立的包（包名 `dsh-token-bill`、行 id `dsh-token-bill`），和旧版互不冲突。安装并启用新版后，在 **插件** 页面关闭或卸载旧的 `@local/token-cost` 即可。旧版的 `inputPrice` / `cacheHitPrice` / `outputPrice` 配置仍然可用，会作为「未知模型的兜底价格」。
+
+2.0.0 版当时叫 `dsh-token-cost`（地址 `github:leecisen/dsh-token-cost`）。如果你装过它，先在 **插件** 页面卸载，再按上面的方法安装新版。
+
+## 配置
+
+不配置也能用：默认人民币、区分时段、在侧边栏显示费用。要修改时，在你的 profile 的 `cordis.patch.yml`（Windows 一般在 `%USERPROFILE%\.dsh\profiles\desktop\cordis.patch.yml`）里加一段：
+
+```yaml
+- id: dsh-token-bill
+  config:
+    currency: CNY            # CNY 或 USD 使用内置 DeepSeek 价格；其他币种只用你在 models 里填的价格
+    timeOfDayPricing: true   # 区分 DeepSeek 高峰/空闲时段；false = 全部按高峰价（保守上限）
+    showInSessionList: true  # 在侧边栏会话列表显示费用
+    holidays:                # 额外的法定节假日（北京时间日期），整天按空闲价
+      - '2027-01-01'
+    models:                  # 每百万 tokens 的价格，单位为 currency
+      hy4:                   # 键可以是「模型 id」，也可以是「provider/模型 id」
+        input: 0.8           # 输入（未命中缓存）
+        cacheHit: 0.2        # 输入（命中缓存），默认等于 input
+        output: 2            # 输出
+        # cacheWrite: 1      # 缓存写入，默认等于 input
+        # offPeak:           # 可选：空闲时段价格，缺的字段沿用上面的值
+        #   output: 1
+      deepseek-account/deepseek-v4-pro:   # 例：只覆盖某个 provider 下的同名模型
+        input: 9
+        cacheHit: 0.3
+        output: 27
+    fallback:                # 可选：所有没有价格的模型都按这个算；不填则显示「未定价」
+      input: 2
+      cacheHit: 0.5
+      output: 8
+```
+
+注意：这里的 `config` 会**整体替换**插件自带的配置（DeepSeek Harness 不做合并），没写的字段使用下表中的默认值。
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `currency` | `CNY` | 币种代码。`CNY` / `USD` 有内置 DeepSeek 价格。 |
+| `symbol` | 随币种（`¥`、`$`…） | 金额前显示的符号。 |
+| `timeOfDayPricing` | `true` | 是否区分 DeepSeek 高峰 / 空闲时段。 |
+| `showInSessionList` | `true` | 是否在侧边栏会话列表显示每个对话的费用。 |
+| `holidays` | 内置 2026 年放假日期 | 追加的节假日，格式 `YYYY-MM-DD`（北京时间）。 |
+| `models` | 无 | 自定义 / 覆盖价格。查找顺序：`provider/模型` → `模型` → 内置价格 → `fallback`。 |
+| `fallback` | 无 | 兜底价格。旧版的 `inputPrice` / `cacheHitPrice` / `outputPrice` 等同于它。 |
+
+### 内置价格
+
+来自 [DeepSeek 官方价格页](https://api-docs.deepseek.com/zh-cn/quick_start/pricing)，**2026-11-07** 核对，单位：每百万 tokens。
+
+| 模型 | 时段 | 输入（命中缓存） | 输入（未命中缓存） | 输出 |
+|---|---|---|---|---|
+| `deepseek-flash` | 高峰 | ¥0.04 / $0.006 | ¥2 / $0.30 | ¥8 / $1.20 |
+| `deepseek-flash` | 空闲 | ¥0.02 / $0.003 | ¥1 / $0.15 | ¥4 / $0.60 |
+| `deepseek-v4-pro` | 高峰 | ¥0.30 / $0.044 | ¥9 / $1.32 | ¥27 / $3.96 |
+| `deepseek-v4-pro` | 空闲 | ¥0.15 / $0.022 | ¥4.5 / $0.66 | ¥13.5 / $1.98 |
+
+- 旧模型名 `deepseek-v4-flash`、`deepseek-v4-flash-vision-exp` 按 `deepseek-flash` 计价（与官方一致）。
+- 高峰时段：北京时间周一至周五（不含法定节假日）9:00–12:00、14:00–18:00；其余时间均为空闲时段。内置了 2026 年的放假日期；2027 年的安排公布后可用 `holidays` 追加，或升级插件。
+- 通过 DeepSeek 账号（`deepseek-account`）使用时，按 API 价格估算，代表「等价 API 费用」；如果你的账号走的是额度/套餐，可以在 `models` 里用 `deepseek-account/<模型>` 把价格改成 0 或你的实际单价。
+- 价格可能调整，以官方页面为准；发现过期欢迎提 issue / PR。
+
+## 计算方式
+
+- **Host 端**注册一个会话投影 `dshTokenBill`，重放会话日志里每一次计费的模型调用：`assistant/message`、`assistant/attempt`（失败后重试的那次也计费）和 `compaction/summary`。按「provider + 模型」和「高峰 / 空闲」分桶累计 token：未命中缓存的输入、命中缓存的输入、缓存写入、输出（以及其中的思考 tokens）。
+- 同一次尝试里，流式过程中的用量会被最终消息的用量替换；遇到 `llm/retry-started` 后，重试那次单独计费——与内置 token 计量的规则一致。
+- 高峰 / 空闲按**事件发生时间**（北京时间）判断，结果可重放、确定。
+- 分叉会话：从父会话继承的那部分事件（`inheritedEventCount` 之前）不计费。
+- 投影里只存 token；**视图**才按当前价格计价，所以改价立即对所有会话生效。
+- **浏览器端**：`conversation.composer.dock` 插槽里的徽标和明细面板读取本会话的投影；`sidebar.session.row.trailing` 插槽从会话列表的摘要数据里读取每个会话的费用。子代理的费用来自 `subagentCatalog` 和会话列表。
+
+## 已知限制
+
+- 估算值：基于模型返回的用量和价格表，不含联网搜索 / 抓取等按次收费的服务，也不含会话标题生成等辅助调用（这些调用没有写入会话日志）。
+- 侧边栏只显示已经有摘要数据的会话：安装插件前的老会话，可能要打开一次才会显示费用。
+- 子代理费用依赖会话列表里已加载的子会话数据，没加载到时金额后会带 `+`。
+- 节假日只内置到 2026 年。
+
+## 开发
+
+```bash
+git clone https://github.com/leecisen/dsh-token-bill.git
+cd dsh-token-bill
+node --test "test/*.test.js"
+```
+
+- `index.js`：Host 入口，注册投影。
+- `lib/fold.js`：投影的折叠逻辑（纯函数）。
+- `lib/pricing.js`：价格表、高峰 / 空闲判断、计价视图（纯函数）。
+- `client.js`：浏览器端（纯 JS，无需构建），只依赖 DSH 共享的 `react`、`react-dom` 和 `@deepseek-ai/dsh-client-ui-primitives`。
+- `test/`：`node --test` 单元测试，包括在 Node 里渲染浏览器端组件的冒烟测试。
+
+本地调试：在 DeepSeek Harness 的「添加插件」里填仓库文件夹的绝对路径来安装；改完代码后重启 DSH 生效。
+
+## 许可证
+
+[MIT](LICENSE)