dsh-workspace-api-key 0.2.8 → 0.2.10

package/README.md

@@ -21,6 +21,7 @@ session key  →  workspace key  →  system default
 - **Mismatch warning** — if the key you bound was recorded for one provider (say `deepseek-official`) and the session now runs on another, entering that session reports it, because that request would be sent with a key the provider does not accept.
 - **No silent substitution** — neither warning ever changes which key is used. The decision stays with you, which is the whole point: an automatically swapped key would defeat the billing separation.
 - **One-click revert** — clearing a session entry falls back to the workspace key, clearing a workspace entry falls back to the system default.
+- **A search default key of its own** — the `搜索默认 key` card binds a key to `DEEPSEEK_API_KEY_SEARCH`, so search can be billed apart from chat without editing the official configuration: a session's own key wins, then a synced workspace's chat cascade, then this key, then whatever the official search page stores.
 - **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.
 - **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.
@@ -34,7 +35,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. The official new Search/Fetch API (`web.searchProvider === 'deepseek-search-api'`) resolves its key itself, and it defaults to the same `DEEPSEEK_API_KEY` the chat uses, so the ref alone cannot say why a key is being asked for. The host half therefore wraps `ctx.web.search` / `ctx.web.fetch` in an `AsyncLocalStorage` scope and applies the search rule only when `credentials.resolve` runs inside it — a session's own key first (always), then, if that workspace ticked `同步搜索 API`, the workspace key and then the system default, and otherwise 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. The official new Search/Fetch API (`web.searchProvider === 'deepseek-search-api'`) resolves its key itself, and it defaults to the same `DEEPSEEK_API_KEY` the chat uses, so the ref alone cannot say why a key is being asked for. The host half therefore wraps `ctx.web.search` / `ctx.web.fetch` in an `AsyncLocalStorage` scope and applies the search rule only when `credentials.resolve` runs inside it — a session's own key first (always), then, if that workspace ticked `同步搜索 API`, the workspace key and then the system default, otherwise its own search default ref when the panel 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;
 - 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;
@@ -51,6 +52,7 @@ The browser half (`lib/client.js`) registers into the `sidebar.panellist` slot (
 | GET | `/wsk-api/resolve` | which level and ref the current session resolves to right now |
 | GET | `/wsk-api/check` | `?sessionId=…&path=…` — read-only verdict for one session: effective level, key, stale flag, provider mismatch, `needsAttention` |
 | POST | `/wsk-api/set` | `{scope: 'workspace' \| 'session', path \| sessionId, title, key, provider?}` binds a key; `{useDefault: true}` or an empty key clears it |
+| POST | `/wsk-api/set` (search) | `{scope: 'search-default', key}` binds the panel's search default key; `{useDefault: true}` clears it |
 | 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 |
@@ -76,7 +78,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.8`, 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.2.10`, 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:
 
@@ -87,11 +89,11 @@ Then add `"dsh-workspace-api-key"` to `dsh.profile.bundles` in that profile's `p
 ## Tests
 
 ```sh
-node test/host.test.mjs     # 157 assertions
-node test/client.test.mjs   # 162 assertions
+node test/host.test.mjs     # 165 assertions
+node test/client.test.mjs   # 170 assertions
 ```
 
-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 two 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 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.
 
 ## Requirements and limits
 
@@ -102,7 +104,7 @@ Neither suite needs a running DSH process. The host suite drives `apply()` again
 - 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.
 - 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 in the credentials file; remove them from the Models page.
+- Uninstalling the plugin leaves the generated `*_WS_*` / `*_SS_*` refs and `DEEPSEEK_API_KEY_SEARCH` in the credentials file; remove them from the Models page.
 - If the panel lists workspaces but no expandable sessions, read the diagnostics line at the bottom of the panel. A red "the host half is still an older version" banner means the DSH process was never restarted: the host half is loaded once at startup, so closing the window or reloading the page is not enough — fully quit DSH Desktop and open it again. Otherwise the diagnostics line shows how many sessions the host sees (and from which source: `sessionController`, its live-session fallback, or the browser store), plus sample session `cwd` values next to sample workspace paths when none of them match.
 
 ## License

package/README.zh.md

@@ -21,6 +21,7 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 - **不匹配提醒** —— 如果绑 key 时记下的是某个服务商（比如 `deepseek-official`），而该会话现在跑在另一个服务商上，点进这个会话时会提醒你，因为那次请求会拿着对方不认的 key 发出去。
 - **绝不悄悄换 key** —— 两种提醒都不会改动实际使用的 key，决定权始终在你手上；自动替换会直接破坏「按会话分离计费」这个初衷。
 - **一键回退** —— 清空会话条目回到工作区 key，清空工作区条目回到系统默认。
+- **搜索默认 key 单独一把** —— 「搜索默认 key」卡片把这把 key 绑到 `DEEPSEEK_API_KEY_SEARCH`，于是搜索可以和聊天分开计费，而且不用去改官方配置：会话自己的 key 最优先，其次勾了同步的工作区走聊天层级，再次是这把搜索默认 key，最后才是官方搜索页里配的那把。
 - **每个工作区一个搜索开关** —— 每个工作区行上都有「同步搜索 API」复选框。勾选后，该目录下会话发出的 `web_search` / `web_fetch` 请求改用它们聊天时用的那把 key（会话 → 工作区 → 系统默认）；不勾选则继续用官方「设置 → 插件 → 网页搜索」里配置的那把 key。会话自己配了 key 时永远优先，所以「工作区同步、会话单独设置」花的是会话那把 key，而不是搜索默认 key。
 - **在失败之前就提醒的搜索告警** —— 配了搜索 key 但没打开「启用新版 Web 搜索 API」，或者新版 API 打开了但它的 key ref 是空的，面板会显示提醒条，点进会话时的覆盖层也会用一句可直接照做的话说明；当生效的搜索通道不是新版 API 时，覆盖层不会拿搜索问题打扰你。
 - **使用说明** —— 面板顶部有「使用说明」，推荐两把 key 分工：聊天默认用 `default`，搜索默认用 `search-default`，两份预算互不干扰；里面还画了层级，并列出了会触发提醒的几种情况。
@@ -34,7 +35,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 原样透传；
-- 把「搜索请求」和「聊天请求」分开。官方新版 Search/Fetch API（`web.searchProvider === 'deepseek-search-api'`）自己解析 key，而它默认读的又是聊天用的 `DEEPSEEK_API_KEY`，所以光看 ref 分不出这次要 key 是为了什么。宿主半边因此把 `ctx.web.search` / `ctx.web.fetch` 包进一个 `AsyncLocalStorage` 作用域，只有当 `credentials.resolve` 在这个作用域里被调用时才套用搜索规则：先看会话自己的 key（永远最优先），再看该工作区有没有勾「同步搜索 API」，勾了就依次用工作区 key、系统默认 key，没勾就用搜索插件配置的那个 ref。旧版基于 Messages 的搜索仍然走原来的聊天层级，因为那条路线本身就是一次 messages 请求；
+- 把「搜索请求」和「聊天请求」分开。官方新版 Search/Fetch API（`web.searchProvider === 'deepseek-search-api'`）自己解析 key，而它默认读的又是聊天用的 `DEEPSEEK_API_KEY`，所以光看 ref 分不出这次要 key 是为了什么。宿主半边因此把 `ctx.web.search` / `ctx.web.fetch` 包进一个 `AsyncLocalStorage` 作用域，只有当 `credentials.resolve` 在这个作用域里被调用时才套用搜索规则：先看会话自己的 key（永远最优先），再看该工作区有没有勾「同步搜索 API」，勾了就依次用工作区 key、系统默认 key；没勾时先用插件面板自己持有的搜索默认 ref（若配了），最后才用搜索插件配置的那个 ref。旧版基于 Messages 的搜索仍然走原来的聊天层级，因为那条路线本身就是一次 messages 请求；
 - 会话列表来自 `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` 与任何工作区路径都对不上；
@@ -50,6 +51,7 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 | GET | `/wsk-api/state` | 默认 ref 状态、工作区及其会话、覆盖项、失效标记 |
 | GET | `/wsk-api/resolve` | 当前会话此刻解析到哪一层、哪个 ref |
 | GET | `/wsk-api/check` | `?sessionId=…&path=…` 只读判定：生效层级、key、失效标记、服务商不匹配、`needsAttention` |
+| POST | `/wsk-api/set`（搜索） | `{scope: 'search-default', key}` 绑定面板自己的搜索默认 key；`{useDefault: true}` 清除 |
 | POST | `/wsk-api/set` | `{scope: 'workspace' \| 'session', path \| sessionId, title, key, provider?}` 绑定 key；`{useDefault: true}` 或空 key 为清除 |
 | POST | `/wsk-api/test` | `{scope, path \| sessionId \| ref}`（或 `{key}`）真发一次请求并返回判定；`invalid` 打标记，`ok` 清标记 |
 | POST | `/wsk-api/clear-flag` | `{ref}` 或一个目标，清掉失效/配额标记 |
@@ -76,7 +78,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.8`；直接从仓库装则用 `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key`（git 来源的插件会在安装时现场构建）。
+锁版本用 `dsh-workspace-api-key@0.2.10`；直接从仓库装则用 `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key`（git 来源的插件会在安装时现场构建）。
 
 然后把 `"dsh-workspace-api-key"` 加进该 profile `package.json` 的 `dsh.profile.bundles`，重启 DSH。本地开发用 link 代替：
 
@@ -87,11 +89,11 @@ pnpm add dsh-workspace-api-key          # 或者：npm install dsh-workspace-api
 ## 测试
 
 ```sh
-node test/host.test.mjs     # 157 条断言
-node test/client.test.mjs   # 162 条断言
+node test/host.test.mjs     # 165 条断言
+node test/client.test.mjs   # 170 条断言
 ```
 
-两个套件都不需要启动 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 压过两者、两类搜索提醒，以及搜索连接测试。浏览器套件覆盖搜索相关界面：每个工作区行的「同步搜索 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`、提醒条与「使用说明」弹窗。
 
 ## 要求与限制
 

package/lib/client.js

@@ -515,6 +515,8 @@ window.__ModuleLoader__.load({
       const [notice, setNotice] = useState(null)
       const [prompt, setPrompt] = useState(null)
       const [help, setHelp] = useState(false)
+      const [searchOpen, setSearchOpen] = useState(false)
+      const [searchDraft, setSearchDraft] = useState('')
       const [expanded, setExpanded] = useState(() => new Set())
 
       const alive = useRef(true)
@@ -661,6 +663,32 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // 搜索默认 key：由插件自己持有一个 ref（DEEPSEEK_API_KEY_SEARCH），
+      // 搜索请求在没有会话/工作区层级 key 时优先用它，从而和聊天 key 分开计费。
+      const saveSearchDefault = async (key) => {
+        const trimmed = typeof key === 'string' ? key.trim() : ''
+        setBusy(true)
+        try {
+          const body = { scope: 'search-default' }
+          if (trimmed === '') body.useDefault = true
+          else body.key = trimmed
+          const next = await api('/set', { method: 'POST', body: JSON.stringify(body) })
+          applyState(next)
+          setSearchDraft('')
+          if (trimmed === '') setSearchOpen(false)
+          setNotice({
+            kind: 'ok',
+            text: trimmed === ''
+              ? '搜索默认 key 已清除：搜索改用官方搜索页里配的那把 key。'
+              : '搜索默认 key 已保存：搜索请求优先用它（工作区同步与会话单独配置仍然优先）。',
+          })
+        } catch (err) {
+          if (alive.current) setNotice({ kind: 'bad', text: `${err?.message ?? err}` })
+        } finally {
+          if (alive.current) setBusy(false)
+        }
+      }
+
       const runTest = async (id, title, body, key) => {
         setTesting(id)
         setNotice(null)
@@ -972,7 +1000,11 @@ window.__ModuleLoader__.load({
                   }),
                   h('span', null, '同步搜索 API'),
                   h('span', { className: 'wsk-check-note' },
-                    ws.searchSync === true ? '搜索用这里的 key' : '搜索用搜索插件里的 key')),
+                    ws.searchSync === true
+                      ? '搜索用这里的 key'
+                      : searchInfo?.defaultConfigured === true
+                        ? '搜索用搜索默认 key'
+                        : '搜索用搜索插件里的 key')),
               ws.kind !== 'orphan' && searchInfo?.apiChannel === true && ws.searchKeyMasked !== undefined
                 ? h('div', { key: 'sk', className: 'wsk-hint', style: { marginTop: 2 } },
                     `搜索生效 key：${ws.searchKeyMasked || '未配置'}`,
@@ -1023,27 +1055,26 @@ window.__ModuleLoader__.load({
           h('h4', null, '推荐用法（两把 key，各管一件事）'),
           h('ol', null,
             h('li', null, '先到「设置 → 模型」配一把系统默认 key，例如就叫 ', h('code', null, 'default'),
-              '。没有单独配置的会话都会用它聊天。'),
-            h('li', null, '再到「设置 → 插件 → 网页搜索」打开「启用新版 Web 搜索 API」，',
-              '并在那里的 API Key 里配一把搜索专用的 key，例如 ', h('code', null, 'search-default'), '。'),
-            h('li', null, '平时不用再管：聊天用工作区/会话的 key，搜索用 ', h('code', null, 'search-default'),
-              '，两边计费互不影响。')),
-          h('h4', null, '层级（从高到低）'),
+              '。没有单独配置的地方都用它聊天。'),
+            h('li', null, '再回到本页的「搜索默认 key」，放一把搜索专用的 key，例如 ', h('code', null, 'search-default'),
+              '。搜索请求默认用它，和聊天那把分开计费。'),
+            h('li', null, '平时不用再管：聊天按工作区/会话的 key 走，搜索走搜索默认 key，两边账单互不影响。')),
+          h('h4', null, '想按工作区核算搜索花费'),
           h('ul', null,
-            h('li', null, '会话单独配置 → 覆盖该会话的一切（聊天与搜索都用它）'),
-            h('li', null, '工作区专属 key → 该工作区下所有没单独配置的会话'),
-            h('li', null, '系统默认 key → 兜底'),
-            h('li', null, '搜索默认 key → 只有在工作区没勾「同步搜索 API」、且该会话没有单独配置时才用')),
-          h('h4', null, '「同步搜索 API」是什么'),
-          h('ul', null,
-            h('li', null, '勾选：该目录下会话的搜索/抓取请求改用上面那套层级 key（和聊天完全一致）。'),
-            h('li', null, '不勾：搜索用「搜索插件里配置的 key」（例如 ', h('code', null, 'search-default'), '）。'),
-            h('li', null, '会话单独配置的 key 永远优先——勾不勾都一样。'),
-            h('li', null, '这个开关只对「新版 Web 搜索 API」有效；旧的 Messages 搜索本来就用聊天 key。')),
+            h('li', null, '在该工作区行勾上「同步搜索 API」：这个目录下会话的搜索就改用聊天那套层级 key',
+              '（会话 key → 工作区 key → 系统默认），不再用搜索默认 key。'),
+            h('li', null, '不勾的目录继续用搜索默认 key。两种方式可以同时存在，一个工作区一个样。')),
+          h('h4', null, '搜索 key 的优先级（从高到低）'),
+          h('ol', null,
+            h('li', null, '会话单独配置的 key —— 该会话的聊天与搜索都用它，永远最优先'),
+            h('li', null, '工作区勾了「同步搜索 API」—— 该工作区下会话的搜索改用：工作区 key → 系统默认 key'),
+            h('li', null, '搜索默认 key —— 没勾同步时，搜索用它'),
+            h('li', null, '官方「网页搜索」页里配的那把 —— 面板没配搜索默认 key 时的兜底',
+              '（它默认就是系统默认 key ', h('code', null, 'DEEPSEEK_API_KEY'), '，与聊天共用）')),
           h('h4', null, '会被提醒的几种情况'),
           h('ul', null,
             h('li', null, '配了搜索 key，但没打开「启用新版 Web 搜索 API」→ 那把 key 其实不会被用到，面板顶部会提示。'),
-            h('li', null, '打开了新版搜索 API，但搜索 key 是空的 → 任何搜索都会失败，面板顶部会提示。'),
+            h('li', null, '打开了新版搜索 API，但既没有搜索默认 key、官方那把也是空的 → 任何搜索都会失败，面板顶部会提示。'),
             h('li', null, '勾了同步，但该工作区既没有专属 key、系统默认 key 也没配 → 会提示先去配一把。')),
           h('h4', null, '原则'),
           h('div', { className: 'wsk-hint' },
@@ -1191,6 +1222,62 @@ window.__ModuleLoader__.load({
                   onClick: () => runTest(DEFAULT_KEY, '系统默认', { ref: defaultRef?.ref ?? DEFAULT_REF }),
                 }, testing === DEFAULT_KEY ? '测试中…' : '测试连接')))),
 
+          searchInfo?.apiChannel === true
+            ? h('div', { className: 'wsk-card' },
+                h('h4', null, '搜索默认 key'),
+                h('div', { className: 'wsk-row' },
+                  h('div', { className: 'wsk-row-main' },
+                    h('div', { className: 'wsk-name' },
+                      h('span', { key: 'r' }, searchInfo.defaultRef ?? 'DEEPSEEK_API_KEY_SEARCH'),
+                      searchInfo.defaultConfigured === true
+                        ? h('span', { key: 's', className: 'wsk-badge ok' }, '已配置')
+                        : h('span', { key: 's', className: 'wsk-badge' }, '未配置')),
+                    h('div', { className: 'wsk-hint' },
+                      '搜索请求默认用它，和聊天那把 key 分开计费。'
+                      + '工作区勾了「同步搜索 API」时改用该工作区的聊天层级；会话单独配置永远最优先。',
+                      searchInfo.defaultConfigured === true && searchInfo.defaultKeyMasked
+                        ? ` 当前值：${searchInfo.defaultKeyMasked}`
+                        : '')),
+                  h('div', { className: 'wsk-actions' },
+                    h('button', {
+                      type: 'button', className: 'wsk-btn', disabled: busy,
+                      onClick: () => setSearchOpen((open) => !open),
+                    }, searchOpen ? '收起' : '配置'))),
+                searchOpen
+                  ? h('div', { className: 'wsk-editor' },
+                      h('input', {
+                        className: 'wsk-input',
+                        type: 'text',
+                        autoComplete: 'off',
+                        spellCheck: false,
+                        placeholder: 'sk-…（留空 = 用官方搜索页里配的那把）',
+                        value: searchDraft,
+                        onChange: (ev) => setSearchDraft(ev.target.value),
+                        onKeyDown: (ev) => { if (ev.key === 'Enter') saveSearchDefault(searchDraft) },
+                      }),
+                      h('div', { className: 'wsk-dialog-actions' },
+                        h('button', {
+                          type: 'button', className: 'wsk-btn primary', disabled: busy,
+                          onClick: () => saveSearchDefault(searchDraft),
+                        }, busy ? '保存中…' : '保存'),
+                        h('button', {
+                          type: 'button', className: 'wsk-btn',
+                          disabled: busy || searchDraft.trim() === '',
+                          onClick: () => runTest('__search_default__', '搜索默认', { scope: 'search-default', channel: 'search' }, searchDraft),
+                        }, testing === '__search_default__' ? '测试中…' : '用这把 key 测试'),
+                        searchInfo.defaultConfigured === true
+                          ? h('button', {
+                              type: 'button', className: 'wsk-btn', disabled: busy,
+                              onClick: () => saveSearchDefault(''),
+                            }, '清除')
+                          : null,
+                        h('button', {
+                          type: 'button', className: 'wsk-btn',
+                          onClick: () => setSearchOpen(false),
+                        }, '收起')))
+                  : null)
+            : null,
+
           h('div', { className: 'wsk-card', style: { background: 'transparent', border: 0, padding: 0 } },
             h('h4', { style: { marginBottom: 6 } }, `工作区（${grouped.length}）`),
             h('div', { className: 'wsk-hint', style: { marginBottom: 6 } },

package/lib/index.js

@@ -63,6 +63,13 @@ const FALLBACK_SEARCH_PROVIDER = 'deepseek-official'
 const FALLBACK_FETCH_PROVIDER = 'http'
 const SEARCH_PROVIDER_ID = 'deepseek-search-api'
 const SEARCH_FETCH_PROVIDER_ID = 'deepseek-fetch-api'
+/**
+ * 插件自己持有的「搜索默认 key」。官方搜索页的密钥框写的是它那套 API 的
+ * `apiKeyEnv`（默认 `DEEPSEEK_API_KEY`，与聊天共用），所以想让搜索单独计费，
+ * 就得另立一把 key。这把 key 由面板管理、存在这个 ref 下，搜索时优先于官方页
+ * 配的那把——这样「聊天一把、搜索一把」不用去改官方配置。
+ */
+const SEARCH_DEFAULT_REF = 'DEEPSEEK_API_KEY_SEARCH'
 
 /**
  * 搜索通道标记：包住 `ctx.web.search` / `ctx.web.fetch`，在它们的异步调用链里
@@ -245,7 +252,7 @@ function workspaceSynced(state, cwd) {
  *   新版 API 通道：会话单独 key → 工作区勾了同步 ? （工作区 key / 系统默认）: 搜索插件自己的 ref
  *   旧 Messages 通道：搜索就在用聊天 key，固定返回搜索 ref。
  */
-function searchRefFor(ctx, state, { sessionId, cwd, web }) {
+async function searchRefFor(ctx, state, { sessionId, cwd, web, searchDefault }) {
   const w = web ?? readWebSettings(ctx)
   if (!w.apiChannel) return w.searchKeyEnv
   const own = sessionOverrideRef(state, sessionId)
@@ -254,7 +261,9 @@ function searchRefFor(ctx, state, { sessionId, cwd, web }) {
     const hit = effectiveOverride(ctx, state, { sessionId, cwd })
     return hit.ref ?? DEFAULT_API_KEY_REF
   }
-  return w.searchKeyEnv
+  // 没同步：插件自己的「搜索默认 key」优先，其次才是官方搜索页配的那把。
+  const configured = searchDefault ?? (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true
+  return configured === true ? SEARCH_DEFAULT_REF : w.searchKeyEnv
 }
 
 // ───────────────── 会话列表（宿主 sessionController + live 兜底） ─────────────────
@@ -630,7 +639,7 @@ function maskKey(value) {
  * 保证显式配置过的 ref 一定被拦。
  */
 function interceptableRefs(ctx, state) {
-  const refs = new Set(['DEEPSEEK_API_KEY'])
+  const refs = new Set(['DEEPSEEK_API_KEY', SEARCH_DEFAULT_REF])
   try {
     const llm = ctx.get('llm')
     const adapters = llm?.adapters
@@ -688,13 +697,23 @@ function readWebSettings(ctx) {
   } catch {
     settings = undefined
   }
-  const read = (ns) => {
-    try {
-      const value = settings?.get?.(ns)
-      return typeof value === 'object' && value !== null ? value : {}
-    } catch {
-      return {}
+  // settings 服务的真实形状是 describe() 返回「按 profile 条目 id 键控」的行（每行带 ns 与活值），
+  // 没有 get(ns)：早期版本曾按 get 读取，结果永远拿到 undefined，搜索面板会整个消失。
+  let rows = []
+  try {
+    if (typeof settings?.describe === 'function') {
+      rows = settings.describe() ?? []
+    } else if (typeof settings?.get === 'function') {
+      rows = [SEARCH_API_NS, LEGACY_SEARCH_NS, WEB_NS]
+        .map((ns) => ({ ns, value: settings.get(ns) }))
+        .filter((row) => row.value !== undefined)
     }
+  } catch {
+    rows = []
+  }
+  const read = (ns) => {
+    const value = rows.find((row) => row?.ns === ns)?.value
+    return typeof value === 'object' && value !== null ? value : {}
   }
   const api = read(SEARCH_API_NS)
   const legacy = read(LEGACY_SEARCH_NS)
@@ -739,6 +758,7 @@ async function searchWarnings(ctx, state, web) {
     ? (await describeKey(ctx, DEFAULT_API_KEY_REF)).configured === true
     : (await describeKey(ctx, web.apiKeyEnv)).configured === true
   const apiKeyPresent = web.apiLiteralKey !== undefined || (web.apiKeyEnv !== DEFAULT_API_KEY_REF && apiKeyConfigured)
+  const searchDefaultConfigured = (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true
 
   // 1) 配了新版搜索 API 的 key，但官方开关没开 → 那把 key 永远不会被读到。
   if (!web.apiChannel && apiKeyPresent) {
@@ -753,7 +773,7 @@ async function searchWarnings(ctx, state, web) {
   }
 
   // 2) 开了新版 API，却没有可用的搜索 key → 搜索会直接报缺少凭据。
-  if (web.apiChannel && web.apiLiteralKey === undefined && !apiKeyConfigured) {
+  if (web.apiChannel && web.apiLiteralKey === undefined && !apiKeyConfigured && !searchDefaultConfigured) {
     out.push({
       code: 'search-key-missing',
       level: 'bad',
@@ -763,6 +783,18 @@ async function searchWarnings(ctx, state, web) {
     })
   }
 
+  // 2b) 面板里配了「搜索默认 key」，但新版 API 没开 → 这把 key 也不会被读到。
+  if (!web.apiChannel && searchDefaultConfigured) {
+    out.push({
+      code: 'search-default-idle',
+      level: 'warn',
+      title: '搜索默认 key 已配置，但「启用新版 Web 搜索 API」没打开',
+      detail: '现在搜索走的是 DeepSeek Messages 通道，用的是聊天那把 key，'
+        + `所以面板里的 ${SEARCH_DEFAULT_REF} 不会被使用。`
+        + '要让它生效，请到「设置 → 插件 → 网页搜索」打开那个开关；若暂时不想用新版 API，可以忽略本条。',
+    })
+  }
+
   // 3) 勾了「同步搜索 API」的工作区里，既没有工作区 key，也没有系统默认 key。
   const defaultConfigured = (await describeKey(ctx, DEFAULT_API_KEY_REF)).configured === true
   const syncPaths = Object.keys(state.searchSync ?? {}).filter((key) => state.searchSync[key] === true)
@@ -1225,7 +1257,14 @@ function installResolver(ctx, state) {
             const fallback = await original(DEFAULT_API_KEY_REF)
             if (fallback?.value !== undefined && fallback.value !== '') return fallback
           }
-          // ③ 没同步：用官方搜索插件自己配的那把 key（原样解析）。
+          // ③ 没同步：插件面板里配的「搜索默认 key」优先，其次才是官方搜索页
+          //    配的那把（默认与聊天共用 DEEPSEEK_API_KEY，所以更常见的路径是把
+          //    搜索 key 放在面板里，聊天 key 留在系统默认）。
+          const searchDefaultHit = await resolveKey(ctx, SEARCH_DEFAULT_REF)
+          if (searchDefaultHit.value !== undefined && searchDefaultHit.value !== '') {
+            log(`search ref ${ref} → ${SEARCH_DEFAULT_REF} (search default)`)
+            return { value: searchDefaultHit.value, source: searchDefaultHit.source ?? 'plugin' }
+          }
           return await original(ref)
         }
       }
@@ -1404,12 +1443,15 @@ async function workspaceRow(ctx, state, { id, path: dir, title, kind }, rows, cl
   // 让用户勾了复选框之后马上能看到效果，而不用等到搜索失败才发现。
   const web = readWebSettings(ctx)
   const synced = state.searchSync?.[normPath(dir)] === true
+  const searchDefaultConfigured = web.apiChannel && (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true
   const searchKeyRef = web.apiChannel
     ? synced
       ? configured
         ? ref
         : DEFAULT_API_KEY_REF
-      : web.searchKeyEnv
+      : searchDefaultConfigured
+        ? SEARCH_DEFAULT_REF
+        : web.searchKeyEnv
     : web.searchKeyEnv
   const searchKeyMasked = web.apiChannel ? maskKey((await resolveKey(ctx, searchKeyRef))?.value) : undefined
   return {
@@ -1546,6 +1588,8 @@ async function snapshot(ctx, state) {
   const searchKeyRef = web.searchKeyEnv
   const searchKeyInfo = await describeKey(ctx, searchKeyRef)
   const searchKeyHit = await resolveKey(ctx, searchKeyRef)
+  const defaultSearchInfo = await describeKey(ctx, SEARCH_DEFAULT_REF)
+  const defaultSearchHit = await resolveKey(ctx, SEARCH_DEFAULT_REF)
   const syncPaths = Object.keys(state.searchSync ?? {}).filter((key) => state.searchSync[key] === true)
   const warnings = await searchWarnings(ctx, state, web)
 
@@ -1600,6 +1644,12 @@ async function snapshot(ctx, state) {
       keySource: searchKeyInfo.source,
       keyWritable: searchKeyInfo.writable !== false,
       literalKey: web.searchLiteralKey !== undefined,
+      // 面板自己持有的「搜索默认 key」（优先于官方页配的那把）。
+      defaultRef: SEARCH_DEFAULT_REF,
+      defaultConfigured: defaultSearchInfo.configured === true,
+      defaultKeyMasked: maskKey(defaultSearchHit?.value),
+      defaultSource: defaultSearchInfo.source,
+      defaultWritable: defaultSearchInfo.writable !== false,
       syncCount: syncPaths.length,
       syncPaths,
       warnings,
@@ -1725,9 +1775,9 @@ async function searchStateOf(ctx, state, { sessionId, cwd }) {
     channel: 'api',
     apiChannel: true,
     sync,
-    ref: searchRefFor(ctx, state, { sessionId, cwd, web }),
+    ref: await searchRefFor(ctx, state, { sessionId, cwd, web }),
     sessionOwnKey: sessionOverrideRef(state, sessionId) !== undefined,
-    keyConfigured: (await describeKey(ctx, searchRefFor(ctx, state, { sessionId, cwd, web }))).configured === true,
+    keyConfigured: (await describeKey(ctx, await searchRefFor(ctx, state, { sessionId, cwd, web }))).configured === true,
   }
 }
 
@@ -1782,12 +1832,27 @@ async function handle(ctx, state, req, res) {
 
     if (pathname === `${API_BASE}/set` && method === 'POST') {
       const body = await readJson(req)
+      const key = typeof body.key === 'string' ? body.key.trim() : ''
+      // 搜索默认 key：不是「某个目录/会话」的覆盖，由插件自己持有一个 ref。
+      if (body.scope === 'search-default') {
+        if (body.useDefault === true || key === '') {
+          await clearKey(ctx, SEARCH_DEFAULT_REF)
+          delete state.invalid[SEARCH_DEFAULT_REF]
+          saveState(state)
+          sendJson(res, 200, { ok: true, cleared: true, ...(await snapshot(ctx, state)) })
+          return
+        }
+        await storeKey(ctx, SEARCH_DEFAULT_REF, key)
+        delete state.invalid[SEARCH_DEFAULT_REF]
+        saveState(state)
+        sendJson(res, 200, { ok: true, ...(await snapshot(ctx, state)) })
+        return
+      }
       const target = targetOf(body)
       if (target.error !== undefined) {
         sendJson(res, 400, { ok: false, error: target.error })
         return
       }
-      const key = typeof body.key === 'string' ? body.key.trim() : ''
       if (body.useDefault === true || key === '') {
         await clearKey(ctx, target.ref)
         delete state.overrides[target.ref]
@@ -1821,15 +1886,17 @@ async function handle(ctx, state, req, res) {
       let sourceRef = typeof body.ref === 'string' && body.ref !== '' ? body.ref : undefined
       if (key === undefined) {
         if (sourceRef === undefined) {
-          if (body.scope === 'session') {
+          if (body.scope === 'search-default') {
+            sourceRef = SEARCH_DEFAULT_REF
+          } else if (body.scope === 'session') {
             const sessionId = typeof body.sessionId === 'string' && body.sessionId !== '' ? body.sessionId : undefined
             const cwd = typeof body.path === 'string' && body.path !== '' ? body.path : activeCwd(ctx)
             sourceRef = channel === 'search'
-              ? searchRefFor(ctx, state, { sessionId, cwd, web })
+              ? await searchRefFor(ctx, state, { sessionId, cwd, web })
               : (sessionId === undefined ? undefined : sessionRef(sessionId))
           } else if (channel === 'search') {
             const dir = typeof body.path === 'string' && body.path !== '' ? body.path : undefined
-            sourceRef = searchRefFor(ctx, state, { cwd: dir, web })
+            sourceRef = await searchRefFor(ctx, state, { cwd: dir, web })
           } else {
             const dir = typeof body.path === 'string' ? body.path : undefined
             const overrideRef = dir !== undefined && dir !== '' ? derivedRef(dir) : undefined

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-workspace-api-key",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "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",