dsh-tokenlens 1.3.3 → 1.3.5

package/CHANGELOG.md

@@ -4,9 +4,18 @@
 
 **版本记录约定**：同一发布日只保留一个章节，标题取当日**最后一个**已发布版本号；当日多次发布的改动合并到该章节，并在标题下注明当日实际发布过的版本号（npm 上仍可安装这些独立版本）。若当日已有发布，后续小改动不再单独增加版本号，而是并入下一篇日志。这样日志按天规整、不出现同日多个小版本。
 
-## 1.3.3 — 2026-11-01
+## 1.3.5 — 2026-11-02
 
-（当日已发布版本：v1.2.2 / v1.3.0 / v1.3.1 / v1.3.3；v1.3.2 因仓库迁移未发布）
+- feat(ui): 供应商管理页可为 **Open Design** 填写「工作区 ID」并持久化到插件配置——此前 workspaceId 只能在 profile patch 或 `OPENDESIGN_WORKSPACE_ID` 里设置，用推理 Key 配好供应商后额度卡片仍报错却无处可改
+- feat(ui): Open Design 额度失败时的引导——详情弹窗的错误条说明「额度查询需要工作区 ID 与 Control Key（不是推理 Key）」，并提供「去配置」按钮直接跳到供应商管理页
+- feat(host): Host 侧错误文案更具体（distinguish 缺 workspaceId / 缺 Control Key，并指向管理页）；`providerUpdate` 接受 `workspaceId`，校验为 1–120 位标识符字符（字母、数字、`. _ : @ -`），路径穿越/空格/超长一律拒绝
+- feat(wire): `providers[]` 仅对声明了 workspace 的适配器（Open Design）下发 `workspaceId` 字段；其余供应商不下发，客户端据此决定是否渲染输入框（旧 Host 无此字段 ⇒ 不渲染，自然降级）
+- feat(ui): Open Design 缺配置时 chip 不再按 `missing-key` 静默隐藏，而是显示「待配置」并可点进详情看引导——否则用户既看不到提示也没有入口
+- 测试：280 → 285（workspace ID 校验/持久化/清空、管理页字段渲染与保存、缺 workspaceId 的 Host 报错与引导按钮、待配置 chip）
+
+## 1.3.4 — 2026-11-01
+
+（当日已发布版本：v1.2.2 / v1.3.0 / v1.3.1 / v1.3.3 / v1.3.4；v1.3.2 因仓库迁移未发布）
 
 - feat(update): 「启动时检查更新」改为**默认开启**（可在插件设置关闭）；启动时向 npm registry 查询一次 latest 版本号，不携带凭据 / 账号 / 用量，失败只记录错误、不阻塞启动
 - feat(ui): 详情弹窗（统计首页）右下角的**插件版本处**显示更新状态——有新版本时显示「有新版本 vX」并可点击打开 npm；无新版本时显示「已是最新版本」；检查失败或关闭检查时不显示
@@ -16,6 +25,7 @@
 - chore(repo): 仓库迁移到 **senyingxidi/dsh-tokenlens**（原作者账号改名）；同步更新 `package.json` 的 repository/homepage/bugs、README 徽章与 7 张截图、`market/index.json`、CONTRIBUTING / SECURITY / CODE_OF_CONDUCT / Issue 模板与 LICENSE 署名；旧 GitHub 地址会 301 重定向，旧市场索引 raw 地址继续可用
 - fix(ui): 插件版本处自愈——页面在插件更新前加载时，`hello` 的旧版本号不再覆盖新的 Host 版本（取 hello / providers / 更新检查 `current` 中最新的版本），无需刷新页面即可显示正确版本
 - docs: README 增加「用 `link:` 安装的插件不要从插件市场重复安装/升级」的 Windows pnpm EPERM 排错说明；CHANGELOG 改为按发布日合并
+- test(ci): 修复 Windows CI 偶发失败——倒计时测试 fixture 增加 30 秒余量，慢机器上「2 小时 30 分后重置」不再跨成 29 分（CI #26 / #28 的偶发红均属这类跨分钟/小时边界）
 - 测试：280 个自动化用例（版本比较/检查/并发、设置开关、状态行、图表下钻与窗口、工作区 wire 回归）
 
 ## 1.2.1 — 2026-10-31

package/PROTOCOL.md

@@ -305,6 +305,9 @@ with `[path]`.
 Client behaviour:
 
 - `missing-key`, `unsupported-provider`, `disabled` → hide the chip (silent).
+  The one exception (v1.3.5): a provider whose Host payload carries a `workspaceId`
+  field (Open Design) keeps a 「待配置 / Needs setup」 chip on `missing-key`, because
+  hiding it would leave no way to reach the dialog's configuration guidance.
 - everything else → show the chip in a warning state with a retry action.
 
 ## Provider selection (client side)
@@ -327,13 +330,15 @@ needs no provider catalog of its own.
 
 The dialog 「供应商管理」 page talks to three additional actions:
 
-- `{action:"providers"}` → `{ok:true, version, providers:[{providerId,label,shortLabel,kind,enabled,hasKey,keySource,apiKeyRef,baseURL,consoleUrl,builtin,dshManaged,dshProviderId}], dshProviders:[{providerId,label,supported,usageProviderId}], settings:{labelStyle,defaultView,defaultScope,detailsExpanded,detailsWindow,updateCheck}, update:<UpdateInfo|null>, updatePackageUrl, storeFile, storeFileDisplay}`. `storeFile` is the real path (local tooling); `storeFileDisplay` replaces the user's home directory with `~` and is what the management page renders. `version` (v1.3.2) is the running Host version, so a page loaded before an in-place plugin update can refresh a stale `hello` label without a reload. `update` (v1.3.0) is the last update-check result and `updatePackageUrl` the npm page the management UI links to.
-- `{action:"providerUpdate", providerId, update:{enabled?,apiKey?,apiKeyRef?,baseURL?,consoleUrl?,label?,shortLabel?}}` → same list payload;
+- `{action:"providers"}` → `{ok:true, version, providers:[{providerId,label,shortLabel,kind,enabled,hasKey,keySource,apiKeyRef,baseURL,consoleUrl,workspaceId?,builtin,dshManaged,dshProviderId}], dshProviders:[{providerId,label,supported,usageProviderId}], settings:{labelStyle,defaultView,defaultScope,detailsExpanded,detailsWindow,updateCheck}, update:<UpdateInfo|null>, updatePackageUrl, storeFile, storeFileDisplay}`. `storeFile` is the real path (local tooling); `storeFileDisplay` replaces the user's home directory with `~` and is what the management page renders. `version` (v1.3.2) is the running Host version, so a page loaded before an in-place plugin update can refresh a stale `hello` label without a reload. `update` (v1.3.0) is the last update-check result and `updatePackageUrl` the npm page the management UI links to. `workspaceId` (v1.3.5) is present only on adapters whose defaults declare one (currently `open-design`); its mere presence is the capability flag for the management page's workspace-ID input, so a provider without it renders no such field.
+- `{action:"providerUpdate", providerId, update:{enabled?,apiKey?,apiKeyRef?,baseURL?,workspaceId?,consoleUrl?,label?,shortLabel?}}` → same list payload;
   empty strings clear a stored value (falling back to the profile/default). `label` (全名, ≤40 chars) and
-  `shortLabel` (短标签, ≤12 chars) let the management page rename a provider. The shipped management page no
-  longer edits API keys or base URLs: every provider inherits them from DSH model settings, and the page only
-  saves enabled/consoleUrl/label/shortLabel. Overrides are persisted atomically to
-  `$DSH_HOME/dsh-tokenlens/providers.json` (plugin-owned, not the profile patch); the same file also
+  `shortLabel` (短标签, ≤12 chars) let the management page rename a provider. `workspaceId` (v1.3.5, ≤120 chars,
+  charset `[A-Za-z0-9._:@-]`) is the workspace-scoped identifier Open Design's read-only billing API needs; a
+  value that is not identifier-shaped (slashes, whitespace, path traversal) answers `parse` and is never persisted.
+  The shipped management page no longer edits API keys or base URLs: every provider inherits them from DSH model
+  settings, and the page only saves enabled/consoleUrl/workspaceId/label/shortLabel. Overrides are persisted
+  atomically to `$DSH_HOME/dsh-tokenlens/providers.json` (plugin-owned, not the profile patch); the same file also
 - `{action:"providerTest", providerId}` → the normal snapshot envelope (`{ok,snapshot}` or `{ok:false,error}`), forcing one upstream read.
 - `{action:"settingsUpdate", settings:{labelStyle?:"short"|"full", defaultView?:"chart"|"data", defaultScope?:"provider"|"all", detailsExpanded?:"auto"|"expanded"|"collapsed", detailsWindow?:"today"|"last7Days"|"second"|"total", updateCheck?:boolean}}` → the same providers payload; every field is optional and persisted in the store (`settings.*`). `labelStyle` controls whether the composer chip shows each provider's `shortLabel` or full `label`; `defaultView` / `defaultScope` / `detailsExpanded` are the usage-dialog defaults; `detailsWindow` (v1.2.1) is the remembered 明细 donut window (falls back visually to `total` when that window is unavailable on the current provider/host); `updateCheck` (v1.3.0, default `true` since v1.3.1) enables the startup update check — the off→on transition runs one check immediately. Invalid values answer `unsupported-provider`.
 

package/README.en.md

@@ -9,7 +9,7 @@
 
 > One glance at your usage: plan capacity for the selected provider plus local token statistics across harnesses, right below the DSH composer.
 
-**dsh-TokenLens** is a usage plugin for DSH (DeepSeek Harness), version v1.3.3. It keeps two kinds of numbers separate:
+**dsh-TokenLens** is a usage plugin for DSH (DeepSeek Harness), version v1.3.4. It keeps two kinds of numbers separate:
 
 - **Plan capacity** — the provider's authoritative server-side values (percentage windows, used / cap, balance or remaining credit);
 - **Local token stats** — tokens consumed on this machine across every connected harness, for the selected provider or for all providers combined.
@@ -66,7 +66,7 @@ dsh plugin --profile <profile> add dsh-tokenlens
 Then make sure `dsh.profile.bundles` in `$DSH_HOME/profiles/<profile>/package.json` contains `"dsh-tokenlens"`:
 
 ```jsonc
-{ "dependencies": { "dsh-tokenlens": "^1.3.3" },
+{ "dependencies": { "dsh-tokenlens": "^1.3.4" },
   "dsh": { "profile": { "bundles": ["…", "dsh-tokenlens"] } } }
 ```
 
@@ -107,7 +107,7 @@ Every option is optional. Override the `dsh-tokenlens` row in `$DSH_HOME/profile
 
 Credentials come from DSH itself: providers configured in DSH inherit their `apiKeyEnv`, or you can set environment variables such as `OPENCODE_GO_API_KEY`, `COMMANDCODE_API_KEY` and `DEEPSEEK_API_KEY`.
 
-Open Design (OpenDesign) is the exception: its read-only billing API needs a **workspace ID** plus a **Control Key** (`OPENDESIGN_CONTROL_KEY` or `VELA_CONTROL_KEY`), which is *not* the inference API key from the Cloud API Keys page. Set `providers.open-design.workspaceId` (or `OPENDESIGN_WORKSPACE_ID`) and provide the Control Key through the environment, DSH credentials, or the management page's key field.
+Open Design (OpenDesign) is the exception: its read-only billing API needs a **workspace ID** plus a **Control Key** (`OPENDESIGN_CONTROL_KEY` or `VELA_CONTROL_KEY`), which is *not* the inference API key from the Cloud API Keys page. Set the workspace ID right on the provider management page's Open Design card (v1.3.5, stored in the plugin's own config and kept across restarts), under `providers.open-design.workspaceId`, or via `OPENDESIGN_WORKSPACE_ID`; provide the Control Key through the environment, DSH credentials, or the management page's key field. When either is missing the detail dialog names the missing piece and offers a 「去配置 / Configure」 button instead of a generic missing-key error.
 
 See the [Chinese README](README.md) for the full configuration reference, preview and provider tables.
 

package/README.md

@@ -9,7 +9,7 @@
 
 > **一眼看清你的用量**：在 DSH 输入框下方显示当前供应商的套餐容量，并汇总本机跨 Harness 的 Token 消耗。
 
-**dsh-TokenLens（词元透镜）** 是 DSH（DeepSeek Harness）的用量插件（v1.3.3，公开版本）。它把两类数字**按不同口径**分开呈现：
+**dsh-TokenLens（词元透镜）** 是 DSH（DeepSeek Harness）的用量插件（v1.3.4，公开版本）。它把两类数字**按不同口径**分开呈现：
 
 - **套餐容量**（供应商服务端权威值）：百分比窗口、`已用 / 上限`、账户余额或剩余额度；
 - **本机 Token 统计**（本机记录）：当前供应商在本机所有已接入 Harness 上的合计用量，也可切到「全部 Harness」看总账。
@@ -41,7 +41,7 @@
   - **本机 Token 统计**：今日 / 最近 7 天 / 最近 30 天 / 总计（订阅类供应商显示「最近 X 天」生效窗口），可按「当前供应商 · 全部 Harness」与「全部 Harness」两个视角查看。
   - **明细与图表**：按 Harness、按供应商、Top 模型、未映射供应商分组；支持「数据」（表格）与「图表」两种模式切换。图表模式里点击某一天的柱子可下钻查看**当天 24 小时**的 Token 消耗，底部「明细」环形图支持 **今日 / 最近 7 天 / 最近 X 天（或最近 30 天）/ 总计** 窗口切换。
   - **工作区徽标**（实验性）：左侧工作区列表的名称旁显示该工作区的本机 Token 合计，悬浮卡片显示今日 / 7 天 / 30 天 / 总计；纯展示，找不到对应 UI 时自动降级。
-- **供应商管理页**：「已配置 / 内置 / 全部」筛选、启用开关、凭据状态、控制台链接、短标签与全名编辑、测试连接、已订阅徽章；另有「插件设置」可配置标签样式、默认展示模式、默认统计范围、明细展开状态、图表「明细」环形图的默认窗口（今日 / 最近 7 天 / 最近 X 天 / 总计，记住上次选择）与「启动时检查更新」（默认开启，可关闭，也可手动立即检查）。
+- **供应商管理页**：「已配置 / 内置 / 全部」筛选、启用开关、凭据状态、控制台链接、短标签与全名编辑、测试连接、已订阅徽章；Open Design 额外提供「工作区 ID」输入（v1.3.5）；另有「插件设置」可配置标签样式、默认展示模式、默认统计范围、明细展开状态、图表「明细」环形图的默认窗口（今日 / 最近 7 天 / 最近 X 天 / 总计，记住上次选择）与「启动时检查更新」（默认开启，可关闭，也可手动立即检查）。
 - **自动识别**：在 DSH「设置 → 模型服务」中配置过的供应商会自动出现在管理页，并按路由 id 或 baseURL 主机匹配内置用量适配器，自动继承 DSH 中的凭据，无需重复填写。
 - **Agent 工具**：注册 `tokenlens_usage`，模型可以自行查询套餐容量与本机用量。
 
@@ -106,7 +106,7 @@ dsh plugin --profile <profile> add dsh-tokenlens
 ```jsonc
 {
   "dependencies": {
-    "dsh-tokenlens": "^1.3.3"
+    "dsh-tokenlens": "^1.3.4"
   },
   "dsh": {
     "profile": {
@@ -192,7 +192,8 @@ dsh plugin --profile <profile> remove dsh-tokenlens
 - 在 DSH「设置 → 模型服务」中配置过的供应商会被自动识别，插件按路由 id 或 baseURL 主机匹配内置适配器，并继承该路由的 `apiKeyEnv` 凭据。
 - 也可以直接用环境变量提供，例如 `OPENCODE_GO_API_KEY`、`COMMANDCODE_API_KEY`、`DEEPSEEK_API_KEY`、`MOONSHOT_API_KEY` 等（每家供应商的引用见 `lib/providers.mjs`）。
 - 或写入 `$DSH_HOME/.credentials.yaml` 的 `refs:` 映射（与 DSH 凭据服务同一份文档）。
-- **Open Design（OpenDesign）** 的额度查询需要 OpenDesign Cloud 的 **workspace ID + Control Key**（`OPENDESIGN_CONTROL_KEY` 或 `VELA_CONTROL_KEY`），**不是** Cloud API Keys 页的推理 Key（推理 Key 只能调用模型）。workspace ID 写在 provider 配置里，或用 `OPENDESIGN_WORKSPACE_ID` 环境变量；Control Key 也可以在供应商管理页的 Key 输入框填写。
+- **Open Design（OpenDesign）** 的额度查询需要 OpenDesign Cloud 的 **workspace ID + Control Key**（`OPENDESIGN_CONTROL_KEY` 或 `VELA_CONTROL_KEY`），**不是** Cloud API Keys 页的推理 Key（推理 Key 只能调用模型）。workspace ID 可直接在[供应商管理页](#供应商管理)的 Open Design 卡片里填写（v1.3.5，保存在插件自己的配置里，重启后仍在），或写在 provider 配置里，或用 `OPENDESIGN_WORKSPACE_ID` 环境变量；Control Key 通过环境变量 / DSH 凭据 / 管理页的 Key 输入框提供。
+- 配置不全时，详情弹窗会说明缺哪一项并提供「去配置」按钮，而不是只显示一个笼统的「没有找到该供应商的 API Key」。
 
 解析顺序（先命中先用）：DSH 凭据服务 → 环境变量 → `$DSH_HOME/.credentials.yaml` → OpenCode CLI 的 `auth.json`（仅默认的 `OPENCODE_GO_API_KEY` 引用）。
 
@@ -252,7 +253,7 @@ dsh plugin --profile <profile> remove dsh-tokenlens
 
 - 同 id 的配置行**整体替换**插件的默认配置，因此覆盖时请重述所有想保留的字段；
 - `providers.<id>` 与 `stats.<zcode|opencode|workbuddy|qoder>` 内部按字段合并到默认值上；
-- 供应商管理页保存的覆盖（启用状态、名称、控制台链接等）写入插件自己的 `$DSH_HOME/dsh-tokenlens/providers.json`（原子写入、仅本人可读），既不进 profile patch，也不会覆盖 DSH 模型设置；读取优先级为 **管理页覆盖 > profile 配置 > 内置默认**。
+- 供应商管理页保存的覆盖（启用状态、名称、控制台链接、Open Design 的工作区 ID 等）写入插件自己的 `$DSH_HOME/dsh-tokenlens/providers.json`（原子写入、仅本人可读），既不进 profile patch，也不会覆盖 DSH 模型设置；读取优先级为 **管理页覆盖 > profile 配置 > 内置默认**。
 - `enabled: false` 会卸载 Host 半（bridge、Agent 工具与轮询一并停止），适合临时停用插件。
 
 ## 支持的供应商
@@ -280,7 +281,7 @@ dsh plugin --profile <profile> remove dsh-tokenlens
 
 - OpenCode 的额度定义见[官方文档](https://opencode.ai/docs/go/#usage-limits)（5h = 月度额度的 20%、周 = 50%、月 = 100%）；接口只返回百分比，插件也只画百分比。
 - Command Code 的 `/alpha/*` 是官方 CLI 自用的私有计费路由；免费 / 无方案账户返回空窗口（显示 `—`），插件不会用方案目录猜额度。
-- Open Design 的窗口按账户实际返回的时长渲染：Go 同时有 5 小时和 7 天窗口，Plus / Pro / Max 只有 7 天窗口；钱包余额是独立于窗口的 USD 额度，用尽后继续扣钱包。查询要求工作区权限，鉴权失败会明确显示错误而不是 0。
+- Open Design 的窗口按账户实际返回的时长渲染：Go 同时有 5 小时和 7 天窗口，Plus / Pro / Max 只有 7 天窗口；钱包余额是独立于窗口的 USD 额度，用尽后继续扣钱包。查询要求工作区权限，鉴权失败会明确显示错误而不是 0；工作区 ID 与 Control Key 缺任一项时，弹窗会指出缺哪一项并给出「去配置」入口（v1.3.5）。
 - 未配置凭据的供应商 chip 静默隐藏；`zai`、`minimax`、`deepinfra` 属 best-effort 适配（未公开接口，失败时按可重试错误优雅降级）。
 - 各供应商的元数据（`kind` / `label` / `shortLabel` / `baseURL` / `apiKeyRef` / `consoleUrl`）集中在 `lib/providers.mjs` 的 `PROVIDER_DEFAULTS` 与 `ADAPTERS` 中，新增适配器只需在该文件登记并补测试。
 
@@ -392,7 +393,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 
 ## 验证
 
-- `node --test`：**280 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
+- `node --test`：**285 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
 - 在真实环境中验证过 **5 个 harness** 的数据源；本机统计与独立的 SQLite 查询、独立的日志解析逐项对账（差额为 0），跨 harness 合并与供应商映射算术自洽。
 - 供应商接口按各官方文档与参考客户端行为验证；未配置凭据时 chip 静默隐藏，接口异常时按可重试错误降级。
 

package/client.js

@@ -157,6 +157,7 @@ window.__ModuleLoader__.load({
       title: '词元透镜（dsh-TokenLens）',
       chipHint: '当前模型供应商的套餐用量，点击查看详情',
       chipUnavailable: '用量读取失败',
+      chipNeedsConfig: '待配置',
       chipNoUsage: '暂无用量',
       chipRolling: '5时',
       chipWeekly: '周',
@@ -328,6 +329,12 @@ window.__ModuleLoader__.load({
       presetCollapse: '收起',
       providerConsoleURL: '控制台地址（Console URL）',
       providerConsoleURLPlaceholder: '留空则使用内置默认地址',
+      providerWorkspaceId: '工作区 ID（Workspace ID）',
+      providerWorkspaceIdHint: 'Open Design Cloud 工作区标识；额度查询需要',
+      providerWorkspaceIdPlaceholder: '留空则使用环境变量 OPENDESIGN_WORKSPACE_ID',
+      providerWorkspaceIdTooLong: '工作区 ID 最多 120 个字符',
+      configureProvider: '去配置',
+      errorOpenDesignConfig: 'Open Design 额度查询需要工作区 ID 与 Control Key（不是推理 Key）',
       providerSave: '保存',
       providerSaving: '保存中…',
       providerTest: '测试连接',
@@ -401,6 +408,7 @@ window.__ModuleLoader__.load({
       title: 'dsh-TokenLens',
       chipHint: 'Plan usage for the selected provider — click for details',
       chipUnavailable: 'Usage unavailable',
+      chipNeedsConfig: 'Needs setup',
       chipNoUsage: 'No usage',
       chipRolling: '5h',
       chipWeekly: 'wk',
@@ -572,6 +580,12 @@ window.__ModuleLoader__.load({
       presetExpand: 'Expand',
       presetCollapse: 'Collapse',
       providerConsoleURL: 'Console URL',
+      providerWorkspaceId: 'Workspace ID',
+      providerWorkspaceIdHint: 'The Open Design Cloud workspace identifier the quota query is scoped to',
+      providerWorkspaceIdPlaceholder: 'Empty uses the OPENDESIGN_WORKSPACE_ID environment variable',
+      providerWorkspaceIdTooLong: 'The workspace ID may be at most 120 characters',
+      configureProvider: 'Configure',
+      errorOpenDesignConfig: 'Open Design quota needs a workspace ID and a Control Key (not an inference key)',
       providerConsoleURLPlaceholder: 'Leave empty for the built-in default',
       providerSave: 'Save',
       providerSaving: 'Saving…',
@@ -1083,6 +1097,10 @@ window.__ModuleLoader__.load({
       // how to add that route instead of offering any credential input.
       const wireDshProviderId = (stringOrEmpty(raw.dshProviderId) || '').trim()
       const dshManaged = raw.dshManaged === true && wireDshProviderId !== ''
+      // v1.3.5: workspace-scoped adapters (Open Design) carry the workspace id a
+      // user may set on this page. Absent on every other provider (and on an
+      // older Host), where it normalizes to '' and no field renders.
+      const workspaceId = (stringOrEmpty(raw.workspaceId) || '').trim()
       // v0.16.0: user-declared custom adapters are flagged `custom:true` (and are
       // no longer builtin). The Host currently returns only the display/credential
       // hints, so the optional declaration tail is normalized defensively: a Host
@@ -1114,6 +1132,10 @@ window.__ModuleLoader__.load({
         windows: normalizeCustomWindows(raw.windows),
         dshManaged,
         dshProviderId: dshManaged ? wireDshProviderId : '',
+        // v1.3.5: the Host only sends this field for adapters that use it; its
+        // mere presence is the capability flag that renders the input.
+        workspaceId,
+        supportsWorkspaceId: Object.prototype.hasOwnProperty.call(raw, 'workspaceId'),
       }
     }
 
@@ -2306,6 +2328,7 @@ window.__ModuleLoader__.load({
               update !== null && typeof update === 'object' && Object.prototype.hasOwnProperty.call(update, field)
             const clearedDraft = hasField('consoleUrl')
             const resetNames = !clearedDraft && (hasField('shortLabel') || hasField('label'))
+            const resetWorkspace = hasField('workspaceId')
             const rowTest = { ...current.rowTest }
             delete rowTest[providerId]
             // Adopt the answered list; a Host that omits it must not blank the page.
@@ -2313,17 +2336,26 @@ window.__ModuleLoader__.load({
             let nextDrafts = current.drafts
             if (clearedDraft) {
               nextDrafts = mapWithout(current.drafts, providerId)
-            } else if (resetNames) {
+            } else if (resetNames || resetWorkspace) {
               const draft = current.drafts[providerId]
               const answered = adoptsList
                 ? parsed.providers.find((entry) => entry.providerId === providerId)
                 : undefined
               if (draft !== undefined && draft !== null && typeof draft === 'object') {
-                nextDrafts = mapWith(current.drafts, providerId, {
-                  ...draft,
-                  shortLabel: answered !== undefined ? answered.shortLabel : draft.shortLabel,
-                  label: answered !== undefined ? answered.label : draft.label,
-                })
+                const next = { ...draft }
+                if (resetNames) {
+                  next.shortLabel = answered !== undefined ? answered.shortLabel : draft.shortLabel
+                  next.label = answered !== undefined ? answered.label : draft.label
+                }
+                // v1.3.5: a saved workspace id re-seeds from the answered list,
+                // so a normalized (trimmed) value replaces the raw draft.
+                if (resetWorkspace) {
+                  next.workspaceId =
+                    answered !== undefined && typeof answered.workspaceId === 'string'
+                      ? answered.workspaceId
+                      : draft.workspaceId
+                }
+                nextDrafts = mapWith(current.drafts, providerId, next)
               }
             }
             patchManagement({
@@ -2810,6 +2842,7 @@ window.__ModuleLoader__.load({
         consoleUrl: provider.consoleUrl,
         shortLabel: provider.shortLabel,
         label: provider.label,
+        workspaceId: typeof provider.workspaceId === 'string' ? provider.workspaceId : '',
       }
     }
 
@@ -2830,6 +2863,13 @@ window.__ModuleLoader__.load({
       if (shortLabel !== provider.shortLabel) update.shortLabel = shortLabel
       const label = typeof source.label === 'string' ? source.label.trim() : provider.label
       if (label !== provider.label) update.label = label
+      // v1.3.5: the workspace id of a workspace-scoped adapter; an empty string
+      // clears the override so the Host falls back to its env var.
+      if (provider.supportsWorkspaceId === true) {
+        const wireWorkspaceId = typeof provider.workspaceId === 'string' ? provider.workspaceId : ''
+        const workspaceId = typeof source.workspaceId === 'string' ? source.workspaceId.trim() : wireWorkspaceId
+        if (workspaceId !== wireWorkspaceId) update.workspaceId = workspaceId
+      }
       return update
     }
 
@@ -2852,13 +2892,15 @@ window.__ModuleLoader__.load({
               consoleUrl: provider.consoleUrl,
               shortLabel: provider.shortLabel,
               label: provider.label,
+              workspaceId: typeof provider.workspaceId === 'string' ? provider.workspaceId : '',
             }),
       })
     }
 
-    /** Record one typed editor value (names and the display-only console URL). */
+    /** Record one typed editor value (names, the display-only console URL, the workspace id). */
     function updateProviderDraft(provider, field, value) {
-      if (field !== 'consoleUrl' && field !== 'shortLabel' && field !== 'label') return
+      if (field !== 'consoleUrl' && field !== 'shortLabel' && field !== 'label' && field !== 'workspaceId') return
+      if (field === 'workspaceId' && provider.supportsWorkspaceId !== true) return
       if (provider === null || provider === undefined) return
       const current = store.get().management
       const draft = providerDraftOf(provider, current)
@@ -3201,6 +3243,9 @@ window.__ModuleLoader__.load({
 .dsh-tokenlens-banner{border:1px solid var(--dsw-alias-border-subtle,rgba(127,127,127,.24));border-radius:var(--dsw-radius-sm);padding:8px 10px;display:flex;flex-direction:column;gap:6px;background:var(--dsw-alias-interactive-bg-hover,rgba(127,127,127,.06))}
 .dsh-tokenlens-banner-title{color:var(--dsw-alias-label-error,#d9534f);font-size:var(--dsw-alias-font-size-sm,12px);line-height:1.5;font-weight:600}
 .dsh-tokenlens-banner-detail{color:var(--dsw-alias-label-tertiary);font-size:var(--dsw-alias-font-size-sm,12px);line-height:1.5;overflow-wrap:anywhere}
+.dsh-tokenlens-banner-hint{align-items:center;display:flex;gap:8px;flex-wrap:wrap;color:var(--dsw-alias-label-secondary);font-size:var(--dsw-alias-font-size-sm,12px);line-height:1.5}
+.dsh-tokenlens-banner-hint-text{min-width:0;overflow-wrap:anywhere}
+.dsh-tokenlens-configure-provider{flex:none}
 .dsh-tokenlens-banner-actions{align-items:center;display:flex;gap:8px}
 .dsh-tokenlens-meta{align-items:baseline;gap:8px;display:flex;justify-content:space-between;color:var(--dsw-alias-label-tertiary);font-size:var(--dsw-alias-font-size-sm,12px);line-height:1.5}
 .dsh-tokenlens-stale{color:#d98a1f;white-space:nowrap}
@@ -3507,9 +3552,23 @@ window.__ModuleLoader__.load({
     // The compositor dock chip.
     // ---------------------------------------------------------------------
 
+    /**
+     * Whether this state is a workspace-scoped provider (Open Design) that is
+     * missing its configuration. Such a provider keeps a chip as the only entry
+     * point to the guidance in the dialog (v1.3.5), because 「没有 API Key」 hides
+     * the chip by protocol and would leave the user with no way in.
+     */
+    function needsWorkspaceConfigEntry(state) {
+      if (normalizeSnapshot(state.snapshot) !== null) return false
+      if (state.error === null || typeof state.error !== 'object' || state.error.code !== 'missing-key') return false
+      const rawId = state.providerId !== null ? state.providerId : (state.snapshot?.provider?.id ?? null)
+      return canonicalProviderId(rawId) === 'open-design'
+    }
+
     /** Whether the chip must stay silent for this state. */
     function chipHidden(state) {
-      return isHidden(state.error)
+      if (!isHidden(state.error)) return false
+      return needsWorkspaceConfigEntry(state) !== true
     }
 
     /** Severity of the chip dot: worst window, balance/unknown mapped to normal. */
@@ -3614,25 +3673,30 @@ window.__ModuleLoader__.load({
     /** The chip when the route has failed and there is no data yet. */
     function buildUnavailableChip(state, t, sessionId) {
       const brand = providerBrand(state, null)
+      // A workspace-scoped provider missing its configuration reads as 「待配置」
+      // instead of a read failure: nothing upstream failed, setup is incomplete.
+      const needsConfig = needsWorkspaceConfigEntry(state)
+      const label = needsConfig ? t('chipNeedsConfig') : t('chipUnavailable')
       return h(
         'span',
         { className: 'dsh-tokenlens-anchor', 'data-composer-stat': 'tokenlens' },
         h(
           Tooltip,
-          { label: t('chipUnavailable'), side: 'top' },
+          { label, side: 'top' },
           h(
             'button',
             {
               type: 'button',
               className: 'dsh-tokenlens-chip',
-              title: t('chipUnavailable'),
-              'aria-label': t('chipUnavailable'),
+              title: label,
+              'aria-label': label,
               'aria-haspopup': 'dialog',
+              ...(needsConfig ? { 'data-needs-config': 'true' } : {}),
               onClick: () => openDialog(sessionId),
             },
             h('span', { className: 'dsh-tokenlens-dot', 'data-level': 'warning', 'aria-hidden': true }),
             h('span', { className: 'dsh-tokenlens-brand' }, brand),
-            h('span', { className: 'dsh-tokenlens-metric' }, t('chipUnavailable')),
+            h('span', { className: 'dsh-tokenlens-metric' }, label),
           ),
         ),
       )
@@ -3880,7 +3944,7 @@ window.__ModuleLoader__.load({
     }
 
     /** The error banner, with a retry button unless the Host says it cannot help. */
-    function buildErrorBanner(error, t, onRetry, key) {
+    function buildErrorBanner(error, t, onRetry, key, extraChildren) {
       const localized = describeError(error, t)
       const detail = typeof error?.message === 'string' ? error.message.trim() : ''
       const showDetail = detail !== '' && detail !== localized
@@ -3890,15 +3954,41 @@ window.__ModuleLoader__.load({
           h(Button, { key: 'retry', variant: 'outline', className: 'dsh-tokenlens-retry', onClick: onRetry }, t('retry')),
         )
       }
+      const extras = Array.isArray(extraChildren) ? extraChildren.filter((child) => child !== null && child !== undefined) : []
       return h(
         'div',
         { key: key ?? 'error', className: 'dsh-tokenlens-banner', 'data-kind': 'error', role: 'alert' },
         h('div', { className: 'dsh-tokenlens-banner-title' }, localized),
         showDetail ? h('div', { className: 'dsh-tokenlens-banner-detail' }, detail) : null,
+        extras.length > 0 ? h('div', { className: 'dsh-tokenlens-banner-hint' }, extras) : null,
         actions.length > 0 ? h('div', { className: 'dsh-tokenlens-banner-actions' }, actions) : null,
       )
     }
 
+    /**
+     * The extra guidance a workspace-scoped provider (Open Design) gets when its
+     * configuration is incomplete: the reason in product terms plus a jump to the
+     * management page, where the workspace id and the Control Key hint live.
+     */
+    function buildWorkspaceConfigHint(state, error, t) {
+      if (error === null || typeof error !== 'object' || error.code !== 'missing-key') return []
+      const rawId = state.providerId !== null ? state.providerId : (state.snapshot?.provider?.id ?? null)
+      if (canonicalProviderId(rawId) !== 'open-design') return []
+      return [
+        h('span', { key: 'text', className: 'dsh-tokenlens-banner-hint-text' }, t('errorOpenDesignConfig')),
+        h(
+          Button,
+          {
+            key: 'configure',
+            variant: 'outline',
+            className: 'dsh-tokenlens-configure-provider',
+            onClick: () => openManagement(),
+          },
+          t('configureProvider'),
+        ),
+      ]
+    }
+
     /** The usage "last updated" line plus a stale marker. */
     function buildMeta(state, snapshot, now, t) {
       if (snapshot === null) return null
@@ -5121,6 +5211,7 @@ window.__ModuleLoader__.load({
               void requestUsage('refresh')
             },
             'usage-error',
+            buildWorkspaceConfigHint(state, state.error, t),
           ),
         )
       }
@@ -6012,6 +6103,21 @@ window.__ModuleLoader__.load({
           label: t('providerConsoleURL'),
           placeholder: t('providerConsoleURLPlaceholder'),
         }),
+        // v1.3.5: only workspace-scoped adapters (Open Design) ask for a
+        // workspace id; every other provider renders no field at all.
+        provider.supportsWorkspaceId === true
+          ? buildProviderNameField(provider, management, t, {
+              key: 'workspaceId',
+              className: 'dsh-tokenlens-workspaceid-input',
+              dataAttr: 'data-provider-workspaceid',
+              field: 'workspaceId',
+              label: t('providerWorkspaceId'),
+              hint: t('providerWorkspaceIdHint'),
+              placeholder: t('providerWorkspaceIdPlaceholder'),
+              maxLength: 120,
+              tooLongText: t('providerWorkspaceIdTooLong'),
+            })
+          : null,
       ]
       const actions = h(
         'div',

package/index.js

@@ -29,7 +29,9 @@ import {
   DISPLAY_VIEWS,
   LABEL_STYLES,
   STATS_SCOPES,
+  WORKSPACE_ID_MAX,
   defaultProviderStoreFile,
+  isWorkspaceId,
   loadProviderStore,
   mergeProviderOverride,
   sanitizeSettings,
@@ -74,7 +76,7 @@ export const inject = []
 export const PLUGIN_NAME = 'dsh-tokenlens'
 
 /** Plugin version; mirrors package.json (kept here so diagnostics need no fs read). */
-export const PLUGIN_VERSION = '1.3.3'
+export const PLUGIN_VERSION = '1.3.5'
 
 /** Documented defaults; every field of the raw row config is optional. */
 const DEFAULTS = {
@@ -636,6 +638,9 @@ export function apply(ctx, rawConfig) {
         })
         key = { ...key, hasKey: key.hasKey && typeof secret.value === 'string' && secret.value !== '' }
       }
+      // v1.3.5: only adapters whose defaults declare a workspace (Open Design)
+      // advertise the field, so the management page renders it exactly there.
+      const supportsWorkspaceId = Object.prototype.hasOwnProperty.call(PROVIDER_DEFAULTS[id], 'workspaceId')
       providers.push({
         providerId: id,
         label: provider.label,
@@ -647,6 +652,9 @@ export function apply(ctx, rawConfig) {
         apiKeyRef: provider.apiKeyRef ?? '',
         baseURL: provider.baseURL ?? '',
         consoleUrl: provider.consoleUrl ?? '',
+        ...(supportsWorkspaceId
+          ? { workspaceId: typeof provider.workspaceId === 'string' ? provider.workspaceId : '' }
+          : {}),
         builtin: true,
         // Configured through DSH model settings: the management page should
         // inherit the key/base URL instead of asking for them again.
@@ -759,6 +767,17 @@ export function apply(ctx, rawConfig) {
     if (typeof update?.enabled === 'boolean') patch.enabled = update.enabled
     if (typeof update?.apiKey === 'string') patch.apiKey = update.apiKey.trim()
     if (typeof update?.apiKeyRef === 'string') patch.apiKeyRef = update.apiKeyRef.trim()
+    if (typeof update?.workspaceId === 'string') {
+      const workspaceId = update.workspaceId.trim()
+      if (workspaceId !== '' && !isWorkspaceId(workspaceId)) {
+        throw new UsageError(
+          'parse',
+          `provider workspaceId must be 1-${WORKSPACE_ID_MAX} identifier characters (letters, digits, . _ : @ -)`,
+          { retryable: false },
+        )
+      }
+      patch.workspaceId = workspaceId
+    }
     if (typeof update?.baseURL === 'string') {
       const rawBaseURL = update.baseURL.trim()
       patch.baseURL = rawBaseURL === '' ? '' : sanitizeUsageBaseURL(rawBaseURL)
@@ -1019,14 +1038,17 @@ export function apply(ctx, rawConfig) {
       if (workspaceId === '') {
         throw new UsageError(
           'missing-key',
-          'OpenDesign quota needs a workspace id (providers.open-design.workspaceId or OPENDESIGN_WORKSPACE_ID)',
+          'OpenDesign quota needs a workspace id: set it on the plugin management page (open-design → 工作区 ID), ' +
+            'in providers.open-design.workspaceId, or in OPENDESIGN_WORKSPACE_ID',
           { retryable: false },
         )
       }
       if (controlKey === '') {
-        throw new UsageError('missing-key', `OpenDesign quota needs a Control Key (${refs.join(' / ')})`, {
-          retryable: false,
-        })
+        throw new UsageError(
+          'missing-key',
+          `OpenDesign quota needs a Control Key (${refs.join(' / ')}); the Cloud API Keys inference key cannot read billing`,
+          { retryable: false },
+        )
       }
       provider = { ...provider, workspaceId, controlKey }
       keyInfo = { ref: controlRef, source: controlSource, detail: controlDetail }

package/lib/provider-store.mjs

@@ -134,6 +134,18 @@ export function sanitizeSettings(value) {
   }
 }
 
+/** The longest workspace id the management page accepts (identifiers are short). */
+export const WORKSPACE_ID_MAX = 120
+
+/**
+ * Whether a typed workspace id is safe to persist and interpolate into an API
+ * path: opaque identifier characters only (uuid / slug shaped).
+ */
+export function isWorkspaceId(value) {
+  return typeof value === 'string' && value.trim() !== '' && value.trim().length <= WORKSPACE_ID_MAX
+    && /^[A-Za-z0-9._:@-]+$/.test(value.trim())
+}
+
 /** Only the fields the management page may set, with type guards. */
 export function sanitizeOverride(value) {
   const out = {}
@@ -148,6 +160,9 @@ export function sanitizeOverride(value) {
   for (const key of ['baseURL', 'consoleUrl', 'usagePath', 'balancePath', 'creditsPath', 'subscriptionsPath', 'whoamiPath']) {
     if (typeof source[key] === 'string' && source[key].trim() !== '') out[key] = source[key].trim()
   }
+  // v1.3.5: Open Design's read-only billing API is workspace-scoped, so the
+  // management page persists the workspace id here (never a secret).
+  if (isWorkspaceId(source.workspaceId)) out.workspaceId = source.workspaceId.trim()
   return out
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tokenlens",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "type": "module",
   "description": "dsh-TokenLens (词元透镜) — provider-aware plan capacity plus local token statistics (today/7d/30d/all-time, by harness/provider/model/workspace) for DSH.",
   "license": "MIT",