dsh-token-gauge 0.1.6 → 0.1.8

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

@@ -32,6 +32,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var client_exports = {};
 __export(client_exports, {
   apply: () => apply,
+  inject: () => inject,
   name: () => name
 });
 module.exports = __toCommonJS(client_exports);
@@ -943,85 +944,56 @@ var gaugeRef = (el) => {
     mountGauge(el);
   }
 };
-function GaugeTab() {
-  return import_react.default.createElement("div", { ref: gaugeRef, className: "tg-tab-root" });
-}
-var GaugeIcon = (size) => {
-  const s = typeof size === "number" && size > 0 ? size : 16;
-  const svgProps = {
-    width: s,
-    height: s,
-    viewBox: "0 0 16 16",
-    fill: "none",
-    xmlns: "http://www.w3.org/2000/svg",
-    "aria-hidden": "true"
-  };
-  const arc = import_react.default.createElement("path", {
-    d: "M2.6 11.6a5.6 5.6 0 1 1 10.8 0",
-    stroke: "currentColor",
-    strokeWidth: 1.5,
-    strokeLinecap: "round"
-  });
-  const needle = import_react.default.createElement("path", {
-    d: "M8 11.6 10.4 7.2",
-    stroke: "currentColor",
-    strokeWidth: 1.5,
-    strokeLinecap: "round"
+function GaugePanel() {
+  return import_react.default.createElement("div", {
+    ref: gaugeRef,
+    className: "tg-panel-root",
+    style: {
+      position: "fixed",
+      right: "0",
+      bottom: "0",
+      width: "420px",
+      height: "33vh",
+      zIndex: 50,
+      pointerEvents: "auto",
+      boxSizing: "border-box",
+      overflow: "hidden",
+      borderTop: "1px solid var(--dsw-alias-hairline)",
+      borderLeft: "1px solid var(--dsw-alias-hairline)",
+      background: "var(--dsw-alias-bg-base)",
+      color: "var(--dsw-alias-label-primary)",
+      boxShadow: "0 0 24px rgba(0,0,0,0.28)"
+    }
   });
-  return import_react.default.createElement("svg", svgProps, arc, needle);
-};
-var TAB_ORDER = 90;
+}
 var name = PLUGIN_ID;
+var inject = ["slots"];
 function apply(ctx) {
-  let registered = false;
-  let unregister = void 0;
-  const register = (sidebar) => {
-    if (registered || !sidebar || typeof sidebar.registerTab !== "function") return;
-    registered = true;
-    try {
-      unregister = sidebar.registerTab({
+  let disposeRegistration = void 0;
+  const doRegister = () => {
+    disposeRegistration = ctx.slots.register(
+      {
+        name: "shell.overlay",
         id: PLUGIN_ID,
-        title: "Token \u4EEA\u8868\u76D8",
-        single: true,
-        order: TAB_ORDER,
-        icon: GaugeIcon,
-        component: GaugeTab
-      });
-    } catch (e) {
-      registered = false;
-    }
+        order: 100,
+        label: "Token \u4EEA\u8868\u76D8"
+      },
+      () => import_react.default.createElement(GaugePanel)
+    );
   };
-  let disposeInject = void 0;
+  let stop = void 0;
   try {
-    disposeInject = ctx.inject(["betterSidebar"], (sidebarCtx) => {
-      register(sidebarCtx && sidebarCtx.betterSidebar);
-    });
-  } catch (e) {
-  }
-  const tryRead = () => {
-    if (registered) return;
-    try {
-      const s = typeof ctx.get === "function" ? ctx.get("betterSidebar") : ctx.betterSidebar;
-      register(s);
-    } catch (e) {
+    if (typeof ctx.slots.inject === "function") {
+      stop = ctx.slots.inject("shell.overlay", doRegister);
+    } else {
+      doRegister();
     }
-  };
-  tryRead();
-  let timer = void 0;
-  if (!registered) {
-    timer = setInterval(() => {
-      tryRead();
-      if (registered && timer !== void 0) clearInterval(timer);
-    }, 500);
+  } catch (e) {
+    console.error("[dsh-token-gauge] \u6CE8\u518C shell.overlay \u5931\u8D25", e);
   }
-  const stop = setTimeout(() => {
-    if (timer !== void 0) clearInterval(timer);
-  }, 3e4);
   return () => {
-    if (timer !== void 0) clearInterval(timer);
-    clearTimeout(stop);
-    if (typeof unregister === "function") unregister();
-    if (typeof disposeInject === "function") disposeInject();
+    if (typeof disposeRegistration === "function") disposeRegistration();
+    if (typeof stop === "function") stop();
   };
 }
 ; return module.exports; } });

package/package.json

@@ -1,82 +1,80 @@
-{
-  "name": "dsh-token-gauge",
-  "version": "0.1.6",
-  "description": "DSH 机车风格 Token 用量/费用仪表盘侧边栏插件（稳定版 0.1.1-rc.x 兼容）",
-  "type": "module",
-  "main": "lib/index.mjs",
-  "module": "lib/index.mjs",
-  "exports": {
-    ".": "./lib/index.mjs",
-    "./client": "./lib/client.mjs",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.mjs",
-    "lib/client.mjs",
-    "lib/LICENSE",
-    "src",
-    "preview",
-    "README.md",
-    "README.en.md",
-    "LICENSE",
-    "cordis.patch.yml",
-    "build.mjs",
-    "tsconfig.json"
-  ],
-  "author": "WorkBuddy User",
-  "license": "MIT",
-  "engines": {
-    "node": ">=20"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/liumiaozhi/dsh-token-gauge.git"
-  },
-  "homepage": "https://github.com/liumiaozhi/dsh-token-gauge#readme",
-  "bugs": {
-    "url": "https://github.com/liumiaozhi/dsh-token-gauge/issues"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  },
-  "dsh": {
-    "engines": {
-      "dsh": ">=0.1.1-rc.1"
-    },
-    "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",
-        "0.1.1-rc.2": "compatible"
-      }
-    }
-  },
-  "scripts": {
-    "build": "node build.mjs",
-    "prepack": "node build.mjs"
-  },
-  "dependencies": {
-    "dsh-better-sidebar": "^0.15.2"
-  },
-  "peerDependencies": {
-    "@deepseek-ai/cordis": "*",
-    "@deepseek-ai/dsh-host-webserver": "*"
-  },
-  "devDependencies": {
-    "@deepseek-ai/cordis": "*",
-    "@types/react": "^18.2.0",
-    "esbuild": "^0.21.5",
-    "react": "^18.2.0",
-    "typescript": "^5.4.0"
-  }
-}
+{
+  "name": "dsh-token-gauge",
+  "version": "0.1.8",
+  "description": "DSH 机车风格 Token 用量/费用仪表盘侧边栏插件（稳定版 0.1.1-rc.x 兼容）",
+  "type": "module",
+  "main": "lib/index.mjs",
+  "module": "lib/index.mjs",
+  "exports": {
+    ".": "./lib/index.mjs",
+    "./client": "./lib/client.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.mjs",
+    "lib/client.mjs",
+    "lib/LICENSE",
+    "src",
+    "preview",
+    "README.md",
+    "README.en.md",
+    "LICENSE",
+    "cordis.patch.yml",
+    "build.mjs",
+    "tsconfig.json"
+  ],
+  "author": "WorkBuddy User",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liumiaozhi/dsh-token-gauge.git"
+  },
+  "homepage": "https://github.com/liumiaozhi/dsh-token-gauge#readme",
+  "bugs": {
+    "url": "https://github.com/liumiaozhi/dsh-token-gauge/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dsh": {
+    "engines": {
+      "dsh": ">=0.1.1-rc.1"
+    },
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.1.1-rc.1": "compatible",
+        "0.1.1-rc.2": "compatible"
+      }
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "node build.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-host-webserver": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@types/react": "^18.2.0",
+    "esbuild": "^0.21.5",
+    "react": "^18.2.0",
+    "typescript": "^5.4.0"
+  }
+}

package/src/client.ts

@@ -1,319 +1,302 @@
-// ============================================================================
-// DSH Client 半边：注册侧边栏 Tab，渲染机车风格仪表盘 + 设置弹窗
-// 运行环境：浏览器（web 平台，与 webServer 同域）。纯原生 DOM/SVG 仪表盘，
-// 通过同域 HTTP 与 Host 半边通信：
-//   GET  /plugins/dsh-token-gauge/state -> 完整 State(JSON)
-//   POST /plugins/dsh-token-gauge/cmd   -> {type,payload} -> 更新后 State
-// 侧边栏 Tab 通过 dsh-better-sidebar 的 ctx.betterSidebar.registerTab 注册
-// （稳定版 0.1.1-rc.x 唯一的外部 Tab 入口）。
-// 为避免与运行时 React 产生双实例 hook 冲突，本组件不调用任何 hook，
-// 仅在 ref 回调里挂载一次原生 DOM 仪表盘，并自行轮询刷新。
-// ============================================================================
-import React from 'react'
-import { getStyle, applyPalette, buildCss } from './styles'
-import { createGauge } from './gauge'
-import { t } from './i18n'
-import { downloadReport } from './export'
-import { createSettingsModal } from './settings'
-
-const PLUGIN_ID = 'dsh-token-gauge'
-const ROUTE_STATE = '/plugins/dsh-token-gauge/state'
-const ROUTE_CMD = '/plugins/dsh-token-gauge/cmd'
-
-function totalOf(b: any): number {
-  return (b?.input || 0) + (b?.cacheRead || 0) + (b?.cacheWrite || 0) + (b?.output || 0)
-}
-function todayKey(d = new Date()): string {
-  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
-}
-function monthKey(d = new Date()): string {
-  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`
-}
-function weekKey(d = new Date()): string {
-  const date = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()))
-  const dayNum = (date.getUTCDay() + 6) % 7
-  date.setUTCDate(date.getUTCDate() - dayNum + 3)
-  const firstThursday = new Date(Date.UTC(date.getUTCFullYear(), 0, 4))
-  const week =
-    1 +
-    Math.round(
-      ((date.getTime() - firstThursday.getTime()) / 86400000 - 3 + ((firstThursday.getUTCDay() + 6) % 7)) / 7,
-    )
-  return `${d.getFullYear()}-W${String(week).padStart(2, '0')}`
-}
-
-function fallbackState(): any {
-  return {
-    global: {},
-    daily: {},
-    weekly: {},
-    monthly: {},
-    sessions: {},
-    models: {},
-    activeSession: '',
-    settings: {
-      style: 'ev',
-      palette: 'neon',
-      lang: 'zh',
-      metric: 'global',
-      display: { usage: true, cost: true, io: true, cacheMiss: true },
-      limits: { global: null, daily: null, weekly: null, monthly: null },
-      pricing: {},
-    },
-  }
-}
-
-// 计算当前指标的量程/费用
-function computeMetric(s: any): { value: number; limit: number | null; cost: number } {
-  const metric = s.settings.metric
-  let entry: any = s.global
-  let limit: number | null = s.settings.limits.global
-  if (metric === 'session') {
-    entry = s.sessions[s.activeSession] || {}
-    limit = s.settings.limits.daily
-  } else if (metric === 'today' || metric === 'daily') {
-    entry = s.daily[todayKey()] || {}
-    limit = s.settings.limits.daily
-  } else if (metric === 'weekly') {
-    entry = s.weekly[weekKey()] || {}
-    limit = s.settings.limits.weekly
-  } else if (metric === 'monthly') {
-    entry = s.monthly[monthKey()] || {}
-    limit = s.settings.limits.monthly
-  }
-  return { value: totalOf(entry), limit, cost: entry.cost || 0 }
-}
-
-// 把原生 DOM 仪表盘挂载进容器，并启动轮询
-function mountGauge(container: HTMLElement): void {
-  // 注入一次全局样式
-  if (!document.getElementById('tg-gauge-style')) {
-    const st = document.createElement('style')
-    st.id = 'tg-gauge-style'
-    st.textContent = buildCss()
-    document.head.appendChild(st)
-  }
-
-  let state: any = null
-  const tr = (k: string) => t((state?.settings?.lang as 'zh' | 'en') || 'zh', k)
-
-  const root = container
-  root.className = 'tg-root tg-style-ev'
-
-  // 头部
-  const head = document.createElement('div')
-  head.className = 'tg-head'
-  const titleEl = document.createElement('div')
-  titleEl.className = 'tg-title'
-  titleEl.textContent = 'Token 仪表盘'
-  const gear = document.createElement('div')
-  gear.className = 'tg-gear'
-  gear.textContent = '⚙'
-  gear.title = '设置'
-  head.append(titleEl, gear)
-  root.appendChild(head)
-
-  // 空数据提示
-  const empty = document.createElement('div')
-  empty.className = 'tg-empty'
-  empty.style.display = 'none'
-  root.appendChild(empty)
-
-  // 仪表盘
-  const gauge = createGauge()
-  root.appendChild(gauge.el)
-
-  // 设置弹窗
-  const modal = createSettingsModal({
-    getLang: () => (state?.settings?.lang as 'zh' | 'en') || 'zh',
-    onSettings: (patch) => sendCmd('setSettings', patch),
-    onExport: (format) => {
-      if (state) downloadReport(state, (state.settings.lang as 'zh' | 'en') || 'zh', format)
-    },
-    onClear: () => sendCmd('clearUsage', undefined),
-    onReset: () => sendCmd('resetSettings', undefined),
-  })
-  root.appendChild(modal.el)
-
-  gear.addEventListener('click', () => modal.open(state || fallbackState()))
-
-  const applyState = (s: any): void => {
-    state = s
-    root.className = 'tg-root ' + getStyle(s.settings.style).className
-    applyPalette(root, s.settings.palette)
-    titleEl.textContent = tr('title')
-    const m = computeMetric(s)
-    gauge.update({ value: m.value, limit: m.limit, cost: m.cost, state: s, display: s.settings.display, t: tr, lang: s.settings.lang })
-    const hasData = totalOf(s.global) > 0
-    empty.style.display = hasData ? 'none' : ''
-    empty.textContent = tr('noData')
-    modal.sync(s)
-  }
-
-  // 拉取最新状态
-  async function poll(): Promise<void> {
-    try {
-      const r = await fetch(ROUTE_STATE, { headers: { Accept: 'application/json' } })
-      if (r.ok) {
-        const s = await r.json()
-        applyState(s)
-      }
-    } catch (e) {
-      // 网络抖动忽略，下一轮重试
-    }
-  }
-
-  // 发送指令并刷新
-  async function sendCmd(type: string, payload: any): Promise<void> {
-    try {
-      await fetch(ROUTE_CMD, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ type, payload }),
-      })
-    } catch (e) {
-      console.warn(`[${PLUGIN_ID}] cmd ${type} failed`, e)
-    }
-    await poll()
-  }
-
-  // 立即拉一次，并定时轮询
-  void poll()
-  const timer = window.setInterval(() => void poll(), 2000)
-  // 容器被移除时停止轮询
-  const mo = new MutationObserver(() => {
-    if (!document.body.contains(container)) {
-      window.clearInterval(timer)
-      mo.disconnect()
-    }
-  })
-  mo.observe(document.body, { childList: true, subtree: true })
-}
-
-// 稳定的 ref 回调：只在首次挂载时构建一次仪表盘
-const gaugeRef = (el: HTMLElement | null): void => {
-  if (el && !el.dataset.tgMounted) {
-    el.dataset.tgMounted = '1'
-    mountGauge(el)
-  }
-}
-
-// 侧边栏 Tab 组件（不调用任何 hook，规避双 React 实例冲突）
-function GaugeTab(): React.ReactElement {
-  return React.createElement('div', { ref: gaugeRef, className: 'tg-tab-root' })
-}
-
-// 侧边栏图标：better-sidebar 以 `icon(size)` 形式调用（见其内置 tab：
-// `icon: (size) => jsx(Icon, { size })`），故这里接收数字尺寸。用 currentColor
-// 着色以自适应明暗主题，纯 SVG 零依赖。
-const GaugeIcon = (size?: number): any => {
-  const s = typeof size === 'number' && size > 0 ? size : 16
-  const svgProps: any = {
-    width: s,
-    height: s,
-    viewBox: '0 0 16 16',
-    fill: 'none',
-    xmlns: 'http://www.w3.org/2000/svg',
-    'aria-hidden': 'true',
-  }
-  // 仪表盘弧 + 指针
-  const arc = React.createElement('path', {
-    d: 'M2.6 11.6a5.6 5.6 0 1 1 10.8 0',
-    stroke: 'currentColor',
-    strokeWidth: 1.5,
-    strokeLinecap: 'round',
-  })
-  const needle = React.createElement('path', {
-    d: 'M8 11.6 10.4 7.2',
-    stroke: 'currentColor',
-    strokeWidth: 1.5,
-    strokeLinecap: 'round',
-  })
-  return React.createElement('svg', svgProps, arc, needle)
-}
-
-// 在「+ 新建 Tab」菜单里的排序位。内置 tab 用 20/91/110 等，order 缺省为 100
-// 会排到菜单最底部不易发现，这里显式给一个偏前的值。
-const TAB_ORDER = 90
-
-export const name = PLUGIN_ID
-
-// 兄弟 bundle 提供的服务（betterSidebar）在本机这个 cordis 里两种读法都不行，必须用
-// ctx.inject 回调模式。原因（已实测坐实，见本文件末尾注释与 dsh-plugin-guide 官方
-// postmortem）：
-//   1) 插件级 `export const inject = ['betterSidebar']`
-//      -> cordis 把整插件 defer，单趟 boot 的 assertEntriesActivated 检查点在
-//         loader.await() 后跑，此时兄弟 bundle 的 provide 还没落到本 fiber，
-//         直接判 "pending (waiting for service: betterSidebar)"（0.1.3 实测）。
-//   2) apply 顶层 `ctx.get('betterSidebar')` 或 `ctx.betterSidebar`
-//      -> 0811 cordis 是「严格注入」：未声明 inject 直接读服务属性，走 ancestor-only
-//         fiber 遍历到 root 找不到就抛
-//         "cannot get property betterSidebar without inject"（0.1.4 实测）。
-// 正确姿势：插件级不声明任何 inject（插件立即激活，不 pending），改用
-// ctx.inject(['betterSidebar'], cb) —— 回调拿到的子上下文里 betterSidebar 是已注入的
-// 合法属性，读它不触发守卫；且注册被延迟到服务就绪那一刻（兄弟 bundle 提供得早或晚
-// 都能注册上）。生态插件 @linxin666/dsh-client-ui-aionui-panel 用的正是这个模式。
-export function apply(ctx: any): (() => void) | void {
-  let registered = false
-  let unregister: unknown = void 0
-
-  // 注册一次即止（registerTab 对重复 id 会抛 "already registered"）
-  const register = (sidebar: any): void => {
-    if (registered || !sidebar || typeof sidebar.registerTab !== 'function') return
-    registered = true
-    try {
-      unregister = sidebar.registerTab({
-        id: PLUGIN_ID,
-        title: 'Token 仪表盘',
-        single: true,
-        order: TAB_ORDER,
-        icon: GaugeIcon,
-        component: GaugeTab,
-      })
-    } catch (e) {
-      registered = false // 失败则允许后续重试
-    }
-  }
-
-  // 主路径：ctx.inject 回调——服务就绪时触发，回调内读 sidebarCtx.betterSidebar 合法
-  let disposeInject: unknown = void 0
-  try {
-    disposeInject = ctx.inject(['betterSidebar'], (sidebarCtx: any) => {
-      register(sidebarCtx && sidebarCtx.betterSidebar)
-    })
-  } catch (e) {
-    /* 运行时无 ctx.inject：交由下面的轮询兜底 */
-  }
-
-  // 兜底：轮询读取。0811 严格注入下未声明 inject 时 ctx.get('betterSidebar')
-  // 会「抛异常」（而非返回 undefined），所以必须用 try/catch 包住读取。
-  const tryRead = (): void => {
-    if (registered) return
-    try {
-      const s = typeof ctx.get === 'function' ? ctx.get('betterSidebar') : ctx.betterSidebar
-      register(s)
-    } catch (e) {
-      /* 服务此刻不可达，下一轮再试 */
-    }
-  }
-  tryRead()
-
-  let timer: unknown = void 0
-  if (!registered) {
-    timer = setInterval(() => {
-      tryRead()
-      if (registered && timer !== void 0) clearInterval(timer as number)
-    }, 500)
-  }
-  const stop = setTimeout(() => {
-    if (timer !== void 0) clearInterval(timer as number)
-  }, 30000)
-
-  // 插件级 disposer
-  return () => {
-    if (timer !== void 0) clearInterval(timer as number)
-    clearTimeout(stop)
-    if (typeof unregister === 'function') (unregister as () => void)()
-    if (typeof disposeInject === 'function') (disposeInject as () => void)()
-  }
-}
+// ============================================================================
+// DSH Client 半边：注册侧边栏 Tab，渲染机车风格仪表盘 + 设置弹窗
+// 运行环境：浏览器（web 平台，与 webServer 同域）。纯原生 DOM/SVG 仪表盘，
+// 通过同域 HTTP 与 Host 半边通信：
+//   GET  /plugins/dsh-token-gauge/state -> 完整 State(JSON)
+//   POST /plugins/dsh-token-gauge/cmd   -> {type,payload} -> 更新后 State
+// 通过官方 shell.overlay 插槽独立挂载浮层面板（方案 A），不再依赖 dsh-better-sidebar。
+// 为避免与运行时 React 产生双实例 hook 冲突，本组件不调用任何 hook，
+// 仅在 ref 回调里挂载一次原生 DOM 仪表盘，并自行轮询刷新。
+// ============================================================================
+import React from 'react'
+import { getStyle, applyPalette, buildCss } from './styles'
+import { createGauge } from './gauge'
+import { t } from './i18n'
+import { downloadReport } from './export'
+import { createSettingsModal } from './settings'
+
+const PLUGIN_ID = 'dsh-token-gauge'
+const ROUTE_STATE = '/plugins/dsh-token-gauge/state'
+const ROUTE_CMD = '/plugins/dsh-token-gauge/cmd'
+
+function totalOf(b: any): number {
+  return (b?.input || 0) + (b?.cacheRead || 0) + (b?.cacheWrite || 0) + (b?.output || 0)
+}
+function todayKey(d = new Date()): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`
+}
+function monthKey(d = new Date()): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}`
+}
+function weekKey(d = new Date()): string {
+  const date = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()))
+  const dayNum = (date.getUTCDay() + 6) % 7
+  date.setUTCDate(date.getUTCDate() - dayNum + 3)
+  const firstThursday = new Date(Date.UTC(date.getUTCFullYear(), 0, 4))
+  const week =
+    1 +
+    Math.round(
+      ((date.getTime() - firstThursday.getTime()) / 86400000 - 3 + ((firstThursday.getUTCDay() + 6) % 7)) / 7,
+    )
+  return `${d.getFullYear()}-W${String(week).padStart(2, '0')}`
+}
+
+function fallbackState(): any {
+  return {
+    global: {},
+    daily: {},
+    weekly: {},
+    monthly: {},
+    sessions: {},
+    models: {},
+    activeSession: '',
+    settings: {
+      style: 'ev',
+      palette: 'neon',
+      lang: 'zh',
+      metric: 'global',
+      display: { usage: true, cost: true, io: true, cacheMiss: true },
+      limits: { global: null, daily: null, weekly: null, monthly: null },
+      pricing: {},
+    },
+  }
+}
+
+// 计算当前指标的量程/费用
+function computeMetric(s: any): { value: number; limit: number | null; cost: number } {
+  const metric = s.settings.metric
+  let entry: any = s.global
+  let limit: number | null = s.settings.limits.global
+  if (metric === 'session') {
+    entry = s.sessions[s.activeSession] || {}
+    limit = s.settings.limits.daily
+  } else if (metric === 'today' || metric === 'daily') {
+    entry = s.daily[todayKey()] || {}
+    limit = s.settings.limits.daily
+  } else if (metric === 'weekly') {
+    entry = s.weekly[weekKey()] || {}
+    limit = s.settings.limits.weekly
+  } else if (metric === 'monthly') {
+    entry = s.monthly[monthKey()] || {}
+    limit = s.settings.limits.monthly
+  }
+  return { value: totalOf(entry), limit, cost: entry.cost || 0 }
+}
+
+// 把原生 DOM 仪表盘挂载进容器，并启动轮询
+function mountGauge(container: HTMLElement): void {
+  // 注入一次全局样式
+  if (!document.getElementById('tg-gauge-style')) {
+    const st = document.createElement('style')
+    st.id = 'tg-gauge-style'
+    st.textContent = buildCss()
+    document.head.appendChild(st)
+  }
+
+  let state: any = null
+  const tr = (k: string) => t((state?.settings?.lang as 'zh' | 'en') || 'zh', k)
+
+  const root = container
+  root.className = 'tg-root tg-style-ev'
+
+  // 头部
+  const head = document.createElement('div')
+  head.className = 'tg-head'
+  const titleEl = document.createElement('div')
+  titleEl.className = 'tg-title'
+  titleEl.textContent = 'Token 仪表盘'
+  const gear = document.createElement('div')
+  gear.className = 'tg-gear'
+  gear.textContent = '⚙'
+  gear.title = '设置'
+  head.append(titleEl, gear)
+  root.appendChild(head)
+
+  // 空数据提示
+  const empty = document.createElement('div')
+  empty.className = 'tg-empty'
+  empty.style.display = 'none'
+  root.appendChild(empty)
+
+  // 仪表盘
+  const gauge = createGauge()
+  root.appendChild(gauge.el)
+
+  // 设置弹窗
+  const modal = createSettingsModal({
+    getLang: () => (state?.settings?.lang as 'zh' | 'en') || 'zh',
+    onSettings: (patch) => sendCmd('setSettings', patch),
+    onExport: (format) => {
+      if (state) downloadReport(state, (state.settings.lang as 'zh' | 'en') || 'zh', format)
+    },
+    onClear: () => sendCmd('clearUsage', undefined),
+    onReset: () => sendCmd('resetSettings', undefined),
+  })
+  root.appendChild(modal.el)
+
+  gear.addEventListener('click', () => modal.open(state || fallbackState()))
+
+  const applyState = (s: any): void => {
+    state = s
+    root.className = 'tg-root ' + getStyle(s.settings.style).className
+    applyPalette(root, s.settings.palette)
+    titleEl.textContent = tr('title')
+    const m = computeMetric(s)
+    gauge.update({ value: m.value, limit: m.limit, cost: m.cost, state: s, display: s.settings.display, t: tr, lang: s.settings.lang })
+    const hasData = totalOf(s.global) > 0
+    empty.style.display = hasData ? 'none' : ''
+    empty.textContent = tr('noData')
+    modal.sync(s)
+  }
+
+  // 拉取最新状态
+  async function poll(): Promise<void> {
+    try {
+      const r = await fetch(ROUTE_STATE, { headers: { Accept: 'application/json' } })
+      if (r.ok) {
+        const s = await r.json()
+        applyState(s)
+      }
+    } catch (e) {
+      // 网络抖动忽略，下一轮重试
+    }
+  }
+
+  // 发送指令并刷新
+  async function sendCmd(type: string, payload: any): Promise<void> {
+    try {
+      await fetch(ROUTE_CMD, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ type, payload }),
+      })
+    } catch (e) {
+      console.warn(`[${PLUGIN_ID}] cmd ${type} failed`, e)
+    }
+    await poll()
+  }
+
+  // 立即拉一次，并定时轮询
+  void poll()
+  const timer = window.setInterval(() => void poll(), 2000)
+  // 容器被移除时停止轮询
+  const mo = new MutationObserver(() => {
+    if (!document.body.contains(container)) {
+      window.clearInterval(timer)
+      mo.disconnect()
+    }
+  })
+  mo.observe(document.body, { childList: true, subtree: true })
+}
+
+// 稳定的 ref 回调：只在首次挂载时构建一次仪表盘
+const gaugeRef = (el: HTMLElement | null): void => {
+  if (el && !el.dataset.tgMounted) {
+    el.dataset.tgMounted = '1'
+    mountGauge(el)
+  }
+}
+
+// 浮层面板组件：固定在右下角、占视口高度 1/3（方案 A：shell.overlay 插槽）。
+// 仍是零 hook、ref 回调挂原生 DOM，规避双 React 实例；外层用内联定位样式，
+// 不被 mountGauge 内的 className 覆盖（style 优先级高于 class）。
+function GaugePanel(): React.ReactElement {
+  return React.createElement('div', {
+    ref: gaugeRef,
+    className: 'tg-panel-root',
+    style: {
+      position: 'fixed',
+      right: '0',
+      bottom: '0',
+      width: '420px',
+      height: '33vh',
+      zIndex: 50,
+      pointerEvents: 'auto',
+      boxSizing: 'border-box',
+      overflow: 'hidden',
+      borderTop: '1px solid var(--dsw-alias-hairline)',
+      borderLeft: '1px solid var(--dsw-alias-hairline)',
+      background: 'var(--dsw-alias-bg-base)',
+      color: 'var(--dsw-alias-label-primary)',
+      boxShadow: '0 0 24px rgba(0,0,0,0.28)',
+    } as any,
+  })
+}
+
+// 侧边栏图标：better-sidebar 以 `icon(size)` 形式调用（见其内置 tab：
+// `icon: (size) => jsx(Icon, { size })`），故这里接收数字尺寸。用 currentColor
+// 着色以自适应明暗主题，纯 SVG 零依赖。
+const GaugeIcon = (size?: number): any => {
+  const s = typeof size === 'number' && size > 0 ? size : 16
+  const svgProps: any = {
+    width: s,
+    height: s,
+    viewBox: '0 0 16 16',
+    fill: 'none',
+    xmlns: 'http://www.w3.org/2000/svg',
+    'aria-hidden': 'true',
+  }
+  // 仪表盘弧 + 指针
+  const arc = React.createElement('path', {
+    d: 'M2.6 11.6a5.6 5.6 0 1 1 10.8 0',
+    stroke: 'currentColor',
+    strokeWidth: 1.5,
+    strokeLinecap: 'round',
+  })
+  const needle = React.createElement('path', {
+    d: 'M8 11.6 10.4 7.2',
+    stroke: 'currentColor',
+    strokeWidth: 1.5,
+    strokeLinecap: 'round',
+  })
+  return React.createElement('svg', svgProps, arc, needle)
+}
+
+// 在「+ 新建 Tab」菜单里的排序位。内置 tab 用 20/91/110 等，order 缺省为 100
+// 会排到菜单最底部不易发现，这里显式给一个偏前的值。
+const TAB_ORDER = 90
+
+export const name = PLUGIN_ID
+
+// 方案 A：通过官方 shell.overlay 插槽（list 型、additive、全框架级浮层）独立挂载仪表盘，
+// 不再依赖第三方插件 dsh-better-sidebar。slots 是 layout 提供的框架级服务（root 早期即
+// 就绪），故插件级 `inject: ['slots']` 不会触发此前 betterSidebar 的 pending / without-inject
+// 问题——这正是脱离 better-sidebar 的核心收益。
+export const inject = ['slots']
+
+export function apply(ctx: any): (() => void) | void {
+  let disposeRegistration: unknown = void 0
+
+  const doRegister = (): void => {
+    // shell.overlay 是 click-through 层，entry 需自行 opt-in pointer events（已在
+    // GaugePanel 外层设 pointerEvents:'auto'）。第二参是返回 React.Element 的工厂函数
+    //（照抄 dsh-cordis-client-runner 官方示例）。
+    disposeRegistration = ctx.slots.register(
+      {
+        name: 'shell.overlay',
+        id: PLUGIN_ID,
+        order: 100,
+        label: 'Token 仪表盘',
+      },
+      () => React.createElement(GaugePanel),
+    )
+  }
+
+  let stop: unknown = void 0
+  try {
+    // slots.inject(seat, cb)：等 shell.overlay 这个 seat 就绪再注册（root 已声明，
+    // 通常同步触发）。某些环境下若无 inject 方法，则直接 register 兜底。
+    if (typeof ctx.slots.inject === 'function') {
+      stop = ctx.slots.inject('shell.overlay', doRegister)
+    } else {
+      doRegister()
+    }
+  } catch (e) {
+    console.error('[dsh-token-gauge] 注册 shell.overlay 失败', e)
+  }
+
+  return () => {
+    if (typeof disposeRegistration === 'function') (disposeRegistration as () => void)()
+    if (typeof stop === 'function') (stop as () => void)()
+  }
+}