@darlingc/dsh-freesearch 0.5.4 → 0.5.6

package/README.md

@@ -9,8 +9,8 @@
 ## 中文
 
 <div align="center">
-  <a href="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free1.png">
-    <img src="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free1.png" alt="免费引擎设置 (Bing)" width="820" />
+  <a href="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free1.png">
+    <img src="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free1.png" alt="免费引擎设置 (Bing)" width="820" />
   </a>
   <br>
   <sub>▲ 免费引擎（以Bing为例）</sub>
@@ -36,7 +36,7 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 - **统一引擎回退** —— 任何引擎失败（付费/免费，缺 key/401/限流/网络）自动轮流尝试下一个引擎：首选引擎 → 其他引擎（exa/tavily/keenable 无 key 也会尝试，因为它们自带 keyless 免费额度）→ 剩余免费引擎，搜索永不直接失败；结果顶部注明实际生效的引擎（如 `Note: perplexity unavailable or failed, using exa.`）
 - **时间过滤** —— `advanced_search` 工具支持 `timeRange`：固定档、自定义相对值、绝对日期三种形式（详见下方逻辑说明）
 - **系统提示词注入** —— agent 知道当前用哪个引擎、哪些需要 key
-- **版本号 + 检查更新** —— 设置卡片显示当前版本（v0.4.12），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
+- **版本号 + 检查更新** —— 设置卡片显示当前版本（v0.5.6），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
 - **结果缓存** —— 相同查询（含引擎/时间过滤参数）5 分钟内命中缓存（LRU 50 条），防免费引擎限流、省付费额度；时长可在设置页 0-5 分钟自由配置（0 关闭）
 - **免费标注** —— 设置页中免费引擎带绿色 `FREE` 徽章，付费引擎带橙色 `API KEY` 徽章
 - **网页抓取（web_fetch）** —— 让 agent 抓取网页内容（官方 `dsh-web-fetch-http` provider，纯 JS，零额外依赖）
@@ -81,8 +81,8 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 - **Key 配置**：在 AI Studio（aistudio.google.com/apikey）免费创建 `GEMINI_API_KEY`，放入 `~/.dsh/.credentials.yaml` 的 `refs.GEMINI_API_KEY`，或在 `~/.dsh/settings.yaml` 的 `free-search:` 下设置 `geminiApiKey`。
 - **模型**：默认 `gemini-2.5-flash`（免费层唯一已实测可联网的模型）。当前 AI Studio 免费层**无需绑卡**即可用 Google Search grounding。
 - **⚠️ 配额警示（务必注意）**：
-  - `gemini-2.5-flash` **文本输出 RPD 仅约 20/天** —— 千万别把它当常规文本问答模型用，会秒爆。本引擎只走 grounding（联网搜索），计的是**搜索 RPD**，不占那 20 次文本额度。
-  - **搜索 RPD 约 1,500/天**（与 Flash-Lite 共享），**RPM 约 5**。每次搜索引擎调用 = 1 次 grounded prompt = 1 搜索 RPD。超限会返回 HTTP 429，本插件会**自动回退到其它免费引擎**（Bing 等），搜索不会因此失败。
+  - `gemini-2.5-flash` **文本输出 RPD 仅约 20/天** —— 千万别把它当常规文本问答模型用，会秒爆。⚠️ **每次发起 grounded 搜索请求，模型生成过程会同时扣 1 次文本输出额度 + 1 次搜索接地额度**：因此那 **20 次文本输出 RPD 就是实际瓶颈**，即便搜索 RPD 高达约 1,500/天，实际每天都只能发起约 **20 次** grounded 搜索。
+  - **搜索 RPD 约 1,500/天**（与 Flash-Lite 共享），**RPM 约 5**。每次搜索引擎调用 = 1 次 grounded prompt = **同时耗 1 文本 + 1 搜索额度**。超限会返回 HTTP 429，本插件会**自动回退到其它免费引擎**（Bing 等），搜索不会因此失败。
   - 因此**不建议把 `gemini` 设为默认首选引擎**（`free-search.provider: gemini`），默认 `bing` + 失败自动回退即可；把 `gemini` 当按需/回退引擎最稳。
 - **与其它引擎差异**：Gemini grounding 返回的是"模型 Ground 到的来源集合"，不是像 Bing 那样的排序结果列表——数量不固定、通常偏少、无优先级；`maxResults` 只能做客户端截断。作为默认搜索体验与真实搜索引擎略有不同。
 
@@ -122,6 +122,29 @@ dsh web
 
 > ⚠️ 依赖：CI 的 `npm stage publish` 需要 GitHub 仓库配置 `NPM_TOKEN` secret（npmjs.com → Access Tokens → Publish 类型 token）。且该包需先在 npm registry 上存在（首次发布无法 stage，需先在网页/本地完成一次正式发布）。
 
+#### 发布到 GitHub Packages（本地，可选，不走 CI/CD）
+
+除 npmjs 外，也可把本包发布到 **GitHub Packages**（`npm.pkg.github.com`，归属 `DarlingC` 组织）。仓库内置了专用 npm 配置 `.npmrc-github`，它**不会自动加载**，因此不会影响常规安装或上方 npmjs Staged Publishing 流程。
+
+```sh
+# 1) 生成带 write:packages 权限的 GitHub PAT（Settings → Developer settings → Personal access tokens）
+export GITHUB_TOKEN=ghp_xxx
+
+# 2) 用专用配置发布到 GitHub Packages（版本号须 >= 已存在版本）
+npm publish --registry=https://npm.pkg.github.com/ --userconfig=.npmrc-github
+```
+
+从 GitHub Packages 安装：
+
+```sh
+export GITHUB_TOKEN=ghp_xxx   # 需 read:packages 权限
+dsh plugin --profile web add @darlingc/dsh-freesearch --registry=https://npm.pkg.github.com/
+# 或在用户/项目 .npmrc 里加一行让该 scope 走 GitHub Packages：
+#   @darlingc:registry=https://npm.pkg.github.com/
+```
+
+> 📌 说明：GitHub Packages 适合「仓库内私有/组织内发布」场景；对外推荐走 npmjs（上方 Staged Publishing）。两套 registry 互不影响，tag push 自动建的 GitHub Release（见 `.github/workflows/publish.yml`）与 GitHub Packages 发布相互独立。
+
 ### 使用
 
 #### 网页设置（推荐）
@@ -130,6 +153,7 @@ dsh web
 
 - **Search engine**：下拉框切换引擎，保存即生效
 - **API keys**：为 Exa / Tavily / Keenable / Perplexity / DeepSeek 填写 key（密码框，保存后只显示"已配置"）
+  - **推荐**：付费引擎 key 建议写入 harness 凭据中心 `~/.dsh/.credentials.yaml`（如 `DEEPSEEK_API_KEY: sk-...`，与官方 LLM provider 一致，一处管理所有 key）。插件读取优先级：凭据中心 > 设置页 > 环境变量，设置页填的 key 仅作为遗留兼容。
 - **Test engine**：直测当前引擎可用性（不走回退链，付费引擎无 key 会明确报错）
 - **Use Bing default**：把当前搜索引擎切回稳定的免费 Bing；`Discard` 只撤销尚未保存的编辑
 - **Platform search**：勾选启用 GitHub / V2EX / Bilibili 平台搜索（`platform_search` 工具按此过滤）
@@ -138,15 +162,15 @@ dsh web
 <table align="center" style="border: none; border-collapse: collapse;">
   <tr style="border: none;">
     <td align="center" width="50%" style="border: none; padding: 6px;">
-      <a href="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free.png">
-        <img src="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free.png" alt="免费引擎设置" width="100%" />
+      <a href="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free.png">
+        <img src="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free.png" alt="免费引擎设置" width="100%" />
       </a>
       <br>
       <sub>▲ <b>免费引擎</b>（显示绿色 FREE 徽章与官网链接）</sub>
     </td>
     <td align="center" width="50%" style="border: none; padding: 6px;">
-      <a href="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-apikey.png">
-        <img src="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-apikey.png" alt="付费引擎设置" width="100%" />
+      <a href="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-apikey.png">
+        <img src="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-apikey.png" alt="付费引擎设置" width="100%" />
       </a>
       <br>
       <sub>▲ <b>付费/API Key 引擎</b>（显示橙色 API KEY 徽章与获取链接）</sub>
@@ -244,17 +268,6 @@ Search engine test:
 
 全部走公开 API，零外部依赖、无需任何 key，开箱即用。
 
-### 本地引擎切换工具（tools/）
-
-`tools/` 目录附带了一个本地切换小工具（零依赖）：
-
-- **`启动搜索引擎切换器.cmd`**（Windows）——双击启动本地 Node 服务（`http://127.0.0.1:4789`）并自动打开浏览器选择页面
-- **`switch-engine.html`** —— 选择页面：显示当前引擎，点选新引擎，一键写入配置
-- **`server.mjs`** —— 本地服务，负责读写 `~/.dsh/profiles/web/cordis.patch.yml`
-- **`switch-engine.ps1`** —— 无界面命令行版：`powershell -File tools/switch-engine.ps1 -Engine bing`
-
-切换后重启 `dsh web` 生效。
-
 > 配置卡片挂在官方设置页的 `settings.plugin.item` 插槽（dsh 自带），配置读写走插件自建 bridge，**不依赖 dsh-web-ui**，插件可独立使用。
 
 ### 代理说明（国内用户）
@@ -280,8 +293,8 @@ Windows 用户：桌面快捷方式已内置此配置（`set NODE_USE_ENV_PROXY=
 ## English
 
 <div align="center">
-  <a href="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free1.png">
-    <img src="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free1.png" alt="Free Engine Settings (Bing)" width="820" />
+  <a href="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free1.png">
+    <img src="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free1.png" alt="Free Engine Settings (Bing)" width="820" />
   </a>
   <br>
   <sub>▲ Free engine (using Bing as an example)</sub>
@@ -307,7 +320,7 @@ This plugin provides multiple free search engines with automatic fallback, compl
 - **Unified Engine Fallback** — Any engine failure (paid or free, missing key, 401, rate limit, network error) automatically tries the next engine: the configured engine first, then other engines (exa/tavily/keenable are tried even without a key because they have built-in keyless quota), then the remaining free engines (Bing/AnySearch etc.) — with a note attached to the results naming the engine that actually served them (e.g. `Note: perplexity unavailable or failed, using exa.`). Search never fails outright.
 - **Time Filtering** — The `advanced_search` tool supports `timeRange`: fixed tiers, custom relative values, or an absolute date (details below)
 - **System Prompt Injection** — The agent is aware of the currently active engine and which engines require API keys
-- **Version + Update Check** — The settings card shows the current version (v0.4.12), and a "Check update" button queries the npm registry to compare against the latest release, prompting a one-click jump when a newer version exists
+- **Version + Update Check** — The settings card shows the current version (v0.5.6), and a "Check update" button queries the npm registry to compare against the latest release, prompting a one-click jump when a newer version exists
 - **Result Caching** — Identical queries (same engine / time-filter args) hit an LRU cache (50 entries) for up to 5 minutes, protecting free engines from rate-limiting and saving paid quota; the TTL is configurable from 0-5 minutes in the settings UI (0 disables caching)
 - **Visual Badges** — Free engines feature a green `FREE` badge, while paid engines show an orange `API KEY` badge in the settings UI
 - **Webpage Fetching (`web_fetch`)** — Allows the agent to read full webpage contents (official `dsh-web-fetch-http` provider, pure JS, zero extra dependencies)
@@ -352,8 +365,8 @@ This plugin provides multiple free search engines with automatic fallback, compl
 - **Key**: create a free `GEMINI_API_KEY` at AI Studio (aistudio.google.com/apikey) and store it in `refs.GEMINI_API_KEY` under `~/.dsh/.credentials.yaml`, or set `geminiApiKey` under `free-search:` in `~/.dsh/settings.yaml`.
 - **Model**: defaults to `gemini-2.5-flash` (the only free-tier model verified to work online here). Google Search Grounding is available on the AI Studio **free tier with no credit card**.
 - **⚠️ Quota warning (important)**:
-  - `gemini-2.5-flash` has a **text-output RPD of only ~20/day** — do **not** use it as a general text model or you will exhaust it instantly. This engine only uses grounding (web search), which counts against the **search RPD**, not the text quota.
-  - **Search RPD ≈ 1,500/day** (shared with Flash-Lite), **RPM ≈ 5**. Each engine call = 1 grounded prompt = 1 search RPD. Exceeding it returns HTTP 429, and this plugin **auto-falls-back to other free engines** (Bing, etc.), so search never hard-fails.
+  - `gemini-2.5-flash` has a **text-output RPD of only ~20/day** — do **not** use it as a general text model or you will exhaust it instantly. ⚠️ **Each grounded search request consumes 1 text-output quota + 1 search-grounding quota simultaneously during generation**, so the **~20/day text-output RPD is the real bottleneck**: even though the search RPD is ~1,500/day, you can effectively make only about **20 grounded searches per day**.
+  - **Search RPD ≈ 1,500/day** (shared with Flash-Lite), **RPM ≈ 5**. Each engine call = 1 grounded prompt = **consumes 1 text + 1 search quota at once**. Exceeding it returns HTTP 429, and this plugin **auto-falls-back to other free engines** (Bing, etc.), so search never hard-fails.
   - So keep `provider: bing` as default and let `gemini` act as a fallback / on-demand engine rather than the primary load.
 - **Difference vs. other engines**: Gemini grounding returns the set of sources the model grounded on — not a ranked SERP list like Bing/DDG. Count is not fixed and is usually small, with no ordering; `maxResults` can only truncate client-side.
 
@@ -391,6 +404,7 @@ After installation, navigate to **Settings → Plugins → Configurable** tab
 
 - **Search engine**: Select an engine from the dropdown; changes take effect immediately upon saving.
 - **API keys**: Enter keys for Exa / Tavily / Keenable / Perplexity / DeepSeek (password fields; displayed as "configured" once saved).
+  - **Recommended**: store paid-engine keys in the harness credential center `~/.dsh/.credentials.yaml` (e.g. `DEEPSEEK_API_KEY: sk-...`, same as the official LLM providers — one place for all keys). Resolution order: credentials center > settings page > environment variable; the settings-page fields remain for backward compatibility.
 - **Test engine**: Tests the selected engine directly (no fallback chain; paid engines without a key report an explicit error).
 - **Use Bing default**: stage a switch back to the stable free Bing engine; `Discard` only cancels unsaved edits
 - **Platform search**: check platforms (GitHub / V2EX / Bilibili / Reddit / HN / Stack Overflow / Wikipedia / npm) to enable them for the `platform_search` tool (disabled platforms are skipped).
@@ -399,15 +413,15 @@ After installation, navigate to **Settings → Plugins → Configurable** tab
 <table align="center" style="border: none; border-collapse: collapse;">
   <tr style="border: none;">
     <td align="center" width="50%" style="border: none; padding: 6px;">
-      <a href="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free.png">
-        <img src="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-free.png" alt="Free Engine Settings" width="100%" />
+      <a href="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free.png">
+        <img src="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-free.png" alt="Free Engine Settings" width="100%" />
       </a>
       <br>
       <sub>▲ <b>Free Engine</b> (shows green FREE badge and official website link)</sub>
     </td>
     <td align="center" width="50%" style="border: none; padding: 6px;">
-      <a href="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-apikey.png">
-        <img src="https://raw.githubusercontent.com/DDDMUC/dsh-free-search/master/assets/settings-apikey.png" alt="Paid/API Key Engine Settings" width="100%" />
+      <a href="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-apikey.png">
+        <img src="https://raw.githubusercontent.com/DarlingC/dsh-freesearch/master/assets/settings-apikey.png" alt="Paid/API Key Engine Settings" width="100%" />
       </a>
       <br>
       <sub>▲ <b>Paid / API Key Engine</b> (shows orange API KEY badge and link to get an API key)</sub>
@@ -505,17 +519,6 @@ Ask the agent to search specific platforms (e.g., *"Search GitHub for deepseek h
 
 All platform searches rely on public endpoints with zero external dependencies and no API keys — they work out of the box.
 
-### Local Engine Switcher (`tools/`)
-
-The `tools/` directory includes a lightweight, zero-dependency switcher:
-
-- **`启动搜索引擎切换器.cmd`** (Windows) — Double-click to launch a local Node server (`http://127.0.0.1:4789`) and automatically open the engine selector page in your browser.
-- **`switch-engine.html`** — The selector UI: displays current engine status and allows one-click switching.
-- **`server.mjs`** — The local backend service responsible for reading/writing `~/.dsh/profiles/web/cordis.patch.yml`.
-- **`switch-engine.ps1`** — Headless PowerShell script: `powershell -File tools/switch-engine.ps1 -Engine bing`.
-
-Restart `dsh web` after switching to apply changes.
-
 > The settings card mounts into the official `settings.plugin.item` slot (built into DSH), and configuration reads/writes go through the plugin's own bridge. **No `dsh-web-ui` dependency — the plugin can be used standalone.**
 
 ### Proxy Note (for Users in Mainland China)

package/cordis.patch.yml

@@ -16,6 +16,9 @@
         provider: bing
         bingMarket: zh-CN
 # 自动接管默认搜索：让 harness 的 web_search 直接用本插件的 provider（内部含全部引擎）
+# 注意 patch 语义是"整行替换 config"（DSH 0.1.2+）：必须保留 fetchProvider，否则
+# web-fetch-http 会被另一层重新注册，与 base bundle 的注册造成 duplicate loader entry。
 - id: web
   config:
     searchProvider: ddg
+    fetchProvider: http

package/lib/client.js

@@ -30,8 +30,15 @@ window.__ModuleLoader__.load({
       ".dshfs-label{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:500}",
       ".dshfs-select{border:1px solid var(--dsw-alias-border-l2);font:inherit;font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-primary);background:var(--dsw-specific-input-major);border-radius:6px;padding:6px 8px;font-size:13px;transition:border-color .13s,box-shadow .13s;width:100%}",
       ".dshfs-select:hover:not(:disabled){border-color:var(--dsw-alias-label-dimmed)}",
+      // 下拉选项列表配色锁死：不随皮肤变量变化（皮肤只影响 select 框体本身）
+      // color-scheme 让浏览器原生下拉按主题渲染；option 显式固定底色/文字色兜底
+      ".dshfs-select{color-scheme:light dark}",
+      ".dshfs-select option,.dshfs-select optgroup{background-color:#ffffff;color:#1f2328}",
+      "@media (prefers-color-scheme:dark){.dshfs-select{color-scheme:dark}.dshfs-select option,.dshfs-select optgroup{background-color:#1e1f24;color:#e8e8ea}}",
       ".dshfs-input{border:1px solid var(--dsw-alias-border-l2);font:inherit;font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-primary);background:var(--dsw-specific-input-major);border-radius:6px;padding:6px 8px;font-size:13px;transition:border-color .13s,box-shadow .13s;width:100%}",
       ".dshfs-ttl{width:88px}",
+      ".dshfs-fieldRow{display:flex;align-items:center;gap:8px;flex-wrap:wrap}",
+      ".dshfs-keyStorage{width:auto;min-width:180px}",
       ".dshfs-input:hover:not(:disabled){border-color:var(--dsw-alias-label-dimmed)}",
       ".dshfs-input:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}",
       ".dshfs-input:disabled{opacity:.6;cursor:default}",
@@ -67,6 +74,8 @@ window.__ModuleLoader__.load({
     }
     //#endregion
 
+    // bridge 路径副本，必须与 lib/index.js 的 BRIDGE_PREFIX（单一权威）保持一致。
+    // 客户端是独立浏览器 bundle，无法 import 服务端文件，只能各放一份；改动任一方需同步另一方。
     const BRIDGE_PREFIX = "/api/dsh-free-search-settings";
     const NS = "free-search";
     const I18N = {
@@ -84,7 +93,12 @@ window.__ModuleLoader__.load({
         perplexityPh: (c) => c ? "Perplexity API 密钥（已配置）" : "Perplexity API 密钥（pplx-...）",
         deepseekPh: (c) => c ? "DeepSeek API 密钥（已配置）" : "DeepSeek API 密钥（sk-...）",
         geminiPh: (c) => c ? "Gemini API 密钥（已配置）" : "Gemini API 密钥（免费层，联网搜索）",
-        keysHint: "密钥保存在 settings.yaml（界面脱敏显示）。为某引擎填写密钥后即可使用。",
+        keysHint: "密钥读取优先级：.credentials.yaml 凭据中心 > 这里 > 环境变量。推荐把 key 写进凭据中心（与官方 LLM 一致，一处管理）。",
+        keyStorage: "Key 存储位置",
+        keyStorageCred: "凭据中心（推荐）",
+        keyStorageSettings: "设置页（兼容）",
+        keyStorageCredHint: (c) => `保存后写入 ~/.dsh/.credentials.yaml（最高优先级）。当前已配置：${["exa", "tavily", "keenable", "perplexity", "deepseek", "gemini"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "无"}`,
+        keyStorageSettingsHint: "保存后写入 settings.yaml（向后兼容路径，优先级低于凭据中心）。",
         platformSearch: "平台搜索（platform_search 工具）",
         platformHint: "为 agent 的 platform_search 工具启用平台。禁用的平台会被跳过。",
         cacheTtl: "结果缓存时长（分钟）",
@@ -126,7 +140,12 @@ window.__ModuleLoader__.load({
         perplexityPh: (c) => c ? "Perplexity API key (configured)" : "Perplexity API key (pplx-...)",
         deepseekPh: (c) => c ? "DeepSeek API key (configured)" : "DeepSeek API key (sk-...)",
         geminiPh: (c) => c ? "Gemini API key (configured)" : "Gemini API key (free tier, web search)",
-        keysHint: "Keys are stored in settings.yaml (redacted in the UI). Enter a key for an engine to use it.",
+        keysHint: "Key resolution: .credentials.yaml credential center > here > environment variables. Recommended: store keys in the credential center (same as official LLM providers, one place for all).",
+        keyStorage: "Key storage",
+        keyStorageCred: "Credential center (recommended)",
+        keyStorageSettings: "Settings page (legacy)",
+        keyStorageCredHint: (c) => `Saved to ~/.dsh/.credentials.yaml (highest priority). Currently configured: ${["exa", "tavily", "keenable", "perplexity", "deepseek", "gemini"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "none"}`,
+        keyStorageSettingsHint: "Saved to settings.yaml (backward-compatible path; lower priority than the credential center).",
         platformSearch: "Platform search (platform_search tool)",
         platformHint: "Enable platforms for the agent's platform_search tool. Disabled platforms are skipped.",
         cacheTtl: "Result cache TTL (minutes)",
@@ -157,7 +176,7 @@ window.__ModuleLoader__.load({
     };
     const tt = (lang) => I18N[lang === "en" ? "en" : "zh"];
     // 当前插件版本（与 lib/index.js 的 PLUGIN_VERSION、package.json 保持一致）
-    const PLUGIN_VERSION = "0.5.4";
+    const PLUGIN_VERSION = "0.5.6";
     const ENGINES = [
       { id: "ddg", label: "DuckDuckGo · HTML", badge: "FREE", link: "https://duckduckgo.com" },
       { id: "ddg-lite", label: "DuckDuckGo · Lite", badge: "FREE", link: "https://duckduckgo.com" },
@@ -208,7 +227,54 @@ window.__ModuleLoader__.load({
       return response.json();
     }
 
+    async function bridgeCredentialsStatus() {
+      const response = await fetch(`${BRIDGE_PREFIX}/credentials-status`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      });
+      return response.json();
+    }
+
+    async function bridgeCredentialsSet(key, value) {
+      const response = await fetch(`${BRIDGE_PREFIX}/credentials-set`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ key, value }),
+      });
+      return response.json();
+    }
+
+    async function bridgeCredentialsUnset(key) {
+      const response = await fetch(`${BRIDGE_PREFIX}/credentials-unset`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ key }),
+      });
+      return response.json();
+    }
+
     function FreeSearchCard(props) {
+      // 检测应用主题深浅（读 body 的 --dsw-alias-bg-base 变量亮度），用于锁定原生下拉配色
+      const isDarkScheme = react.useMemo(() => {
+        try {
+          const root = document.body || document.documentElement;
+          const bg = getComputedStyle(root).getPropertyValue("--dsw-alias-bg-base").trim();
+          const m = bg.match(/(\d+)\s*[, ]\s*(\d+)\s*[, ]\s*(\d+)/);
+          if (m) {
+            const l = 0.299 * Number(m[1]) + 0.587 * Number(m[2]) + 0.114 * Number(m[3]);
+            return l < 128;
+          }
+          if (/^#([0-9a-f]{3,8})/i.test(bg)) {
+            const hex = bg.slice(1);
+            const h = hex.length <= 4 ? hex.replace(/./g, (c) => c + c) : hex;
+            const r = parseInt(h.slice(0, 2), 16), g = parseInt(h.slice(2, 4), 16), b = parseInt(h.slice(4, 6), 16);
+            return 0.299 * r + 0.587 * g + 0.114 * b < 128;
+          }
+        } catch {}
+        return typeof matchMedia === "function" ? matchMedia("(prefers-color-scheme: dark)").matches : false;
+      }, []);
+      const selectColorScheme = isDarkScheme ? "dark" : "light";
       const [open, setOpen] = react.useState(false);
       const [state, setState] = react.useState({ status: "loading" });
       const [provider, setProvider] = react.useState("bing");
@@ -221,6 +287,10 @@ window.__ModuleLoader__.load({
       const [platforms, setPlatforms] = react.useState(["github", "v2ex", "bilibili", "reddit", "hn", "stackoverflow", "wikipedia", "npm"]);
       const [cacheTtl, setCacheTtl] = react.useState(5);
       const [keysConfigured, setKeysConfigured] = react.useState({});
+      // key 存储位置：credentials（凭据中心，默认）| settings（设置页，兼容旧行为）
+      const [keyStorage, setKeyStorage] = react.useState("credentials");
+      // 凭据中心里已配置的 key（describe 不返回，需单独查）
+      const [credConfigured, setCredConfigured] = react.useState({});
       const [lang, setLang] = react.useState("zh");
       const [dirty, setDirty] = react.useState(false);
       const [saving, setSaving] = react.useState(false);
@@ -262,7 +332,21 @@ window.__ModuleLoader__.load({
                 }
               }
               setKeysConfigured(configured);
+              // key 存储位置（默认凭据中心）
+              setKeyStorage(v.keyStorage === "settings" ? "settings" : "credentials");
               setState({ status: "ready", writable: result.value.writable });
+              // 查询凭据中心里各 key 的配置状态
+              try {
+                const cred = await bridgeCredentialsStatus();
+                if (cred.ok) {
+                  const cc = {};
+                  const map = { exaApiKey: "exa", tavilyApiKey: "tavily", keenableApiKey: "keenable", perplexityApiKey: "perplexity", deepseekApiKey: "deepseek", geminiApiKey: "gemini" };
+                  for (const [k, v] of Object.entries(cred.value.configured ?? {})) {
+                    if (map[k]) cc[map[k]] = v;
+                  }
+                  setCredConfigured(cc);
+                }
+              } catch {}
             } else {
               setState({ status: "unavailable" });
             }
@@ -288,18 +372,36 @@ window.__ModuleLoader__.load({
         setSaving(true);
         setFailed(false);
         try {
+          // key 存储分流：凭据中心（默认）走 credentials-set；设置页走 settings mutate（兼容）
+          const keyFields = [
+            ["exaApiKey", exaKey],
+            ["tavilyApiKey", tavilyKey],
+            ["keenableApiKey", keenableKey],
+            ["perplexityApiKey", perplexityKey],
+            ["deepseekApiKey", deepseekKey],
+            ["geminiApiKey", geminiKey],
+          ];
+          let credFailed = false;
+          if (keyStorage === "credentials") {
+            for (const [field, value] of keyFields) {
+              if (!value.trim()) continue;
+              const r = await bridgeCredentialsSet(field, value.trim());
+              if (!r.ok) credFailed = true;
+            }
+          }
           const ops = [{ op: "set", path: ["provider"], value: provider }];
           ops.push({ op: "set", path: ["lang"], value: lang });
-          if (exaKey.trim()) ops.push({ op: "set", path: ["exaApiKey"], value: exaKey.trim() });
-          if (tavilyKey.trim()) ops.push({ op: "set", path: ["tavilyApiKey"], value: tavilyKey.trim() });
-          if (keenableKey.trim()) ops.push({ op: "set", path: ["keenableApiKey"], value: keenableKey.trim() });
-          if (perplexityKey.trim()) ops.push({ op: "set", path: ["perplexityApiKey"], value: perplexityKey.trim() });
-          if (deepseekKey.trim()) ops.push({ op: "set", path: ["deepseekApiKey"], value: deepseekKey.trim() });
-          if (geminiKey.trim()) ops.push({ op: "set", path: ["geminiApiKey"], value: geminiKey.trim() });
+          ops.push({ op: "set", path: ["keyStorage"], value: keyStorage });
+          if (keyStorage !== "credentials") {
+            // settings 模式：key 仍写 settings.yaml（旧行为）
+            for (const [field, value] of keyFields) {
+              if (value.trim()) ops.push({ op: "set", path: [field], value: value.trim() });
+            }
+          }
           ops.push({ op: "set", path: ["platforms"], value: platforms });
           ops.push({ op: "set", path: ["cacheTtl"], value: Math.min(Math.max(Number(cacheTtl) ?? 5, 0), 5) });
           const result = await bridgeMutate({ ns: NS, ops });
-          if (result.ok) {
+          if (result.ok && !credFailed) {
             setDirty(false);
             setProvider(result.value.value.provider ?? provider);
             setFailed(false);
@@ -452,6 +554,7 @@ react_jsx_runtime.jsx("div", {
                       react_jsx_runtime.jsx("select", {
                         className: "dshfs-select",
                         value: provider,
+                        style: { colorScheme: selectColorScheme },
                         disabled: !ready || saving,
                         onChange: (e) => select(e.target.value),
                         children: ENGINES.map((engine) =>
@@ -559,6 +662,34 @@ react_jsx_runtime.jsx("div", {
                         className: "dshfs-hint",
                         children: t.keysHint,
                       }),
+                      react_jsx_runtime.jsx("div", {
+                        className: "dshfs-fieldRow",
+                        children: [
+                          react_jsx_runtime.jsx("label", {
+                            className: "dshfs-label",
+                            children: t.keyStorage,
+                          }),
+                          react_jsx_runtime.jsx("select", {
+                            className: "dshfs-select dshfs-keyStorage",
+                            value: keyStorage,
+                            style: { colorScheme: selectColorScheme },
+                            disabled: !ready || saving,
+                            onChange: (e) => {
+                              setKeyStorage(e.target.value);
+                              setDirty(true);
+                              setFailed(false);
+                            },
+                            children: [
+                              react_jsx_runtime.jsx("option", { value: "credentials", children: t.keyStorageCred }),
+                              react_jsx_runtime.jsx("option", { value: "settings", children: t.keyStorageSettings }),
+                            ],
+                          }),
+                        ],
+                      }),
+                      react_jsx_runtime.jsx("p", {
+                        className: "dshfs-hint",
+                        children: keyStorage === "credentials" ? t.keyStorageCredHint(credConfigured) : t.keyStorageSettingsHint,
+                      }),
                     ],
                   }),
                   react_jsx_runtime.jsx("div", {

package/lib/index.js

@@ -16,8 +16,14 @@ const USER_AGENT =
 const ACCEPT_LANG = "zh-CN,zh;q=0.9,en;q=0.8";
 
 const FREE_SEARCH_NS = settingsNamespace("free-search");
+// bridge 路径的【单一权威】定义（M1）。
+// client.js 为独立浏览器 bundle，无法 import 本文件，故在其中保留一份同步副本（同名常量）；
+// 改动本路径时，必须同步改 lib/client.js 的 BRIDGE_PREFIX，否则两端桥接会断。
 const BRIDGE_PREFIX = "/api/dsh-free-search-settings";
-const FREE_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch"];
+// 免费引擎清单（导出为公共 API）。顺序必须与 search() 内部回退链 freeEngines 一致
+// （见下方 search() 中 const freeEngines = [...]）：bing 排最前（最稳的默认回退），
+// 其余按回退优先级排列；改动此处需同步改 freeEngines，否则导出顺序会误导维护者。
+const FREE_ENGINES = ["bing", "anysearch", "ddg", "ddg-lite", "searxng"];
 const ALL_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch", "exa", "tavily", "keenable", "perplexity", "deepseek-official", "gemini"];
 
 // Gemini (Google search grounding) 引擎。
@@ -28,7 +34,7 @@ const GEMINI_MODEL = "gemini-2.5-flash";
 const GEMINI_URL = `https://generativelanguage.googleapis.com/v1beta/models/${GEMINI_MODEL}:generateContent`;
 
 // 当前插件版本（发布时与 package.json 同步）
-const PLUGIN_VERSION = "0.5.4";
+const PLUGIN_VERSION = "0.5.6";
 // 检查更新的 npm registry 元数据地址（@darlingc/dsh-freesearch 是 npmjs 上的公开包）
 const NPM_REGISTRY_URL = "https://registry.npmjs.org/@darlingc%2Fdsh-freesearch/latest";
 const PLUGIN_NPM_URL = "https://www.npmjs.com/package/@darlingc/dsh-freesearch";
@@ -1185,7 +1191,7 @@ function toView(descriptor) {
   };
 }
 
-function makeBridgeRoutes(settings, search, testEngine) {
+function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
   const allowlisted = () =>
     settings
       .describe({ redactSecrets: true })
@@ -1338,6 +1344,52 @@ function makeBridgeRoutes(settings, search, testEngine) {
       }
       return { ok: true, value: toView(descriptor) };
     },
+    // 凭据中心：查询各引擎 key 的配置状态（value 不返回，只返回是否已配置）
+    async credentialsStatus() {
+      const credentials = getCredentials();
+      if (!credentials) return { ok: false, code: "credentials-unavailable", message: "credentials service is not available" };
+      const configured = {};
+      for (const [settingsKey, ref] of Object.entries(KEY_REF_MAP)) {
+        try {
+          const info = await credentials.describe(ref);
+          configured[settingsKey] = info !== undefined && info.configured === true;
+        } catch {
+          configured[settingsKey] = false;
+        }
+      }
+      return { ok: true, value: { configured, available: true } };
+    },
+    // 凭据中心：写入一个引擎 key（ref 白名单限定）
+    async credentialsSet(request) {
+      const credentials = getCredentials();
+      if (!credentials) return { ok: false, code: "credentials-unavailable", message: "credentials service is not available" };
+      const { key, value } = request ?? {};
+      const ref = KEY_REF_MAP[key];
+      if (!ref) return { ok: false, code: "credentials-rejected", message: `unknown credential key "${key}"` };
+      if (typeof value !== "string" || value.trim().length === 0) {
+        return { ok: false, code: "credentials-rejected", message: "value is required" };
+      }
+      try {
+        await credentials.set(ref, value.trim());
+        return { ok: true, value: { ref, set: true } };
+      } catch (error) {
+        return { ok: false, code: "credentials-write-failed", message: error instanceof Error ? error.message : String(error) };
+      }
+    },
+    // 凭据中心：删除一个引擎 key
+    async credentialsUnset(request) {
+      const credentials = getCredentials();
+      if (!credentials) return { ok: false, code: "credentials-unavailable", message: "credentials service is not available" };
+      const { key } = request ?? {};
+      const ref = KEY_REF_MAP[key];
+      if (!ref) return { ok: false, code: "credentials-rejected", message: `unknown credential key "${key}"` };
+      try {
+        await credentials.unset(ref);
+        return { ok: true, value: { ref, set: false } };
+      } catch (error) {
+        return { ok: false, code: "credentials-write-failed", message: error instanceof Error ? error.message : String(error) };
+      }
+    },
   };
 
   const guard = (req, res) => {
@@ -1374,6 +1426,40 @@ function makeBridgeRoutes(settings, search, testEngine) {
         writeJson(res, 200, await handlers.mutate(body));
       },
     },
+    {
+      kind: "exact",
+      path: `${BRIDGE_PREFIX}/credentials-status`,
+      handler: async (req, res) => {
+        if (!guard(req, res)) return;
+        writeJson(res, 200, await handlers.credentialsStatus());
+      },
+    },
+    {
+      kind: "exact",
+      path: `${BRIDGE_PREFIX}/credentials-set`,
+      handler: async (req, res) => {
+        if (!guard(req, res)) return;
+        const body = await readJsonBody(req);
+        if (body === undefined) {
+          writeJson(res, 400, { ok: false, code: "credentials-rejected", message: "malformed JSON body" });
+          return;
+        }
+        writeJson(res, 200, await handlers.credentialsSet(body));
+      },
+    },
+    {
+      kind: "exact",
+      path: `${BRIDGE_PREFIX}/credentials-unset`,
+      handler: async (req, res) => {
+        if (!guard(req, res)) return;
+        const body = await readJsonBody(req);
+        if (body === undefined) {
+          writeJson(res, 400, { ok: false, code: "credentials-rejected", message: "malformed JSON body" });
+          return;
+        }
+        writeJson(res, 200, await handlers.credentialsUnset(body));
+      },
+    },
     {
       kind: "exact",
       path: `${BRIDGE_PREFIX}/check-update`,
@@ -1410,10 +1496,21 @@ function makeBridgeRoutes(settings, search, testEngine) {
 const name = "web-search-free";
 const inject = ["web"];
 
+// 引擎 key 与凭据中心 ref 的映射（白名单：只允许这些 ref 被 UI 读写凭据中心）
+const KEY_REF_MAP = {
+  exaApiKey: "EXA_API_KEY",
+  tavilyApiKey: "TAVILY_API_KEY",
+  keenableApiKey: "KEENABLE_API_KEY",
+  perplexityApiKey: "PERPLEXITY_API_KEY",
+  deepseekApiKey: "DEEPSEEK_API_KEY",
+  geminiApiKey: "GEMINI_API_KEY",
+};
+
 const Config = z.object({
   provider: z.string().default("bing"),
   cache: z.boolean().default(true), // 单 query 结果缓存开关（防限流/省额度）
   cacheTtl: z.number().default(5), // 缓存时长（分钟），0-5 可配置（使用处再 clamp）
+  keyStorage: z.string().default("credentials"), // key 存储位置：credentials（凭据中心）| settings（设置页）
   lang: z.string().default("zh"),
   region: z.string(),
   bingMarket: z.string().default("zh-CN"),
@@ -1430,7 +1527,8 @@ const Config = z.object({
 function apply(ctx, config) {
   let current = () => config ?? {};
   const logger = ctx.logger;
-  const credentials = ctx.get("credentials");
+  // credentials 服务可能晚于本插件挂载（跨 bundle 顺序），运行期动态获取而不是 apply 时缓存
+  const getCredentials = () => ctx.get("credentials");
 
   // 系统提示词动态刷新：设置变更时重新生成，避免显示旧引擎
   let refreshPrompt = null;
@@ -1438,16 +1536,17 @@ function apply(ctx, config) {
   // 单 query 结果缓存（provider.search 内闭包持有）：LRU 50 条 / TTL 可配置
   const searchCache = new Map(); // key -> { value, expiresAt }
 
-  // key 优先级：settings 的 free-search.<x>ApiKey > 环境变量/credentials
+  // key 优先级：credentials（.credentials.yaml 凭据中心，官方推荐）> settings 的 free-search.<x>ApiKey（遗留兼容）> 环境变量
   const resolveApiKey = async (envName, settingsKey) => {
-    const cfg = current();
-    if (settingsKey && cfg[settingsKey]) return cfg[settingsKey];
+    const credentials = getCredentials();
     if (credentials) {
       try {
         const resolved = await credentials.resolve(envName);
         if (resolved?.value) return resolved.value;
       } catch {}
     }
+    const cfg = current();
+    if (settingsKey && cfg[settingsKey]) return cfg[settingsKey];
     return process.env[envName] ?? "";
   };
 
@@ -1655,7 +1754,8 @@ function apply(ctx, config) {
       const disposers = makeBridgeRoutes(
         sctx.settings,
         (request) => provider.search(request, undefined),
-        (engine, query, timeRange) => runEngineTest(engine, query, timeRange)
+        (engine, query, timeRange) => runEngineTest(engine, query, timeRange),
+        getCredentials
       ).map((route) => sctx.webServer.register(route));
       return () => {
         for (const dispose of disposers) dispose();
@@ -1938,7 +2038,7 @@ function apply(ctx, config) {
             },
             engine: {
               type: "string",
-              description: "Optional specific engine to try first: ddg, ddg-lite, bing, searxng, anysearch, exa, tavily, keenable, perplexity, deepseek-official.",
+              description: "Optional specific engine to try first: ddg, ddg-lite, bing, searxng, anysearch, exa, tavily, keenable, perplexity, deepseek-official, gemini.",
             },
           },
           output: {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@darlingc/dsh-freesearch",
-    "version": "0.5.4",
+    "version": "0.5.6",
     "description": "Free web search for DeepSeek Harness: 11 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable keyless + Gemini grounding) + time filtering + platform search + web_fetch, with web settings UI.",
     "type": "module",
     "main": "lib/index.js",
@@ -39,7 +39,7 @@
     },
     "repository": {
         "type": "git",
-        "url": "https://github.com/DarlingC/dsh-freesearch.git"
+        "url": "git+https://github.com/DarlingC/dsh-freesearch.git"
     },
     "engines": {
         "node": ">=20"
@@ -72,6 +72,9 @@
                 "@deepseek-ai/dsh-client-runtime"
             ],
             "platform": "web"
+        },
+        "engines": {
+            "dsh": ">=0.1.1-rc.1"
         }
     }
 }