dsh-workspace-api-key 0.2.11 → 0.2.13

package/README.md

@@ -21,7 +21,8 @@ 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 default key of its own** — the `搜索默认 key` card binds a key to `DEEPSEEK_API_KEY_SEARCH`, so search can be billed apart from chat: a session's own key wins, then a synced workspace's chat cascade, then this key, then whatever the official search page stores.
+- **Takes over the official search key field, once there is a key to put there** — on startup, while the new Web Search API is on, the plugin points the official `web-deepseek-api` / `web-search-deepseek` entry at `DEEPSEEK_API_KEY_SEARCH` (only that `apiKeyEnv` pointer, never a key value). The `设置 → 插件 → 网页搜索` field then edits the same search key this panel does, so it can no longer overwrite your chat key, and there is no second place where a search key can hide. Until you save a search key, the official entry keeps pointing at the chat key, so upgrading never breaks `web_search`; the panel says so instead of failing silently.
 - **A search switch per workspace** — every workspace row carries a `同步搜索 API` checkbox. Ticked, the `web_search` / `web_fetch` calls made by sessions in that directory use the key they would use for chat (`session → workspace → system default`); unticked, they keep the key the official 设置 → 插件 → 网页搜索 page manages. A session with its own key always wins, so "sync on, session configured separately" spends the session key, not the search key.
 - **Search warnings that arrive before the failure** — when a search key is configured but `启用新版 Web 搜索 API` is off, or when the new API is on but its key ref is empty, the panel shows a warning banner and the entering-session overlay says it too, in one line you can act on. The overlay stays quiet about search problems when the search provider is not the one in use.
 - **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.
@@ -78,7 +79,7 @@ The command forwards its arguments to pnpm inside the profile directory, so the
 pnpm add dsh-workspace-api-key          # or: npm install dsh-workspace-api-key
 ```
 
-Pin a version with `dsh-workspace-api-key@0.2.11`, or install straight from the repository with `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key` (a git-hosted plugin is built from source on install).
+Pin a version with `dsh-workspace-api-key@0.2.13`, 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:
 
@@ -89,8 +90,8 @@ Then add `"dsh-workspace-api-key"` to `dsh.profile.bundles` in that profile's `p
 ## Tests
 
 ```sh
-node test/host.test.mjs     # 165 assertions
-node test/client.test.mjs   # 170 assertions
+node test/host.test.mjs     # 175 assertions
+node test/client.test.mjs   # 173 assertions
 ```
 
 Neither suite needs a running DSH process. The host suite drives `apply()` against a mock context (fake `credentials`, `workspaceRegistry`, `agents`, `sessionController`, `sessions`, `webServer`, stubbed `fetch`) and covers ref derivation, the session → workspace → default cascade, workspace matching, redirecting a second adapter's `apiKeyEnv`, clearing back to the default, 401/402/429/5xx classification, the loopback and origin checks, state persistence, the session probe including the `{items}` envelope, the live-session fallback, and subagent and blank sessions being hidden, and the search scope with a stand-in `web` service and a stand-in settings service: the legacy route keeping the chat cascade, the new provider keeping its own key, the workspace switch taking over, a session key outranking both, the 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.

package/README.zh.md

@@ -21,7 +21,8 @@ DSH 只从一个全局凭据 ref（默认 `DEEPSEEK_API_KEY`）解析 DeepSeek k
 - **不匹配提醒** —— 如果绑 key 时记下的是某个服务商（比如 `deepseek-official`），而该会话现在跑在另一个服务商上，点进这个会话时会提醒你，因为那次请求会拿着对方不认的 key 发出去。
 - **绝不悄悄换 key** —— 两种提醒都不会改动实际使用的 key，决定权始终在你手上；自动替换会直接破坏「按会话分离计费」这个初衷。
 - **一键回退** —— 清空会话条目回到工作区 key，清空工作区条目回到系统默认。
-- **搜索默认 key 单独一把** —— 「搜索默认 key」卡片把这把 key 绑到 `DEEPSEEK_API_KEY_SEARCH`，于是搜索可以和聊天分开计费，而且不用去改官方配置：会话自己的 key 最优先，其次勾了同步的工作区走聊天层级，再次是这把搜索默认 key，最后才是官方搜索页里配的那把。
+- **搜索默认 key 单独一把** —— 「搜索默认 key」卡片把这把 key 绑到 `DEEPSEEK_API_KEY_SEARCH`，于是搜索可以和聊天分开计费：会话自己的 key 最优先，其次勾了同步的工作区走聊天层级，再次是这把搜索默认 key，最后才是官方搜索页里配的那把。
+- **接管官方搜索 key 设置（先有 key 才接管）** —— 启动时若已启用新版 Web 搜索 API，插件把官方 `web-deepseek-api` / `web-search-deepseek` 条目的 `apiKeyEnv` 指到 `DEEPSEEK_API_KEY_SEARCH`（只改这一个指向，永远不动 key 内容）。此后「设置 → 插件 → 网页搜索」里填的就是本面板这把搜索 key，既不会再顶掉聊天 key，也不存在第二处藏搜索 key 的地方。还没配搜索 key 时，官方条目继续指着聊天那把，所以升级不会让 `web_search` 直接失效，面板会如实提醒「搜索暂时和聊天共用一把 key」。
 - **每个工作区一个搜索开关** —— 每个工作区行上都有「同步搜索 API」复选框。勾选后，该目录下会话发出的 `web_search` / `web_fetch` 请求改用它们聊天时用的那把 key（会话 → 工作区 → 系统默认）；不勾选则继续用官方「设置 → 插件 → 网页搜索」里配置的那把 key。会话自己配了 key 时永远优先，所以「工作区同步、会话单独设置」花的是会话那把 key，而不是搜索默认 key。
 - **在失败之前就提醒的搜索告警** —— 配了搜索 key 但没打开「启用新版 Web 搜索 API」，或者新版 API 打开了但它的 key ref 是空的，面板会显示提醒条，点进会话时的覆盖层也会用一句可直接照做的话说明；当生效的搜索通道不是新版 API 时，覆盖层不会拿搜索问题打扰你。
 - **使用说明** —— 面板顶部有「使用说明」，推荐两把 key 分工：聊天默认用 `default`，搜索默认用 `search-default`，两份预算互不干扰；里面还画了层级，并列出了会触发提醒的几种情况。
@@ -78,7 +79,7 @@ dsh plugin --profile web add dsh-workspace-api-key
 pnpm add dsh-workspace-api-key          # 或者：npm install dsh-workspace-api-key
 ```
 
-锁版本用 `dsh-workspace-api-key@0.2.11`；直接从仓库装则用 `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key`（git 来源的插件会在安装时现场构建）。
+锁版本用 `dsh-workspace-api-key@0.2.13`；直接从仓库装则用 `dsh-workspace-api-key@github:COH2357/dsh-workspace-api-key`（git 来源的插件会在安装时现场构建）。
 
 然后把 `"dsh-workspace-api-key"` 加进该 profile `package.json` 的 `dsh.profile.bundles`，重启 DSH。本地开发用 link 代替：
 
@@ -89,8 +90,8 @@ pnpm add dsh-workspace-api-key          # 或者：npm install dsh-workspace-api
 ## 测试
 
 ```sh
-node test/host.test.mjs     # 165 条断言
-node test/client.test.mjs   # 170 条断言
+node test/host.test.mjs     # 175 条断言
+node test/client.test.mjs   # 173 条断言
 ```
 
 两个套件都不需要启动 DSH。宿主套件用一个假 ctx（假的 `credentials`、`workspaceRegistry`、`agents`、`sessionController`、`sessions`、`webServer`，以及打桩的 `fetch`）驱动 `apply()`，覆盖 ref 派生、会话→工作区→默认的级联、工作区匹配、把第二个适配器的 `apiKeyEnv` 一起重定向、清回默认、401/402/429/5xx 的判定、回环与来源校验、状态落盘，以及会话探针（含 `{items}` 信封与 live 兜底）。浏览器套件通过一个极小的 `window.__ModuleLoader__` 与自制 React 运行时加载 `lib/client.js`，渲染出面板与覆盖层，断言槽注册、首屏渲染、会话折叠/展开、会话级保存与测试、宿主列不出会话时从浏览器端存储恢复会话（标题取 `displayTitle`、隐藏子代理会话与空会话、浏览器端只认识一部分会话时不挤掉宿主行）、会话列表服务晚于插件提供时的重试、未分组目录卡片、失效与不匹配提醒、「去配置」的交接、没有会话列表时的降级，以及 `ctx.get('layout')` 在插件 apply 之后才可用时返回键仍然有效。宿主套件还带一个假的 `web` 服务与假的设置服务，验证搜索作用域：旧通道沿用聊天层级、新版通道用它自己的 key、工作区开关接管、会话 key 压过两者、面板自己的搜索默认 key 生效与清除、三类搜索提醒，以及搜索连接测试。浏览器套件覆盖搜索相关界面：每个工作区行的「同步搜索 API」复选框、它发出的 `/wsk-api/search-sync`、提醒条与「使用说明」弹窗。

package/lib/client.js

@@ -676,12 +676,39 @@ window.__ModuleLoader__.load({
           applyState(next)
           setSearchDraft('')
           if (trimmed === '') setSearchOpen(false)
-          setNotice({
-            kind: 'ok',
-            text: trimmed === ''
-              ? '搜索默认 key 已清除：搜索改用官方搜索页里配的那把 key。'
-              : '搜索默认 key 已保存：搜索请求优先用它（工作区同步与会话单独配置仍然优先）。',
-          })
+          const bound = next?.bound
+          if (trimmed === '') {
+            setNotice({ kind: 'ok', text: '搜索默认 key 已清除：搜索改用官方搜索页里配的那把 key。' })
+          } else if (bound?.ok === false) {
+            setNotice({
+              kind: 'warn',
+              text: `key 已保存在 ${next?.search?.defaultRef ?? '搜索默认 ref'}，但没能改官方设置（${bound.reason}）：`
+                + '官方「网页搜索」页仍指向原来的 ref，两处暂时不是同一把。',
+            })
+          } else {
+            setNotice({
+              kind: 'ok',
+              text: `搜索默认 key 已保存到 ${next?.search?.defaultRef ?? '搜索默认 ref'}，`
+                + '官方「网页搜索」页的 API Key 输入框也指向这个 ref：以后两边改的是同一把 key。',
+            })
+          }
+        } catch (err) {
+          if (alive.current) setNotice({ kind: 'bad', text: `${err?.message ?? err}` })
+        } finally {
+          if (alive.current) setBusy(false)
+        }
+      }
+
+      // 只把官方网页搜索页的 ref 指到插件自有 ref（key 已经在库里，只是官方页看不到）。
+      const syncSearchDefault = async () => {
+        setBusy(true)
+        try {
+          const next = await api('/set', { method: 'POST', body: JSON.stringify({ scope: 'search-default', adopt: true }) })
+          applyState(next)
+          const bound = next?.bound
+          setNotice(bound?.ok === false
+            ? { kind: 'warn', text: `没能改官方设置：${bound.reason}` }
+            : { kind: 'ok', text: `已同步：官方「网页搜索」页现在绑定 ${next?.search?.officialRef ?? next?.search?.defaultRef ?? '同一个 ref'}，与面板改的是同一把 key。` })
         } catch (err) {
           if (alive.current) setNotice({ kind: 'bad', text: `${err?.message ?? err}` })
         } finally {
@@ -1057,7 +1084,9 @@ window.__ModuleLoader__.load({
             h('li', null, '先到「设置 → 模型」配一把系统默认 key，例如就叫 ', h('code', null, 'default'),
               '。没有单独配置的地方都用它聊天。'),
             h('li', null, '再回到本页的「搜索默认 key」，放一把搜索专用的 key，例如 ', h('code', null, 'search-default'),
-              '。搜索请求默认用它，和聊天那把分开计费。'),
+              '。搜索请求默认用它，和聊天那把分开计费。',
+              '保存时插件会把官方「设置 → 插件 → 网页搜索」里的 API Key 指向同一个 ref，',
+              '所以那个页面显示、修改的都是这把 key，两边不会各存一份。'),
             h('li', null, '平时不用再管：聊天按工作区/会话的 key 走，搜索走搜索默认 key，两边账单互不影响。')),
           h('h4', null, '想按工作区核算搜索花费'),
           h('ul', null,
@@ -1071,11 +1100,22 @@ window.__ModuleLoader__.load({
             h('li', null, '搜索默认 key —— 没勾同步时，搜索用它'),
             h('li', null, '官方「网页搜索」页里配的那把 —— 面板没配搜索默认 key 时的兜底',
               '（它默认就是系统默认 key ', h('code', null, 'DEEPSEEK_API_KEY'), '，与聊天共用）')),
+          h('h4', null, '官方「设置 → 插件 → 网页搜索」那个 Key 框怎么办'),
+          h('div', { className: 'wsk-hint' },
+            '官方那个输入框写的永远是「当前 API 段的 ', h('code', null, 'apiKeyEnv'),
+            ' 指向的 ref」，默认就是聊天那把（', h('code', null, 'DEEPSEEK_API_KEY'), '）。',
+            '本插件启动后会把它指到插件自己的搜索 ref（', h('code', null, 'DEEPSEEK_API_KEY_SEARCH'), '），',
+            '等于把官方那个 key 设置接管过来：从今往后官方页里填的也是这把搜索 key，',
+            '不会再把聊天 key 顶掉，也不会出现「两把搜索 key 各管一半」。'),
+          h('div', { className: 'wsk-hint' },
+            '所以日常只需要在本页配搜索 key，官方那一页可以不管；本插件只改 ',
+            h('code', null, 'apiKeyEnv'), ' 这个指向，永远不动你的 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('li', null, '勾了同步，但该工作区既没有专属 key、系统默认 key 也没配 → 会提示先去配一把。'),
+            h('li', null, '搜索默认 key 存好了，但官方页还指着聊天那把 → 会提示点「同步到官方设置」，一键对齐。')),
           h('h4', null, '原则'),
           h('div', { className: 'wsk-hint' },
             '提醒只报告、不替你改 key。插件绝不会自动切换或替换你的 key，避免计费被悄悄改到别的账号上。')),
@@ -1234,10 +1274,22 @@ window.__ModuleLoader__.load({
                         : h('span', { key: 's', className: 'wsk-badge' }, '未配置')),
                     h('div', { className: 'wsk-hint' },
                       '搜索请求默认用它，和聊天那把 key 分开计费。'
-                      + '工作区勾了「同步搜索 API」时改用该工作区的聊天层级；会话单独配置永远最优先。',
+                      + '工作区勾了「同步搜索 API」时改用该工作区的聊天层级；会话单独配置永远最优先。'),
+                    h('div', { className: 'wsk-hint' },
                       searchInfo.defaultConfigured === true && searchInfo.defaultKeyMasked
-                        ? ` 当前值：${searchInfo.defaultKeyMasked}`
-                        : '')),
+                        ? `当前值：${searchInfo.defaultKeyMasked}。`
+                        : '',
+                      searchInfo.officialShared === true
+                        ? '官方「网页搜索」页现在仍指着聊天那把 key（DEEPSEEK_API_KEY）——保存一次搜索 key 后，插件会把它接过来。'
+                        : `官方「网页搜索」页已由本插件接管：那里填的也是 ${searchInfo.officialRef ?? 'DEEPSEEK_API_KEY_SEARCH'} 这一把，不会再误改聊天 key。`),
+                    searchInfo.officialShared === true && searchInfo.ownedConfigured === true
+                      ? h('div', { className: 'wsk-hint' },
+                          '你之前保存过搜索默认 key，但官方页还指向聊天那把。',
+                          h('button', {
+                            type: 'button', className: 'wsk-btn', style: { marginLeft: 6 }, disabled: busy,
+                            onClick: () => syncSearchDefault(),
+                          }, '同步到官方设置'))
+                      : null),
                   h('div', { className: 'wsk-actions' },
                     h('button', {
                       type: 'button', className: 'wsk-btn', disabled: busy,

package/lib/index.js

@@ -247,6 +247,102 @@ function workspaceSynced(state, cwd) {
   return state.searchSync?.[norm] === true
 }
 
+/**
+ * 官方「设置 → 插件 → 网页搜索」页那个 API Key 输入框绑定到的 ref。
+ *
+ * 官方页写的就是 provider 配置里的 `apiKeyEnv`（没写时是 `DEEPSEEK_API_KEY`），
+ * 所以想让「面板里的搜索默认 key」与「官方页里那把」是同一个值，就得让 `apiKeyEnv` 指过来。
+ */
+function officialSearchRef(web) {
+  return web.apiChannel ? web.apiKeyEnv : web.legacyKeyEnv
+}
+
+/**
+ * 面板「搜索默认 key」实际落在哪个 ref。
+ *
+ * 官方还指向聊天那把（`DEEPSEEK_API_KEY`）时，用插件自有的 `DEEPSEEK_API_KEY_SEARCH` 顶替——
+ * 否则保存搜索 key 会把聊天 key 覆盖掉。官方指向别处（含已被本插件改过）时，就直接用官方那个 ref，
+ * 于是官方页和面板改的是同一把 key。
+ */
+function searchDefaultRefOf(web) {
+  const official = officialSearchRef(web)
+  return official === DEFAULT_API_KEY_REF ? SEARCH_DEFAULT_REF : official
+}
+
+/**
+ * 「搜索没有自己的 key 时退回哪一把」——官方搜索页当前指向的 ref。
+ *
+ * 例外：如果那个 ref 是插件自己改上去的 `DEEPSEEK_API_KEY_SEARCH`，而它还是空的
+ * （用户还没配搜索默认 key），就退回聊天 ref——否则升级完、还没配搜索 key 时，
+ * 所有 web_search 都会因为「ref 是空的」直接失败。
+ */
+function fallbackSearchRef(web) {
+  return web.searchKeyEnv === SEARCH_DEFAULT_REF ? DEFAULT_API_KEY_REF : web.searchKeyEnv
+}
+
+/**
+ * 把官方两套搜索插件的 `apiKeyEnv` 都指向同一个 ref。
+ *
+ * 这样「面板里保存的搜索默认 key」就是「官方网页搜索页里的那把 key」：官方页的输入框写同一个 ref，
+ * 两边不再各存一份。settings.update 只改 volatile 字段，失败就原样返回，绝不影响 key 本身。
+ */
+async function bindOfficialSearchRef(ctx, ref) {
+  let settings
+  try {
+    settings = ctx.get('settings')
+  } catch {
+    settings = undefined
+  }
+  if (typeof settings?.update !== 'function' || typeof settings?.describe !== 'function') {
+    return { ok: false, reason: 'settings-unavailable', changed: [] }
+  }
+  const changed = []
+  for (const ns of [SEARCH_API_NS, LEGACY_SEARCH_NS]) {
+    try {
+      const row = (settings.describe() ?? []).find((item) => item?.ns === ns)
+      if (row === undefined) continue
+      if (row.value?.apiKeyEnv === ref) continue
+      await settings.update(ns, { apiKeyEnv: ref }, row.revision)
+      changed.push(ns)
+    } catch (error) {
+      return { ok: false, reason: error?.message ?? String(error), changed }
+    }
+  }
+  return { ok: true, changed }
+}
+
+/**
+ * 启动时把官方「网页搜索」页的 key 指向拉回一致。
+ *
+ * 官方页那个 Key 输入框写的永远是「当前 API 段的 apiKeyEnv 指向的 ref」。用户要求
+ * 「直接禁用官方页面里的搜索 key 设置」——所以插件要把它指到自己的 `DEEPSEEK_API_KEY_SEARCH`：
+ * 从那以后官方页填的就是插件这把搜索 key，既不会误改聊天 key，也不再存在第二把搜索 key。
+ *
+ * 但接管有个前提：搜索默认 key 已经存在。官方那条 ref 指向一把空 key 会让**所有搜索直接失败**，
+ * 所以这里分两种情况：
+ *   - 官方指着搜索 ref、但那把 key 还没有 → 退回聊天那把，搜索继续可用（等用户配了再接管）；
+ *   - 官方指着聊天那把、而搜索 key 已经配好 → 接管过去。
+ * 只改 apiKeyEnv 指向，不动任何 key 的值；settings 不可写就静默跳过。
+ */
+async function reconcileOfficialSearchRef(ctx) {
+  const web = readWebSettings(ctx)
+  if (web.apiChannel !== true) return
+  const official = officialSearchRef(web)
+  if (official !== SEARCH_DEFAULT_REF && official !== DEFAULT_API_KEY_REF) return
+  const owned = (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true
+  if (official === SEARCH_DEFAULT_REF && !owned) {
+    const bound = await bindOfficialSearchRef(ctx, DEFAULT_API_KEY_REF)
+    if (bound.ok !== true) log('restore official search ref failed: %s', bound.reason)
+    else if (bound.changed.length > 0) log('search default key is empty; official search key falls back to %s', DEFAULT_API_KEY_REF)
+    return
+  }
+  if (official === DEFAULT_API_KEY_REF && owned) {
+    const bound = await bindOfficialSearchRef(ctx, SEARCH_DEFAULT_REF)
+    if (bound.ok !== true) log('adopt official search ref failed: %s', bound.reason)
+    else if (bound.changed.length > 0) log('adopted official search key settings: %s', bound.changed.join(', '))
+  }
+}
+
 /**
  * 「这个会话/目录的搜索请求会去读哪个 ref」——纯计算，不解析凭据。
  *   新版 API 通道：会话单独 key → 工作区勾了同步 ? （工作区 key / 系统默认）: 搜索插件自己的 ref
@@ -261,9 +357,10 @@ async function searchRefFor(ctx, state, { sessionId, cwd, web, searchDefault })
     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
+  // 没同步：搜索默认 key（官方 ref 或插件自有的 ref）优先，其次才是官方搜索页配的那把。
+  const ownRef = searchDefaultRefOf(w)
+  const configured = searchDefault ?? (await describeKey(ctx, ownRef)).configured === true
+  return configured === true ? ownRef : fallbackSearchRef(w)
 }
 
 // ───────────────── 会话列表（宿主 sessionController + live 兜底） ─────────────────
@@ -789,7 +886,9 @@ async function searchWarnings(ctx, state, web) {
     ? (await describeKey(ctx, DEFAULT_API_KEY_REF)).configured === true
     : (await describeKey(ctx, web.apiKeyEnv)).configured === true
   const apiKeyPresent = web.apiLiteralKey !== undefined || (web.apiKeyEnv !== DEFAULT_API_KEY_REF && apiKeyConfigured)
-  const searchDefaultConfigured = (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true
+  const searchDefaultRef = searchDefaultRefOf(web)
+  const searchDefaultConfigured = (await describeKey(ctx, searchDefaultRef)).configured === true
+  const officialRef = officialSearchRef(web)
 
   // 1) 配了新版搜索 API 的 key，但官方开关没开 → 那把 key 永远不会被读到。
   if (!web.apiChannel && apiKeyPresent) {
@@ -803,15 +902,28 @@ async function searchWarnings(ctx, state, web) {
     })
   }
 
-  // 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。',
-    })
+  // 2) 开了新版 API，却没有搜索默认 key：
+  //    聊天 key 还在 → 搜索暂时沿用聊天那把（能跑，但计费混在一起，值得提醒）；
+  //    聊天 key 也没了 → 搜索会直接报缺少凭据。
+  if (web.apiChannel && web.apiLiteralKey === undefined && !searchDefaultConfigured) {
+    const chatConfigured = (await describeKey(ctx, DEFAULT_API_KEY_REF)).configured === true
+    if (chatConfigured) {
+      out.push({
+        code: 'search-default-missing',
+        level: 'warn',
+        title: '搜索默认 key 还没配置：搜索暂时沿用聊天那把 key',
+        detail: `现在搜索读的是 ${DEFAULT_API_KEY_REF}（和聊天共用一把），所以搜索与聊天的花费算在一起。`
+          + `在本面板的「搜索默认 key」里保存一把后，插件会自动把官方配置指过去，两边就分开了。`,
+      })
+    } else {
+      out.push({
+        code: 'search-key-missing',
+        level: 'bad',
+        title: '新版 Web 搜索 API 已启用，但搜索 key 没有配置',
+        detail: `搜索会用 ${web.apiKeyEnv} 去取 key，而它当前是空的：任何 web_search 都会失败。`
+          + '到「设置 → 插件 → 网页搜索」里填一把，或在本面板的「搜索默认 key」里保存一把。',
+      })
+    }
   }
 
   // 2b) 面板里配了「搜索默认 key」，但新版 API 没开 → 这把 key 也不会被读到。
@@ -821,11 +933,23 @@ async function searchWarnings(ctx, state, web) {
       level: 'warn',
       title: '搜索默认 key 已配置，但「启用新版 Web 搜索 API」没打开',
       detail: '现在搜索走的是 DeepSeek Messages 通道，用的是聊天那把 key，'
-        + `所以面板里的 ${SEARCH_DEFAULT_REF} 不会被使用。`
+        + `所以面板里的 ${searchDefaultRef} 不会被使用。`
         + '要让它生效，请到「设置 → 插件 → 网页搜索」打开那个开关；若暂时不想用新版 API，可以忽略本条。',
     })
   }
 
+  // 2c) 搜索默认 key 已保存，但官方网页搜索页还指向聊天那把 → 官方页看不到它，
+  //     一键同步就能让两处共用同一个 ref。
+  if (searchDefaultRef === SEARCH_DEFAULT_REF && searchDefaultConfigured) {
+    out.push({
+      code: 'search-official-shared',
+      level: 'warn',
+      title: '搜索默认 key 已保存，但官方「网页搜索」页仍指向聊天那把',
+      detail: `官方页现在绑的是 ${DEFAULT_API_KEY_REF}（与聊天共用），所以那里看不到 ${SEARCH_DEFAULT_REF} 这把。`
+        + '点面板上的「同步到官方设置」，官方页的 API Key 输入框就会改到同一个 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)
@@ -1137,6 +1261,8 @@ export function apply(ctx) {
   // ── 1. 包装 credentials.resolve + 标记搜索/抓取通道 ─────────────────
   installWebScope(ctx)
   installResolver(ctx, state)
+  // 「直接禁用官方页面里的搜索 key 设置」：把官方 apiKeyEnv 指到插件自有 ref（异步、失败不影响启动）。
+  void reconcileOfficialSearchRef(ctx)
 
   // ── 2. REST API（loopback 可信）──────────────────────────────────────
   let webServer
@@ -1288,12 +1414,12 @@ function installResolver(ctx, state) {
             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)
+          // ③ 没同步：用「搜索默认 key」。它要么就是官方页绑定的那个 ref（保存时已把
+          //    apiKeyEnv 指过来，两处同源），要么是插件自有的 ref（官方还指向聊天那把时）。
+          const searchDefaultRef = searchDefaultRefOf(web)
+          const searchDefaultHit = await resolveKey(ctx, searchDefaultRef)
           if (searchDefaultHit.value !== undefined && searchDefaultHit.value !== '') {
-            log(`search ref ${ref} → ${SEARCH_DEFAULT_REF} (search default)`)
+            log(`search ref ${ref} → ${searchDefaultRef} (search default)`)
             return { value: searchDefaultHit.value, source: searchDefaultHit.source ?? 'plugin' }
           }
           return await original(ref)
@@ -1474,15 +1600,15 @@ async function workspaceRow(ctx, state, { id, path: dir, title, kind }, rows, cl
   // 让用户勾了复选框之后马上能看到效果，而不用等到搜索失败才发现。
   const web = readWebSettings(ctx)
   const synced = state.searchSync?.[normPath(dir)] === true
-  const searchDefaultConfigured = web.apiChannel && (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true
+  const searchDefaultConfigured = web.apiChannel && (await describeKey(ctx, searchDefaultRefOf(web))).configured === true
   const searchKeyRef = web.apiChannel
     ? synced
       ? configured
         ? ref
         : DEFAULT_API_KEY_REF
       : searchDefaultConfigured
-        ? SEARCH_DEFAULT_REF
-        : web.searchKeyEnv
+        ? searchDefaultRefOf(web)
+        : fallbackSearchRef(web)
     : web.searchKeyEnv
   const searchKeyMasked = web.apiChannel ? maskKey((await resolveKey(ctx, searchKeyRef))?.value) : undefined
   return {
@@ -1619,8 +1745,10 @@ async function snapshot(ctx, state) {
   const searchKeyRef = web.searchKeyEnv
   const searchKeyInfo = await describeKey(ctx, searchKeyRef)
   const searchKeyHit = await resolveKey(ctx, searchKeyRef)
-  const defaultSearchInfo = await describeKey(ctx, SEARCH_DEFAULT_REF)
-  const defaultSearchHit = await resolveKey(ctx, SEARCH_DEFAULT_REF)
+  const searchDefaultRef = searchDefaultRefOf(web)
+  const officialRef = officialSearchRef(web)
+  const defaultSearchInfo = await describeKey(ctx, searchDefaultRef)
+  const defaultSearchHit = await resolveKey(ctx, searchDefaultRef)
   const syncPaths = Object.keys(state.searchSync ?? {}).filter((key) => state.searchSync[key] === true)
   const warnings = await searchWarnings(ctx, state, web)
 
@@ -1675,9 +1803,16 @@ async function snapshot(ctx, state) {
       keySource: searchKeyInfo.source,
       keyWritable: searchKeyInfo.writable !== false,
       literalKey: web.searchLiteralKey !== undefined,
-      // 面板自己持有的「搜索默认 key」（优先于官方页配的那把）。
-      defaultRef: SEARCH_DEFAULT_REF,
+      // 面板自己持有的「搜索默认 key」。它落在哪个 ref 取决于官方页：
+      // 官方还指向聊天那把时用插件自有的 SEARCH_DEFAULT_REF，否则直接用官方那个 ref（两处同源）。
+      defaultRef: searchDefaultRef,
       defaultConfigured: defaultSearchInfo.configured === true,
+      // 官方网页搜索页绑定的 ref（它的 API Key 输入框写的就是这个 ref）。
+      officialRef,
+      officialShared: officialRef === DEFAULT_API_KEY_REF,
+      // 插件自有 ref：官方仍共用聊天 key 时「同步到官方设置」会把它指过去。
+      ownedRef: SEARCH_DEFAULT_REF,
+      ownedConfigured: (await describeKey(ctx, SEARCH_DEFAULT_REF)).configured === true,
       defaultKeyMasked: maskKey(defaultSearchHit?.value),
       defaultSource: defaultSearchInfo.source,
       defaultWritable: defaultSearchInfo.writable !== false,
@@ -1864,19 +1999,37 @@ 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。
+      // 搜索默认 key：不是「某个目录/会话」的覆盖。
+      // 它写在「官方网页搜索页绑定的那个 ref」上 —— 官方页的 API Key 输入框写的就是这个 ref，
+      // 于是面板和官方页改的是同一把 key，不会各存一份。官方还指向聊天那把（DEEPSEEK_API_KEY）时，
+      // 先把两套搜索插件的 apiKeyEnv 改到插件自有 ref，再写值。
       if (body.scope === 'search-default') {
+        const web = readWebSettings(ctx)
+        const official = officialSearchRef(web)
+        const needsBind = official === DEFAULT_API_KEY_REF
+        const target = needsBind ? SEARCH_DEFAULT_REF : official
+        // 只要求同步（不改 key）：用于「key 已经存过，但官方页还看不到」的一键修复。
+        if (body.adopt === true) {
+          const bound = await bindOfficialSearchRef(ctx, SEARCH_DEFAULT_REF)
+          saveState(state)
+          sendJson(res, 200, { ok: true, adopted: true, bound, ...(await snapshot(ctx, state)) })
+          return
+        }
         if (body.useDefault === true || key === '') {
-          await clearKey(ctx, SEARCH_DEFAULT_REF)
+          await clearKey(ctx, target)
+          if (needsBind) await clearKey(ctx, SEARCH_DEFAULT_REF)
+          delete state.invalid[target]
           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]
+        let bound = { ok: true, changed: [], skipped: true }
+        if (needsBind) bound = await bindOfficialSearchRef(ctx, SEARCH_DEFAULT_REF)
+        await storeKey(ctx, target, key)
+        delete state.invalid[target]
         saveState(state)
-        sendJson(res, 200, { ok: true, ...(await snapshot(ctx, state)) })
+        sendJson(res, 200, { ok: true, bound, ...(await snapshot(ctx, state)) })
         return
       }
       const target = targetOf(body)
@@ -1918,7 +2071,7 @@ async function handle(ctx, state, req, res) {
       if (key === undefined) {
         if (sourceRef === undefined) {
           if (body.scope === 'search-default') {
-            sourceRef = SEARCH_DEFAULT_REF
+            sourceRef = searchDefaultRefOf(web)
           } 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)

package/package.json

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