codex-app-server/docs/web-search-mcp.md

网页搜索 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 配置：

[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 解析：<script> / <style> / <noscript> 内容一律剥离，只留静态文本与绝对 http(s) 链接（相对链接不进 links 列表）。所以：

• 能拿到：静态壳里的标题、占位文本（如 "Loading…"）、 静态正文、绝对链接；首屏静态内容本身就是正文的页面 不受影响。
• 拿不到：正文靠 JS 渲染的段落（mock 壳里 RENDERED-BODY-PARAGRAPH 只存在于 <script> 数据块 中，直接抓取结果里没有它，也不把数据块原文泄漏进 文本）；分页靠 JS 加载的后续项（mock 里第 2 页 ITEM-PAGE-2 只经 /api/items?page=2 到达，直接抓取 只有第 1 页静态项，也拿不到该 API 地址本身）。
• 为什么：解析器没有 JS 引擎，也从不执行脚本或追 JS 发起的请求；这是结构性缺失，不是解析器 bug， 调解析参数补不回来。直接抓取在 JS 重型站上只能 给出“壳 + 首屏静态部分”，不能谎称是全文。

阶段 2：provider 抽取在 mock 层面能补什么、补不了什么

mock 层面（伪造的 Tavily extract 响应返回完整渲染文本） 证明链路本身能补：fetch_via_provider 返回 source=tavily-extract 的完整文本；抽取与直接都失败时 fetch_best 回退到直接抓取的壳（source=direct-fetch）， 仍拿不到渲染正文——回退保证的是“不断链”，不是“补全文”。

mock 补不了、也证明不了的部分：

• 真实 provider 是否真的渲染该站的 JS（取决于各家 extract 实现是否跑无头浏览器、等多久、反爬策略）， mock 响应是“我假设它渲染了”，不是实测证据。
• JS 分页 / 交互（点“加载更多”、登录后内容、滚动加载） provider 抽取一般只取单 URL 的渲染结果，不会替调用方 翻页或交互；多页内容仍需逐 URL fetch。
• 抽取返回空时是失败，不是空页：fetch_via_provider 空结果报 WebSearchError，不伪造页面；但 fetch_best 随后回退直接抓取会返回壳文本——调用方须以 source 字段分辨“渲染全文”与“壳”，不能只看 text 非空就当全文。

Live 对照（与 mock 分开写，未验证的不写成已验证）

• 无 key 的 SearXNG 路线：旧 VM 测试曾用 SEARXNG_URL=https://searx.diante.me 失败（URLError: Remote end closed connection without response）——该失败 现已归因：https 是错的，主机 nginx 只听 80、无 443 vhost，https 在 TLS 层证书主机名不匹配失败，根本没到 SearXNG，不能据此断言服务挂了。2026-11-01 探针实测： http 经同一 Tinyproxy 0.34 秒回 200、16 条结果，服务 活着；主机 env 仅 SEARXNG_URL=http://searx.diante.me 一行、无 SEARXNG_ENGINES，默认 pin 生效。容器内真实 任务派发仍是 blocker（不由本轨创建生产任务），live 对照在该项上仍记为未完成；测试文件里的 live 烟囱 测试默认跳过，只在 WEBSEARCH_EVAL_LIVE_SEARXNG=1 且配了 SEARXNG_URL 时才跑。
• 付费后端 live 效果（Tavily extract / Exa contents / Perplexity / Brave 的真实 JS 渲染能力）：无 key，本轨 一律未验证，不编造效果，逐项列为 blocker（见回执）， 在拿到 key 之前，文档里关于 provider 渲染能力的任何 表述都只是 mock 层面的链路结论。