@darlingc/dsh-freesearch 0.5.4 → 0.5.5

package/README.md

@@ -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.5），"检查更新"按钮直连 npm registry 对比最新版，有新版本时提示并可一键跳转
 - **结果缓存** —— 相同查询（含引擎/时间过滤参数）5 分钟内命中缓存（LRU 50 条），防免费引擎限流、省付费额度；时长可在设置页 0-5 分钟自由配置（0 关闭）
 - **免费标注** —— 设置页中免费引擎带绿色 `FREE` 徽章，付费引擎带橙色 `API KEY` 徽章
 - **网页抓取（web_fetch）** —— 让 agent 抓取网页内容（官方 `dsh-web-fetch-http` provider，纯 JS，零额外依赖）
@@ -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` 工具按此过滤）
@@ -307,7 +331,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.5), 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)
@@ -391,6 +415,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).

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}",
@@ -84,7 +91,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 +138,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 +174,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.5";
     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 +225,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 +285,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 +330,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 +370,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 +552,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 +660,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

@@ -28,7 +28,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.5";
 // 检查更新的 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 +1185,7 @@ function toView(descriptor) {
   };
 }
 
-function makeBridgeRoutes(settings, search, testEngine) {
+function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
   const allowlisted = () =>
     settings
       .describe({ redactSecrets: true })
@@ -1338,6 +1338,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 +1420,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 +1490,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 +1521,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 +1530,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 +1748,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();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@darlingc/dsh-freesearch",
-    "version": "0.5.4",
+    "version": "0.5.5",
     "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"
         }
     }
 }