@epoch-agent/plugin-web 3.1.2 → 4.0.0

package/README.md

@@ -7,8 +7,8 @@
   web 搜索（native / tavily / brave / searxng / keyless 五个后端）
 - ❌ **不做**：不执行 JS、不渲染页面、不带浏览器；**不抓搜索引擎的 HTML 结果页**
   （违反 ToS、随时会碎、要处理验证码 —— 要搜就走后端，不走爬虫）
-- **依赖**：只有 node 内置模块。[protocol](../../protocol) 是 peer，
-  HTML 转换是手写的（无第三方库）
+- **依赖**：`@epoch-agent/protocol` + `@epoch-agent/infra`，两个都是 `dependencies`
+  （本包**没有 `peerDependencies`**），HTML 转换是手写的（无第三方库）
 
 ## 工具参数
 
@@ -50,7 +50,29 @@
 - **`keyless`**（`search/keyless.ts`）打 Exa / Parallel 的匿名 MCP 端点，
   带游标轮转摊平两家免费额度。**查询词会发给第三方**，所以它排在最后、且能整档关掉。
 
-两个开关缺省开：`search.native: false` / `search.keyless: false`。
+两个开关**缺省开**，只有显式写 `search.native: false` / `search.keyless: false` 才关
+（实现是 `=== false ? 关 : 开`，**不是「真值才开」**）。
+
+#### 为什么是这两家（2026-09-15 实探，不是照抄）
+
+四家里只有 epoch 原来会「什么都没有就把工具拿掉」，所以选型时把同级项目的做法
+和这几家的实际表现一起量了一遍：
+
+| 结论                                              | 证据                                                                                                                           |
+| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Exa / Parallel 公开 MCP 端点**匿名可用**          | 无 Authorization，`tools/call` 返回 200                                                                                        |
+| **直连可达**，不需要代理                          | 绕开本机代理重测：两域名 200 / 0.7s，结果一致                                                                                  |
+| Exa 中文覆盖**不差**、但**质量差**                | 中文查 8/8 是中文结果，其中 3 条品牌软文、2 条豆丁网                                                                           |
+| Parallel 有语义漂移                               | 英文查 10 条里 3 条是 Curtain **Wall**（建筑幕墙）                                                                             |
+| **DeepSeek 服务端搜索更好**（所以 native 排第一） | `POST /anthropic/v1/messages` + `web_search_20250305`：10 条全中文、**0 条软文**，还捞到了 Exa / Parallel 都没有的平台维度数据 |
+
+横向对照：codex 用 OpenAI Responses 的服务端 `web_search`、gemini-cli 用 Gemini
+grounding（两家都是 `native` 那一档），opencode 打 Exa / Parallel 公开端点（就是
+`keyless` 这一档），hermes-agent 做了最全的探测级联 + keyless ring。
+
+> ⚠️ **native 排在 tavily 前面是有代价的决定**：只设了 `TAVILY_API_KEY` 却没写
+> `search.provider` 的人，从这一版起会改走 native，那把 key 变成静默失效的配置。
+> 要钉住一家就显式写 `search.provider`。
 
 > SearXNG **默认没开** JSON 输出，实例的 `settings.yml` 里要有
 > `search: { formats: [html, json] }`。没开时它返回 403，我们把这句话写进了错误里 ——
@@ -83,6 +105,26 @@
 
 其余限制：响应上限 5 MB，Cloudflare 挑战会重试一次。
 
+## 回执语言：给模型读的一律英文
+
+`web_fetch` / `web_search` 的**工具回执**——失败说明、被拦截的原因、provider 报错、
+「一条都没搜到」这类说明——**全部是英文**，判据同
+[core 的 `code-mode/notice.ts`](../../core/src/code-mode/notice.ts) 文件头（2026-11-05
+拍的口径：回执的读者是模型，跟工具 description 同一档，不跟界面语言走）。
+所以这几处 `t()` 调用显式传了 `'en'`，`check:i18n` 那边也不要指望它们跟着 `zh` 变。
+
+反过来，这些**不**在这一档里：
+
+- **抓回来的网页正文 / 搜索结果的标题、摘要**——那是别人的数据，原样回给模型
+- **`unavailableReason()` 与 `selectSearchProvider()` 的 `detail`**——启动诊断，
+  用户读的，照旧跟着界面语言走
+- **`native` 档的 `buildPrompt()`**——发给对端模型的指令，用户读的正是它的回答，
+  界面切成英文却用中文问它，答案多半也是中文
+
+拦截原因那一格有个额外要求：**URL 和判定原因都得留着**。`url-safety` 只给原因
+（带主机名 / 解析到的地址），被拒的那个完整 URL 由 `web-fetch` 补在前面 ——
+少了 URL 模型不知道是第一跳还是第五跳被拒，少了原因它只能盲目换个地址重试。
+
 ## 三个 annotation 不只是元数据
 
 ```ts

package/dist/index.d.ts

@@ -238,6 +238,10 @@ declare function createBraveProvider(opts?: BraveOptions): SearchProvider;
  * 一份实现就够。`openai`（Responses API）和 `google`（grounding）的传输层
  * 完全不同，是**另外两份实现**，不在这一版里；能力表留着扩展位，
  * 表里没有的 provider 会如实报原因然后落到下一档，不是报错。
+ *
+ * ⚠️ **这一档只有一处跟界面语言走：`buildPrompt()`** —— 那是发给对端模型的指令，
+ * 用户读的正是它的回答。而 `SearchError` / `ignored` 那两句进的是**工具回执**，
+ * 一律英文（`t(..., 'en')`，2026-11-05 的口径）。
  */
 
 interface NativeOptions {
@@ -283,6 +287,10 @@ declare function createNativeProvider(opts?: NativeOptions): SearchProvider;
  * - Parallel 还收一个可选的 `model_name` 分析字段 —— **故意不传**。
  *
  * 即便如此，查询词本身仍然会发给第三方。要整档关掉：`search.keyless: false`。
+ *
+ * ⚠️ **`SearchError` / `ignored` 那两句是进工具回执的，一律英文**
+ * （`t(..., 'en')`，2026-11-05 的口径）；而 `unavailableReason()` 那句是启动诊断、
+ * 给用户看的，照旧跟界面语言走。
  */
 
 /** 给用例用：把游标拨回 0，否则用例之间会互相影响 */

package/dist/index.js

@@ -110,24 +110,30 @@ function checkUrlSafety(url) {
   try {
     parsed = new URL(url);
   } catch {
-    return { safe: false, reason: "\u65E0\u6548 URL" };
+    return { safe: false, reason: "not a valid URL (it could not be parsed)" };
   }
   if (!ALLOWED_PROTOCOLS.includes(parsed.protocol)) {
-    return { safe: false, reason: `\u7981\u6B62\u534F\u8BAE: ${parsed.protocol}` };
+    return {
+      safe: false,
+      reason: `disallowed protocol: ${parsed.protocol} (only http and https are allowed)`
+    };
   }
   if (parsed.username || parsed.password) {
-    return { safe: false, reason: "URL \u4E0D\u5141\u8BB8\u5305\u542B\u7528\u6237\u540D/\u5BC6\u7801" };
+    return { safe: false, reason: "URL must not carry a username or password" };
   }
   const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
-  if (!host) return { safe: false, reason: "\u7F3A\u5C11\u4E3B\u673A\u540D" };
+  if (!host) return { safe: false, reason: "missing hostname" };
   if (BLOCKED_HOSTNAMES.has(host)) {
-    return { safe: false, reason: `\u7981\u6B62\u8BBF\u95EE\u672C\u5730/\u5143\u6570\u636E\u4E3B\u673A: ${host}` };
+    return {
+      safe: false,
+      reason: `blocked host (loopback or cloud metadata endpoint): ${host}`
+    };
   }
   if (BLOCKED_SUFFIXES.some((s) => host.endsWith(s))) {
-    return { safe: false, reason: `\u7981\u6B62\u8BBF\u95EE\u5185\u90E8\u57DF: ${host}` };
+    return { safe: false, reason: `blocked internal domain suffix: ${host}` };
   }
   if (isIP(host) !== 0 && isBlockedAddress(host)) {
-    return { safe: false, reason: `\u7981\u6B62\u8BBF\u95EE\u79C1\u6709/\u4FDD\u7559\u5730\u5740: ${host}` };
+    return { safe: false, reason: `blocked private or reserved address: ${host}` };
   }
   return { safe: true };
 }
@@ -142,7 +148,7 @@ async function checkUrlSafetyAsync(url) {
       if (isBlockedAddress(r.address)) {
         return {
           safe: false,
-          reason: `${host} \u89E3\u6790\u5230\u79C1\u6709/\u4FDD\u7559\u5730\u5740 ${r.address}\uFF0C\u62D2\u7EDD\u8BBF\u95EE`
+          reason: `${host} resolves to the private or reserved address ${r.address} \u2014 refusing to connect`
         };
       }
     }
@@ -154,6 +160,8 @@ async function checkUrlSafetyAsync(url) {
 // src/tools/web-fetch.ts
 var MAX_SIZE = 5 * 1024 * 1024;
 var MAX_REDIRECTS = 5;
+var TOO_LARGE = "Response too large (exceeds the 5MB limit) \u2014 fetch a smaller resource instead";
+var TIMEOUT_HINT = "Request timed out \u2014 retry with a larger timeout (up to 120s) or fetch a smaller page";
 var BROWSER_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36";
 function acceptFor(format2) {
   if (format2 === "markdown") return "text/markdown;q=1.0, text/html;q=0.9, text/plain;q=0.8";
@@ -165,7 +173,7 @@ async function fetchWithSafeRedirects(startUrl, init) {
   for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
     const safety = await checkUrlSafetyAsync(current);
     if (!safety.safe) {
-      const where = hop === 0 ? "URL \u4E0D\u5B89\u5168" : `\u91CD\u5B9A\u5411\u7B2C ${hop} \u8DF3\u88AB\u62D2`;
+      const where = hop === 0 ? `Refused to fetch ${current}` : `Refused redirect hop ${hop} (${current})`;
       return { error: `${where}: ${safety.reason}` };
     }
     const response = await fetch(current, { ...init, redirect: "manual" });
@@ -177,18 +185,21 @@ async function fetchWithSafeRedirects(startUrl, init) {
       try {
         next = new URL(location, current).toString();
       } catch {
-        return { error: `\u91CD\u5B9A\u5411\u5730\u5740\u65E0\u6CD5\u89E3\u6790: ${location}` };
+        return { error: `Redirect target could not be parsed: ${location}` };
       }
       current = next;
       continue;
     }
     return { response, finalUrl: current };
   }
-  return { error: `\u91CD\u5B9A\u5411\u8D85\u8FC7 ${MAX_REDIRECTS} \u8DF3\uFF0C\u5DF2\u653E\u5F03` };
+  return {
+    error: `Gave up after more than ${MAX_REDIRECTS} redirects (possible redirect loop)`
+  };
 }
 async function execWebFetch(args, _ctx) {
   const url = String(args["url"] || "").trim();
-  if (!url) return fail(5001, "URL \u4E0D\u80FD\u4E3A\u7A7A");
+  if (!url)
+    return fail(5001, "URL is empty \u2014 pass a full page URL that starts with http:// or https://");
   const format2 = args["format"] || "markdown";
   const timeout = Math.min(args["timeout"] || 30, 120) * 1e3;
   const controller = new AbortController();
@@ -214,10 +225,9 @@ async function execWebFetch(args, _ctx) {
     if (!response.ok) return fail(5003, `HTTP ${response.status}: ${response.statusText}`);
     const contentType = response.headers.get("content-type") || "";
     const contentLen = response.headers.get("content-length");
-    if (contentLen && Number(contentLen) > MAX_SIZE)
-      return fail(5004, "\u54CD\u5E94\u8FC7\u5927 (exceeds 5MB limit)");
+    if (contentLen && Number(contentLen) > MAX_SIZE) return fail(5004, TOO_LARGE);
     const body = await readCapped(response, MAX_SIZE);
-    if (body === null) return fail(5004, "\u54CD\u5E94\u8FC7\u5927 (exceeds 5MB limit)");
+    if (body === null) return fail(5004, TOO_LARGE);
     const raw = new TextDecoder().decode(body);
     const isHtml = contentType.includes("text/html") || raw.includes("<html") || raw.includes("<HTML");
     let output;
@@ -227,7 +237,7 @@ async function execWebFetch(args, _ctx) {
       output = raw.slice(0, 5e4);
     }
     const title = extractTitle(raw, isHtml);
-    const prefix = finalUrl !== url ? `> \u6700\u7EC8\u5730\u5740: ${finalUrl}
+    const prefix = finalUrl !== url ? `> Final URL: ${finalUrl}
 
 ` : "";
     return {
@@ -239,9 +249,9 @@ ${output}` : output),
     };
   } catch (err) {
     if (err instanceof Error && err.name === "AbortError") {
-      return fail(5005, "\u8BF7\u6C42\u8D85\u65F6");
+      return fail(5005, TIMEOUT_HINT);
     }
-    return fail(5006, `\u7F51\u7EDC\u9519\u8BEF: ${err instanceof Error ? err.message : String(err)}`);
+    return fail(5006, `Network error: ${err instanceof Error ? err.message : String(err)}`);
   } finally {
     clearTimeout(timer);
   }
@@ -296,18 +306,20 @@ async function searchFetch(url, init, who) {
     response = await fetch(url, init);
   } catch (err) {
     if (err instanceof Error && err.name === "AbortError") {
-      throw new SearchError(`${who} \u641C\u7D22\u8D85\u65F6`);
+      throw new SearchError(`${who} search timed out`);
     }
-    throw new SearchError(`${who} \u8FDE\u4E0D\u4E0A\uFF1A${err instanceof Error ? err.message : String(err)}`);
+    throw new SearchError(
+      `${who} is unreachable: ${err instanceof Error ? err.message : String(err)}`
+    );
   }
   if (!response.ok) {
-    const hint = response.status === 401 || response.status === 403 ? "\uFF08API key \u65E0\u6548\u6216\u6CA1\u6709\u6743\u9650\uFF09" : response.status === 429 ? "\uFF08\u914D\u989D\u7528\u5C3D\u6216\u89E6\u53D1\u9650\u6D41\uFF09" : "";
-    throw new SearchError(`${who} \u8FD4\u56DE HTTP ${response.status}${hint}`, response.status);
+    const hint = response.status === 401 || response.status === 403 ? " (invalid or unauthorized API key)" : response.status === 429 ? " (quota exhausted or rate limited \u2014 retry later or switch provider)" : "";
+    throw new SearchError(`${who} returned HTTP ${response.status}${hint}`, response.status);
   }
   try {
     return await response.json();
   } catch {
-    throw new SearchError(`${who} \u7684\u54CD\u5E94\u4E0D\u662F\u5408\u6CD5 JSON`);
+    throw new SearchError(`${who} returned a response that is not valid JSON`);
   }
 }
 function str(obj, key) {
@@ -347,10 +359,14 @@ function format(results, ignored, summary) {
    ${snippet}` : `${i + 1}. ${r.title}${date}
    ${r.url}`;
   });
-  const head = `${results.length} \u6761\u7ED3\u679C\uFF08\u53EA\u6709\u6458\u8981\uFF0C\u8981\u6B63\u6587\u8BF7\u5BF9\u5177\u4F53 URL \u8C03 web_fetch\uFF09`;
-  const lead = summary ? ["", `\u540E\u7AEF\u7EFC\u8FF0\uFF08\u636E\u4E0B\u5217\u6765\u6E90\u5408\u6210\uFF0C\u5F15\u7528\u65F6\u8BF7\u843D\u5230\u5177\u4F53 URL\uFF09\uFF1A`, summary] : [];
+  const head = `${results.length} result${results.length === 1 ? "" : "s"} (titles, URLs and snippets only \u2014 call web_fetch on a specific URL to read the page)`;
+  const lead = summary ? [
+    "",
+    "Backend summary (synthesized from the sources below \u2014 cite a concrete URL when you quote it):",
+    summary
+  ] : [];
   const tail = ignored.length > 0 ? [`
-\u6CE8\u610F\uFF1A${ignored.join("\uFF1B")}`] : [];
+Note: ${ignored.join("; ")}`] : [];
   return [head, ...lead, "", ...lines, ...tail].join("\n");
 }
 function stringArray(value) {
@@ -366,7 +382,7 @@ function createWebSearchExec(deps) {
       return {
         success: false,
         output: "",
-        error: { code: 5101, message: "\u67E5\u8BE2\u8BCD\u4E0D\u80FD\u4E3A\u7A7A" },
+        error: { code: 5101, message: "Query must not be empty" },
         duration: 0
       };
     }
@@ -387,7 +403,11 @@ function createWebSearchExec(deps) {
     if (cached) {
       return {
         success: true,
-        output: format(cached.results, ["\u672C\u6B21\u7ED3\u679C\u6765\u81EA\u672C\u4F1A\u8BDD\u7F13\u5B58\uFF0C\u672A\u91CD\u65B0\u8054\u7F51"], cached.summary),
+        output: format(
+          cached.results,
+          ["served from this session cache \u2014 no new network request was made"],
+          cached.summary
+        ),
         duration: Date.now() - started
       };
     }
@@ -402,7 +422,7 @@ function createWebSearchExec(deps) {
       if (outcome.results.length === 0) {
         return {
           success: true,
-          output: `\u6CA1\u6709\u641C\u5230\u7ED3\u679C\uFF08${deps.provider.name}\uFF09\u3002\u6362\u4E2A\u8BF4\u6CD5\u6216\u653E\u5BBD\u6761\u4EF6\u518D\u8BD5\u3002`,
+          output: `No results from ${deps.provider.name}. Try different wording, or loosen the filters (domains / recencyDays).`,
           duration: Date.now() - started
         };
       }
@@ -412,14 +432,14 @@ function createWebSearchExec(deps) {
         duration: Date.now() - started
       };
     } catch (err) {
-      const message = err instanceof SearchError ? err.message : `\u641C\u7D22\u5931\u8D25\uFF1A${err instanceof Error ? err.message : String(err)}`;
+      const message = err instanceof SearchError ? err.message : `Search failed: ${err instanceof Error ? err.message : String(err)}`;
       return {
         success: false,
         output: "",
         error: {
           code: 5102,
           message,
-          suggestion: "\u8FD9\u4E0D\u662F\u81F4\u547D\u9519\u8BEF\uFF0C\u53EF\u4EE5\u7EE7\u7EED\u522B\u7684\u5DE5\u4F5C\uFF0C\u6216\u7A0D\u540E\u91CD\u8BD5"
+          suggestion: "This is not fatal \u2014 carry on with other work, or retry later."
         },
         duration: Date.now() - started
       };
@@ -474,7 +494,9 @@ function createBraveProvider(opts = {}) {
       }
       const ignored = [];
       if (options.recencyDays !== void 0 && !freshness) {
-        ignored.push("recencyDays\uFF08brave \u7684 freshness \u53EA\u5230\u300C\u4E00\u5E74\u5185\u300D\uFF0C\u66F4\u5927\u7684\u5929\u6570\u5DF2\u5FFD\u7565\uFF09");
+        ignored.push(
+          'recencyDays (brave freshness only reaches "past year"; larger day counts were ignored)'
+        );
       }
       return { results, ...ignored.length > 0 ? { ignored } : {} };
     }
@@ -553,25 +575,29 @@ async function mcpCall(init) {
     });
   } catch (err) {
     if (err instanceof Error && err.name === "AbortError") {
-      throw new SearchError(t2("web_search_setup.err_timeout", { who: init.who }));
+      throw new SearchError(t2("web_search_setup.err_timeout", { who: init.who }, "en"));
     }
     throw new SearchError(
-      t2("web_search_setup.err_unreachable", {
-        who: init.who,
-        detail: err instanceof Error ? err.message : String(err)
-      })
+      t2(
+        "web_search_setup.err_unreachable",
+        {
+          who: init.who,
+          detail: err instanceof Error ? err.message : String(err)
+        },
+        "en"
+      )
     );
   }
   if (!response.ok) {
-    const hint = response.status === 429 ? t2("web_search_setup.err_rate_limited_hint") : "";
+    const hint = response.status === 429 ? t2("web_search_setup.err_rate_limited_hint", void 0, "en") : "";
     throw new SearchError(
-      t2("web_search_setup.err_http", { who: init.who, status: response.status, hint }),
+      t2("web_search_setup.err_http", { who: init.who, status: response.status, hint }, "en"),
       response.status
     );
   }
   const text = parseMcpResponse(await response.text());
   if (text === void 0)
-    throw new SearchError(t2("web_search_setup.err_no_content", { who: init.who }));
+    throw new SearchError(t2("web_search_setup.err_no_content", { who: init.who }, "en"));
   return text;
 }
 // src/search/keyless.ts
@@ -630,7 +656,7 @@ function parseParallel(text, max) {
   try {
     data = JSON.parse(text);
   } catch {
-    throw new SearchError(t3("web_search_setup.err_bad_json", { who: "parallel" }));
+    throw new SearchError(t3("web_search_setup.err_bad_json", { who: "parallel" }, "en"));
   }
   if (!Array.isArray(data.results)) return [];
   const out = [];
@@ -699,9 +725,13 @@ function createKeylessProvider(opts = {}) {
         }
       }
       throw new SearchError(
-        t3("web_search_setup.keyless_all_failed", {
-          tried: failures.join(t3("web_search_setup.tried_sep"))
-        })
+        t3(
+          "web_search_setup.keyless_all_failed",
+          {
+            tried: failures.join(t3("web_search_setup.tried_sep", void 0, "en"))
+          },
+          "en"
+        )
       );
     }
   };
@@ -709,9 +739,11 @@ function createKeylessProvider(opts = {}) {
 function ignoredOf(options) {
   const ignored = [];
   if (options.recencyDays !== void 0)
-    ignored.push(t3("web_search_setup.ignored_recency_keyless"));
-  if (options.domains?.length) ignored.push(t3("web_search_setup.ignored_domains_keyless"));
-  if (options.excludeDomains?.length) ignored.push(t3("web_search_setup.ignored_exclude_keyless"));
+    ignored.push(t3("web_search_setup.ignored_recency_keyless", void 0, "en"));
+  if (options.domains?.length)
+    ignored.push(t3("web_search_setup.ignored_domains_keyless", void 0, "en"));
+  if (options.excludeDomains?.length)
+    ignored.push(t3("web_search_setup.ignored_exclude_keyless", void 0, "en"));
   return ignored;
 }
 // src/search/native.ts
@@ -795,11 +827,11 @@ function createNativeProvider(opts = {}) {
       const results = collectResults(blocks, options.maxResults);
       if (results.length === 0) {
         throw new SearchError(
-          t4("web_search_setup.native_no_search", { provider: opts.providerType })
+          t4("web_search_setup.native_no_search", { provider: opts.providerType }, "en")
         );
       }
       const summary = collectSummary(blocks);
-      const ignored = options.recencyDays === void 0 ? [] : [t4("web_search_setup.ignored_recency_native")];
+      const ignored = options.recencyDays === void 0 ? [] : [t4("web_search_setup.ignored_recency_native", void 0, "en")];
       return {
         results,
         ...summary ? { summary } : {},
@@ -844,7 +876,7 @@ function createSearxngProvider(opts) {
       ).catch((err) => {
         if (err instanceof SearchError && err.status === 403) {
           throw new SearchError(
-            "searxng \u8FD4\u56DE 403 \u2014\u2014 \u591A\u534A\u662F\u5B9E\u4F8B\u6CA1\u5F00 JSON \u8F93\u51FA\uFF08settings.yml \u91CC search.formats \u8981\u542B json\uFF09",
+            "searxng returned 403 \u2014 most likely the instance has JSON output disabled (settings.yml needs json under search.formats)",
             403
           );
         }
@@ -864,7 +896,9 @@ function createSearxngProvider(opts) {
       }
       const ignored = [];
       if (options.recencyDays !== void 0 && !range) {
-        ignored.push("recencyDays\uFF08searxng \u53EA\u652F\u6301 day/week/month/year \u56DB\u6863\uFF0C\u5929\u6570\u592A\u5927\u5DF2\u5FFD\u7565\uFF09");
+        ignored.push(
+          "recencyDays (searxng only supports day/week/month/year buckets; larger day counts were ignored)"
+        );
       }
       return { results, ...ignored.length > 0 ? { ignored } : {} };
     }
@@ -991,17 +1025,21 @@ function selectSearchProvider(config, native) {
 var webPlugin = {
   name: "@epoch-agent/plugin-web",
   version: "0.0.0",
-  description: "Web \u6293\u53D6\u63D2\u4EF6 \u2014 URL \u5B89\u5168\u6821\u9A8C + HTML\u2192Markdown + SSRF \u9632\u62A4",
+  description: "Web fetching and searching \u2014 URL safety checks, HTML to Markdown, SSRF protection",
   tools: [
     {
       name: "web_fetch",
-      description: "\u6293\u53D6\u7F51\u9875\u5185\u5BB9\u3002\u53C2\u6570: url(\u5FC5\u586B), format(markdown|text|html, \u9ED8\u8BA4 markdown), timeout(\u79D2, \u9ED8\u8BA4 30, \u6700\u5927 120)\u3002\u81EA\u52A8\u5C06 HTML \u8F6C\u4E3A Markdown\uFF0C\u8FC7\u6EE4 script/style\uFF0CSSRF \u5B89\u5168\u6821\u9A8C\u3002",
+      description: "Fetch a web page and return its content. HTML is converted to Markdown and script/style are stripped. Fails on private and loopback addresses (SSRF protection).",
       parameters: {
         type: "object",
         properties: {
-          url: { type: "string", description: "\u7F51\u9875 URL\uFF08\u5FC5\u987B\u4EE5 http:// \u6216 https:// \u5F00\u5934\uFF09" },
-          format: { type: "string", enum: ["markdown", "text", "html"], description: "\u8FD4\u56DE\u683C\u5F0F" },
-          timeout: { type: "number", description: "\u8D85\u65F6\u79D2\u6570\uFF08\u9ED8\u8BA4 30\uFF0C\u6700\u5927 120\uFF09" }
+          url: { type: "string", description: "Page URL. Must start with http:// or https://." },
+          format: {
+            type: "string",
+            enum: ["markdown", "text", "html"],
+            description: "What to return (default markdown)."
+          },
+          timeout: { type: "number", description: "Timeout in seconds (default 30, max 120)." }
         },
         required: ["url"]
       },
@@ -1015,19 +1053,29 @@ var webPlugin = {
 function createWebSearchTool(provider, opts = {}) {
   return {
     name: "web_search",
-    description: `\u7528 ${provider.name} \u641C\u7D22\u7F51\u9875\u3002\u53C2\u6570: query(\u5FC5\u586B), maxResults(\u9ED8\u8BA4 5, \u6700\u5927 20), recencyDays(\u53EA\u8981\u6700\u8FD1 N \u5929), domains(\u53EA\u641C\u8FD9\u4E9B\u57DF\u540D), excludeDomains(\u6392\u9664\u8FD9\u4E9B\u57DF\u540D)\u3002**\u53EA\u8FD4\u56DE\u6807\u9898 / URL / \u6458\u8981\uFF0C\u4E0D\u8FD4\u56DE\u7F51\u9875\u6B63\u6587** \u2014\u2014 \u770B\u5B8C\u6458\u8981\u5224\u65AD\u54EA\u6761\u503C\u5F97\u8BFB\uFF0C\u518D\u5BF9\u90A3\u4E2A URL \u8C03 web_fetch \u53D6\u6B63\u6587\u3002`,
+    description: `Search the web with ${provider.name}. **Returns titles, URLs and snippets only \u2014 not page contents.** Read the snippets, decide which result is worth opening, then call web_fetch on that URL.`,
     parameters: {
       type: "object",
       properties: {
-        query: { type: "string", description: "\u641C\u7D22\u8BCD" },
-        maxResults: { type: "number", description: "\u8FD4\u56DE\u51E0\u6761\uFF08\u9ED8\u8BA4 5\uFF0C\u6700\u5927 20\uFF09" },
-        recencyDays: { type: "number", description: "\u53EA\u8981\u6700\u8FD1 N \u5929\u5185\u53D1\u5E03\u7684" },
+        query: { type: "string", description: "Search query." },
+        maxResults: {
+          type: "number",
+          description: "How many results to return (default 5, max 20)."
+        },
+        recencyDays: {
+          type: "number",
+          description: "Only results published within the last N days."
+        },
         domains: {
           type: "array",
           items: { type: "string" },
-          description: '\u53EA\u5728\u8FD9\u4E9B\u57DF\u540D\u91CC\u641C\uFF0C\u4F8B\u5982 ["nodejs.org"]'
+          description: 'Only search within these domains, e.g. ["nodejs.org"].'
         },
-        excludeDomains: { type: "array", items: { type: "string" }, description: "\u6392\u9664\u8FD9\u4E9B\u57DF\u540D" }
+        excludeDomains: {
+          type: "array",
+          items: { type: "string" },
+          description: "Exclude these domains."
+        }
       },
       required: ["query"]
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-agent/plugin-web",
-  "version": "3.1.2",
+  "version": "4.0.0",
   "private": false,
   "description": "Web 抓取插件 — URL 安全校验 + HTML→Markdown + SSRF 防护",
   "repository": {
@@ -22,8 +22,8 @@
     "dist"
   ],
   "dependencies": {
-    "@epoch-agent/infra": "3.1.2",
-    "@epoch-agent/protocol": "3.1.2"
+    "@epoch-agent/infra": "4.0.0",
+    "@epoch-agent/protocol": "4.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",