dsh-workspace-api-key 0.2.17 → 0.3.0

package/README.md

@@ -25,10 +25,20 @@ session key  →  workspace key  →  system default
 - **Takes over the official search key field, once there is a key to put there** — on startup, while the new Web Search API is on, the plugin points the official `web-deepseek-api` / `web-search-deepseek` entry at `DEEPSEEK_API_KEY_SEARCH` (only that `apiKeyEnv` pointer, never a key value). The `设置 → 插件 → 网页搜索` field then edits the same search key this panel does, so it can no longer overwrite your chat key, and there is no second place where a search key can hide. Until you save a search key, the official entry keeps pointing at the chat key, so upgrading never breaks `web_search`; the panel says so instead of failing silently.
 - **A search switch per workspace** — every workspace row carries a `同步搜索 API` checkbox. Ticked, the `web_search` / `web_fetch` calls made by sessions in that directory use the key they would use for chat (`session → workspace → system default`); unticked, they keep the key the official 设置 → 插件 → 网页搜索 page manages. A session with its own key always wins, so "sync on, session configured separately" spends the session key, not the search key.
 - **Search warnings that arrive before the failure** — when a search key is configured but `启用新版 Web 搜索 API` is off, or when the new API is on but its key ref is empty, the panel shows a warning banner and the entering-session overlay says it too, in one line you can act on. The overlay stays quiet about search problems when the search provider is not the one in use.
+- *(The four search features above apply to older hosts only. DSH >= `0.2.2-rc.2` replaced them with a `计费方式` (billing mode) model; the old fields no longer take effect. See "Host compatibility" below for the new behaviour.)*
 - **A usage guide** — `使用说明` at the top of the panel recommends two keys: a chat default (`default`) and a search default (`search-default`), so the two budgets stay separate; it also draws the cascade and lists the situations that trigger a warning.
 - **A way back from Settings** — Settings → API Key 分配 keeps an "open the panel" button and explains the overflow-menu and reload routes, so an unpinned sidebar icon is never a dead end.
 - **Language-aware UI** — the panel follows the web GUI language from `@deepseek-ai/dsh-client-locale`: English when the GUI is English, Chinese when it is Chinese. Answers produced by the host half (connection-test details, search warnings) are translated in the browser half, so the panel does not mix languages.
 
+## Host compatibility (0.3.0+)
+
+The plugin switches on **host capability**, not on a parsed version: if the `web-deepseek-api` settings row contains `searchBilling` / `fetchBilling`, the host is the new one (DSH >= `0.2.2-rc.2`); otherwise the old behaviour applies.
+
+- **New host**: the main panel keeps a single "搜索与获取" card that explains the official settings page owns the search key, shows the current search/fetch billing mode, and offers an "打开官方搜索设置" button. The old "搜索默认 key" card, the "同步搜索 API" switch, the effective-search-key hint, and all three search warnings are hidden — `apiKeyEnv` no longer takes effect on this host, so showing them would only invite misconfiguration. With "DeepSeek API Key" billing, search resolves `DEEPSEEK_API_KEY` and therefore follows the session → workspace → default cascade automatically; with "已登录的 DeepSeek 账号" billing it uses the account token, which the plugin cannot override, and the card says so.
+- **Old host**: the 0.2.x behaviour is unchanged (search default key, `apiKeyEnv` takeover, per-workspace sync switch, search warnings).
+- **Host version**: `hostVersion` in `/wsk-api/state` is best-effort — the plugin reads the `version` of a resolvable `@deepseek-ai/dsh` package.json; the desktop host is packed inside app.asar, so when it cannot be resolved the Settings card shows an unknown version. Capability detection, not the version string, drives behaviour.
+- **Experimental "unified search key"** (Settings → API Key 分配 only, never in the main panel): when enabled, the plugin points the official `searchApiKeyEnv` / `fetchApiKeyEnv` at `DEEPSEEK_API_KEY_SEARCH` and stores that one key, so every session and workspace uses it for `web_search` / `web_fetch` (ahead of session/workspace keys); disabling clears both fields and returns to the official billing mode. It requires the new host — an old host answers the request with 400.
+
 ## How it works
 
 Host half (`lib/index.js`):
@@ -38,7 +48,7 @@ Host half (`lib/index.js`):
 - matches that directory against `workspaceRegistry.list()` after normalizing both sides (absolute, trailing separator removed, lower-cased on Windows);
 - derives a stable ref per level — `DEEPSEEK_API_KEY_WS_<first 16 hex chars of sha1(normalized path), upper-cased>` for a workspace and `DEEPSEEK_API_KEY_SS_<first 16 hex chars of sha1(session id), upper-cased>` for a session (a session id contains `-` and cannot be a ref name) — writes the key through the credentials service, and serves that ref's value;
 - rewrites only refs a provider actually reads: the default ref, every adapter's configured `apiKeyEnv`, and its own generated refs. Every other ref passes through untouched;
-- tells search credentials apart from chat credentials **by ref, not by wrapping the web seam**. The official new Search/Fetch API resolves its key under `web-deepseek-api.apiKeyEnv`, which this plugin points at its own `DEEPSEEK_API_KEY_SEARCH` at startup and whenever the panel saves a search key, so a search resolve is recognisable from the ref alone: chat never asks for it. Earlier 0.2.x releases wrapped `ctx.web.search` / `ctx.web.fetch` in an `AsyncLocalStorage` scope instead; that patch is gone from 0.2.15 on, because a wrapper around the web seam can leave `web_search` / `web_fetch` waiting until their 30/60 s tool budget expires (it hangs even for addresses that fail instantly, e.g. `http://127.0.0.1:1/`). The rule itself is unchanged: a session's own key first (always), then, if the workspace ticked `同步搜索 API`, the workspace key and then the system default, otherwise the panel's search default ref when it holds one, and only then the ref the search plugin configured. The legacy Messages-based search keeps the plain chat cascade, because that route *is* a messages request;
+- tells search credentials apart from chat credentials **by ref, not by wrapping the web seam**. The official new Search/Fetch API resolves its key under `web-deepseek-api.apiKeyEnv`, which this plugin points at its own `DEEPSEEK_API_KEY_SEARCH` at startup and whenever the panel saves a search key, so a search resolve is recognisable from the ref alone: chat never asks for it. Earlier 0.2.x releases wrapped `ctx.web.search` / `ctx.web.fetch` in an `AsyncLocalStorage` scope instead; that patch is gone from 0.2.15 on, because a wrapper around the web seam can leave `web_search` / `web_fetch` waiting until their 30/60 s tool budget expires (it hangs even for addresses that fail instantly, e.g. `http://127.0.0.1:1/`). The rule itself is unchanged: a session's own key first (always), then, if the workspace ticked `同步搜索 API`, the workspace key and then the system default, otherwise the panel's search default ref when it holds one, and only then the ref the search plugin configured. The legacy Messages-based search keeps the plain chat cascade, because that route *is* a messages request. On the new billing model the plugin no longer writes `apiKeyEnv` (a dead field there): `api-key` billing resolves `DEEPSEEK_API_KEY`, so search follows the chat cascade; `account` billing uses the account token, which the plugin cannot override, so it only warns; the experimental unified key points `searchApiKeyEnv` at the plugin-owned `DEEPSEEK_API_KEY_SEARCH` and, recognised by ref, wins first;
 - builds the session list from the `sessionController` service (`list()`, unwrapping its `{items: […]}` envelope) and falls back to the live `sessions` service (`ctx.get('sessions').list()`), so the panel still has sessions when the controller is missing, throws, or returns an empty list. It hides the two kinds of session the sidebar hides: subagent sessions (`origin: 'subagent'`, or a `parentSession`) and *blank* sessions (created but never prompted — the sidebar shows only the one currently open). Without those two filters one workspace with a single real session listed thirteen;
 - reports its own version and a session probe (`available`, `shape`, `source`, `count`, `withoutCwd`, `subagents`, `samples`, `error`, plus sample workspace paths) in `/wsk-api/state`, so the panel can say *why* no sessions are listed: a stale host half (only a page reload instead of an app restart), a missing `sessionController`, a throwing `list()`, an unexpected envelope shape, or a `cwd` that matches no workspace path;
 - lists a directory that is not a registered workspace only if the sidebar would show it. It cannot decide that itself, because "only the currently open blank session counts" is knowledge the browser side holds (`retainedBy.mainView`), so it sends every such directory plus a `blank` flag per session and a `hiddenBlankDirs` list naming the ones whose sessions are all blank — the browser half applies the same verdict the sidebar does;
@@ -59,6 +69,7 @@ The browser half (`lib/client.js`) registers into the `sidebar.panellist` slot (
 | POST | `/wsk-api/test` | `{scope, path \| sessionId \| ref}` (or `{key}`) runs one real request and returns the verdict; `invalid` marks the flag, `ok` clears it |
 | POST | `/wsk-api/clear-flag` | `{ref}` or a target drops the invalid/quota flag |
 | POST | `/wsk-api/search-sync` | `{path, enabled}` turns a workspace's `同步搜索 API` switch on or off |
+| POST | `/wsk-api/search-unified` | `{enabled, key?}` — experimental: pins search and fetch for every session/workspace to one key; enabling writes `searchApiKeyEnv` / `fetchApiKeyEnv`, disabling clears them |
 
 Only loopback callers are accepted (`127.0.0.1`, `::1`, `::ffff:127.0.0.1`) with a same-origin or absent `Origin`. No response ever contains a plaintext key, only a mask.
 
@@ -81,7 +92,7 @@ The command forwards its arguments to pnpm inside the profile directory, so the
 pnpm add dsh-workspace-api-key          # or: npm install dsh-workspace-api-key
 ```
 
-Pin a version with `dsh-workspace-api-key@0.2.17`, or install straight from the repository with `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key` (a git-hosted plugin is built from source on install).
+Pin a version with `dsh-workspace-api-key@0.3.0`, or install straight from the repository with `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key` (a git-hosted plugin is built from source on install).
 
 Then add `"dsh-workspace-api-key"` to `dsh.profile.bundles` in that profile's `package.json` and restart DSH. For local development, use a link instead:
 
@@ -92,19 +103,20 @@ Then add `"dsh-workspace-api-key"` to `dsh.profile.bundles` in that profile's `p
 ## Tests
 
 ```sh
-node test/host.test.mjs     # 177 assertions
-node test/client.test.mjs   # 180 assertions
+node test/host.test.mjs           # 196 assertions
+node test/client.test.mjs         # 180 assertions
+node test/client-billing.test.mjs # 8 assertions (new billing model)
 ```
 
-Neither suite needs a running DSH process. The host suite drives `apply()` against a mock context (fake `credentials`, `workspaceRegistry`, `agents`, `sessionController`, `sessions`, `webServer`, stubbed `fetch`) and covers ref derivation, the session → workspace → default cascade, workspace matching, redirecting a second adapter's `apiKeyEnv`, clearing back to the default, 401/402/429/5xx classification, the loopback and origin checks, state persistence, the session probe including the `{items}` envelope, the live-session fallback, and subagent and blank sessions being hidden, and the search scope with a stand-in `web` service and a stand-in settings service: the legacy route keeping the chat cascade, the new provider keeping its own key, the workspace switch taking over, a session key outranking both, the panel's own search default key being used and cleared, the three search warnings, and the search connection test. The client suite loads `lib/client.js` through a minimal `window.__ModuleLoader__` plus a small React runtime, renders the panel and the overlay, and asserts slot registration, the first render, session expand/collapse, per-session saving and testing, sessions recovered from the browser-side store when the host has none (with `displayTitle` winning and subagent sessions hidden), the ungrouped-directory card, the stale and mismatch prompts, the "go configure" hand-off, graceful degradation without a session list, back-navigation when `ctx.get('layout')` only becomes available after the plugin was applied, and the search UI: the switch on every workspace row, the `/wsk-api/search-sync` call it makes, the warning banner, and the usage dialog.
+Neither main suite needs a running DSH process. The host suite drives `apply()` against a mock context (fake `credentials`, `workspaceRegistry`, `agents`, `sessionController`, `sessions`, `webServer`, stubbed `fetch`) and covers ref derivation, the session → workspace → default cascade, workspace matching, redirecting a second adapter's `apiKeyEnv`, clearing back to the default, 401/402/429/5xx classification, the loopback and origin checks, state persistence, the session probe including the `{items}` envelope, the live-session fallback, and subagent and blank sessions being hidden, and the search scope with a stand-in `web` service and a stand-in settings service: the legacy route keeping the chat cascade, the new provider keeping its own key, the workspace switch taking over, a session key outranking both, the panel's own search default key being used and cleared, the three search warnings, and the search connection test. The client suite loads `lib/client.js` through a minimal `window.__ModuleLoader__` plus a small React runtime, renders the panel and the overlay, and asserts slot registration, the first render, session expand/collapse, per-session saving and testing, sessions recovered from the browser-side store when the host has none (with `displayTitle` winning and subagent sessions hidden), the ungrouped-directory card, the stale and mismatch prompts, the "go configure" hand-off, graceful degradation without a session list, back-navigation when `ctx.get('layout')` only becomes available after the plugin was applied, and the search UI: the switch on every workspace row, the `/wsk-api/search-sync` call it makes, the warning banner, and the usage dialog. `client-billing.test.mjs` covers the new billing model — no legacy search UI, the official-settings entry, and the unified-key notice — and `client-i18n.test.mjs` checks the English dictionary (7 assertions).
 
 ## Requirements and limits
 
-- Verified against DSH Desktop 2.0.17 with `@deepseek-ai/dsh*` 0.2.0-rc.2 and `@deepseek-ai/cordis` 4.0.4. It has no runtime dependency and imports no `@deepseek-ai/*` package — only the host services (`credentials`, `workspaceRegistry`, `agents`, `sessionController`, `webServer`, `llm`, `settings`) and Node built-ins.
+- Verified against DSH Desktop with `@deepseek-ai/dsh*` 0.2.2-rc.2 and `@deepseek-ai/cordis` 4.0.4. It has no runtime dependency and imports no `@deepseek-ai/*` package — only the host services (`credentials`, `workspaceRegistry`, `agents`, `sessionController`, `webServer`, `llm`, `settings`) and Node built-ins.
 - One key per level: a session has a single key whichever provider route reads it, and a key recorded for one provider is reported as a mismatch when the session runs on another. Model changes inside one provider are not treated as a mismatch, because a DeepSeek key is account-wide.
 - Sessions are matched to a workspace by their directory (`cwd`). The host's own `list()` skips stored sessions that never got a `cwd`, and the live-session fallback only knows sessions that are currently loaded, so the panel may show fewer sessions than the sidebar. Sessions visible only in the browser-side store carry no `cwd` of their own beyond the one the sidebar knows.
 - The connection test speaks the Anthropic Messages shape (`POST <baseURL>/messages` with `x-api-key` and `anthropic-version: 2023-06-01`), which is what the DeepSeek route uses. A provider that speaks a different protocol can still have keys bound per level, but the test may report a failure for a key that works.
-- Search support needs a DSH build that ships the official Search/Fetch API (`web-deepseek-api`, the 设置 → 插件 → 网页搜索 page with `启用新版 Web 搜索 API`). On a build without it the plugin simply never sees a search request: the switch stays visible, and the panel reports the legacy Messages channel instead of guessing.
+- Search support needs a DSH build that ships the official Search/Fetch API (`web-deepseek-api`, the 设置 → 插件 → 网页搜索 page with `启用新版 Web 搜索 API`). On a build without it the plugin simply never sees a search request: the switch stays visible, and the panel reports the legacy Messages channel instead of guessing. On the new billing model, `account` billing uses the account token and cannot be overridden by the plugin — it can only be reported; choose "DeepSeek API Key" billing to follow session/workspace keys, or use the experimental unified search key in Settings.
 - Keys are stored through the credentials service in `$DSH_HOME/.credentials.yaml` under `refs:`, in plaintext, exactly like the default key. They are not written into session logs, the plugin's state file, or the plugin directory.
 - Matching is textual after normalization. If a session's `cwd` is a symlink or junction to a registered workspace path, it will not match and the level above is used.
 - Uninstalling the plugin leaves the generated `*_WS_*` / `*_SS_*` refs and `DEEPSEEK_API_KEY_SEARCH` in the credentials file; remove them from the Models page.

package/README.zh.md

@@ -25,10 +25,20 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 - **接管官方搜索 key 设置（先有 key 才接管）** —— 启动时若已启用新版 Web 搜索 API，插件把官方 `web-deepseek-api` / `web-search-deepseek` 条目的 `apiKeyEnv` 指到 `DEEPSEEK_API_KEY_SEARCH`（只改这一个指向，永远不动 key 内容）。此后「设置 → 插件 → 网页搜索」里填的就是本面板这把搜索 key，既不会再顶掉聊天 key，也不存在第二处藏搜索 key 的地方。还没配搜索 key 时，官方条目继续指着聊天那把，所以升级不会让 `web_search` 直接失效，面板会如实提醒「搜索暂时和聊天共用一把 key」。
 - **每个工作区一个搜索开关** —— 每个工作区行上都有「同步搜索 API」复选框。勾选后，该目录下会话发出的 `web_search` / `web_fetch` 请求改用它们聊天时用的那把 key（会话 → 工作区 → 系统默认）；不勾选则继续用官方「设置 → 插件 → 网页搜索」里配置的那把 key。会话自己配了 key 时永远优先，所以「工作区同步、会话单独设置」花的是会话那把 key，而不是搜索默认 key。
 - **在失败之前就提醒的搜索告警** —— 配了搜索 key 但没打开「启用新版 Web 搜索 API」，或者新版 API 打开了但它的 key ref 是空的，面板会显示提醒条，点进会话时的覆盖层也会用一句可直接照做的话说明；当生效的搜索通道不是新版 API 时，覆盖层不会拿搜索问题打扰你。
+- *（上面四条搜索能力只适用于旧版宿主。DSH >= `0.2.2-rc.2` 把搜索/获取改成了「计费方式」，旧字段不再生效；新版宿主上的行为见「宿主版本兼容」。）*
 - **使用说明** —— 面板顶部有「使用说明」，推荐两把 key 分工：聊天默认用 `default`，搜索默认用 `search-default`，两份预算互不干扰；里面还画了层级，并列出了会触发提醒的几种情况。
 - **面板入口也能从设置里找回来** —— 「设置 → API Key 分配」里还有一个「打开 API Key 分配面板」按钮：侧栏图标被取消固定时，点它就能回到这里；那里也写明了「更多」菜单和刷新页面两条找回途径。
 - **界面跟随 DSH 语言** —— 面板跟随 `@deepseek-ai/dsh-client-locale`：Web 界面是英文时显示英文，是中文时保持中文；宿主半边返回的提示（连接测试详情、搜索提醒）也在浏览器半边翻译，界面不会中英混排。
 
+## 宿主版本兼容（0.3.0 起）
+
+插件按**宿主能力**切换界面，不猜版本号：`web-deepseek-api` 的设置里出现 `searchBilling` / `fetchBilling` 字段，就按新版宿主（DSH >= `0.2.2-rc.2`）处理，否则按旧版处理。
+
+- **新版宿主**：主面板只保留一张「搜索与获取」卡片，说明官方设置页已经接管搜索 key，显示当前的搜索/获取计费方式，并提供「打开官方搜索设置」按钮。旧版的「搜索默认 key」卡片、「同步搜索 API」开关、「搜索生效 key」提示和三类搜索告警全部隐藏——`apiKeyEnv` 在新版里已不再生效，继续展示只会让人误配。计费方式为「DeepSeek API Key」时，搜索解析的是 `DEEPSEEK_API_KEY`，因此会自动跟随上面讲的会话 → 工作区 → 系统默认级联；计费方式为「已登录的 DeepSeek 账号」时走账号令牌，插件无法覆盖，卡片会如实提示。
+- **旧版宿主**：0.2.x 的行为原样保留（搜索默认 key、接管 `apiKeyEnv`、工作区同步开关、搜索告警）。
+- **宿主版本**：`/wsk-api/state` 里的 `hostVersion` 是尽力而为读出来的——从能解析到的 `@deepseek-ai/dsh` 的 `package.json` 取 `version`；桌面版宿主打在 asar 里读不到时返回空，设置页显示「未知」。所以兼容性判断始终以设置字段为准，版本号只用于展示。
+- **实验性「统一搜索 key」**（只在「设置 → API Key 分配」，不放进主面板）：开启后插件把官方 `searchApiKeyEnv` / `fetchApiKeyEnv` 指向 `DEEPSEEK_API_KEY_SEARCH`，并把这把 key 存进凭据服务，于是所有会话、工作区的 `web_search` / `web_fetch` 都用它（优先于会话/工作区 key）；关闭时清空这两个字段，回到官方计费方式。它需要新版宿主，旧版宿主调用会返回 400。
+
 ## 实现方式
 
 宿主半边（`lib/index.js`）：
@@ -38,7 +48,7 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 - 把该目录与 `workspaceRegistry.list()` 做规范化后比对（绝对化、去掉尾部分隔符、Windows 折大小写）；
 - 由每一层派生出稳定的 ref —— 工作区是 `DEEPSEEK_API_KEY_WS_<sha1(规范化路径) 前 16 位十六进制大写>`，会话是 `DEEPSEEK_API_KEY_SS_<sha1(会话 id) 前 16 位十六进制大写>`（会话 id 含 `-`，不能直接当 ref 名）——通过凭据服务写入 key，并返回这个 ref 的值；
 - 只改写 provider 真正会读的 ref：默认 ref、每个适配器配置的 `apiKeyEnv`，以及插件自己生成的 ref；其它 ref 原样透传；
-- 把「搜索请求」和「聊天请求」分开——**按 ref 分辨，而不是包住 web 服务**。官方新版 Search/Fetch API 自己解析 key，用的是 `web-deepseek-api.apiKeyEnv` 指向的凭据；本插件在启动时（以及面板每次保存搜索 key 时）把它指到插件自有的 `DEEPSEEK_API_KEY_SEARCH`，于是只看 ref 就能认出「这是搜索在要 key」：聊天永远不会解析这个 ref。0.2.15 起删掉了原先「把 `ctx.web.search` / `ctx.web.fetch` 包进 `AsyncLocalStorage`」的做法——包住 web 服务可能让 `web_search` / `web_fetch` 一直挂到工具 30/60 秒预算耗尽（连 `http://127.0.0.1:1/` 这种必然立刻失败的地址也一样挂）。规则本身没变：先看会话自己的 key（永远最优先），再看该工作区有没有勾「同步搜索 API」，勾了就依次用工作区 key、系统默认 key；没勾时先用插件面板自己持有的搜索默认 ref（若配了），最后才用搜索插件配置的那个 ref。旧版基于 Messages 的搜索仍然走原来的聊天层级，因为那条路线本身就是一次 messages 请求；
+- 把「搜索请求」和「聊天请求」分开——**按 ref 分辨，而不是包住 web 服务**。官方新版 Search/Fetch API 自己解析 key，用的是 `web-deepseek-api.apiKeyEnv` 指向的凭据；本插件在启动时（以及面板每次保存搜索 key 时）把它指到插件自有的 `DEEPSEEK_API_KEY_SEARCH`，于是只看 ref 就能认出「这是搜索在要 key」：聊天永远不会解析这个 ref。0.2.15 起删掉了原先「把 `ctx.web.search` / `ctx.web.fetch` 包进 `AsyncLocalStorage`」的做法——包住 web 服务可能让 `web_search` / `web_fetch` 一直挂到工具 30/60 秒预算耗尽（连 `http://127.0.0.1:1/` 这种必然立刻失败的地址也一样挂）。规则本身没变：先看会话自己的 key（永远最优先），再看该工作区有没有勾「同步搜索 API」，勾了就依次用工作区 key、系统默认 key；没勾时先用插件面板自己持有的搜索默认 ref（若配了），最后才用搜索插件配置的那个 ref。旧版基于 Messages 的搜索仍然走原来的聊天层级，因为那条路线本身就是一次 messages 请求。新版计费模型下不再写 `apiKeyEnv`（那是死字段）：`api-key` 计费时搜索解析 `DEEPSEEK_API_KEY`，自然沿着聊天级联走；`account` 计费走账号令牌，插件覆盖不了，只做提示；实验性统一 key 则把 `searchApiKeyEnv` 指到插件自有的 `DEEPSEEK_API_KEY_SEARCH`，并按 ref 分辨、优先返回这把 key；
 - 会话列表来自 `sessionController` 服务（`list()`，会拆开它 `{items: […]}` 的信封），控件缺失 / 抛错 / 列表为空时再退到宿主 live 会话服务（`ctx.get('sessions').list()`），所以那种情况下面板仍能列出会话；侧栏藏起来的两种会话这里也藏：子代理会话（`origin: 'subagent'` 或带 `parentSession`）和**空会话**（建了但一句话都没发过，侧栏只显示当前开着的那个）。两种都不过滤的话，一个只有 1 个真实会话的工作区会列出 13 个；
 - 不是注册工作区的目录，只有侧栏真的会显示它才会被列出来。这件事宿主判不了：「空会话里只有当前开着的那个算数」是浏览器端才知道的事（`retainedBy.mainView`），所以宿主把这种目录连同每个会话的 `blank` 标记一起发出去，并用 `hiddenBlankDirs` 点名「里面全是空会话」的目录，由浏览器半边套用与侧栏一致的判据；
 - `/wsk-api/state` 会带上插件自身版本与会话探针（`available`、`shape`、`source`、`count`、`withoutCwd`、`subagents`、`samples`、`error`，以及工作区路径样本），面板据此说明**为什么**没有列出会话：宿主半边是旧版本（只刷新了页面而没重启应用）、没有 `sessionController`、`list()` 抛错、信封形状不认识，还是会话的 `cwd` 与任何工作区路径都对不上；
@@ -59,6 +69,7 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 | POST | `/wsk-api/test` | `{scope, path \| sessionId \| ref}`（或 `{key}`）真发一次请求并返回判定；`invalid` 打标记，`ok` 清标记 |
 | POST | `/wsk-api/clear-flag` | `{ref}` 或一个目标，清掉失效/配额标记 |
 | POST | `/wsk-api/search-sync` | `{path, enabled}` —— 打开或关闭某个工作区的「同步搜索 API」 |
+| POST | `/wsk-api/search-unified` | `{enabled, key?}` —— 实验性：把所有会话/工作区的搜索与获取固定到同一把 key；开启时写 `searchApiKeyEnv` / `fetchApiKeyEnv`，关闭时清空 |
 
 只接受本机回环调用（`127.0.0.1`、`::1`、`::ffff:127.0.0.1`），且 `Origin` 必须同源或缺失。任何响应都不会包含明文 key，只有掩码。
 
@@ -81,7 +92,7 @@ dsh plugin --profile web add dsh-workspace-api-key
 pnpm add dsh-workspace-api-key          # 或者：npm install dsh-workspace-api-key
 ```
 
-锁版本用 `dsh-workspace-api-key@0.2.17`；直接从仓库装则用 `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key`（git 来源的插件会在安装时现场构建）。
+锁版本用 `dsh-workspace-api-key@0.3.0`；直接从仓库装则用 `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key`（git 来源的插件会在安装时现场构建）。
 
 然后把 `"dsh-workspace-api-key"` 加进该 profile `package.json` 的 `dsh.profile.bundles`，重启 DSH。本地开发用 link 代替：
 
@@ -92,16 +103,17 @@ pnpm add dsh-workspace-api-key          # 或者：npm install dsh-workspace-api
 ## 测试
 
 ```sh
-node test/host.test.mjs     # 177 条断言
-node test/client.test.mjs   # 180 条断言
+node test/host.test.mjs           # 196 条断言
+node test/client.test.mjs         # 180 条断言
+node test/client-billing.test.mjs # 8 条断言（新版计费模型）
 ```
 
-两个套件都不需要启动 DSH。宿主套件用一个假 ctx（假的 `credentials`、`workspaceRegistry`、`agents`、`sessionController`、`sessions`、`webServer`，以及打桩的 `fetch`）驱动 `apply()`，覆盖 ref 派生、会话→工作区→默认的级联、工作区匹配、把第二个适配器的 `apiKeyEnv` 一起重定向、清回默认、401/402/429/5xx 的判定、回环与来源校验、状态落盘，以及会话探针（含 `{items}` 信封与 live 兜底）。浏览器套件通过一个极小的 `window.__ModuleLoader__` 与自制 React 运行时加载 `lib/client.js`，渲染出面板与覆盖层，断言槽注册、首屏渲染、会话折叠/展开、会话级保存与测试、宿主列不出会话时从浏览器端存储恢复会话（标题取 `displayTitle`、隐藏子代理会话与空会话、浏览器端只认识一部分会话时不挤掉宿主行）、会话列表服务晚于插件提供时的重试、未分组目录卡片、失效与不匹配提醒、「去配置」的交接、没有会话列表时的降级，以及 `ctx.get('layout')` 在插件 apply 之后才可用时返回键仍然有效。宿主套件还带一个假的 `web` 服务与假的设置服务，验证搜索作用域：旧通道沿用聊天层级、新版通道用它自己的 key、工作区开关接管、会话 key 压过两者、面板自己的搜索默认 key 生效与清除、三类搜索提醒，以及搜索连接测试。浏览器套件覆盖搜索相关界面：每个工作区行的「同步搜索 API」复选框、它发出的 `/wsk-api/search-sync`、提醒条与「使用说明」弹窗。
+两个主套件都不需要启动 DSH。宿主套件用一个假 ctx（假的 `credentials`、`workspaceRegistry`、`agents`、`sessionController`、`sessions`、`webServer`，以及打桩的 `fetch`）驱动 `apply()`，覆盖 ref 派生、会话→工作区→默认的级联、工作区匹配、把第二个适配器的 `apiKeyEnv` 一起重定向、清回默认、401/402/429/5xx 的判定、回环与来源校验、状态落盘，以及会话探针（含 `{items}` 信封与 live 兜底）。浏览器套件通过一个极小的 `window.__ModuleLoader__` 与自制 React 运行时加载 `lib/client.js`，渲染出面板与覆盖层，断言槽注册、首屏渲染、会话折叠/展开、会话级保存与测试、宿主列不出会话时从浏览器端存储恢复会话（标题取 `displayTitle`、隐藏子代理会话与空会话、浏览器端只认识一部分会话时不挤掉宿主行）、会话列表服务晚于插件提供时的重试、未分组目录卡片、失效与不匹配提醒、「去配置」的交接、没有会话列表时的降级，以及 `ctx.get('layout')` 在插件 apply 之后才可用时返回键仍然有效。宿主套件还带一个假的 `web` 服务与假的设置服务，验证搜索作用域：旧通道沿用聊天层级、新版通道用它自己的 key、工作区开关接管、会话 key 压过两者、面板自己的搜索默认 key 生效与清除、三类搜索提醒，以及搜索连接测试。浏览器套件覆盖搜索相关界面：每个工作区行的「同步搜索 API」复选框、它发出的 `/wsk-api/search-sync`、提醒条与「使用说明」弹窗；`client-billing.test.mjs` 专门验证新版计费模型下面板不再出现旧搜索 UI、只给官方设置入口，以及统一搜索 key 的提示。i18n 套件（`client-i18n.test.mjs`，7 条断言）验证英文字典完整。
 
 ## 要求与限制
 
-- 已在 DSH Desktop 2.0.17（`@deepseek-ai/dsh*` 0.2.0-rc.2、`@deepseek-ai/cordis` 4.0.4）上验证。插件没有运行时依赖，也不 import 任何 `@deepseek-ai/*` 包，只用宿主服务（`credentials`、`workspaceRegistry`、`agents`、`sessionController`、`webServer`、`llm`、`settings`）与 Node 内置模块。
-- 搜索功能依赖自带官方 Search/Fetch API 的 DSH（`web-deepseek-api`，即「设置 → 插件 → 网页搜索」里那个「启用新版 Web 搜索 API」）。没有这个能力的版本上，插件根本收不到搜索请求：开关照旧显示，面板会如实报告当前是旧版 Messages 通道，而不是瞎猜。
+- 已在 DSH Desktop（`@deepseek-ai/dsh*` 0.2.2-rc.2、`@deepseek-ai/cordis` 4.0.4）上验证。插件没有运行时依赖，也不 import 任何 `@deepseek-ai/*` 包，只用宿主服务（`credentials`、`workspaceRegistry`、`agents`、`sessionController`、`webServer`、`llm`、`settings`）与 Node 内置模块。
+- 搜索功能依赖自带官方 Search/Fetch API 的 DSH（`web-deepseek-api`，即「设置 → 插件 → 网页搜索」里那个「启用新版 Web 搜索 API」）。没有这个能力的版本上，插件根本收不到搜索请求：开关照旧显示，面板会如实报告当前是旧版 Messages 通道，而不是瞎猜。新版宿主改用「计费方式」后，`account` 计费走账号令牌，插件无法覆盖，只能提示；需要按会话/工作区 key 计费时请把计费方式设为「DeepSeek API Key」，或使用设置页里的实验性「统一搜索 key」。
 - 每一层只有一把 key：一个会话无论被哪个 provider 路由读取，用的都是同一把 key；key 记下的服务商与会话当前服务商不一致时会被报为「不匹配」，但同一服务商内换模型不算不匹配，因为 DeepSeek key 是账号级的。
 - 会话按目录（`cwd`）归入工作区。宿主自己的 `list()` 会跳过从未存过 `cwd` 的历史会话，而 live 兜底只认识当前装载中的会话，所以面板列出的会话可能比侧栏少；只在浏览器端存储里可见的会话，除了侧栏知道的那个 `cwd` 之外没有别的路径信息。
 - 「测试连接」说的是 Anthropic Messages 协议（`POST <baseURL>/messages` 带 `x-api-key` 与 `anthropic-version: 2023-06-01`），也就是 DeepSeek 路由用的协议；换了别的协议的 provider 一样可以按层绑 key，只是测试可能把有效的 key 报成失败。

package/lib/client.js

@@ -167,7 +167,37 @@ window.__ModuleLoader__.load({
   "再或者按 Ctrl+R 刷新页面 —— 面板固定状态只存在内存里，刷新就会恢复默认。": "or press Ctrl+R to reload the page — the pin state lives only in memory, so a reload restores the defaults.",
   "打开 API Key 分配面板": "Open the API Key Allocation panel",
   "已切到该面板：如果它还是没出现，说明面板正在加载，稍等一下。": "Switched to that panel: if it has not appeared yet, it is still loading — give it a moment.",
-  "这里同时管着每个工作区 / 会话的 key 与搜索通道；面板右上角的「使用说明」有完整的优先级说明。": "This panel manages the key and search channel of every workspace and session; the \"How to use\" button in its header explains the full precedence order."
+  "这里同时管着每个工作区 / 会话的 key 与搜索通道；面板右上角的「使用说明」有完整的优先级说明。": "This panel manages the key and search channel of every workspace and session; the \"How to use\" button in its header explains the full precedence order.",
+  "搜索与获取": "Search & fetch",
+  "新版宿主用「计费方式」管理网页搜索 / 网页获取：key 由官方设置页决定，本面板不再接管，也不再显示旧的搜索 key。": "The newer host manages web search and fetch by billing mode: the key is decided on the official settings page, so this panel no longer takes over search keys or shows the old search key.",
+  "实验性「统一搜索 key」已开启：所有会话 / 工作区搜索都使用同一把 key。可在「设置 → API Key 分配」里更换或关闭。": "The experimental unified search key is on: every session and workspace searches with the same key. Change or disable it in Settings → API Key Allocation.",
+  "计费方式为「DeepSeek API Key」时，搜索会跟随当前会话 / 工作区的聊天 key；为「已登录的 DeepSeek 账号」时，搜索走账号令牌，插件无法覆盖。": "With billing set to \"DeepSeek API Key\", searches follow the current session/workspace chat key; with \"Signed-in DeepSeek account\", searches use the account token, which this plugin cannot override.",
+  "自动": "Automatic",
+  "已登录的 DeepSeek 账号": "Signed-in DeepSeek account",
+  "打开官方搜索设置": "Open official search settings",
+  "检测到的宿主版本：": "Detected host version: ",
+  "搜索 API（实验性）": "Search API (experimental)",
+  "新版宿主由官方「设置 → 插件 → 网页搜索」统一管理搜索/获取的计费方式。这里只保留一个实验开关：把所有会话的搜索强制指向插件持有的同一把 key，适合“一把搜索 key 走天下”。": "The newer host manages search/fetch billing on the official Settings → Plugins → Web Search page. Only one experimental switch remains here: force every session's searches to use a single key held by this plugin — handy for a single search key everywhere.",
+  "当前已启用：所有会话 / 工作区搜索都使用 DEEPSEEK_API_KEY_SEARCH 这一把 key，不再跟随各自的聊天 key。": "Currently on: every session and workspace searches with DEEPSEEK_API_KEY_SEARCH instead of its chat key.",
+  "粘贴新的搜索 key（sk-…）": "Paste a new search key (sk-…)",
+  "保存并继续使用": "Save and keep using",
+  "关闭统一搜索 key": "Disable unified search key",
+  "开启后，插件会把官方搜索配置的 key 指向自己持有的 ref，所有会话 / 工作区搜索都用这一把，不再跟随各自的聊天 key。关闭时会把官方配置清回默认计费方式。": "When enabled, the plugin points the official search key at its own ref, so every session and workspace searches with that single key instead of its chat key. Disabling clears the official setting back to the default billing mode.",
+  "粘贴搜索 key（sk-…）": "Paste a search key (sk-…)",
+  "开启": "Enable",
+  "已开启：所有会话/工作区共用这把搜索 key。": "Enabled: every session and workspace now shares this search key.",
+  "已关闭统一搜索 key，回到官方计费方式。": "Unified search key disabled; back to the official billing mode.",
+  "搜索 / 获取已交给官方设置": "Search & fetch are handled by the official settings",
+  "当前宿主的网页搜索与网页获取按「计费方式」选择用哪把 key，本插件不再接管搜索 key，也不显示旧的搜索配置。": "The current host picks the key for web search and fetch by billing mode; this plugin no longer takes over search keys or shows the old search configuration.",
+  "计费方式为「DeepSeek API Key」：搜索跟随当前会话 / 工作区的聊天 key，账单一起算。": "Billing \"DeepSeek API Key\": searches follow the current session/workspace chat key and share its bill.",
+  "计费方式为「已登录的 DeepSeek 账号」：搜索走账号令牌，插件无法覆盖。": "Billing \"Signed-in DeepSeek account\": searches use the account token, which this plugin cannot override.",
+  "「自动」：看当前会话走的是哪个模型路由，规则由宿主决定。": "\"Automatic\": follows the model route of the current session; the host decides the rules.",
+  "要改计费方式，点面板里的「打开官方搜索设置」，或手动到「设置 → 插件 → 网页搜索」。": "To change billing, press \"Open official search settings\" in the panel, or go to Settings → Plugins → Web Search manually.",
+  "实验性的「统一搜索 key」在「设置 → API Key 分配」页里，开启后所有会话搜索共用插件持有的一把 key。": "The experimental unified search key lives on the Settings → API Key Allocation page; when on, every session searches with one key held by the plugin.",
+  "聊天 key 的优先级": "Chat key precedence",
+  "会话单独配置的 key": "a key configured for the session",
+  "工作区专属 key": "a workspace-specific key",
+  "系统默认 key": "the system default key"
 }
 
     const EN_HOST = {
@@ -772,6 +802,61 @@ window.__ModuleLoader__.load({
 
     // ─────────────────────────────── 主页面 ───────────────────────────────
 
+    function billingText(value) {
+      switch (value) {
+        case 'account': return tr('已登录的 DeepSeek 账号')
+        case 'api-key': return tr('DeepSeek API Key')
+        default: return tr('自动')
+      }
+    }
+
+    /**
+     * 跳到官方「设置 → 插件 → 网页搜索」。
+     *
+     * 宿主没有给普通插件开放「把设置打开到某个 section」的 API（settings store 的
+     * openSection 只发给 settings.launcher），所以这里做尽力而为的点击导航：
+     * 打开设置 → 点「插件」→ 点「网页搜索」。任何一步失败，用户至少停在设置里。
+     */
+    function openOfficialSearchSettings() {
+      const findClickable = (root, pattern) => {
+        const nodes = root.querySelectorAll('button, a, [role="tab"], [role="button"], [role="menuitem"]')
+        for (const node of nodes) {
+          const text = (node.textContent ?? '').trim()
+          if (text !== '' && pattern.test(text)) {
+            node.click()
+            return true
+          }
+        }
+        return false
+      }
+      try {
+        if (document.querySelector('[data-shortcut-modal="settings"]') === null) {
+          const trigger = document.querySelector('button[aria-haspopup="dialog"]')
+          if (trigger !== null) trigger.click()
+          else window.dispatchEvent(new KeyboardEvent('keydown', { key: ',', code: 'Comma', ctrlKey: true, bubbles: true }))
+        }
+        let tries = 0
+        const timer = setInterval(() => {
+          tries += 1
+          const modal = document.querySelector('[data-shortcut-modal="settings"]')
+          const text = modal === null ? '' : (modal.textContent ?? '')
+          if (modal !== null && /插件|Plugins?/i.test(text)) {
+            if (findClickable(modal, /^插件$|^Plugins?$/i)) {
+              clearInterval(timer)
+              setTimeout(() => {
+                const again = document.querySelector('[data-shortcut-modal="settings"]')
+                if (again !== null) findClickable(again, /网页搜索|Web search/i)
+              }, 150)
+              return
+            }
+          }
+          if (tries > 40) clearInterval(timer)
+        }, 50)
+      } catch {
+        /* 尽力而为：至少把设置打开 */
+      }
+    }
+
     /**
      * 「设置 → API Key 分配」这一栏：侧栏图标没了也能从这里回到面板。
      *
@@ -783,6 +868,40 @@ window.__ModuleLoader__.load({
     function SettingsSection() {
       useI18n()
       const [opened, setOpened] = useState(false)
+      const [state, setState] = useState(null)
+      const [unifiedKey, setUnifiedKey] = useState('')
+      const [unifiedBusy, setUnifiedBusy] = useState(false)
+      const [unifiedNotice, setUnifiedNotice] = useState(null)
+      useEffect(() => {
+        let alive = true
+        api('/state').then((next) => { if (alive) setState(next) }).catch(() => {})
+        return () => { alive = false }
+      }, [])
+      const search = state?.search ?? null
+      const billing = search?.mode === 'billing'
+      const unified = search?.unified === true
+      const saveUnified = async (enabled) => {
+        setUnifiedBusy(true)
+        setUnifiedNotice(null)
+        try {
+          const next = await api('/search-unified', {
+            method: 'POST',
+            body: JSON.stringify({ enabled, key: unifiedKey }),
+          })
+          setState(next)
+          setUnifiedKey('')
+          setUnifiedNotice({
+            kind: 'ok',
+            text: enabled
+              ? '已开启：所有会话/工作区共用这把搜索 key。'
+              : '已关闭统一搜索 key，回到官方计费方式。',
+          })
+        } catch (err) {
+          setUnifiedNotice({ kind: 'err', text: String(err?.message ?? err) })
+        } finally {
+          setUnifiedBusy(false)
+        }
+      }
       const openPanel = () => {
         try {
           const layout = host.ctx === null ? undefined : host.ctx.get('layout')
@@ -811,7 +930,64 @@ window.__ModuleLoader__.load({
                 '已切到该面板：如果它还是没出现，说明面板正在加载，稍等一下。')
             : null,
           h('div', { className: 'wsk-hint', style: { marginTop: 10 } },
-            '这里同时管着每个工作区 / 会话的 key 与搜索通道；面板右上角的「使用说明」有完整的优先级说明。')))
+            '这里同时管着每个工作区 / 会话的 key 与搜索通道；面板右上角的「使用说明」有完整的优先级说明。')),
+        billing
+          ? h('div', { className: 'wsk-card' },
+              h('h4', null, '搜索 API（实验性）'),
+              h('div', { className: 'wsk-hint' },
+                '新版宿主由官方「设置 → 插件 → 网页搜索」统一管理搜索/获取的计费方式。这里只保留一个实验开关：把所有会话的搜索强制指向插件持有的同一把 key，适合“一把搜索 key 走天下”。'),
+              unified
+                ? h('div', null,
+                    h('div', { className: 'wsk-hint' },
+                      '当前已启用：所有会话 / 工作区搜索都使用 DEEPSEEK_API_KEY_SEARCH 这一把 key，不再跟随各自的聊天 key。'),
+                    h('div', { className: 'wsk-row', style: { marginTop: 8 } },
+                      h('input', {
+                        className: 'wsk-input',
+                        type: 'password',
+                        value: unifiedKey,
+                        placeholder: '粘贴新的搜索 key（sk-…）',
+                        onChange: (ev) => setUnifiedKey(ev.target.value),
+                      }),
+                      h('button', {
+                        type: 'button', className: 'wsk-btn primary',
+                        disabled: unifiedBusy || unifiedKey.trim() === '',
+                        onClick: () => saveUnified(true),
+                      }, '保存并继续使用'),
+                      h('button', {
+                        type: 'button', className: 'wsk-btn',
+                        disabled: unifiedBusy,
+                        onClick: () => saveUnified(false),
+                      }, '关闭统一搜索 key')))
+                : h('div', null,
+                    h('div', { className: 'wsk-hint' },
+                      '开启后，插件会把官方搜索配置的 key 指向自己持有的 ref，所有会话 / 工作区搜索都用这一把，不再跟随各自的聊天 key。关闭时会把官方配置清回默认计费方式。'),
+                    h('div', { className: 'wsk-row', style: { marginTop: 8 } },
+                      h('input', {
+                        className: 'wsk-input',
+                        type: 'password',
+                        value: unifiedKey,
+                        placeholder: '粘贴搜索 key（sk-…）',
+                        onChange: (ev) => setUnifiedKey(ev.target.value),
+                      }),
+                      h('button', {
+                        type: 'button', className: 'wsk-btn primary',
+                        disabled: unifiedBusy || unifiedKey.trim() === '',
+                        onClick: () => saveUnified(true),
+                      }, '开启'))),
+              unifiedNotice !== null
+                ? h('div', {
+                    className: 'wsk-hint',
+                    style: { marginTop: 8, color: unifiedNotice.kind === 'ok' ? undefined : '#e5484d' },
+                  }, unifiedNotice.text)
+                : null,
+              h('button', {
+                type: 'button', className: 'wsk-btn', style: { marginTop: 8 },
+                onClick: openOfficialSearchSettings,
+              }, '打开官方搜索设置'))
+          : null,
+        billing && typeof state?.hostVersion === 'string' && state.hostVersion !== ''
+          ? h('div', { className: 'wsk-hint' }, tf(`检测到的宿主版本：${state.hostVersion}`, `Detected host version: ${state.hostVersion}`))
+          : null)
     }
 
     function WorkspaceKeyPage(props) {
@@ -1321,7 +1497,7 @@ window.__ModuleLoader__.load({
                     }, verdictText(lastTest.verdict))
                   : null),
               h('div', { className: 'wsk-path' }, prettyPath(ws.path)),
-              ws.kind === 'orphan'
+              ws.kind === 'orphan' || searchInfo?.mode === 'billing'
                 ? null
                 : h('label', {
                     key: 'sync',
@@ -1342,7 +1518,7 @@ window.__ModuleLoader__.load({
                       : searchInfo?.defaultConfigured === true
                         ? '搜索用搜索默认 key'
                         : '搜索用搜索插件里的 key')),
-              ws.kind !== 'orphan' && searchInfo?.apiChannel === true && ws.searchKeyMasked !== undefined
+              ws.kind !== 'orphan' && searchInfo?.mode !== 'billing' && searchInfo?.apiChannel === true && ws.searchKeyMasked !== undefined
                 ? h('div', { key: 'sk', className: 'wsk-hint', style: { marginTop: 2 } },
                     tf(`搜索生效 key：${ws.searchKeyMasked || '未配置'}`, `Effective search key: ${ws.searchKeyMasked || 'not configured'}`),
                     ws.searchSync === true
@@ -1385,7 +1561,30 @@ window.__ModuleLoader__.load({
             : null)
       }
 
-      const renderHelp = () => h(Dialog, {
+      const renderHelp = () => (searchInfo?.mode === 'billing'
+        ? h(Dialog, {
+            title: '使用说明',
+            onDismiss: () => setHelp(false),
+            body: h('div', { className: 'wsk-help' },
+              h('h4', null, '搜索 / 获取已交给官方设置'),
+              h('div', { className: 'wsk-hint' },
+                '当前宿主的网页搜索与网页获取按「计费方式」选择用哪把 key，本插件不再接管搜索 key，也不显示旧的搜索配置。'),
+              h('ul', null,
+                h('li', null, '计费方式为「DeepSeek API Key」：搜索跟随当前会话 / 工作区的聊天 key，账单一起算。'),
+                h('li', null, '计费方式为「已登录的 DeepSeek 账号」：搜索走账号令牌，插件无法覆盖。'),
+                h('li', null, '「自动」：看当前会话走的是哪个模型路由，规则由宿主决定。')),
+              h('div', { className: 'wsk-hint' },
+                '要改计费方式，点面板里的「打开官方搜索设置」，或手动到「设置 → 插件 → 网页搜索」。'),
+              h('div', { className: 'wsk-hint' },
+                '实验性的「统一搜索 key」在「设置 → API Key 分配」页里，开启后所有会话搜索共用插件持有的一把 key。'),
+              h('h4', null, '聊天 key 的优先级'),
+              h('ol', null,
+                h('li', null, '会话单独配置的 key'),
+                h('li', null, '工作区专属 key'),
+                h('li', null, '系统默认 key'))),
+            actions: [{ label: '知道了', primary: true, onClick: () => setHelp(false) }],
+          })
+        : h(Dialog, {
         title: '使用说明',
         onDismiss: () => setHelp(false),
         body: h('div', { className: 'wsk-help' },
@@ -1430,7 +1629,7 @@ window.__ModuleLoader__.load({
           h('div', { className: 'wsk-hint' },
             '提醒只报告、不替你改 key。插件绝不会自动切换或替换你的 key，避免计费被悄悄改到别的账号上。')),
         actions: [{ label: '知道了', primary: true, onClick: () => setHelp(false) }],
-      })
+      }))
 
       const renderPrompt = () => {
         if (prompt === null) return null
@@ -1572,7 +1771,28 @@ window.__ModuleLoader__.load({
                   onClick: () => runTest(DEFAULT_KEY, '系统默认', { ref: defaultRef?.ref ?? DEFAULT_REF }),
                 }, testing === DEFAULT_KEY ? '测试中…' : '测试连接')))),
 
-          searchInfo?.apiChannel === true
+          searchInfo?.mode === 'billing'
+            ? h('div', { className: 'wsk-card' },
+                h('h4', null, '搜索与获取'),
+                h('div', { className: 'wsk-hint' },
+                  '新版宿主用「计费方式」管理网页搜索 / 网页获取：key 由官方设置页决定，本面板不再接管，也不再显示旧的搜索 key。'),
+                h('div', { className: 'wsk-hint' },
+                  tf(
+                    `当前计费方式：搜索「${billingText(searchInfo.billing?.search)}」，获取「${billingText(searchInfo.billing?.fetch)}」`,
+                    `Current billing: search "${billingText(searchInfo.billing?.search)}", fetch "${billingText(searchInfo.billing?.fetch)}"`)),
+                searchInfo?.unified === true
+                  ? h('div', { className: 'wsk-hint' },
+                      '实验性「统一搜索 key」已开启：所有会话 / 工作区搜索都使用同一把 key。可在「设置 → API Key 分配」里更换或关闭。')
+                  : h('div', { className: 'wsk-hint' },
+                      '计费方式为「DeepSeek API Key」时，搜索会跟随当前会话 / 工作区的聊天 key；为「已登录的 DeepSeek 账号」时，搜索走账号令牌，插件无法覆盖。'),
+                h('div', { className: 'wsk-row', style: { marginTop: 8 } },
+                  h('button', {
+                    type: 'button', className: 'wsk-btn primary',
+                    onClick: openOfficialSearchSettings,
+                  }, '打开官方搜索设置')))
+            : null,
+
+          searchInfo?.mode !== 'billing' && searchInfo?.apiChannel === true
             ? h('div', { className: 'wsk-card' },
                 h('h4', null, '搜索默认 key'),
                 h('div', { className: 'wsk-row' },

package/lib/index.js

@@ -32,6 +32,7 @@
 
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
 import { createHash } from 'node:crypto'
+import { createRequire } from 'node:module'
 import { homedir } from 'node:os'
 import { join, dirname, basename, resolve as pathResolve } from 'node:path'
 
@@ -116,6 +117,11 @@ function isSearchRefFor(ctx, ref) {
   if (typeof ref !== 'string' || ref === '') return false
   const web = currentWeb(ctx)
   if (web.apiChannel !== true) return false
+  // 新版计费模型：搜索只认 `searchApiKeyEnv` 指向的自有 ref；聊天 ref（DEEPSEEK_API_KEY）
+  // 绝不能被当成搜索处理，否则「统一搜索 key」会把聊天也一起换掉。
+  if (web.mode === 'billing') {
+    return ref === SEARCH_DEFAULT_REF || (web.ownSearchRef !== undefined && ref === web.ownSearchRef)
+  }
   // 官方页还没被接管时，搜索用的是聊天那把 ref：这时分辨不了，按聊天处理（安全）。
   if (web.searchKeyEnv === DEFAULT_API_KEY_REF) return ref === SEARCH_DEFAULT_REF
   return ref === SEARCH_DEFAULT_REF || ref === web.searchKeyEnv || ref === web.legacyKeyEnv
@@ -142,6 +148,39 @@ const PLUGIN_VERSION = (() => {
   }
 })()
 
+/**
+ * 宿主运行时版本（尽力而为，只用于界面展示与日志）。
+ *
+ * 行为判断**不**依赖它：桌面端宿主代码打在 app.asar 里，`@deepseek-ai/dsh`
+ * 不一定能从插件目录解析到；而新版搜索配置的 schema 特征（searchBilling /
+ * fetchBilling）与行为一一对应，所以 gating 用特性检测，版本号只是辅助信息。
+ */
+const HOST_VERSION = (() => {
+  try {
+    const req = createRequire(import.meta.url)
+    let main
+    try {
+      main = req.resolve('@deepseek-ai/dsh')
+    } catch {
+      main = undefined
+    }
+    if (main === undefined) return undefined
+    // 从入口文件往上找最近的 package.json。
+    let dir = dirname(main)
+    for (let depth = 0; depth < 5; depth += 1) {
+      const candidate = join(dir, 'package.json')
+      if (existsSync(candidate)) {
+        const pkg = JSON.parse(readFileSync(candidate, 'utf8'))
+        if (typeof pkg?.version === 'string') return pkg.version
+      }
+      dir = dirname(dir)
+    }
+  } catch {
+    /* ignore */
+  }
+  return undefined
+})()
+
 // ─────────────────────────── 路径 / 工作区键 ───────────────────────────
 
 /** 统一的路径比较用规范形：绝对化 + 分隔符统一 + Windows 折大小写。 */
@@ -354,6 +393,32 @@ async function bindOfficialSearchRef(ctx, ref) {
   return { ok: true, changed }
 }
 
+/**
+ * 写新版搜索 API 的 schema 字段（实验性「统一搜索 key」用）。
+ *
+ * 只改 `searchApiKeyEnv` / `fetchApiKeyEnv` 这类声明过的字段，不碰任何 key 值；
+ * 空字符串表示「清掉自有 ref、回到官方计费方式」（官方 resolveTarget 用 nonEmpty 判断）。
+ */
+async function updateSearchApiSettings(ctx, patch) {
+  let settings
+  try {
+    settings = ctx.get('settings')
+  } catch {
+    settings = undefined
+  }
+  if (typeof settings?.update !== 'function' || typeof settings?.describe !== 'function') {
+    return { ok: false, reason: 'settings-unavailable' }
+  }
+  try {
+    const row = (settings.describe() ?? []).find((item) => item?.ns === SEARCH_API_NS)
+    if (row === undefined) return { ok: false, reason: 'search-settings-missing' }
+    await settings.update(SEARCH_API_NS, patch, row.revision)
+    return { ok: true }
+  } catch (error) {
+    return { ok: false, reason: error?.message ?? String(error) }
+  }
+}
+
 /**
  * 启动时把官方「网页搜索」页的 key 指向拉回一致。
  *
@@ -879,6 +944,14 @@ function webDefaults() {
     apiChannel: false,
     searchKeyEnv: DEFAULT_API_KEY_REF,
     searchLiteralKey: undefined,
+    // 搜索配置模型：'ref' = 旧版（apiKeyEnv 指针）；'billing' = 0.2.2-rc.2 起的计费方式模型。
+    mode: 'ref',
+    searchBilling: undefined,
+    fetchBilling: undefined,
+    ownSearchRef: undefined,
+    ownFetchRef: undefined,
+    searchBaseURL: undefined,
+    fetchBaseURL: undefined,
   }
 }
 
@@ -903,6 +976,27 @@ function webConfigOf(rows) {
     : FALLBACK_FETCH_PROVIDER
   const apiLiteralKey = typeof api.apiKey === 'string' && api.apiKey !== '' ? api.apiKey : undefined
   const legacyLiteralKey = typeof legacy.apiKey === 'string' && legacy.apiKey !== '' ? legacy.apiKey : undefined
+
+  // 0.2.2-rc.2 起，搜索改由「计费方式」决定凭据：searchBilling / fetchBilling +
+  // （可选的）自有端点/ref。旧字段 apiKeyEnv 还能加载，但已经不再生效。
+  // 用「行里有没有 *_Billing」做特性检测，而不是解析宿主版本号：版本号在桌面端
+  // 拿不到（宿主代码打在 asar 里），而这个 schema 特征与行为是一一对应的。
+  const searchBilling = typeof api.searchBilling === 'string' && api.searchBilling !== '' ? api.searchBilling : undefined
+  const fetchBilling = typeof api.fetchBilling === 'string' && api.fetchBilling !== '' ? api.fetchBilling : undefined
+  const mode = searchBilling !== undefined || fetchBilling !== undefined ? 'billing' : 'ref'
+  const ownSearchRef = typeof api.searchApiKeyEnv === 'string' && api.searchApiKeyEnv !== ''
+    ? api.searchApiKeyEnv
+    : undefined
+  const ownFetchRef = typeof api.fetchApiKeyEnv === 'string' && api.fetchApiKeyEnv !== ''
+    ? api.fetchApiKeyEnv
+    : undefined
+  const searchBaseURL = typeof api.searchBaseURL === 'string' && api.searchBaseURL !== ''
+    ? api.searchBaseURL
+    : FALLBACK_SEARCH_BASE_URL
+  const fetchBaseURL = typeof api.fetchBaseURL === 'string' && api.fetchBaseURL !== ''
+    ? api.fetchBaseURL
+    : FALLBACK_SEARCH_BASE_URL
+
   return {
     apiKeyEnv,
     legacyKeyEnv,
@@ -915,8 +1009,17 @@ function webConfigOf(rows) {
     /** 新版 Search/Fetch API 是否被选中（官方开关）= provider 选择被改成了 API 版。 */
     apiChannel: searchProvider === SEARCH_PROVIDER_ID || fetchProvider === SEARCH_FETCH_PROVIDER_ID,
     /** 搜索请求真正会用的那套配置的 key 引用。 */
-    searchKeyEnv: searchProvider === SEARCH_PROVIDER_ID ? apiKeyEnv : legacyKeyEnv,
+    searchKeyEnv: searchProvider === SEARCH_PROVIDER_ID
+      ? (mode === 'billing' ? ownSearchRef ?? DEFAULT_API_KEY_REF : apiKeyEnv)
+      : legacyKeyEnv,
     searchLiteralKey: searchProvider === SEARCH_PROVIDER_ID ? apiLiteralKey : legacyLiteralKey,
+    mode,
+    searchBilling,
+    fetchBilling,
+    ownSearchRef,
+    ownFetchRef,
+    searchBaseURL,
+    fetchBaseURL,
   }
 }
 
@@ -927,6 +1030,30 @@ function webConfigOf(rows) {
  */
 async function searchWarnings(ctx, state, web) {
   const out = []
+
+  // 新版计费模型：搜索不再读 apiKeyEnv 指针，旧提醒（同步/搜索默认 key）全部失去意义。
+  // 这里只保留两条与新版真正相关的提示，避免面板给出过时或错误的引导。
+  if (web.mode === 'billing') {
+    if (web.ownSearchRef === SEARCH_DEFAULT_REF) {
+      out.push({
+        code: 'search-unified',
+        level: 'info',
+        title: '实验性：所有会话的搜索共用同一把 key',
+        detail: `搜索/获取被指向插件自有的 ${SEARCH_DEFAULT_REF}，官方「计费方式」暂时不生效。`
+          + '要恢复按会话/工作区计费，到「设置 → API Key 分配」里关掉这项实验功能。',
+      })
+    } else if (web.searchBilling === 'account') {
+      out.push({
+        code: 'search-billing-account',
+        level: 'warn',
+        title: '搜索当前按「已登录的 DeepSeek 账号」计费',
+        detail: '计费方式设为 account 时，搜索只使用账号令牌，本插件配置的 API key 不会参与搜索。'
+          + '要让搜索跟随会话/工作区的 key，请到「设置 → 插件 → 网页搜索」把计费方式改成「DeepSeek API Key」。',
+      })
+    }
+    return out
+  }
+
   const apiKeyConfigured = web.apiKeyEnv === DEFAULT_API_KEY_REF
     ? (await describeKey(ctx, DEFAULT_API_KEY_REF)).configured === true
     : (await describeKey(ctx, web.apiKeyEnv)).configured === true
@@ -1321,7 +1448,9 @@ export function apply(ctx) {
   }
   installResolver(ctx, state)
   // 「直接禁用官方页面里的搜索 key 设置」：把官方 apiKeyEnv 指到插件自有 ref（异步、失败不影响启动）。
-  void reconcileOfficialSearchRef(ctx)
+  // 0.2.2-rc.2 起官方改用计费方式（searchBilling/fetchBilling），apiKeyEnv 已不再生效：
+  // 这时再写它只会制造「看起来配了、其实没用」的无效配置，所以只在旧模型下接管。
+  if (currentWeb(ctx).mode !== 'billing') void reconcileOfficialSearchRef(ctx)
 
   // ── 2. REST API（loopback 可信）──────────────────────────────────────
   let webServer
@@ -1404,6 +1533,15 @@ function installResolver(ctx, state) {
       if (isSearchRefFor(ctx, ref)) {
         const web = currentWeb(ctx)
         if (web.apiChannel) {
+          // 实验性「统一搜索 key」：搜索/获取固定用插件自有的那一把，优先于会话/工作区配置。
+          // 只在计费模型下生效：旧模型里 searchApiKeyEnv 就是「搜索默认 key」，语义不同。
+          if (web.mode === 'billing' && web.ownSearchRef === SEARCH_DEFAULT_REF) {
+            const forced = await resolveKey(ctx, SEARCH_DEFAULT_REF)
+            if (forced.value !== undefined && forced.value !== '') {
+              log(`search ref ${ref} → ${SEARCH_DEFAULT_REF} (unified)`)
+              return { value: forced.value, source: forced.source ?? 'plugin' }
+            }
+          }
           // ① 会话单独设置的 key 永远优先——哪怕官方搜索插件里配了别的 key。
           const sessionKey = sessionOverrideRef(state, sessionId)
           if (sessionKey !== undefined) {
@@ -1783,6 +1921,7 @@ async function snapshot(ctx, state) {
   return {
     ok: true,
     pluginVersion: PLUGIN_VERSION,
+    hostVersion: HOST_VERSION,
     storeVersion: STATE_VERSION,
     // 面板卡顿排查用：会话探针（宿主 list 一次要扫所有会话）与整行的耗时。
     timings: { probeMs, rowsMs: Math.max(0, totalMs - probeMs), totalMs },
@@ -1821,6 +1960,13 @@ async function snapshot(ctx, state) {
     // 搜索 / 抓取通道：官方「设置 → 插件 → 网页搜索」里的配置 + 本插件怎么参与。
     // 面板据此显示通道、生效 key 与提醒；不暴露任何明文。
     search: {
+      // 'billing' = 0.2.2-rc.2 起的计费方式模型；'ref' = 旧版 apiKeyEnv 指针模型。
+      mode: web.mode ?? 'ref',
+      billing: { search: web.searchBilling, fetch: web.fetchBilling },
+      ownSearchRef: web.ownSearchRef,
+      ownFetchRef: web.ownFetchRef,
+      // 实验性「统一搜索 key」：把官方 searchApiKeyEnv 指向插件自有 ref。
+      unified: web.mode === 'billing' && web.searchKeyEnv === SEARCH_DEFAULT_REF,
       channel: web.apiChannel ? 'api' : 'messages',
       apiChannel: web.apiChannel,
       searchProvider: web.searchProvider,
@@ -2168,6 +2314,43 @@ async function handle(ctx, state, req, res) {
       return
     }
 
+    if (pathname === `${API_BASE}/search-unified` && method === 'POST') {
+      const body = await readJson(req)
+      const web = refreshWebCache(ctx)
+      if (web.mode !== 'billing') {
+        sendJson(res, 400, { ok: false, error: '当前宿主还是旧版搜索配置，不支持该实验功能' })
+        return
+      }
+      const enabled = body.enabled !== false
+      if (enabled) {
+        const key = typeof body.key === 'string' ? body.key.trim() : ''
+        if (key === '') {
+          sendJson(res, 400, { ok: false, error: '请先填写一把搜索 key' })
+          return
+        }
+        await storeKey(ctx, SEARCH_DEFAULT_REF, key)
+        const updated = await updateSearchApiSettings(ctx, {
+          searchApiKeyEnv: SEARCH_DEFAULT_REF,
+          fetchApiKeyEnv: SEARCH_DEFAULT_REF,
+        })
+        if (updated.ok !== true) {
+          sendJson(res, 500, { ok: false, error: `写入官方搜索配置失败：${updated.reason}` })
+          return
+        }
+      } else {
+        const updated = await updateSearchApiSettings(ctx, { searchApiKeyEnv: '', fetchApiKeyEnv: '' })
+        if (updated.ok !== true) {
+          sendJson(res, 500, { ok: false, error: `写入官方搜索配置失败：${updated.reason}` })
+          return
+        }
+      }
+      webCache = undefined
+      refreshWebCache(ctx)
+      log(`unified search key ${enabled ? 'on' : 'off'}`)
+      sendJson(res, 200, { ok: true, enabled, ...(await snapshot(ctx, state)) })
+      return
+    }
+
     if (pathname === `${API_BASE}/search-sync` && method === 'POST') {
       const body = await readJson(req)
       const dir = typeof body.path === 'string' ? body.path : undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-workspace-api-key",
-  "version": "0.2.17",
+  "version": "0.3.0",
   "description": "A DeepSeek Harness plugin that binds a separate DeepSeek API key to each workspace, or to a single session, so the spend of one key stays with the sessions you choose.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,6 @@
     "lib/client.js"
   ],
   "scripts": {
-    "test": "node test/host.test.mjs && node test/client.test.mjs && node test/client-i18n.test.mjs"
+    "test": "node test/host.test.mjs && node test/client.test.mjs && node test/client-i18n.test.mjs && node test/client-billing.test.mjs"
   }
 }