dsh-workspace-api-key 0.2.7 → 0.2.8

package/README.md

@@ -21,6 +21,9 @@ 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 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 +34,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;
 - 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;
@@ -49,6 +53,7 @@ The browser half (`lib/client.js`) registers into the `sidebar.panellist` slot (
 | 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/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 +61,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.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).
+
 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 +87,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     # 157 assertions
+node test/client.test.mjs   # 162 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 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.
 
 ## Requirements and limits
 
@@ -84,6 +99,7 @@ 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.

package/README.zh.md

@@ -21,6 +21,9 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 - **不匹配提醒** —— 如果绑 key 时记下的是某个服务商（比如 `deepseek-official`），而该会话现在跑在另一个服务商上，点进这个会话时会提醒你，因为那次请求会拿着对方不认的 key 发出去。
 - **绝不悄悄换 key** —— 两种提醒都不会改动实际使用的 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 +34,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 请求；
 - 会话列表来自 `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` 与任何工作区路径都对不上；
@@ -49,6 +53,7 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 | 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 +61,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.8`；直接从仓库装则用 `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 +87,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     # 157 条断言
+node test/client.test.mjs   # 162 条断言
 ```
 
-两个套件都不需要启动 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 压过两者、两类搜索提醒，以及搜索连接测试。浏览器套件覆盖搜索相关界面：每个工作区行的「同步搜索 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,7 @@ window.__ModuleLoader__.load({
       const [tests, setTests] = useState({})
       const [notice, setNotice] = useState(null)
       const [prompt, setPrompt] = useState(null)
+      const [help, setHelp] = useState(false)
       const [expanded, setExpanded] = useState(() => new Set())
 
       const alive = useRef(true)
@@ -653,6 +684,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 +729,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 +764,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 +956,30 @@ 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' : '搜索用搜索插件里的 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 +1016,41 @@ 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, '再到「设置 → 插件 → 网页搜索」打开「启用新版 Web 搜索 API」，',
+              '并在那里的 API Key 里配一把搜索专用的 key，例如 ', h('code', null, 'search-default'), '。'),
+            h('li', null, '平时不用再管：聊天用工作区/会话的 key，搜索用 ', h('code', null, 'search-default'),
+              '，两边计费互不影响。')),
+          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('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 +1114,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 +1137,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。',
@@ -1088,7 +1221,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 +1266,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 +1341,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 +1358,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 +1369,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,28 @@ 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'
+
+/**
+ * 搜索通道标记：包住 `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 +225,38 @@ 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。
+ */
+function searchRefFor(ctx, state, { sessionId, cwd, web }) {
+  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
+  }
+  return w.searchKeyEnv
+}
+
 // ───────────────── 会话列表（宿主 sessionController + live 兜底） ─────────────────
 
 /** 宿主是否挂载了会话列表 API（仅诊断用；界面看 sessionProbe.available）。 */
@@ -433,11 +488,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 +510,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()
   }
 }
 
@@ -586,9 +653,151 @@ 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)
+
+  // 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) {
+    out.push({
+      code: 'search-key-missing',
+      level: 'bad',
+      title: '新版 Web 搜索 API 已启用，但搜索 key 没有配置',
+      detail: `搜索会用 ${web.apiKeyEnv} 去取 key，而它当前是空的：任何 web_search 都会失败。`
+        + '到「设置 → 插件 → 网页搜索」里填一把，或把该 ref 指向已有的 key。',
+    })
+  }
+
+  // 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 +995,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 +1123,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 +1195,43 @@ 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（原样解析）。
+          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 +1380,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 +1399,19 @@ 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 searchKeyRef = web.apiChannel
+    ? synced
+      ? configured
+        ? ref
+        : DEFAULT_API_KEY_REF
+      : web.searchKeyEnv
+    : web.searchKeyEnv
+  const searchKeyMasked = web.apiChannel ? maskKey((await resolveKey(ctx, searchKeyRef))?.value) : undefined
   return {
     id,
     path: dir,
@@ -1044,6 +1425,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 +1541,14 @@ 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 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 +1585,25 @@ 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,
+      syncCount: syncPaths.length,
+      syncPaths,
+      warnings,
+    },
   }
 }
 
@@ -1266,6 +1677,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 +1707,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: searchRefFor(ctx, state, { sessionId, cwd, web }),
+    sessionOwnKey: sessionOverrideRef(state, sessionId) !== undefined,
+    keyConfigured: (await describeKey(ctx, searchRefFor(ctx, state, { sessionId, cwd, web }))).configured === true,
   }
 }
 
@@ -1382,27 +1815,39 @@ 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
+            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 })
+              : (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 })
           } 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 +1872,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.8",
   "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",