@rayadesu/dsh-billing 0.2.3 → 0.3.0

package/AGENTS.md

@@ -47,7 +47,7 @@ cordis.patch.yml         DSH profile bundle 补丁层：挂载 llm-billing + ui-
 - **密钥不进仓库**：`DEEPSEEK_API_KEY` 等一律由用户环境或凭据 seam 提供，仓库不含真实值。
 - **README 双语**：每个 README 遵循 DSH 结构 `README.md`(EN) + `README.zh.md`(ZH) +
   `README.i18n.yaml`（记录两文件 git blob hash，改动后需更新）。
-- **版本对齐**：根 bundle 与两个包统一版本号（当前 0.2.3），`pnpm-lock.yaml` 随依赖变更更新。
+- **版本对齐**：根 bundle 与两个包统一版本号（当前 0.3.0），`pnpm-lock.yaml` 随依赖变更更新。
 - **文本规范**：LF 换行、文件末尾一个换行（`.editorconfig`/`.gitattributes` 已声明）。
 
 ## 常用命令

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # last confirmed-consistent state. Both languages carry equal authority; after
 # editing either side, bring the other along and re-record both hashes with:
 #   git hash-object README.md README.zh.md
-README.md: fd68d55fd7fa097b79dc8a5d02f2e19a6c76ac4a
-README.zh.md: 02d86da0f335c9dbd3b6d469e3a908f279e9ae32
+README.md: 043453b28aa797ae654f2fa8653a547c1a9dd13b
+README.zh.md: a60f2df77c3ff883a6e0ceb74c114510bf1643ce

package/README.md

@@ -2,14 +2,15 @@
 
 English | [中文](README.zh.md)
 
-A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that shows your **DeepSeek account balance**, **this session's (this conversation's) billed spend**, and **today's total spend across all sessions** directly in the web session header.
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that shows your **DeepSeek account balance**, **this session's (this conversation's) billed spend**, and **today's total spend across all sessions** directly in the web session header; each completed turn also shows its **turn cost** in the message actions row, and the detail panel ends with a **today session-spend ranking**.
 
-> The balance is the real `GET /user/balance` figure; the session and today spends price each message's billed tokens at the official peak/off-peak rates and are estimates, not billing promises.
+> The balance is the real `GET /user/balance` figure; the session, turn, and today spends price each message's billed tokens at the official peak/off-peak rates and are estimates, not billing promises.
 
 ## What it shows
 
 - **Session-header badge** — two lines: remaining balance (`剩余额度：¥X`) and this conversation's billed spend (`本轮对话花费：¥X`).
-- **Detail panel** — the remaining amount, this session's spend (`本会话花费`) with today's all-session spend beside it (`今日共花费`), one priced row per model (`缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z`), plus a manual refresh action and a spend disclaimer.
+- **Detail panel** — the remaining amount, this session's spend (`本会话花费`) with today's all-session spend beside it (`今日共花费`), one priced row per model (`缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z`), plus a manual refresh action and a spend disclaimer. The panel ends with a **today session-spend ranking**: sessions sorted by today's spend, highest first (names come from the log's Chinese titles and follow renames automatically; at most the top 10 rows, with a "…N more sessions" hint).
+- **Turn cost row** — each completed turn's closing message shows `本轮花费 ¥X` at the **front** of the actions row (before the copy control): the "本轮花费" word in the usage-card title tone and the amount in the summary tone, **always visible** (not hover-revealed like the clock text); turns without DeepSeek usage (zero cost) or failed loads stay hidden.
 - **Failures and empty states** — a session or day without priced usage shows "no usage recorded" instead of a fabricated figure; a missing key, rejected credential, or transport error renders a muted "Balance unavailable" whose tooltip carries the Remote's own error message.
 
 ## Data update mechanics
@@ -19,15 +20,22 @@ A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin tha
 - **Old values survive refreshes** — a failed refresh keeps the last good value instead of blanking it.
 
 ## Preview
-<img width="505" height="264" alt="image" src="billing-preview.png" />
+
+A real session: the session-header badge, the detail panel (remaining amount, this session's spend next to today's all-session spend, per-model breakdown, and the today session-spend ranking), plus the turn-cost row in the message actions row:
+
+<img width="1200" alt="Billing plugin overview: session header badge, detail panel with per-model rows and today's session ranking, and the turn-cost row" src="preview-overview.png" />
+
+Close-up of the turn-cost row — money-bag icon, `本轮花费` label and the `¥` amount, in front of the copy control:
+
+<img width="640" alt="Turn-cost row close-up: money-bag icon, 本轮花费 label and ¥ amount before the copy control" src="preview-turn-cost.png" />
 
 
 ## Package layout
 
 | Package | Side | Role |
 | --- | --- | --- |
-| [`packages/llm-billing`](packages/llm-billing) — `@rayadesu/dsh-llm-billing` | Host | Owns the `/user/balance` transport and the peak/off-peak pricing table. Exposes the `billing` Remote (`getBalance`, `getSessionSpend`, `getTodaySpend`). |
-| [`packages/ui-billing`](packages/ui-billing) — `@rayadesu/dsh-client-ui-billing` | Browser | Mounts the `billing` Remote itself and contributes the session-header badge and detail panel. |
+| [`packages/llm-billing`](packages/llm-billing) — `@rayadesu/dsh-llm-billing` | Host | Owns the `/user/balance` transport and the peak/off-peak pricing table. Exposes the `billing` Remote (`getBalance`, `getSessionSpend`, `getTodaySpend`, `getTodaySessionsSpend`, `getTurnSpend`). |
+| [`packages/ui-billing`](packages/ui-billing) — `@rayadesu/dsh-client-ui-billing` | Browser | Mounts the `billing` Remote itself and contributes the session-header badge and detail panel, plus the turn-cost row in the message actions strip. |
 
 ## Prerequisites
 
@@ -36,22 +44,51 @@ A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin tha
 
 ## Installation
 
-> 📌 **About this repository**: this repo is the plugin's **only distribution
-> source** — the official [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)
-> repository does **not** ship the billing plugin. It was briefly integrated into
-> this user's fork, which has since been reverted to the official commit
-> (`141eb6fef8`); this repo no longer depends on any fork.
+### Install (published to npm)
 
-### Installation (published to npm, one command)
+The three packages are published to npm under the `@rayadesu` scope. Install the
+bundle plus the two plugin packages in one command — the bundle declares the two
+plugin packages as peer dependencies, which pnpm does not auto-install into the
+profile, so they must be named explicitly.
 
-The three packages are published to npm under the `@rayadesu` scope. Install
-the bundle plus the two plugin packages in one command (the bundle declares the
-two plugin packages as peer dependencies, which pnpm does not auto-install into
-the profile, so they must be named explicitly):
+The `dsh` command you use depends on how dsh is installed:
 
-```bash
-dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
-```
+- **Global install** — use the global `dsh` from anywhere:
+
+  ```bash
+  dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+  ```
+
+- **Source-built dsh** (a deepseek-harness checkout) — the CLI only resolves from
+  the source directory, so run it through pnpm there (`pnpm dsh` is the
+  harness-local binary, equivalent to the global `dsh`):
+
+  ```bash
+  cd deepseek-harness
+  pnpm dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+  ```
+
+### pnpm 11 release-age gate
+
+A dsh profile installs plugins through pnpm, and pnpm 11's supply-chain
+release-age gate does not pick up packages younger than 24 hours by default —
+a freshly published version is therefore not resolved immediately. To get the
+latest version right after a publish:
+
+- Disable the age gate in the profile's pnpm config:
+
+  ```yaml
+  # ~/.dsh/profiles/web/pnpm-workspace.yaml
+  minimumReleaseAge: 0
+  ```
+
+- Or, within the 24-hour window, install with an explicitly pinned version (an
+  explicit pin bypasses the age gate; replace `0.3.0` with the version you want;
+  from a source checkout, use `pnpm dsh …` as above):
+
+  ```bash
+  dsh plugin --profile web add @rayadesu/dsh-billing@0.3.0 @rayadesu/dsh-llm-billing@0.3.0 @rayadesu/dsh-client-ui-billing@0.3.0
+  ```
 
 Manual rows (only when you do not want the bundle):
 
@@ -64,6 +101,18 @@ Manual rows (only when you do not want the bundle):
       name: '@rayadesu/dsh-client-ui-billing'
 ```
 
+### Common commands
+
+Global `dsh` is assumed; a source-built dsh uses `pnpm dsh` from the
+deepseek-harness checkout instead — the subcommands are identical.
+
+```sh
+dsh plugin --profile web list    # list the web profile's installed plugins
+dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+dsh plugin --profile web remove @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+dsh plugin --profile web update  # update plugins to the latest allowed versions
+```
+
 ### Dependency notes
 
 The two plugin packages declare the DeepSeek Harness packages they build on
@@ -115,14 +164,36 @@ workspace-registered protocol package, so `packages/typert-protocol` vendors
 the published `@deepseek-ai/dsh-typert-protocol@0.1.1-rc.2` declarations; when
 the dsh dependency line moves, refresh it from the installed package.
 
-Publishing (the bundle and both plugins share one version):
+Publishing (the bundle and both plugins share one version; `prepublishOnly`
+runs the `verify` gate automatically). Use `npm publish` from **inside each
+package directory** — `pnpm publish` fails (token resolution) and a folder
+argument like `npm publish packages/llm-billing` is parsed as a GitHub
+shorthand, which triggers a bogus `git ls-remote` instead of a publish. The
+registry requires a token that bypasses 2FA (an `npm login` session token gets
+E403).
+
+**Configure the token once, so it never appears in a command** — put one line
+in `~/.npmrc` referencing an environment variable, which npm expands at
+publish time:
+
+```ini
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+Then set the variable and `npm publish` plainly — the token is in no argument
+and stays out of shell history:
 
 ```sh
-pnpm --filter @rayadesu/dsh-llm-billing publish --access public
-pnpm --filter @rayadesu/dsh-client-ui-billing publish --access public
-pnpm publish --access public   # @rayadesu/dsh-billing bundle
+export NPM_TOKEN=<your npm token>
+cd packages/llm-billing && npm publish
+cd packages/ui-billing && npm publish
+npm publish   # @rayadesu/dsh-billing bundle (repo root)
 ```
 
+(Alternatively write the real token directly into `~/.npmrc`, e.g.
+`npm config set //registry.npmjs.org/:_authToken <TOKEN>`; the commands then
+carry no token either. Either way, **never commit the token**.)
+
 ## Configuration
 
 Both packages ship sane defaults; everything below is optional.
@@ -142,12 +213,16 @@ Both packages ship sane defaults; everything below is optional.
 - Each `assistant/message` event reports three billed token buckets: **cache-hit input**, **cache-miss input** (uncached input + cache writes), and **output** (including reasoning).
 - Each message is priced at the peak/off-peak rate of its own **Beijing-time** hour, the three buckets are billed separately (`缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z`), then summed per model. Peak windows apply weekdays (Monday–Friday) only; weekends are always off-peak.
 - **Today's spend** aggregates every session's events on the current Beijing-time calendar day with the same pricing rules; event dates are also assigned in Beijing time.
+- **Turn cost** prices the messages inside the turn's `turn/start`..`turn/end` range with the same rules (located by the closing message's session id + message id).
+- **Today session ranking** aggregates today's spend per session with the same rules (a cross-day session counts only today's part), sorted descending; names come from the log's latest `session/title` event (the auto-generated Chinese title or a user rename).
 - Models without a rate row are not priced (the built-in catalog currently has the three V4 rows: V4 Flash, V4 Pro, and V4 Flash Vision Exp). Rates follow the DeepSeek pricing effective **August 17**; the weekend-off-peak rule (weekends billed at off-peak prices all day) follows the adjustment effective **August 23**.
 
 ## Known limitations
 
-- **Priced rows only** — the session and today spends only price models that have a `billing.models` row.
-- **On-demand read** — today's spend reads every session's full event log on each refresh, so cost grows with total log size.
+- **Priced rows only** — the session, turn, and today spends only price models that have a `billing.models` row.
+- **On-demand aggregation** — today's spend and the session ranking are computed on the host behind a 60-second cache; a miss scans only sessions whose persisted log changed since the last resolution (live sessions fold through the projection cells when the registry is composed), and a growing session's spend is priced incrementally (only the appended tail is re-priced).
+- **Ranking capped at 10** — the panel shows at most the top 10 sessions, with a "…N more sessions" hint.
+- **Turn cost needs a finalized closing message** — interrupted turns have no actions row, so no turn cost; cold sessions served straight from the projection cache may rank with an "Untitled" name until their log is read again.
 - **Balance does not follow automatically** — the balance stays a manual snapshot (no polling); spending from another client does not move the shown value until a refresh or browser reload.
 - **Estimate, not a promise** — the session spend prices tokens at official rates; the provider's actual billing prevails.
 

package/README.zh.md

@@ -2,14 +2,15 @@
 
 [English](README.md) | 中文
 
-一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件，在 Web 会话头部直接显示你的 **DeepSeek 账户余额**、**当前会话（本轮对话）的花费**，以及**今日所有会话的共花费**。
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件，在 Web 会话头部直接显示你的 **DeepSeek 账户余额**、**当前会话（本轮对话）的花费**，以及**今日所有会话的共花费**；每条已完成的回合还会在消息操作行里显示**本轮花费**，详情面板底部带**今日各会话花费排行**。
 
-> 余额是 `GET /user/balance` 的真实数字；会话花费与今日共花费是按官方峰/谷单价对每条消息的计费 token 逐条计价的结果，不是计费承诺。
+> 余额是 `GET /user/balance` 的真实数字；会话花费、本轮花费与今日共花费是按官方峰/谷单价对每条消息的计费 token 逐条计价的结果，不是计费承诺。
 
 ## 显示什么
 
 - **会话头部徽标** —— 两行：剩余余额（`剩余额度：¥X`）＋ 本轮对话的计费花费（`本轮对话花费：¥X`）。
-- **详情面板** —— 剩余金额、本会话花费（`本会话花费`）与其右侧的今日所有会话共花费（`今日共花费`），以及每个模型一行的花费分项（`缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z`），外加手动刷新按钮与花费说明。
+- **详情面板** —— 剩余金额、本会话花费（`本会话花费`）与其右侧的今日所有会话共花费（`今日共花费`），以及每个模型一行的花费分项（`缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z`），外加手动刷新按钮与花费说明；面板底部是**今日会话花费排行**：按今日花费从高到低排列的会话列表（会话名取日志中的中文标题，重命名后自动同步；最多显示前 10 条，其余以「…还有 N 个会话」提示）。
+- **本轮花费行** —— 每条已完成回合的收尾消息操作行**最前**（复制按钮之前）显示 `本轮花费 ¥X`：「本轮花费」一词用「本轮用量」卡片标题色、金额用卡片摘要色，**始终显示**（不随悬停隐藏，不同于时钟文本）；回合没有 DeepSeek 用量（花费为 0）或加载失败时不显示。
 - **失败与空态** —— 会话或今日没有可计价消耗时显示「暂无消耗记录」而不是编造数字；未配置 key、凭据被拒或传输错误时显示弱化的「额度不可用」，其提示携带 Remote 自己的错误信息。
 
 ## 数据更新机制
@@ -19,15 +20,22 @@
 - **刷新期间旧值保留** —— 刷新失败保留上一次有效值，不会清空。
 
 ## 显示样式
-<img width="505" height="264" alt="image" src="billing-preview.png" />
+
+真实会话中的会话头部徽标与详情面板（剩余金额、本会话花费与今日共花费、按模型分项、今日会话花费排行），以及消息操作行里的本轮花费行：
+
+<img width="1200" alt="计费插件总览：会话头部徽标、详情面板（按模型分项与今日会话花费排行）、消息操作行里的本轮花费行" src="preview-overview.png" />
+
+本轮花费行特写 —— 钱袋图标、`本轮花费` 标签与 `¥` 金额，位于复制控件之前：
+
+<img width="640" alt="本轮花费行特写：钱袋图标、本轮花费标签与金额，位于复制控件之前" src="preview-turn-cost.png" />
 
 
 ## 包结构
 
 | 包 | 侧 | 作用 |
 | --- | --- | --- |
-| [`packages/llm-billing`](packages/llm-billing) —— `@rayadesu/dsh-llm-billing` | 主机端 | 负责 `/user/balance` 传输与峰/谷计价表。对外暴露 `billing` Remote（`getBalance`、`getSessionSpend`、`getTodaySpend`）。 |
-| [`packages/ui-billing`](packages/ui-billing) —— `@rayadesu/dsh-client-ui-billing` | 浏览器端 | 自己挂载 `billing` Remote，并贡献会话头部徽标与详情面板。 |
+| [`packages/llm-billing`](packages/llm-billing) —— `@rayadesu/dsh-llm-billing` | 主机端 | 负责 `/user/balance` 传输与峰/谷计价表。对外暴露 `billing` Remote（`getBalance`、`getSessionSpend`、`getTodaySpend`、`getTodaySessionsSpend`、`getTurnSpend`）。 |
+| [`packages/ui-billing`](packages/ui-billing) —— `@rayadesu/dsh-client-ui-billing` | 浏览器端 | 自己挂载 `billing` Remote，并贡献会话头部徽标与详情面板、消息操作行里的本轮花费行。 |
 
 ## 前置条件
 
@@ -36,19 +44,45 @@
 
 ## 安装
 
-> 📌 **仓库说明**：本仓库是插件的**唯一分发来源**——deepseek-harness 官方仓库
-> （[deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness)）
-> **不含**计费插件；插件曾短暂集成于本用户的 fork，现已回退到官方提交版本
-> （`141eb6fef8`），本仓库不再依赖任何 fork。
-
 ### 安装（已发布到 npm，一条命令）
 
 三个包已发布到 npm 的 `@rayadesu` scope。一条命令同时安装 bundle 与两个插件包
-（bundle 把两个插件包声明为 peer 依赖，而 profile 默认不自动安装 peer，所以要显式列出）：
+（bundle 把两个插件包声明为 peer 依赖，而 profile 默认不自动安装 peer，所以要显式列出）。
 
-```bash
-dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
-```
+用哪个 `dsh` 命令取决于你的 dsh 安装方式：
+
+- **全局安装** —— 任意目录直接用全局 `dsh`：
+
+  ```bash
+  dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+  ```
+
+- **源码构建的 dsh**（deepseek-harness 源码目录）—— CLI 只在源码目录里能解析，
+  所以要在这个目录里用 pnpm 跑（`pnpm dsh` 即源码内二进制，等价于全局 `dsh`）：
+
+  ```bash
+  cd deepseek-harness
+  pnpm dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+  ```
+
+### pnpm 11 发布龄门槛
+
+dsh profile 通过 pnpm 安装插件，而 pnpm 11 的供应链发布龄门槛默认不会采纳发布不足
+24 小时的包——刚发布的新版本不会立即被解析。想在发布后立刻拿到最新版：
+
+- 在 profile 的 pnpm 配置里关掉发布龄门槛：
+
+  ```yaml
+  # ~/.dsh/profiles/web/pnpm-workspace.yaml
+  minimumReleaseAge: 0
+  ```
+
+- 或者在 24 小时窗口内用**显式钉版本**安装（显式钉版本可绕开门槛，把 `0.3.0` 换成你要的版本；
+  源码构建的 dsh 用 `pnpm dsh …`，同上）：
+
+  ```bash
+  dsh plugin --profile web add @rayadesu/dsh-billing@0.3.0 @rayadesu/dsh-llm-billing@0.3.0 @rayadesu/dsh-client-ui-billing@0.3.0
+  ```
 
 手动补行（仅当不想用 bundle 时）：
 
@@ -61,6 +95,18 @@ dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @ra
       name: '@rayadesu/dsh-client-ui-billing'
 ```
 
+### 常用命令
+
+下面以全局 `dsh` 为例；源码构建的 dsh 用 `pnpm dsh` 并在 deepseek-harness 源码目录执行，
+子命令完全一致。
+
+```sh
+dsh plugin --profile web list    # 列出 web profile 已安装的插件
+dsh plugin --profile web add @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+dsh plugin --profile web remove @rayadesu/dsh-billing @rayadesu/dsh-llm-billing @rayadesu/dsh-client-ui-billing
+dsh plugin --profile web update  # 把插件更新到当前允许的最新版本
+```
+
 ### 依赖说明
 
 两个插件包把它们依赖的 DeepSeek Harness 包（`@deepseek-ai/cordis`、
@@ -107,14 +153,31 @@ typert 生成器只认工作区内已注册协议包里的 `Remote`/`TypertRemot
 `packages/typert-protocol` 内嵌了 npm 上 `@deepseek-ai/dsh-typert-protocol@0.1.1-rc.2` 的
 声明文件；dsh 依赖线升级时，从安装包重新刷新它。
 
-发布（bundle 与两个插件包统一版本号）：
+发布（bundle 与两个插件包统一版本号；`prepublishOnly` 会自动跑 `verify` 门禁）。
+要用 `npm publish` 且**必须在各包目录内执行**——`pnpm publish` 会失败（token 读取方式问题），
+而 `npm publish packages/llm-billing` 这种带路径参数的形式会被 npm 解析成 GitHub 仓库简写，
+触发假的 `git ls-remote` 而不是发布。registry 要求 **bypass-2FA 的 token**（`npm login`
+的会话 token 会 E403）。
+
+**一次性配置 token（之后命令里不再出现 token）** —— 在 `~/.npmrc` 里写一行并引用环境变量，
+npm 发布时从环境展开：
+
+```ini
+//registry.npmjs.org/:_authToken=${NPM_TOKEN}
+```
+
+然后设置环境变量并直接 `npm publish` —— token 不在任何命令行参数里，也不进 shell 历史：
 
 ```sh
-pnpm --filter @rayadesu/dsh-llm-billing publish --access public
-pnpm --filter @rayadesu/dsh-client-ui-billing publish --access public
-pnpm publish --access public   # @rayadesu/dsh-billing bundle
+export NPM_TOKEN=<你的 npm token>
+cd packages/llm-billing && npm publish
+cd packages/ui-billing && npm publish
+npm publish   # @rayadesu/dsh-billing bundle（仓库根）
 ```
 
+（备选：把真实 token 直接写进 `~/.npmrc`，如 `npm config set //registry.npmjs.org/:_authToken <TOKEN>`，
+之后命令行同样不含 token。无论哪种方式，**绝不把 token 提交进仓库**。）
+
 ## 配置
 
 两个包都有合理默认值，下面都是可选的。
@@ -134,12 +197,16 @@ pnpm publish --access public   # @rayadesu/dsh-billing bundle
 - 每条 `assistant/message` 事件报告三个计费 token 桶：**缓存命中输入**、**未命中输入**（未缓存输入 + 缓存写入）、**输出**（含推理）。
 - 每条消息按其**发生时刻（北京时间）**所在的峰/谷时段单价计价，三个桶分别计费（`缓存命中 ¥X · 未命中输入 ¥Y · 输出 ¥Z`），再按模型汇总。高峰窗口仅周一至周五适用；周末全天按低谷价计费。
 - **今日共花费**按同一个计价规则汇总当天（北京时间自然日）所有会话的事件；事件归属的日期同样按北京时间计算。
+- **本轮花费**按同一规则计价该回合 `turn/start`..`turn/end` 区间内的消息（定位到收尾消息的会话 id + 消息 id）。
+- **今日会话花费排行**按同一规则按会话汇总今日花费（跨天会话只统计今天的部分），从高到低排序；会话名取日志中最后一条 `session/title` 事件（自动生成的中文标题或用户重命名的新标题）。
 - 没有费率行的模型不计入（内置价目表目前含三个 V4 行：V4 Flash、V4 Pro、V4 Flash Vision Exp）。计费按 DeepSeek **8 月 17 日实行**的费率；**周末按低谷价计费**的规则按 **8 月 23 日**生效的调整执行。
 
 ## 已知限制
 
-- **有费率行才计价** —— 会话花费与今日共花费只统计价目表（`billing.models`）里有的模型。
-- **按需读取** —— 今日共花费每次刷新都会读取所有会话的完整事件日志，成本随总日志大小增长。
+- **有费率行才计价** —— 会话花费、本轮花费与今日共花费只统计价目表（`billing.models`）里有的模型。
+- **按需聚合** —— 今日共花费与今日会话排行在主机端 60 秒缓存之后计算；缓存未命中时只扫描持久化日志自上次解析以来变化过的会话（有投影注册表时，活跃会话直接读投影单元），增长中的会话花费按增量计价（只重算新增尾部）。
+- **排行只显示前 10** —— 详情面板最多展示前 10 个会话，其余以「…还有 N 个会话」提示。
+- **本轮花费只出现在已定稿的收尾消息** —— 中断的回合没有操作行，不显示本轮花费；冷会话（投影缓存直接命中）排行标题可能显示「未命名」，待其日志被重新读取后恢复。
 - **额度不自动跟随** —— 余额保持手动刷新（无轮询），账户在其他客户端产生消耗时，界面值不会自动变化，需手动刷新或刷新浏览器。
 - **是估算，不是承诺** —— 会话花费按官方单价对 token 计价；实际计费以服务商为准。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rayadesu/dsh-billing",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "DeepSeek Harness billing plugin: account balance and this session's billed spend with a session-header badge.",
   "license": "MIT",
   "packageManager": "pnpm@11.7.0",
@@ -25,6 +25,8 @@
     "README.md",
     "README.zh.md",
     "README.i18n.yaml",
+    "preview-overview.png",
+    "preview-turn-cost.png",
     "LICENSE",
     "AGENTS.md"
   ],
@@ -32,8 +34,8 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@rayadesu/dsh-llm-billing": "^0.2.3",
-    "@rayadesu/dsh-client-ui-billing": "^0.2.3"
+    "@rayadesu/dsh-client-ui-billing": "^0.3.0",
+    "@rayadesu/dsh-llm-billing": "^0.3.0"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",