dsh-free-search 0.9.6 → 0.9.8

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` / 引擎测试都不再用它），并可用 ↑↓ 调整全局回退顺序（一键恢复默认）
@@ -138,33 +139,45 @@ dsh web
 
 #### 接管行为与验证
 
-插件加载后**自动接管搜索**（运行时接管，不改配置层）：
+插件加载后**自动接管搜索**：
 
 - `web.searchProvider` 未设置，或仍是 DSH 出厂默认的官方搜索 `deepseek-official` 时，自动切换为本插件的 provider（id 固定为 `ddg`）；
 - 如果（你或别的插件）已显式选择其他 provider，本插件不抢占，只在启动日志输出 WARN 与切换用的 YAML。
 
-**不再往配置里写 `searchProvider: ddg`**：静态覆盖曾导致"悬空引用"——patch 是整段覆盖 config，一旦插件那一行被**停用或跳过**（比如在插件管理器里关掉），配置仍指向 `ddg` 而没有任何东西注册它，于是每次搜索都失败：
+**接管会写进 profile（DSH 0.2.x）**：从 `0.2.0-rc.2` 起 provider 选择存放在 config 的 volatile ref 里，只能经 `settings.mutate("web", …)` 写入，落盘结果就是 `profiles/<profile>/cordis.patch.yml` 多出：
+
+```yaml
+- id: web
+  config:
+    searchProvider: ddg
+    fetchProvider: fs-quality-fetch
+```
+
+所以**停用或卸载本插件之前，请先删掉 `- id: web` 这两行**（或整行删掉让 DSH 回到出厂默认）。否则配置仍指向 `ddg` 而没有任何东西注册它，每次搜索都会失败：
 
 ```
 Error: configured web provider "ddg" is not registered
 ```
 
-现在没有这层覆盖：插件被停用时 `web.searchProvider` 保持官方默认（`deepseek-official`），搜索至少还能走官方通道；插件启用时由上面的运行时接管切到 `ddg`。
+更早的 DSH（0.1.x）由 patch 静态覆盖 config，不需要也更不该手写这段，这里不再赘述。
 
-> 如果你曾按旧文档手动在 `profiles/<profile>/cordis.patch.yml` 里加过下面这段，而插件没有启用，就会看到上面那条错误——**删掉这段即可**（或重新启用插件）：
+#### DSH 的「DeepSeek 搜索 API」开关
 
-```yaml
-# 可选，通常不需要：只有你想强制指定时才加。
-# DSH 0.1.2+ 的 patch 是"整段覆盖 config"，必须保留 fetchProvider。
-- id: web
-  config:
-    searchProvider: ddg
-    fetchProvider: http
-```
+DSH 0.2.1 设置 → 网页搜索 → **DeepSeek 搜索 API** 开关会和本插件互相影响，行为如下：
+
+| 操作 | 结果 |
+|---|---|
+| 打开开关 | `web.searchProvider` 写成 `deepseek-search-api`（属于「显式选择其他 provider」），**本插件主动让路**，搜索走官方直连 API；抓取同时变成 `deepseek-fetch-api` |
+| 关闭开关 | DSH 会把整行 `- id: web` 删掉，provider 回到出厂默认 `deepseek-official` —— 这是**模型搜索**（一次完整 aux 请求，实测 ~12s、按 token 计费），不是免费引擎 |
+| 关闭后 | **0.9.8 起**：插件检测到 `deepseek-official` 会在运行时补一次接管（日志 `DSH's search switch put the web providers back to the official defaults — re-took …`），通常几秒内恢复免费链路；若没恢复，完整重启 DSH |
+
+想换引擎请用 `/free-search-engine` 或本插件设置页，**不要动那个开关**。打开开关再关掉，官方直连会退回模型搜索，直到插件重新接管或重启。
+
+> 如果你在 0.1.x 时代按旧文档手写过 `- id: web`，现在可以删掉：0.2.x 由运行时接管写入。手写时注意 `fetchProvider` 应该是 `fs-quality-fetch`（本插件注册的抓取 provider），不是 `http`。
 
 - `searchProvider: ddg` —— 本插件的 **provider id（固定值）**，不是"使用 DuckDuckGo 引擎"；用哪个引擎由设置页的 `provider` 字段决定（`bing`/`baidu`/`auto`/…）。
-- `fetchProvider: http` —— 官方网页抓取（web-fetch-http），手动声明时必须保留。
-- 想改用官方搜索：在插件管理器里停用本插件条目即可，不需要改配置。
+- `fetchProvider: fs-quality-fetch` —— 本插件的抓取 provider（直接 → exa contents → firecrawl → crawl4ai）。
+- 想改用官方搜索：**先删掉 `- id: web` 的两行，再在插件管理器里停用本插件**。
 
 #### 姊妹插件：dsh-preset-workbench（预设工作台）
 
@@ -459,7 +472,7 @@ Search engine test:
 
 #### 离线自检断言（tools/）
 
-仓库自带 **17 个**零依赖断言脚本（合计 **507 项**），**不需要 API key、不联网、不需要测试框架**，Node ≥ 20 即可跑：
+仓库自带 **19 个**零依赖断言脚本（合计 **528 项**），**不需要 API key、不联网、不需要测试框架**，Node ≥ 20 即可跑：
 
 | 脚本 | 覆盖 | 运行（项数） |
 |---|---|---|
@@ -479,7 +492,9 @@ 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-fetch-abort.mjs` | 抓取中断（#87）：压缩响应中途断连必须 reject（不再永久 pending）、明文断连同样 reject、abort 能打断停滞的 gzip 流、complete 响应与重定向仍正常 | `node tools/assert-fetch-abort.mjs`（6） |
+| `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 重建分别成行、关闭 DSH 搜索开关后重新接管且不抢 `deepseek-search-api`、apply 重入/重复注册不再中断、重复日志去重 | `node tools/assert-provider-takeover.mjs`（16） |
 
 任何一个失败会以非 0 退出码结束并列出失败项；把某个旧版本文件路径作为参数传进去，可以看到修复前必红（用来证明断言不是空转）。改动发布相关逻辑后建议先跑一遍再发版。
 
@@ -529,7 +544,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)
@@ -638,33 +654,45 @@ dsh web
 
 #### Takeover behavior and verification
 
-The plugin **takes over search at runtime** once loaded (it does not touch the config layer):
+The plugin **takes over search** once loaded:
 
 - When `web.searchProvider` is unset, or still the shipped default `deepseek-official`, it switches to this plugin's provider (id: `ddg`);
 - If you (or another plugin) explicitly selected a different provider, it does not steal it — it only logs a WARN with a copy-pasteable YAML snippet.
 
-**It no longer writes `searchProvider: ddg` into the config layer.** A static override used to create a dangling reference: a patch replaces the whole row config, so when the plugin's row was **disabled or skipped** (e.g. switched off in the plugin manager) the config still said `ddg` while nothing registered it, and every search failed with:
+**The takeover is persisted into the profile (DSH 0.2.x).** Since `0.2.0-rc.2` the provider selection lives in volatile config refs and can only be written through `settings.mutate("web", …)`, which lands in `profiles/<profile>/cordis.patch.yml` as:
+
+```yaml
+- id: web
+  config:
+    searchProvider: ddg
+    fetchProvider: fs-quality-fetch
+```
+
+So **remove those `- id: web` lines before disabling or uninstalling this plugin** (or delete the whole row and let DSH fall back to its defaults). Otherwise the config still points at `ddg` while nothing registers it, and every search fails with:
 
 ```
 Error: configured web provider "ddg" is not registered
 ```
 
-Without that override, a disabled plugin leaves `web.searchProvider` at the shipped default (`deepseek-official`) so search still works through the official provider; when the plugin is enabled the runtime takeover above points it at `ddg`.
+Older DSH (0.1.x) used a static patch layer for this; writing that row by hand there is neither needed nor recommended.
 
-> If you previously added the snippet below by hand to `profiles/<profile>/cordis.patch.yml` *and* the plugin is not enabled, you will see that error — **just remove the snippet** (or re-enable the plugin):
+#### DSH's "DeepSeek search API" switch
 
-```yaml
-# Optional; normally unnecessary — only to force a specific provider.
-# Since DSH 0.1.2 a patch REPLACES the whole entry config: keep fetchProvider.
-- id: web
-  config:
-    searchProvider: ddg
-    fetchProvider: http
-```
+DSH 0.2.1 has Settings → Web search → **DeepSeek search API**, which interacts with this plugin:
+
+| Action | Result |
+|---|---|
+| Turn the switch on | `web.searchProvider` becomes `deepseek-search-api` (an explicit choice), so **this plugin steps aside** and search goes through the official direct API; fetch becomes `deepseek-fetch-api` as well |
+| Turn the switch off | DSH deletes the whole `- id: web` row, so the provider falls back to the shipped default `deepseek-official` — that is **model search** (a full auxiliary request, ~12 s in practice, billed per token), not the free engines |
+| After turning it off | **Since 0.9.8**: the plugin notices `deepseek-official` and re-takes at runtime (log line `DSH's search switch put the web providers back to the official defaults — re-took …`), normally within seconds; if it does not, restart DSH |
+
+Use `/free-search-engine` or this plugin's settings page to change engines, **not that switch**. Turning it on and then off drops you from the official direct API back to model search until the plugin re-takes over or DSH restarts.
+
+> If you hand-wrote `- id: web` back in the 0.1.x era, you can drop it now: 0.2.x writes it at runtime. If you do declare it by hand, `fetchProvider` should be `fs-quality-fetch` (the fetch provider this plugin registers), not `http`.
 
 - `searchProvider: ddg` — this plugin's **fixed provider id**, not "use the DuckDuckGo engine"; the engine is chosen by the `provider` field in settings (`bing` / `baidu` / `auto` / …).
-- `fetchProvider: http` — the official web-fetch provider; keep it when declaring the row by hand.
-- To go back to official search: disable this plugin's entry in the plugin manager — no config edit needed.
+- `fetchProvider: fs-quality-fetch` — this plugin's fetch provider (direct → exa contents → firecrawl → crawl4ai).
+- To go back to official search: **remove those `- id: web` lines first, then disable this plugin** in the plugin manager.
 
 #### Sister Plugin: dsh-preset-workbench
 
@@ -959,7 +987,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:
+**Nineteen** zero-dependency assertion scripts ship with the repo (**528 assertions** total): **no API keys, no network, no test framework**, Node ≥ 20:
 
 | Script | Covers | Run (count) |
 |---|---|---|
@@ -979,7 +1007,9 @@ 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-fetch-abort.mjs` | fetch interruption (#87): a compressed response cut mid-body rejects instead of hanging forever, identity truncation rejects too, abort breaks a stalled gzip stream, and complete responses plus redirects still work | `node tools/assert-fetch-abort.mjs` (6) |
+| `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, re-takeover after DSH's search switch is turned off without fighting an explicit `deepseek-search-api`, apply re-entry / duplicate registrations tolerated, and repeated logs deduplicated | `node tools/assert-provider-takeover.mjs` (16) |
 
 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.8";
     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.8 完全一致；留白不足（窄窗口/卡片贴边）时直接隐藏。
+      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/fetch_provider.js

@@ -123,18 +123,70 @@ function browserDumpDom(browserPath, url, { timeoutMs = 25000, signal } = {}) {
 }
 
 /** GET 跟随重定向（≤5 跳），返回最终 URL / 状态 / 正文 / 内容类型；支持 gzip/br/deflate 解压。 */
-function httpsGetFollow(url, { headers = {}, timeoutMs = 20000, signal } = {}) {
+export function httpsGetFollow(url, { headers = {}, timeoutMs = 20000, signal } = {}, transport = https) {
   return new Promise((resolve, reject) => {
+    let settled = false;
+    let activeReq = null;
+    let activeRes = null;
+    let activeStream = null;
+
+    const cleanup = () => {
+      if (signal) signal.removeEventListener("abort", onAbort);
+    };
+    const settle = (ok, value) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (ok) resolve(value);
+      else reject(value);
+    };
+    const destroyActive = () => {
+      for (const target of [activeStream, activeRes, activeReq]) {
+        try {
+          target?.destroy?.(new Error("aborted"));
+        } catch {
+          // 忽略清理失败
+        }
+      }
+    };
+    const onAbort = () => {
+      destroyActive();
+      settle(false, signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
+    };
+
+    if (signal) {
+      if (signal.aborted) {
+        settle(false, new Error("aborted"));
+        return;
+      }
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+
     const hop = (current, left) => {
-      const u = new URL(current);
-      const req = https.request(
-        { hostname: u.hostname, port: u.port || 443, path: u.pathname + u.search, method: "GET", headers, timeout: timeoutMs, signal },
+      if (settled) return;
+      let target;
+      try {
+        target = new URL(current);
+      } catch (error) {
+        settle(false, error);
+        return;
+      }
+      const req = transport.request(
+        {
+          hostname: target.hostname,
+          port: target.port || (target.protocol === "http:" ? 80 : 443),
+          path: target.pathname + target.search,
+          method: "GET",
+          headers,
+          timeout: timeoutMs,
+        },
         (res) => {
+          activeRes = res;
           if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && left > 0) {
             res.resume();
-            const next = new URL(res.headers.location, current).toString();
-            return hop(next, left - 1);
+            return hop(new URL(res.headers.location, current).toString(), left - 1);
           }
+
           const enc = String(res.headers["content-encoding"] || "").toLowerCase();
           let stream = res;
           try {
@@ -144,17 +196,53 @@ function httpsGetFollow(url, { headers = {}, timeoutMs = 20000, signal } = {}) {
           } catch {
             stream = res;
           }
+          activeStream = stream;
+
           const chunks = [];
-          stream.on("data", (c) => chunks.push(c));
-          stream.on("end", () => resolve({ url: current, status: res.statusCode, text: Buffer.concat(chunks).toString("utf8"), contentType: res.headers["content-type"] || "" }));
-          stream.on("error", reject);
+          // 压缩响应的解压流感知不到上游 res 的销毁：pipe 不转发 error/close，
+          // 对端中途断连时解压流既不 end 也不 error，Promise 会永久挂起（#87）。
+          // 因此 body 的失败必须从 res 侧判定，并主动销毁解压流。
+          const bodyGone = (reason) => {
+            if (settled) return;
+            try {
+              stream.destroy?.();
+            } catch {
+              // 忽略
+            }
+            settle(false, reason instanceof Error ? reason : new Error(String(reason)));
+          };
+          res.on("aborted", () => bodyGone(new Error("connection aborted while reading the response body")));
+          res.on("error", (error) => bodyGone(error));
+          res.on("close", () => {
+            if (!res.complete) bodyGone(new Error("connection closed before the response body completed"));
+          });
+
+          stream.on("data", (chunk) => chunks.push(chunk));
+          stream.on("end", () =>
+            settle(true, {
+              url: current,
+              status: res.statusCode,
+              text: Buffer.concat(chunks).toString("utf8"),
+              contentType: res.headers["content-type"] || "",
+            })
+          );
+          stream.on("error", (error) => settle(false, error));
         }
       );
-      req.on("timeout", () => req.destroy(new Error(`timeout after ${timeoutMs}ms`)));
-      req.on("error", reject);
+      activeReq = req;
+      req.on("timeout", () => {
+        req.destroy(new Error(`timeout after ${timeoutMs}ms`));
+        settle(false, new Error(`timeout after ${timeoutMs}ms`));
+      });
+      req.on("error", (error) => settle(false, error));
       req.end();
     };
-    hop(url, 5);
+
+    try {
+      hop(url, 5);
+    } catch (error) {
+      settle(false, error);
+    }
   });
 }
 
@@ -222,7 +310,7 @@ export function createFetchProvider({ resolveApiKey, logger }) {
       const firecrawlKey = await resolveApiKey("FIRECRAWL_API_KEY", "firecrawlApiKey").catch(() => undefined);
       if (firecrawlKey) {
         try {
-          const md = await callFirecrawl(url, firecrawlKey);
+          const md = await callFirecrawl(url, firecrawlKey, signal);
           if (md.trim().length >= T1_MIN_CHARS) return { url, statusCode: 200, body: { kind: "text", content: md }, truncated: false };
           errors.push("firecrawl: short content");
         } catch (e) { errors.push(`firecrawl: ${e.message}`); }
@@ -231,7 +319,7 @@ export function createFetchProvider({ resolveApiKey, logger }) {
       const crawl4aiKey = await resolveApiKey("CRAWL4AI_API_KEY", undefined).catch(() => undefined);
       if (crawl4aiKey) {
         try {
-          const text = await callCrawl4ai(url, crawl4aiKey);
+          const text = await callCrawl4ai(url, crawl4aiKey, signal);
           if (text.trim().length >= T1_MIN_CHARS) return { url, statusCode: 200, body: { kind: "text", content: text }, truncated: false };
           errors.push("crawl4ai: short content");
         } catch (e) { errors.push(`crawl4ai: ${e.message}`); }

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.8";
 // 检查更新的 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,79 @@ 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.8 首版实测把 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;
+    // #86：DSH 设置里的「DeepSeek 搜索 API」开关关掉时会把整行 `- id: web` 删掉，
+    // provider 回到出厂默认 `deepseek-official`（模型搜索，更慢更贵），而插件只在加载时接管过一次。
+    // 这里在 web 配置变化后补一次运行时接管；只认「出厂默认」，绝不抢显式选择的 `deepseek-search-api`。
+    let reclaimAttempted = false;
+    const reclaimOfficialDefaults = (next) => {
+      if (reclaimAttempted) return;
+      const config = next.config ?? {};
+      const ops = [];
+      if (config.searchProvider === "deepseek-official") takeOverOps(ctx.web, "searchProvider", provider.id, ops);
+      if (
+        (config.fetchProvider === "http" || config.fetchProvider === undefined) &&
+        current().fetchProviderTakeover !== false
+      ) {
+        takeOverOps(ctx.web, "fetchProvider", fetchProvider.id, ops);
+      }
+      if (ops.length === 0) return;
+      reclaimAttempted = true;
+      const fields = [...new Set(ops.map((op) => String(op.path?.[0] ?? "?")))].join(" + ");
+      Promise.resolve(sctx.settings.mutate("web", ops)).then(
+        () =>
+          logger.info(
+            `free-search: DSH's search switch put the web providers back to the official defaults — re-took ${fields}.`
+          ),
+        (error) =>
+          logger.warn(
+            `free-search: could not re-take the web providers after the switch was turned off (${error?.message ?? error}); restart DSH to re-apply`
+          )
+      );
+    };
+    const runWebDiag = () => {
+      const next = snapshotWebEntry();
+      const previous = lastWebEntry;
+      if (next !== null) {
+        lastWebEntry = next;
+        reclaimOfficialDefaults(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 +4234,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 +5261,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.8",
   "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",