dsh-plugin-usage 0.2.0 → 0.3.0

package/README.md

@@ -1,141 +1,72 @@
 # dsh-plugin-usage
 
-DeepSeek Harness 的 **Token 用量统计**插件（UI 参考 CC Switch 的「用量统计」功能）。
+DeepSeek Harness 的 **Token 用量统计**插件：按天 / 自定义范围查看 Token、调用次数与成本，支持模型筛选、定价配置和年度热力图。
 
-> A **token usage statistics** plugin for DeepSeek Harness, inspired by CC Switch's usage stats.
->
-> GitHub: [bennett-dsh/dsh-plugin-usage](https://github.com/bennett-dsh/dsh-plugin-usage) · npm: `dsh-plugin-usage`
+> Token usage statistics for DeepSeek Harness.
 
-- 按天 / 自定义时间范围查看 Token 用量
-- 按模型筛选，查看调用次数、输入/输出 Token、缓存命中、费用
-- 可配置的每百万 Token 价格表（内置 DeepSeek 常见模型默认价，未配置的模型标记为「未定价」）
-- 深/浅色主题自适应（使用 DSH 主题变量），无第三方图表库（手写堆叠柱状图）
+![用量统计](image.png)
+![明细与热力图](image-1.png)
 
-> Features: daily / custom-range views · model filtering · call counts, in/out tokens, cache hits & cost · configurable per-million-token pricing (built-in defaults for common DeepSeek models; unpriced models are flagged) · dark/light theme via DSH tokens · zero chart dependencies (hand-written stacked bars).
+## 功能
 
-## 功能特性 / Features
+- 今日 / 近 7 天 / 近 30 天 / 全部 / 自定义范围（不限跨度），按小时·天聚合
+- 模型筛选、按模型明细（请求数、输入/输出、缓存、成本、占比）
+- KPI 网格里的「模型占比」卡：按总 Token 显示前 4 个模型与「其它」
+- 参考成本可在 ¥ / $ 之间切换（固定汇率 1 USD = 7 CNY，宿主侧折算）
+- 可配置的每百万 Token 价格表（内置 DeepSeek 常见模型默认价）
+- 年度热力图；深/浅色自适应，只用 DSH 主题变量，无第三方图表库
 
-- 📊 **用量总览** — 总 Token、输入/输出 Token、调用次数、成本汇总卡片
-- 📅 **时间范围** — 今日 / 近 7 天 / 近 30 天 / 自定义范围
-- 🔍 **模型筛选** — 多选模型，按模型查看明细与占比
-- 📈 **每日趋势** — 按天堆叠柱状图（输入=蓝、输出=绿），hover 查看明细
-- 💰 **定价配置** — 为模型设置每百万 Token 价格（输入 / 输出 / 缓存命中 / 缓存创建），保存后立即生效
-- 🌗 **主题自适应** — 跟随 DSH 深/浅色主题，无第三方图表库
+## 安装
 
-## 效果图
+插件已发布到 npm：`dsh-plugin-usage`。
 
-![alt text](image.png)
+- **DSH Desktop**：设置 → 插件 → 添加插件，输入 `dsh-plugin-usage`
+- **Web / CLI profile**：`dsh plugin --profile <name> add dsh-plugin-usage`，重启生效
 
-![alt text](image-1.png)
+升级同理（桌面端在插件页点更新，CLI 用 `update`）。
 
-## 安装与构建 / Install & Build
+> `desktop` profile 由 Electron 应用独占，不能用 `dsh plugin --profile desktop` 操作。
 
-```sh
-npm install        # 首次（devDependencies：typescript）
-npm run build      # tsc 输出到 lib/，并生成 client 模块入口
-```
+## 配置
 
-### 通过官方命令安装（推荐）/ Install via the Official Command
+设置 → 插件 → `dsh-plugin-usage` 可改 `currency` 和 `prices`（每百万 Token 价格），写入 profile patch，重启保留。
+`currency` 是默认显示币种；仪表盘上参考成本卡里的 ¥ / $ 切换只影响当前界面（同浏览器记住选择）。
 
-插件已发布为 npm 包，使用 DSH 官方的插件管理命令安装：
+价格优先匹配 `provider/model`，其次裸 `model`；未配置的模型标为「未定价」，成本记 0。
 
-```sh
-dsh plugin --profile web add dsh-plugin-usage
-dsh web            # 重启后生效
-```
+## 数据来源与口径
 
-安装后 `dsh` 会检测到包的 `dsh.bundle` 声明，自动把 `dsh-plugin-usage` 加入
-profile 的 `dsh.profile.bundles` 层栈，无需手动编辑任何配置文件。卸载 / 更新：
+折叠 DSH 会话日志中已持久化的用量事件，不自己记日志：
 
-```sh
-dsh plugin --profile web remove dsh-plugin-usage   # 卸载
-dsh plugin --profile web update dsh-plugin-usage   # 更新
-```
+- 读取走官方接口：活跃会话 `snapshotEvents()`，历史会话 `sessionPersistence.open/read`，按 `revision` 跳过未变日志
+- 计费对齐官方 `tokenUsage` 投影：同一 `(turn, step)` 替换；`llm/retry-started` 后的重试累加；`assistant/attempt` 的 stream 用量也计入
+- fork 会话按 `inheritedEventCount` 跳过父会话前缀，不重复计费
+- 费用 = Σ(各 Token 分桶 × 对应单价) / 1e6
+- 价目表以**美元 / 百万 Token** 为基准（与 DeepSeek 官方价一致）；显示 `¥` 时按固定 7:1 折算，价目表本身不改写
 
-> 若 pnpm 因「发布时间过新」拒绝安装（`minimumReleaseAge` 校验），把
-> `dsh-plugin-usage@<version>` 加入 profile 的 `pnpm-workspace.yaml` 的
-> `minimumReleaseAgeExclude` 列表后重试（官方对新发布包同样采用此做法）。
+## 兼容性
 
-### 从源码加载 / Load from Source
+- DSH `>=0.2.0-rc.2 <0.3.0`（`engines.dsh`），Node ≥ 22
+- 更早的宿主保留 `Session.events` / `readFrom` 回退路径
 
-正式加载使用 patch 方式：把以下条目加入 `~/.dsh/profiles/web/cordis.patch.yml`（或使用 `--patch` 参数），路径替换为你本地的仓库路径：
-
-```yaml
-- insert:
-  - id: usage-host
-    name: '/path/to/dsh-plugin-usage/lib/host/index.js'
-  - id: usage-client
-    name: '/path/to/dsh-plugin-usage/lib/client/index.js'
-```
-
-然后启动：
+## 开发
 
 ```sh
-dsh web --patch /path/to/dsh-plugin-usage/cordis.yml
+npm install
+npm run build   # tsc → lib/，再生成 lib/client/index.js
+npm test        # node --test
 ```
 
-开发期也可以在会话中通过动态插件（cordis_define）加载：Client UI 由 Host 的 `usage/client-source` RPC 从 `src/client/index.js` 实时读取并在浏览器中评估（UI 代码只有一份，改完刷新即生效）。
-
-## 使用说明 / Usage
-
-1. 打开设置（左下角）→ 左侧导航「用量统计」。
-2. 顶部筛选：日期预设（今日 / 近 7 天 / 近 30 天 / 自定义）、模型多选。
-3. 汇总卡：总 Token、输入 Token、输出 Token、调用次数、成本（未定价调用会在卡片下提示）。
-4. 每日用量趋势：按天堆叠柱状图（输入=蓝、输出=绿），hover 查看明细。
-5. 按模型明细表：请求数 / 输入 / 输出 / 总 Token / 成本 / 占比。
-6. 「定价配置」区块：为模型设置每百万 Token 价格，保存后立即生效。
-
-## 数据来源与口径 / Data Source
-
-插件**不自己记录原始日志**，而是折叠 DSH 已持久化的会话日志：
-
-- DSH 的 agent loop 会把每次模型调用的用量以 `assistant/message` 会话事件（携带 `usage`：输入/输出/缓存命中/缓存创建 Token 与 `message.source.{provider,model}`）写入会话日志（`~/.dsh/sessions/`）。
-- 插件启动时**回填（backfill）全部历史会话**，之后每 2s 增量扫描活跃会话（内存），每 30s 增量扫描持久化会话（按 seq 水位）。
-- 覆盖范围：所有 agent loop 调用（含子代理）。compaction / session-title 等辅助调用不写入会话日志，不在统计范围内。
-- 去重：按会话内 `(turn, step)` 去重——同一 `(turn, step)` 的后续用量事件**替换**先前样本，而不是重复累计。
-- 费用 = `(输入×输入价 + 输出×输出价 + 缓存命中×缓存命中价 + 缓存创建×缓存创建价) / 1e6`，价格表可改。
-- 价格表持久化：官方 DSH settings 服务可用时，价格表经 `usage.prices` settings 命名空间持久化（重启后保留，并出现在官方 Plugins 配置页）；否则回退到进程内存（仅本次运行有效）。
-
-> 动态插件形态下数据保存在进程内存中，重启后自动从会话日志重新回填，无需落盘文件。
-
-## 源码结构 / Project Structure
+CI 跑 install → build → test → bundle id 契约 → tarball 内容检查；推 `v*` tag 会校验版本、构建测试并创建 GitHub Release。
 
 ```
-src/
-├── host/
-│   ├── index.js         Host 入口：接线 fold / scan / query / settings / aggregate / rpc / client-source，驱动定时扫描
-│   ├── settings.js      价格表 + 费用计算（内置 DeepSeek 常见模型默认价，可选 settings 命名空间持久化）
-│   ├── state.js         运行时状态：records / watermarks / backfill / dedup / index
-│   ├── aggregate.js     增量聚合索引：add / remove / recordsInRange，供查询高效取数
-│   ├── fold.js          会话事件 → usage 记录（含会话内 (turn, step) 去重替换）
-│   ├── scan.js          启动回填 + 活跃/持久化会话的增量扫描（每 tick / 每 30s，按 seq 水位）
-│   ├── query.js         聚合与查询：按天/按模型汇总、未定价检测、heatmap
-│   ├── rpc.js           RPC 注册：usage/query、usage/prices、usage/client-source（动态 harness 与静态 connection 桥）
-│   ├── client-source.js 读取 src/client/index.js 实时提供给浏览器（动态插件形态）
-│   └── time.js          时间分桶：day/hour/minute 粒度与 step 网格（纯函数）
-├── client/index.js   Client half：设置页「用量统计」仪表盘（筛选/汇总卡/柱状图/模型表/定价配置），样式内联
-└── client/styles.js  UI 样式源（构建脚本已合并进 index.js，可删除）
-scripts/
-└── build-client.js   构建时生成 lib/client/index.js 模块入口（同一份 UI 代码的正式加载形态）
-cordis.patch.yml      bundle patch：`dsh plugin add` 安装后由 `dsh.bundle` 声明自动激活
+src/host/    宿主：scan / fold / query / settings / aggregate / rpc
+src/client/  设置页「用量统计」仪表盘（纯 JS，样式内联）
+scripts/     构建客户端 bundle 入口
 ```
 
-## 开发与测试 / Development & Testing
-
-```sh
-npm install        # 首次安装依赖（devDependencies：typescript）
-npm run build      # tsc 输出到 lib/，再由 scripts/build-client.js 生成 client 模块入口
-npm test           # node --test tests/
-```
-
-`src/host/` 下的宿主逻辑（fold / scan / query / aggregate / time / settings 等）均为可直接
-import 的 ESM 模块，单元测试直接运行，无需启动 DSH harness。
-
-## 说明 / Notes
-
-- 插件名 `usage`；动态插件运行在会话级，卸载后统计重新回填即可恢复。
-- 价格表持久化策略见「数据来源与口径」（官方 settings 可用时走 `usage.prices` 命名空间，否则进程内存回退）。
+> 开发期也可用 `--patch` 从源码加载：`dsh web --patch cordis.yml`（路径见 `cordis.yml`）。
 
-## 开源协议 / License
+## License
 
 [MIT](./LICENSE)

package/icon.svg

@@ -0,0 +1,11 @@
+<svg width="36" height="36" viewBox="0 0 36 36" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Usage statistics">
+  <defs>
+    <linearGradient id="usage-bars" x1="8" y1="7.5" x2="28" y2="28" gradientUnits="userSpaceOnUse">
+      <stop stop-color="#67C7FE"/>
+      <stop offset="1" stop-color="#3F77D8"/>
+    </linearGradient>
+  </defs>
+  <rect x="8" y="20.5" width="5.5" height="7.5" rx="2.4" fill="url(#usage-bars)"/>
+  <rect x="15.25" y="14" width="5.5" height="14" rx="2.4" fill="url(#usage-bars)"/>
+  <rect x="22.5" y="7.5" width="5.5" height="20.5" rx="2.4" fill="url(#usage-bars)"/>
+</svg>