dsh-free-search 0.4.20 → 0.4.22

package/lib/client.js

@@ -1,4 +1,4 @@
-window.__ModuleLoader__.load({
+window.__ModuleLoader__.load({
   id: "dsh-free-search",
   factory: (require) => {
     var module = { exports: {} };
@@ -30,8 +30,8 @@
       ".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 鏄惧紡鍥哄畾搴曡壊/鏂囧瓧鑹插厹搴?
+      // 下拉选项列表配色锁死：不随皮肤变量变化（皮肤只影响 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}}",
@@ -78,57 +78,57 @@
     const NS = "free-search";
     const I18N = {
       zh: {
-        description: "鍏嶈垂鎼滅储 鈥斺€?鏃犻渶 API key锛圔ing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable锛?,
-        unsaved: "鏈繚瀛?,
-        searchEngine: "鎼滅储寮曟搸",
-        visit: "璁块棶瀹樼綉 鈫?,
-        getKey: "鑾峰彇 API Key 鈫?,
-        engineHint: "Bing 鏄渶绋冲畾鐨勫厤璐瑰紩鎿庛€侱uckDuckGo 鍦ㄥ叡浜?IP 涓婂彲鑳介檺娴併€侫PI KEY 寮曟搸闇€鍦ㄤ笅鏂瑰～鍐欏嚟鎹€?,
-        apiKeys: "API 瀵嗛挜锛堝彲閫夛級",
-        exaPh: (c) => c ? "Exa API 瀵嗛挜锛堝凡閰嶇疆锛? : "Exa API 瀵嗛挜锛堝彲閫夛紝涓嶅～涔熷彲鍏嶈垂浣跨敤锛?,
-        tavilyPh: (c) => c ? "Tavily API 瀵嗛挜锛堝凡閰嶇疆锛? : "Tavily API 瀵嗛挜锛堝彲閫夛紝涓嶅～涔熷彲鍏嶈垂浣跨敤锛?,
-        keenablePh: (c) => c ? "Keenable API 瀵嗛挜锛堝凡閰嶇疆锛? : "Keenable API 瀵嗛挜锛堝彲閫夛紝涓嶅～涔熷彲鍏嶈垂浣跨敤锛?,
-        perplexityPh: (c) => c ? "Perplexity API 瀵嗛挜锛堝凡閰嶇疆锛? : "Perplexity API 瀵嗛挜锛坧plx-...锛?,
-        deepseekPh: (c) => c ? "DeepSeek API 瀵嗛挜锛堝凡閰嶇疆锛? : "DeepSeek API 瀵嗛挜锛坰k-...锛?,
-        keysHint: "瀵嗛挜璇诲彇浼樺厛绾э細.credentials.yaml 鍑嵁涓績 > 杩欓噷 > 鐜鍙橀噺銆傛帹鑽愭妸 key 鍐欒繘鍑嵁涓績锛堜笌瀹樻柟 LLM 涓€鑷达紝涓€澶勭鐞嗭級銆?,
-        keyStorage: "Key 瀛樺偍浣嶇疆",
-        keyStorageCred: "鍑嵁涓績锛堟帹鑽愶級",
-        keyStorageSettings: "璁剧疆椤碉紙鍏煎锛?,
-        keyStorageCredHint: (c) => `淇濆瓨鍚庡啓鍏?~/.dsh/.credentials.yaml锛堟渶楂樹紭鍏堢骇锛夈€傚綋鍓嶅凡閰嶇疆锛?{["exa", "tavily", "keenable", "perplexity", "deepseek"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "鏃?}`,
-        keyStorageSettingsHint: "淇濆瓨鍚庡啓鍏?settings.yaml锛堝悜鍚庡吋瀹硅矾寰勶紝浼樺厛绾т綆浜庡嚟鎹腑蹇冿級銆?,
-        platformSearch: "骞冲彴鎼滅储锛坧latform_search 宸ュ叿锛?,
-        platformHint: "涓?agent 鐨?platform_search 宸ュ叿鍚敤骞冲彴銆傜鐢ㄧ殑骞冲彴浼氳璺宠繃銆?,
-        cacheTtl: "缁撴灉缂撳瓨鏃堕暱锛堝垎閽燂級",
-        cacheTtlHint: "0 鍏抽棴缂撳瓨锛屾渶闀?5 鍒嗛挓銆傜缉鐭彲鍔犲揩鏃舵晥锛屽欢闀垮彲闃查檺娴併€佺渷棰濆害銆?,
-        unavailable: "璁剧疆涓嶅彲鐢?鈥斺€?free-search 妗ユ帴鏈毚闇层€?,
-        saveFailed: "淇濆瓨澶辫触",
-        testing: "娴嬭瘯涓€?,
-        testEngine: "娴嬭瘯寮曟搸",
-        useBing: "鎭㈠ Bing 榛樿",
-        discard: "鎾ら攢",
-        saving: "淇濆瓨涓€?,
-        save: "淇濆瓨",
-        testOk: (r) => `鉁?${r.count} 鏉＄粨鏋滐紙寮曟搸: ${r.engine}锛?{r.content ? ` 鈥?${r.content}` : ""}${r.sample ? ` 路 渚嬪 "${r.sample.slice(0, 40)}"` : ""}`,
-        testFail: (e) => `鉁?${e}`,
+        description: "免费搜索 —— 无需 API key（Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable）",
+        unsaved: "未保存",
+        searchEngine: "搜索引擎",
+        visit: "访问官网 →",
+        getKey: "获取 API Key →",
+        engineHint: "Bing 是最稳定的免费引擎。DuckDuckGo 在共享 IP 上可能限流。API KEY 引擎需在下方填写凭据。",
+        apiKeys: "API 密钥（可选）",
+        exaPh: (c) => c ? "Exa API 密钥（已配置）" : "Exa API 密钥（可选，不填也可免费使用）",
+        tavilyPh: (c) => c ? "Tavily API 密钥（已配置）" : "Tavily API 密钥（可选，不填也可免费使用）",
+        keenablePh: (c) => c ? "Keenable API 密钥（已配置）" : "Keenable API 密钥（可选，不填也可免费使用）",
+        perplexityPh: (c) => c ? "Perplexity API 密钥（已配置）" : "Perplexity API 密钥（pplx-...）",
+        deepseekPh: (c) => c ? "DeepSeek API 密钥（已配置）" : "DeepSeek API 密钥（sk-...）",
+        keysHint: "密钥读取优先级：.credentials.yaml 凭据中心 > 这里 > 环境变量。推荐把 key 写进凭据中心（与官方 LLM 一致，一处管理）。",
+        keyStorage: "Key 存储位置",
+        keyStorageCred: "凭据中心（推荐）",
+        keyStorageSettings: "设置页（兼容）",
+        keyStorageCredHint: (c) => `保存后写入 ~/.dsh/.credentials.yaml（最高优先级）。当前已配置：${["exa", "tavily", "keenable", "perplexity", "deepseek"].filter((k) => c[k]).map((k) => k.toUpperCase()).join(", ") || "无"}`,
+        keyStorageSettingsHint: "保存后写入 settings.yaml（向后兼容路径，优先级低于凭据中心）。",
+        platformSearch: "平台搜索（platform_search 工具）",
+        platformHint: "为 agent 的 platform_search 工具启用平台。禁用的平台会被跳过。",
+        cacheTtl: "结果缓存时长（分钟）",
+        cacheTtlHint: "0 关闭缓存，最长 5 分钟。缩短可加快时效，延长可防限流、省额度。",
+        unavailable: "设置不可用 —— free-search 桥接未暴露。",
+        saveFailed: "保存失败",
+        testing: "测试中…",
+        testEngine: "测试引擎",
+        useBing: "恢复 Bing 默认",
+        discard: "撤销",
+        saving: "保存中…",
+        save: "保存",
+        testOk: (r) => `✓ ${r.count} 条结果（引擎: ${r.engine}）${r.content ? ` — ${r.content}` : ""}${r.sample ? ` · 例如 "${r.sample.slice(0, 40)}"` : ""}`,
+        testFail: (e) => `✗ ${e}`,
         toggleLang: "EN",
-        checkUpdate: "妫€鏌ユ洿鏂?,
-        checkingUpdate: "妫€鏌ヤ腑鈥?,
-        updateAvailable: (c, l) => `鍙戠幇鏂扮増鏈?v${l}锛堝綋鍓?v${c}锛塦,
-        updateLatest: (c) => `宸叉槸鏈€鏂扮増鏈?v${c}`,
-        updateCheckFailed: "妫€鏌ユ洿鏂板け璐ワ紙鏃犳硶璁块棶 npm registry锛?,
-        updateView: "鏌ョ湅 鈫?,
-        upgrade: "鍗囩骇",
-        upgrading: "鍗囩骇涓€?,
-        upgradeLinkMode: "锛堟湰鍦板紑鍙戞ā寮忥紝鍗囩骇璇风敤 git pull锛?,
-        upgradeDone: (l) => `鍗囩骇鍒?v${l} 瀹屾垚锛岄噸鍚?dsh 鍚庣敓鏁坄,
-        upgradeFailed: (m) => `鍗囩骇澶辫触锛?{m}`,
+        checkUpdate: "检查更新",
+        checkingUpdate: "检查中…",
+        updateAvailable: (c, l) => `发现新版本 v${l}（当前 v${c}）`,
+        updateLatest: (c) => `已是最新版本 v${c}`,
+        updateCheckFailed: "检查更新失败（无法访问 npm registry）",
+        updateView: "查看 →",
+        upgrade: "升级",
+        upgrading: "升级中…",
+        upgradeLinkMode: "（本地开发模式，升级请用 git pull）",
+        upgradeDone: (l) => `升级到 v${l} 完成，重启 dsh 后生效`,
+        upgradeFailed: (m) => `升级失败：${m}`,
       },
       en: {
-        description: "Free web search 鈥?no API key needed (Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable)",
+        description: "Free web search — no API key needed (Bing / DuckDuckGo / AnySearch / Exa / Tavily / Keenable)",
         unsaved: "unsaved",
         searchEngine: "Search engine",
-        visit: "Visit website 鈫?,
-        getKey: "Get API Key 鈫?,
+        visit: "Visit website →",
+        getKey: "Get API Key →",
         engineHint: "Bing is the most stable FREE engine. DuckDuckGo may rate-limit on shared IPs. API KEY engines need credentials below.",
         apiKeys: "API keys (optional)",
         exaPh: (c) => c ? "Exa API key (configured)" : "Exa API key (optional, free without)",
@@ -146,39 +146,39 @@
         platformHint: "Enable platforms for the agent's platform_search tool. Disabled platforms are skipped.",
         cacheTtl: "Result cache TTL (minutes)",
         cacheTtlHint: "0 disables caching, max 5 minutes. Lower = fresher results, higher = less rate-limiting / fewer credits used.",
-        unavailable: "Settings unavailable 鈥?the free-search bridge is not exposed.",
+        unavailable: "Settings unavailable — the free-search bridge is not exposed.",
         saveFailed: "save failed",
-        testing: "Testing鈥?,
+        testing: "Testing…",
         testEngine: "Test engine",
         useBing: "Use Bing default",
         discard: "Discard",
-        saving: "Saving鈥?,
+        saving: "Saving…",
         save: "Save",
-        testOk: (r) => `鉁?${r.count} results (engine: ${r.engine})${r.content ? ` 鈥?${r.content}` : ""}${r.sample ? ` 路 e.g. "${r.sample.slice(0, 40)}"` : ""}`,
-        testFail: (e) => `鉁?${e}`,
-        toggleLang: "涓枃",
+        testOk: (r) => `✓ ${r.count} results (engine: ${r.engine})${r.content ? ` — ${r.content}` : ""}${r.sample ? ` · e.g. "${r.sample.slice(0, 40)}"` : ""}`,
+        testFail: (e) => `✗ ${e}`,
+        toggleLang: "中文",
         checkUpdate: "Check update",
-        checkingUpdate: "Checking鈥?,
+        checkingUpdate: "Checking…",
         updateAvailable: (c, l) => `New version v${l} available (current v${c})`,
         updateLatest: (c) => `You're on the latest version v${c}`,
         updateCheckFailed: "Update check failed (cannot reach npm registry)",
-        updateView: "View 鈫?,
+        updateView: "View →",
         upgrade: "Upgrade",
-        upgrading: "Upgrading鈥?,
+        upgrading: "Upgrading…",
         upgradeLinkMode: "(local dev install - use git pull to update)",
         upgradeDone: (l) => `Upgraded to v${l} - restart dsh to apply`,
-        upgradeFailed: (m) => `Upgrade failed: ${m}`,
+        upgradeFailed: (m) => `Upgrade failed: ${m}`,
       },
     };
     const tt = (lang) => I18N[lang === "en" ? "en" : "zh"];
-    // 褰撳墠鎻掍欢鐗堟湰锛堜笌 lib/index.js 鐨?PLUGIN_VERSION 淇濇寔涓€鑷达級
-    const PLUGIN_VERSION = "0.4.20";
+    // 当前插件版本（与 lib/index.js 的 PLUGIN_VERSION 保持一致）
+    const PLUGIN_VERSION = "0.4.22";
     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" },
+      { id: "ddg", label: "DuckDuckGo · HTML", badge: "FREE", link: "https://duckduckgo.com" },
+      { id: "ddg-lite", label: "DuckDuckGo · Lite", badge: "FREE", link: "https://duckduckgo.com" },
       { id: "bing", label: "Bing", badge: "FREE", link: "https://www.bing.com" },
-      { id: "anysearch", label: "AnySearch 路 AI", badge: "FREE", link: "https://anysearch.com" },
-      { id: "searxng", label: "SearXNG 路 鍏冩悳绱?, badge: "FREE", link: "https://github.com/searxng/searxng" },
+      { id: "anysearch", label: "AnySearch · AI", badge: "FREE", link: "https://anysearch.com" },
+      { id: "searxng", label: "SearXNG · 元搜索", badge: "FREE", link: "https://github.com/searxng/searxng" },
       { id: "exa", label: "Exa", badge: "FREE", link: "https://dashboard.exa.ai/api-keys" },
       { id: "tavily", label: "Tavily", badge: "FREE", link: "https://app.tavily.com/home" },
       { id: "keenable", label: "Keenable", badge: "FREE", link: "https://keenable.ai/login" },
@@ -250,7 +250,7 @@
     }
 
     function FreeSearchCard(props) {
-      // 妫€娴嬪簲鐢ㄤ富棰樻繁娴咃紙璇?body 鐨?--dsw-alias-bg-base 鍙橀噺浜害锛夛紝鐢ㄤ簬閿佸畾鍘熺敓涓嬫媺閰嶈壊
+      // 检测应用主题深浅（读 body 的 --dsw-alias-bg-base 变量亮度），用于锁定原生下拉配色
       const isDarkScheme = react.useMemo(() => {
         try {
           const root = document.body || document.documentElement;
@@ -282,9 +282,9 @@
       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 瀛樺偍浣嶇疆锛歝redentials锛堝嚟鎹腑蹇冿紝榛樿锛墊 settings锛堣缃〉锛屽吋瀹规棫琛屼负锛?
+      // key 存储位置：credentials（凭据中心，默认）| settings（设置页，兼容旧行为）
       const [keyStorage, setKeyStorage] = react.useState("credentials");
-      // 鍑嵁涓績閲屽凡閰嶇疆鐨?key锛坉escribe 涓嶈繑鍥烇紝闇€鍗曠嫭鏌ワ級
+      // 凭据中心里已配置的 key（describe 不返回，需单独查）
       const [credConfigured, setCredConfigured] = react.useState({});
       const [lang, setLang] = react.useState("zh");
       const [dirty, setDirty] = react.useState(false);
@@ -313,7 +313,7 @@
               setDeepseekKey(v.deepseekApiKey ?? "");
               setPlatforms(Array.isArray(v.platforms) && v.platforms.length > 0 ? v.platforms : ["github", "v2ex", "bilibili", "reddit", "hn", "stackoverflow", "wikipedia", "npm"]);
               setCacheTtl(v.cacheTtl === undefined ? 5 : Math.min(Math.max(Number(v.cacheTtl) ?? 5, 0), 5));
-              // secrets 瀛楁鏍囪鍝簺 key 宸查厤缃紙鍊艰鑴辨晱锛屼粎鏄剧ず"宸查厤缃?锛?
+              // secrets 字段标记哪些 key 已配置（值被脱敏，仅显示"已配置"）
               const configured = {};
               for (const secret of view.secrets ?? []) {
                 if (secret.set) {
@@ -326,10 +326,10 @@
                 }
               }
               setKeysConfigured(configured);
-              // key 瀛樺偍浣嶇疆锛堥粯璁ゅ嚟鎹腑蹇冿級
+              // key 存储位置（默认凭据中心）
               setKeyStorage(v.keyStorage === "settings" ? "settings" : "credentials");
               setState({ status: "ready", writable: result.value.writable });
-              // 鏌ヨ鍑嵁涓績閲屽悇 key 鐨勯厤缃姸鎬?
+              // 查询凭据中心里各 key 的配置状态
               try {
                 const cred = await bridgeCredentialsStatus();
                 if (cred.ok) {
@@ -366,7 +366,7 @@
         setSaving(true);
         setFailed(false);
         try {
-          // key 瀛樺偍鍒嗘祦锛氬嚟鎹腑蹇冿紙榛樿锛夎蛋 credentials-set锛涜缃〉璧?settings mutate锛堝吋瀹癸級
+          // key 存储分流：凭据中心（默认）走 credentials-set；设置页走 settings mutate（兼容）
           const keyFields = [
             ["exaApiKey", exaKey],
             ["tavilyApiKey", tavilyKey],
@@ -387,7 +387,7 @@
           ops.push({ op: "set", path: ["keyStorage"], value: keyStorage });
           ops.push({ op: "set", path: ["safeSearch"], value: safeSearch });
           if (keyStorage !== "credentials") {
-            // settings 妯″紡锛歬ey 浠嶅啓 settings.yaml锛堟棫琛屼负锛?
+            // settings 模式：key 仍写 settings.yaml（旧行为）
             for (const [field, value] of keyFields) {
               if (value.trim()) ops.push({ op: "set", path: [field], value: value.trim() });
             }
@@ -527,7 +527,7 @@
               }),
               react_jsx_runtime.jsx("span", {
                 className: open ? "dshfs-chevron dshfs-chevronOpen" : "dshfs-chevron",
-                children: "鈻?,
+                children: "▾",
               }),
             ],
           }),
@@ -890,8 +890,8 @@ react_jsx_runtime.jsx("div", {
     const inject = ["slots", "commandUi"];
 
     function apply(ctx) {
-      // 鎸傚畼鏂规彃妲?settings.plugin.item锛堣缃?鈫?鎻掍欢 鈫?鍙厤缃爣绛鹃〉锛夈€?
-      // 涓嶄緷璧?dsh-web-ui锛氶厤缃鍐欒蛋鑷缓 bridge锛?api/dsh-free-search-settings锛夈€?
+      // 挂官方插槽 settings.plugin.item（设置 → 插件 → 可配置标签页）。
+      // 不依赖 dsh-web-ui：配置读写走自建 bridge（/api/dsh-free-search-settings）。
       ctx.slots.inject("settings.plugin.item", () =>
         ctx.slots.register(
           {
@@ -904,14 +904,14 @@ react_jsx_runtime.jsx("div", {
           FreeSearchCard
         )
       );
-      // /free-search-engine 寮瑰嚭寮忓懡浠わ細杈撳叆 "/" 閫変腑鍚庡脊鍑哄紩鎿庡垪琛紝鐐归€夊嵆鍒囨崲銆?
-      // 绛夋晥浜庤缃〉鍒囨崲寮曟搸+淇濆瓨锛涘懡浠ゅ彧鏀?provider 閰嶇疆锛屾悳绱粛璧板洖閫€閾俱€?
+      // /free-search-engine 弹出式命令：输入 "/" 选中后弹出引擎列表，点选即切换。
+      // 等效于设置页切换引擎+保存；命令只改 provider 配置，搜索仍走回退链。
       ctx.inject(["commandUi"], (sctx) => {
         const command = sctx.get("commandUi");
         sctx.effect(() => {
           const dispose = command.register({
             name: "free-search-engine",
-            description: "鍒囨崲鎼滅储寮曟搸 / Switch web search engine",
+            description: "切换搜索引擎 / Switch web search engine",
             available: () => true,
             ui: {
               kind: "popupSelect",
@@ -921,8 +921,8 @@ react_jsx_runtime.jsx("div", {
                 const current = view?.value?.provider ?? "bing";
                 return ENGINES.map((e) => ({
                   id: e.id,
-                  label: `${e.label}${e.badge === "FREE" ? " 路 鍏嶈垂" : " 路 API Key"}`,
-                  detail: e.id === current ? (view?.value?.lang === "en" ? "current" : "褰撳墠") : undefined,
+                  label: `${e.label}${e.badge === "FREE" ? " · 免费" : " · API Key"}`,
+                  detail: e.id === current ? (view?.value?.lang === "en" ? "current" : "当前") : undefined,
                   active: e.id === current,
                 }));
               },

package/lib/index.js

@@ -1,4 +1,4 @@
-import { SettingsConflictError, SettingsProvider } from "@deepseek-ai/dsh-settings";
+import { SettingsConflictError, SettingsProvider } from "@deepseek-ai/dsh-settings";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import z from "@deepseek-ai/schemastery";
 import fs from "node:fs";
@@ -20,14 +20,14 @@ const BRIDGE_PREFIX = "/api/dsh-free-search-settings";
 const FREE_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch"];
 const ALL_ENGINES = ["ddg", "ddg-lite", "bing", "searxng", "anysearch", "exa", "tavily", "keenable", "perplexity", "deepseek-official"];
 
-// 褰撳墠鎻掍欢鐗堟湰锛堝彂甯冩椂涓?package.json 鍚屾锛?
-const PLUGIN_VERSION = "0.4.20";
-// 妫€鏌ユ洿鏂扮殑 npm registry 鍏冩暟鎹湴鍧€锛坉sh-free-search 鏄?npmjs 涓婄殑鍏紑鍖咃級
+// 当前插件版本（发布时与 package.json 同步）
+const PLUGIN_VERSION = "0.4.22";
+// 检查更新的 npm registry 元数据地址（dsh-free-search 是 npmjs 上的公开包）
 const NPM_REGISTRY_URL = "https://registry.npmjs.org/dsh-free-search/latest";
 const PLUGIN_NPM_URL = "https://www.npmjs.com/package/dsh-free-search";
 const PLUGIN_REPO_URL = "https://github.com/DDDMUC/dsh-free-search";
 
-// 鏌ヨ npm registry 鐨勬渶鏂扮増鏈紱澶辫触鏃惰繑鍥?null锛堢綉缁?浠ｇ悊闂涓嶉樆濉炶缃〉锛?
+// 查询 npm registry 的最新版本；失败时返回 null（网络/代理问题不阻塞设置页）
 async function fetchLatestVersion(signal) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 10000);
@@ -49,7 +49,7 @@ async function fetchLatestVersion(signal) {
   }
 }
 
-// 绠€鍗曠殑 semver 姣旇緝锛堜粎澶勭悊 x.y.z 涓?娆?琛ヤ竵锛屽拷鐣ラ鍙戝竷鏍囩锛夛紱a>b 杩斿洖 1, a<b 杩斿洖 -1, 鐩哥瓑杩斿洖 0
+// 简单的 semver 比较（仅处理 x.y.z 主/次/补丁，忽略预发布标签）；a>b 返回 1, a<b 返回 -1, 相等返回 0
 function compareVersions(a, b) {
   const na = String(a).split(".").map((n) => parseInt(n, 10) || 0);
   const nb = String(b).split(".").map((n) => parseInt(n, 10) || 0);
@@ -60,8 +60,8 @@ function compareVersions(a, b) {
   return 0;
 }
 
-// 妫€娴嬫彃浠剁殑瀹夎妯″紡锛氶亶鍘?profiles/*/node_modules/dsh-free-search锛?
-// symlink锛坙ink: 鏈湴寮€鍙戯級鈫?isLink=true锛沶pm 鐪熷畨瑁?鈫?isLink=false锛涙壘涓嶅埌 鈫?null
+// 检测插件的安装模式：遍历 profiles/*/node_modules/dsh-free-search，
+// symlink（link: 本地开发）→ isLink=true；npm 真安装 → isLink=false；找不到 → null
 function detectInstallMode() {
   const profilesDir = path.join(process.cwd(), "profiles");
   let found = null;
@@ -80,7 +80,7 @@ function detectInstallMode() {
   return found;
 }
 
-// time_range 鏀寔锛氬浐瀹氭。 day/week/month/year锛屾垨鑷畾涔夛紙鐩稿 12h/3d/2mo/1y銆佺粷瀵?YYYY-MM-DD锛?
+// time_range 支持：固定档 day/week/month/year，或自定义（相对 12h/3d/2mo/1y、绝对 YYYY-MM-DD）
 const TIME_RANGES = ["day", "week", "month", "year"];
 const DAYS_BY_RANGE = { day: 1, week: 7, month: 30, year: 365 };
 const KEENABLE_REL = { day: "1d", week: "7d", month: "1mo", year: "1y" };
@@ -90,12 +90,12 @@ function isoDaysAgo(days) {
   return new Date(Date.now() - days * 86_400_000).toISOString().replace(/\.\d{3}Z$/, ".000Z");
 }
 
-// 鎶婄敤鎴?agent 缁欑殑 timeRange 瑙ｆ瀽鎴愮粺涓€瀵硅薄锛歿 days } 鐩稿澶╂暟锛屾垨 { after } 缁濆鏃ユ湡銆?
-// 杈撳叆鏀寔锛歞ay/week/month/year銆?2h/3d/2mo/1y銆?026-07-01锛屾垨宸茶В鏋愮殑 {days}/{after} 瀵硅薄銆?
-// 鏃犳晥杩斿洖 undefined銆?
+// 把用户/agent 给的 timeRange 解析成统一对象：{ days } 相对天数，或 { after } 绝对日期。
+// 输入支持：day/week/month/year、12h/3d/2mo/1y、2026-07-01，或已解析的 {days}/{after} 对象。
+// 无效返回 undefined。
 function parseTimeRange(input) {
   if (input === undefined || input === null) return undefined;
-  // 宸茶В鏋愬璞★細鐩存帴閫忎紶
+  // 已解析对象：直接透传
   if (typeof input === "object") {
     if (typeof input.after === "string" && /^\d{4}-\d{2}-\d{2}$/.test(input.after)) return { after: input.after };
     if (typeof input.days === "number" && Number.isFinite(input.days) && input.days > 0) return { days: input.days };
@@ -116,7 +116,7 @@ function parseTimeRange(input) {
   return undefined;
 }
 
-// 鎶婅嚜瀹氫箟澶╂暟鏄犲皠鍒板彧鏀寔鍥哄畾妗ｇ殑寮曟搸锛圱avily / SearXNG / DDG锛夌殑鏈€杩戜技妗ｄ綅
+// 把自定义天数映射到只支持固定档的引擎（Tavily / SearXNG / DDG）的最近似档位
 function approximateTimeRange(days) {
   if (days <= 2) return "day";
   if (days <= 14) return "week";
@@ -136,18 +136,18 @@ function decodeEntities(text) {
     .replace(/&#(\d+);/g, (_, n) => String.fromCharCode(Number(n)));
 }
 
-//#region 缁撴灉缂撳瓨锛堥槻闄愭祦/鐪侀搴︼紝LRU 50 鏉★紝TTL 鍙厤缃?0-5 鍒嗛挓锛?
+//#region 结果缓存（防限流/省额度，LRU 50 条，TTL 可配置 0-5 分钟）
 const CACHE_MAX_ENTRIES = 50;
-// fallback 鏉＄洰锛堝疄闄呭紩鎿?鈮?棣栭€夊紩鎿庢椂锛塗TL = 閰嶇疆 TTL 鐨?1/5锛堥粯璁?5 鍒嗛挓 鈫?60s锛夛細
-// 棣栭€夊紩鎿庢仮澶嶅悗鏈€澶?1 鍒嗛挓鍗冲彲鎷垮埌鏂扮粨鏋滐紝閬垮厤鍥為€€缁撴灉琚畬鏁?TTL 閽夋锛涢閫夋垚鍔熸潯鐩粛鐢ㄥ畬鏁?TTL銆?
+// fallback 条目（实际引擎 ≠ 首选引擎时）TTL = 配置 TTL 的 1/5（默认 5 分钟 → 60s）：
+// 首选引擎恢复后最多 1 分钟即可拿到新结果，避免回退结果被完整 TTL 钉死；首选成功条目仍用完整 TTL。
 
 function buildCacheKey(query, maxResults, timeRangeLabel, preferred) {
   return [query ?? "", maxResults ?? 5, timeRangeLabel ?? "", preferred].join("\u0000");
 }
 //#endregion
 
-// 缁熶竴鐨?snippet 娓呮礂锛氬墧闄ょ櫥褰?浠樿垂澧?璁㈤槄绛夊櫔闊崇煭璇紝鎶樺彔绌虹櫧锛岄檺鍒堕暱搴︺€?
-// 鍙湪鍥為€€閾惧嚭鍙ｇ粺涓€搴旂敤锛屽悇寮曟搸鍐呴儴涓嶅仛锛岄伩鍏嶉噸澶嶅鐞嗐€?
+// 统一的 snippet 清洗：剔除登录/付费墙/订阅等噪音短语，折叠空白，限制长度。
+// 只在回退链出口统一应用，各引擎内部不做，避免重复处理。
 const SNIPPET_NOISE =
   /\b(sign up|sign in|log in|login|subscribe( to| for)?|member[- ]?only|become a member|create (a )?free account|read more|continue reading|story continues|get started|install (the )?app|view on|medium membership|join \w+ for free|get updates from this writer|stories in your inbox|remember me for|unlock this|free to read|become a patron)\b/gi;
 
@@ -193,7 +193,7 @@ function uniqueSources(sources, limit) {
 }
 
 async function fetchHtml(url, signal) {
-  // 鍗曟璇锋眰瓒呮椂 12s锛岄伩鍏嶆寕璧疯褰撴垚 Connection error
+  // 单次请求超时 12s，避免挂起被当成 Connection error
   let response;
   try {
     const controller = new AbortController();
@@ -215,14 +215,14 @@ async function fetchHtml(url, signal) {
     throw new Error(`HTTP ${response.status} from ${url.split("?")[0]}`);
   }
   const html = await response.text();
-  // DuckDuckGo 鍙嶇埇楠岃瘉椤垫娴嬶紙HTTP 202 鎴栭獙璇佸叧閿瓧锛?
+  // DuckDuckGo 反爬验证页检测（HTTP 202 或验证关键字）
   if (response.status === 202 || /anomaly|captcha|unusual traffic|robot check/i.test(html.slice(0, 4000))) {
     throw new Error("DuckDuckGo is rate-limited right now (anti-bot challenge, usually temporary) - Bing works");
   }
   return html;
 }
 
-// 甯﹂噸璇曠殑鎶撳彇锛氱綉缁滈敊璇?绌虹粨鏋滄椂閲嶈瘯锛岄棿闅?1.5s锛屾渶澶?3 娆?
+// 带重试的抓取：网络错误/空结果时重试，间隔 1.5s，最多 3 次
 async function fetchHtmlWithRetry(url, signal) {
   let lastError;
   for (let attempt = 1; attempt <= 3; attempt++) {
@@ -241,10 +241,10 @@ async function fetchHtmlWithRetry(url, signal) {
 async function searchDdgHtml(query, maxResults, options, signal) {
   const params = new URLSearchParams({ q: query });
   if (options?.region) params.set("kl", options.region);
-  // DDG 瀹夊叏鎼滅储锛歰ff(adlt=-1) / moderate(adlt=0) / strict(adlt=1)
+  // DDG 安全搜索：off(adlt=-1) / moderate(adlt=0) / strict(adlt=1)
   const adlt = options?.safeSearch ?? "off";
   params.set("adlt", adlt === "strict" ? "1" : adlt === "moderate" ? "0" : "-1");
-  // DDG 鏃堕棿杩囨护锛歞f=d/w/m/y锛堝彧鏀寔鍥哄畾妗ｏ紝鑷畾涔夊彇杩戜技妗ｏ級
+  // DDG 时间过滤：df=d/w/m/y（只支持固定档，自定义取近似档）
   if (options?.timeRange) {
     const df = { day: "d", week: "w", month: "m", year: "y" }[approximateTimeRange(options.timeRange.days ?? 7)];
     if (df) params.set("df", df);
@@ -273,7 +273,7 @@ async function searchDdgLite(query, maxResults, options, signal) {
   const params = new URLSearchParams({ q: query });
   const adlt = options?.safeSearch ?? "off";
   params.set("adlt", adlt === "strict" ? "1" : adlt === "moderate" ? "0" : "-1");
-  // DDG Lite 鍚屾牱鏀寔 df 鏃堕棿杩囨护
+  // DDG Lite 同样支持 df 时间过滤
   if (options?.timeRange) {
     const df = { day: "d", week: "w", month: "m", year: "y" }[approximateTimeRange(options.timeRange.days ?? 7)];
     if (df) params.set("df", df);
@@ -336,12 +336,12 @@ async function searchSearxng(query, maxResults, options, signal) {
   const instances = options?.searxngInstances?.length
     ? options.searxngInstances
     : SEARXNG_INSTANCES;
-  // 鑱氬悎鎵€鏈夊疄渚嬬殑澶辫触鍘熷洜锛岄伩鍏嶅彧鏄剧ず鏈€鍚庝竴涓疄渚嬬殑閿欒
+  // 聚合所有实例的失败原因，避免只显示最后一个实例的错误
   const errors = [];
   for (const base of instances) {
     try {
       const params = new URLSearchParams({ q: query, format: "json" });
-      // SearXNG 鍘熺敓鏀寔 time_range 杩囨护锛堝彧鏀寔鍥哄畾妗ｏ紝鑷畾涔夊彇杩戜技妗ｏ級
+      // SearXNG 原生支持 time_range 过滤（只支持固定档，自定义取近似档）
       if (options?.timeRange) {
         const tr = SEARXNG_TIME[approximateTimeRange(options.timeRange.days ?? 7)];
         if (tr) params.set("time_range", tr);
@@ -381,9 +381,9 @@ async function searchSearxng(query, maxResults, options, signal) {
       errors.push(`${base}: ${message}`);
     }
   }
-  // 绌哄疄渚嬪垪琛ㄥ厹搴曪細閬垮厤 "all SearXNG instances failed: " 灏惧反鎮┖
+  // 空实例列表兜底：避免 "all SearXNG instances failed: " 尾巴悬空
   const detail = errors.length > 0 ? errors.join(", ") : "no instances configured";
-  // Note 浼氬紩鐢ㄨ繖涓敊璇秷鎭紝鎴柇閬垮厤 6 瀹炰緥鍏ㄦ寕鏃跺埛灞?
+  // Note 会引用这个错误消息，截断避免 6 实例全挂时刷屏
   throw new Error(`all SearXNG instances failed: ${detail.slice(0, 300)}`);
 }
 //#endregion
@@ -392,7 +392,7 @@ async function searchSearxng(query, maxResults, options, signal) {
 const ANYSEARCH_URL = "https://api.anysearch.com/v1/search";
 const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
 
-// AnySearch: 鍏嶈垂鍖垮悕棰濆害锛堟棤 key锛夛紝缁撴瀯鍖?JSON 缁撴灉
+// AnySearch: 免费匿名额度（无 key），结构化 JSON 结果
 async function searchAnysearch(query, maxResults, signal) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 12000);
@@ -429,7 +429,7 @@ async function searchAnysearch(query, maxResults, signal) {
   };
 }
 
-// Exa MCP: 鍖垮悕鍏紑 MCP锛堟棤 key锛夛紝web_search_exa 宸ュ叿
+// Exa MCP: 匿名公开 MCP（无 key），web_search_exa 工具
 async function searchExaMCP(query, maxResults, signal) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 20000);
@@ -457,7 +457,7 @@ async function searchExaMCP(query, maxResults, signal) {
   }
   if (!response.ok) throw new Error(`Exa MCP error (HTTP ${response.status})`);
   const text = await response.text();
-  // 瑙ｆ瀽 SSE 鏍煎紡锛歟vent: message\ndata: {...}
+  // 解析 SSE 格式：event: message\ndata: {...}
   const lines = text.split("\n");
   let json = null;
   for (const line of lines) {
@@ -477,7 +477,7 @@ async function searchExaMCP(query, maxResults, signal) {
     .filter((b) => b.type === "text")
     .map((b) => b.text)
     .join("\n");
-  // 瑙ｆ瀽 "Title: X\nURL: Y\nPublished: Z\nHighlights:\n..."
+  // 解析 "Title: X\nURL: Y\nPublished: Z\nHighlights:\n..."
   const blocks = textBlocks.split(/\n(?=Title:)/);
   for (const block of blocks) {
     const title = block.match(/^Title: (.+)$/m)?.[1];
@@ -489,7 +489,7 @@ async function searchExaMCP(query, maxResults, signal) {
       url,
       ...(title ? { title } : {}),
       ...(highlights ? { snippet: highlights.slice(0, 300) } : {}),
-      // 鍙繚鐣欐棩鏈熷舰鎬侊紙ISO 鎴?YYYY-MM-DD锛夛紝杩囨护 "N/A" 绛夊崰浣嶇
+      // 只保留日期形态（ISO 或 YYYY-MM-DD），过滤 "N/A" 等占位符
       ...(published && /^\d{4}-\d{2}-\d{2}/.test(published) ? { publishedAt: published } : {}),
     });
   }
@@ -523,7 +523,7 @@ async function searchGithub(query, maxResults, signal) {
     sources: (data.items ?? []).map((item) => ({
       url: item.html_url,
       title: item.full_name ?? item.name,
-      snippet: `${item.description ?? ""}${item.stargazers_count ? ` 猸?{item.stargazers_count}` : ""}`.trim(),
+      snippet: `${item.description ?? ""}${item.stargazers_count ? ` ⭐${item.stargazers_count}` : ""}`.trim(),
     })),
     truncated: false,
   };
@@ -617,11 +617,11 @@ async function searchHackerNews(query, maxResults, signal) {
     sources: (data.hits ?? [])
       .filter((h) => h.title || h.story_title)
       .map((h) => ({
-        // 鏈夊閾剧敤澶栭摼锛岀函璁ㄨ甯栫敤 HN 璁ㄨ椤?
+        // 有外链用外链，纯讨论帖用 HN 讨论页
         url: h.url ?? `https://news.ycombinator.com/item?id=${h.objectID}`,
         title: h.title ?? h.story_title,
         ...((h.points !== undefined && h.points !== null) || (h.num_comments !== undefined && h.num_comments !== null)
-          ? { snippet: `HN discussion 路 ${h.points ?? 0} points 路 ${h.num_comments ?? 0} comments` }
+          ? { snippet: `HN discussion · ${h.points ?? 0} points · ${h.num_comments ?? 0} comments` }
           : {}),
       })),
     truncated: false,
@@ -644,7 +644,7 @@ async function searchStackOverflow(query, maxResults, signal) {
       url: it.link,
       title: it.title,
       ...(it.score !== undefined || it.answer_count !== undefined
-        ? { snippet: `${it.is_answered ? "鉁?answered" : "unanswered"} 路 score ${it.score ?? 0} 路 ${it.answer_count ?? 0} answers` }
+        ? { snippet: `${it.is_answered ? "✓ answered" : "unanswered"} · score ${it.score ?? 0} · ${it.answer_count ?? 0} answers` }
         : {}),
     })),
     truncated: false,
@@ -666,7 +666,7 @@ async function searchWikipedia(query, maxResults, signal, lang) {
     sources: (data.query?.search ?? []).map((s) => ({
       url: `https://${host}/wiki/${encodeURIComponent(String(s.title).replace(/ /g, "_"))}`,
       title: s.title,
-      // snippet 鍚?<span class="searchmatch"> 楂樹寒鏍囩锛屽墺鎺?
+      // snippet 含 <span class="searchmatch"> 高亮标签，剥掉
       ...(s.snippet ? { snippet: stripTags(s.snippet).slice(0, 200) } : {}),
     })),
     truncated: false,
@@ -691,7 +691,7 @@ async function searchNpm(query, maxResults, signal) {
         url: p.links?.npm ?? `https://www.npmjs.com/package/${p.name}`,
         title: p.name,
         ...((p.description || p.version)
-          ? { snippet: `v${p.version ?? "?"}${p.description ? ` 鈥?${String(p.description).slice(0, 160)}` : ""}` }
+          ? { snippet: `v${p.version ?? "?"}${p.description ? ` — ${String(p.description).slice(0, 160)}` : ""}` }
           : {}),
       })),
     truncated: false,
@@ -731,7 +731,7 @@ async function searchExa(query, maxResults, apiKey, timeRange, signal) {
     contents: { highlights: { highlightsPerUrl: 1 } },
     ...(maxResults !== undefined ? { numResults: maxResults } : {}),
   };
-  // Exa 鏃堕棿杩囨护锛歴tartPublishedDate锛圛SO 鏃ユ湡锛涙敮鎸佷换鎰忓ぉ鏁板拰缁濆鏃ユ湡锛?
+  // Exa 时间过滤：startPublishedDate（ISO 日期；支持任意天数和绝对日期）
   if (timeRange) {
     if (timeRange.after) body.startPublishedDate = timeRange.after;
     else if (timeRange.days !== undefined) body.startPublishedDate = isoDaysAgo(timeRange.days);
@@ -771,7 +771,7 @@ async function searchExa(query, maxResults, apiKey, timeRange, signal) {
   return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
 }
 
-// Tavily: 鏃?key 璧?keyless锛堝厤璐瑰尶鍚嶉搴︼級锛屾湁 key 璧拌处鍙锋。锛圔earer锛?
+// Tavily: 无 key 走 keyless（免费匿名额度），有 key 走账号档（Bearer）
 async function searchTavily(query, maxResults, apiKey, timeRange, signal) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 15000);
@@ -784,7 +784,7 @@ async function searchTavily(query, maxResults, apiKey, timeRange, signal) {
       max_results: Math.min(maxResults ?? 5, 20),
       search_depth: "basic",
     };
-    // Tavily 鏃堕棿杩囨护锛歵ime_range 鍙敮鎸佸浐瀹氭。锛岃嚜瀹氫箟澶╂暟鍙栨渶杩戜技妗ｄ綅
+    // Tavily 时间过滤：time_range 只支持固定档，自定义天数取最近似档位
     if (timeRange) {
       const tr = approximateTimeRange(timeRange.days ?? 7);
       if (tr) body.time_range = tr;
@@ -825,7 +825,7 @@ async function searchTavily(query, maxResults, apiKey, timeRange, signal) {
   return { sources: uniqueSources(sources, maxResults ?? 10), truncated: false };
 }
 
-// 鎶婁换鎰忓ぉ鏁拌浆鎴?Keenable 鐨勭浉瀵规椂闂存牸寮忥紙12h / Nd / Nmo / Ny锛?
+// 把任意天数转成 Keenable 的相对时间格式（12h / Nd / Nmo / Ny）
 function formatKeenableRelative(days) {
   if (days <= 0.5) return "12h";
   if (days < 1) return `${Math.round(days * 24)}h`;
@@ -834,7 +834,7 @@ function formatKeenableRelative(days) {
   return `${Math.round(days / 365)}y`;
 }
 
-// Keenable: 鏈?key 璧?REST API锛圶-API-Key锛夛紝鏃?key 璧?keyless MCP锛堝厤璐瑰尶鍚嶉搴︼級
+// Keenable: 有 key 走 REST API（X-API-Key），无 key 走 keyless MCP（免费匿名额度）
 function extractKeenableSources(text, maxResults) {
   const sources = [];
   const blocks = String(text).split(/\n(?=Title:)/);
@@ -848,7 +848,7 @@ function extractKeenableSources(text, maxResults) {
       url,
       ...(title ? { title } : {}),
       ...(snippets ? { snippet: snippets.slice(0, 300) } : {}),
-      // 涓?Exa MCP 涓€鑷达細鍙繚鐣欐棩鏈熷舰鎬侊紝杩囨护 "N/A" 绛夊崰浣嶇
+      // 与 Exa MCP 一致：只保留日期形态，过滤 "N/A" 等占位符
       ...(published && /^\d{4}-\d{2}-\d{2}/.test(published) ? { publishedAt: published } : {}),
     });
   }
@@ -863,7 +863,7 @@ async function searchKeenableREST(query, maxResults, apiKey, timeRange, signal)
   let response;
   try {
     const body = { query, mode: "realtime" };
-    // Keenable 鏃堕棿杩囨护锛歱ublished_after锛堢浉瀵?12h/7d/1mo/1y 鎴栫粷瀵?YYYY-MM-DD锛?
+    // Keenable 时间过滤：published_after（相对 12h/7d/1mo/1y 或绝对 YYYY-MM-DD）
     if (timeRange) {
       if (timeRange.after) body.published_after = timeRange.after;
       else if (timeRange.days !== undefined) body.published_after = formatKeenableRelative(timeRange.days);
@@ -908,7 +908,7 @@ async function searchKeenableMCP(query, maxResults, timeRange, signal) {
   let response;
   try {
     const arguments_ = { query };
-    // Keenable MCP 鏀寔 published_after锛堢浉瀵规垨缁濆鏃ユ湡锛?
+    // Keenable MCP 支持 published_after（相对或绝对日期）
     if (timeRange) {
       if (timeRange.after) arguments_.published_after = timeRange.after;
       else if (timeRange.days !== undefined) arguments_.published_after = formatKeenableRelative(timeRange.days);
@@ -935,7 +935,7 @@ async function searchKeenableMCP(query, maxResults, timeRange, signal) {
   const data = await response.json();
   if (data.error) throw new Error(`Keenable MCP error: ${data.error?.message ?? "unknown"}`);
   const content = data.result?.content ?? [];
-  // isError=true 鏃?content 閲屾槸閿欒鏂囨湰
+  // isError=true 时 content 里是错误文本
   const text = content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
   if (data.result?.isError) throw new Error(`Keenable MCP error: ${text.slice(0, 200)}`);
   return { sources: extractKeenableSources(text, maxResults ?? 10), truncated: false };
@@ -948,7 +948,7 @@ async function searchKeenable(query, maxResults, apiKey, timeRange, signal) {
 
 async function searchPerplexity(query, maxResults, apiKey, signal) {
   if (!apiKey) throw new Error("Perplexity search requires PERPLEXITY_API_KEY");
-  // 鍐呯疆 20s 瓒呮椂锛堜笌澶栭儴 signal 缁勫悎锛夛細璋冪敤鏂逛笉浼?signal 鏃朵篃涓嶄細姘镐箙鍗′綇
+  // 内置 20s 超时（与外部 signal 组合）：调用方不传 signal 时也不会永久卡住
   const response = await fetch("https://api.perplexity.ai/chat/completions", {
     method: "POST",
     redirect: "error",
@@ -984,7 +984,7 @@ async function searchPerplexity(query, maxResults, apiKey, signal) {
 
 async function searchDeepSeekOfficial(query, maxResults, apiKey, signal) {
   if (!apiKey) throw new Error("DeepSeek search requires DEEPSEEK_API_KEY");
-  // 鍐呯疆 20s 瓒呮椂锛堜笌澶栭儴 signal 缁勫悎锛夛細璋冪敤鏂逛笉浼?signal 鏃朵篃涓嶄細姘镐箙鍗′綇
+  // 内置 20s 超时（与外部 signal 组合）：调用方不传 signal 时也不会永久卡住
   const response = await fetch("https://api.deepseek.com/anthropic/v1/messages", {
     method: "POST",
     redirect: "error",
@@ -1131,13 +1131,13 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
           hasUpdate: cmp > 0,
           updateUrl: PLUGIN_NPM_URL,
           repoUrl: PLUGIN_REPO_URL,
-          // 鍙竴閿崌绾э細npm 鐪熷畨瑁呮椂 true锛涙湰鍦?link 寮€鍙戞ā寮?false锛堝崌绾ц git pull 婧愮爜锛?
+          // 可一键升级：npm 真安装时 true；本地 link 开发模式 false（升级请 git pull 源码）
           installable: mode !== null && !mode.isLink,
           installMode: mode?.isLink ? "link" : mode !== null ? "registry" : "unknown",
         },
       };
     },
-    // 涓€閿崌绾э細浠呭湪 npm 鐪熷畨瑁呮ā寮忎笅鎵ц pnpm 鍗囩骇锛沴ink 妯″紡鎷掔粷锛堥伩鍏嶇牬鍧忔湰鍦板紑鍙戦摼璺級
+    // 一键升级：仅在 npm 真安装模式下执行 pnpm 升级；link 模式拒绝（避免破坏本地开发链路）
     async updatePlugin() {
       const mode = detectInstallMode();
       if (mode === null) {
@@ -1177,7 +1177,7 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
       }
       const maxResults = Math.min(Math.max(Number(request.maxResults) || 5, 1), 10);
       const timeRange = parseTimeRange(request.timeRange);
-      // 鎸囧畾 engine锛氱洿娴嬭寮曟搸鏈韩锛堜笉璧板洖閫€閾撅級锛屾姤鍛婂畠鑷繁鐨勫彲鐢ㄦ€?
+      // 指定 engine：直测该引擎本身（不走回退链），报告它自己的可用性
       if (typeof request.engine === "string" && request.engine.length > 0) {
         if (typeof testEngine !== "function") {
           return { ok: false, code: "search-unavailable", message: "engine test is not wired" };
@@ -1207,11 +1207,11 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
         return {
           ok: true,
           value: {
-            // 瀹為檯浣跨敤鐨勫紩鎿庯細provider.search 鍦ㄦ垚鍔熸椂杩斿洖 provider 瀛楁
+            // 实际使用的引擎：provider.search 在成功时返回 provider 字段
             provider: result.provider ?? request.engine ?? request.provider ?? "bing",
             sources: result.sources ?? [],
             content: result.content ?? "",
-            // 缂撳瓨鍛戒腑鏍囪锛歱rovider.search 鎴愬姛璺緞鏍囪 _cache锛坔it=鍛戒腑缂撳瓨锛宮iss=鐪熷疄鎼滅储锛?
+            // 缓存命中标记：provider.search 成功路径标记 _cache（hit=命中缓存，miss=真实搜索）
             cache: result._cache === "hit" ? "hit" : "miss",
           },
         };
@@ -1257,7 +1257,7 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
       }
       return { ok: true, value: toView(descriptor) };
     },
-    // 鍑嵁涓績锛氭煡璇㈠悇寮曟搸 key 鐨勯厤缃姸鎬侊紙value 涓嶈繑鍥烇紝鍙繑鍥炴槸鍚﹀凡閰嶇疆锛?
+    // 凭据中心：查询各引擎 key 的配置状态（value 不返回，只返回是否已配置）
     async credentialsStatus() {
       const credentials = getCredentials();
       if (!credentials) return { ok: false, code: "credentials-unavailable", message: "credentials service is not available" };
@@ -1272,7 +1272,7 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
       }
       return { ok: true, value: { configured, available: true } };
     },
-    // 鍑嵁涓績锛氬啓鍏ヤ竴涓紩鎿?key锛坮ef 鐧藉悕鍗曢檺瀹氾級
+    // 凭据中心：写入一个引擎 key（ref 白名单限定）
     async credentialsSet(request) {
       const credentials = getCredentials();
       if (!credentials) return { ok: false, code: "credentials-unavailable", message: "credentials service is not available" };
@@ -1289,7 +1289,7 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
         return { ok: false, code: "credentials-write-failed", message: error instanceof Error ? error.message : String(error) };
       }
     },
-    // 鍑嵁涓績锛氬垹闄や竴涓紩鎿?key
+    // 凭据中心：删除一个引擎 key
     async credentialsUnset(request) {
       const credentials = getCredentials();
       if (!credentials) return { ok: false, code: "credentials-unavailable", message: "credentials service is not available" };
@@ -1409,7 +1409,7 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
 const name = "web-search-free";
 const inject = ["web"];
 
-// 寮曟搸 key 涓庡嚟鎹腑蹇?ref 鐨勬槧灏勶紙鐧藉悕鍗曪細鍙厑璁歌繖浜?ref 琚?UI 璇诲啓鍑嵁涓績锛?
+// 引擎 key 与凭据中心 ref 的映射（白名单：只允许这些 ref 被 UI 读写凭据中心）
 const KEY_REF_MAP = {
   exaApiKey: "EXA_API_KEY",
   tavilyApiKey: "TAVILY_API_KEY",
@@ -1420,9 +1420,9 @@ const KEY_REF_MAP = {
 
 const Config = z.object({
   provider: z.string().default("bing"),
-  cache: z.boolean().default(true), // 鍗?query 缁撴灉缂撳瓨寮€鍏筹紙闃查檺娴?鐪侀搴︼級
-  cacheTtl: z.number().default(5), // 缂撳瓨鏃堕暱锛堝垎閽燂級锛?-5 鍙厤缃紙浣跨敤澶勫啀 clamp锛?
-  keyStorage: z.string().default("credentials"), // key 瀛樺偍浣嶇疆锛歝redentials锛堝嚟鎹腑蹇冿級| settings锛堣缃〉锛?
+  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"),
@@ -1439,16 +1439,16 @@ const Config = z.object({
 function apply(ctx, config) {
   let current = () => config ?? {};
   const logger = ctx.logger;
-  // credentials 鏈嶅姟鍙兘鏅氫簬鏈彃浠舵寕杞斤紙璺?bundle 椤哄簭锛夛紝杩愯鏈熷姩鎬佽幏鍙栬€屼笉鏄?apply 鏃剁紦瀛?
+  // credentials 服务可能晚于本插件挂载（跨 bundle 顺序），运行期动态获取而不是 apply 时缓存
   const getCredentials = () => ctx.get("credentials");
 
-  // 绯荤粺鎻愮ず璇嶅姩鎬佸埛鏂帮細璁剧疆鍙樻洿鏃堕噸鏂扮敓鎴愶紝閬垮厤鏄剧ず鏃у紩鎿?
+  // 系统提示词动态刷新：设置变更时重新生成，避免显示旧引擎
   let refreshPrompt = null;
 
-  // 鍗?query 缁撴灉缂撳瓨锛坧rovider.search 鍐呴棴鍖呮寔鏈夛級锛歀RU 50 鏉?/ TTL 鍙厤缃?
+  // 单 query 结果缓存（provider.search 内闭包持有）：LRU 50 条 / TTL 可配置
   const searchCache = new Map(); // key -> { value, expiresAt }
 
-  // key 浼樺厛绾э細credentials锛?credentials.yaml 鍑嵁涓績锛屽畼鏂规帹鑽愶級> settings 鐨?free-search.<x>ApiKey锛堥仐鐣欏吋瀹癸級> 鐜鍙橀噺
+  // key 优先级：credentials（.credentials.yaml 凭据中心，官方推荐）> settings 的 free-search.<x>ApiKey（遗留兼容）> 环境变量
   const resolveApiKey = async (envName, settingsKey) => {
     const credentials = getCredentials();
     if (credentials) {
@@ -1462,32 +1462,32 @@ function apply(ctx, config) {
     return process.env[envName] ?? "";
   };
 
-  // 鎬绘帶 provider锛氭寜 settings 鐨?provider 瀛楁璺敱鍒颁换鎰忓紩鎿庛€?
-  // 浠讳綍寮曟搸澶辫触锛堢己 key / 401 / 闄愭祦 / 缃戠粶锛夐兘浼氳嚜鍔ㄨ疆娴佸皾璇曚笅涓€涓紩鎿庯紝
-  // 鐩村埌鎴愬姛鎴栧叏閮ㄥけ璐ャ€傚苟鍦ㄧ粨鏋滈噷闄勫甫鍥為€€鎻愮ず锛岄伩鍏?agent 鎼滅储鐩存帴澶辫触銆?
+  // 总控 provider：按 settings 的 provider 字段路由到任意引擎。
+  // 任何引擎失败（缺 key / 401 / 限流 / 网络）都会自动轮流尝试下一个引擎，
+  // 直到成功或全部失败。并在结果里附带回退提示，避免 agent 搜索直接失败。
   const provider = {
     id: "ddg",
     available() {
       return true;
     },
-    // 鍗?query 缁撴灉缂撳瓨锛歬ey=query+maxResults+timeRangeLabel+preferred锛孧ap 澶╃劧 LRU
+    // 单 query 结果缓存：key=query+maxResults+timeRangeLabel+preferred，Map 天然 LRU
     async search(request, signal) {
-      // 鍏叡鍜藉枆鏍￠獙锛歸eb_search / advanced_search / raw-search 涓夋潯璺緞閮界粡杩囪繖閲?
+      // 公共咽喉校验：web_search / advanced_search / raw-search 三条路径都经过这里
       if (request === null || typeof request !== "object" || typeof request.query !== "string" || request.query.trim().length === 0) {
         throw new Error("query is required");
       }
       const cfg = current();
-      // 棣栭€夊紩鎿庯細free_search 宸ュ叿鏄惧紡鎸囧畾锛坮equest.engine锛変紭鍏堜簬璁剧疆锛坈fg.provider锛?
+      // 首选引擎：free_search 工具显式指定（request.engine）优先于设置（cfg.provider）
       const preferred =
         typeof request.engine === "string" && ALL_ENGINES.includes(request.engine)
           ? request.engine
           : cfg.provider ?? "bing";
-      // time_range 杩囨护锛堜粎 advanced_search 宸ュ叿閫忎紶锛涙爣鍑?web_search 鏃犳鍙傛暟锛?
-      // 淇濈暀鍘熷瀛楃涓茬敤浜?Note 灞曠ず锛況aw-search 妗ュ彲鑳藉凡鎶?timeRange 瑙ｆ瀽鎴愬璞?
+      // time_range 过滤（仅 advanced_search 工具透传；标准 web_search 无此参数）
+      // 保留原始字符串用于 Note 展示；raw-search 桥可能已把 timeRange 解析成对象
       const timeRange = parseTimeRange(request.timeRange);
       const timeRangeLabel = typeof request.timeRange === "string" ? request.timeRange : String(timeRange?.days ?? timeRange?.after ?? "");
 
-      // 缂撳瓨 TTL锛堝垎閽燂紝0-5 鍙厤缃級锛沜ache=false 鎴?ttl<=0 鏃跺畬鍏ㄧ鐢?
+      // 缓存 TTL（分钟，0-5 可配置）；cache=false 或 ttl<=0 时完全禁用
       const cacheTtlMs = (Math.min(Math.max(Number(cfg.cacheTtl) ?? 5, 0), 5)) * 60 * 1000;
       const cacheEnabled = cfg.cache !== false && cacheTtlMs > 0;
       const cacheKey = cacheEnabled
@@ -1499,31 +1499,31 @@ function apply(ctx, config) {
           if (signal?.aborted) throw new Error("search aborted");
           searchCache.delete(cacheKey);
           searchCache.set(cacheKey, hit);
-          // 娴呮嫹璐?+ 绉佹湁鏍囪锛歴ources 鏁扮粍涔熷鍒朵竴灞傦紝褰诲簳闅旂缂撳瓨瀵硅薄锛堣皟鐢ㄦ柟 push/鏀瑰厓绱犱笉褰卞搷缂撳瓨锛?
+          // 浅拷贝 + 私有标记：sources 数组也复制一层，彻底隔离缓存对象（调用方 push/改元素不影响缓存）
           return { ...hit.value, sources: hit.value.sources?.slice(), _cache: "hit" };
         }
         if (hit) searchCache.delete(cacheKey);
       }
 
-      // 缁熶竴寮曟搸閾撅細棣栭€変紭鍏堬紝鐒跺悗鍏朵粬浠樿垂寮曟搸锛堟湁 key 鐨勪紭鍏堝皾璇曪級锛屾渶鍚庡厤璐瑰紩鎿?
+      // 统一引擎链：首选优先，然后其他付费引擎（有 key 的优先尝试），最后免费引擎
       const paidEngines = ["exa", "tavily", "keenable", "perplexity", "deepseek-official"];
       const freeEngines = ["bing", "anysearch", "ddg", "ddg-lite", "searxng"];
-      // 鏀寔 time_range 杩囨护鐨勫紩鎿庯細tavily / exa / keenable / searxng / ddg / ddg-lite
+      // 支持 time_range 过滤的引擎：tavily / exa / keenable / searxng / ddg / ddg-lite
       const timeEngines = ["tavily", "exa", "keenable", "searxng", "ddg", "ddg-lite"];
       let chain;
-      // 棣栭€夊紩鎿庤璺宠繃鐨勫師鍥狅紙鐢ㄤ簬鐢熸垚鍑嗙‘鐨?Note锛岄伩鍏嶈瀵?agent/鐢ㄦ埛锛夛細
-      //  - "time-filter"锛氬甫 timeRange 涓旈閫夊紩鎿庝笉鏀寔鏃堕棿杩囨护锛堟牴鏈病灏濊瘯锛?
-      //  - "failed"锛氶閫夊紩鎿庣‘瀹炶灏濊瘯浣嗗け璐ワ紙缂?key / 401 / 闄愭祦 / 0 缁撴灉 / 缃戠粶锛?
-      //  - null锛氶閫夊紩鎿庢垚鍔熸垨鏃犲洖閫€
+      // 首选引擎被跳过的原因（用于生成准确的 Note，避免误导 agent/用户）：
+      //  - "time-filter"：带 timeRange 且首选引擎不支持时间过滤（根本没尝试）
+      //  - "failed"：首选引擎确实被尝试但失败（缺 key / 401 / 限流 / 0 结果 / 网络）
+      //  - null：首选引擎成功或无回退
       let preferredSkippedReason = null;
       if (timeRange) {
-        // 鏈夋椂闂磋繃婊ら渶姹傛椂锛屾妸鏀寔杩囨护鐨勫紩鎿庢帓鍓嶉潰锛堥閫夊紩鎿庤嫢鏀寔浠嶄紭鍏堬級
+        // 有时间过滤需求时，把支持过滤的引擎排前面（首选引擎若支持仍优先）
         const preferredFirst = [preferred].filter((e) => timeEngines.includes(e));
         const otherTime = timeEngines.filter((e) => e !== preferred);
         const noTime = [...paidEngines, ...freeEngines].filter((e) => !timeEngines.includes(e) && e !== preferred);
         chain = [...preferredFirst, ...otherTime, ...noTime];
         if (!timeEngines.includes(preferred)) {
-          // 棣栭€夊紩鎿庝笉鏀寔鏃堕棿杩囨护 鈫?瀹冧笉鍦ㄩ摼閲岋紝涓嶄細琚皾璇曪紙杩欎笉绛変簬澶辫触锛?
+          // 首选引擎不支持时间过滤 → 它不在链里，不会被尝试（这不等于失败）
           preferredSkippedReason = "time-filter";
         }
       } else {
@@ -1534,9 +1534,9 @@ function apply(ctx, config) {
 
       let lastError = null;
       let usedEngine = null;
-      // 棣栭€夊紩鎿庤嫢琚皾璇曞悗澶辫触锛岃褰曞け璐ヨ鎯咃紙鐢ㄤ簬 Note锛?
+      // 首选引擎若被尝试后失败，记录失败详情（用于 Note）
       let preferredFailure = null;
-      // 鎬昏秴鏃堕绠楋細涓茶鍥為€€鏃堕檺鍒舵暣鏉″紩鎿庨摼鐨勬€绘椂闀匡紝闃叉鍚勫紩鎿庤秴鏃剁疮鍔犺揪鍒嗛挓绾?
+      // 总超时预算：串行回退时限制整条引擎链的总时长，防止各引擎超时累加达分钟级
       const BUDGET_MS = 30000;
       const deadline = Date.now() + BUDGET_MS;
       for (const engine of chain) {
@@ -1544,7 +1544,7 @@ function apply(ctx, config) {
         if (remaining <= 0) {
           throw new Error(`search timed out after ${BUDGET_MS / 1000}s`);
         }
-        // 缁勫悎澶栭儴鍙栨秷 signal + 鍓╀綑棰勭畻瓒呮椂锛氬畼鏂?web_search 鍙栨秷銆佸紩鎿庤秴鏃躲€佹€婚绠楅兘鑳借Е鍙?
+        // 组合外部取消 signal + 剩余预算超时：官方 web_search 取消、引擎超时、总预算都能触发
         const effSignal = AbortSignal.any([...(signal !== undefined ? [signal] : []), AbortSignal.timeout(remaining)]);
         try {
           let result;
@@ -1559,7 +1559,7 @@ function apply(ctx, config) {
           } else if (engine === "anysearch") {
             result = await searchAnysearch(request.query, request.maxResults, effSignal);
           } else if (engine === "exa") {
-            // exa锛氭湁 key 璧?REST锛屾棤 key 璧?keyless MCP锛堝厤璐癸級
+            // exa：有 key 走 REST，无 key 走 keyless MCP（免费）
             const key = await resolveApiKey("EXA_API_KEY", "exaApiKey");
             if (key) {
               result = await searchExa(request.query, request.maxResults, key, timeRange, effSignal);
@@ -1567,11 +1567,11 @@ function apply(ctx, config) {
               result = await searchExaMCP(request.query, request.maxResults, effSignal);
             }
           } else if (engine === "tavily") {
-            // tavily锛氭湁 key 璧拌处鍙锋。锛屾棤 key 璧?keyless锛堝厤璐瑰尶鍚嶉搴︼級
+            // tavily：有 key 走账号档，无 key 走 keyless（免费匿名额度）
             const key = await resolveApiKey("TAVILY_API_KEY", "tavilyApiKey");
             result = await searchTavily(request.query, request.maxResults, key, timeRange, effSignal);
           } else if (engine === "keenable") {
-            // keenable锛氭湁 key 璧?REST锛屾棤 key 璧?keyless MCP锛堝厤璐癸級
+            // keenable：有 key 走 REST，无 key 走 keyless MCP（免费）
             const key = await resolveApiKey("KEENABLE_API_KEY", "keenableApiKey");
             result = await searchKeenable(request.query, request.maxResults, key, timeRange, effSignal);
           } else if (engine === "perplexity") {
@@ -1580,7 +1580,7 @@ function apply(ctx, config) {
               lastError = new Error("Perplexity requires PERPLEXITY_API_KEY");
               if (engine === preferred) preferredFailure = "PERPLEXITY_API_KEY is not configured";
               logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
-              continue; // 鏃?key 璺宠繃
+              continue; // 无 key 跳过
             }
             result = await searchPerplexity(request.query, request.maxResults, key, effSignal);
           } else if (engine === "deepseek-official") {
@@ -1589,7 +1589,7 @@ function apply(ctx, config) {
               lastError = new Error("DeepSeek requires DEEPSEEK_API_KEY");
               if (engine === preferred) preferredFailure = "DEEPSEEK_API_KEY is not configured";
               logger.warn(`free-search: engine "${engine}" skipped (no key), trying next engine`);
-              continue; // 鏃?key 璺宠繃
+              continue; // 无 key 跳过
             }
             result = await searchDeepSeekOfficial(request.query, request.maxResults, key, effSignal);
           } else {
@@ -1598,11 +1598,11 @@ function apply(ctx, config) {
 
           if (result.sources.length > 0) {
             usedEngine = engine;
-            // 缁熶竴娓呮礂 snippet锛氬幓鐧诲綍/浠樿垂澧?璁㈤槄鍣煶锛屾姌鍙犵┖鐧斤紙鏈夊€肩殑鎵嶅鐞嗭紝淇濇寔 lossless JSON锛?
+            // 统一清洗 snippet：去登录/付费墙/订阅噪音，折叠空白（有值的才处理，保持 lossless JSON）
             result.sources = result.sources.map((s) =>
               s.snippet ? { ...s, snippet: cleanSnippet(s.snippet) } : s
             );
-            // 鐢ㄤ簡闈為閫夊紩鎿庢椂锛屽湪缁撴灉閲岄檮涓婂噯纭彁绀猴紙鍖哄垎"涓嶆敮鎸佹椂闂磋繃婊よ璺宠繃"涓?鐪熷疄澶辫触"锛?
+            // 用了非首选引擎时，在结果里附上准确提示（区分"不支持时间过滤被跳过"与"真实失败"）
             if (engine !== preferred) {
               if (preferredSkippedReason === "time-filter") {
                 result.content = `Note: ${preferred} does not support time filtering (timeRange=${timeRangeLabel}), using ${engine}.`;
@@ -1612,10 +1612,10 @@ function apply(ctx, config) {
                 result.content = `Note: ${preferred} unavailable or failed, using ${engine}.`;
               }
             }
-            // 鍐欏叆缂撳瓨锛堝彧缂撳瓨鎴愬姛缁撴灉锛屽け璐ヨ蛋 throw 澶╃劧涓嶇紦瀛橈級
+            // 写入缓存（只缓存成功结果，失败走 throw 天然不缓存）
             const cached = { ...result, provider: engine, engine: engine };
             if (cacheKey !== null) {
-              // fallback 鏉＄洰锛堝疄闄呭紩鎿庘墵棣栭€夛級鐢ㄩ厤缃?TTL 鐨?1/5锛岄閫夋垚鍔熶繚鎸佸畬鏁?TTL
+              // fallback 条目（实际引擎≠首选）用配置 TTL 的 1/5，首选成功保持完整 TTL
               const entryTtlMs = engine !== preferred ? Math.max(cacheTtlMs / 5, 1000) : cacheTtlMs;
               searchCache.set(cacheKey, {
                 value: cached,
@@ -1648,7 +1648,7 @@ function apply(ctx, config) {
         current = source;
       },
       onChange: () => {
-        // settings 鍙樻洿鏃跺埛鏂扮郴缁熸彁绀鸿瘝锛堟樉绀烘渶鏂板紩鎿庯級
+        // settings 变更时刷新系统提示词（显示最新引擎）
         if (typeof refreshPrompt === "function") refreshPrompt();
       },
     });
@@ -1670,16 +1670,16 @@ function apply(ctx, config) {
 
   ctx.web.registerSearchProvider(provider);
 
-  // 杩愯鏃跺厹搴曪細DSH 0.1.1+ 涓?profile patch 鐨?config 浼氭暣浣撹鐩?bundle patch 鐨?config锛?
-  // 鐢ㄦ埛鐨?`- id: web` patch锛堝鍙 fetchProvider锛変細闈欓粯鎶规帀 searchProvider锛屽鑷村洖閫€ DeepSeek 瀹樻柟鎼滅储銆?
-  // 杩欓噷鍦?provider 娉ㄥ唽鍚庢鏌ワ細鏈寚鍚戜换浣?provider锛坲ndefined锛夋椂鑷姩鎺ョ涓烘湰鎻掍欢锛?
-  // 鐢ㄦ埛鏄惧紡閰嶇疆浜嗗叾浠?provider 鍒欎笉鍔ㄣ€?
+  // 运行时兜底：DSH 0.1.1+ 中 profile patch 的 config 会整体覆盖 bundle patch 的 config，
+  // 用户的 `- id: web` patch（如只设 fetchProvider）会静默抹掉 searchProvider，导致回退 DeepSeek 官方搜索。
+  // 这里在 provider 注册后检查：未指向任何 provider（undefined）时自动接管为本插件；
+  // 用户显式配置了其他 provider 则不动。
   if (!ctx.web.searchProviderId) {
     ctx.web.searchProviderId = provider.id;
     logger.info(`free-search: web.searchProvider was unset (patch override or missing config), taking over as "${provider.id}"`);
   }
 
-  // 娴嬭瘯宸ュ叿锛氳 agent 閫愪釜娴嬭瘯鎵€鏈夋悳绱㈠紩鎿庯紝鎶ュ憡鍙敤鎬?
+  // 测试工具：让 agent 逐个测试所有搜索引擎，报告可用性
   const runEngineTest = async (engine, query, timeRange) => {
     const cfg = current();
     const q = query || "DeepSeek Harness";
@@ -1725,9 +1725,9 @@ function apply(ctx, config) {
     };
     try {
       const result = await attempt();
-      // 浠樿垂寮曟搸鏃?key锛氱洿鎺ラ€忎紶澶辫触缁撴灉
+      // 付费引擎无 key：直接透传失败结果
       if (result.ok === false) return result;
-      // 鍏嶈垂寮曟搸鍋跺彂鍙嶇埇/绌虹粨鏋滄椂閲嶈瘯涓€娆?
+      // 免费引擎偶发反爬/空结果时重试一次
       if (result.sources && result.sources.length === 0) {
         await new Promise((resolve) => setTimeout(resolve, 1500));
         return await attempt();
@@ -1815,7 +1815,7 @@ function apply(ctx, config) {
             return { results };
           },
           finalizeContent(exec, result) {
-            // 鎶?render 杈撳嚭鍖呰鎴愬悎娉曠殑 text block锛坈ontent 蹇呴』鏄?block 鏁扮粍锛?
+            // 把 render 输出包装成合法的 text block（content 必须是 block 数组）
             const text = result.content;
             if (typeof text === "string" && text.length > 0) {
               return [{ type: "text", text }];
@@ -1830,7 +1830,7 @@ function apply(ctx, config) {
     }, "free-search: test engines tool");
   });
 
-  // 骞冲彴鎼滅储宸ュ叿锛欸itHub / V2EX / Bilibili / Reddit锛堝叕寮€ API锛岄浂渚濊禆锛?
+  // 平台搜索工具：GitHub / V2EX / Bilibili / Reddit（公开 API，零依赖）
   ctx.inject(["tools"], (sctx) => {
     sctx.effect(() => {
       const dispose = sctx.tools.register(
@@ -1882,7 +1882,7 @@ function apply(ctx, config) {
             if (!PLATFORMS[platform]) {
               throw new Error(`unknown platform "${platform}" - use one of: ${Object.keys(PLATFORMS).join(", ")}`);
             }
-            // 骞冲彴寮€鍏筹細settings 閲岀鐢ㄦ煇骞冲彴鏃讹紝宸ュ叿鏄庣‘鍛婄煡
+            // 平台开关：settings 里禁用某平台时，工具明确告知
             const enabled = current().platforms ?? ["github", "v2ex", "bilibili", "reddit", "hn", "stackoverflow", "wikipedia", "npm"];
             if (!enabled.includes(platform)) {
               throw new Error(
@@ -1891,7 +1891,7 @@ function apply(ctx, config) {
             }
             const limit = Math.min(args.maxResults ?? 5, 10);
             const result = await searchPlatform(platform, args.query, limit, undefined, current().lang);
-            // lossless JSON 涓嶅厑璁?undefined 瀛楁锛氬墧闄ょ己澶卞瓧娈?
+            // lossless JSON 不允许 undefined 字段：剔除缺失字段
             const sources = (result.sources ?? []).map((s) => {
               const source = {};
               if (s.url !== undefined && s.url !== null && s.url !== "") source.url = s.url;
@@ -1914,8 +1914,8 @@ function apply(ctx, config) {
     }, "free-search: platform search tool");
   });
 
-  // 楂樼骇鎼滅储宸ュ叿锛氭敮鎸佹椂闂磋繃婊わ紙time_range锛夊拰鎸囧畾寮曟搸锛坋ngine锛夈€?
-  // 璧颁笌 web_search 鐩稿悓鐨勭粺涓€鍥為€€閾撅紝浣嗗厑璁?agent 鏄惧紡璇锋眰"鏈€杩?N 澶?鐨勭粨鏋溿€?
+  // 高级搜索工具：支持时间过滤（time_range）和指定引擎（engine）。
+  // 走与 web_search 相同的统一回退链，但允许 agent 显式请求"最近 N 天"的结果。
   ctx.inject(["tools"], (sctx) => {
     sctx.effect(() => {
       const dispose = sctx.tools.register(
@@ -1975,10 +1975,10 @@ function apply(ctx, config) {
               maxResults: Math.min(args.maxResults ?? 5, 10),
             };
             if (parseTimeRange(args.timeRange) !== undefined) request.timeRange = args.timeRange;
-            // engine 鎸囧畾鏃讹細浠呭綋璇ュ紩鎿庡彲鐢ㄦ墠浼樺厛锛堜粛璧板洖閫€閾撅紝澶辫触鑷姩鎹㈠紩鎿庯級
+            // engine 指定时：仅当该引擎可用才优先（仍走回退链，失败自动换引擎）
             if (args.engine && ALL_ENGINES.includes(args.engine)) request.engine = args.engine;
             const result = await provider.search(request);
-            // lossless JSON 涓嶅厑璁?undefined 瀛楁锛氭寜瀛樺湪鐨勫€兼瀯閫犲璞★紝缂哄瓧娈电洿鎺ョ渷鐣?
+            // lossless JSON 不允许 undefined 字段：按存在的值构造对象，缺字段直接省略
             return {
               provider: result.provider ?? result._provider ?? "bing",
               content: typeof result.content === "string" ? result.content : "",
@@ -2007,7 +2007,7 @@ function apply(ctx, config) {
     }, "free-search: advanced search tool");
   });
 
-  // 璁?agent 鐭ラ亾鍙敤鎼滅储寮曟搸锛堝姩鎬佺敓鎴愶紝闅?key/璁剧疆鍙樺寲锛?
+  // 让 agent 知道可用搜索引擎（动态生成，随 key/设置变化）
   ctx.inject(["systemPrompt"], (sctx) => {
     let disposeSection = null;
     refreshPrompt = () => {
@@ -2045,7 +2045,7 @@ function apply(ctx, config) {
           "",
           "For platform-specific searches (GitHub repos, V2EX threads, Bilibili videos, Reddit posts, Hacker News discussions, Stack Overflow questions, Wikipedia articles, npm packages), use the platform_search tool with platform: github|v2ex|bilibili|reddit|hn|stackoverflow|wikipedia|npm.",
           "",
-          "The user can switch the search engine themselves by typing /free-search-engine in the chat 鈥?it opens a picker to choose an engine, just like the settings page. This changes the preferred engine; search still falls back to other engines automatically if it fails. You should not switch engines on your own; let the user decide.",
+          "The user can switch the search engine themselves by typing /free-search-engine in the chat — it opens a picker to choose an engine, just like the settings page. This changes the preferred engine; search still falls back to other engines automatically if it fails. You should not switch engines on your own; let the user decide.",
         ].join("\n"),
       });
     };

package/package.json

@@ -1,67 +1,67 @@
-{
-    "name":  "dsh-free-search",
-    "version": "0.4.20",
-    "description":  "Free web search for DeepSeek Harness: 10 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable keyless) + time filtering + platform search + web_fetch, with web settings UI.",
-    "type":  "module",
-    "main":  "lib/index.js",
-    "exports":  {
-                    ".":  "./lib/index.js",
-                    "./client":  "./lib/client.js",
-                    "./package.json":  "./package.json"
-                },
-    "files":  [
-                  "lib/index.js",
-                  "lib/client.js",
-                  "cordis.patch.yml"
-              ],
-    "keywords":  [
-                     "deepseek-harness",
-                     "dsh",
-                     "dsh-plugin",
-                     "web-search",
-                     "duckduckgo",
-                     "bing",
-                     "tavily",
-                     "exa",
-                     "keenable",
-                     "perplexity",
-                     "search",
-                     "free"
-                 ],
-    "license":  "MIT",
-    "publishConfig":  {
-                          "access":  "public"
-                      },
-    "repository":  {
-                       "type":  "git",
-                       "url":  "https://github.com/DDDMUC/dsh-free-search.git"
-                   },
-    "engines":  {
-                    "node":  "\u003e=20"
-                },
-    "dependencies":  {
-                         "@deepseek-ai/schemastery":  "^3.18.1"
-                     },
-    "peerDependencies":  {
-                             "@deepseek-ai/dsh-settings":  "\u003e=0.1.0-rc.6",
-                             "@deepseek-ai/dsh-tools":  "\u003e=0.1.0-rc.6"
-                         },
-    "devDependencies":  {
-                            "@deepseek-ai/dsh-settings":  "0.1.0-rc.7",
-                            "@deepseek-ai/dsh-tools":  "0.1.0-rc.7"
-                        },
-    "dsh":  {
-                "bundle":  {
-                               "patch":  "cordis.patch.yml"
-                           },
-                "client":  {
-                               "inject":  [
-                                              "@deepseek-ai/dsh-client-runtime"
-                                          ],
-                               "platform":  "web"
-                           },
-                "engines":  {
-                                "dsh":  "\u003e=0.1.1-rc.1"
-                            }
-            }
-}
+{
+  "name": "dsh-free-search",
+  "version": "0.4.22",
+  "description": "Free web search for DeepSeek Harness: 10 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable keyless) + time filtering + platform search + web_fetch, with web settings UI.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml"
+  ],
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "web-search",
+    "duckduckgo",
+    "bing",
+    "tavily",
+    "exa",
+    "keenable",
+    "perplexity",
+    "search",
+    "free"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/DDDMUC/dsh-free-search.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-settings": ">=0.1.0-rc.6",
+    "@deepseek-ai/dsh-tools": ">=0.1.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-settings": "0.1.0-rc.7",
+    "@deepseek-ai/dsh-tools": "0.1.0-rc.7"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ],
+      "platform": "web"
+    },
+    "engines": {
+      "dsh": ">=0.1.1-rc.1"
+    }
+  }
+}