dsh-token-total 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 HaoyueQin (dsh-usage-statistics-panel, the upstream project this plugin derives from)
+Copyright (c) 2026 GaoHu1997 (dsh-token-total modifications and additions)
+
+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,110 @@
-# Temporary Holding Version
+# dsh-token-total
 
-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.
+DSH（DeepSeek Harness）Web 插件：**Token 用量统计看板** + **单会话用量（含子智能体）**。
+
+两件事，一个插件：
+
+1. **统计看板** — 侧边栏插件区下方的入口，点开是完整的用量看板（快捷筛选 / 六卡片 / 活跃热力图 / 缓存命中率趋势 + 分模型柱状图 / 按模型与按供应商 Top5）。
+2. **单会话统计** — 增强会话输入框下方的原生信息栏，把「Token 用量」从「只有主智能体」改成「主智能体 + 全部子智能体」，让一次会话的真实消耗有地方可看。
+
+所有图表都是手写 SVG，不依赖任何图表库；配色走 DSH 主题变量，自动适配明暗主题。
+
+## 功能
+
+### 统计看板
+
+入口在左侧边栏的插件区（与原生「插件」页并列的独立页面），点开即为看板，分上中下三部分。
+
+#### 上部
+
+- **快捷筛选**：今日 / 近 3 天 / 近 7 天 / 近 1 月 / 近 3 月 / 自定义（起止日期）。
+- **一行六个卡片**：总 Tokens、输入 Tokens、输出 Tokens、缓存 Tokens、缓存命中率、请求数量。
+  Token 数量用 **K / M / B** 紧凑单位显示主值，下方一行给出精确数字。
+- **活跃热力图**：GitHub 风格，格子颜色深浅表示当天 token 消耗的多少；图例「较少 → 较多」五档。
+- 右上角保留 **刷新**（只重取聚合结果），不再提供重建统计按钮。
+
+#### 中部
+
+- **缓存命中率趋势**：一条平滑折线（Catmull-Rom 转贝塞尔）。
+- **分模型柱状图**：堆叠柱表示实际 token 消耗，不同模型不同颜色；右轴为 0–100% 缓存命中率。
+- **不显示图例**：鼠标悬浮时 tooltip 逐项列出该时间桶内各模型的 token 与命中率。
+- **横轴粒度**：今日 / 近 3 天按**小时**分桶，更长的区间按**天**分桶。
+
+#### 下部
+
+- **按模型**：按模型选择器的**显示名称**（不是路由 id）跨供应商聚合，取前 5，展示模型名、总 Tokens、缓存命中率（跨多个供应商时附供应商列表）。排行与趋势使用同一归一化规则：忽略大小写，将空格、下划线和连字符统一为 `-`，例如 `gpt-6.1-sol`、`GPT 6.1 sol`、`gpt 6.1 sol` 合并为 `gpt-6.1-sol`；版本号和后缀仍区分，避免误合并不同模型。无法读取历史路由的模型元数据时，回退到历史引用中的模型名称；不改写原始记录，不需要重建统计。
+- **按供应商**：一个供应商下所有模型聚合，取前 5，展示供应商名、总 Tokens、缓存命中率。
+
+### 单会话统计
+
+会话输入框下方原生的「用时与速度 / Token 用量」两枚胶囊被接管并增强：
+
+- **Token 胶囊**显示的是**整棵会话树**（主智能体 + 全部子智能体）的合计，点开弹窗分为「主智能体 / 子智能体 / 会话合计」三行，并给出子智能体会话数。
+- 子智能体是独立持久化的会话，通过日志头的 `parentSession` 串成树；插件按需重放这些日志汇总（同一套 `(turn, step)` 去重规则，且跳过 fork 继承来的事件前缀，避免与父会话重复计数）。
+- **会话 Token 明细始终开启**：未命中缓存、缓存读 / 写、输出分别列出；底部胶囊的缓存命中率始终显示两位小数。
+- **流式吞吐速度始终开启**：输出过程中显示估算的解码速度；暂无有效样本或输出结束后，回到会话累计的精确值。
+- 不再提供底部增强功能的开关；旧版本保存的关闭设置不再影响显示。
+
+## 安装
+
+```sh
+dsh plugin --profile <profile> add dsh-token-total@latest
+```
+
+本地开发时直接指向目录：
+
+```sh
+dsh plugin --profile <profile> add "file:D:\work\dsh-token-total"
+```
+
+`package.json` 里的 `dsh.bundle.patch` 会让 CLI 在安装后把本插件追加进该 profile 的 `dsh.profile.bundles`，重启后自动挂载，无需手改 profile 配置。若该 profile 的 `cordis.patch.yml` 里还留着旧的手工挂载行，请先删掉，否则会重复挂载（两个宿主实例、两条重复路由）。
+
+> Electron 桌面端的 `desktop` profile 由应用独占管理，CLI 会拒绝写入（`profile "desktop" is managed exclusively by the Electron application`）。请用应用内的插件管理器安装，或另建一个 profile 验证。
+
+## 数据来源与统计口径
+
+- **事件来源**：`sessionPersistence` 的会话日志（`assistant/message` 的 `usage`）。插件订阅 `session/event` 实时增量累加，同时一次性回扫已有历史会话；`llm/retry-started` 会清空当前 `(turn, step)` 槽位，所以重试不会漏计也不会重复计。
+- **本地持久化**：聚合结果写入 storage-domain 的 `token_total_history` 域（`$DSH_HOME/storages/` 下），纯本地、无外部依赖。回扫游标按会话记录已消费的事件序号，重启后从断点继续。
+- **单会话统计**：不走聚合存储（那里没有会话维度），而是按需读该会话及其所有子孙会话的日志重放求和，结果短暂缓存，并在该会话树任一成员产生新事件时精确失效。
+- **缓存命中率** = 缓存命中 token ÷ 输入 token 总量（命中 + 未命中）。
+
+## HTTP 接口
+
+宿主侧注册一个前缀路由 `/token-total/api`，全部为 `POST` + JSON：
+
+| 路径 | 作用 |
+| --- | --- |
+| `/token-total/api/range` | 取某个时间范围的聚合（`{range, from?, to?}`） |
+| `/token-total/api/session` | 取某会话树的用量（`{sessionId}`，返回 `self` / `subagents` / `total` / `subagentSessions`） |
+| `/token-total/api/status` | 回扫进度 |
+| `/token-total/api/reset` | 清空统计并重新回扫 |
+
+请求经过与官方 `/api` 网关同源的信任栅栏（Host / Origin / `sec-fetch-site` 三重校验，防 DNS rebinding）。
+
+## 配置
+
+| 键 | 默认 | 说明 |
+| --- | --- | --- |
+| `source` | `session-log` | 统计来源 |
+| `backfillConcurrency` | `4` | 历史回扫的并发会话数 |
+
+## 兼容性
+
+- DSH `>= 0.1.7-rc.1`（`peerDependencies`）；实测运行于 `0.2.1-rc.2`，会话日志格式 v3 与 v4 均可读取（v3 走 alpha 的 `open/read` 接口，v4 走句柄分页读取）。
+- 浏览器半区只依赖 `@deepseek-ai/dsh-client-{locale,ui-slots,ui-primitives}` 与 React 18，不打入任何 Node 内置模块。
+
+## 开发
+
+```sh
+pnpm install
+pnpm run build        # tsc 声明 + 宿主/浏览器两个 bundle
+pnpm run typecheck    # 宿主半区
+pnpm run typecheck:client
+pnpm test             # 模型显示名称聚合、趋势、底部偏好回归测试
+```
+
+产物：`lib/index.js`（宿主，ESM）、`lib/client.js`（浏览器，CJS 包装进 `__ModuleLoader__.load`）、`lib/types/**/*.d.ts`。CSS Modules 在构建时被内联成 `<style data-plugin-css>` 注入，因此 Web 外壳不需要 CSS 管线。
+
+## 许可
+
+MIT。本项目的宿主与浏览器实现改编自 [dsh-usage-statistics-panel](https://github.com/HaoyueQin/dsh-usage-statistics-panel)（MIT, Copyright (c) 2026 HaoyueQin），在其基础上按本项目的需求重做了卡片、筛选、图表与列表，并新增了整棵会话树（含子智能体）的用量统计。原始版权声明保留在 [LICENSE](./LICENSE) 中。

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# dsh-token-total bundle patch
+#
+# This file is the `dsh.bundle.patch` layer of the published npm package: when
+# the plugin is installed through the official CLI --
+#   dsh plugin --profile <name> add dsh-token-total@<version>
+# -- the command reconciles `dsh.profile.bundles` against installed packages
+# and, seeing this declaration, appends `dsh-token-total` to the bundle stack.
+# The profile boot then merges THIS patch (a single `insert` of the plugin row)
+# exactly like a manual cordis.patch.yml mount line. No profile file edits are
+# needed -- one command installs and mounts.
+#
+# If the profile still carries an old manual mount line in its own
+# cordis.patch.yml, remove it before switching to the bundle channel to avoid
+# double-mounting (two host halves, two duplicate route registrations).
+#
+# Aggregate double-mount guard: aggregate bundles may already mount this
+# package under their own entry id. Two mounts register /token-total/api twice
+# and fail the whole plugin tree at boot ("duplicate prefix route"). The `!!js`
+# disabled expression backs THIS row off when another *enabled* entry already
+# mounts `dsh-token-total`; the aggregate instance then owns the panel.
+- insert:
+    - id: token-total
+      name: 'dsh-token-total'
+      disabled: !!js "[...ctx.loader.entries()].some((e) => e.options.name === 'dsh-token-total' && e.options.id !== 'token-total' && !e.disabled)"

package/icon.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="36" height="36" viewBox="0 0 36 36">
+  <!-- Card icon read by app-boot's readPluginMeta() from package.json "icon".
+       Composition follows the bar-chart brand marks collected in
+       glincker/thesvg (chunky rounded bars near the frame's full height, one
+       colour each, no axis line — cf. chartdotjs, mixpanel); no brand's
+       artwork is copied, only that composition. What this panel adds is its
+       own two signatures: the stacked token bars and the cache hit-rate trend
+       line drawn over them as a two-bend polyline, closed by an end dot. The
+       line is a polyline, not a smooth curve, on purpose: on this 36px canvas
+       the old three-segment bezier's wiggles were only a pixel or two tall, so
+       they read as meaningless bends; two bends keep the rising trend without
+       inventing detail (issue #12). The three hues are the hexes the project's
+       banner uses for its first three chart colours, so the icon matches the
+       donuts and lists it opens. Bars carry a per-hue vertical
+       gradient for depth; the ink is centred on its bounding box.
+       Transparent background on purpose: the Plugins page draws its own 48px
+       (card) / 40px (row) hairline frame, so a filled tile would double it.
+       Read in an <img> context: no foreignObject, scripts or external refs. -->
+  <defs>
+    <linearGradient id="usageStatsBlue" x1="18" y1="9" x2="18" y2="29" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#7CBBFF" />
+      <stop offset="1" stop-color="#2F7FE0" />
+    </linearGradient>
+    <linearGradient id="usageStatsGreen" x1="18" y1="9" x2="18" y2="29" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#9BC49F" />
+      <stop offset="1" stop-color="#46734C" />
+    </linearGradient>
+    <linearGradient id="usageStatsOrange" x1="18" y1="9" x2="18" y2="29" gradientUnits="userSpaceOnUse">
+      <stop offset="0" stop-color="#F0B57F" />
+      <stop offset="1" stop-color="#AC6835" />
+    </linearGradient>
+  </defs>
+  <path d="M4.3 17.6L12.5 14L21.3 10.8L29.5 9" fill="none" stroke="#4D6BFE" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round" />
+  <circle cx="29.5" cy="9" r="2.1" fill="#4D6BFE" />
+  <rect x="5.7" y="18.8" width="5.6" height="10.2" rx="2.8" fill="url(#usageStatsBlue)" />
+  <rect x="14.3" y="13" width="5.6" height="16" rx="2.8" fill="url(#usageStatsGreen)" />
+  <rect x="22.9" y="16" width="5.6" height="13" rx="2.8" fill="url(#usageStatsOrange)" />
+</svg>