dsh-token-gauge 0.1.6 → 0.1.7

package/README.md

@@ -19,13 +19,19 @@ DeepSeek Harness（DSH）Web 侧边栏插件：以「机车风格仪表盘」实
 ## 安装
 
 > **兼容性**：本插件面向 **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-better-sidebar`**：本插件的 Tab 通过 `ctx.betterSidebar.registerTab` 注册到它的**右侧工作台**，所以它必须是 **profile 的直接依赖、且已挂进 `dsh.profile.bundles`**：
+>
+> `dsh plugin --profile web add dsh-better-sidebar`
+>
+> ⚠️ **陷阱（很常见）**：它若只是本插件的**传递依赖**，只会被装进 `node_modules` 而**不会**被挂成 bundle 层 —— 加载树里没有条目、`betterSidebar` 服务不会被 provide，表现就是本插件「已启用 / 已挂载」却没有任何侧边栏 Tab，**而且全程零报错**（0.1.7 起会在浏览器控制台打出明确指引）。同理请确认 `cordis.patch.yml` 与 `.dsh-market/state.json` 没有把它列为 `disabled`。
+>
+> 另注：Tab 注册后会出现在侧边栏 **「+ 新建 Tab」菜单**里（这是 better-sidebar 的设计：注册的是 tab *类型*，需你点开一次才会出现在标签栏），详见下方「排查」。
 
 ### 方式一：从市场安装（推荐）
 
-> **强烈建议钉版本安装**：`dsh plugin add` 底层是 pnpm，受你本地 `.npmrc` 指向的镜像（如 npmmirror）同步延迟影响，裸 `add dsh-token-gauge` 在 `^0.1.0` 范围内可能解析到尚未带 `dsh.bundle` 的旧版 `0.1.0`（装上去只会是普通依赖、不进 bundle 层、侧边栏不出现）。**显式钉 `0.1.1` 可彻底规避这一坑**：
+> **强烈建议钉版本安装**：`dsh plugin add` 底层是 pnpm，受你本地 `.npmrc` 指向的镜像（如 npmmirror）同步延迟影响，裸 `add dsh-token-gauge` 在 `^0.1.0` 范围内可能解析到尚未带 `dsh.bundle` 的旧版 `0.1.0`（装上去只会是普通依赖、不进 bundle 层、侧边栏不出现）。**显式钉 `0.1.7` 可彻底规避这一坑**：
 ```bash
-dsh plugin --profile web add dsh-token-gauge@0.1.1
+dsh plugin --profile web add dsh-token-gauge@0.1.7
 dsh web
 ```
 > 若想装最新版，可先 `dsh plugin --profile web update dsh-token-gauge` 升级，再确认 `node_modules/dsh-token-gauge/package.json` 的 `dsh.bundle.patch` 字段存在。
@@ -35,9 +41,9 @@ dsh web
 若此前已误装 `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 plugin --profile web add dsh-token-gauge@0.1.7   # 钉版本，避免又解析回 0.1.0
 ```
-装完后 `dsh.profile.bundles` 在 reconcile 时自动把 `token-gauge` 加为第 13 层，重启 `dsh web` 侧边栏即出现「Token 仪表盘」。
+装完后 `dsh.profile.bundles` 在 reconcile 时自动把 `token-gauge` 加为最后一层，重启 `dsh web` 后，在侧边栏 **「+ 新建 Tab」菜单**里选「Token 仪表盘」即可打开。
 
 ### 方式二：本地源码安装
 ```bash
@@ -54,7 +60,7 @@ node build.mjs
 dsh web --patch ./cordis.patch.yml
 ```
 
-安装后重启/硬刷新 DSH Web，侧边栏出现「Token 仪表盘」Tab。开始对话产生 Token 后，仪表盘即实时更新。
+安装后**完整重启** DSH Web（进程内 client 缓存只在重启时清空，硬刷新不够），然后在侧边栏点 **「+ 新建 Tab」→「Token 仪表盘」** 打开它。开始对话产生 Token 后，仪表盘即实时更新。
 
 ### 排查：侧边栏 Tab 不出现
 
@@ -62,6 +68,8 @@ DSH 把插件拆成 host（Node 端）与 client（浏览器端）两半，走
 
 - **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-better-sidebar` 是否真的挂载了**（「已启用/已挂载却无 Tab」的头号原因）：Tab 挂在它的右侧工作台上。检查 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` **和** `dependencies` 里是否**都**有 `dsh-better-sidebar` —— **只存在于 `node_modules` 不算**：作为传递依赖装进来的包不会被挂成 bundle 层，服务不会被 provide，于是本插件完全静默（0.1.7 起浏览器控制台会打出指引）。同时确认 `cordis.patch.yml` 与 `.dsh-market/state.json` 未把它标为 `disabled`。
+- **类型已注册，但标签栏里看不到**：`registerTab` 注册的是 tab **类型**，不会自动出现在标签栏 —— 需到侧边栏 **「+ 新建 Tab」菜单**点选「Token 仪表盘」打开一次。若菜单里也找不到，去看侧边栏**设置面板的 Tab 列表**：列表里有 = 注册成功只是没打开；列表里也没有 = 服务没拿到（回到上一条）。
 - 改动后务必**完整重启 `dsh web`**（进程内 client 缓存只在重启时清空），仅硬刷新不够。
 
 ## 数据来源与费用口径

package/lib/client.mjs

@@ -1016,6 +1016,11 @@ function apply(ctx) {
   }
   const stop = setTimeout(() => {
     if (timer !== void 0) clearInterval(timer);
+    if (!registered) {
+      console.error(
+        "[dsh-token-gauge] \u672A\u53D6\u5F97 dsh-better-sidebar \u670D\u52A1\uFF0C\u4FA7\u8FB9\u680F Tab \u672A\u6CE8\u518C\u3002\n  \u8BF7\u628A\u5B83\u88C5\u6210 profile \u7684\u300C\u76F4\u63A5\u4F9D\u8D56\u300D\u5E76\u6302\u8F7D\uFF1A\n    dsh plugin --profile web add dsh-better-sidebar\n  \u7136\u540E\u5B8C\u6574\u91CD\u542F dsh web\u3002\n  \u6CE8\u610F\uFF1A\u4EC5\u4F5C\u4E3A\u672C\u63D2\u4EF6\u7684\u4F20\u9012\u4F9D\u8D56\u5B58\u5728\u4E8E node_modules \u662F\u4E0D\u591F\u7684\u2014\u2014DSH \u4E0D\u4F1A\u628A\n  \u4F20\u9012\u4F9D\u8D56\u6302\u6210 bundle \u5C42\uFF0C\u90A3\u79CD\u60C5\u51B5\u4E0B\u672C\u63D2\u4EF6\u4F1A\u9759\u9ED8\u5730\u6CA1\u6709 Tab\u3002"
+      );
+    }
   }, 3e4);
   return () => {
     if (timer !== void 0) clearInterval(timer);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-token-gauge",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "DSH 机车风格 Token 用量/费用仪表盘侧边栏插件（稳定版 0.1.1-rc.x 兼容）",
   "type": "module",
   "main": "lib/index.mjs",
@@ -47,13 +47,6 @@
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
-    "client": {
-      "inject": [
-        "@deepseek-ai/dsh-client-ui-sidebar",
-        "dsh-better-sidebar"
-      ],
-      "platform": "web"
-    },
     "compatibility": {
       "dshReleases": {
         "0.1.1-rc.1": "compatible",
@@ -65,12 +58,21 @@
     "build": "node build.mjs",
     "prepack": "node build.mjs"
   },
-  "dependencies": {
-    "dsh-better-sidebar": "^0.15.2"
-  },
   "peerDependencies": {
     "@deepseek-ai/cordis": "*",
-    "@deepseek-ai/dsh-host-webserver": "*"
+    "@deepseek-ai/dsh-host-webserver": "*",
+    "dsh-better-sidebar": ">=0.15.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "dsh-better-sidebar": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "*",

package/src/client.ts

@@ -307,6 +307,21 @@ export function apply(ctx: any): (() => void) | void {
   }
   const stop = setTimeout(() => {
     if (timer !== void 0) clearInterval(timer as number)
+    if (!registered) {
+      // 服务始终不可达 ≈ dsh-better-sidebar 没被挂成 profile 层。
+      // 关键陷阱：它若只是本插件的「传递依赖」，只会落进 node_modules 而不会被
+      // 加入 dsh.profile.bundles —— 加载树里没有条目，服务根本不会被 provide，
+      // 本插件于是「已挂载但无 Tab」且全程零报错（真·静默失败）。故这里必须
+      // 打出可操作的指引，而不是默默放弃。
+      console.error(
+        '[dsh-token-gauge] 未取得 dsh-better-sidebar 服务，侧边栏 Tab 未注册。\n' +
+          '  请把它装成 profile 的「直接依赖」并挂载：\n' +
+          '    dsh plugin --profile web add dsh-better-sidebar\n' +
+          '  然后完整重启 dsh web。\n' +
+          '  注意：仅作为本插件的传递依赖存在于 node_modules 是不够的——DSH 不会把\n' +
+          '  传递依赖挂成 bundle 层，那种情况下本插件会静默地没有 Tab。',
+      )
+    }
   }, 30000)
 
   // 插件级 disposer