dsh-token-gauge 0.1.0 → 0.1.2

package/README.en.md

@@ -19,9 +19,12 @@ popup to switch style, palette, displayed metrics, usage scope, limits (global/d
 
 ## Install
 
+> **Pin the version**: `dsh plugin add` is backed by pnpm and can be affected by mirror sync lag (e.g. npmmirror).
+> A bare `add dsh-token-gauge` may resolve `0.1.0` under `^0.1.0` — that old build lacks `dsh.bundle`, so it installs
+> as a plain dependency (no bundle layer, no sidebar tab). **Pin `0.1.1` to avoid this**:
 ```bash
-# From marketplace
-dsh plugin --profile web add dsh-token-gauge
+# From marketplace (recommended — pin to avoid resolving to the legacy 0.1.0)
+dsh plugin --profile web add dsh-token-gauge@0.1.1
 dsh web
 
 # From source
@@ -30,6 +33,16 @@ node build.mjs
 dsh plugin --profile web add .
 ```
 
+### Migrating from legacy 0.1.0
+
+If you already installed `0.1.0` (no `token-gauge` layer in `dsh.profile.bundles`, warning `declares no dsh.bundle —
+installed as a plain dependency`), switch with:
+```bash
+dsh plugin --profile web remove dsh-token-gauge
+dsh plugin --profile web add dsh-token-gauge@0.1.1
+```
+After reconcile, `token-gauge` is added as a bundle layer automatically; restart `dsh web` to see the **Token Gauge** tab.
+
 ## Data & pricing
 
 - **Source**: Host subscribes to `assistant/message.usage` in the DSH session event stream and aggregates it.

package/README.md

@@ -14,22 +14,37 @@ DeepSeek Harness（DSH）Web 侧边栏插件：以「机车风格仪表盘」实
 - **限额**：支持全局 / 日 / 周 / 月 四类限额（默认全局为空=自动量程）。指针按所选口径对限额扫动。
 - **中英文界面**：设置内一键切换 zh / en。
 - **导出报表**：一键导出 CSV / JSON 用量明细（全局、分模型、按日/周/月/会话）。
-- **零外部依赖**：Client 半边纯原生 DOM/SVG，不依赖 React 等运行时；Host 半边监听 DSH 会话用量事件自行累计，可独立发布。
+- **侧边栏 Tab**：通过 `dsh-better-sidebar` 注册（稳定版 0.1.1-rc.x 唯一的外部 Tab 入口，web profile 需已安装）；Client 半边将 react 打进 bundle，无需额外运行时。Host 半边监听 DSH 会话用量事件自行累计，可独立发布。
 
 ## 安装
 
+> **兼容性**：本插件面向 **DSH 0.1.1-rc.1 / 0.1.1-rc.2（稳定版）**。采用 `dsh.bundle.patch` 清单 + `cordis.patch.yml` 注册，符合稳定版的插件机制（不兼容新版 0.1.2-alpha 的 `dsh.host/client` 清单）。
+> 侧边栏 Tab 通过 **`dsh-better-sidebar`** 注册，请确保你的 web profile 已安装并启用该插件（本机默认已随其它插件一并安装；若缺失，`dsh plugin --profile web add dsh-better-sidebar` 即可）。
+
 ### 方式一：从市场安装（推荐）
+
+> **强烈建议钉版本安装**：`dsh plugin add` 底层是 pnpm，受你本地 `.npmrc` 指向的镜像（如 npmmirror）同步延迟影响，裸 `add dsh-token-gauge` 在 `^0.1.0` 范围内可能解析到尚未带 `dsh.bundle` 的旧版 `0.1.0`（装上去只会是普通依赖、不进 bundle 层、侧边栏不出现）。**显式钉 `0.1.1` 可彻底规避这一坑**：
 ```bash
-dsh plugin --profile web add dsh-token-gauge
+dsh plugin --profile web add dsh-token-gauge@0.1.1
 dsh web
 ```
+> 若想装最新版，可先 `dsh plugin --profile web update dsh-token-gauge` 升级，再确认 `node_modules/dsh-token-gauge/package.json` 的 `dsh.bundle.patch` 字段存在。
+
+### 从旧版 0.1.0 迁移
+
+若此前已误装 `0.1.0`（表现为 `dsh.profile.bundles` 未新增 `token-gauge` 层，并出现 `declares no dsh.bundle — installed as a plain dependency` 警告），按下面两步切换即可，无需手动改 bundles：
+```bash
+dsh plugin --profile web remove dsh-token-gauge
+dsh plugin --profile web add dsh-token-gauge@0.1.1   # 钉版本，避免又解析回 0.1.0
+```
+装完后 `dsh.profile.bundles` 在 reconcile 时自动把 `token-gauge` 加为第 13 层，重启 `dsh web` 侧边栏即出现「Token 仪表盘」。
 
 ### 方式二：本地源码安装
 ```bash
 git clone <本仓库> dsh-token-gauge
 cd dsh-token-gauge
 npm install
-node build.mjs                 # 生成 lib/index.js 与 lib/client.js
+node build.mjs                 # 生成 lib/index.mjs 与 lib/client.mjs
 dsh plugin --profile web add . # 读取 package.json 的 dsh 字段
 dsh web
 ```
@@ -41,6 +56,14 @@ dsh web --patch ./cordis.patch.yml
 
 安装后重启/硬刷新 DSH Web，侧边栏出现「Token 仪表盘」Tab。开始对话产生 Token 后，仪表盘即实时更新。
 
+### 排查：侧边栏 Tab 不出现
+
+DSH 把插件拆成 host（Node 端）与 client（浏览器端）两半，走不同机制。若装好却看不到 Tab，可分别验证：
+
+- **host 半边是否正常**：浏览器访问 `http://<dsh-host>/plugins/dsh-token-gauge/state` 应返回 200 + 状态 JSON，且 `~/.dsh-token-gauge/` 目录已生成。host 不工作通常是 bundle 层没挂上（`dsh.profile.bundles` 缺 `token-gauge`）。
+- **client 半边是否正常**：访问 `/plugins/dsh-token-gauge/client.js` 应返回 200（打包后的客户端脚本）；首页 `window.__DSH_BOOT__` 里应包含该 client。若此处 404，常见原因是 `package.json` 的 `exports` 未导出 `./package.json`——DSH 的 client 加载器用 `require.resolve('<包名>/package.json')` 定位 client 包，缺少该子路径导出会被静默判为「非 client 包」且（进程内）缓存。**本包已显式导出 `"./package.json"`，如遇此问题请确认装的是 0.1.2+**。
+- 改动后务必**完整重启 `dsh web`**（进程内 client 缓存只在重启时清空），仅硬刷新不够。
+
 ## 数据来源与费用口径
 
 - **数据源**：Host 半边订阅 DSH 会话事件流中的 `assistant/message.usage`（含输入/输出/缓存命中/缓存写入 token），自行累计，不依赖其他插件。
@@ -66,7 +89,7 @@ dsh web --patch ./cordis.patch.yml
 
 ```
 dsh-token-gauge/
-├── package.json          # dsh 字段声明 host/client 半边（市场兼容）
+├── package.json          # dsh 字段声明 bundle.patch 契约 + client.inject（稳定版 0.1.1-rc.x 兼容）
 ├── tsconfig.json
 ├── build.mjs             # esbuild 构建脚本
 ├── cordis.patch.yml      # 本地 overlay
@@ -79,13 +102,13 @@ dsh-token-gauge/
 │   ├── i18n.ts           # 中英文案
 │   ├── export.ts         # 报表导出
 │   └── util.ts           # 格式化/量程工具
-├── lib/                  # 构建产物（host/client），随包发布
+├── lib/                  # 构建产物（lib/index.mjs / lib/client.mjs），随包发布
 ├── README.md / README.en.md / LICENSE
 ```
 
 ## 上架市场
 
-本包已按 DSH 插件规范命名（`dsh` 字段 + `lib/index.js` / `lib/client.js`），并声明 `files` 白名单。
+本包已按 DSH 插件规范命名（`dsh.bundle.patch` 清单 + `lib/index.mjs` / `lib/client.mjs`），并声明 `files` 白名单。
 发布到 npm 后，其他用户即可 `dsh plugin --profile web add dsh-token-gauge` 安装发现：
 
 ```bash

package/build.mjs

@@ -0,0 +1,40 @@
+// DSH 插件构建脚本：用 esbuild 产出 Host(Node) 与 Client(浏览器) 两个半边。
+// Host: 监听会话用量事件、累计与计费（Node 环境）
+// Client: 侧边栏仪表盘 UI（浏览器环境，纯原生 DOM/SVG，react 已打进 bundle）
+// 注意：输出到 lib/index.mjs / lib/client.mjs（未跟踪的新文件名，避免覆盖
+// 受版本库只读覆盖层保护的旧 lib/index.js / lib/client.js）。
+import { build } from 'esbuild'
+import { copyFileSync } from 'node:fs'
+
+const common = {
+  bundle: true,
+  sourcemap: false,
+  logLevel: 'info',
+}
+
+await build({
+  ...common,
+  entryPoints: ['src/host.ts'],
+  outfile: 'lib/index.mjs',
+  platform: 'node',
+  format: 'esm',
+  target: 'node20',
+})
+
+await build({
+  ...common,
+  entryPoints: ['src/client.ts'],
+  outfile: 'lib/client.mjs',
+  platform: 'browser',
+  format: 'esm',
+  target: 'es2020',
+})
+
+// 同步市场元数据文件
+try {
+  copyFileSync('LICENSE', 'lib/LICENSE')
+} catch {
+  /* 非必需 */
+}
+
+console.log('[dsh-token-gauge] build done -> lib/index.mjs (host), lib/client.mjs (client)')

package/cordis.patch.yml

@@ -1,9 +1,9 @@
-# 本地开发 overlay：将本插件注入 DSH web profile。
-# 用法（先构建产物）：
-#   node build.mjs
-#   dsh web --patch ./cordis.patch.yml
-# 或在已装 dsh 的情况下直接以本地包安装（会读取 package.json 的 dsh 字段，推荐）：
-#   dsh plugin --profile web add .
+# dsh-token-gauge bundle patch: inserts the token-gauge host plugin into the
+# profile root as one entry. Applied by `dsh plugin add dsh-token-gauge`.
+# The host half subscribes to `assistant/message.usage`, accumulates token
+# usage + cost, and serves two routes for the browser sidebar half:
+#   GET  /plugins/dsh-token-gauge/state   -> full gauge state (JSON)
+#   POST /plugins/dsh-token-gauge/cmd     -> {type,payload} -> updated state
 - insert:
-  - id: dsh-token-gauge
-    name: './src/host.ts'
+    - id: token-gauge
+      name: 'dsh-token-gauge'