dsh-token-gauge 0.1.1 → 0.1.3

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

@@ -22,10 +22,22 @@ DeepSeek Harness（DSH）Web 侧边栏插件：以「机车风格仪表盘」实
 > 侧边栏 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
@@ -44,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），自行累计，不依赖其他插件。
@@ -69,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

package/build.mjs

@@ -1,17 +1,29 @@
 // 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）。
+// Client: 侧边栏仪表盘 UI（浏览器环境）。
+//
+// 关键契约（稳定版 DSH 0.1.1-rc.x 的 client 加载器 @deepseek-ai/dsh-client-modules）：
+//   加载器把 client bundle 作为脚本注入，要求 bundle 在加载时主动调用
+//   window.__ModuleLoader__.load({ id: '<包名>', factory: (require) => <module.exports> })
+//   自注册（参考 dsh-better-sidebar 等所有正常插件都是此格式）。factory 内用
+//   运行时提供的 require 取依赖（如 react），从而与运行时 React 共享同一实例。
+//   早期误用 ESM + export 导致「loaded without registering」错误，现已修正为
+//   __ModuleLoader__.load 包裹的 CJS。
+//
+// 输出到 lib/index.mjs / lib/client.mjs（未跟踪的新文件名，避免覆盖受版本库
+// 只读覆盖层保护的旧 lib/index.js / lib/client.js）。
 import { build } from 'esbuild'
 import { copyFileSync } from 'node:fs'
 
+const PLUGIN_ID = 'dsh-token-gauge'
+
 const common = {
   bundle: true,
   sourcemap: false,
   logLevel: 'info',
 }
 
+// Host 半边：Node 环境，ESM 即可（webServer 路由）
 await build({
   ...common,
   entryPoints: ['src/host.ts'],
@@ -21,13 +33,22 @@ await build({
   target: 'node20',
 })
 
+// Client 半边：DSH client-modules 加载器契约 = window.__ModuleLoader__.load 包裹的 CJS
+// react 标为 external，由运行时 require("react") 提供（共享单实例，规避双 React 冲突）。
 await build({
   ...common,
   entryPoints: ['src/client.ts'],
   outfile: 'lib/client.mjs',
   platform: 'browser',
-  format: 'esm',
+  format: 'cjs',
   target: 'es2020',
+  external: ['react', 'react-dom', 'react/jsx-runtime'],
+  banner: {
+    js: `window.__ModuleLoader__.load({ id: "${PLUGIN_ID}", factory: function(require){ var module = { exports: {} }; var exports = module.exports;`,
+  },
+  footer: {
+    js: `; return module.exports; } });`,
+  },
 })
 
 // 同步市场元数据文件
@@ -37,4 +58,4 @@ try {
   /* 非必需 */
 }
 
-console.log('[dsh-token-gauge] build done -> lib/index.mjs (host), lib/client.mjs (client)')
+console.log('[dsh-token-gauge] build done -> lib/index.mjs (host), lib/client.mjs (client, __ModuleLoader__.load format)')