@epoch-agent/plugin-web 0.1.0

package/LICENSE

@@ -0,0 +1,219 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+--------------------------------------------------------------------------------
+
+epoch-agent
+Copyright 2024-2026 bowen
+
+Portions of this software are derived from the Gemini CLI
+(https://github.com/google-gemini/gemini-cli), Copyright 2025 Google LLC,
+licensed under the Apache License, Version 2.0. Those files have been modified;
+each one retains its original copyright notice and SPDX-License-Identifier
+header. See the NOTICE file in the project source repository for the complete
+list of derived files.
+
+This software also quotes, with attribution, two lines of prose from OpenAI
+Codex (https://github.com/openai/codex), Copyright 2025 OpenAI, licensed under
+the Apache License, Version 2.0. No source file is a derived work of Codex.
+See the NOTICE file for details.

package/README.md

@@ -0,0 +1,106 @@
+# @epoch-agent/plugin-web
+
+网页抓取与搜索插件。**两个工具**：`web_fetch`（总是有）和 `web_search`
+（**配了搜索后端才注册**）。
+
+- ✅ **做**：HTTP GET → HTML→Markdown/Text/HTML、SSRF 校验、逐跳重定向校验、大小限制；
+  web 搜索（tavily / brave / searxng 三个后端）
+- ❌ **不做**：不执行 JS、不渲染页面、不带浏览器；**不抓搜索引擎的 HTML 结果页**
+  （违反 ToS、随时会碎、要处理验证码 —— 没 key 就诚实地不提供这个工具）
+- **依赖**：只有 node 内置模块。[protocol](../../protocol) 是 peer，
+  HTML 转换是手写的（无第三方库）
+
+## 工具参数
+
+```json
+{ "url": "https://example.com/doc", "format": "markdown", "timeout": 30 }
+{ "query": "node 22 fetch keepalive", "maxResults": 5, "recencyDays": 30 }
+```
+
+**两个工具的参数表在 [docs/TOOLS.md](../../../docs/TOOLS.md#网页)** —— 那份是工具清单
+的唯一真源，这里只写这个包自己的实现取舍。
+
+## `web_search`：搜什么，不抓什么
+
+**只返回标题 / URL / 摘要，不返回正文。** 一次搜索 5 条结果全抓正文轻松几万 token，
+而其中多半是模型看一眼摘要就丢掉的。分工是：搜 → 模型挑 → `web_fetch` 抓那一条。
+
+### 三个后端，按凭据自动挑
+
+三家（`tavily` / `brave` / `searxng`）各要什么凭据见
+[docs/TOOLS.md](../../../docs/TOOLS.md#web_search-要一个搜索后端)。
+
+不配 `search.provider` 时按那张表的顺序探测，第一个有凭据的赢。**显式配了哪家就只认哪家**
+—— 缺 key 时报诊断而不是悄悄换一家：换一家意味着查询发去了另一家公司，
+那是用户没同意的事。
+
+一个后端都没有时 `web_search` **不注册**，启动诊断给 `skipped` 并列出三家各缺什么。
+注册一个一调就报错的工具比不注册更糟：模型看见工具表里有它就会反复试，每次烧一轮。
+
+> SearXNG **默认没开** JSON 输出，实例的 `settings.yml` 里要有
+> `search: { formats: [html, json] }`。没开时它返回 403，我们把这句话写进了错误里 ——
+> 否则用户会以为是自己地址写错了。
+
+### 搜索结果是**风险最高**的一种不可信内容
+
+它和抓来的网页一样带 `openWorldHint: true`（见下一节），但风险更高一档：
+网页要等 agent 主动去抓，而搜索结果是攻击者可以针对某个查询词**主动投放**的
+（SEO 投毒 + 提示注入）。所以 [core 的 system prompt](../../core/src/agent/prompt.ts)
+在不可信内容策略里单独点了它的名。
+
+结果里的 URL **不自动跟随**。模型要抓时走 `web_fetch`，SSRF 校验和 `network`
+权限判定一道都不会因为「这是搜出来的」而放松。
+
+失败（key 错 / 配额用尽 / 网络不通）返回一条**说明原因**的失败结果，不抛异常 ——
+搜索挂了不该让整轮对话断在这儿。同一个查询在**同一会话内**缓存，省配额。
+
+## SSRF 防护是三层，不是一层
+
+1. **协议白名单**——只放 `http` / `https`
+2. **主机名与 IP 字面量黑名单**——`localhost`、云元数据域名、私网段
+   （10/8、127/8、169.254/16、172.16/12、192.168/16、CGNAT、组播与保留段，IPv6 同理）
+3. **DNS 解析后再校验一次**——攻击者控制的域名可以解析到 `127.0.0.1`，
+   光看主机名字面量挡不住。这是最常见的绕过手法
+
+外加**逐跳重定向校验**：不用 `fetch` 的 `redirect: 'follow'`，而是手动跟随、每一跳
+重新做完整校验（最多 5 跳）。默认跟随只校验第一个 URL，一个公网地址 302 到
+`169.254.169.254` 就能直接读到云元数据。
+
+其余限制：响应上限 5 MB，Cloudflare 挑战会重试一次。
+
+## 三个 annotation 不只是元数据
+
+```ts
+annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: true }
+```
+
+`openWorldHint: true` 会让 [core](../../core) 的 tool-executor 把输出包进
+`<tool_output untrusted="true">`。抓来的网页内容作者既不是用户也不是我们，必须标成
+「数据」而不是「指令」再回灌上下文。
+
+`describeTarget: (args) => args.url` 让审批缓存按 URL 记——不给它就只能退回参数 JSON，
+「批准抓这个站」下次照样弹窗。
+
+## 文件
+
+| 文件                               | 内容                                            |
+| ---------------------------------- | ----------------------------------------------- |
+| `index.ts`                         | `webPlugin` + `createWebSearchTool`（条件注册） |
+| `tools/web-fetch.ts`               | 抓取 + 重定向 + 大小限制 + 重试                 |
+| `tools/web-search.ts`              | 搜索工具：参数钳制 + 会话内缓存 + 失败不炸轮    |
+| `search/provider.ts`               | 后端接口 + 共用的 HTTP / 错误分类               |
+| `search/registry.ts`               | 按配置 + 凭据挑后端（挑不到就不注册）           |
+| `search/{tavily,brave,searxng}.ts` | 三个后端各自的请求 / 响应翻译                   |
+| `utils/url-safety.ts`              | 三层 SSRF 校验                                  |
+| `utils/html-to-markdown.ts`        | 手写 HTML→Markdown / →Text                      |
+
+## 开发
+
+```bash
+pnpm --filter @epoch-agent/plugin-web test
+```
+
+四个用例文件：`ssrf.test.ts`、`url-safety.test.ts`、`html-to-markdown.test.ts`、
+`web-search.test.ts`。改 SSRF 判定必须先看前两个——里面记的是具体的绕过手法，
+不是凑数的。搜索那份**全部用假 `fetch`**：真打网络的用例要么依赖别人的 API key、
+要么在墙内直接红，两种都不该进 `pnpm check`。

package/dist/index.d.ts

@@ -0,0 +1,229 @@
+import { SearchProviderType, EpochConfig, ToolContext, ToolResult, EpochTool, EpochPlugin } from '@epoch-agent/protocol';
+
+/**
+ * 搜索后端的接口（方案 37）。
+ *
+ * ## 为什么 provider 化而不是绑死一家
+ *
+ * 搜索 API 全都要 key、都有配额、都可能被墙。绑死一家等于给用户一个大概率
+ * 不可用的功能。设计口径和 `ProviderRouter`（15 个 LLM provider 按凭据挑）一致，
+ * 但**不复用代码** —— 那边要管降级链、工厂缓存、运行期换模型，这里只要
+ * 「能不能用」和「搜一次」两件事。
+ *
+ * ## 每个 provider 只负责三件事
+ *
+ * 1. 说自己能不能用（`unavailableReason`）—— 装配层据此决定注册不注册工具
+ * 2. 把我们的查询翻成它的 HTTP 请求
+ * 3. 把它的响应翻回 `SearchResult[]`
+ *
+ * **不负责**：SSRF 校验（结果里的 URL 不自动跟随，跟随时由 `web_fetch` 校验）、
+ * 缓存（在工具那一层，跨 provider 共用）、错误分类（同上）。
+ */
+/** 一条搜索结果。**没有网页正文** —— 正文要模型自己调 `web_fetch` */
+interface SearchResult {
+    title: string;
+    url: string;
+    /** 摘要，通常是 provider 自己截的一两句话 */
+    snippet: string;
+    /** ISO 日期，provider 给了才有 */
+    publishedAt?: string;
+}
+interface SearchOptions {
+    /** 要几条。provider 自己钳到它的上限 */
+    maxResults: number;
+    /** 只要最近 N 天的。provider 不支持时**忽略并说明**，不是报错 */
+    recencyDays?: number;
+    /** 只在这些域名里搜 */
+    domains?: string[];
+    /** 排除这些域名 */
+    excludeDomains?: string[];
+    /** 中止信号，工具那一层给的超时 */
+    signal?: AbortSignal;
+}
+interface SearchOutcome {
+    results: SearchResult[];
+    /**
+     * 这次调用有哪些参数**没生效**（provider 不支持）。
+     *
+     * 走这条通道而不是静默忽略：模型写了 `recencyDays: 7` 却拿到三年前的结果，
+     * 它没法知道是「最近确实没有」还是「这个参数根本没传下去」，
+     * 于是会反复重试同一个查询。
+     */
+    ignored?: string[];
+}
+interface SearchProvider {
+    readonly name: string;
+    /**
+     * 现在能不能用；能用返回 `null`，不能用返回**一句给人看的原因**
+     * （含怎么配）。装配层拿它写启动诊断。
+     *
+     * 每次调用都重新判：key 是从环境变量读的，而凭据预取发生在装配早期，
+     * 缓存下来会得到一个「启动那一刻」的答案。
+     */
+    unavailableReason(): string | null;
+    search(query: string, opts: SearchOptions): Promise<SearchOutcome>;
+}
+/** provider 报出来的失败。工具那一层把它翻成给模型看的话，**不让整轮失败** */
+declare class SearchError extends Error {
+    /** HTTP 状态码，网络层失败时没有 */
+    readonly status?: number | undefined;
+    constructor(message: string, 
+    /** HTTP 状态码，网络层失败时没有 */
+    status?: number | undefined);
+}
+
+/**
+ * 按配置 + 凭据挑一个搜索后端（方案 37）。
+ *
+ * ```
+ * 显式配了 provider  → 只认那一家。缺 key 就报出来，**不静默回落到别家**
+ * 没配             → 按顺序试 tavily → brave → searxng，第一个能用的赢
+ * 一个都不能用      → 返回 null，工具**不注册**
+ * ```
+ *
+ * ## 「配了却缺 key」为什么不回落
+ *
+ * 用户显式写 `provider: brave` 是一个决定（他可能有隐私要求、或者公司只报销这家）。
+ * 悄悄换成 tavily 意味着他的查询发去了另一家公司 —— 那是他没同意的事。
+ * 报出来让他自己选，是唯一诚实的做法。
+ *
+ * ## 「一个都没有」为什么不注册工具，而不是注册一个会报错的
+ *
+ * 注册一个一调就失败的工具，模型会反复试（它看到工具表里有 `web_search`，
+ * 就会认为搜索是可行的），每次都烧一轮。不注册的话它从一开始就知道没这个能力。
+ * 诊断走 `skipped` 而不是 `failed` —— 没配搜索不是故障，是没开这个功能。
+ */
+
+/** 一次后端选择的结果 */
+type SearchSelection = {
+    provider: SearchProvider;
+    detail: string;
+}
+/** 没有可用后端。`detail` 是给启动诊断的一句话，含怎么配 */
+ | {
+    provider: null;
+    detail: string;
+};
+declare function createSearchProvider(type: SearchProviderType, config: EpochConfig['search']): SearchProvider;
+/**
+ * 挑一个能用的后端。
+ *
+ * @param config `EpochConfig.search`。整段缺席 = 用户没开这个功能，
+ *   但**仍然会按凭据自动探测** —— 环境里已经有 `TAVILY_API_KEY` 的人
+ *   不该被要求再写一行配置才能用上。
+ */
+declare function selectSearchProvider(config: EpochConfig['search']): SearchSelection;
+
+/**
+ * SearXNG —— **自托管、无 key** 的那一档（方案 37）。
+ *
+ * 它是这个方案里唯一一个不依赖第三方账号的后端：内网、隐私敏感、
+ * 或者单纯不想再办一个 API key 的场景，答案是它。
+ *
+ * 用 JSON 格式接口（`/search?format=json`）。注意 SearXNG **默认没开** JSON 输出，
+ * 实例的 `settings.yml` 里要有：
+ *
+ * ```yaml
+ * search:
+ *   formats: [html, json]
+ * ```
+ *
+ * 没开时它返回 HTTP 403 —— 那句提示写进了错误里，否则用户会以为是自己地址写错了。
+ */
+
+interface SearxngOptions {
+    /** 实例地址，例如 `https://searx.example.com` */
+    baseUrl?: string;
+}
+declare function createSearxngProvider(opts: SearxngOptions): SearchProvider;
+
+/**
+ * Tavily —— 专为 LLM 做的搜索 API（方案 37）。
+ *
+ * 选它做第一顺位是因为它返回的 `content` 本来就是**为模型准备的摘要**，
+ * 而不是搜索引擎那种带省略号的片段。同样一次搜索，模型判断「这条值不值得抓正文」
+ * 的准确率更高，于是二次 `web_fetch` 更少。
+ *
+ * key：`TAVILY_API_KEY`。
+ */
+
+interface TavilyOptions {
+    /** 不给就从 `TAVILY_API_KEY` 读 —— **每次读**，不缓存（见 provider.ts） */
+    apiKey?: string;
+}
+declare function createTavilyProvider(opts?: TavilyOptions): SearchProvider;
+
+/**
+ * Brave Search API（方案 37）。
+ *
+ * 有免费额度、隐私口碑好，是「不想把查询交给大厂」但又不想自建 SearXNG 时的选项。
+ *
+ * key：`BRAVE_SEARCH_API_KEY`。
+ */
+
+interface BraveOptions {
+    apiKey?: string;
+}
+declare function createBraveProvider(opts?: BraveOptions): SearchProvider;
+
+/**
+ * web_search —— 搜一串结果回来，**不抓正文**（方案 37）。
+ *
+ * ⚠️ 方案 37 的 md 2026-08-10 按去留规则删了，**而它没有独立的验收记录** ——
+ * 判据当时是搬进本文件这段头注释的（见 `.agents/plans/README.md` 那一轮的记账）。
+ * 也就是说这里就是真源，别再往方案 md 找。
+ *
+ * ## 为什么不顺手把正文也抓了
+ *
+ * 一次搜索 5 条结果，全抓正文轻松几万 token，而其中多半是模型看一眼摘要就会
+ * 丢掉的。分工是：`web_search` 给标题 + URL + 摘要，模型自己判断哪条值得看，
+ * 再调 `web_fetch`。工具描述里必须把这句话写出来，否则模型会期望这里直接给正文，
+ * 然后对着摘要抱怨内容不全。
+ *
+ * ## 搜索结果是**风险最高的一种**不可信内容
+ *
+ * `openWorldHint: true` 让 core 的 tool-executor 把输出包进
+ * `<tool_output untrusted="true">`。这不是走个形式：搜索结果是攻击者可以**主动
+ * 投放**的内容（SEO 投毒 + 提示注入），比读到一个仓库里的 README 危险得多。
+ * 结果里的 URL **不自动跟随** —— 模型要抓时走 `web_fetch`，那条路有 SSRF 校验
+ * 和 `network` 权限判定，一道都不会因为「这是搜出来的」而放松。
+ *
+ * ## 失败不炸轮
+ *
+ * 配额用尽 / key 错了 / 网络不通 —— 全部返回一条**说明为什么**的失败结果，
+ * 而不是抛异常。模型收到「搜索不可用：配额用尽」之后可以接着干别的；
+ * 抛出去的话这一轮就断在这儿了。
+ *
+ * ## 刻意不记搜索次数（方案 37 的一个明确决定）
+ *
+ * 原方案有一条「搜索调用次数进 `epoch status`」，**没做，也不打算做**：
+ * 那要在 runtime 上再挂一个计数器、穿过装配层递到 CLI，而它的收益
+ * （用户知道自己这轮搜了几次）远小于那条接线的常驻成本。
+ * 真需要按次计费或配额告警时，`Telemetry` 那条通道本来就是干这个的
+ * —— 工具调用已经有 `TOOL_CALL_COUNT` 指标，按工具名一分就是搜索次数，
+ * 不用为它单开一条链路。
+ */
+
+interface WebSearchDeps {
+    provider: SearchProvider;
+    /** 一次返回几条的缺省值，来自 `config.search.maxResults` */
+    defaultMaxResults?: number;
+}
+/** 给用例用：清掉缓存 */
+declare function clearSearchCache(): void;
+/** 造一个绑定了具体后端的 `web_search` 执行函数 */
+declare function createWebSearchExec(deps: WebSearchDeps): (args: Record<string, unknown>, ctx: ToolContext) => Promise<ToolResult>;
+
+declare const webPlugin: EpochPlugin;
+/**
+ * `web_search` 工具（方案 37）。
+ *
+ * **不在 `webPlugin.tools` 里**，因为它是有条件的：没有可用的搜索后端时
+ * 压根不该注册（见 `search/registry.ts` 的文件头）。装配层挑到后端才调这个工厂，
+ * 形状与 `createTodoTool` / `createMemoryTool` 那几个条件工具一致。
+ */
+declare function createWebSearchTool(provider: SearchProvider, opts?: {
+    defaultMaxResults?: number;
+}): EpochTool;
+
+export { SearchError, type SearchOptions, type SearchOutcome, type SearchProvider, type SearchResult, type SearchSelection, clearSearchCache, createBraveProvider, createSearchProvider, createSearxngProvider, createTavilyProvider, createWebSearchExec, createWebSearchTool, selectSearchProvider, webPlugin };

package/dist/index.js

@@ -0,0 +1,743 @@
+// src/utils/html-to-markdown.ts
+function htmlToMarkdown(html) {
+  let cleaned = html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<meta[^>]*>/gi, "").replace(/<!--[\s\S]*?-->/g, "");
+  cleaned = cleaned.replace(
+    /<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi,
+    (_, n, text) => "\n\n" + "#".repeat(Number(n)) + " " + stripTags(text).trim() + "\n\n"
+  );
+  cleaned = cleaned.replace(
+    /<p[^>]*>([\s\S]*?)<\/p>/gi,
+    (_, text) => "\n\n" + stripTags(text).trim() + "\n\n"
+  );
+  cleaned = cleaned.replace(/<br\s*\/?>/gi, "\n");
+  cleaned = cleaned.replace(/<a[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, (_, url, text) => {
+    const t = stripTags(text).trim();
+    return t ? `[${t}](${url})` : url;
+  });
+  cleaned = cleaned.replace(
+    /<img[^>]*src="([^"]*)"[^>]*alt="([^"]*)"[^>]*>/gi,
+    (_, url, alt) => `![${alt}](${url})`
+  );
+  cleaned = cleaned.replace(/<img[^>]*src="([^"]*)"[^>]*>/gi, (_, url) => `![](${url})`);
+  cleaned = cleaned.replace(/<(strong|b)[^>]*>([\s\S]*?)<\/(strong|b)>/gi, "**$2**");
+  cleaned = cleaned.replace(/<(em|i)[^>]*>([\s\S]*?)<\/(em|i)>/gi, "*$2*");
+  cleaned = cleaned.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, "`$1`");
+  cleaned = cleaned.replace(
+    /<pre[^>]*>[\s\S]*?<code[^>]*>([\s\S]*?)<\/code>[\s\S]*?<\/pre>/gi,
+    (_, code) => "\n```\n" + decodeEntities(code).trim() + "\n```\n"
+  );
+  cleaned = cleaned.replace(
+    /<li[^>]*>([\s\S]*?)<\/li>/gi,
+    (_, text) => "- " + stripTags(text).trim() + "\n"
+  );
+  cleaned = cleaned.replace(/<ol[^>]*>([\s\S]*?)<\/ol>/gi, (_, listContent) => {
+    let i = 1;
+    return listContent.replace(
+      /<li[^>]*>([\s\S]*?)<\/li>/gi,
+      (_2, text) => `${i++}. ` + stripTags(text).trim() + "\n"
+    );
+  });
+  cleaned = stripTags(cleaned);
+  cleaned = decodeEntities(cleaned);
+  cleaned = cleaned.replace(/\n{3,}/g, "\n\n").trim();
+  return cleaned;
+}
+function htmlToText(html) {
+  return stripTags(
+    html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<br\s*\/?>/gi, "\n")
+  ).replace(/&nbsp;/g, " ").replace(/\n{3,}/g, "\n\n").trim();
+}
+function stripTags(html) {
+  return html.replace(/<[^>]*>/g, "");
+}
+function decodeEntities(text) {
+  return text.replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ");
+}
+
+// src/utils/url-safety.ts
+import { lookup } from "dns/promises";
+import { isIP } from "net";
+var ALLOWED_PROTOCOLS = ["http:", "https:"];
+var BLOCKED_IPV4 = [
+  /^0\./,
+  // 当前网络 / 未指定
+  /^10\./,
+  // class A private
+  /^127\./,
+  // loopback
+  /^169\.254\./,
+  // link-local（含云元数据 169.254.169.254）
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  // class B private
+  /^192\.0\.0\./,
+  // IETF protocol assignments
+  /^192\.0\.2\./,
+  // TEST-NET-1
+  /^192\.168\./,
+  // class C private
+  /^198\.1[89]\./,
+  // benchmark
+  /^198\.51\.100\./,
+  // TEST-NET-2
+  /^203\.0\.113\./,
+  // TEST-NET-3
+  /^2(2[4-9]|3\d)\./,
+  // 224-239 组播
+  /^2(4[0-9]|5[0-5])\./,
+  // 240-255 保留 / 广播
+  /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./
+  // 100.64/10 CGNAT
+];
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "localhost",
+  "localhost.localdomain",
+  "ip6-localhost",
+  "ip6-loopback",
+  // 云元数据端点
+  "metadata.google.internal",
+  "metadata.goog",
+  "metadata",
+  "instance-data",
+  // 常见的「解析到回环」的公共域名，用来绕过主机名检查
+  "localtest.me",
+  "lvh.me",
+  "vcap.me"
+]);
+var BLOCKED_SUFFIXES = [".localhost", ".local", ".internal", ".localtest.me", ".lvh.me"];
+function isBlockedIPv6(addr) {
+  const a = addr.toLowerCase().replace(/^\[|\]$/g, "");
+  if (a === "::" || a === "::1") return true;
+  if (/^fe[89ab][0-9a-f]:/.test(a)) return true;
+  if (/^f[cd][0-9a-f]{2}:/.test(a)) return true;
+  const mapped = a.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/);
+  if (mapped && mapped[1]) return isBlockedIPv4(mapped[1]);
+  return false;
+}
+function isBlockedIPv4(addr) {
+  return BLOCKED_IPV4.some((p) => p.test(addr));
+}
+function isBlockedAddress(addr) {
+  const v = isIP(addr);
+  if (v === 4) return isBlockedIPv4(addr);
+  if (v === 6) return isBlockedIPv6(addr);
+  return false;
+}
+function checkUrlSafety(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { safe: false, reason: "\u65E0\u6548 URL" };
+  }
+  if (!ALLOWED_PROTOCOLS.includes(parsed.protocol)) {
+    return { safe: false, reason: `\u7981\u6B62\u534F\u8BAE: ${parsed.protocol}` };
+  }
+  if (parsed.username || parsed.password) {
+    return { safe: false, reason: "URL \u4E0D\u5141\u8BB8\u5305\u542B\u7528\u6237\u540D/\u5BC6\u7801" };
+  }
+  const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, "").replace(/\.$/, "");
+  if (!host) return { safe: false, reason: "\u7F3A\u5C11\u4E3B\u673A\u540D" };
+  if (BLOCKED_HOSTNAMES.has(host)) {
+    return { safe: false, reason: `\u7981\u6B62\u8BBF\u95EE\u672C\u5730/\u5143\u6570\u636E\u4E3B\u673A: ${host}` };
+  }
+  if (BLOCKED_SUFFIXES.some((s) => host.endsWith(s))) {
+    return { safe: false, reason: `\u7981\u6B62\u8BBF\u95EE\u5185\u90E8\u57DF: ${host}` };
+  }
+  if (isIP(host) !== 0 && isBlockedAddress(host)) {
+    return { safe: false, reason: `\u7981\u6B62\u8BBF\u95EE\u79C1\u6709/\u4FDD\u7559\u5730\u5740: ${host}` };
+  }
+  return { safe: true };
+}
+async function checkUrlSafetyAsync(url) {
+  const sync = checkUrlSafety(url);
+  if (!sync.safe) return sync;
+  const host = new URL(url).hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (isIP(host) !== 0) return sync;
+  try {
+    const records = await lookup(host, { all: true, verbatim: true });
+    for (const r of records) {
+      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`
+        };
+      }
+    }
+  } catch {
+    return sync;
+  }
+  return sync;
+}
+
+// src/tools/web-fetch.ts
+var MAX_SIZE = 5 * 1024 * 1024;
+var MAX_REDIRECTS = 5;
+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";
+  if (format2 === "text") return "text/plain;q=1.0, text/html;q=0.9";
+  return "text/html;q=1.0";
+}
+async function fetchWithSafeRedirects(startUrl, init) {
+  let current = startUrl;
+  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`;
+      return { error: `${where}: ${safety.reason}` };
+    }
+    const response = await fetch(current, { ...init, redirect: "manual" });
+    if (response.status >= 300 && response.status < 400) {
+      const location = response.headers.get("location");
+      if (!location) return { response, finalUrl: current };
+      await response.arrayBuffer().catch(() => void 0);
+      let next;
+      try {
+        next = new URL(location, current).toString();
+      } catch {
+        return { error: `\u91CD\u5B9A\u5411\u5730\u5740\u65E0\u6CD5\u89E3\u6790: ${location}` };
+      }
+      current = next;
+      continue;
+    }
+    return { response, finalUrl: current };
+  }
+  return { error: `\u91CD\u5B9A\u5411\u8D85\u8FC7 ${MAX_REDIRECTS} \u8DF3\uFF0C\u5DF2\u653E\u5F03` };
+}
+async function execWebFetch(args, _ctx) {
+  const url = String(args["url"] || "").trim();
+  if (!url) return fail(5001, "URL \u4E0D\u80FD\u4E3A\u7A7A");
+  const format2 = args["format"] || "markdown";
+  const timeout = Math.min(args["timeout"] || 30, 120) * 1e3;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeout);
+  try {
+    const headers = {
+      "User-Agent": BROWSER_UA,
+      Accept: acceptFor(format2),
+      "Accept-Language": "en-US,en;q=0.9"
+    };
+    const first = await fetchWithSafeRedirects(url, { signal: controller.signal, headers });
+    if ("error" in first) return fail(5002, first.error);
+    let { response } = first;
+    const { finalUrl } = first;
+    if (response.status === 403 && response.headers.get("cf-mitigated") === "challenge") {
+      const retry = await fetchWithSafeRedirects(finalUrl, {
+        signal: controller.signal,
+        headers: { "User-Agent": "epoch-agent/1.0", Accept: "text/html" }
+      });
+      if ("error" in retry) return fail(5002, retry.error);
+      response = retry.response;
+    }
+    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)");
+    const body = await readCapped(response, MAX_SIZE);
+    if (body === null) return fail(5004, "\u54CD\u5E94\u8FC7\u5927 (exceeds 5MB limit)");
+    const raw = new TextDecoder().decode(body);
+    const isHtml = contentType.includes("text/html") || raw.includes("<html") || raw.includes("<HTML");
+    let output;
+    if (isHtml) {
+      output = format2 === "text" ? htmlToText(raw) : htmlToMarkdown(raw);
+    } else {
+      output = raw.slice(0, 5e4);
+    }
+    const title = extractTitle(raw, isHtml);
+    const prefix = finalUrl !== url ? `> \u6700\u7EC8\u5730\u5740: ${finalUrl}
+
+` : "";
+    return {
+      success: true,
+      output: prefix + (title ? `# ${title}
+
+${output}` : output),
+      duration: 0
+    };
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      return fail(5005, "\u8BF7\u6C42\u8D85\u65F6");
+    }
+    return fail(5006, `\u7F51\u7EDC\u9519\u8BEF: ${err instanceof Error ? err.message : String(err)}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function readCapped(response, max) {
+  if (!response.body) {
+    const buf = new Uint8Array(await response.arrayBuffer());
+    return buf.byteLength > max ? null : buf;
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let total = 0;
+  for (; ; ) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (!value) continue;
+    total += value.byteLength;
+    if (total > max) {
+      await reader.cancel().catch(() => void 0);
+      return null;
+    }
+    chunks.push(value);
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+function fail(code, message) {
+  return { success: false, output: "", error: { code, message }, duration: 0 };
+}
+function extractTitle(html, isHtml) {
+  if (!isHtml) return void 0;
+  const m = html.match(/<title[^>]*>([\s\S]*?)<\/title>/i);
+  return m && m[1] ? m[1].trim().slice(0, 200) : void 0;
+}
+
+// src/search/provider.ts
+var SearchError = class extends Error {
+  constructor(message, status) {
+    super(message);
+    this.status = status;
+    this.name = "SearchError";
+  }
+  status;
+};
+async function searchFetch(url, init, who) {
+  let response;
+  try {
+    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} \u8FDE\u4E0D\u4E0A\uFF1A${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);
+  }
+  try {
+    return await response.json();
+  } catch {
+    throw new SearchError(`${who} \u7684\u54CD\u5E94\u4E0D\u662F\u5408\u6CD5 JSON`);
+  }
+}
+function str(obj, key) {
+  if (typeof obj !== "object" || obj === null) return "";
+  const value = obj[key];
+  return typeof value === "string" ? value : "";
+}
+function toResult(raw, keys) {
+  const url = str(raw, keys.url);
+  if (!url) return null;
+  const publishedAt = keys.date ? str(raw, keys.date) : "";
+  return {
+    title: str(raw, keys.title) || url,
+    url,
+    snippet: str(raw, keys.snippet),
+    ...publishedAt ? { publishedAt } : {}
+  };
+}
+
+// src/tools/web-search.ts
+var DEFAULT_MAX_RESULTS = 5;
+var HARD_MAX_RESULTS = 20;
+var TIMEOUT_MS = 2e4;
+var MAX_SNIPPET = 500;
+var cache = /* @__PURE__ */ new Map();
+function clearSearchCache() {
+  cache.clear();
+}
+function cacheKey(sessionId, query, opts) {
+  return `${sessionId}\0${query.trim().toLowerCase()}\0${JSON.stringify(opts)}`;
+}
+function format(results, ignored) {
+  const lines = results.map((r, i) => {
+    const date = r.publishedAt ? ` \xB7 ${r.publishedAt}` : "";
+    const snippet = r.snippet.length > MAX_SNIPPET ? `${r.snippet.slice(0, MAX_SNIPPET)}\u2026` : r.snippet;
+    return `${i + 1}. ${r.title}${date}
+   ${r.url}
+   ${snippet}`;
+  });
+  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 tail = ignored.length > 0 ? [`
+\u6CE8\u610F\uFF1A${ignored.join("\uFF1B")}`] : [];
+  return [head, "", ...lines, ...tail].join("\n");
+}
+function stringArray(value) {
+  if (!Array.isArray(value)) return void 0;
+  const out = value.filter((v) => typeof v === "string" && v.trim().length > 0);
+  return out.length > 0 ? out : void 0;
+}
+function createWebSearchExec(deps) {
+  return async function execWebSearch(args, ctx) {
+    const started = Date.now();
+    const query = String(args["query"] ?? "").trim();
+    if (!query) {
+      return {
+        success: false,
+        output: "",
+        error: { code: 5101, message: "\u67E5\u8BE2\u8BCD\u4E0D\u80FD\u4E3A\u7A7A" },
+        duration: 0
+      };
+    }
+    const requested = Number(args["maxResults"]);
+    const maxResults = Math.min(
+      Number.isFinite(requested) && requested > 0 ? Math.floor(requested) : deps.defaultMaxResults ?? DEFAULT_MAX_RESULTS,
+      HARD_MAX_RESULTS
+    );
+    const recency = Number(args["recencyDays"]);
+    const options = {
+      maxResults,
+      ...Number.isFinite(recency) && recency > 0 ? { recencyDays: Math.floor(recency) } : {},
+      ...stringArray(args["domains"]) ? { domains: stringArray(args["domains"]) } : {},
+      ...stringArray(args["excludeDomains"]) ? { excludeDomains: stringArray(args["excludeDomains"]) } : {}
+    };
+    const key = cacheKey(ctx.sessionId, query, options);
+    const cached = cache.get(key);
+    if (cached) {
+      return {
+        success: true,
+        output: format(cached, ["\u672C\u6B21\u7ED3\u679C\u6765\u81EA\u672C\u4F1A\u8BDD\u7F13\u5B58\uFF0C\u672A\u91CD\u65B0\u8054\u7F51"]),
+        duration: Date.now() - started
+      };
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+    try {
+      const outcome = await deps.provider.search(query, { ...options, signal: controller.signal });
+      cache.set(key, outcome.results);
+      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`,
+          duration: Date.now() - started
+        };
+      }
+      return {
+        success: true,
+        output: format(outcome.results, outcome.ignored ?? []),
+        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)}`;
+      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"
+        },
+        duration: Date.now() - started
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+
+// src/search/brave.ts
+var ENDPOINT = "https://api.search.brave.com/res/v1/web/search";
+var MAX_RESULTS = 20;
+function createBraveProvider(opts = {}) {
+  const key = () => (opts.apiKey ?? process.env["BRAVE_SEARCH_API_KEY"] ?? "").trim();
+  return {
+    name: "brave",
+    unavailableReason() {
+      return key() ? null : "\u7F3A\u5C11 BRAVE_SEARCH_API_KEY\uFF08\u5728 https://brave.com/search/api \u7533\u8BF7\u540E\u5199\u8FDB ~/.epoch/.env\uFF09";
+    },
+    async search(query, options) {
+      const url = new URL(ENDPOINT);
+      url.searchParams.set("q", buildQuery(query, options));
+      url.searchParams.set("count", String(Math.min(options.maxResults, MAX_RESULTS)));
+      const freshness = toFreshness(options.recencyDays);
+      if (freshness) url.searchParams.set("freshness", freshness);
+      const json = await searchFetch(
+        url.toString(),
+        {
+          headers: {
+            Accept: "application/json",
+            "Accept-Encoding": "gzip",
+            "X-Subscription-Token": key()
+          },
+          ...options.signal ? { signal: options.signal } : {}
+        },
+        "brave"
+      );
+      const web = json.web;
+      const raw = Array.isArray(web?.results) ? web.results : [];
+      const results = [];
+      for (const item of raw) {
+        const hit = toResult(item, {
+          title: "title",
+          url: "url",
+          snippet: "description",
+          date: "age"
+        });
+        if (hit) results.push(hit);
+        if (results.length >= options.maxResults) break;
+      }
+      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");
+      }
+      return { results, ...ignored.length > 0 ? { ignored } : {} };
+    }
+  };
+}
+function buildQuery(query, opts) {
+  const parts = [query];
+  for (const d of opts.domains ?? []) parts.push(`site:${d}`);
+  for (const d of opts.excludeDomains ?? []) parts.push(`-site:${d}`);
+  return parts.join(" ");
+}
+function toFreshness(days) {
+  if (days === void 0 || days <= 0) return void 0;
+  if (days <= 1) return "pd";
+  if (days <= 7) return "pw";
+  if (days <= 31) return "pm";
+  if (days <= 366) return "py";
+  return void 0;
+}
+
+// src/search/searxng.ts
+function createSearxngProvider(opts) {
+  return {
+    name: "searxng",
+    unavailableReason() {
+      if (!opts.baseUrl?.trim()) {
+        return "searxng \u9700\u8981\u81EA\u5EFA\u5B9E\u4F8B\u5730\u5740\uFF08epoch config set search.baseUrl https://\u4F60\u7684\u5B9E\u4F8B\uFF09";
+      }
+      try {
+        const url = new URL(opts.baseUrl);
+        if (url.protocol !== "http:" && url.protocol !== "https:") {
+          return `searxng \u7684 baseUrl \u5FC5\u987B\u662F http(s)\uFF0C\u73B0\u5728\u662F ${url.protocol}`;
+        }
+      } catch {
+        return `searxng \u7684 baseUrl \u4E0D\u662F\u5408\u6CD5 URL\uFF1A${opts.baseUrl}`;
+      }
+      return null;
+    },
+    async search(query, options) {
+      const base = opts.baseUrl.replace(/\/+$/, "");
+      const url = new URL(`${base}/search`);
+      url.searchParams.set("q", buildQuery2(query, options));
+      url.searchParams.set("format", "json");
+      const range = timeRange(options.recencyDays);
+      if (range) url.searchParams.set("time_range", range);
+      const body = await searchFetch(
+        url.toString(),
+        {
+          headers: { Accept: "application/json" },
+          ...options.signal ? { signal: options.signal } : {}
+        },
+        "searxng"
+      ).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",
+            403
+          );
+        }
+        throw err;
+      });
+      const raw = Array.isArray(body.results) ? body.results : [];
+      const results = [];
+      for (const item of raw) {
+        const hit = toResult(item, {
+          title: "title",
+          url: "url",
+          snippet: "content",
+          date: "publishedDate"
+        });
+        if (hit) results.push(hit);
+        if (results.length >= options.maxResults) break;
+      }
+      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");
+      }
+      return { results, ...ignored.length > 0 ? { ignored } : {} };
+    }
+  };
+}
+function buildQuery2(query, opts) {
+  const parts = [query];
+  for (const d of opts.domains ?? []) parts.push(`site:${d}`);
+  for (const d of opts.excludeDomains ?? []) parts.push(`-site:${d}`);
+  return parts.join(" ");
+}
+function timeRange(days) {
+  if (days === void 0 || days <= 0) return void 0;
+  if (days <= 1) return "day";
+  if (days <= 7) return "week";
+  if (days <= 31) return "month";
+  if (days <= 366) return "year";
+  return void 0;
+}
+
+// src/search/tavily.ts
+var ENDPOINT2 = "https://api.tavily.com/search";
+var MAX_RESULTS2 = 20;
+function createTavilyProvider(opts = {}) {
+  const key = () => (opts.apiKey ?? process.env["TAVILY_API_KEY"] ?? "").trim();
+  return {
+    name: "tavily",
+    unavailableReason() {
+      return key() ? null : "\u7F3A\u5C11 TAVILY_API_KEY\uFF08\u5728 https://tavily.com \u7533\u8BF7\u540E\u5199\u8FDB ~/.epoch/.env\uFF09";
+    },
+    async search(query, options) {
+      const body = {
+        query,
+        max_results: Math.min(options.maxResults, MAX_RESULTS2),
+        // `basic` 而不是 `advanced`：后者贵一倍，而我们本来就不要正文 ——
+        // 模型看完 snippet 自己去 web_fetch
+        search_depth: "basic"
+      };
+      if (options.recencyDays !== void 0 && options.recencyDays > 0) {
+        body["days"] = Math.ceil(options.recencyDays);
+      }
+      if (options.domains?.length) body["include_domains"] = options.domains;
+      if (options.excludeDomains?.length) body["exclude_domains"] = options.excludeDomains;
+      const json = await searchFetch(
+        ENDPOINT2,
+        {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+            // Bearer 而不是 body 里的 api_key 字段：后者是旧写法，
+            // 且会让 key 出现在任何记录了请求体的地方
+            Authorization: `Bearer ${key()}`
+          },
+          body: JSON.stringify(body),
+          ...options.signal ? { signal: options.signal } : {}
+        },
+        "tavily"
+      );
+      const raw = Array.isArray(json.results) ? json.results : [];
+      const results = [];
+      for (const item of raw) {
+        const hit = toResult(item, {
+          title: "title",
+          url: "url",
+          snippet: "content",
+          date: "published_date"
+        });
+        if (hit) results.push(hit);
+        if (results.length >= options.maxResults) break;
+      }
+      return { results };
+    }
+  };
+}
+
+// src/search/registry.ts
+var AUTO_ORDER = ["tavily", "brave", "searxng"];
+function createSearchProvider(type, config) {
+  if (type === "searxng") {
+    return createSearxngProvider(config?.baseUrl ? { baseUrl: config.baseUrl } : {});
+  }
+  return type === "brave" ? createBraveProvider() : createTavilyProvider();
+}
+function selectSearchProvider(config) {
+  const explicit = config?.provider;
+  if (explicit) {
+    const provider = createSearchProvider(explicit, config);
+    const reason = provider.unavailableReason();
+    return reason ? { provider: null, detail: `\u914D\u7F6E\u6307\u5B9A\u4E86 ${explicit}\uFF0C\u4F46${reason}` } : { provider, detail: `\u4F7F\u7528 ${explicit}` };
+  }
+  const tried = [];
+  for (const type of AUTO_ORDER) {
+    const provider = createSearchProvider(type, config);
+    const reason = provider.unavailableReason();
+    if (!reason) return { provider, detail: `\u81EA\u52A8\u9009\u7528 ${type}\uFF08\u6309\u51ED\u636E\u63A2\u6D4B\uFF09` };
+    tried.push(reason);
+  }
+  return {
+    provider: null,
+    // 把三家各自缺什么都列出来：用户多半只想配一家，让他自己挑最方便的那个
+    detail: `\u672A\u914D\u7F6E\u641C\u7D22\u540E\u7AEF\uFF0Cweb_search \u672A\u6CE8\u518C\u3002\u53EF\u9009\uFF1A${tried.join("\uFF1B")}`
+  };
+}
+
+// src/index.ts
+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",
+  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",
+      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" }
+        },
+        required: ["url"]
+      },
+      // `openWorldHint: true` 不只是元数据：core 的 tool-executor 用它决定
+      // 要不要把输出包进 `<tool_output untrusted="true">`。抓来的网页内容
+      // 作者既不是用户也不是我们，必须标成「数据」而不是「指令」回灌上下文。
+      annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+      operation: "network",
+      // 审批目标是 URL —— 五候选里没有 `url`，不给 describeTarget 就只能退回
+      // 参数 JSON，「批准抓这个站」下次照样弹窗
+      describeTarget: (args) => String(args["url"] ?? ""),
+      execute: execWebFetch
+    }
+  ]
+};
+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`,
+    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" },
+        domains: {
+          type: "array",
+          items: { type: "string" },
+          description: '\u53EA\u5728\u8FD9\u4E9B\u57DF\u540D\u91CC\u641C\uFF0C\u4F8B\u5982 ["nodejs.org"]'
+        },
+        excludeDomains: { type: "array", items: { type: "string" }, description: "\u6392\u9664\u8FD9\u4E9B\u57DF\u540D" }
+      },
+      required: ["query"]
+    },
+    // `openWorldHint: true` 是这里最重要的一行：core 的 tool-executor 用它决定
+    // 要不要把输出包进 `<tool_output untrusted="true">`。搜索结果是攻击者
+    // **可以主动投放**的内容（SEO 投毒 + 提示注入），是不可信内容里风险最高的一种。
+    // `idempotentHint: false` —— 同一个词今天明天搜出来的东西不一样
+    annotations: { readOnlyHint: true, idempotentHint: false, openWorldHint: true },
+    operation: "network",
+    // 审批目标是查询词而不是参数 JSON：`terminal` 那边批准的是命令，
+    // 这边批准的就该是「搜这个词」
+    describeTarget: (args) => String(args["query"] ?? ""),
+    execute: createWebSearchExec({ provider, ...opts })
+  };
+}
+export {
+  SearchError,
+  clearSearchCache,
+  createBraveProvider,
+  createSearchProvider,
+  createSearxngProvider,
+  createTavilyProvider,
+  createWebSearchExec,
+  createWebSearchTool,
+  selectSearchProvider,
+  webPlugin
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@epoch-agent/plugin-web",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Web 抓取插件 — URL 安全校验 + HTML→Markdown + SSRF 防护",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ddbor/epoch-agent.git"
+  },
+  "license": "Apache-2.0",
+  "author": "epoch-agent",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@epoch-agent/protocol": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}