# 网页搜索 MCP v1（oh-my-pi 模式，Python 实现） 目标：给 codex 任务一个可用的 `web_search` / `web_fetch`， 不把 oh-my-pi 的 TypeScript 代码原样搬过来（codex 认不出 pi 的工具），只复用它的模式：统一工具 + provider 抽象 + `auto` 链式回退 + 抓取转干净文本。 ## 文件 - `cloud/websearch.py`：provider 链、抓取、codex-home 播种 助手。纯标准库，无第三方依赖，这样它能不经 pip 安装就 在宿主和 Docker 容器里跑。 - `cloud/websearch_mcp.py`：stdio JSON-RPC MCP 服务器， 只做协议帧，逻辑全在 websearch.py。日志只写 stderr， stdout 是 JSON-RPC 流，绝不能混日志。 - `cloud/tests/test_websearch_mcp.py`：12 个单测，全部 mock HTTP，不联网、不需要真实 key。 - `cloud/tests/test_code_search.py`：编程作用域与抽取回退链 的单测，同样全部 mock HTTP、不联网、不需要真实 key。 - `cloud/tests/test_code_search_ext.py`：任务级 `allowed_hosts` 扩展的单测（指定 / 未指定 / 点边界 / 空值与非法值 / Perplexity 超 20 域 / MCP 透传）。 - `cloud/tests/test_websearch_paid_freeze.py`：付费冻结单测 （默认 auto 无付费后端、SearXNG 失败不回落付费、显式 pin 仍工作、解冻开关关时不变 / 开时恢复旧链、 DuckDuckGo 兜底失败报错清晰、超时报错清晰；全部 mock HTTP，不联网、不需要真实 key）。 - `cloud/tests/test_js_heavy_extract.py`：JS 重型页面 抽取评估的 mock 单测（直接抓取壳-only、provider 抽取 补与不补、回退语义；live SearXNG 烟囱默认跳过）。 ## 工具 - `web_search(query, limit=5, provider="auto", scope="general")`：返回 `{provider, results:[{title, url, snippet, score?}], answer?, attempted, scope}`， `scope="code"` 时另带 `code_domains`。 `answer` 只有 provider 本身给合成答案时才有（目前是 Perplexity Sonar）；其它 provider 的总结仍由主模型做。 `scope` 详见下面“编程搜索 scope=code”一节。 - `web_fetch(url, char_limit=15000)`：走 `fetch_best` 抽取回退链 （Tavily extract → Exa contents → 直接抓取），返回 `{url, title, text, links, truncated, source}`（`source` 为 `tavily-extract` / `exa-contents` / `direct-fetch`）。 超长按头 75% + 尾 25% 截断并标 `[TRUNCATED]`；只接受 http(s)，拒绝 localhost 与字面私有 IP；抽取与直接抓取都失败时报错，不伪造页面。 ## Provider 链：默认冻结，显式 pin 与显式解冻除外 冻结语义（本轨起，默认 `auto` 只走免费路线，顺序固定）： 1. `searxng`：`GET $SEARXNG_URL/search?format=json`，需自托管 实例且 JSON 格式已打开。默认参数：`engines=bing,360search` （2026-10-30 主机实测：默认 general 类别 20.0s 撞超时， pinned 两引擎 0.47s；`SEARXNG_ENGINES` 可覆盖，空值恢复 不 pin）。`SEARXNG_URL` 在代码里无默认值：未配时该后端 直接报 `searxng not configured (SEARXNG_URL unset)`，链 只剩 DuckDuckGo；生产值 `http://searx.diante.me` 来自主 机 env（见“生产接线”），不在代码里写死；主机 env 实测 仅有 `SEARXNG_URL` 这一行、无 `SEARXNG_ENGINES` 行， 所以默认 pin（bing,360search）生效。注意是 http 不是 https：主机 nginx 只听 80、无 443 vhost，https 会在 TLS 层证书主机名不匹配失败，根本到不了 SearXNG。 2. `duckduckgo`：解析 `https://html.duckduckgo.com/html/`， 免 key 兜底，布局漂移时只会返回空结果并继续走链， 不会把工具打崩；但它在两种出口下都不可作可用兜底： 本 VM 直连回 202 + 机器人挑战页、0 条，主机 Tinyproxy 路径约 25 秒超时。兜底失败时记为 `no results` / 超时并 如实报错，不伪造结果；因此 SearXNG 挂时冻结默认链可能 以诚实失败告终，这是已知边界，不是静默降级。 冻结保证：即使环境里配了付费 key，默认 auto 也绝不调用 Perplexity / Exa / Tavily / Brave、绝不产生付费花费； SearXNG 失败后默认也不回落到付费后端，只走 DuckDuckGo。 付费后端的代码、测试、文档一律保留，未删除。 显式 pin 仍工作：`provider="tavily"` / `"exa"` / `"perplexity"` / `"brave"` 显式指定时照常调用，这是用户 有意的覆盖，不是默认行为；pin 失败不回退（与冻结前一致）。 解冻开关：`WEBSEARCH_ENABLE_PAID=1`（且仅精确值 `1`， `true` / `yes` / `0` 都不算开，默认关）时，默认 auto 恢复旧链，顺序为 Perplexity → Exa → Tavily → Brave → SearXNG → DuckDuckGo（旧链里只试有 key 的付费后端 + 已配 URL 的 SearXNG + DuckDuckGo）。解冻是显式动作， 会产生付费花费，绝不能被默认链静默触发；开关走 worker 环境透传进 MCP config env（见“生产接线”）。 旧链各后端（解冻后 / 显式 pin 时）的请求形态不变： 1. `perplexity`：`POST https://api.perplexity.ai/chat/completions`， 模型 `sonar`，`Authorization: Bearer $PERPLEXITY_API_KEY`。 返回合成答案 + `search_results` / `citations`。 2. `exa`：`POST https://api.exa.ai/search`，头 `x-api-key`， `type: auto`，`contents.text.maxCharacters: 2000` + `highlights: true`。 3. `tavily`：`POST https://api.tavily.com/search`， `Authorization: Bearer $TAVILY_API_KEY`， `search_depth: basic`，`include_answer: false`（工具只返 结果，总结留给模型）。 4. `brave`：`GET https://api.search.brave.com/res/v1/web/search`， 头 `X-Subscription-Token`，`extra_snippets: true`。 规则：任一后端 HTTP 失败或 0 结果都继续下一个；全部失败 返回各后端错误（不含 key）。超时失败报 `timeout after Ns waiting for HTTP response`（N 为 `WEBSEARCH_TIMEOUT`，默认 20 秒），并记在该后端的 attempted 条目里，绝不把超时写成“无结果”或空答案。 `WEBSEARCH_TIMEOUT`（秒，默认 20）改单次超时。另注意： 旧文档曾写可用 `WEBSEARCH_PROVIDERS` 改默认链顺序， 代码里从未实现该变量，本轨已删此说法（不另新加该变量， 保持改动最小）。 ## 接入 codex（测试项目做法） codex 从 codex-home 的 `config.toml` 读 MCP 配置： ```toml [mcp_servers.websearch] command = "python3" args = ["/path/to/codex-home/websearch_mcp.py"] ``` `ensure_codex_home_websearch(codex_home_dir, command_args=...)` 会把 `websearch.py` / `websearch_mcp.py` 拷进该 codex-home， 并在缺失时追加上面这段（已有 section 绝不重写；key 绝不 写进 config.toml，key 只走 MCP 进程的环境变量）。 注意：同一个 config.toml 不能同时装宿主路径和容器路径， Docker 租户必须传容器内路径 `/var/lib/codex-app-server/codex-home/websearch_mcp.py`， 因为该目录正是租户 codex-home 的容器内挂载点。 ## 生产接线（worker + egress + 自托管 SearXNG） - worker 自动播种：`cloud/worker.py --websearch-mcp`（默认关）。 开启后 `_tenant_dirs` 在播种 config.toml 之后调播种助手， 写容器内路径 `/var/lib/codex-app-server/codex-home/websearch_mcp.py`。 老租户下一次任务自动合并（`_tenant_dirs` 每次派发都调到）， 已有 section 不重写。autoscaler unit 已加 `--websearch-mcp`， 但 unit 文件不在 deploy tar 里，主机上须单独 scp + daemon-reload + restart autoscaler 才生效（见部署教训）。 - egress 白名单：`deploy/egress/tinyproxy-filter` 已加 Perplexity、Exa、Tavily、Brave、DuckDuckGo 与 `searx.diante.me`（精确匹配，不用 diante.me 通配，否则 任务经代理也能摸到 api.diante.me 控制面；filter 行即 `^searx\.diante\.me$`，本轨不改这行）。主机上须把 该文件拷到 `/etc/tinyproxy/tinyproxy-filter` 并重载 tinyproxy，重载后先验中转域名还通，再验新域名。 - 自托管 SearXNG（公开子域名路）：主机 Docker 跑 `searxng/searxng`，经 nginx（仅听 80，无 443 vhost、无 证书）反代到 `searx.diante.me`，MCP 侧 `SEARXNG_URL=http://searx.diante.me` 走 worker 进程 环境（`/etc/codex-app-server/env`）继承到 codex 再到 MCP，不写进 config.toml。`WEBSEARCH_ENABLE_PAID` 同理 走 worker 的 search_env 透传进 `[mcp_servers.websearch.env]` （worker 代码已含该键）；主机侧改 env 文件后需重启相关 unit 才生效——那是部署动作，不在本轨。公开实例的代价是可能被外人 刷：SearXNG limiter 保持开启，JSON 格式是 MCP 要用的 唯一格式。未加域名进白名单之前，Docker 任务的搜索 会被代理 403 挡住（fail closed，工具报错，不会静默绕过）。 - 付费后端实测：付费后端只以 mock 响应验证了请求 字段与结果映射，未用真实 key 跑过；上生产前须用真实 key 在测试项目跑一遍，再谈默认链顺序是否合理。 ## 编程搜索 scope=code（v2 新增，只做编程任务搜索） 选型：`web_search` 加 `scope="code"` 参数，不另立 `code_search` 工具。理由：同一条 provider 链、同一套 回退与 key 规则，只多一层域名限定；另立工具会复制 schema、handler 与播种文档两套，且调用方要在两个 工具间二选一。代码（`cloud/websearch.py` 的 `CODE_SEARCH_DOMAINS` / `search(..., scope=...)`）、 MCP 工具描述（`cloud/websearch_mcp.py` 的 `web_search` 描述与 `scope` enum）与本文三处一致， 只有 `general` / `code` 两个值，未知 scope 在发任何 HTTP 之前就报 `ValueError`，绝不静默退化成无限定搜索。 ### 允许域清单（实际落代码的 15 个，含子域名） - 官方文档：`docs.python.org`、`nodejs.org`、`go.dev`、 `pkg.go.dev`、`docs.rs`、`doc.rust-lang.org`、 `developer.mozilla.org` - 代码托管：`github.com`、`githubusercontent.com` （GitHub 自己的 raw host，blob 页之外原始文件所用） - 包仓库：`pypi.org`、`npmjs.com`、`crates.io` - 问答与安全：`stackoverflow.com`、`nvd.nist.gov`、`cve.org` 匹配规则是域名本身或其子域名（点边界匹配： `gist.github.com` 算、`evilgithub.com` 不算）。 changelog / release notes 只有落在上述域名时才在 范围内（例如项目在 GitHub 的 Releases 页）；没有 “项目官方域名自动识别”——不在清单里的项目官网 （如某框架自己的 docs 站）本版不返回，这是明确的 缺口，不是泛化成任意站的口子。 ### 不在范围清单（scope=code 下一律过滤掉） 通用新闻、购物、社交、地点、机票酒店、天气、行情、 视频/图片站、博客聚合与其它任意站。`scope="code"` 不是“优先编程来源”，是硬过滤：非清单域的结果不 返回、不降级展示，只在 `attempted` 里记 `domain_filtered_out` 数量。 ### 各后端如何限定（先核实请求字段再写代码） - 原生支持，直接传：Tavily `include_domains`、 Exa `include_domains`、Perplexity Sonar chat completions 的顶层 `search_domain_filter`（上限 20 个域，本清单 15 个，整单可传）。 - 原生不支持，不编造参数：Brave 网页搜索端点没有 `include_domains` 参数（多域 `site:` 改写语义未经 证实，不改写查询），SearXNG / DuckDuckGo 同样不传； 这三家只靠 `search()` 返回后的统一事后过滤。 - 双保险：原生限定的后端返回后同样再过一次事后 过滤，所以各后端在 code 作用域下的语义一致。 - 链语义：某后端结果被全部滤掉时，该后端记为 “no results”（`code-domain filter removed all N results`），链继续走下一个后端；全部后端都空才 报错。 ### 清单外项目官网域：任务级显式扩展 `allowed_hosts` 这不是“任意站搜索”，仍是显式白名单机制，只是白名单 可以由调用方在当次调用里显式加域。选型是任务级参数 `(a)`，不是配置级扩展清单 `(b)`，理由：改动最小 （只动 `search()` 签名与 MCP 透传，不动 worker、 unit、env、播种与主机配置）；按调用隔离（某任务要 某项目官网，不会把该域放宽给所有任务——配置级清单 一旦写入就是全局放宽，安全姿态更差）；用完即弃 （不持久化，下次调用不带就不生效）。 用法：`search(..., scope="code", allowed_hosts=["docs.example-project.dev"])`，MCP 侧 `web_search` 的 `allowed_hosts` 数组字段同名透传。 规则（全部由 `cloud/websearch.py` 的 `_normalize_allowed_hosts` 在发任何 HTTP 之前强制）： - 只在 `scope="code"` 下生效；`scope="general"` 下传 `allowed_hosts` 直接报 `ValueError`，绝不静默忽略； 不传时行为与本版之前完全一致（仍是 15 域）。 - 生效清单 = 内置 15 域 + 本次显式 extras（去重、保序）； 返回结果的 `code_domains` 即为该生效清单。 - 匹配仍是点边界：子域名算（`api.docs.example-project.dev` 算），`evildocs.example-project.dev` 与 `docs.example-project.dev.evil.com` 都不算。 - 空值 / 非法值报错不静默退化：`[]`、裸字符串 （可迭代但不是域名列表）、`*` 通配、带 scheme / 端口 / 路径 / userinfo 的值、前导点、空标签、非字符串 元素、以及全部等于内置域（即“扩展了个寂寞”）都报 `ValueError`，且此时尚未发任何 HTTP。 - 扩展值绝不写进日志：错误串与 `attempted` 条目里不 出现扩展值；扩展值只出现在调用方自己那次结果的 `code_domains` 回显里（调用方自己指定的值回显给 自己，不是日志）。 - 与原生后端限定方式的关系，和现有逻辑一致：原生 支持的后端（Tavily / Exa 的 `include_domains`）直接传 生效清单；Perplexity 的 `search_domain_filter` 上限 20 个域，内置 15 + 扩展超 20 时跳过其原生过滤、只靠 事后过滤（事后过滤永远是权威，语义不变）；原生不 支持的后端（Brave、SearXNG、DuckDuckGo）本来就不传 参数，只靠 `search()` 返回后的统一事后过滤。 - `web_fetch` 不受 `allowed_hosts` 影响：fetch 本来就是 按指定 URL 抓取，没有域名白名单可扩展。 ### 抓取回退链与 403 语义（web_fetch） `web_fetch` 实际调 `fetch_best`，顺序固定： 1. Tavily extract（`POST https://api.tavily.com/extract`， `urls:[url]`，取 `results[0].raw_content`；空结果或 `failed_results` 命中都算失败）——只在配了 `TAVILY_API_KEY` 时试。 2. Exa contents（`POST https://api.exa.ai/contents`， `ids:[url]` + `text.maxCharacters`，取 `results[0].text`， 无 text 时取 highlights 拼接；空算失败）——只在 配了 `EXA_API_KEY` 时试。 3. 直接抓取（旧 `fetch_url` 的 HTML 清洗与截断）。 抽取与直接都失败时，错误同时写明两边失败，不伪造 页面。无任何抽取 key 时 `fetch_via_provider` 单独调会 明确报“no extract provider configured”，但 `fetch_best` 会直接走直接抓取（与旧 web_fetch 行为一致），不是 报错。localhost / 私有 IP 在抽取之前就拒绝，不会经 抽取商去探内网。 403 语义：抽取走的是搜索商 API 域名（`tavily.com`、 `exa.ai`，已在 Tinyproxy 白名单里），不直接碰目标站， 所以文档站本身不在白名单时抽取仍可通；只有回退到 直接抓取时，目标域不在白名单才会被代理 403 挡住。 这是 fail-closed：报错、不静默绕过、不承诺“任意 文档站都能直接抓”。本轨**没有改** `deploy/egress/tinyproxy-filter`（也不改主机上的文件）： 若将来主机侧要让直接抓取也通，需另行走主机变更， filter 行须用 POSIX BASIC 正则（`^\(.*\.\)*域名$`）、 文件 644，extended 锚定写法会把允许域也挡成 403 （见部署教训）；该变更不在本轨授权内。 ### 安全与隔离（不变） - key 只走 MCP 进程环境变量，绝不写进 config.toml、 日志、测试、文档；本轨测试用的 key 全是 `*-SECRET-*` 假值。 - worker 开关默认关；租户播种幂等、已有 section 不重写；Docker 环境变量走 extra_env + `[mcp_servers.websearch.env]` 路径。 - `web_fetch` 仍只接受 http(s)、拒 localhost 与私有 IP，且它不是沙箱边界（danger-full-access 任务本 来就能 curl）。 - 老租户注意：播种助手从不覆盖内容已变的租户脚本 （既有防覆盖规则），所以 scope 只对新播种的租户 立即生效；老租户拿到新脚本需另行决策，不在本轨 改动该规则。 ## 诚实边界 - 本批只做代码 + 单测 + 测试租户目录的配置合并验证， 未推分支、未建 PR、未合并、未部署、未改生产 worker 与 egress 配置、未跑真实 codex 任务。 - 付费冻结本轨同样只在本地提交里：生产默认链要等部署 新代码后才变；解冻开关在主机上默认仍是关（除非主机 env 显式设为 `WEBSEARCH_ENABLE_PAID=1`，且那需要 主机侧改 env + 重启 unit，属部署动作）。 - DuckDuckGo 的 HTML 解析是兜底手段，布局一变就可能 0 结果；它存在的意义是“没 key 也能走通链路”，不是 长期依赖的搜索后端。实测（2026-10-28，VM 出口）： html / lite 端点均回 202 + 机器人挑战页（anomaly）， 不是解析器 bug——在这个出口下免 key 搜索实际不通， 免 key 可用性最终要靠自托管 SearXNG 或付费后端。 - `web_fetch` 不是安全边界：danger-full-access 的任务 本来就能 curl，fetch 只挡了最明显的非 http(s) 与 本地私有地址，不应把它当沙箱用。 - 编程搜索本轨未做（见回执）：真实 key 的 live 测试、 主机 unit / filter / env 接线、GitHub API token （本设计走网页搜索后端限定域名，不调 GitHub API， 所以不需要 token；真要 GitHub 代码内容搜索 API 是 另一功能，不在本轨）、老租户脚本升级。清单外项目 官网域本轨已做（见上节 `allowed_hosts`，本地提交、 未推未部署），仍缺真实 key 的 live 验证。 ## JS 重型站点抽取效果评估（本轨新增，mock 为主） 评估对象是已有抽取链，不改默认抽取顺序、不因评估换 后端：`fetch_best` 固定为 Tavily extract → Exa contents → 直接抓取。结论只写在这里，不改代码行为。 测试文件：`cloud/tests/test_js_heavy_extract.py`（全部 mock HTTP，只有一个显式开关的 live 烟囱测试，默认跳过）。 ### 阶段 1：直接抓取能拿到什么、拿不到什么 直接抓取是标准库 HTML 解析：`