@samecorner/dsh-client-ui-token-usage

Readme

# dsh-token-usage

[![npm version](https://img.shields.io/npm/v/@samecorner/dsh-client-ui-token-usage)](https://www.npmjs.com/package/@samecorner/dsh-client-ui-token-usage)
[![License](https://img.shields.io/npm/l/@samecorner/dsh-client-ui-token-usage)](https://github.com/samecorner/dsh-token-usage/blob/main/LICENSE)

DSH（DeepSeek Harness）Web GUI 的 **Token 用量分析插件**：在会话顶部的 Tab 栏（Chat / Trajectory 之后）新增一个「Token 用量」页，展示整轮对话的 token 明细与上下文占用。发布在 npm：`@samecorner/dsh-client-ui-token-usage`。

灵感来自 pi-web-token-usage（pi-web 的同类插件），但完全按 DSH 的插件契约实现：

| 能力 | 数据来源 |
|---|---|
| 总 token / 计费 token / 输出 / 缓存读取 KPI（数字滚动动画） | host 端 tokenUsage projection（token-meter 已内置在 dsh web） |
| 上下文占用进度条（≥80% 警告变色）、提示缓存命中率、推理占比、平均/峰值单次调用 | host 端 contextPressure / tokenUsage projection + 窗口内 step 折叠统计 |
| 上下文构成（系统提示 / 工具 schema / 对话内容三段堆叠条，新请求组成估算） | host 端 contextBreakdown projection |
| 轮次 / 步数 | host 端 sessionStats projection |
| 构成环形图 + 明细表（输入/缓存读/缓存写/输出/推理，占比微条） | 上述 tokenUsage |
| 逐轮堆叠柱状图（hover tooltip）+ 逐轮明细（含耗时）+ 累计计费曲线 | 客户端从会话事件窗口折叠 assistant/message 的 usage（ConversationNode + View target） |
| 按模型拆分（token/调用数/缓存命中率）+ 复制 Markdown 报告 + 加载更早记录 | 模型路由聚合 / 面板按钮 |

## 安装

### 方式 A：npm 一键安装（推荐，免编译、免改配置）

```bash
# 在哪里执行都可以，dsh 会自动到对应的 profile 目录里跑 pnpm
# （首次使用会自动初始化 profile）
dsh plugin --profile web add @samecorner/dsh-client-ui-token-usage

# 重启 dsh web，顶部即出现「Token 用量」Tab
```

该包声明了 `dsh.bundle.patch`（见 `bundle.patch.yml`），`dsh plugin add` 后**自动挂载**：包会被加进 profile 的 bundle 层，无需手动改 `cordis.patch.yml`。若之前在 `cordis.patch.yml` 里手动 insert 过同 id，请删除该条目，避免重复挂载报错。

更新：`dsh plugin --profile web update @samecorner/dsh-client-ui-token-usage`
卸载：`dsh plugin --profile web remove @samecorner/dsh-client-ui-token-usage`（依赖与层列表自动一并摘除）

### 方式 B：源码构建 + 本地开发安装

```bash
# 1. 构建（需要 node >= 18；依赖只来自 npm 公开包，不需要 DSH 源码）
npm install
npm run build        # 产出 lib/client.js + lib/index.js

# 2. 以本地目录安装进 profile（同样走 dsh plugin，自动挂载）
dsh plugin --profile web add /path/to/dsh-token-usage
# 目录依赖是链接语义：改代码 npm run build 后重启 web 即生效，无需拷贝/同步

# 3. 重启 dsh web
```

## 开发

```bash
npm run typecheck    # tsc --noEmit（类型来自 npm 上的 @deepseek-ai/*@0.1.0-rc.6）
npm run build        # esbuild：浏览器 bundle + node half
npm run test         # 冒烟：loader 形态 + SSR 渲染（不启动 web）
node scripts/smoke-loader.mjs       # 模拟 DSH 模块表验证产物形态
node scripts/render-test.mjs && node scripts/.tmp/render-test.bundle.mjs  # SSR 渲染冒烟（抓运行时错误）
```

修改源码后重新 build，重启 dsh web 生效（或使用 dsh 的 HMR 机制热更）。

> **写插件前先读**：[`docs/client-plugin-dev-guide.zh.md`](docs/client-plugin-dev-guide.zh.md) —— Web 客户端插件开发手册（官方 Demo 目录、完整流程、踩坑清单含 `module is not defined` 事故的修复对照）。

### 包结构

```
dsh-token-usage/
├── src/
│   ├── index.ts                    # host 端空入口
│   └── client/
│       ├── index.ts                # apply：注册 locale / 节点定义 / 视图 / Tab
│       ├── token-usage-contract.ts # 视图数据类型 + ConversationViewSnapshotMap 合并
│       ├── token-usage-step-definition.ts  # assistant/message → usage 节点（last-wins）
│       ├── token-usage-snapshot-builder.ts # 折叠成逐轮明细 + 总计
│       ├── TokenUsageView.tsx      # 面板组件（KPI/环形图/柱状图/曲线）
│       ├── styles.ts               # 自包含样式（--dsw-alias-* 主题变量驱动）
│       └── locales.ts              # 中/英文案
├── build.mjs                       # esbuild 打包（匹配 DSH client bundle 格式）
├── bundle.patch.yml                # dsh plugin add 自动挂载层（dsh.bundle.patch）
└── package.json
```

## 发布与分享

- **仓库**：https://github.com/samecorner/dsh-token-usage（已关联官方 `dsh-plugin` topic，见
  https://github.com/topics/dsh-plugin）
- **npm**：`@samecorner/dsh-client-ui-token-usage`。发版流程：

  ```bash
  npm run test && npm version patch && npm publish
  # 使用方：dsh plugin --profile web update @samecorner/dsh-client-ui-token-usage
  ```

- 依赖只有 devDependencies（类型 + 构建工具），运行时零依赖（只 external 平台模块）。
- 若 fork 改名需同步：package.json name + build.mjs 里的 ID + styles.ts 的 data-plugin 归属标记 + bundle.patch.yml 的 name。

## 工作原理（DSH 插件机制速记）

- 一切皆 Cordis 插件；浏览器端插件 = 一个 conversation.view slot 条目（id/order/label/组件）。
- host 端 token-meter / session-stats 已内置并挂载，把 tokenUsage / contextPressure /
  contextBreakdown / sessionStats projection 推到客户端 useProjection。
- 逐轮数据：注册 conversationEvents 节点定义（匹配 assistant/message 的 usage）+ conversationViews
  视图 target，客户端窗口分页自动维护快照。
- 打包格式：lib/client.js 必须带 window.__ModuleLoader__.load({ id, factory }) 包装；
  react / cordis / ui-slots 等平台模块保持 external。

## 已知限制

- 逐轮明细只覆盖「窗口内已装配且带 usage 的 assistant/message」；被取消的步、以及 usage 缺失的调用
  不出现在逐轮表（整轮合计仍以 host projection 为准，两者口径可能略有差异）。
- 推理 token 计入输出（与 token-meter 口径一致）；无成本估算（DSH 不记录单价，避免猜测计费）。
- 上下文占用显示的是 token-meter 的近似投影（projectedTokens / contextWindow），非计费口径。

## License

MIT