dsh-free-search 0.9.6 → 0.9.7

package/README.md

@@ -30,7 +30,8 @@ dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`
 
 - **零成本** —— 多个免费引擎，无需 key、无需注册
 - **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、AnySearch、Exa、Tavily、Keenable、Firecrawl、Parallel、Perplexity、SerpBase、Serply、DeepSeek 官方、DeepSeek 原生搜索 API、You.com、百度千帆、Kimi、阿里云百炼、火山联网搜索（豆包搜索）、知乎全网/站内（`zhihu_global`/`zhihu_site`，经知乎开放平台 MCP）、OpenAI / Gemini / Claude 模型内置搜索
-- **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换；入口在左侧「插件」页的组件行配置（`plugins.row.config`，DSH 0.1.7-rc.1+）
+- **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）+ 中英文切换；入口在左侧「插件」页的组件行配置（`plugins.row.config`，DSH 0.1.7-rc.1+）。远程访问（VPS / 反向代理 / 自定义域名）下也能用：桥接接口沿用宿主的 Host 围栏，`--trusted-host` 与 `--public-url` 声明的地址会放行（#84）
+- **右侧浮动目录** —— 卡片右侧的页面留白里浮出「引擎 / 回退 / 语言池 / 搜索行为 / 抓取 / 性能」六个快捷跳转，滚动自动高亮当前项、点击平滑跳转；不占用正文宽度（正文布局与 0.9.6 一致），右侧留白不足时自动隐藏
 - **弹出式切换命令** —— 聊天框输入 `/free-search-engine`，弹出引擎选择窗口，点选即切换（等效设置页 + 保存）
 - **引擎测试** —— `free_search_test` 工具让 agent 一键测试所有引擎；设置页也有"测试引擎"按钮（直测当前引擎，不走回退链，付费引擎无 key 会明确报错）
 - **全局引擎开关与回退优先级** —— 设置页可勾选/取消引擎（取消后全局生效：普通搜索 / Auto / `advanced_search` / `multi_search` / 引擎测试都不再用它），并可用 ↑↓ 调整全局回退顺序（一键恢复默认）
@@ -459,7 +460,7 @@ Search engine test:
 
 #### 离线自检断言（tools/）
 
-仓库自带 **17 个**零依赖断言脚本（合计 **507 项**），**不需要 API key、不联网、不需要测试框架**，Node ≥ 20 即可跑：
+仓库自带 **18 个**零依赖断言脚本（合计 **520 项**），**不需要 API key、不联网、不需要测试框架**，Node ≥ 20 即可跑：
 
 | 脚本 | 覆盖 | 运行（项数） |
 |---|---|---|
@@ -479,7 +480,8 @@ Search engine test:
 | `assert-killtree-win32.mjs` | Windows 子进程树终止（#74）：不再依赖 `taskkill` | `node tools/assert-killtree-win32.mjs`（8） |
 | `assert-killtree-portable.mjs` | 跨平台 `killTree` 便携版契约 | `node tools/assert-killtree-portable.mjs`（5） |
 | `assert-parallel-mcp.mjs` | Parallel MCP 引擎：25 s 超时/调用方取消覆盖**响应体读取**、共享 SSE 解析器（通知/多行帧）、6 类错误路径、REST 精确时间过滤 | `node tools/assert-parallel-mcp.mjs`（15） |
-| `assert-provider-takeover.mjs` | provider 接管：旧属性 API 与 rc.2 的 `config.*` ref 两套兼容、`settings.mutate(web)` 单批写入、显式指定的 provider 不被抢占、`fetchProviderTakeover: false` 时保留显式 `http`、apply 重入/重复注册不再中断、重复日志去重 | `node tools/assert-provider-takeover.mjs`（12） |
+| `assert-bridge-access.mjs` | 桥接 Host 围栏（#84）：loopback 放行、remote peer 打 loopback Host 拒绝、`--trusted-host`（无端口匹配任意端口 / 带端口精确匹配）、`--public-url`、绑定地址、跨站与异源拒绝 | `node tools/assert-bridge-access.mjs`（11） |
+| `assert-provider-takeover.mjs` | provider 接管：旧属性 API 与 rc.2 的 `config.*` ref 两套兼容、`settings.mutate(web)` 单批写入、显式指定的 provider 不被抢占、`fetchProviderTakeover: false` 时保留显式 `http`、describe 噪声不误报、嵌套 config 变化与 web 重建分别成行、apply 重入/重复注册不再中断、重复日志去重 | `node tools/assert-provider-takeover.mjs`（14） |
 
 任何一个失败会以非 0 退出码结束并列出失败项；把某个旧版本文件路径作为参数传进去，可以看到修复前必红（用来证明断言不是空转）。改动发布相关逻辑后建议先跑一遍再发版。
 
@@ -529,7 +531,8 @@ This plugin provides multiple free search engines with automatic fallback, compl
 
 - **Zero Cost** — Multiple free engines with no API key or registration required
 - **Multi-Engine Support** — DuckDuckGo (HTML / Lite), Bing, AnySearch AI, SearXNG (meta-search with custom instances), Exa, Tavily, Keenable, Firecrawl, Parallel, Perplexity, SerpBase, Serply, DeepSeek Official, You.com, Baidu Qianfan, Kimi, Aliyun Bailian, Volcano Doubao, Zhihu web-wide/site search (`zhihu_global`/`zhihu_site`, via the Zhihu open-platform MCP), and the model-based OpenAI / Gemini / Claude searches
-- **Web Settings UI** — Engine switching, API key configuration (keys masked as "configured" in the UI), and a Chinese/English toggle; the entry is the component-row config (`plugins.row.config`) on the sidebar Plugins page (DSH 0.1.7-rc.1+)
+- **Web Settings UI** — Engine switching, API key configuration (keys masked as "configured" in the UI), and a Chinese/English toggle; the entry is the component-row config (`plugins.row.config`) on the sidebar Plugins page (DSH 0.1.7-rc.1+). Remote access (VPS, reverse proxy, custom domain) works too: the bridge reuses the host's own Host fence, so addresses declared with `--trusted-host` or `--public-url` are accepted (#84)
+- **Right-hand section rail** — A floating list (Engines / Fallback / Language pools / Search behaviour / Fetch / Performance) sits in the page margin to the right of the card: it highlights the section you are in while scrolling and jumps smoothly on click. It is rendered in a portal and never narrows the card, so the body layout is unchanged; it hides itself when the margin is too tight.
 - **Popup Switch Command** — Type `/free-search-engine` in the chat: a picker opens with all engines; click one to switch (equivalent to the settings page + save)
 - **Engine Testing** — `free_search_test` for the agent to check all engines in one call; the settings UI also has a "Test engine" button that tests the selected engine directly (no fallback chain; paid engines without a key report an explicit error)
 - **Global engine enable/disable & fallback priority** — uncheck engines you never want (applies everywhere: web_search fallback, Auto routing, advanced_search, multi_search, engine tests) and reorder the global fallback chain with ↑↓ (one-click reset)
@@ -959,7 +962,7 @@ Restart `dsh web` after switching to apply changes.
 
 #### Offline self-check assertions (`tools/`)
 
-**Seventeen** zero-dependency assertion scripts ship with the repo (**507 assertions** total): **no API keys, no network, no test framework**, Node ≥ 20:
+**Eighteen** zero-dependency assertion scripts ship with the repo (**520 assertions** total): **no API keys, no network, no test framework**, Node ≥ 20:
 
 | Script | Covers | Run (count) |
 |---|---|---|
@@ -979,7 +982,8 @@ Restart `dsh web` after switching to apply changes.
 | `assert-killtree-win32.mjs` | Windows process-tree termination (#74): no longer relies on `taskkill` | `node tools/assert-killtree-win32.mjs` (8) |
 | `assert-killtree-portable.mjs` | portable `killTree` contract | `node tools/assert-killtree-portable.mjs` (5) |
 | `assert-parallel-mcp.mjs` | Parallel MCP engine: the 25 s timeout / caller abort covers the **body read**, shared SSE parser (notifications, multiline frames), six error paths, REST precise time filtering | `node tools/assert-parallel-mcp.mjs` (15) |
-| `assert-provider-takeover.mjs` | provider takeover: both the legacy property API and the rc.2 `config.*` refs, a single batched `settings.mutate(web)`, explicit foreign providers left untouched, an explicit `http` kept when `fetchProviderTakeover` is off, apply re-entry / duplicate registrations tolerated, and repeated logs deduplicated | `node tools/assert-provider-takeover.mjs` (12) |
+| `assert-bridge-access.mjs` | bridge Host fence (#84): loopback allowed, a remote peer behind a loopback Host refused, `--trusted-host` (port-less matches any port, explicit port matches exactly), `--public-url`, the bind address, cross-site and foreign-Origin refused | `node tools/assert-bridge-access.mjs` (11) |
+| `assert-provider-takeover.mjs` | provider takeover: both the legacy property API and the rc.2 `config.*` refs, a single batched `settings.mutate(web)`, explicit foreign providers left untouched, an explicit `http` kept when `fetchProviderTakeover` is off, describe()-triggered events ignored when nothing changed, nested config changes and web rebuilds reported separately, apply re-entry / duplicate registrations tolerated, and repeated logs deduplicated | `node tools/assert-provider-takeover.mjs` (14) |
 
 Any failure exits non-zero with the failing items listed. Passing the path of an older file shows the pre-fix failures (proving the assertions are not vacuous). Worth running before a release.
 

package/lib/client.js

@@ -5,6 +5,7 @@ window.__ModuleLoader__.load({
     var exports = module.exports;
 
     let react = require("react");
+    let react_dom = require("react-dom");
     let react_jsx_runtime = require("react/jsx-runtime");
 
     //#region css
@@ -29,6 +30,13 @@ window.__ModuleLoader__.load({
       "@keyframes dshfsFadeIn{from{opacity:0;transform:translateY(-4px)}to{opacity:1;transform:translateY(0)}}",
       ".dshfs-body{flex-direction:column;gap:20px;padding:0 20px 20px;display:flex;animation:dshfsFadeIn 240ms cubic-bezier(.4,0,.2,1) forwards}",
       "@media (prefers-reduced-motion: reduce){.dshfs-body{animation:none}}",
+      ".dshfs-rail{display:none;position:fixed;top:50%;transform:translateY(-50%);flex-direction:column;gap:2px;max-height:70vh;overflow:auto;z-index:5;padding:2px}",
+      ".dshfs-railItem{display:flex;align-items:center;gap:6px;padding:3px 2px;border:0;background:none;font:inherit;font-size:12px;line-height:1.5;color:inherit;opacity:.42;text-align:left;cursor:pointer;transition:opacity 120ms}",
+      ".dshfs-railItem:hover{opacity:.85}",
+      ".dshfs-railItemActive{opacity:.95;font-weight:600}",
+      ".dshfs-railDot{flex:none;width:4px;height:4px;border-radius:50%;background:currentColor;opacity:.45}",
+      ".dshfs-railItemActive .dshfs-railDot{opacity:1;background:#0071e3}",
+      "@media (prefers-color-scheme: dark){.dshfs-railItemActive .dshfs-railDot{background:#0a84ff}}",
       ".dshfs-footer{justify-content:space-between;align-items:center;gap:12px;display:flex;flex-wrap:wrap;padding-top:4px}",
       ".dshfs-footerLeft{display:flex;align-items:center;gap:12px;flex-wrap:wrap;min-width:0}",
       ".dshfs-footerRight{display:flex;align-items:center;gap:10px;flex-wrap:wrap}",
@@ -267,6 +275,13 @@ window.__ModuleLoader__.load({
         marketAuto: "自动 —— 不发送 mkt（推荐用于非上列地区）",
         fetchTakeoverLabel: "自动接管 web_fetch",
         fetchTakeoverHint: "开启时：web.fetchProvider 未设置或仍是出厂默认 http 会接管为 fs-quality-fetch。如果你刻意 pin 了 http（例如只想用内置抓取），关掉此项。",
+        navLabel: "本页导航",
+        navEngines: "引擎",
+        navFallback: "回退",
+        navPools: "语言池",
+        navBehavior: "搜索行为",
+        navFetch: "抓取",
+        navPerformance: "性能",
         marketZhCN: "zh-CN —— 中国大陆（默认）",
         marketZhTW: "zh-TW —— 台湾",
         marketEnUS: "en-US —— 美国",
@@ -388,6 +403,13 @@ window.__ModuleLoader__.load({
         marketAuto: "Automatic — send no mkt (recommended outside the listed regions)",
         fetchTakeoverLabel: "Take over web_fetch automatically",
         fetchTakeoverHint: "On: when web.fetchProvider is unset or still the factory default http, it is taken over as fs-quality-fetch. Turn this off if you deliberately pinned http (e.g. you only want the built-in fetcher).",
+        navLabel: "On this page",
+        navEngines: "Engines",
+        navFallback: "Fallback",
+        navPools: "Language pools",
+        navBehavior: "Search behaviour",
+        navFetch: "Fetch",
+        navPerformance: "Performance",
         marketZhCN: "zh-CN - China (default)",
         marketZhTW: "zh-TW - Taiwan",
         marketEnUS: "en-US - United States",
@@ -404,8 +426,27 @@ window.__ModuleLoader__.load({
     };
     const tt = (lang) => I18N[lang === "en" ? "en" : "zh"];
     // 当前插件版本（与 lib/index.js 的 PLUGIN_VERSION 保持一致；跟随上游 v0.7.5）
-    const PLUGIN_VERSION = "0.9.6";
+    const PLUGIN_VERSION = "0.9.7";
     const PLUGIN_REPO_URL = "https://github.com/DDDMUC/dsh-free-search";
+    // 右侧浮动目录（#85）：条目顺序即页面顺序，anchor 是页面里对应 field 的 id。
+    const NAV_ITEMS = [
+      { id: "engines", anchor: "dshfs-anchor-engines" },
+      { id: "fallback", anchor: "dshfs-anchor-fallback" },
+      { id: "pools", anchor: "dshfs-anchor-pools" },
+      { id: "behavior", anchor: "dshfs-anchor-behavior" },
+      { id: "fetch", anchor: "dshfs-anchor-fetch" },
+      { id: "performance", anchor: "dshfs-anchor-performance" },
+    ];
+    // 目录跟着真正滚动的祖先走：DSH 页面通常不是 window 在滚。
+    const findScrollParent = (element) => {
+      let node = element && element.parentElement ? element.parentElement : null;
+      while (node && node !== document.body && node !== document.documentElement) {
+        const style = window.getComputedStyle(node);
+        if (/(auto|scroll|overlay)/.test(style.overflowY) && node.scrollHeight > node.clientHeight) return node;
+        node = node.parentElement;
+      }
+      return null;
+    };
     const ENGINES = [
       { id: "auto", label: "Auto · 智能路由", badge: "AUTO", link: null },
       { id: "multi", label: "Multi Search · 多引擎", badge: "MULTI", link: null },
@@ -601,6 +642,9 @@ window.__ModuleLoader__.load({
       // 页面自带标题/面包屑，卡片固定展开、表头不再可折叠。
       const pageMode = !!(props && props.page);
       const [open, setOpen] = react.useState(pageMode);
+      const [railActive, setRailActive] = react.useState(NAV_ITEMS[0].id);
+      const bodyRef = react.useRef(null);
+      const railRef = react.useRef(null);
       const [state, setState] = react.useState({ status: "loading" });
       const [provider, setProvider] = react.useState("bing");
       const [disabledEngines, setDisabledEngines] = react.useState([]);
@@ -1019,9 +1063,86 @@ window.__ModuleLoader__.load({
         }
       };
 
+      // 浮动目录（#85）：放在卡片右侧的页面留白里，绝对定位不参与卡片布局，
+      // 所以正文宽度和 0.9.7 完全一致；留白不足（窄窗口/卡片贴边）时直接隐藏。
+      react.useEffect(() => {
+        if (!open) return undefined;
+        const place = () => {
+          const body = bodyRef.current;
+          const rail = railRef.current;
+          if (!body || !rail) return;
+          const space = window.innerWidth - body.getBoundingClientRect().right;
+          if (space < 120) {
+            rail.style.display = "none";
+            return;
+          }
+          rail.style.display = "flex";
+          const width = rail.getBoundingClientRect().width || 66;
+          rail.style.right = Math.max(12, Math.round(space / 2 - width / 2)) + "px";
+        };
+        place();
+        window.addEventListener("resize", place);
+        return () => window.removeEventListener("resize", place);
+      }, [open, state.status]);
+
+      // 当前分组：分组顶部越过 35% 激活线就算当前；滚到底高亮最后一组。
+      react.useEffect(() => {
+        if (!open) return undefined;
+        const scroller = findScrollParent(bodyRef.current);
+        const target = scroller ?? (typeof window === "undefined" ? null : window);
+        if (!target) return undefined;
+        const compute = () => {
+          const viewportHeight = scroller ? scroller.clientHeight : window.innerHeight;
+          const atBottom = scroller
+            ? scroller.scrollTop + scroller.clientHeight >= scroller.scrollHeight - 8
+            : window.innerHeight + window.scrollY >= document.documentElement.scrollHeight - 8;
+          if (atBottom) {
+            setRailActive(NAV_ITEMS[NAV_ITEMS.length - 1].id);
+            return;
+          }
+          const viewportTop = scroller ? scroller.getBoundingClientRect().top : 0;
+          const line = viewportTop + viewportHeight * 0.35;
+          let current = NAV_ITEMS[0].id;
+          for (const item of NAV_ITEMS) {
+            const section = typeof document === "undefined" ? null : document.getElementById(item.anchor);
+            if (section && section.getBoundingClientRect().top <= line) current = item.id;
+          }
+          setRailActive(current);
+        };
+        let frame = 0;
+        const onScroll = () => {
+          if (frame) return;
+          frame = requestAnimationFrame(() => {
+            frame = 0;
+            compute();
+          });
+        };
+        compute();
+        target.addEventListener("scroll", onScroll, { passive: true });
+        return () => {
+          target.removeEventListener("scroll", onScroll);
+          if (frame) cancelAnimationFrame(frame);
+        };
+      }, [open, state.status]);
+
       if (state.status === "loading") return null;
       const ready = state.status === "ready";
       const t = tt(uiLang || (lang === "en" ? "en" : "zh"));
+      const navLabels = {
+        engines: t.navEngines,
+        fallback: t.navFallback,
+        pools: t.navPools,
+        behavior: t.navBehavior,
+        fetch: t.navFetch,
+        performance: t.navPerformance,
+      };
+      const goToSection = (id) => {
+        const item = NAV_ITEMS.find((entry) => entry.id === id);
+        const section = item && typeof document !== "undefined" ? document.getElementById(item.anchor) : null;
+        if (!section) return;
+        setRailActive(id);
+        section.scrollIntoView({ behavior: "smooth", block: "start" });
+      };
       const title = "Free Search";
       const description = t.description;
       const enabledEngineCount = ENGINES.filter((e) => e.id !== "auto" && e.id !== "multi" && !disabledEngines.includes(e.id)).length;
@@ -1056,6 +1177,7 @@ window.__ModuleLoader__.load({
         const candidates = ENGINE_IDS.filter((id) => !pool.includes(id) && !EXPLICIT_ONLY_ENGINES.includes(id));
         return react_jsx_runtime.jsx("div", {
           className: "dshfs-field",
+          id: poolKey === "zh" ? "dshfs-anchor-pools" : undefined,
           children: [
             react_jsx_runtime.jsx("div", {
               className: "dshfs-label",
@@ -1216,9 +1338,34 @@ window.__ModuleLoader__.load({
           open
             ? react_jsx_runtime.jsx("div", {
                 className: "dshfs-body",
+                ref: bodyRef,
                 children: [
+                  // 目录走 portal 挂到 document.body：卡片的 backdrop-filter / 动画 transform
+                  // 会成为 fixed 的包含块，留在卡片里就永远贴不到页面右侧的留白。
+                  typeof document === "undefined"
+                    ? null
+                    : react_dom.createPortal(
+                        react_jsx_runtime.jsx("nav", {
+                          className: "dshfs-rail",
+                          ref: railRef,
+                          "aria-label": t.navLabel,
+                          children: NAV_ITEMS.map((item) =>
+                            react_jsx_runtime.jsx("button", {
+                              type: "button",
+                              className: "dshfs-railItem" + (railActive === item.id ? " dshfs-railItemActive" : ""),
+                              onClick: () => goToSection(item.id),
+                              children: [
+                                react_jsx_runtime.jsx("span", { className: "dshfs-railDot" }),
+                                react_jsx_runtime.jsx("span", { children: navLabels[item.id] }),
+                              ],
+                            }, item.id)
+                          ),
+                        }),
+                        document.body
+                      ),
                   react_jsx_runtime.jsx("div", {
                     className: "dshfs-field",
+                    id: "dshfs-anchor-engines",
                     children: [
 react_jsx_runtime.jsx("div", {
                         className: "dshfs-label",
@@ -1305,6 +1452,7 @@ react_jsx_runtime.jsx("div", {
                   }),
                   react_jsx_runtime.jsx("div", {
                     className: "dshfs-field",
+                    id: "dshfs-anchor-fallback",
                     children: [
                       react_jsx_runtime.jsx("div", {
                         className: "dshfs-label",
@@ -1478,6 +1626,7 @@ react_jsx_runtime.jsx("div", {
                   }),
                   react_jsx_runtime.jsx("div", {
                     className: "dshfs-field",
+                    id: "dshfs-anchor-behavior",
                     children: [
                       react_jsx_runtime.jsx("div", {
                         className: "dshfs-label",
@@ -1572,6 +1721,7 @@ react_jsx_runtime.jsx("div", {
                   }),
                   react_jsx_runtime.jsx("div", {
                     className: "dshfs-field",
+                    id: "dshfs-anchor-fetch",
                     children: [
                       react_jsx_runtime.jsx("label", {
                         className: "dshfs-check",
@@ -1677,6 +1827,7 @@ react_jsx_runtime.jsx("div", {
                   }),
                   react_jsx_runtime.jsx("div", {
                     className: "dshfs-field",
+                    id: "dshfs-anchor-performance",
                     children: [
                       react_jsx_runtime.jsx("div", {
                         className: "dshfs-label",

package/lib/index.js

@@ -256,7 +256,7 @@ function routeEngines(query, { timeRange, disabledEngines = [], fallbackOrder =
 }
 
 // 当前插件版本（发布时与 package.json 同步；跟随上游 v0.7.5，不在 PR 里 bump）
-const PLUGIN_VERSION = "0.9.6";
+const PLUGIN_VERSION = "0.9.7";
 // 检查更新的 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";
@@ -2847,26 +2847,64 @@ async function searchDoubao(query, maxResults, apiKey, timeRange, signal) {
 //#region bridge
 const MAX_JSON_BODY_BYTES = 64 * 1024;
 
-function isLoopbackRequest(request) {
-  const address = request.socket.remoteAddress;
-  if (address !== "127.0.0.1" && address !== "::1" && address !== "::ffff:127.0.0.1") return false;
-  const host = request.headers.host;
-  if (typeof host !== "string") return false;
-  let hostUrl;
+// #84：桥接接口的 Host 围栏。
+// DSH 宿主对 /api 已经做了同样的 Browser-trust 围栏并完成鉴权：放行 loopback、
+// 监听绑定的 IP 字面量，以及 --trusted-host / --public-url 声明的 authority。
+// 插件此前只认 loopback，于是 VPS / 反向代理 / 自定义域名下配置页整体 403、表单全灰。
+// 这里沿用宿主的信任集合，而不是把写接口无差别放开。
+const bridgeTrust = { hosts: [], publicHost: "" };
+
+function parseAuthority(authority) {
   try {
-    hostUrl = new URL("http://" + host);
+    return new URL("http://" + authority);
   } catch {
-    return false;
+    return null;
   }
-  if (hostUrl.hostname !== "127.0.0.1" && hostUrl.hostname !== "localhost" && hostUrl.hostname !== "[::1]") return false;
+}
+
+function isLoopbackAddress(address) {
+  const value = String(address ?? "");
+  return value === "127.0.0.1" || value === "::1" || value === "::ffff:127.0.0.1" || /^127\./.test(value);
+}
+
+function isLoopbackHostname(hostname) {
+  if (hostname === "localhost" || hostname === "[::1]" || hostname === "::1") return true;
+  const parts = hostname.split(".");
+  return parts.length === 4 && parts[0] === "127" && parts.every((part) => /^\d{1,3}$/.test(part) && Number(part) <= 255);
+}
+
+// 与宿主的 isTrustedAuthority 同规则：无端口条目匹配任意端口，带端口条目精确匹配。
+function matchesTrustedAuthority(hostUrl, entry) {
+  const entryUrl = parseAuthority(entry);
+  if (entryUrl === null) return false;
+  return entryUrl.port === "" ? entryUrl.hostname === hostUrl.hostname : entryUrl.host === hostUrl.host;
+}
+
+function isBridgeRequestAllowed(request, trust = bridgeTrust) {
+  const host = request.headers.host;
+  if (typeof host !== "string") return false;
+  const hostUrl = parseAuthority(host);
+  if (hostUrl === null) return false;
+  // 跨站发起的请求一律拒绝（防 confused deputy）；同源请求才继续看 Host。
   if (request.headers["sec-fetch-site"] === "cross-site") return false;
   const origin = request.headers.origin;
-  if (origin === undefined) return true;
-  try {
-    return new URL(origin).host === hostUrl.host;
-  } catch {
-    return false;
+  if (origin !== undefined) {
+    try {
+      if (new URL(origin).host !== hostUrl.host) return false;
+    } catch {
+      return false;
+    }
+  }
+  if (isLoopbackHostname(hostUrl.hostname)) return isLoopbackAddress(request.socket.remoteAddress);
+  if (trust.hosts.some((entry) => matchesTrustedAuthority(hostUrl, entry))) return true;
+  if (trust.publicHost && matchesTrustedAuthority(hostUrl, trust.publicHost)) return true;
+  // 直接绑定非 loopback 地址（--host 192.168.x.x / 公网 IP）时，Host 就是绑定地址。
+  const localAddress = request.socket.localAddress;
+  if (typeof localAddress === "string" && localAddress !== "0.0.0.0" && localAddress !== "::") {
+    const local = parseAuthority(localAddress.includes(":") ? `[${localAddress}]` : localAddress);
+    if (local !== null && local.hostname === hostUrl.hostname) return true;
   }
+  return false;
 }
 
 function writeJson(res, status, body) {
@@ -3116,8 +3154,8 @@ function makeBridgeRoutes(settings, search, testEngine, getCredentials) {
   };
 
   const guard = (req, res) => {
-    if (!isLoopbackRequest(req)) {
-      writeJson(res, 403, { error: "loopback requests only" });
+    if (!isBridgeRequestAllowed(req)) {
+      writeJson(res, 403, { error: "requests must come from the local host or a configured trusted host" });
       return false;
     }
     if (req.method !== "POST") {
@@ -3434,6 +3472,46 @@ function resolveConfig(config) {
   return out;
 }
 
+// #82 诊断：深度比较 web 条目的 config，返回 `a.b: 旧 → 新` 形式的路径（最多 8 条）。
+// 只用于日志，不参与任何逻辑；嵌套对象会展开，数组按整体比较。
+function changedConfigPaths(previous, next, prefix = "", out = []) {
+  const left = previous !== null && typeof previous === "object" ? previous : {};
+  const right = next !== null && typeof next === "object" ? next : {};
+  for (const key of new Set([...Object.keys(left), ...Object.keys(right)])) {
+    if (out.length >= 8) break;
+    const path = prefix ? `${prefix}.${key}` : key;
+    const before = left[key];
+    const after = right[key];
+    const nested =
+      before !== null &&
+      after !== null &&
+      typeof before === "object" &&
+      typeof after === "object" &&
+      !Array.isArray(before) &&
+      !Array.isArray(after);
+    if (nested) {
+      changedConfigPaths(before, after, path, out);
+      continue;
+    }
+    if (JSON.stringify(before ?? null) !== JSON.stringify(after ?? null)) {
+      out.push(`${path}: ${previewConfigValue(before)} → ${previewConfigValue(after)}`);
+    }
+  }
+  return out;
+}
+
+function previewConfigValue(value) {
+  if (value === undefined) return "undefined";
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    text = String(value);
+  }
+  if (text === undefined) text = "undefined";
+  return text.length > 48 ? `${text.slice(0, 45)}...` : text;
+}
+
 function apply(ctx, config) {
   // 重入保护：同一个 ctx 上 apply 只跑一次。rc.2 的 boot 里出现过未 dispose 的重入，
   // 会撞上下面的重复注册（provider / route），导致 entry 反复失败把 boot 拖死。
@@ -3460,6 +3538,25 @@ function apply(ctx, config) {
   // credentials 服务可能晚于本插件挂载（跨 bundle 顺序），运行期动态获取而不是 apply 时缓存
   const getCredentials = () => ctx.get("credentials");
 
+  // #84：读取宿主的远程访问信任集合（--trusted-host / --public-url），供桥接 Host 围栏使用。
+  // webStartup 只在 dsh web 下提供；拿不到就维持 loopback-only 的老行为。
+  ctx.inject(["webStartup"], (sctx) => {
+    try {
+      const startup = sctx.get("webStartup");
+      if (!startup) return;
+      if (Array.isArray(startup.trustedHosts)) {
+        bridgeTrust.hosts = startup.trustedHosts
+          .filter((entry) => typeof entry === "string" && entry.trim())
+          .map((entry) => entry.trim());
+      }
+      if (typeof startup.publicUrl === "string" && startup.publicUrl) {
+        try {
+          bridgeTrust.publicHost = new URL(startup.publicUrl).host;
+        } catch {}
+      }
+    } catch {}
+  });
+
   // 系统提示词动态刷新：设置变更时重新生成，避免显示旧引擎
   let refreshPrompt = null;
   // Multi Search 执行器在 runEngineTest 定义后初始化；provider.search 运行时再调用。
@@ -3950,33 +4047,47 @@ function apply(ctx, config) {
       );
     });
     // Re-render the dynamic system-prompt engine list whenever this entry's config changes.
-    // #82：先记下当前 web 配置，这样诊断日志里的 changed 是真正被改动的字段，而不是整份配置。
-    let lastWebConfig = (() => {
+    // #82：dsh-settings 在 describe() 里也会 emit `settings/document-updated`（raw 快照变了就发），
+    // 所以「收到事件」≠「有人写入」。事件只当触发信号，并且必须**推迟到 emit 栈之外**再读配置：
+    // 在 emit 的同步栈里再调 describe() 会和设置文档的写入路径打架（0.9.7 首版实测把 web 服务卡死）。
+    // 读到值后再对 web 条目的 uid + 整份 config 做深度比对：没变（describe 噪声）不记，变了才记一条。
+    const snapshotWebEntry = () => {
       try {
-        return sctx.settings.describe({ redactSecrets: true }).find((entry) => String(entry.ns) === "web")?.value ?? null;
+        const descriptor = sctx.settings.describe({ redactSecrets: true }).find((entry) => String(entry.ns) === "web");
+        if (!descriptor) return null;
+        return { uid: descriptor.schema?.uid ?? null, config: descriptor.value ?? {} };
       } catch {
         return null;
       }
-    })();
+    };
+    let lastWebEntry = null; // 首次事件只用来建立基线，不当成「变化」
+    let webDiagLogged = false;
+    let webDiagQueued = false;
+    const runWebDiag = () => {
+      const next = snapshotWebEntry();
+      const previous = lastWebEntry;
+      if (next !== null) lastWebEntry = next;
+      if (previous === null || next === null || webDiagLogged) return;
+      const changed = changedConfigPaths(previous.config, next.config);
+      const rebuilt = previous.uid !== next.uid;
+      if (!rebuilt && changed.length === 0) return;
+      const parts = [];
+      if (rebuilt) parts.push(`the web service was rebuilt (entry uid ${previous.uid} → ${next.uid})`);
+      if (changed.length > 0) parts.push(`config ${changed.join(", ")}`);
+      webDiagLogged = true;
+      logger.info(
+        `free-search: the web entry changed — ${parts.join("; ")}. A provider write rebuilds the web service and re-applies this plugin (only the first change per process is logged).`
+      );
+    };
     sctx.on("settings/document-updated", (ns) => {
-      // 诊断 #82：web 的 provider 选择被写入会让 web 服务重建、依赖它的插件重新 apply。
-      // 记一条并附上变化的字段（每进程一次），方便判断是谁触发的。
-      if (String(ns) === "web") {
-        try {
-          const descriptor = sctx.settings.describe({ redactSecrets: true }).find((entry) => String(entry.ns) === "web");
-          const next = descriptor?.value ?? null;
-          if (next !== null) {
-            const previous = lastWebConfig ?? {};
-            const keys = [...new Set([...Object.keys(previous), ...Object.keys(next)])];
-            const changed = keys.filter((key) => JSON.stringify(next[key] ?? null) !== JSON.stringify(previous[key] ?? null));
-            logOnce(
-              logger,
-              "info",
-              `free-search: the web config was updated (changed: ${changed.join(", ") || "none visible"}) — a provider write rebuilds the web service and re-applies this plugin`
-            );
-            lastWebConfig = next;
-          }
-        } catch {}
+      if (String(ns) === "web" && !webDiagQueued) {
+        webDiagQueued = true;
+        setTimeout(() => {
+          webDiagQueued = false;
+          try {
+            runWebDiag();
+          } catch {}
+        }, 0);
       }
       if (String(ns) === FREE_SEARCH_NS && typeof refreshPrompt === "function") refreshPrompt();
     });
@@ -4091,7 +4202,19 @@ function apply(ctx, config) {
       return;
     }
     void Promise.resolve(sctx.settings.mutate("web", ops)).catch((error) => {
-      logger.warn(`free-search: failed to take over the web providers (${error?.message ?? error})`);
+      const message = error?.message ?? String(error);
+      // #82：profile 的 package.json 原子写锁超时是另一类失败——不是 provider 冲突，
+      // 而是同一 profile 被并发写入，写不进配置 → 运行态和配置态对不上 → 下一轮 apply 再来一次。
+      if (/timed out waiting for the writer lock/i.test(message)) {
+        logOnce(
+          logger,
+          "warn",
+          "free-search: could not write the web provider selection — the profile's package.json writer lock timed out " +
+            `(${message}). Another writer is holding the same profile; this plugin retries on the next apply.`
+        );
+        return;
+      }
+      logger.warn(`free-search: failed to take over the web providers (${message})`);
     });
   });
 
@@ -5106,6 +5229,7 @@ function apply(ctx, config) {
 
 export {
   ALL_ENGINES,
+  isBridgeRequestAllowed,
   EXPLICIT_ONLY_ENGINES,
   assertSchemasterySupportsVolatile,
   COOLDOWN_SESSION_MS,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-free-search",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "description": "Free web search for DeepSeek Harness: 27 engines (Bing/DuckDuckGo/AnySearch/SearXNG/Exa/Tavily/Keenable/Firecrawl/Parallel keyless; Zhihu global/site via MCP and Perplexity/SerpBase/DeepSeek (official + native tools/search)/You.com/Baidu/Kimi/Aliyun/Doubao with key; OpenAI/Gemini/Claude model built-in search, explicit-only) + auto smart routing + global engine enable/disable & fallback priority + editable zh/en language pools + multi mode (parallel full language-pool merge) + multi_search cross-source tool + failure-aware fallback (quota/auth cooldown, transient retry, fallbackOn) + time filtering + platform search + domain blocklist (blockedDomains) + web_fetch, with web settings UI.",
   "type": "module",
   "main": "lib/index.js",