dsh-workspace-api-key 0.2.7 → 0.2.9

package/README.md

@@ -21,6 +21,10 @@ 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.
 
 ## How it works
 
@@ -31,6 +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, 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;
@@ -47,8 +52,10 @@ 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 |
 
 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.
 
@@ -56,13 +63,23 @@ Workspace targets may be directories that are not registered workspaces; such en
 
 ## Install
 
-Install through the market (设置 → 插件市场) once the plugin is listed, or manually:
+Install through the market (设置 → 插件市场) once the plugin is listed, or from npm:
 
 ```sh
-# in the profile directory, e.g. ~/.dsh/profiles/desktop
-pnpm add "dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key"
+# via the DSH CLI, into one profile (web, tui, ...). Desktop's own profile is
+# managed by the Electron app, so install there from its UI.
+dsh plugin --profile web add dsh-workspace-api-key
 ```
 
+The command forwards its arguments to pnpm inside the profile directory, so the equivalent manual form is:
+
+```sh
+# in the profile directory, e.g. ~/.dsh/profiles/web
+pnpm add dsh-workspace-api-key          # or: npm install dsh-workspace-api-key
+```
+
+Pin a version with `dsh-workspace-api-key@0.2.9`, 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:
 
 ```jsonc
@@ -72,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     # 136 assertions
-node test/client.test.mjs   # 145 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, and the session probe including the `{items}` envelope, the live-session fallback, and subagent and blank sessions being hidden. 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, and back-navigation when `ctx.get('layout')` only becomes available after the plugin was applied.
+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
 
@@ -84,9 +101,10 @@ Neither suite needs a running DSH process. The host suite drives `apply()` again
 - 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.
 - 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,10 @@ 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`，两份预算互不干扰；里面还画了层级，并列出了会触发提醒的几种情况。
 
 ## 实现方式
 
@@ -31,6 +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（若配了），最后才用搜索插件配置的那个 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` 与任何工作区路径都对不上；
@@ -46,9 +51,11 @@ 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}` 或一个目标，清掉失效/配额标记 |
+| POST | `/wsk-api/search-sync` | `{path, enabled}` —— 打开或关闭某个工作区的「同步搜索 API」 |
 
 只接受本机回环调用（`127.0.0.1`、`::1`、`::ffff:127.0.0.1`），且 `Origin` 必须同源或缺失。任何响应都不会包含明文 key，只有掩码。
 
@@ -56,13 +63,23 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 
 ## 安装
 
-插件被市场收录后，可以直接在「设置 → 插件市场」里一键安装；也可以手动装：
+插件被市场收录后，可以直接在「设置 → 插件市场」里一键安装；也可以从 npm 装：
 
 ```sh
-# 在 profile 目录里，例如 ~/.dsh/profiles/desktop
-pnpm add "dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key"
+# 用 DSH 自带的 CLI 装进某个 profile（web、tui……）。Desktop 自己的 profile
+# 由 Electron 应用独占管理，请在它的界面里安装。
+dsh plugin --profile web add dsh-workspace-api-key
 ```
 
+这条命令会把参数原样转交给 profile 目录里的 pnpm，等价的手写形式是：
+
+```sh
+# 在 profile 目录里，例如 ~/.dsh/profiles/web
+pnpm add dsh-workspace-api-key          # 或者：npm install dsh-workspace-api-key
+```
+
+锁版本用 `dsh-workspace-api-key@0.2.9`；直接从仓库装则用 `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key`（git 来源的插件会在安装时现场构建）。
+
 然后把 `"dsh-workspace-api-key"` 加进该 profile `package.json` 的 `dsh.profile.bundles`，重启 DSH。本地开发用 link 代替：
 
 ```jsonc
@@ -72,15 +89,16 @@ pnpm add "dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key"
 ## 测试
 
 ```sh
-node test/host.test.mjs     # 136 条断言
-node test/client.test.mjs   # 145 条断言
+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 之后才可用时返回键仍然有效。
+两个套件都不需要启动 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 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 通道，而不是瞎猜。
 - 每一层只有一把 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

@@ -110,6 +110,18 @@ window.__ModuleLoader__.load({
 .wsk-dialog .wsk-btn:hover:not(:disabled) { background: color-mix(in srgb, currentColor 8%, transparent); }
 .wsk-kv { display: flex; gap: 6px; font-size: 12px; line-height: 1.7; }
 .wsk-kv-key { color: color-mix(in srgb, currentColor 60%, transparent); flex: 0 0 auto; min-width: 74px; }
+.wsk-check { display: flex; align-items: center; gap: 6px; font-size: 11px;
+  color: var(--wsk-dim); margin-top: 5px; cursor: pointer; user-select: none; }
+.wsk-check input { margin: 0; accent-color: #2563eb; }
+.wsk-check.on { color: var(--wsk-fg, inherit); }
+.wsk-check .wsk-check-note { color: var(--wsk-faint); }
+.wsk-help { display: flex; flex-direction: column; gap: 10px; max-height: min(60vh, 520px); overflow: auto; }
+.wsk-help h4 { margin: 0; font-size: 13px; }
+.wsk-help ol, .wsk-help ul { margin: 0; padding-left: 18px; display: flex; flex-direction: column; gap: 4px; }
+.wsk-help li { font-size: 12px; line-height: 1.7; }
+.wsk-help code { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 11px; padding: 1px 4px; border-radius: 4px;
+  background: color-mix(in srgb, currentColor 10%, transparent); }
 @media (prefers-color-scheme: dark) {
   .wsk-dialog { --wsk-dialog-bg: #1f2124; --wsk-dialog-fg: #f2f2f2; }
 }
@@ -187,6 +199,24 @@ window.__ModuleLoader__.load({
       return `这把 key 是为「${key}」准备的，当前会话用的是「${session}」`
     }
 
+    /**
+     * 进入会话时要提醒的「搜索配置问题」。
+     * 这两类问题都不会立刻报错，只会在用户下一次搜索时炸掉，所以必须在入口提醒。
+     */
+    function searchIssueText(search) {
+      if (search === null || search === undefined) return undefined
+      if (search.apiChannel === true) {
+        if (search.keyConfigured === false) {
+          return '你打开了「启用新版 Web 搜索 API」，但搜索 key 还没有配置：这个会话里的搜索会直接失败。'
+        }
+        return undefined
+      }
+      if (search.leftoverKey === true) {
+        return '你配置了搜索专用的 API Key，但「启用新版 Web 搜索 API」没有打开，所以那把 key 现在不会被使用。'
+      }
+      return undefined
+    }
+
     function sessionLabel(session) {
       const title = typeof session.title === 'string' && session.title !== '' ? session.title : undefined
       return title ?? (session.blank === true ? '（空会话）' : String(session.sessionId).slice(0, 12))
@@ -484,6 +514,9 @@ window.__ModuleLoader__.load({
       const [tests, setTests] = useState({})
       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)
@@ -630,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)
@@ -653,6 +712,27 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // 「同步搜索 API」：勾上之后，该目录下所有会话的搜索/抓取请求改用本插件的
+      // 层级 key（会话 → 工作区 → 系统默认）；不勾则用官方搜索插件里配的那把 key。
+      const toggleSearchSync = async (path, enabled) => {
+        setBusy(true)
+        try {
+          applyState(await api('/search-sync', { method: 'POST', body: JSON.stringify({ path, enabled }) }))
+          if (alive.current) {
+            setNotice({
+              kind: 'ok',
+              text: enabled
+                ? '已同步：该目录下会话的搜索请求改用聊天用的那把 key（会话单独配置仍然优先）。'
+                : '已取消同步：该目录的搜索请求改用「设置 → 插件 → 网页搜索」里配置的 key。',
+            })
+          }
+        } catch (err) {
+          if (alive.current) setNotice({ kind: 'bad', text: String(err?.message ?? err) })
+        } finally {
+          if (alive.current) setBusy(false)
+        }
+      }
+
       const clearFlag = async (id, body, title) => {
         setBusy(true)
         try {
@@ -677,6 +757,8 @@ window.__ModuleLoader__.load({
       const ungrouped = view?.ungrouped ?? []
       const defaultRef = view?.defaultRef
       const providers = view?.providers ?? []
+      const searchInfo = view?.search
+      const searchWarnings = Array.isArray(searchInfo?.warnings) ? searchInfo.warnings : []
 
       // ── 诊断 ──────────────────────────────────────────────────────────────
       // 面板里「看不到可展开的会话」有两个完全不同的原因，修法也不同：
@@ -710,10 +792,16 @@ window.__ModuleLoader__.load({
         const blankDirs = Array.isArray(state.hiddenBlankDirs) && state.hiddenBlankDirs.length > 0
           ? ` · ${state.hiddenBlankDirs.length} 个目录只有空会话（未分组里不列）`
           : ''
+        const searchDiag = searchInfo === undefined
+          ? ''
+          : ` · 搜索通道：${searchInfo.apiChannel === true ? '新版 API' : 'Messages'}`
+            + `（${searchInfo.keyRef ?? '—'}${searchInfo.keyMasked ? ` · ${searchInfo.keyMasked}` : ' · 未配置'}）`
+            + (searchInfo.syncCount > 0 ? ` · 已同步 ${searchInfo.syncCount} 个目录` : '')
         return `插件 v${hostVersion} · 状态存储 v${state.storeVersion ?? '—'}`
           + ` · 宿主会话列表：${sessions}${listError}${noCwd}${subs}`
           + ` · 浏览器会话列表：${clientCount} 个${blanks}${blankDirs}`
           + ` · 工作区 ${grouped.length} + 未分组 ${ungrouped.length} · 挂在目录下的会话 ${sessionTotal}`
+          + searchDiag
       }
 
       const diagSamples = () => {
@@ -896,6 +984,34 @@ window.__ModuleLoader__.load({
                     }, verdictText(lastTest.verdict))
                   : null),
               h('div', { className: 'wsk-path' }, prettyPath(ws.path)),
+              ws.kind === 'orphan'
+                ? null
+                : h('label', {
+                    key: 'sync',
+                    className: `wsk-check${ws.searchSync === true ? ' on' : ''}`,
+                    title: '勾选后：该目录下会话的搜索/抓取请求改用聊天用的那把 key'
+                      + '（会话单独配置仍然优先）。不勾则用「设置 → 插件 → 网页搜索」里配置的 key。',
+                  },
+                  h('input', {
+                    type: 'checkbox',
+                    checked: ws.searchSync === true,
+                    disabled: busy,
+                    onChange: (ev) => toggleSearchSync(ws.path, ev.target.checked),
+                  }),
+                  h('span', null, '同步搜索 API'),
+                  h('span', { className: 'wsk-check-note' },
+                    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 || '未配置'}`,
+                    ws.searchSync === true
+                      ? `（${ws.configured === true ? '本目录专属' : '系统默认'}）`
+                      : '（搜索插件）')
+                : null,
               reason !== undefined
                 ? h('div', { className: 'wsk-hint', style: { color: 'var(--wsk-bad)', marginTop: 4 } }, reason)
                 : null),
@@ -932,6 +1048,40 @@ window.__ModuleLoader__.load({
             : null)
       }
 
+      const renderHelp = () => h(Dialog, {
+        title: '使用说明',
+        onDismiss: () => setHelp(false),
+        body: h('div', { className: 'wsk-help' },
+          h('h4', null, '推荐用法（两把 key，各管一件事）'),
+          h('ol', null,
+            h('li', null, '先到「设置 → 模型」配一把系统默认 key，例如就叫 ', h('code', null, 'default'),
+              '。没有单独配置的地方都用它聊天。'),
+            h('li', null, '再回到本页的「搜索默认 key」，放一把搜索专用的 key，例如 ', h('code', null, 'search-default'),
+              '。搜索请求默认用它，和聊天那把分开计费。'),
+            h('li', null, '平时不用再管：聊天按工作区/会话的 key 走，搜索走搜索默认 key，两边账单互不影响。')),
+          h('h4', null, '想按工作区核算搜索花费'),
+          h('ul', null,
+            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, '勾了同步，但该工作区既没有专属 key、系统默认 key 也没配 → 会提示先去配一把。')),
+          h('h4', null, '原则'),
+          h('div', { className: 'wsk-hint' },
+            '提醒只报告、不替你改 key。插件绝不会自动切换或替换你的 key，避免计费被悄悄改到别的账号上。')),
+        actions: [{ label: '知道了', primary: true, onClick: () => setHelp(false) }],
+      })
+
       const renderPrompt = () => {
         if (prompt === null) return null
         if (prompt.kind === 'no-default') {
@@ -995,6 +1145,9 @@ window.__ModuleLoader__.load({
           h('span', { className: 'wsk-title' }, 'API Key 分配'),
           h('span', { className: 'wsk-sub' }, '按工作区 / 会话隔离计费'),
           h('span', { className: 'wsk-spacer' }),
+          h('button', {
+            type: 'button', className: 'wsk-btn', onClick: () => setHelp(true),
+          }, '使用说明'),
           h('button', {
             type: 'button', className: 'wsk-btn', disabled: busy, onClick: refresh,
           }, refreshSvg(14), h('span', null, busy ? '刷新中…' : '刷新'))),
@@ -1015,6 +1168,17 @@ window.__ModuleLoader__.load({
                   '请「完全退出」DSH Desktop 再重新打开（关闭窗口 / 刷新页面都不够：宿主代码只在启动时加载）。'),
                 h('div', { className: 'wsk-hint' }, diagText()))
             : null,
+          // 搜索配置的提醒（宿主算好、界面只负责展示）：都是「不提醒的话，用户
+          // 要等搜索失败才会发现」的问题，所以放在最上面。
+          searchWarnings.map((warning, index) => h('div', {
+            key: `warn:${warning.code ?? index}`,
+            className: `wsk-msg ${warning.level === 'bad' ? 'bad' : warning.level === 'warn' ? 'warn' : 'info'}`,
+            style: { marginBottom: 12 },
+          },
+          warning.title,
+          warning.detail !== undefined
+            ? h('div', { className: 'wsk-hint' }, warning.detail)
+            : null)),
           state !== null && state.sessionListAvailable === false && clientCount === 0
             ? h('div', { className: 'wsk-msg info', style: { marginBottom: 12 } },
                 '当前 DSH 版本没有提供会话列表服务，只能按工作区配置 key。',
@@ -1058,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 } },
@@ -1088,7 +1308,8 @@ window.__ModuleLoader__.load({
             state?.statePath ? h('div', null, `状态文件：${state.statePath}`) : null,
             diagText() !== undefined ? h('div', { className: 'wsk-diag' }, diagText()) : null)),
 
-        renderPrompt())
+        renderPrompt(),
+        help ? renderHelp() : null)
     }
 
     // ─────────────────────── 进入会话时的提醒（覆盖层） ───────────────────────
@@ -1132,7 +1353,11 @@ window.__ModuleLoader__.load({
                 + (cwd === undefined ? '' : `&path=${encodeURIComponent(cwd)}`)
               const res = await api(query)
               if (disposed) return
-              if (res.needsAttention === true) setPrompt(res)
+              // 搜索配置问题也要提醒（否则用户只会在下一次搜索失败时才发现）。
+              const searchIssue = res.search?.apiChannel === true
+                ? res.search?.keyConfigured === false
+                : res.search?.leftoverKey === true
+              if (res.needsAttention === true || searchIssue === true) setPrompt(res)
             } catch {
               /* 宿主接口不可用时不打扰用户 */
             }
@@ -1203,8 +1428,13 @@ window.__ModuleLoader__.load({
         if (prompt === null) return null
         const invalid = invalidReason(prompt.invalid)
         const mismatch = mismatchText(prompt.mismatch)
+        const searchIssue = searchIssueText(prompt.search)
         return h(Dialog, {
-          title: invalid !== undefined ? '这个会话用的 API Key 已失效' : '这个会话的 API Key 可能不匹配',
+          title: invalid !== undefined
+            ? '这个会话用的 API Key 已失效'
+            : mismatch !== undefined
+              ? '这个会话的 API Key 可能不匹配'
+              : '网页搜索的配置需要确认',
           body: h('div', null,
             kv('会话', prompt.title ?? String(prompt.sessionId ?? '').slice(0, 12)),
             kv('模型', `${prompt.provider ?? '未知'} / ${prompt.model ?? '默认模型'}`),
@@ -1215,6 +1445,9 @@ window.__ModuleLoader__.load({
             mismatch !== undefined
               ? h('div', { className: 'wsk-hint', style: { marginTop: 8, color: 'var(--wsk-warn)' } }, mismatch)
               : null,
+            searchIssue !== undefined
+              ? h('div', { className: 'wsk-hint', style: { marginTop: 8, color: 'var(--wsk-warn)' } }, searchIssue)
+              : null,
             h('div', { className: 'wsk-hint', style: { marginTop: 8 } },
               '插件不会自动更换 key —— 用哪把 key 由你决定，避免计费被悄悄改到别的账号上。')),
           onDismiss: () => setPrompt(null),
@@ -1223,7 +1456,12 @@ window.__ModuleLoader__.load({
             ...(invalid !== undefined
               ? [{ label: res2Upper(prompt), onClick: useUpperLevel }]
               : []),
-            { label: invalid !== undefined ? '稍后' : '继续用当前 key', onClick: () => setPrompt(null) },
+            {
+              label: invalid !== undefined
+                ? '稍后'
+                : mismatch !== undefined ? '继续用当前 key' : '知道了',
+              onClick: () => setPrompt(null),
+            },
           ],
         })
       }

package/lib/index.js

@@ -32,6 +32,7 @@
 
 import { mkdirSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
 import { createHash } from 'node:crypto'
+import { AsyncLocalStorage } from 'node:async_hooks'
 import { homedir } from 'node:os'
 import { join, dirname, basename, resolve as pathResolve } from 'node:path'
 
@@ -50,6 +51,35 @@ const API_BASE = '/wsk-api'
 const TIMEOUT_MS = 20000
 const DEBUG = process.env.WSK_DEBUG === '1'
 
+const DEFAULT_API_KEY_REF = 'DEEPSEEK_API_KEY'
+/** 新版 Search / Fetch API（`deepseek-search-api` / `deepseek-fetch-api`）的配置命名空间。 */
+const SEARCH_API_NS = 'web-deepseek-api'
+/** 旧的「通过 Messages 搜索」provider 的配置命名空间。 */
+const LEGACY_SEARCH_NS = 'web-search-deepseek'
+/** 承载 `searchProvider` / `fetchProvider` 选择的命名空间。 */
+const WEB_NS = 'web'
+const FALLBACK_SEARCH_BASE_URL = 'https://api.deepseek.com/v1/tools'
+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`，在它们的异步调用链里
+ * 打一个 AsyncLocalStorage 标记。`credentials.resolve` 的 wrapper 据此知道
+ * 「这次取 key 是搜索/抓取在要，还是聊天在要」——两者用的是同一把
+ * `DEEPSEEK_API_KEY` 时，除此之外没有别的可靠区分方式（resolve 只收到 ref）。
+ */
+const searchScope = new AsyncLocalStorage()
+const WEB_SCOPE_MARK = Symbol.for('dsh-workspace-api-key/web-scope')
+
 // 幂等标记：同一进程里可能被 apply 多次（热重载），只装一层 wrapper。
 const INSTALL_KEY = Symbol.for('dsh-workspace-api-key/installed')
 
@@ -202,6 +232,40 @@ function effectiveOverride(ctx, state, { sessionId, cwd }) {
   return { level: 'default', ref: undefined, entry: undefined }
 }
 
+/** 该会话是否有「单独设置」的 key（搜索通道里它永远优先）。 */
+function sessionOverrideRef(state, sessionId) {
+  if (typeof sessionId !== 'string' || sessionId === '') return undefined
+  const ref = sessionRef(sessionId)
+  if (ref === undefined) return undefined
+  return state.overrides[ref] === undefined ? undefined : ref
+}
+
+/** 该目录是否勾了「同步搜索 API」。 */
+function workspaceSynced(state, cwd) {
+  const norm = normPath(cwd)
+  if (norm === undefined) return false
+  return state.searchSync?.[norm] === true
+}
+
+/**
+ * 「这个会话/目录的搜索请求会去读哪个 ref」——纯计算，不解析凭据。
+ *   新版 API 通道：会话单独 key → 工作区勾了同步 ? （工作区 key / 系统默认）: 搜索插件自己的 ref
+ *   旧 Messages 通道：搜索就在用聊天 key，固定返回搜索 ref。
+ */
+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)
+  if (own !== undefined) return own
+  if (workspaceSynced(state, cwd)) {
+    const hit = effectiveOverride(ctx, state, { sessionId, cwd })
+    return hit.ref ?? DEFAULT_API_KEY_REF
+  }
+  // 没同步：插件自己的「搜索默认 key」优先，其次才是官方搜索页配的那把。
+  const configured = searchDefault ?? (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true
+  return configured === true ? SEARCH_DEFAULT_REF : w.searchKeyEnv
+}
+
 // ───────────────── 会话列表（宿主 sessionController + live 兜底） ─────────────────
 
 /** 宿主是否挂载了会话列表 API（仅诊断用；界面看 sessionProbe.available）。 */
@@ -433,11 +497,13 @@ function stateFilePath() {
   return join(home, 'storages', 'dsh-workspace-api-key.json')
 }
 
-const STATE_VERSION = 2
+const STATE_VERSION = 3
 
 /**
  * v1 的覆盖项没有 scope/sessionId/provider 字段，读进来时补齐：
  * 有 sessionId 的算会话级，其余算工作区级。
+ * v3 新增 `searchSync`（规范路径 → true）：该工作区的搜索/抓取请求改用本插件
+ * 的层级 key（会话 → 工作区 → 系统默认），而不是官方搜索插件里配置的那把。
  */
 function normalizeState(parsed) {
   const overrides = {}
@@ -453,17 +519,27 @@ function normalizeState(parsed) {
     }
   }
   const invalid = typeof parsed?.invalid === 'object' && parsed.invalid !== null ? parsed.invalid : {}
-  return { version: STATE_VERSION, overrides, invalid }
+  const searchSync = {}
+  const rawSync = typeof parsed?.searchSync === 'object' && parsed.searchSync !== null ? parsed.searchSync : {}
+  for (const [key, value] of Object.entries(rawSync)) {
+    const norm = normPath(key)
+    if (norm !== undefined && value === true) searchSync[norm] = true
+  }
+  return { version: STATE_VERSION, overrides, invalid, searchSync }
+}
+
+function emptyState() {
+  return { version: STATE_VERSION, overrides: {}, invalid: {}, searchSync: {} }
 }
 
 function loadState() {
   const path = stateFilePath()
   try {
-    if (!existsSync(path)) return { version: STATE_VERSION, overrides: {}, invalid: {} }
+    if (!existsSync(path)) return emptyState()
     return normalizeState(JSON.parse(readFileSync(path, 'utf8')))
   } catch (err) {
     console.warn('[workspace-api-key] load state failed:', String(err?.message ?? err))
-    return { version: STATE_VERSION, overrides: {}, invalid: {} }
+    return emptyState()
   }
 }
 
@@ -563,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
@@ -586,9 +662,164 @@ function interceptableRefs(ctx, state) {
   for (const entry of Object.values(state.overrides)) {
     if (typeof entry?.ref === 'string' && entry.ref !== '') refs.add(entry.ref)
   }
+  // 搜索/抓取通道的 ref 也要拦：用户可能把「新版 Web 搜索 API」的 key 指到
+  // 独立 ref（例如 DEEPSEEK_SEARCH_API_KEY）。不拦的话，勾了「同步搜索 API」
+  // 也会静默不生效——面板显示已同步、实际还在用系统默认 key。
+  try {
+    const web = readWebSettings(ctx)
+    for (const ref of [web.apiKeyEnv, web.legacyKeyEnv]) {
+      if (typeof ref === 'string' && ref !== '') refs.add(ref)
+    }
+  } catch {
+    /* settings 不可用时只保留已知 ref */
+  }
   return refs
 }
 
+// ───────────────────────── 搜索 / 抓取通道配置 ─────────────────────────
+
+/**
+ * 读官方「插件 → 网页搜索」页写的三处配置（全部走 `ctx.get('settings').get(ns)`，
+ * 与 dsh-client-ui-settings-web-search 的 web-search-card-controller 同源）。
+ *
+ *   - `web.searchProvider` / `web.fetchProvider`：开关把它写成
+ *     `deepseek-search-api` + `deepseek-fetch-api`（新版）或 `deepseek-official` + `http`（旧的 Messages 版）。
+ *   - `web-deepseek-api.*`：新版 Search/Fetch API 的 key 引用、基础地址、每次结果数。
+ *   - `web-search-deepseek.*`：旧版 Messages 搜索的 key 引用。
+ *
+ * 官方页的密钥输入框写的是「当前选中那套 API 的 apiKeyEnv 指向的凭据」，所以
+ * 我们只要读 apiKeyEnv，就等于知道用户配的搜索 key 在哪个 ref 上。
+ */
+function readWebSettings(ctx) {
+  let settings
+  try {
+    settings = ctx.get('settings')
+  } catch {
+    settings = undefined
+  }
+  const read = (ns) => {
+    try {
+      const value = settings?.get?.(ns)
+      return typeof value === 'object' && value !== null ? value : {}
+    } catch {
+      return {}
+    }
+  }
+  const api = read(SEARCH_API_NS)
+  const legacy = read(LEGACY_SEARCH_NS)
+  const web = read(WEB_NS)
+
+  const apiKeyEnv = typeof api.apiKeyEnv === 'string' && api.apiKeyEnv !== '' ? api.apiKeyEnv : DEFAULT_API_KEY_REF
+  const legacyKeyEnv = typeof legacy.apiKeyEnv === 'string' && legacy.apiKeyEnv !== '' ? legacy.apiKeyEnv : DEFAULT_API_KEY_REF
+  const baseURL = typeof api.baseURL === 'string' && api.baseURL !== '' ? api.baseURL : FALLBACK_SEARCH_BASE_URL
+  const searchProvider = typeof web.searchProvider === 'string' && web.searchProvider !== ''
+    ? web.searchProvider
+    : FALLBACK_SEARCH_PROVIDER
+  const fetchProvider = typeof web.fetchProvider === 'string' && web.fetchProvider !== ''
+    ? web.fetchProvider
+    : 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
+  return {
+    apiKeyEnv,
+    legacyKeyEnv,
+    apiLiteralKey,
+    legacyLiteralKey,
+    baseURL,
+    searchProvider,
+    fetchProvider,
+    count: typeof api.count === 'number' ? api.count : 10,
+    /** 新版 Search/Fetch API 是否被选中（官方开关）= provider 选择被改成了 API 版。 */
+    apiChannel: searchProvider === SEARCH_PROVIDER_ID || fetchProvider === SEARCH_FETCH_PROVIDER_ID,
+    /** 搜索请求真正会用的那套配置的 key 引用。 */
+    searchKeyEnv: searchProvider === SEARCH_PROVIDER_ID ? apiKeyEnv : legacyKeyEnv,
+    searchLiteralKey: searchProvider === SEARCH_PROVIDER_ID ? apiLiteralKey : legacyLiteralKey,
+  }
+}
+
+/**
+ * 面板顶部要展示的「该提醒但容易忽略」的搜索配置问题。
+ *
+ * 只报告，不改任何配置——每一条都能自己解释清楚「为什么」和「怎么修」。
+ */
+async function searchWarnings(ctx, state, web) {
+  const 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
+  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) {
+    out.push({
+      code: 'search-key-idle',
+      level: 'warn',
+      title: '搜索 key 已配置，但「启用新版 Web 搜索 API」没打开',
+      detail: `当前搜索走的是 DeepSeek Messages 通道（provider: ${web.searchProvider}），`
+        + `所以 ${web.apiKeyEnv} 这把 key 不会被使用。要让它生效，请到「设置 → 插件 → 网页搜索」打开那个开关；`
+        + '若暂时不想用新版 API，可以忽略本条。',
+    })
+  }
+
+  // 2) 开了新版 API，却没有可用的搜索 key → 搜索会直接报缺少凭据。
+  if (web.apiChannel && web.apiLiteralKey === undefined && !apiKeyConfigured && !searchDefaultConfigured) {
+    out.push({
+      code: 'search-key-missing',
+      level: 'bad',
+      title: '新版 Web 搜索 API 已启用，但搜索 key 没有配置',
+      detail: `搜索会用 ${web.apiKeyEnv} 去取 key，而它当前是空的：任何 web_search 都会失败。`
+        + '到「设置 → 插件 → 网页搜索」里填一把，或把该 ref 指向已有的 key。',
+    })
+  }
+
+  // 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)
+  const dryWorkspaces = []
+  for (const norm of syncPaths) {
+    const wsRef = derivedRef(norm)
+    const hasWorkspaceKey = wsRef !== undefined && state.overrides[wsRef] !== undefined
+    if (!hasWorkspaceKey && !defaultConfigured) dryWorkspaces.push(norm)
+  }
+  if (dryWorkspaces.length > 0) {
+    out.push({
+      code: 'search-sync-no-key',
+      level: 'warn',
+      title: `${dryWorkspaces.length} 个已同步的工作区没有可用的 key`,
+      detail: '这些工作区勾了「同步搜索 API」，但既没有工作区专属 key，系统默认 key 也没配置：'
+        + '搜索会用空 key 发出去。给这些工作区各配一把，或先配好系统默认 key。',
+      paths: dryWorkspaces,
+    })
+  }
+
+  // 4) 勾了同步，但当前还是旧的 Messages 通道 → 同步开关对搜索没有区别
+  //    （旧通道本来就解析聊天用的 ref，层级 key 一直生效）。
+  if (!web.apiChannel && syncPaths.length > 0) {
+    out.push({
+      code: 'search-sync-legacy',
+      level: 'info',
+      title: '「同步搜索 API」现在没有区别',
+      detail: '当前搜索走旧的 Messages 通道，它本来就用聊天通道的 key（会话 → 工作区 → 系统默认），'
+        + '所以这个开关只影响「启用新版 Web 搜索 API」之后的行为。',
+    })
+  }
+
+  return out
+}
+
 // ─────────────────────────── 失效判定 ───────────────────────────
 
 function classifyFailure(failure) {
@@ -786,12 +1017,84 @@ async function probeKey(ctx, key) {
   return { ok: false, verdict: 'error', status: res.status, latencyMs, detail: `${sanitizeDetail(raw) ?? `HTTP ${res.status}`}${hint}` }
 }
 
-// ─────────────────────────── 插件主体 ───────────────────────────
+/**
+ * 验证「新版 Web 搜索 API」这条通道：`POST {baseURL}/search`，最小请求。
+ * 与搜索插件自己的调用形状一致（`{ query, count, need_content }`），所以 200 就
+ * 说明「key 有效 + 端点正确 + 开关真的生效」三件事同时成立。
+ */
+async function probeSearch(ctx, state, key, web) {
+  const base = String(web?.baseURL ?? FALLBACK_SEARCH_BASE_URL).replace(/\/+$/u, '')
+  const endpoint = `${base}/search`
+  const started = Date.now()
+  let res
+  try {
+    res = await fetch(endpoint, {
+      method: 'POST',
+      redirect: 'error',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'application/json',
+        authorization: `Bearer ${key}`,
+      },
+      body: JSON.stringify({ query: 'deepseek', count: 1, need_content: false }),
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    })
+  } catch (err) {
+    const message = String(err?.message ?? err)
+    const timedOut = err?.name === 'TimeoutError' || err?.name === 'AbortError'
+    return {
+      ok: false,
+      verdict: 'unreachable',
+      status: 0,
+      latencyMs: Date.now() - started,
+      detail: timedOut ? `请求超时（${TIMEOUT_MS}ms）：${endpoint}` : `${message}（${endpoint}）`,
+    }
+  }
 
+  const latencyMs = Date.now() - started
+  const raw = await res.text().catch(() => '')
+  if (res.ok) {
+    let count
+    try {
+      const parsed = JSON.parse(raw)
+      count = Array.isArray(parsed?.results) ? parsed.results.length : undefined
+    } catch {
+      /* 非 JSON 也算成功 */
+    }
+    return {
+      ok: true,
+      verdict: 'ok',
+      status: res.status,
+      latencyMs,
+      detail: `搜索通道正常${count === undefined ? '' : `，返回 ${count} 条结果`}（${endpoint}）`,
+    }
+  }
+  if (res.status === 401 || res.status === 403) {
+    return { ok: false, verdict: 'invalid', status: res.status, latencyMs, detail: sanitizeDetail(raw) ?? 'key 无效（401/403）' }
+  }
+  if (res.status === 402) {
+    return { ok: false, verdict: 'quota', status: res.status, latencyMs, detail: sanitizeDetail(raw) ?? '余额/配额不足（402）' }
+  }
+  if (res.status === 429) {
+    return { ok: false, verdict: 'rate-limit', status: res.status, latencyMs, detail: sanitizeDetail(raw) ?? '被限流（429），但 key 本身可能有效' }
+  }
+  if (res.status === 400) {
+    return { ok: true, verdict: 'ok', status: res.status, latencyMs, detail: `鉴权通过（HTTP 400：${sanitizeDetail(raw) ?? '请求参数被拒'}）` }
+  }
+  const hint = res.status === 404
+    ? `（404：端点 ${endpoint} 不存在，检查「Search / Fetch API 基础地址」）`
+    : web?.apiChannel === false
+      ? `（${endpoint}；当前搜索通道是 Messages 版，新版 API 可能还没启用）`
+      : `（${endpoint}）`
+  return { ok: false, verdict: 'error', status: res.status, latencyMs, detail: `${sanitizeDetail(raw) ?? `HTTP ${res.status}`}${hint}` }
+}
+
+// ─────────────────────────── 插件主体 ───────────────────────────
 export function apply(ctx) {
   const state = loadState()
 
-  // ── 1. 包装 credentials.resolve ──────────────────────────────────────
+  // ── 1. 包装 credentials.resolve + 标记搜索/抓取通道 ─────────────────
+  installWebScope(ctx)
   installResolver(ctx, state)
 
   // ── 2. REST API（loopback 可信）──────────────────────────────────────
@@ -842,6 +1145,54 @@ export function apply(ctx) {
   )
 }
 
+/**
+ * 装上搜索/抓取通道标记：把 `ctx.web.search` / `ctx.web.fetch` 包一层
+ * AsyncLocalStorage，让 resolve wrapper 知道「这次取 key 的是搜索，不是聊天」。
+ * 装不上就静默跳过——不影响任何既有行为（只是无法区分通道）。
+ */
+function installWebScope(ctx) {
+  if (globalThis[WEB_SCOPE_MARK] !== undefined) {
+    log('web scope already installed; skipping')
+    return
+  }
+  let web
+  try {
+    web = ctx.get('web')
+  } catch {
+    web = undefined
+  }
+  if (web === undefined) return
+
+  const originals = {}
+  for (const method of ['search', 'fetch']) {
+    if (typeof web[method] !== 'function') continue
+    const original = web[method].bind(web)
+    originals[method] = original
+    try {
+      web[method] = (...args) => searchScope.run(true, () => original(...args))
+    } catch {
+      delete originals[method]
+    }
+  }
+  if (Object.keys(originals).length === 0) return
+
+  globalThis[WEB_SCOPE_MARK] = { web, originals }
+  ctx.effect(
+    () => () => {
+      for (const [method, original] of Object.entries(originals)) {
+        try {
+          web[method] = original
+        } catch {
+          /* ignore */
+        }
+      }
+      delete globalThis[WEB_SCOPE_MARK]
+    },
+    'workspace-api-key: restore web.search/fetch',
+  )
+  log(`web scope wrapped: ${Object.keys(originals).join(',')}`)
+}
+
 /**
  * 装上 resolve wrapper。装不上也不能影响宿主：任何异常都吞掉并退回原行为。
  */
@@ -866,8 +1217,50 @@ function installResolver(ctx, state) {
   const wrapped = async (ref /*, ...rest */) => {
     try {
       if (!interceptableRefs(ctx, state).has(ref)) return await original(ref)
+      const sessionId = activeSessionId(ctx)
+      const cwd = activeCwd(ctx)
+
+      // 搜索 / 抓取通道：官方「新版 Web 搜索 API」用的是独立的一套 key 配置，
+      // 语义与聊天不同，因此单独处理（旧 Messages 通道仍走下面的聊天层级）。
+      if (searchScope.getStore() === true) {
+        const web = readWebSettings(ctx)
+        if (web.apiChannel) {
+          // ① 会话单独设置的 key 永远优先——哪怕官方搜索插件里配了别的 key。
+          const sessionKey = sessionOverrideRef(state, sessionId)
+          if (sessionKey !== undefined) {
+            const value = await original(sessionKey)
+            if (value?.value !== undefined && value.value !== '') {
+              log(`search ref ${ref} → ${sessionKey} (session)`)
+              return value
+            }
+          }
+          // ② 工作区勾了「同步搜索 API」：按会话 → 工作区 → 系统默认的层级。
+          if (workspaceSynced(state, cwd)) {
+            const hit = effectiveOverride(ctx, state, { sessionId, cwd })
+            if (hit.ref !== undefined && hit.level !== 'default') {
+              const value = await original(hit.ref)
+              if (value?.value !== undefined && value.value !== '') {
+                log(`search ref ${ref} → ${hit.ref} (${hit.level}, synced)`)
+                return value
+              }
+            }
+            const fallback = await original(DEFAULT_API_KEY_REF)
+            if (fallback?.value !== undefined && fallback.value !== '') return fallback
+          }
+          // ③ 没同步：插件面板里配的「搜索默认 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)
+        }
+      }
+
       // 1) 会话级覆盖优先，2) 再工作区级，3) 都没有就用系统默认（原 ref）。
-      const hit = effectiveOverride(ctx, state, { sessionId: activeSessionId(ctx), cwd: activeCwd(ctx) })
+      const hit = effectiveOverride(ctx, state, { sessionId, cwd })
       if (hit.ref !== undefined && hit.level !== 'default') {
         const value = await original(hit.ref)
         if (value?.value !== undefined && value.value !== '') {
@@ -1016,6 +1409,10 @@ async function sessionRow(ctx, state, row, fallbackCwd) {
     effectiveTitle: eff.entry?.title,
     invalid: eff.ref !== undefined ? state.invalid[eff.ref] ?? null : null,
     mismatch: mismatchOf(eff.entry, selection),
+    // 搜索通道：该会话所在目录是否勾了「同步搜索 API」，以及本会话是否另有
+    // 单独的 key（单独设置永远优先于工作区同步与官方搜索插件里的 key）。
+    searchSync: workspaceSynced(state, cwd),
+    sessionSearchKey: sessionOverrideRef(state, sessionId) !== undefined,
   }
 }
 
@@ -1031,6 +1428,22 @@ async function workspaceRow(ctx, state, { id, path: dir, title, kind }, rows, cl
   }
   sessions.sort((left, right) => (right.updatedAt ?? 0) - (left.updatedAt ?? 0))
   if (claimed !== undefined) claimed.add(normPath(dir))
+  // 搜索通道：只有新版 Search/Fetch API 才有「同步 / 不同步」的区别（旧 Messages
+  // 通道本来就用聊天 key）。这里给出「该工作区的搜索请求实际会用哪把 key」，
+  // 让用户勾了复选框之后马上能看到效果，而不用等到搜索失败才发现。
+  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
+      : searchDefaultConfigured
+        ? SEARCH_DEFAULT_REF
+        : web.searchKeyEnv
+    : web.searchKeyEnv
+  const searchKeyMasked = web.apiChannel ? maskKey((await resolveKey(ctx, searchKeyRef))?.value) : undefined
   return {
     id,
     path: dir,
@@ -1044,6 +1457,9 @@ async function workspaceRow(ctx, state, { id, path: dir, title, kind }, rows, cl
     overrideProvider: configured ? state.overrides[ref]?.provider : undefined,
     invalid: ref !== undefined ? state.invalid[ref] ?? null : null,
     exists: typeof dir === 'string' ? existsSync(dir) : false,
+    searchSync: synced,
+    searchKeyRef,
+    searchKeyMasked,
     sessions,
   }
 }
@@ -1157,6 +1573,16 @@ async function snapshot(ctx, state) {
     })
   }
 
+  // ── 搜索 / 抓取通道总览 ──────────────────────────────────────────────
+  const web = readWebSettings(ctx)
+  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)
+
   return {
     ok: true,
     pluginVersion: PLUGIN_VERSION,
@@ -1193,6 +1619,31 @@ async function snapshot(ctx, state) {
     // 因为「当前打开的空会话」要显示，而这件事只有浏览器端知道）。
     hiddenBlankDirs,
     sessionOverrides,
+    // 搜索 / 抓取通道：官方「设置 → 插件 → 网页搜索」里的配置 + 本插件怎么参与。
+    // 面板据此显示通道、生效 key 与提醒；不暴露任何明文。
+    search: {
+      channel: web.apiChannel ? 'api' : 'messages',
+      apiChannel: web.apiChannel,
+      searchProvider: web.searchProvider,
+      fetchProvider: web.fetchProvider,
+      baseURL: web.baseURL,
+      count: web.count,
+      keyRef: searchKeyRef,
+      keyRefConfigured: searchKeyInfo.configured === true,
+      keyMasked: maskKey(searchKeyHit?.value),
+      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,
+    },
   }
 }
 
@@ -1266,6 +1717,7 @@ async function checkSession(ctx, state, params) {
   const sessionEntry = sid !== undefined ? state.overrides[sessionRef(sid)] : undefined
   const ws = locateWorkspace(ctx, cwd)
   const wsRef = ws !== undefined ? derivedRef(ws.path) : undefined
+  const searchState = await searchStateOf(ctx, state, { sessionId: sid, cwd })
   return {
     ok: true,
     sessionId: sid ?? null,
@@ -1295,6 +1747,27 @@ async function checkSession(ctx, state, params) {
     },
     defaultRef: { ref: defaultRefName, configured: defaultInfo.configured === true },
     providers: providerList(ctx),
+    // 搜索通道：进会话时若搜索配置有问题，界面要能立刻提醒（而不是等到搜索失败）。
+    search: searchState,
+  }
+}
+
+/** 进会话提醒用的搜索通道摘要（不含明文 key）。 */
+async function searchStateOf(ctx, state, { sessionId, cwd }) {
+  const web = readWebSettings(ctx)
+  const sync = workspaceSynced(state, cwd)
+  if (!web.apiChannel) {
+    const idle = web.apiLiteralKey !== undefined
+      || (web.apiKeyEnv !== DEFAULT_API_KEY_REF && (await describeKey(ctx, web.apiKeyEnv)).configured === true)
+    return { channel: 'messages', apiChannel: false, sync, leftoverKey: idle }
+  }
+  return {
+    channel: 'api',
+    apiChannel: true,
+    sync,
+    ref: await searchRefFor(ctx, state, { sessionId, cwd, web }),
+    sessionOwnKey: sessionOverrideRef(state, sessionId) !== undefined,
+    keyConfigured: (await describeKey(ctx, await searchRefFor(ctx, state, { sessionId, cwd, web }))).configured === true,
   }
 }
 
@@ -1349,12 +1822,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]
@@ -1382,27 +1870,41 @@ async function handle(ctx, state, req, res) {
 
     if (pathname === `${API_BASE}/test` && method === 'POST') {
       const body = await readJson(req)
+      const web = readWebSettings(ctx)
+      const channel = body.channel === 'search' ? 'search' : 'chat'
       let key = typeof body.key === 'string' && body.key.trim() !== '' ? body.key.trim() : undefined
       let sourceRef = typeof body.ref === 'string' && body.ref !== '' ? body.ref : undefined
       if (key === undefined) {
         if (sourceRef === undefined) {
-          if (body.scope === 'session') {
-            sourceRef = typeof body.sessionId === 'string' && body.sessionId !== '' ? sessionRef(body.sessionId) : undefined
+          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'
+              ? 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 = 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
             sourceRef = overrideRef !== undefined && state.overrides[overrideRef] !== undefined ? overrideRef : undefined
           }
         }
-        if (sourceRef === undefined) sourceRef = 'DEEPSEEK_API_KEY'
+        if (sourceRef === undefined) sourceRef = DEFAULT_API_KEY_REF
         const hit = await resolveKey(ctx, sourceRef)
         key = hit?.value
       }
       if (typeof key !== 'string' || key === '') {
-        sendJson(res, 400, { ok: false, error: `没有可测试的 key（ref=${sourceRef ?? '未知'}）` })
+        const hint = channel === 'search'
+          ? `（ref=${sourceRef ?? '未知'}；新版 Web 搜索 API 已启用但该 ref 没有值，搜索会直接失败）`
+          : `（ref=${sourceRef ?? '未知'}）`
+        sendJson(res, 400, { ok: false, error: `没有可测试的 key${hint}` })
         return
       }
-      const result = await probeKey(ctx, key)
+      const result = channel === 'search' ? await probeSearch(ctx, state, key, web) : await probeKey(ctx, key)
       const isOverrideRef = sourceRef !== undefined && state.overrides[sourceRef] !== undefined
       if (result.verdict === 'invalid') {
         if (isOverrideRef) {
@@ -1427,6 +1929,27 @@ async function handle(ctx, state, req, res) {
       return
     }
 
+    if (pathname === `${API_BASE}/search-sync` && method === 'POST') {
+      const body = await readJson(req)
+      const dir = typeof body.path === 'string' ? body.path : undefined
+      if (dir === undefined || dir === '') {
+        sendJson(res, 400, { ok: false, error: '缺少 path' })
+        return
+      }
+      const norm = normPath(dir)
+      if (norm === undefined) {
+        sendJson(res, 400, { ok: false, error: '无法规范化该路径' })
+        return
+      }
+      const enabled = body.enabled !== false
+      if (enabled) state.searchSync[norm] = true
+      else delete state.searchSync[norm]
+      saveState(state)
+      log(`search sync ${enabled ? 'on' : 'off'}: ${dir}`)
+      sendJson(res, 200, { ok: true, enabled, ...(await snapshot(ctx, state)) })
+      return
+    }
+
     if (pathname === `${API_BASE}/clear-flag` && method === 'POST') {
       const body = await readJson(req)
       let ref = typeof body.ref === 'string' && body.ref !== '' ? body.ref : undefined

package/package.json

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