dsh-plugin-cost-meter 0.0.0-stage → 0.5.1

package/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.5.1
+
+- Manual `config.models` entries now outrank every automatic source even at
+  equal specificity (previously a same-route catalog entry could win). Added a
+  regression test for the tie-break.
+
+## 0.5.0
+
+- **Automatic silent price updates**: bundled `catalog/prices.json`, an
+  out-of-band remote catalog (`catalogUrl`, default derived from the package
+  repository), and a periodic refresh (`refreshMinutes`, default 360) that
+  swaps the live table in place. A failed refresh keeps the last good rates.
+- **Weekday-aware peak hours**: peak now applies only on the configured
+  weekdays (`peak.days`, default Monday–Friday), so weekends bill off-peak.
+  This fixes weekend over-billing.
+- **Explicit peak/off-peak rates**: catalog entries may carry
+  `cacheMissOffPeak` / `cacheHitOffPeak` / `outputOffPeak`; the multiplier is
+  only a fallback.
+- **Route-aware pricing**: usage is bucketed per `{ provider, model }`; lookups
+  support `provider/*`, model wildcards, and case/space/punctuation-insensitive
+  model ids. Manual config keys may be bare (`deepseek-flash`) or routed.
+- **Currency conversion**: a USD catalog can be displayed in CNY via
+  `config.fx.cnyPerUsd` (default 7.1).
+- **No fabricated prices**: a route with no matching rate reports
+  `priced: false` and the badge shows "未配置" instead of a fallback amount.
+- Projection state bumped to `stateVersion 3`; tests cover the new behaviour.
+
+## 0.4.0
+
+- Package as a `dsh.bundle` profile layer: `dsh plugin add dsh-plugin-cost-meter`
+  now activates the plugin automatically (no manual patch row required).
+- Split documentation into an English `README.md` and a Chinese `README.zh.md`.
+- Add contract tests (`npm test`), `LICENSE`, `.gitignore`, and `CHANGELOG.md`.
+- Add npm/GitHub package metadata (`repository`, `homepage`, `bugs`, `keywords`).
+
+## 0.3.2
+
+- Fix the DSH 0.2.1 compatibility gate: declare `engines.dsh` and widen the
+  `@deepseek-ai/dsh-session-projection` peer range to `>=0.1.5-rc.1 <1.0.0`.
+
+## 0.3.1
+
+- Price the new `deepseek-flash` model id (DSH 0.1.7+ adapter catalog); keep
+  `deepseek-v4-flash` for replayed older sessions.
+
+## 0.3.0
+
+- Migrate to the DSH >= 0.1.5 session-projection contract:
+  `stateSchema` + `wire: { viewSchema, view }`.
+- Replace the removed `@deepseek-ai/dsh-client-runtime` client dependency with
+  `dsh-client-ui-renderer` and `dsh-client-ui-session`.
+
+## 0.2.0
+
+- Peak/off-peak (time-of-day) pricing: each request is bucketed by its own
+  `event.time`, with a configurable multiplier, time zone, and peak windows.
+
+## 0.1.0
+
+- Initial release: per-session cost badge in the conversation header, with a
+  configurable price table and an optional JSON price source.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 doubsumi
+
+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.md

@@ -1,3 +1,158 @@
-# Temporary Holding Version
+# dsh-plugin-cost-meter
 
-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.
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-cost-meter)](https://www.npmjs.com/package/dsh-plugin-cost-meter)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-2ea44f)](https://github.com/topics/dsh-plugin)
+
+A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that puts a **live cost badge in the conversation header (top-right)** and prices every request with **peak / off-peak (time-of-day) tiers**.
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  Session title                                [¥0.0042]      │   ← badge here
+├──────────────────────────────────────────────────────────────┤
+│  … conversation …                                            │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## Features
+
+- **Live** — the badge updates as the host reports provider usage; no polling, no timers.
+- **Historically correct** — each request is priced by its **own wall-clock timestamp**, so a session that spans peak and off-peak stays accurate even if the page sits open overnight.
+- **Weekday-aware peak tiers** — DeepSeek bills peak only **Monday–Friday**; weekends are off-peak all day. The schedule is configurable (windows, weekdays, multiplier, time zone).
+- **Silent price sync** — a bundled price catalog plus an out-of-band remote catalog refreshed on an interval. Push a new `catalog/prices.json` and every installed copy picks it up **without a plugin release**; a failed refresh keeps the last good rates.
+- **Explicit peak/off-peak rates** — models may carry an explicit discounted pair (`cacheMiss` + `cacheMissOffPeak`), not just a multiplier.
+- **Route-aware matching** — `provider/model`, `provider/*`, `*`-model wildcards, and case/space/punctuation-insensitive model ids.
+- **Never fakes a number** — an unpriced route renders `未配置` (`unpriced`) instead of a made-up fallback rate.
+
+## Install
+
+### From npm (recommended)
+
+```cmd
+dsh plugin --profile web add dsh-plugin-cost-meter
+```
+
+The package declares `dsh.bundle`, so `dsh plugin add` activates it as a profile layer automatically — no manual `cordis.patch.yml` row is required.
+
+### From a local checkout
+
+```cmd
+dsh plugin --profile web add "link:E:/path/to/dsh-plugin-cost-meter"
+```
+
+`link:` keeps the checkout live, so edits apply after a `dsh web` restart without reinstalling.
+
+Restart the server afterwards:
+
+```cmd
+dsh web
+```
+
+## Configure
+
+The bundled `cordis.patch.yml` inserts the plugin row with defaults. Override it by adding a `cost-meter` row with the same `id` in your profile's `cordis.patch.yml` (`~/.dsh/profiles/web/cordis.patch.yml`):
+
+```yaml
+- insert:
+    - id: cost-meter
+      name: dsh-plugin-cost-meter
+      config:
+        currency: CNY                 # display currency; empty = catalog currency
+        fx:
+          cnyPerUsd: 7.1              # used when the catalog is USD and you display CNY
+        catalogUrl: ""                # "" = this package's own catalog (derived from repository)
+        refreshMinutes: 360           # silent refresh interval; 0 disables it
+        pricingTimeoutMs: 4000
+        pricingUrl: ""                # optional legacy { models, default } document
+        models:                       # manual overrides (highest priority, display currency)
+          deepseek-official/deepseek-flash:
+            inputPerM: 1.06           # off-peak base
+            cacheReadPerM: 0.021
+            cacheWritePerM: 1.06
+            outputPerM: 4.26
+        default:                      # optional fallback; omit to report unknown routes as unpriced
+          inputPerM: 1
+          outputPerM: 4
+        peak:
+          enabled: true
+          multiplier: 2               # used only when a rate has no explicit off-peak value
+          timezoneOffsetMinutes: 480  # UTC+8
+          days: [1, 2, 3, 4, 5]       # ISO weekdays; weekends are off-peak
+          windows: [[9, 12], [14, 18]]
+```
+
+Two rate styles are accepted everywhere:
+
+- **Catalog style** (peak base + optional off-peak): `cacheMiss`, `cacheHit`, `cacheWrite`, `output`, and `cacheMissOffPeak`, `cacheHitOffPeak`, `cacheWriteOffPeak`, `outputOffPeak`.
+- **Legacy style** (off-peak base): `inputPerM`, `cacheReadPerM`, `cacheWritePerM`, `outputPerM` (with optional `*Peak` fields).
+
+## Automatic price updates
+
+Prices resolve in this order (highest wins):
+
+1. `config.models` / `config.default`
+2. `config.pricingUrl` (legacy document)
+3. the **remote catalog** at `config.catalogUrl` — default: this package's own `catalog/prices.json` on GitHub, derived from `package.json.repository`
+4. the **bundled** `catalog/prices.json` (offline fallback)
+
+A timer re-reads the remote catalog and `pricingUrl` every `refreshMinutes` (default 6 hours) and swaps the live table in place:
+
+- a failed refresh **keeps the last successful data**;
+- a source that never loaded does not clear anything;
+- a price change applies to the whole session on the **next event**, and immediately on a page reload.
+
+This makes the catalog the single place to maintain rates: **edit and push `catalog/prices.json`, and installed copies update themselves** — no new plugin release. Forks get their own update channel automatically because the default URL is derived from `package.json.repository`.
+
+To point at a private mirror or a local file, set `catalogUrl` (`https://…`, a path, or `file:///…`). Set it to `""` to disable remote syncing.
+
+## Peak / off-peak
+
+- Tiering uses the **request's own `event.time`**, never "now".
+- Peak applies only on the configured weekdays (`days`, default Monday–Friday); weekends are off-peak all day.
+- The schedule comes from the catalog's `peakSchedule` (time zone, days, windows, off-peak ratio) and can be overridden field by field in `config.peak`.
+- `peak.enabled: false` bills one flat rate; `peak.timezoneOffsetMinutes` shifts the wall clock for the window check.
+
+The hover tooltip shows the current tier, the multiplier, the route, and the token breakdown.
+
+## Pricing model
+
+```
+cost = Σ_routes [ cost_off(route) + cost_peak(route) ]
+
+cost_tier(route) = (uncachedInput × miss
+                  + cacheRead     × hit
+                  + cacheWrite    × write
+                  + output        × out) / 1_000_000
+```
+
+Totals are accumulated per `{ provider, model }` route and per tier, so switching models mid-session keeps each route on its own price. A repeated usage sample for the same `(turn, step)` replaces the earlier one instead of double-counting.
+
+## Compatibility
+
+| Surface | DSH ≤ 0.1.0-rc.6 | DSH ≥ 0.1.5 |
+|---|---|---|
+| Projection contract | `schema` + `view` | `stateSchema` + `wire: { viewSchema, view }` |
+| Client deps | `@deepseek-ai/dsh-client-runtime` | `@deepseek-ai/dsh-client-ui-renderer`, `@deepseek-ai/dsh-client-ui-session` |
+| Compatibility gate | — | `engines.dsh` / `peerDependencies` must satisfy the running version |
+
+The badge uses the additive `conversation.session.header.utilities` slot; `…header.corner` is a `single` slot already occupied by a shipped plugin.
+
+## Development
+
+```cmd
+npm install
+npm test
+```
+
+`test/contract.test.mjs` covers the projection contract, weekday peak, catalog parsing, explicit dual rates, currency conversion, normalization/wildcards, unpriced routes, and manual overrides. It runs offline (`catalogUrl: ""`).
+
+## Notes
+
+- Costs are **estimates**: they depend on the provider-reported `usage` and on the price table.
+- The badge is **per session**; it does not aggregate sub-sessions or the whole account.
+- The bundled catalog is a dated snapshot — verify it against the [official pricing page](https://api-docs.deepseek.com/quick_start/pricing) and update `catalog/prices.json` when rates change.
+- The plugin is a Web surface plugin; compositions without `sessionProjections` (e.g. headless) skip registration.
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,159 @@
+# dsh-plugin-cost-meter
+
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-cost-meter)](https://www.npmjs.com/package/dsh-plugin-cost-meter)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[English](README.md) | 中文
+
+一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：在**会话头部右上角**实时显示当前对话的**消耗金额**，按**峰谷分时**计价，并**自动静默更新价格**。
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│  会话标题                                     [¥0.0042]      │   ← 徽章位置
+├──────────────────────────────────────────────────────────────┤
+│  … 对话内容 …                                                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+## 特性
+
+- **实时**：宿主上报用量后徽章即更新，不轮询、不定时器。
+- **历史准确**：每个请求按**它自己的发生时间**判峰谷，会话横跨峰谷、页面开一夜也不漂。
+- **周内高峰**：DeepSeek 高峰只在**周一至周五**，周末全天低谷；窗口、星期、倍率、时区全部可配。
+- **静默同步价格**：内置价格目录 + 远程目录定时刷新。**改并推送 `catalog/prices.json` 即可**，已安装的插件自动跟上，无需发新版；刷新失败保留上一次成功的数据。
+- **显式峰谷双价**：支持 `cacheMiss` + `cacheMissOffPeak` 这样的成对费率，而不只是乘一个倍率。
+- **路由感知匹配**：支持 `provider/model`、`provider/*`、模型通配，模型 id 忽略大小写/空格/标点差异。
+- **绝不编造数字**：未配置价格的模型显示**"未配置"**，而不是用一个兜底价假装准确。
+
+## 安装
+
+### 从 npm 安装（推荐）
+
+```cmd
+dsh plugin --profile web add dsh-plugin-cost-meter
+```
+
+插件声明了 `dsh.bundle`，`dsh plugin add` 会自动把它注册为 profile 层，**无需手写** `cordis.patch.yml`。
+
+### 本地源码安装
+
+```cmd
+dsh plugin --profile web add "link:E:/path/to/dsh-plugin-cost-meter"
+```
+
+`link:` 方式下改源码后重启 `dsh web` 即可生效。
+
+随后重启服务：
+
+```cmd
+dsh web
+```
+
+## 配置
+
+插件自带的 `cordis.patch.yml` 只插入默认行；在**你自己的** `cordis.patch.yml`（`~/.dsh/profiles/web/cordis.patch.yml`）里用相同 `id` 覆盖：
+
+```yaml
+- insert:
+    - id: cost-meter
+      name: dsh-plugin-cost-meter
+      config:
+        currency: CNY                 # 显示币种；留空 = 跟随目录币种
+        fx:
+          cnyPerUsd: 7.1              # 目录是美元、显示人民币时使用
+        catalogUrl: ""                # "" = 用本包自带目录（按 repository 推导远程地址）
+        refreshMinutes: 360           # 静默刷新间隔；0 表示关闭
+        pricingTimeoutMs: 4000
+        pricingUrl: ""                # 可选的旧版 { models, default } 文档
+        models:                       # 手动覆盖（优先级最高，显示币种）
+          deepseek-official/deepseek-flash:
+            inputPerM: 1.06           # 空闲价基准
+            cacheReadPerM: 0.021
+            cacheWritePerM: 1.06
+            outputPerM: 4.26
+        default:                      # 可选兜底；不写则未命中路由显示"未配置"
+          inputPerM: 1
+          outputPerM: 4
+        peak:
+          enabled: true
+          multiplier: 2               # 仅在费率没有显式空闲价时使用
+          timezoneOffsetMinutes: 480  # UTC+8
+          days: [1, 2, 3, 4, 5]       # ISO 星期；周末为空闲
+          windows: [[9, 12], [14, 18]]
+```
+
+费率支持两种写法：
+
+- **目录风格**（高峰基准 + 可选空闲价）：`cacheMiss`、`cacheHit`、`cacheWrite`、`output`，以及 `cacheMissOffPeak`、`cacheHitOffPeak`、`cacheWriteOffPeak`、`outputOffPeak`。
+- **旧版风格**（空闲基准）：`inputPerM`、`cacheReadPerM`、`cacheWritePerM`、`outputPerM`（可加 `*Peak`）。
+
+## 自动更新价格
+
+价格按优先级合并（高者胜）：
+
+1. `config.models` / `config.default`
+2. `config.pricingUrl`（旧版文档）
+3. **远程目录** `config.catalogUrl` —— 默认由 `package.json.repository` 推导为本包在 GitHub 上的 `catalog/prices.json`
+4. 包内自带的 `catalog/prices.json`（离线兜底）
+
+定时器每 `refreshMinutes`（默认 6 小时）重读远程目录与 `pricingUrl`，并**就地替换**生效价格表：
+
+- 刷新失败**保留上一次成功的数据**；
+- 从未成功过的源不会清空任何已有数据；
+- 价格变更会在**下一次会话事件**时对整个会话重新计价；刷新页面则立即生效。
+
+因此价格只需维护**一处**：**改并推送 `catalog/prices.json`，已安装的插件自动更新**，不用发版。默认地址由 `package.json.repository` 推导，fork 出来的仓库自动拥有自己的更新通道。
+
+需要私有镜像或本地文件时，把 `catalogUrl` 指向 `https://…`、本地路径或 `file:///…`；设为 `""` 可关闭远程同步。
+
+## 峰谷分时
+
+- 时段判定用**请求自身的 `event.time`**，不是"现在"。
+- 高峰只在配置的星期生效（`days`，默认周一至周五），周末全天空闲。
+- 时段来自目录里的 `peakSchedule`（时区、星期、窗口、低谷比例），并可用 `config.peak` 逐字段覆盖。
+- `peak.enabled: false` 退化为固定费率；`peak.timezoneOffsetMinutes` 决定窗口按哪个墙钟判断。
+
+悬停徽章可看到当前时段、倍率、模型路由与 token 明细。
+
+## 计价模型
+
+```
+cost = Σ_routes [ cost_off(route) + cost_peak(route) ]
+
+cost_tier(route) = (未命中输入 × miss
+                  + 缓存命中   × hit
+                  + 缓存写入   × write
+                  + 输出       × out) / 1_000_000
+```
+
+用量按 `{ provider, model }` 路由 × 时段分别累计，所以中途换模型也各按各的价；同一 `(turn, step)` 重复上报会替换而非重复累计。
+
+## 兼容性
+
+| 接口 | DSH ≤ 0.1.0-rc.6 | DSH ≥ 0.1.5 |
+|---|---|---|
+| 投影契约 | `schema` + `view` | `stateSchema` + `wire: { viewSchema, view }` |
+| 客户端依赖 | `@deepseek-ai/dsh-client-runtime` | `@deepseek-ai/dsh-client-ui-renderer`、`@deepseek-ai/dsh-client-ui-session` |
+| 兼容性闸门 | — | `engines.dsh` / `peerDependencies` 必须满足运行时版本 |
+
+徽章使用增量式的 `conversation.session.header.utilities` 槽位；`…header.corner` 是 `single` 槽位且已被内置插件占用。
+
+## 开发
+
+```cmd
+npm install
+npm test
+```
+
+`test/contract.test.mjs` 覆盖：投影契约、周内高峰、目录解析、显式双价、币种换算、归一化/通配、未配置路由、手动覆盖。测试离线运行（`catalogUrl: ""`）。
+
+## 说明
+
+- 金额是**估算**：依赖提供方上报的 `usage` 与价格表。
+- 徽章是**单会话**口径，不聚合子会话或整个账号。
+- 内置目录是某个时点的快照，请对照[官方价格页](https://api-docs.deepseek.com/quick_start/pricing)核对，并在费率变化时更新 `catalog/prices.json`。
+- 插件面向 Web 表层；没有 `sessionProjections` 的组合（如 headless）会跳过注册。
+
+## 许可证
+
+[MIT](LICENSE)

package/catalog/prices.json

@@ -0,0 +1,73 @@
+{
+  "schema": 1,
+  "updatedAt": "2026-10-18",
+  "currency": "USD",
+  "note": "Out-of-band price catalog for dsh-plugin-cost-meter. Every rate is USD per 1,000,000 tokens. `cacheMiss`/`cacheHit`/`output` are the PEAK (full) rates; the `*OffPeak` fields are the discounted rates. The plugin reads this file from its own package and, when `catalogUrl` is set (the default derives from package.json repository), re-reads the same shape from the network on an interval — pushing a new version of this file updates every installed copy without publishing a plugin release. Rates captured 2026-09 from the vendor-published table; DeepSeek announced Flash price cuts in 2026-09, so verify against https://api-docs.deepseek.com/quick_start/pricing before relying on them.",
+  "providers": {
+    "deepseek-official": {
+      "label": { "zh": "DeepSeek 官方", "en": "DeepSeek Official" },
+      "api": "openai-completions",
+      "docs": "https://api-docs.deepseek.com/quick_start/pricing",
+      "peakSchedule": {
+        "timezone": "UTC",
+        "days": [1, 2, 3, 4, 5],
+        "windows": [
+          { "from": "01:00", "to": "04:00" },
+          { "from": "06:00", "to": "10:00" }
+        ],
+        "offPeakRatio": 0.5,
+        "note": "Peak hours are 01:00-04:00 and 06:00-10:00 UTC Monday through Friday (09:00-12:00 and 14:00-18:00 Beijing); every other hour, plus the whole weekend, is off-peak at half price."
+      },
+      "models": {
+        "deepseek-flash": {
+          "label": "DeepSeek-V4.1-Flash",
+          "cacheHit": 0.006,
+          "cacheHitOffPeak": 0.003,
+          "cacheMiss": 0.3,
+          "cacheMissOffPeak": 0.15,
+          "output": 1.2,
+          "outputOffPeak": 0.6
+        },
+        "deepseek-v4-flash": {
+          "label": "DeepSeek-V4.1-Flash (legacy alias)",
+          "note": "The V4 Flash name is still accepted and served by V4.1 Flash at the Flash price.",
+          "cacheHit": 0.006,
+          "cacheHitOffPeak": 0.003,
+          "cacheMiss": 0.3,
+          "cacheMissOffPeak": 0.15,
+          "output": 1.2,
+          "outputOffPeak": 0.6
+        },
+        "deepseek-v4-pro": {
+          "label": "DeepSeek-V4-Pro-0813",
+          "cacheHit": 0.044,
+          "cacheHitOffPeak": 0.022,
+          "cacheMiss": 1.32,
+          "cacheMissOffPeak": 0.66,
+          "output": 3.96,
+          "outputOffPeak": 1.98
+        },
+        "deepseek-chat": {
+          "label": "DeepSeek Chat (legacy)",
+          "note": "Legacy flat-price model; the off-peak fields repeat the peak rate so it is never discounted.",
+          "cacheHit": 0.07,
+          "cacheHitOffPeak": 0.07,
+          "cacheMiss": 0.27,
+          "cacheMissOffPeak": 0.27,
+          "output": 1.1,
+          "outputOffPeak": 1.1
+        },
+        "deepseek-reasoner": {
+          "label": "DeepSeek Reasoner (legacy)",
+          "note": "Legacy flat-price model; the off-peak fields repeat the peak rate so it is never discounted.",
+          "cacheHit": 0.14,
+          "cacheHitOffPeak": 0.14,
+          "cacheMiss": 0.55,
+          "cacheMissOffPeak": 0.55,
+          "output": 2.19,
+          "outputOffPeak": 2.19
+        }
+      }
+    }
+  }
+}

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-cost-meter — profile-layer patch.
+#
+# Inserted when this package is installed as a bundle (`dsh plugin add`).
+# The row is intentionally config-free: set `config.currency` / `config.models`
+# / `config.peak` in your profile's own `cordis.patch.yml` (same id
+# `cost-meter`), which overrides this row by id.
+- insert:
+    - id: cost-meter
+      name: dsh-plugin-cost-meter

package/lib/client.js

@@ -0,0 +1,148 @@
+/**
+ * dsh-plugin-cost-meter — browser half.
+ *
+ * Renders a small, passive cost pill into the conversation header's
+ * right-aligned utilities slot (`conversation.session.header.utilities` — the
+ * top-right corner of the session header). The value is the `costUsage`
+ * session projection registered by the host half, read through the framework
+ * `useProjection` hook; it updates live as the host reports provider usage.
+ *
+ * An unpriced route renders "未配置" instead of a fabricated amount, matching
+ * the host's `priced: false` contract.
+ *
+ * Loaded by the client module loader (`window.__ModuleLoader__`).
+ */
+const TAG_ID = "dsh-plugin-cost-meter/client.css";
+
+const css = [
+  ".dsh-cost-meter-badge{",
+  "border:1px solid var(--dsw-alias-border-l2);",
+  "color:var(--dsw-alias-label-primary);",
+  "font-family:var(--dsw-font-family);",
+  "background:transparent;",
+  "border-radius:18px;",
+  "height:32px;",
+  "padding:6px 12px;",
+  "font-size:13px;",
+  "font-weight:400;",
+  "line-height:20px;",
+  "display:inline-flex;",
+  "align-items:center;",
+  "white-space:nowrap;",
+  "font-variant-numeric:tabular-nums;",
+  "cursor:default;",
+  "}",
+  ".dsh-cost-meter-badge[data-priced='0']{",
+  "color:var(--dsw-alias-label-dimmed);",
+  "border-style:dashed;",
+  "}"
+].join("");
+
+window.__ModuleLoader__.load({
+  id: "dsh-plugin-cost-meter",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+    var react_jsx_runtime = require("react/jsx-runtime");
+
+    // Inject the badge stylesheet once.
+    if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(TAG_ID) + "]") === null) {
+      var tag = document.createElement("style");
+      tag.dataset.plugin = "dsh-plugin-cost-meter";
+      tag.dataset.pluginCss = TAG_ID;
+      tag.textContent = css;
+      document.head.appendChild(tag);
+    }
+
+    var cssClass = { badge: "dsh-cost-meter-badge" };
+
+    /** Format a cost with adaptive precision for tiny per-conversation sums. */
+    function formatCost(cost, currency) {
+      var abs = Math.abs(cost);
+      var fractionDigits;
+      if (abs === 0) fractionDigits = 2;
+      else if (abs >= 1) fractionDigits = 2;
+      else if (abs >= 0.01) fractionDigits = 4;
+      else if (abs >= 0.0001) fractionDigits = 6;
+      else fractionDigits = 8;
+      try {
+        return new Intl.NumberFormat(undefined, {
+          style: "currency",
+          currency: currency,
+          currencyDisplay: "narrowSymbol",
+          minimumFractionDigits: fractionDigits,
+          maximumFractionDigits: fractionDigits
+        }).format(cost);
+      } catch (_err) {
+        return cost.toFixed(fractionDigits) + " " + currency;
+      }
+    }
+
+    /** Hover breakdown for the badge. */
+    function tooltip(value) {
+      var tier = value.currentTier === "peak" ? "高峰时段 (x" + value.peakMultiplier + ")" : "空闲时段";
+      var route = (value.provider != null ? value.provider + "/" : "") + (value.model != null ? value.model : "未知");
+      var lines = [
+        "当前对话估算费用",
+        "当前时段: " + tier,
+        "模型: " + route,
+        "输入: " + value.uncachedInputTokens.toLocaleString() + " tokens",
+        "输出: " + value.outputTokens.toLocaleString() + " tokens",
+        "缓存命中读取: " + value.cacheReadTokens.toLocaleString() + " tokens",
+        "缓存写入: " + value.cacheWriteTokens.toLocaleString() + " tokens"
+      ];
+      if (!value.priced) {
+        lines.push("");
+        lines.push("未配置价格: " + (value.unpricedRoutes || []).join(", "));
+        lines.push("请在插件 config.models 或价格目录中补充该模型");
+      } else {
+        lines.push("");
+        lines.push("价格随目录自动同步; 可在插件 config 中覆盖");
+      }
+      return lines.join("\n");
+    }
+
+    /**
+     * The badge. Session-scope standard kit supplies `useProjection`; the
+     * value reads `undefined` until the first projection baseline lands.
+     */
+    function CostBadge(props) {
+      var useProjection = props.useProjection;
+      var value = useProjection("costUsage");
+      if (!value) return null;
+      var priced = value.priced !== false;
+      var label = priced ? formatCost(value.cost, value.currency) : "未配置";
+      var description = tooltip(value);
+      return react_jsx_runtime.jsx("span", {
+        className: cssClass.badge,
+        title: description,
+        role: "status",
+        "aria-label": description,
+        "data-priced": priced ? "1" : "0",
+        children: label
+      });
+    }
+
+    var inject = ["slots"];
+
+    /**
+     * Mount the badge into the header utilities slot once ui-conversation
+     * declares it.
+     * @param ctx - browser root context carrying the slots service.
+     */
+    function apply(ctx) {
+      ctx.slots.inject("conversation.session.header.utilities", function () {
+        return ctx.slots.register({
+          name: "conversation.session.header.utilities",
+          id: "cost-meter",
+          order: 0
+        }, CostBadge);
+      });
+    }
+
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  }
+});

package/lib/index.js

@@ -0,0 +1,574 @@
+/**
+ * dsh-plugin-cost-meter — host half.
+ *
+ * Registers a `costUsage` session-projection unit that folds durable provider
+ * token usage (the same `assistant/chunk` / `assistant/message` usage samples
+ * the built-in token meter consumes) and attributes each step's usage to the
+ * `{ provider, model }` route named by the latest `request/header`.
+ *
+ * Price sources, highest priority first:
+ *   1. manual `config.models` / `config.default`   (display currency)
+ *   2. legacy `config.pricingUrl` JSON document     (`{ models, default }`)
+ *   3. remote catalog `config.catalogUrl`           (default: this package's
+ *      own `catalog/prices.json` on GitHub, derived from `package.json`)
+ *   4. bundled `catalog/prices.json`                (offline fallback)
+ *
+ * Silent updates: a timer re-reads the remote catalog / pricingUrl on an
+ * interval (`config.refreshMinutes`, default 360) and swaps the live table.
+ * A failed refresh keeps the last successful data; a failed source never
+ * clears data it did not create. The badge reflects a price change on the
+ * next session event (the whole session is re-priced) or a page reload.
+ *
+ * Peak / off-peak
+ * ---------------
+ * Each request is tiered by its own `event.time` (never by "now"), and the
+ * schedule supports a weekday filter — DeepSeek bills peak only Monday
+ * through Friday, so weekends are off-peak all day. Rates may be given as an
+ * explicit peak/off-peak pair (`cacheMiss` + `cacheMissOffPeak`) or as a
+ * single off-peak base scaled by `peak.multiplier`.
+ *
+ * Unknown routes are reported as `priced: false` instead of being billed at a
+ * made-up fallback rate; the badge shows "unpriced" for them.
+ *
+ * @module dsh-plugin-cost-meter
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { z as zod } from "zod";
+
+/** Cordis plugin name (diagnostics). */
+const name = "cost-meter";
+/** No required services: `sessionProjections` is an optional capability. */
+const inject = [];
+
+/** Built-in schedule: DeepSeek Beijing peak, weekdays only, half price off peak. */
+const PEAK_DEFAULTS = {
+  enabled: true,
+  multiplier: 2,
+  ratio: 0.5,
+  timezoneOffsetMinutes: 480,
+  days: [1, 2, 3, 4, 5],
+  windows: [[9, 12], [14, 18]]
+};
+
+/** How often a silent refresh runs when `refreshMinutes` is not configured. */
+const DEFAULT_REFRESH_MINUTES = 360;
+/** Default CNY/USD rate for converting a USD catalog into a CNY display. */
+const DEFAULT_CNY_PER_USD = 7.1;
+
+const ZERO_BUCKETS = () => ({ uncachedInputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 });
+
+function readJson(url) {
+  try {
+    return JSON.parse(readFileSync(url, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/** This package's manifest, used to derive the default catalog URL. */
+const PACKAGE = readJson(new URL("../package.json", import.meta.url)) ?? {};
+/** The bundled offline catalog. */
+const BUNDLED_CATALOG = readJson(new URL("../catalog/prices.json", import.meta.url)) ?? { schema: 1, providers: {} };
+
+/** Finite, non-negative number or undefined. */
+function num(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+
+/** Matching key: case/space/punctuation-insensitive, bracket annotations dropped. */
+function norm(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/[（(\[][^)\]）]*[)\]）]/g, "")
+    .replace(/[\s\-_.]+/g, "");
+}
+
+/** Split a `provider/model` key; a bare key matches any provider. */
+function splitKey(key) {
+  const index = key.indexOf("/");
+  return index < 0 ? { provider: "*", model: key } : { provider: key.slice(0, index), model: key.slice(index + 1) };
+}
+
+/**
+ * Parse one rate entry. Catalog style (`cacheMiss`/`cacheHit`/`output`, peak
+ * base with optional `*OffPeak`) and legacy style (`*PerM`, off-peak base)
+ * are both accepted.
+ * @returns `{ peak, off }` per-1M buckets, or undefined when incomplete.
+ */
+function parseRates(entry, { ratio, multiplier }) {
+  if (entry == null || typeof entry !== "object") return undefined;
+  const catalogStyle = entry.cacheMiss !== undefined || entry.cacheHit !== undefined || entry.output !== undefined;
+  if (catalogStyle) {
+    const miss = num(entry.cacheMiss);
+    const out = num(entry.output);
+    if (miss === undefined || out === undefined) return undefined;
+    const hit = num(entry.cacheHit) ?? 0;
+    const write = num(entry.cacheWrite) ?? miss;
+    return {
+      peak: { miss, hit, write, out },
+      off: {
+        miss: num(entry.cacheMissOffPeak) ?? miss * ratio,
+        hit: num(entry.cacheHitOffPeak) ?? hit * ratio,
+        write: num(entry.cacheWriteOffPeak) ?? write * ratio,
+        out: num(entry.outputOffPeak) ?? out * ratio
+      }
+    };
+  }
+  const miss = num(entry.inputPerM);
+  const out = num(entry.outputPerM);
+  if (miss === undefined || out === undefined) return undefined;
+  const hit = num(entry.cacheReadPerM) ?? 0;
+  const write = num(entry.cacheWritePerM) ?? miss;
+  return {
+    off: { miss, hit, write, out },
+    peak: {
+      miss: num(entry.inputPerMPeak) ?? miss * multiplier,
+      hit: num(entry.cacheReadPerMPeak) ?? hit * multiplier,
+      write: num(entry.cacheWritePerMPeak) ?? write * multiplier,
+      out: num(entry.outputPerMPeak) ?? out * multiplier
+    }
+  };
+}
+
+/** `"01:00"` / `1` → hours past midnight (fractional). */
+function parseClock(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  const match = /^(\d{1,2})(?::(\d{1,2}))?$/.exec(String(value ?? "").trim());
+  if (match === null) return undefined;
+  return Number(match[1]) + Number(match[2] ?? 0) / 60;
+}
+
+/** Accept `[[9,12]]`, `[{from:"09:00",to:"12:00"}]`, or `[{fromHour,toHour}]`. */
+function parseWindows(list) {
+  const out = [];
+  for (const item of Array.isArray(list) ? list : []) {
+    if (Array.isArray(item) && item.length === 2) {
+      const from = Number(item[0]);
+      const to = Number(item[1]);
+      if (Number.isFinite(from) && Number.isFinite(to)) out.push([from, to]);
+    } else if (item !== null && typeof item === "object") {
+      const from = parseClock(item.from ?? item.fromHour);
+      const to = parseClock(item.to ?? item.toHour);
+      if (from !== undefined && to !== undefined) out.push([from, to]);
+    }
+  }
+  return out;
+}
+
+/** Minutes east of UTC for a numeric offset, `UTC+8`, or a well-known zone name. */
+function parseOffset(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  const text = String(value ?? "").trim();
+  const utc = /^UTC([+-])(\d{1,2})(?::(\d{2}))?$/i.exec(text);
+  if (utc !== null) return (utc[1] === "-" ? -1 : 1) * (Number(utc[2]) * 60 + Number(utc[3] ?? 0));
+  if (/^UTC$/i.test(text)) return 0;
+  const named = { "Asia/Shanghai": 480, "Asia/Chongqing": 480, "Asia/Hong_Kong": 480, "Asia/Taipei": 480, "Asia/Tokyo": 540 };
+  return named[text];
+}
+
+/**
+ * Resolve the effective peak schedule from the catalog's `peakSchedule` and
+ * the plugin config (config wins field by field).
+ */
+function resolveSchedule(configPeak, catalogSchedule) {
+  const schedule = { ...PEAK_DEFAULTS, days: [...PEAK_DEFAULTS.days], windows: PEAK_DEFAULTS.windows.map((w) => [...w]) };
+  if (catalogSchedule !== null && typeof catalogSchedule === "object") {
+    const offset = parseOffset(catalogSchedule.timezone);
+    if (offset !== undefined) schedule.timezoneOffsetMinutes = offset;
+    if (Array.isArray(catalogSchedule.days)) {
+      const days = catalogSchedule.days.filter((d) => Number.isInteger(d) && d >= 0 && d <= 6);
+      if (days.length > 0) schedule.days = days;
+    }
+    const windows = parseWindows(catalogSchedule.windows);
+    if (windows.length > 0) schedule.windows = windows;
+    const ratio = num(catalogSchedule.offPeakRatio);
+    if (ratio !== undefined && ratio > 0 && ratio <= 1) schedule.ratio = ratio;
+  }
+  const source = configPeak ?? {};
+  if (typeof source.enabled === "boolean") schedule.enabled = source.enabled;
+  if (num(source.multiplier) !== undefined && source.multiplier > 0) schedule.multiplier = source.multiplier;
+  if (typeof source.timezoneOffsetMinutes === "number" && Number.isFinite(source.timezoneOffsetMinutes)) schedule.timezoneOffsetMinutes = source.timezoneOffsetMinutes;
+  if (Array.isArray(source.days)) {
+    const days = source.days.filter((d) => Number.isInteger(d) && d >= 0 && d <= 6);
+    if (days.length > 0) schedule.days = days;
+  }
+  const windows = parseWindows(source.windows);
+  if (windows.length > 0) schedule.windows = windows;
+  const ratio = num(source.offPeakRatio);
+  if (ratio !== undefined && ratio > 0 && ratio <= 1) schedule.ratio = ratio;
+  return schedule;
+}
+
+/** Whether an instant falls inside a peak window on a peak weekday. */
+function isPeakAt(timeMs, schedule) {
+  if (!schedule.enabled || schedule.days.length === 0 || schedule.windows.length === 0) return false;
+  const shifted = new Date(timeMs + schedule.timezoneOffsetMinutes * 60000);
+  if (!schedule.days.includes(shifted.getUTCDay())) return false;
+  const minutes = shifted.getUTCHours() * 60 + shifted.getUTCMinutes();
+  for (const [from, to] of schedule.windows) {
+    if (minutes >= from * 60 && minutes < to * 60) return true;
+  }
+  return false;
+}
+
+/** Currency factor between a catalog currency and the display currency. */
+function fxFactor(from, to, fx) {
+  const source = String(from ?? "").toUpperCase();
+  const target = String(to ?? "").toUpperCase();
+  if (source === "" || target === "" || source === target) return 1;
+  const cnyPerUsd = num(fx?.cnyPerUsd) ?? DEFAULT_CNY_PER_USD;
+  if (source === "USD" && target === "CNY") return cnyPerUsd;
+  if (source === "CNY" && target === "USD") return 1 / cnyPerUsd;
+  return 1;
+}
+
+function scaleRates(rates, factor) {
+  if (factor === 1) return rates;
+  const scale = (bucket) => ({ miss: bucket.miss * factor, hit: bucket.hit * factor, write: bucket.write * factor, out: bucket.out * factor });
+  return { peak: scale(rates.peak), off: scale(rates.off) };
+}
+
+/** Flatten one catalog document into priced route entries. */
+function catalogEntries(catalog, { displayCurrency, fx, schedule, source, rank }) {
+  const entries = [];
+  const currency = catalog?.currency ?? "USD";
+  const factor = fxFactor(currency, displayCurrency, fx);
+  for (const [provider, declaration] of Object.entries(catalog?.providers ?? {})) {
+    for (const [model, entry] of Object.entries(declaration?.models ?? {})) {
+      const rates = parseRates(entry, { ratio: schedule.ratio, multiplier: schedule.multiplier });
+      if (rates === undefined) continue;
+      entries.push({ provider, model, rates: scaleRates(rates, factor), source, rank });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Build the live price table: bundled catalog, remote catalog, legacy pricing
+ * documents, then manual config (highest priority).
+ */
+function buildPriceTable({ bundled, remote, legacyDocs = [], config, schedule }) {
+  const catalogCurrency = remote?.currency ?? bundled?.currency ?? "USD";
+  const displayCurrency = (typeof config?.currency === "string" && config.currency !== "" && config.currency)
+    || catalogCurrency;
+  const entries = [];
+  entries.push(...catalogEntries(bundled, { displayCurrency, fx: config?.fx, schedule, source: "bundled", rank: 1 }));
+  if (remote !== undefined) entries.push(...catalogEntries(remote, { displayCurrency, fx: config?.fx, schedule, source: "remote", rank: 2 }));
+  for (const doc of legacyDocs) {
+    const factor = fxFactor(doc?.currency, displayCurrency, config?.fx);
+    for (const [key, entry] of Object.entries(doc?.models ?? {})) {
+      const rates = parseRates(entry, { ratio: schedule.ratio, multiplier: schedule.multiplier });
+      if (rates === undefined) continue;
+      const { provider, model } = splitKey(key);
+      entries.push({ provider, model, rates: scaleRates(rates, factor), source: "pricingUrl", rank: 3 });
+    }
+  }
+  for (const [key, entry] of Object.entries(config?.models ?? {})) {
+    const rates = parseRates(entry, { ratio: schedule.ratio, multiplier: schedule.multiplier });
+    if (rates === undefined) continue;
+    const { provider, model } = splitKey(key);
+    entries.push({ provider, model, rates, source: "config", rank: 4 });
+  }
+  const fallback = parseRates(config?.default, { ratio: schedule.ratio, multiplier: schedule.multiplier })
+    ?? parseRates(legacyDocs.at(-1)?.default, { ratio: schedule.ratio, multiplier: schedule.multiplier });
+  return { currency: displayCurrency, entries, default: fallback };
+}
+
+/**
+ * Resolve a route's priced entry. Manual config outranks every automatic
+ * source; within equal rank, a more specific route beats a wildcard, and a
+ * later entry wins an exact tie. A provider wildcard and a model wildcard are
+ * both supported, and a bare model key matches every provider.
+ * @returns the matched entry, or undefined when the route is unpriced.
+ */
+function lookupPrice(table, provider, model) {
+  if (table === undefined) return undefined;
+  const wantedProvider = norm(provider);
+  const wantedModel = norm(model ?? "");
+  let best;
+  for (const entry of table.entries) {
+    if (entry.provider !== "*" && norm(entry.provider) !== wantedProvider) continue;
+    if (entry.model !== "*" && norm(entry.model) !== wantedModel) continue;
+    const score = (entry.provider === "*" ? 0 : 2) + (entry.model === "*" ? 0 : 2);
+    const rank = entry.rank ?? 0;
+    const stronger = best === undefined
+      || rank > best.rank
+      || (rank === best.rank && score >= best.score);
+    if (stronger) best = { entry, score, rank };
+  }
+  return best?.entry;
+}
+
+/** Cost of one token bucket under one rate bucket. */
+function costOf(buckets, rate) {
+  return (
+    buckets.uncachedInputTokens * rate.miss +
+    buckets.cacheReadTokens * rate.hit +
+    buckets.cacheWriteTokens * rate.write +
+    buckets.outputTokens * rate.out
+  ) / 1_000_000;
+}
+
+/** Disjoint provider usage buckets (reasoning is already inside output). */
+const bucketsFrom = (usage) => ({
+  uncachedInputTokens: usage.inputTokens ?? 0,
+  outputTokens: usage.outputTokens ?? 0,
+  cacheReadTokens: usage.cacheReadTokens ?? 0,
+  cacheWriteTokens: usage.cacheWriteTokens ?? 0
+});
+const bucketsEqual = (a, b) => a.uncachedInputTokens === b.uncachedInputTokens && a.outputTokens === b.outputTokens && a.cacheReadTokens === b.cacheReadTokens && a.cacheWriteTokens === b.cacheWriteTokens;
+const addBuckets = (a, b) => ({
+  uncachedInputTokens: (a?.uncachedInputTokens ?? 0) + b.uncachedInputTokens,
+  outputTokens: (a?.outputTokens ?? 0) + b.outputTokens,
+  cacheReadTokens: (a?.cacheReadTokens ?? 0) + b.cacheReadTokens,
+  cacheWriteTokens: (a?.cacheWriteTokens ?? 0) + b.cacheWriteTokens
+});
+const subBuckets = (a, b) => ({
+  uncachedInputTokens: (a?.uncachedInputTokens ?? 0) - b.uncachedInputTokens,
+  outputTokens: (a?.outputTokens ?? 0) - b.outputTokens,
+  cacheReadTokens: (a?.cacheReadTokens ?? 0) - b.cacheReadTokens,
+  cacheWriteTokens: (a?.cacheWriteTokens ?? 0) - b.cacheWriteTokens
+});
+
+/** Fetch a JSON document from an http(s) URL, a local path, or a file:// URL. */
+async function fetchJson(url, timeoutMs) {
+  if (url.startsWith("file://")) return JSON.parse(readFileSync(fileURLToPath(url), "utf8"));
+  if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(url)) return JSON.parse(readFileSync(url, "utf8"));
+  const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), headers: { accept: "application/json" } });
+  if (!response.ok) throw new Error(`HTTP ${response.status}`);
+  return await response.json();
+}
+
+/** Default catalog URL derived from the package's repository (fork-friendly). */
+function defaultCatalogUrl() {
+  const repository = String(PACKAGE.repository?.url ?? "");
+  const match = /github\.com[/:]([^/]+)\/([^/]+?)(?:\.git)?(?:#.*)?$/.exec(repository.trim());
+  return match === null ? "" : `https://raw.githubusercontent.com/${match[1]}/${match[2]}/main/catalog/prices.json`;
+}
+
+/** The first provider-declared peak schedule in a catalog document. */
+function firstSchedule(catalog) {
+  for (const declaration of Object.values(catalog?.providers ?? {})) {
+    if (declaration?.peakSchedule !== undefined) return declaration.peakSchedule;
+  }
+  return undefined;
+}
+
+/**
+ * Load every configured source. Each source fails independently and keeps the
+ * previous successful payload, so a transient network error never drops data.
+ * @returns `{ table, schedule, remote, legacy }`.
+ */
+async function loadSources(config, warn, previous) {
+  const timeoutMs = num(config.pricingTimeoutMs) ?? 4000;
+  let remote = previous?.remote;
+  let legacy = previous?.legacy;
+
+  const catalogUrl = config.catalogUrl === undefined ? defaultCatalogUrl() : String(config.catalogUrl ?? "");
+  if (catalogUrl !== "") {
+    try {
+      remote = await fetchJson(catalogUrl, timeoutMs);
+    } catch (error) {
+      if (previous?.remote === undefined) warn(`catalog ${JSON.stringify(catalogUrl)} unavailable: ${error?.message ?? error}; using the bundled catalog`);
+    }
+  }
+  if (typeof config.pricingUrl === "string" && config.pricingUrl !== "") {
+    try {
+      legacy = await fetchJson(config.pricingUrl, timeoutMs);
+    } catch (error) {
+      if (previous?.legacy === undefined) warn(`pricing ${JSON.stringify(config.pricingUrl)} unavailable: ${error?.message ?? error}; using bundled rates`);
+    }
+  }
+
+  const schedule = resolveSchedule(config.peak, firstSchedule(BUNDLED_CATALOG) ?? firstSchedule(remote));
+  const table = buildPriceTable({ bundled: BUNDLED_CATALOG, remote, legacyDocs: legacy === undefined ? [] : [legacy], config, schedule });
+  return { table, schedule, remote, legacy };
+}
+
+/**
+ * Build the `costUsage` projection unit over a live source ref.
+ * State is pure token accounting per (route × tier); `wire.view` prices it.
+ */
+function buildProjection(live) {
+  const bucketsSchema = zod.object({
+    uncachedInputTokens: zod.number().int().nonnegative(),
+    outputTokens: zod.number().int().nonnegative(),
+    cacheReadTokens: zod.number().int().nonnegative(),
+    cacheWriteTokens: zod.number().int().nonnegative()
+  }).strict();
+
+  const routeSchema = zod.object({
+    provider: zod.string().nullable(),
+    model: zod.string().nullable(),
+    off: bucketsSchema,
+    peak: bucketsSchema
+  }).strict();
+
+  const stateSchema = zod.object({
+    provider: zod.string().nullable(),
+    model: zod.string().nullable(),
+    perRoute: zod.record(zod.string(), routeSchema),
+    last: zod.union([
+      zod.null(),
+      zod.object({
+        turn: zod.number().int(),
+        step: zod.number().int(),
+        route: zod.string(),
+        tier: zod.enum(["off", "peak"]),
+        buckets: bucketsSchema
+      }).strict()
+    ])
+  }).strict();
+
+  const viewSchema = zod.object({
+    currency: zod.string(),
+    cost: zod.number(),
+    priced: zod.boolean(),
+    provider: zod.string().nullable(),
+    model: zod.string().nullable(),
+    currentTier: zod.enum(["off", "peak"]),
+    peakMultiplier: zod.number(),
+    unpricedRoutes: zod.array(zod.string()),
+    uncachedInputTokens: zod.number().int().nonnegative(),
+    outputTokens: zod.number().int().nonnegative(),
+    cacheReadTokens: zod.number().int().nonnegative(),
+    cacheWriteTokens: zod.number().int().nonnegative()
+  }).strict();
+
+  return {
+    key: "costUsage",
+    stateSchema,
+    init: () => ({ provider: null, model: null, perRoute: {}, last: null }),
+    apply(state, event) {
+      const liveNow = live.current;
+      let provider = state.provider;
+      let model = state.model;
+      if (event.type === "request/header") {
+        const headerConfig = event.data?.header?.config;
+        if (typeof headerConfig?.provider === "string" && headerConfig.provider !== "") provider = headerConfig.provider;
+        if (typeof headerConfig?.model === "string" && headerConfig.model !== "") model = headerConfig.model;
+      }
+
+      let turn;
+      let step;
+      let usage;
+      if (event.type === "assistant/chunk" && event.data?.chunk?.type === "usage") {
+        turn = event.data.turn;
+        step = event.data.step;
+        usage = event.data.chunk.usage;
+      } else if (event.type === "assistant/message" && event.data?.usage !== undefined) {
+        turn = event.data.turn;
+        step = event.data.step;
+        usage = event.data.usage;
+      } else {
+        return provider === state.provider && model === state.model ? state : { ...state, provider, model };
+      }
+
+      const tier = isPeakAt(event.time, liveNow.schedule) ? "peak" : "off";
+      const route = `${provider ?? ""}\u0000${model ?? ""}`;
+      const buckets = bucketsFrom(usage);
+
+      const previous = state.last !== null && state.last.turn === turn && state.last.step === step ? state.last : undefined;
+      if (previous !== undefined && previous.route === route && previous.tier === tier && bucketsEqual(previous.buckets, buckets)) {
+        return provider === state.provider && model === state.model ? state : { ...state, provider, model };
+      }
+
+      const perRoute = { ...state.perRoute };
+      if (previous !== undefined) {
+        const replaced = { ...(perRoute[previous.route] ?? { provider: null, model: null, off: ZERO_BUCKETS(), peak: ZERO_BUCKETS() }) };
+        replaced[previous.tier] = subBuckets(replaced[previous.tier], previous.buckets);
+        perRoute[previous.route] = replaced;
+      }
+      const entry = { ...(perRoute[route] ?? { provider, model, off: ZERO_BUCKETS(), peak: ZERO_BUCKETS() }) };
+      entry.provider = provider;
+      entry.model = model;
+      entry[tier] = addBuckets(entry[tier], buckets);
+      perRoute[route] = entry;
+
+      return { provider, model, perRoute, last: { turn, step, route, tier, buckets } };
+    },
+    wire: {
+      viewSchema,
+      view(state) {
+        const liveNow = live.current;
+        const table = liveNow.table;
+        const totals = ZERO_BUCKETS();
+        const unpriced = [];
+        let cost = 0;
+        for (const entry of Object.values(state.perRoute)) {
+          const matched = lookupPrice(table, entry.provider, entry.model);
+          if (matched === undefined) {
+            unpriced.push(`${entry.provider ?? "?"}/${entry.model ?? "?"}`);
+          } else {
+            cost += costOf(entry.off, matched.rates.off) + costOf(entry.peak, matched.rates.peak);
+          }
+          totals.uncachedInputTokens += entry.off.uncachedInputTokens + entry.peak.uncachedInputTokens;
+          totals.outputTokens += entry.off.outputTokens + entry.peak.outputTokens;
+          totals.cacheReadTokens += entry.off.cacheReadTokens + entry.peak.cacheReadTokens;
+          totals.cacheWriteTokens += entry.off.cacheWriteTokens + entry.peak.cacheWriteTokens;
+        }
+        return {
+          currency: table.currency,
+          cost,
+          priced: unpriced.length === 0,
+          provider: state.provider,
+          model: state.model,
+          currentTier: isPeakAt(Date.now(), liveNow.schedule) ? "peak" : "off",
+          peakMultiplier: liveNow.schedule.multiplier,
+          unpricedRoutes: unpriced,
+          ...totals
+        };
+      }
+    },
+    stateVersion: 3
+  };
+}
+
+function warnWith(ctx, message) {
+  try {
+    if (ctx?.logger?.warn != null) ctx.logger.warn(`[dsh-plugin-cost-meter] ${message}`);
+    else console.warn(`[dsh-plugin-cost-meter] ${message}`);
+  } catch {
+    console.warn(`[dsh-plugin-cost-meter] ${message}`);
+  }
+}
+
+/**
+ * Register the projection and start the silent refresh loop.
+ * @param ctx - host root context.
+ * @param config - the raw plugin row config.
+ */
+async function apply(ctx, config) {
+  const cfg = config ?? {};
+  const live = { current: undefined };
+  const warn = (message) => warnWith(ctx, message);
+
+  live.current = await loadSources(cfg, warn, undefined);
+  ctx.inject(["sessionProjections"], (projectionCtx) => {
+    projectionCtx.sessionProjections.register(buildProjection(live));
+  });
+
+  const minutes = num(cfg.refreshMinutes) ?? DEFAULT_REFRESH_MINUTES;
+  if (minutes > 0) {
+    let busy = false;
+    const timer = setInterval(async () => {
+      if (busy) return;
+      busy = true;
+      try {
+        live.current = await loadSources(cfg, warn, live.current);
+      } catch (error) {
+        warn(`price refresh failed: ${error?.message ?? error}; keeping the previous rates`);
+      } finally {
+        busy = false;
+      }
+    }, minutes * 60_000);
+    timer.unref?.();
+    if (typeof ctx.effect === "function") ctx.effect(() => () => clearInterval(timer), "dsh-plugin-cost-meter: price refresh");
+  }
+}
+
+/** Internal helpers exported for the contract tests. */
+const internals = { buildPriceTable, catalogEntries, isPeakAt, lookupPrice, parseRates, resolveSchedule };
+
+export { apply, inject, internals, name };

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "dsh-plugin-cost-meter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.1",
+  "description": "Live per-session cost badge in the DeepSeek Harness conversation header (top-right), with peak/off-peak (峰谷分时) pricing.",
+  "keywords": [
+    "dsh-plugin",
+    "deepseek-harness",
+    "dsh",
+    "deepseek",
+    "cost",
+    "pricing",
+    "token",
+    "usage",
+    "billing"
+  ],
+  "license": "MIT",
+  "author": "doubsumi",
+  "homepage": "https://github.com/doubsumi/dsh-plugin-cost-meter#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doubsumi/dsh-plugin-cost-meter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/doubsumi/dsh-plugin-cost-meter/issues"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "catalog/prices.json",
+    "cordis.patch.yml",
+    "README.zh.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "dsh": ">=0.1.5-rc.1 <1.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-session-projection": ">=0.1.5-rc.1 <1.0.0"
+  },
+  "scripts": {
+    "test": "node test/contract.test.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-renderer",
+        "@deepseek-ai/dsh-client-ui-session",
+        "@deepseek-ai/dsh-client-ui-conversation"
+      ],
+      "platform": "web"
+    }
+  }
+}