agent-hub-runner 0.3.3 → 0.5.0

package/README.md

@@ -16,8 +16,8 @@ agent-hub 的电脑运行器。装在你自己的电脑上，配对之后，你
 ## 需要
 
 - **Node 22 或更新**（终端里运行 `node -v` 看版本）。还没装：去 [nodejs.org](https://nodejs.org) 下载 LTS 版（Mac 选 .pkg 安装包），或者 `brew install node`。
-- **macOS**：给 bot 选目录时会在 Mac 上弹出系统的「选文件夹」窗口；开机自启也只支持 Mac。别的系统能连上，但选不了目录。
-- bot 跑命令时用 `bash`（macOS、Linux 自带）。
+- **macOS / Windows**：给 bot 选自定义目录时会弹系统选文件夹窗口；macOS 和 Windows 都支持开机自启。
+- bot 跑命令时 macOS / Linux 用 `bash`，Windows 用 PowerShell。
 
 ## 第一次连接
 
@@ -30,7 +30,15 @@ agent-hub 的电脑运行器。装在你自己的电脑上，配对之后，你
 
    配对码 5 分钟有效、只能用一次；过期了在抽屉里点「换一个码」。配对成功后直接连上。
 3. Mac 上会问「开机自动连上？(Y/n)」：回车就是「是」，以后开机自己连上，终端可以关；选「否」的话终端窗口别关。
-4. 抽屉里第 2 步会自动打勾。第 3 步点「选择目录…」，在 Mac 弹出的窗口里选这个 bot 能用的文件夹。每个 bot 各选各的。
+4. 抽屉里第 2 步会自动打勾。之后到网页右侧「bot设置 → 执行环境」给这个 bot 选电脑；默认使用这台电脑的共享资料库，需要时可点「选择自定义目录」在本机弹窗里选文件夹。
+
+## 多台电脑、共享资料库和整台电脑访问（0.5.0 起）
+
+- 同一个账号可以连多台电脑；每台运行器有自己的配置和令牌。
+- 每台电脑有一个**固定的共享资料库**：`~/.agent-runner/library`（Windows 是当前用户目录下的 `.agent-runner\library`）。程序自动创建，不能改成别的路径；升级、重启、自更新都不会清空。它是应用数据，不是临时缓存。
+- bot 绑定这台电脑后默认就使用共享资料库；单个 bot 可以在网页 bot 设置里改成别的目录。
+- 绑定后 bot 可以读写整台电脑，**不再限制在某个授权文件夹**；实际仍受运行器所在系统账号本身的权限限制。read 不弹批准，write/edit 自动允许并留记录，跑命令仍按「帮我批准命令行」决定是否要你点。只绑定你信任的电脑。
+- 后台任务创建时冻结当时的电脑和目录；中途在网页切绑不影响旧任务，新消息和新任务用新绑定。
 
 `@` 后面的地址默认是 https；`localhost`、`127.x` 默认 http；也可以写全 `码@http://…`。老写法 `pair <配对码> --server <地址>` 照样能用。只配对不连：加 `--no-start`。
 
@@ -63,14 +71,15 @@ npx -y agent-hub-runner@latest browser status  # 看浏览器装没装
 
 ## 配置文件
 
-- 默认在 `~/.agent-runner/config.json`（权限 600），里面有服务器地址、设备 id、长期令牌、电脑名和每个 bot 的目录。别发给别人。
+- 默认在 `~/.agent-runner/config.json`（权限 600），里面有服务器地址、设备 id、长期令牌、电脑名和每个 bot 的工作目录。别发给别人。
+- 共享资料库固定在同一应用目录下的 `library/`，不写进配置，也没有修改命令。
 - 想放别处：设环境变量 `AGENT_RUNNER_CONFIG=/某个路径/config.json`。
 - 文件坏了：删掉它，回网页拿新配对码重新配对。
 
 
 ## 项目上下文快照（0.3.0；`.claude/skills` 起 0.3.1）
 
-服务器在每轮主对话开始时可能调用只读操作 `context_snapshot`（没有路径参数）：在**当前 bot 的授权文件夹根**里读取一份 AGENTS/CLAUDE 规则，并列出 `.pi/skills`、`.agents/skills`、`.claude/skills` 下技能的名称与说明（不上传技能全文）。目录外路径和越界符号链接一律拒绝。基础快照需要运行器 **0.3.0+**；发现 `.claude/skills` 需要 **0.3.1+**。
+服务器在每轮主对话开始时可能调用只读操作 `context_snapshot`（没有路径参数）：在**当前 bot 的默认工作目录**里读取一份 AGENTS/CLAUDE 规则，并列出 `.pi/skills`、`.agents/skills`、`.claude/skills` 下技能的名称与说明（不上传技能全文）。R758 起目录不再是权限边界，但项目规则仍只从默认工作目录开始找。基础快照需要运行器 **0.3.0+**；发现 `.claude/skills` 需要 **0.3.1+**。
 
 ## 常见问题
 
@@ -79,10 +88,13 @@ npx -y agent-hub-runner@latest browser status  # 看浏览器装没装
 - 「权限不够」/ `EACCES`：别用 sudo；运行 `sudo chown -R "$(whoami)" ~/.npm ~/.agent-runner` 修好再试。
 - 「找不到服务器」「连不上服务器」「超时」：检查网络；命令要整条原样复制。
 - 「配对码过期了 / 已经用过了 / 已经作废了」：网页上点「换一个码」再运行新命令。
-- 「这个账号已经连着一台电脑了」：一个账号同时只能连一台，先在网页抽屉「连着的电脑」里点「断开」。
+- 「这个账号已经连着一台电脑了」：这是旧版提示；0.5.0 起一个账号可以连多台，旧版可以升级后再配。
+- 想再加一台电脑：网页「我的电脑」抽屉里点「添加电脑」，拿新码到另一台电脑运行。
 - 开机自启报「Bootstrap failed: 5: Input/output error」：这个后台任务以前被 macOS 记成了「已禁用」。0.2.1 起 `autostart on` 会自己解除并重试，直接再运行一次 `npx -y agent-hub-runner@latest autostart on` 就行；还不行就按它给的那条 `launchctl enable …` 命令运行后再试，或重启电脑再试。
 - 升级后网页还说「运行器版本太旧」：旧版本的运行器还在后台跑着（升级前开的终端，或者旧的开机自启），新版一看有人连着就退出了。0.2.2 起新版会自己把旧版本停掉、接上服务器；从 0.2.1 或更早升上来的，运行一次 `npx -y agent-hub-runner@latest autostart on` 就行，它会先停掉正在跑的那个，等新版本真连上了才说「已设开机自启」。
 - 网页上点「升级」（0.3.2 起）：抽屉里有新版本时点一下，运行器自己去 npm 拉最新版、校验后换上并重启，不用开终端。0.3.1 及更早不认这个按钮，仍用上面那条命令升一次。
+- 联网搜索（0.4.0 起）：bot 设置里打开「允许联网搜索」后，bot 可以上网查资料。默认用 DuckDuckGo，不用注册、不用 key。想更稳可以在「我的电脑」抽屉里换成 Tavily 或 Brave（去官网注册，把 key 粘进来），或者填一个 SearXNG 地址。key 只存在你电脑上，服务器不留。0.3.x 及更早没有这项，抽屉里会给升级命令。
+- 共享资料库和整台电脑访问需要 **0.5.0**；旧运行器仍能连接，但不知道默认资料库，也不会按新规则放开目录。
 
 ## 断开、卸载
 

package/autostart.mjs

@@ -20,7 +20,7 @@ export const THROTTLE_S = 10;
 /** 复制到 ~/.agent-runner/bin/<版本>/ 的文件（package.json 用来读版本号） */
 // @意图#R729(2026-11-04): 多复制 browser.mjs（runner.mjs 要 import 它）
 // @意图#R690(2026-11-01): 多复制 changes.mjs（runner.mjs 要 import 它，少了开机自启的副本起不来）
-export const COPY_FILES = ["runner.mjs", "ops.mjs", "project-context.mjs", "edit.mjs", "changes.mjs", "browser.mjs", "autostart.mjs", "package.json"];
+export const COPY_FILES = ["runner.mjs", "ops.mjs", "project-context.mjs", "edit.mjs", "changes.mjs", "browser.mjs", "autostart.mjs", "search.mjs", "package.json"]; // search.mjs：R751 联网搜索（零依赖，拷文件即可）
 /** 优先用的稳定 node 路径（Homebrew 升级 node 后这两个软链还在；nvm 的带版本号路径卸了就没了） */
 export const STABLE_NODES = ["/opt/homebrew/bin/node", "/usr/local/bin/node"];
 export const ONLY_MAC = "开机自启目前只支持 Mac 和 Windows";

package/ops.mjs

@@ -1,5 +1,5 @@
-// @意图#R636(2026-10-27): 运行器在你电脑上真正执行 read / write / edit / bash。路径只在这里判断（S6 结论：服务器不解析用户电脑的路径）：
-// 先按授权目录换算成真实路径（解开符号链接，包括指向不存在目标的符号链接），不在授权目录里的一律拒绝；bash 的工作目录就是授权目录。
+// @意图#R636(2026-10-27): 运行器在你电脑上真正执行 read / write / edit / bash。路径只在这里判断（S6 结论：服务器不解析用户电脑的路径）。
+// @意图#R758(2026-11-08): 绑定后整台电脑都可读写，工作目录只是默认 cwd（相对路径起点）；仍然解开符号链接，不越过 OS 账号权限。
 // 第一轮没有沙箱（king 定的范围）：bash 里的命令本身能碰到目录外的东西，只能靠你看清批准卡片再点。
 import { spawn, spawnSync } from "node:child_process";
 import fs from "node:fs/promises";
@@ -44,14 +44,10 @@ export async function realOf(abs, depth = 0) {
 
 export const inside = (real, root) => real === root || real.startsWith(root.endsWith(path.sep) ? root : root + path.sep);
 
-/** 换算并检查：在授权目录里返回真实路径，不在就抛「目录外路径已拒绝」。 */
-// @意图#R636(2026-10-27): 授权目录外的路径一律拒绝
+/** 换算成真实路径；R758 起不再限制在 root 内，root 只用来解析相对路径。 */
 export async function resolveInside(p, root) {
   if (typeof p !== "string" || !p.trim()) throw new Error("路径是空的");
-  let real;
-  try { real = await realOf(expandPath(p, root)); } catch (e) { throw new Error(`无法解析路径：${p}（${e?.code ?? e?.message ?? e}）`); }
-  if (!inside(real, root)) throw new Error(`目录外路径已拒绝：${p}（授权目录是 ${root}）`);
-  return real;
+  try { return await realOf(expandPath(p, root)); } catch (e) { throw new Error(`无法解析路径：${p}（${e?.code ?? e?.message ?? e}）`); }
 }
 
 function imageMime(buf) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hub-runner",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "agent-hub 的电脑运行器：配对后让你的 bot 在这台电脑上读写授权目录里的文件、跑命令（跑命令要你在网页上批准），还能用它自己的独立浏览器",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "changes.mjs",
     "browser.mjs",
     "autostart.mjs",
+    "search.mjs",
     "bin/agent-hub-runner.mjs",
     "README.md"
   ],

package/runner.mjs

@@ -28,9 +28,10 @@ import { fileURLToPath } from "node:url";
 import { runOp } from "./ops.mjs";
 import { buildChangeRecord, changesDirFor, CHANGE_ID_RE, createChangeStore } from "./changes.mjs";
 import { browserStatus, createBrowserManager, installBrowser } from "./browser.mjs";
+import { searchWeb, cleanSearchConfig, searchConfigStatus } from "./search.mjs"; // R751
 import { autostartOff, autostartOffWindows, autostartOn, autostartOnWindows, autostartStatus, autostartStatusWindows, COPY_FILES, installCopy, integrityOk, logFileFor, ONLY_MAC, otherAutostarts, runnerHome, truncateLogIfBig } from "./autostart.mjs";
 
-export const PROTOCOL_VERSION = 1;
+export const PROTOCOL_VERSION = 2;
 /** npm 包名，也是装好后的命令名 */
 export const PKG_BIN = "agent-hub-runner";
 /** R666：抽屉里给的、npx 运行时提示里写的命令前缀（@latest：每次都用最新版，也不会被电脑上旧的全局安装盖掉） */
@@ -49,6 +50,8 @@ export const CLOSE_REPLACED = 4409;
 
 // @意图#R666(2026-10-29): 默认目录可用 AGENT_RUNNER_HOME 换（测试、开机自启的副本用）；不设时和原来一样是 ~/.agent-runner/config.json
 export const configPath = () => process.env.AGENT_RUNNER_CONFIG || path.join(runnerHome(), "config.json");
+/** R758：这台电脑固定的共享资料库（程序自己管理，不提供修改入口）；测试可用 AGENT_RUNNER_HOME 隔离。 */
+export const libraryDir = (env = process.env) => path.join(runnerHome(env), "library");
 
 const stamp = () => new Date().toLocaleTimeString("zh-CN", { hour12: false });
 const say = (s) => console.log(`[${stamp()}] ${s}`);
@@ -187,9 +190,8 @@ export function pickDirWindows({ signal, spawn: spawnFn = spawn } = {}) {
 
 // @意图#R639(2026-10-27): 配对时的 --dir 和网页上选的目录走同一套检查
 export async function checkDir(dir) {
-  const real = await fs.realpath(path.resolve(dir)).catch(() => { throw new Error(`授权目录不存在：${dir}`); });
-  if (!statSync(real).isDirectory()) throw new Error(`授权目录不是目录：${dir}`);
-  if (real === path.parse(real).root) throw new Error("不能把整个磁盘根目录授权出去");
+  const real = await fs.realpath(path.resolve(dir)).catch(() => { throw new Error(`工作目录不存在：${dir}`); });
+  if (!statSync(real).isDirectory()) throw new Error(`工作目录不是目录：${dir}`);
   return real;
 }
 
@@ -306,8 +308,10 @@ const wsUrlOf = (server) => `${server.replace(/^http/, "ws")}/devices/ws`;
 // 新消息 change_get {id, change_id} → change_result {id, ok:true, found, record}，不看这个 bot 有没有目录（换了目录也能看旧记录）
 // @意图#R729(2026-11-04): 新消息 browser {id, bot_id, action, args} → result（截图或元素清单）、browser_open {id, bot_id} → result（网页点「打开 bot 的浏览器」）；
 // 浏览器不看这个 bot 有没有选目录（资料目录在 ~/.agent-runner/browser-profiles/<bot_id>/，和授权目录无关）；断线不关浏览器（重连后接着用）
-export function createSession(cfg, { log = say, platform = process.platform, pickDir = platform === "win32" ? pickDirWindows : pickDirMac, file = configPath(), changes, browser } = {}) {
-  let dirs = botDirsOf(cfg); // bot_id → 授权目录
+export function createSession(cfg, { log = say, platform = process.platform, pickDir = platform === "win32" ? pickDirWindows : pickDirMac, file = configPath(), changes, browser, search } = {}) {
+  const searchImpl = search ?? searchWeb; // R751：测试注入，默认真搜
+  const sharedLibrary = libraryDir();
+  let dirs = botDirsOf(cfg); // bot_id → 工作目录
   let browsers = browser; // R729：每个 bot 一只浏览器，用到时才建
   const browserMgr = () => (browsers ??= createBrowserManager({ log }));
   const jobs = new Map(); // 调用 id → AbortController
@@ -330,8 +334,11 @@ export function createSession(cfg, { log = say, platform = process.platform, pic
   async function handleCall(send, msg) {
     const { id, op, args } = msg;
     const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
-    const dir = bot ? dirs[bot] : undefined; // 这次调用用开始时这个 bot 的目录；中途换目录不影响它
+    // R758：任务/这一轮冻结的目录优先；没有就按 bot 当前目录。中途换目录不影响已经发出去的调用。
+    const frozen = typeof msg.dir === "string" && msg.dir.trim() ? msg.dir.trim() : undefined;
+    let dir = bot ? (frozen ?? dirs[bot]) : undefined;
     if (!dir) { send({ type: "result", id, ok: false, error: NO_DIR }); return; }
+    try { dir = await checkDir(dir); } catch (e) { send({ type: "result", id, ok: false, error: e?.message ?? String(e) }); return; }
     const ac = new AbortController();
     jobs.set(id, ac);
     log(`[${bot}] ${op === "bash" ? `bash：${args?.command}` : `${op}：${args?.path}`}`);
@@ -362,6 +369,32 @@ export function createSession(cfg, { log = say, platform = process.platform, pic
       send({ type: "result", id, ok: false, error: e?.message ?? String(e) });
     }
   }
+  // @意图#R751(2026-11-07): 联网搜索：不看 bot 有没有选目录（搜索不碰文件）；按本机配置选 provider，key 只在这台电脑上
+  async function handleSearch(send, msg) {
+    const { id } = msg;
+    const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
+    const query = typeof msg.args?.query === "string" ? msg.args.query : "";
+    log(`[${bot}] 搜索：${query}`);
+    try {
+      const r = await searchImpl(query, { count: msg.args?.count, search: cfg.search });
+      send({ type: "result", id, ok: true, provider: r.provider, results: r.results, cached: r.cached === true });
+    } catch (e) {
+      send({ type: "result", id, ok: false, error: e?.message ?? String(e) });
+    }
+  }
+  // 网页保存搜索配置：key 只写本机配置文件，不回显；服务器只拿 provider/hasKey 状态
+  async function handleSearchConfig(send, msg) {
+    const { id } = msg;
+    try {
+      cfg.search = cleanSearchConfig(msg.config);
+      saveConfig(cfg, file);
+      log(`搜索配置已保存：${cfg.search.provider}${cfg.search.apiKey ? "（有 key）" : ""}`);
+      send({ type: "result", id, ok: true, ...searchConfigStatus(cfg.search) });
+    } catch (e) {
+      send({ type: "result", id, ok: false, error: e?.message ?? String(e) });
+    }
+  }
+
   // @意图#R729(2026-11-04): 网页点「打开 bot 的浏览器」：在这台电脑上弹出有窗口的浏览器（后台的换成有窗口的，恢复打开的网址）
   async function handleBrowserOpen(send, msg) {
     const { id } = msg;
@@ -375,6 +408,24 @@ export function createSession(cfg, { log = say, platform = process.platform, pic
     }
   }
 
+  // R758：服务器同步 bot 当前绑定。dir 空 = 用固定共享资料库；自定义路径来自本机选目录或服务器已保存的值。
+  async function handleSetBinding(send, msg) {
+    const { id } = msg;
+    const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
+    if (!bot) { send({ type: "result", id, ok: false, error: "缺 bot_id" }); return; }
+    try {
+      const wanted = typeof msg.dir === "string" && msg.dir.trim() ? msg.dir.trim() : sharedLibrary;
+      if (wanted === sharedLibrary) mkdirSync(sharedLibrary, { recursive: true, mode: 0o700 });
+      const real = await checkDir(wanted);
+      dirs = { ...dirs, [bot]: real };
+      cfg.bot_dirs = { ...dirs };
+      saveConfig(cfg, file);
+      send({ type: "result", id, ok: true, bot_id: bot, dir: real });
+    } catch (e) {
+      send({ type: "result", id, ok: false, error: e?.message ?? String(e) });
+    }
+  }
+
   async function handlePick(send, msg) {
     const { id } = msg;
     const bot = typeof msg.bot_id === "string" ? msg.bot_id : "";
@@ -408,10 +459,13 @@ export function createSession(cfg, { log = say, platform = process.platform, pic
     cleanChanges() { return changeStore().clean(true).catch(() => 0); },
     onMessage(msg, send) {
       if (msg.type === "call") return handleCall(send, msg);
+      if (msg.type === "set_binding") return handleSetBinding(send, msg);
       if (msg.type === "pick_dir") return handlePick(send, msg);
       if (msg.type === "change_get") return handleChangeGet(send, msg);
       if (msg.type === "browser") return handleBrowser(send, msg); // R729
       if (msg.type === "browser_open") return handleBrowserOpen(send, msg); // R729
+      if (msg.type === "search") return handleSearch(send, msg); // R751
+      if (msg.type === "search_config") return handleSearchConfig(send, msg); // R751
       if (msg.type === "abort") { jobs.get(msg.id)?.abort(); picks.get(msg.id)?.abort(); }
       return undefined;
     },
@@ -461,8 +515,8 @@ export function startRunner(cfg, { log = say, retryMs = 2000, platform = process
     const sock = new WebSocket(wsUrlOf(cfg.server));
     ws = sock;
     sock.addEventListener("open", () => {
-      send(sock, { type: "hello", version: PROTOCOL_VERSION, device_id: cfg.device_id, token: cfg.token, bot_dirs: session.botDirs,
-        name: cfg.name ?? os.hostname(), os: `${process.platform} ${os.release()}`, runner_version: RUNNER_VERSION, autostart: background, browser: browserInfo() });
+      send(sock, { type: "hello", version: PROTOCOL_VERSION, device_id: cfg.device_id, token: cfg.token, bot_dirs: session.botDirs, library_dir: libraryDir(),
+        name: cfg.name ?? os.hostname(), os: `${process.platform} ${os.release()}`, runner_version: RUNNER_VERSION, autostart: background, browser: browserInfo(), search: searchConfigStatus(cfg.search) });
       beat = setInterval(() => send(sock, { type: "ping", browser: browserInfo() }), HEARTBEAT_MS);
     });
     sock.addEventListener("message", (ev) => {

package/search.mjs

@@ -0,0 +1,174 @@
+// @意图#R751(2026-11-07): king 确认 R751：运行器内置联网搜索，网页开关可选。
+// 默认 DuckDuckGo 抓公开结果页（免注册免 key），可选 Tavily / Brave key、SearXNG 实例地址。
+// key 只存本机 config.json（600），由网页下发（runner.mjs 的 search_config），服务器不存。
+// 零依赖：DDG 的 HTML 解析自己写——开机自启安装只拷文件不装依赖（autostart.mjs 的 COPY_FILES），引第三方库会让自启那份跑不起来。
+// 参考 pi-web-access 的 duckduckgo.ts 的做法（抓 html.duckduckgo.com/html/ 再解析）；DDG 是非官方接口，改版/限流会失败，报错要说人话。
+
+export const SEARCH_PROVIDERS = ["duckduckgo", "tavily", "brave", "searxng"];
+export const SEARCH_CACHE_MS = 5 * 60_000; // 同一个查询 5 分钟内不重查，防模型刷搜索
+export const SEARCH_TIMEOUT_MS = 20_000;
+const DDG_URL = "https://html.duckduckgo.com/html/";
+const UA = "Mozilla/5.0 (compatible; agent-hub-runner/1.0; +https://github.com/cs1145994973/agent-hub-runner)";
+const CACHE_MAX = 50;
+const cache = new Map(); // key → { at, results }
+
+export function normalizeCount(n) {
+  if (typeof n !== "number" || !Number.isFinite(n)) return 5;
+  return Math.max(1, Math.min(Math.floor(n), 10));
+}
+
+/** 去标签 + 解码常见 HTML 实体（DDG 的标题/摘要里有 <b> 和实体） */
+export function decodeHtml(s) {
+  return String(s ?? "")
+    .replace(/<[^>]*>/g, "")
+    .replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (m, ent) => {
+      const lower = ent.toLowerCase();
+      if (lower.startsWith("#x")) return String.fromCodePoint(parseInt(lower.slice(2), 16));
+      if (lower.startsWith("#")) return String.fromCodePoint(parseInt(lower.slice(1), 10));
+      const named = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+      return named[lower] ?? m;
+    })
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function resultUrl(href) {
+  try {
+    const link = new URL(href, DDG_URL);
+    const dest = link.searchParams.get("uddg") ?? link.href;
+    const url = new URL(dest);
+    return url.protocol === "http:" || url.protocol === "https:" ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 解析 DDG 结果页：按 class 含独立单词 result 的 div 分块，跳过广告块，提 result__a / result__snippet */
+export function parseDuckDuckGo(html, count = 5) {
+  const starts = [...String(html).matchAll(/<div[^>]*class="[^"]*\bresult\b[^"]*"[^>]*>/g)];
+  const results = [];
+  let parseable = 0;
+  for (let i = 0; i < starts.length && results.length < count; i++) {
+    const begin = starts[i].index;
+    const end = i + 1 < starts.length ? starts[i + 1].index : html.length;
+    const block = html.slice(begin, end);
+    if (/result--ad/.test(starts[i][0])) continue;
+    const a = block.match(/<a\b[^>]*result__a[^>]*>([\s\S]*?)<\/a>/);
+    if (!a) continue;
+    const href = a[0].match(/href="([^"]+)"/)?.[1] ?? "";
+    const title = decodeHtml(a[1]);
+    const url = href ? resultUrl(href) : null;
+    if (!title || !url) continue;
+    parseable++;
+    const snip = block.match(/<(?:a|div)\b[^>]*result__snippet[^>]*>([\s\S]*?)<\/(?:a|div)>/);
+    results.push({ title, url, snippet: snip ? decodeHtml(snip[1]) : "" });
+  }
+  if (parseable === 0) throw new Error("DuckDuckGo 这次没解析到结果：可能被限流或页面结构变了。可以换个说法再试、稍后再试，或在「我的电脑」里改配 Tavily / Brave key。");
+  return results;
+}
+
+async function request(fetchImpl, url, init, signal) {
+  const res = await fetchImpl(url, {
+    ...init,
+    signal: signal ? AbortSignal.any([AbortSignal.timeout(SEARCH_TIMEOUT_MS), signal]) : AbortSignal.timeout(SEARCH_TIMEOUT_MS),
+  });
+  if (!res.ok) {
+    const body = (await res.text().catch(() => "")).slice(0, 200);
+    throw new Error(`搜索请求失败（HTTP ${res.status}）${res.status === 403 || res.status === 429 ? "：可能被限流，稍后再试" : ""}${body ? `：${body}` : ""}`);
+  }
+  return res;
+}
+
+async function searchDuckDuckGo(query, { count, fetchImpl, signal }) {
+  const url = new URL(DDG_URL);
+  url.searchParams.set("q", query);
+  const res = await request(fetchImpl, url, { headers: { Accept: "text/html", "User-Agent": UA } }, signal);
+  return parseDuckDuckGo(await res.text(), count);
+}
+
+async function searchTavily(query, { count, apiKey, fetchImpl, signal }) {
+  const res = await request(fetchImpl, "https://api.tavily.com/search", {
+    method: "POST",
+    headers: { "Content-Type": "application/json", Authorization: `Bearer ${apiKey}` },
+    body: JSON.stringify({ query, max_results: count }),
+  }, signal);
+  const data = await res.json();
+  return (data.results ?? []).slice(0, count).map((r) => ({ title: String(r.title ?? ""), url: String(r.url ?? ""), snippet: String(r.content ?? "") }));
+}
+
+async function searchBrave(query, { count, apiKey, fetchImpl, signal }) {
+  const url = new URL("https://api.search.brave.com/res/v1/web/search");
+  url.searchParams.set("q", query);
+  url.searchParams.set("count", String(count));
+  const res = await request(fetchImpl, url, { headers: { Accept: "application/json", "X-Subscription-Token": apiKey } }, signal);
+  const data = await res.json();
+  return (data.web?.results ?? []).slice(0, count).map((r) => ({ title: String(r.title ?? ""), url: String(r.url ?? ""), snippet: String(r.description ?? "") }));
+}
+
+async function searchSearxng(query, { count, searxngUrl, fetchImpl, signal }) {
+  const base = String(searxngUrl).replace(/\/+$/, "");
+  const url = new URL(`${base}/search`);
+  url.searchParams.set("q", query);
+  url.searchParams.set("format", "json");
+  const res = await request(fetchImpl, url, { headers: { Accept: "application/json", "User-Agent": UA } }, signal);
+  const data = await res.json();
+  return (data.results ?? []).slice(0, count).map((r) => ({ title: String(r.title ?? ""), url: String(r.url ?? ""), snippet: String(r.content ?? "") }));
+}
+
+/** 网页下发的配置写本地前的校验（runner.mjs 的 search_config 也用） */
+export function cleanSearchConfig(raw) {
+  const provider = SEARCH_PROVIDERS.includes(raw?.provider) ? raw.provider : "duckduckgo";
+  const out = { provider };
+  if (provider === "tavily" || provider === "brave") {
+    const key = typeof raw?.apiKey === "string" ? raw.apiKey.trim() : "";
+    if (!key) throw new Error(`${provider} 要填 API key`);
+    if (key.length > 200) throw new Error("API key 太长了，检查一下是不是复制错了");
+    out.apiKey = key;
+  }
+  if (provider === "searxng") {
+    const url = String(raw?.searxngUrl ?? "").trim();
+    const u = new URL(url); // 不合法直接抛
+    if (u.protocol !== "http:" && u.protocol !== "https:") throw new Error("SearXNG 地址要以 http(s):// 开头");
+    out.searxngUrl = url;
+  }
+  return out;
+}
+
+export function searchConfigStatus(search) {
+  const provider = SEARCH_PROVIDERS.includes(search?.provider) ? search.provider : "duckduckgo";
+  return { provider, hasKey: typeof search?.apiKey === "string" && search.apiKey.length > 0 };
+}
+
+/**
+ * 搜一次。opts: { count, search（config.json 的 search 节）, fetchImpl（测试注入）, signal }
+ * 返回 { provider, results: [{ title, url, snippet }] }；失败抛中文错误。
+ */
+export async function searchWeb(query, opts = {}) {
+  const q = String(query ?? "").trim();
+  if (!q) throw new Error("搜索词不能为空");
+  const search = opts.search ?? {};
+  const provider = SEARCH_PROVIDERS.includes(search.provider) ? search.provider : "duckduckgo";
+  const count = normalizeCount(opts.count);
+  const fetchImpl = opts.fetchImpl ?? fetch;
+  const cacheKey = `${provider}|${provider === "searxng" ? search.searxngUrl ?? "" : ""}|${count}|${q}`;
+  const hit = cache.get(cacheKey);
+  if (hit && Date.now() - hit.at < SEARCH_CACHE_MS) return { provider, results: hit.results, cached: true };
+
+  const args = { count, apiKey: search.apiKey, searxngUrl: search.searxngUrl, fetchImpl, signal: opts.signal };
+  let results;
+  if (provider === "tavily") {
+    if (!args.apiKey) throw new Error("选了 Tavily 但没配 key：在「我的电脑」里填上，或切回 DuckDuckGo。");
+    results = await searchTavily(q, args);
+  } else if (provider === "brave") {
+    if (!args.apiKey) throw new Error("选了 Brave 但没配 key：在「我的电脑」里填上，或切回 DuckDuckGo。");
+    results = await searchBrave(q, args);
+  } else if (provider === "searxng") {
+    if (!args.searxngUrl) throw new Error("选了 SearXNG 但没填实例地址：在「我的电脑」里填上，或切回 DuckDuckGo。");
+    results = await searchSearxng(q, args);
+  } else {
+    results = await searchDuckDuckGo(q, args);
+  }
+  cache.set(cacheKey, { at: Date.now(), results });
+  if (cache.size > CACHE_MAX) cache.delete(cache.keys().next().value);
+  return { provider, results };
+}