多源网页搜索 Tannnnhauser/pivot-web-search

Pivot Web Search

面向 MCP 宿主、命令行和宿主适配器的弹性多服务商网页搜索与页面提取。

这是什么？

Pivot Web Search 通过三种接口，对外提供同一套搜索、抓取和配置服务：

- MCP 服务器（pivot-web-search-mcp）—— 供 Claude Code 以及任何支持 MCP 的宿主使用
- 命令行（pivot-web-search）—— 供人和 shell 脚本使用，不需要 AI 宿主
- JSON 桥接（pivot-web-search-bridge）—— 面向适配器的宿主中立子进程接口

它把每个查询路由到多个服务商，结果质量差或某个服务商宕机时自动故障转移，跟踪配额与健康状况，并在本地提取页面内容 —— 不依赖 Anthropic API，因此在 Amazon Bedrock 和其他 API 服务商上都能用。Claude Code 插件和可选的 DeepSeek Harness 适配器提供针对宿主的安装方式；采用 Pivot 从不需要修改宿主源码。

DuckDuckGo 无需 API key 即可使用；加上带 API 的服务商（Tavily、Brave、Gemini）能提升可靠性。

选择你的接口

| 你的使用场景… | 从这里开始 |
| Claude Code | 安装插件 |
| Codex | 安装插件 |
| 其他 MCP 宿主（Cursor、Claude Desktop……） | 配置 pivot-web-search-mcp |
| 终端 / 脚本 / CI | 安装并运行命令行 |
| DeepSeek Harness | 安装运行时 + DSH 包 |

核心特性

- 一套运行时，三种接口 —— 同一套搜索/抓取/配置服务支撑 MCP、命令行和 JSON 桥接。
- 多服务商故障转移 —— 按配额感知路由；跳过结果质量差或配额耗尽的服务商，保留部分结果作为兜底。
- 超级模式 —— 并行查询所有服务商，按 URL 去重，按跨服务商一致度排序。
- 本地页面提取 —— 通过 trafilatura 获取完整内容，带 Next.js/Nuxt.js SPA 兜底方案和可选的 JS 渲染器。
- 配置热重载 —— 通过 YAML 增删、重排服务商和代理；改动在下一个请求生效。
- 可操作的诊断信息 —— 全部失败时，给出每个服务商的失败原因和建议，而不是笼统报错。

某个 API 不可用、被限流、被封锁或配额耗尽时，单服务商搜索就会失败。Pivot 把每个请求路由到已配置的服务商，保留可用的部分结果，并通过 MCP、命令行和适配器友好的 JSON 暴露一致的行为。

前置条件

- uv —— 自动管理 Python 和依赖（每种接口都用它）。
- 至少一个搜索服务商（DDG 无需 API key）。
推荐： 至少配置一个免费 API key —— Tavily（每月 1000 credits，无需信用卡）或 Brave（每月 1000 次查询，需要信用卡）。DDG 是免费兜底，但高频使用下可能不稳定。

各宿主的配置步骤见下方对应的 Quick Start。

Quick Starts

Claude Code 插件

Step 1 —— 添加 marketplace（只需一次）：

claude plugin marketplace add https://github.com/Tannnnhauser/pivot-web-search.git

Step 2 —— 安装：

claude plugin install pivot-web-search

插件会在安装时提示你填写配置：

| 设置项 | 说明 |
| Tavily API Key | 存入系统钥匙串。填上即可启用 Tavily（也可以从 shell 继承 TAVILY_API_KEY）。 |
| Brave Search API Key | 存入系统钥匙串。填上即可启用 Brave（也可以继承 BRAVE_API_KEY）。 |
| Gemini API Key | 存入系统钥匙串。填上即可启用 Gemini（也可以继承 GEMINI_SEARCH_API_KEY / GOOGLE_STUDIO_API_KEY）。 |
| Proxy URLs | 逗号分隔的代理列表，按顺序尝试。direct 始终作为最后的兜底追加在末尾 —— 想关掉它，改用 ~/.pivot-web-search/proxies.yaml。 |

你提供哪些 key，对应的服务商就自动启用；DDG 始终开启。路由顺序和超时来自智能默认值 —— 提供 key 的顺序不影响结果。随时可以用 claude plugin configure pivot-web-search 重新配置。

验证： 让 Claude Code 运行 WebSearchConfig，action 传 status —— 你应该能看到一份服务商健康报告。

Key 解析顺序与 macOS GUI 注意事项

对每个服务商的 key，插件按以下顺序读取：(1) 从 shell 继承的标准环境变量（如 TAVILY_API_KEY）—— 设了就优先用它 —— 然后 (2) /plugin UI 里填的值（以 PIVOT_USERCONFIG_TAVILY_API_KEY 注入）。想改用 UI 里的值，就在 shell 里 unset TAVILY_API_KEY。

macOS： 从 Spotlight 或 Dock 启动 Claude Code 时，它看不到 ~/.zshrc 里 export 的变量。请从终端启动，或者通过 /plugin UI 设置 key，或者把它们加到 ~/.claude/config.json 的 env 块里。

Codex 插件

添加同一个 GitHub marketplace，安装同一份插件包：

codex plugin marketplace add Tannnnhauser/pivot-web-search --ref main
codex plugin add pivot-web-search@pivot-web-search-plugin

安装后新开一个 Codex 聊天。以后升级版本用：

codex plugin marketplace upgrade pivot-web-search-plugin

Codex 从上面列出的标准环境变量读取服务商 key。没有 key 也能用 DDG；~/.pivot-web-search/ 下的高级服务商与代理配置对所有宿主通用。

MCP 宿主

任何支持 MCP 的宿主（Claude Code、Claude Desktop、Cursor……）都能直接用 uvx 跑起服务端 —— 不用 clone，不用 venv。加到你的 .mcp.json：

{
"mcpServers": {
"pivot-web-search": {
"command": "uvx",
"args": [
"git+https://github.com/Tannnnhauser/pivot-web-search.git#subdirectory=plugins/pivot-web-search"
],
"env": {
"TAVILY_API_KEY": "tvly-...",
"BRAVE_API_KEY": "BSA...",
"GEMINI_SEARCH_API_KEY": "AI..."
}
}
}
}

用 @v1.1.0 锁定版本：

git+https://github.com/Tannnnhauser/pivot-web-search.git@v1.1.0#subdirectory=plugins/pivot-web-search

服务商与代理的高级配置放在 ~/.pivot-web-search/.yaml（见 Configuration），对所有启动方式都生效。

命令行

安装后的包会提供 pivot-web-search，这是面向人的命令，底层服务和 MCP 工具一致——可以在终端、脚本或 CI 里用，不必经过 AI 宿主。用 uv 单独安装： sh
uv tool install 'git+https://github.com/Tannnnhauser/pivot-web-search.git@v1.1.0#subdirectory=plugins/pivot-web-search'
sh
pivot-web-search search "latest Python release" --format json
pivot-web-search fetch https://example.com --format md
pivot-web-search config status

search 参数：

| 参数 | 默认值 | 说明 |
| --max-results | 5 | 结果数量（1–10，加 --super 时为 1–20） |
| --provider | auto | 按名称强制指定已配置的服务商 |
| --super | 关闭 | 并行查询所有服务商 |
| --news | 关闭 | 搜索新闻，而非通用网页 |
| --timelimit | — | d / w / m / y 时效过滤 |
| --include-answer | 关闭 | 支持时附带 AI 回答 |
| --search-depth | basic | basic 或 advanced（Tavily） |
| --topic | general | general 或 news（Tavily） |
| --days | — | 把新闻限制在最近 N 天 |
| --include-domains | — | 域名白名单 |
| --exclude-domains | — | 域名黑名单 |
| --include-content | 关闭 | 返回预先抓取的页面内容（Brave LLM Context） |
| --max-content-tokens | 8192 | --include-content 的 token 预算 |
| --region | wt-wt | DDG 地区（仅命令行；MCP 无对应项） |
| --format | md | md 或 json |

fetch（别名 extract）：--query（给 JS 渲染器的相关性提示）、--max-chars（按 URL 截断）、--format（默认 json，或 md）。

config：位置参数为动作，status（默认）或 reload。

DeepSeek Harness

可选的 pivot-web-search-dsh Profile Bundle 把 Pivot 注册为 DSH 现有的 web_search 和 web_fetch 服务商，走的是 DSH 已发布的 Bundle、ctx.web 和 ctx.subprocess API。模型看到的仍是 DSH 的标准工具——不会多出一套 Pivot 专用工具。宿主集成使用公开扩展 API；适配器不需要 fork DSH，也不用改源码。

安装运行时和 Bundle： sh
uv tool install 'git+https://github.com/Tannnnhauser/pivot-web-search.git@v1.1.0#subdirectory=plugins/pivot-web-search'
dsh plugin --profile web add pivot-web-search-dsh
添加 Bundle 后重启配置档。它会选服务商 pivot 作为 searchProvider/fetchProvider，并启用 DSH 的 tool-web 入口（随附的 web 配置档默认禁用它）。用 dsh --profile web --dump-config 验证 —— 你应该看到 searchProvider: pivot、fetchProvider: pivot、启用的 tool-web，以及 pivot-web-search-provider。

cordis.patch.yml 会显式转发服务商密钥（TAVILY_API_KEY、BRAVE_API_KEY、GEMINI_SEARCH_API_KEY、GOOGLE_STUDIO_API_KEY，外加 PIVOT_WEB_SEARCH_PROXIES）；~/.pivot-web-search/ 下的配置文件会被直接读取。

自定义服务商： 桥接子进程只接收 cordis.patch.yml 中列出的环境变量 —— 它不继承父 shell。如果自定义服务商的 api_key_env 指向的密钥不在上面的列表里（比如自托管网关的 token），把该变量加到 Bundle 的 env 块，否则它到不了桥接进程。

开发环境的安装与卸载步骤见 integrations/deepseek-harness/。

配置

Pivot 默认走自动检测 —— 提供 API 密钥（UI 或 shell 环境变量），匹配的服务商就会启用，并带上智能路由默认值。常见场景不需要 YAML。

进阶场景可以把 YAML 放进 ~/.pivot-web-search/：

| 文件 | 用途 |
| providers.yaml | 接管服务商配置：SearXNG、自定义 JSON API、LLM 搜索服务商、显式优先级 |
| proxies.yaml | 接管代理配置：SOCKS5、强制代理（不回退直连）、按代理设置优先级 |

优先级按文件整体生效，全有或全无： 文件一旦存在，该部分的自动检测就被跳过 —— 你需要把想要的条目全部列出（包括 DDG）。模板在 examples/。

~/.pivot-web-search/providers.yaml

服务商按优先级依次尝试（数值越小越先）。同优先级的服务商会做对冲 —— 并发查询、错开启动，第一个高质量结果胜出。不写显式 priority 时，按类型套用智能默认值。
yaml
providers:
- name: tavily
type: tavily
api_key_env: TAVILY_API_KEY

- name: brave
type: brave
api_key_env: BRAVE_API_KEY

- name: gemini
type: gemini
api_key_env: GEMINI_SEARCH_API_KEY
model: gemini-2.5-flash

- name: ddg
type: ddg

Self-hosted SearXNG

- name: searxng-local

type: searxng

endpoint: "http://localhost:8888/search"

Generic JSON API (Serper, Google CSE, etc.) — multiple instances allowed,

each with independent priority, quota tracking, and circuit-breaker state.

- name: serper

type: json_api

endpoint: "https://google.serper.dev/search"

api_key_env: SERPER_API_KEY

method: POST

request_body:

q: "{{query}}"

num: "{{max_results}}"

response_mapping:

results_path: "organic"

title: "title"

url: "link"

snippet: "snippet"

智能默认优先级（未显式指定 priority 时）：
| 类型 | 优先级 | 超时 |
| llm_search | 10 | 15s |
| tavily / brave / gemini | 20 | 4s / 4s / 20s |
| searxng / json_api | 30 | 6s |
| ddg | 90 | 6s |

注意： llm_search 服务商优先级为 10，排在 Tavily/Brave 前面，超时 15s，所以每次查询都可能要 15s 以上。如果延迟比答案质量更重要，把它的 priority 调到 20 以上。

LLM 搜索服务商（type: llm_search）

适用于任何自带联网搜索 grounding 的模型（Perplexity Sonar Pro、带 web_search 的 OpenAI、SAP AI Core 等）。这类服务商返回 AI 答案，外加引用的 URL。通过 ~/.pivot-web-search/providers.yaml 配置（模板见 examples/providers.yaml）。

chat_completions —— 任何兼容 /chat/completions 且自带搜索的端点： yaml
- name: sonar-pro
type: llm_search
api_format: chat_completions
endpoint: "https://api.perplexity.ai/chat/completions"
model: sonar-pro
api_key_env: PERPLEXITY_API_KEY
timeout: 15

解析响应时按顺序尝试：search_results（Perplexity/Sonar）、带 type: url_citation 的 annotations（OpenAI Chat Completions），然后是顶层 citations。

responses —— 使用 web_search 工具的 OpenAI Responses API（/responses）： yaml
- name: gpt-web-search
type: llm_search
api_format: responses
endpoint: "https://api.openai.com/v1/responses"
model: gpt-4o
api_key_env: OPENAI_API_KEY
timeout: 45
search_tool: web_search
search_context_size: medium

通用字段：

| 字段 | 是否必填 | 说明 |
| api_format | 否 | chat_completions（默认）或 responses |
| endpoint | 是 | API 端点的完整 URL |
| model | 是 | 模型标识符 |
| api_key_env | 是 | 存放 API key 的环境变量（以 Bearer token 发送） |
| max_tokens | 否 | 响应最大 token 数（默认：500 / responses 为 4000） |
| timeout | 否 | 请求超时秒数（默认：30） |
| system_prompt | 否 | 系统提示词（仅 chat_completions） |
| headers | 否 | 额外的请求头 |
| web_search_options | 否 | 额外的搜索选项（仅 chat_completions） |

gemini 类型内部同样是 LLM 搜索（Google Search grounding），但为了向后兼容和双 key 回退，仍保留 type: gemini。

~/.pivot-web-search/proxies.yaml

这个文件一旦存在就完全接管配置 —— 安装时填的 Proxy URLs 字段会被忽略，direct 也不会自动追加（这是强制走代理场景的逃生通道）。
yaml
proxies:
- name: direct
url: null # null = direct connection
enabled: true
priority: 1

- name: myproxy1
url: "http://myproxy1.example:8080"
enabled: true
priority: 2

SOCKS5 (requires PySocks: uv pip install pysocks)

- name: ssh-tunnel

url: "socks5://127.0.0.1:1080"

enabled: true

priority: 3

config/fetch.yaml

控制 WebFetch 的行为，包括 JS 渲染回退：yaml js_renderer: none # none (default), "playwright", or "tavily" max_chars: 100000 # content truncation limit

如果网站重度依赖 JavaScript，把 js_renderer 设为 playwright（需要先跑 uv sync --extra browser）。

MCP 工具参考

通过 MCP 调用时，工具名会加前缀：mcp__pivot-web-search__WebSearch、mcp__pivot-web-search__WebFetch、mcp__pivot-web-search__WebSearchConfig。

WebSearch

| 参数 | 类型 | 默认值 | 说明 |
| query | str | 必填* | 搜索关键词 |
| provider | str | "auto" | 强制指定服务商：auto / ddg / tavily / brave / gemini / searxng，或任何已注册的名字 |
| super_mode | bool | false | 并行查询所有服务商 |
| max_results | int | 5 | 1–10（super 模式下 1–20） |
| allowed_domains | list[str] | null | 只保留这些域名下的结果 |
| blocked_domains | list[str] | null | 排除这些域名下的结果 |
| news | bool | false | 搜新闻而不是搜网页 |
| timelimit | str | null | d / w / m / y |
| include_answer | bool | false | AI 生成的答案摘要（Tavily） |
| include_content | bool | false | 预先抓好的页面内容（Brave LLM Context） |
| max_content_tokens | int | 8192 | include_content=true 时的 token 预算（1024–32768） |
| search_depth | str | "basic" | basic 或 advanced —— advanced 消耗 2 倍额度（Tavily） |
| topic | str | "general" | general 或 news（Tavily） |
| days | int | null | 只保留最近 N 天的新闻（Tavily） |

WebFetch

| 参数 | 类型 | 默认值 | 说明 |
| url | str / list[str] | 必填 | 要抓取的 URL。HTTP 会自动升级为 HTTPS。传多个 URL 即进入批量模式。 |
| query | str | null | 可选的相关性查询，供 JS 兜底渲染器使用 |
| max_chars | int | null | 把输出截断到这个字符数（默认：100,000） |

行为： 每个 URL 缓存 15 分钟 · 识别并拒绝二进制内容 · 跨主机跳转安全（跳转前拦截） · SPA 兜底（__NEXT_DATA__ / RSC payload / __NUXT_DATA__）。

WebSearchConfig

| 参数 | 类型 | 默认值 | 说明 |
| action | str | "status" | status —— 服务商健康状态、配额、配置来源；reload —— 热重载 YAML |

status 会返回服务商健康状态、各服务商的配额，以及配置来源标注，告诉你每项设置来自哪里（环境变量、YAML 路径，还是内置默认值）。

路由与故障转移怎么工作

Request
│
├─ normal mode: priority-group routing
│ ┌─ Group 1 (priority 10): LLM Search (Perplexity, OpenAI, etc.)
│ ├─ Group 2 (priority 20): Tavily + Brave + Gemini ← hedged (200ms stagger, first quality-gate pass wins)
│ ├─ Group 3 (priority 30): SearXNG / json_api
│ └─ Group 4 (priority 90): DDG (free exhaustion fallback)
│
│ Gates: quota-exhausted → skip | circuit-open → skip | affinity mismatch → skip
│ 质量门禁（3 层）：AI 回答 ≥40 字符？→ 唯一 URL ≥2？→ 关键词重叠？
│ 熔断器：连续失败 3 次 → OPEN（冷却 60s）→ HALF_OPEN → 探测 │ └─ super 模式： Tavily ┐ Brave ┤ 并行（跳过已耗尽）→ 去重 → 按服务商数量排序 Gemini ┤ DDG ┘

每个服务商独立尝试所有已配置代理（direct → myproxy1 → …），按主机缓存并持久化到 ~/.cache/pivot-web-search/。

配额管理

用量跨会话跟踪，存放在 ~/.cache/pivot-web-search/quota.json：

| 服务商 | 跟踪方式 | 免费额度 | 详情 |
| DuckDuckGo | 不跟踪 | 无限 | 免费，无需 API key |
| Tavily | API 同步 | 1000 credits/月 | 启动时调用 GET /usage 获取真实 credit 数据 |
| Brave | 响应头 | 滚动 30 天窗口 | 解析 X-RateLimit-Remaining / X-RateLimit-Reset |
| Gemini | 本地（每日） | 不定（PT 午夜重置） | 通过 PIVOT_WEB_SEARCH_GEMINI_QUOTA 设置上限 |

配额感知调度会跳过用量达 100% 的服务商；日历翻页时重置。

架构

三个接口共用同一套服务：

MCP server ─┐
CLI ────────┼─→ search / fetch / config services ─→ provider registry ─→ providers
JSON bridge ┘ (DDG/Tavily/Brave/Gemini/SearXNG/json_api/llm_search)

- server.py — FastMCP 适配器（3 个 MCP 工具）· cli.py — 命令行适配器 · machine_bridge.py — 主机无关的 JSON 适配器
- search_service.py / fetch_service.py / config_service.py — 权威编排 · presentation.py — Markdown/JSON 投影
- routing.py / quality_gate.py — 优先级分组路由、对冲、熔断器 · backends.py / extraction.py / http_client.py — 服务商 I/O、提取、代理故障转移
- providers/ — 适配器基类、6 个内置实现、mtime 热重载注册表 · quota.py / config.py — 跨会话配额、YAML 热重载

Claude Code 插件载荷位于 plugins/pivot-web-search/；DSH 适配器位于 integrations/deepseek-harness/（绝不修改 DSH 源码）；YAML 模板位于 examples/。

测试 sh
uv sync # install workspace + dev deps
uv run pytest -m "not integration" -q # 364 offline tests
uv run pytest -m integration -vv # 7 live network/API tests
uv run pytest # all 371 Python tests
uv run python scripts/codex-plugin-smoke.py # Codex install, skill discovery, cached MCP handshake
npm --prefix integrations/deepseek-harness test
(cd integrations/deepseek-harness && npm pack --dry-run)
npm --prefix integrations/deepseek-harness run test:dsh

本地开发 Claude Code：claude --plugin-dir /path/to/pivot-web-search/。

故障排查启用调试日志 —— 设置 PIVOT_WEB_SEARCH_DEBUG=1；带时间戳的日志会写入 ~/.cache/pivot-web-search/server.log。

所有服务商都返回不了结果 —— 运行 WebSearchConfig 的 status 动作（或 pivot-web-search config status），检查服务商健康状况和当前生效的配置来源。确保至少有一个服务商持有有效密钥（或者 DDG 可以访问）。

macOS 上出现 SSL 证书错误 —— 插件使用 certifi；如果错误依旧：uv sync --upgrade-package certifi。

DuckDuckGo 触发限流（403） —— 连续失败后，熔断器会跳过 DDG 60 秒，然后探测恢复。想要稳定，就配置一个带 API 的服务商。

trafilatura 提取结果为空 —— 有些 JS 密集的站点需要渲染器。在 config/fetch.yaml 里设置 js_renderer: playwright，然后执行 uv sync --extra browser && playwright install chromium。

方案对比

| 特性 | Pivot Web Search | 单服务商 MCP 工具 | 内置 WebSearch |
| 多服务商故障转移 | 4 家以上服务商，自动回退 | 单点故障 | Bedrock 上不可用 |
| 配额管理 | 跨会话跟踪 | 无 | 不适用 |
| 超级模式（并行） | 同时调用所有服务商 | 无法实现 | 不适用 |
| 本地内容提取 | trafilatura + SPA 回退 | 通常是 Tavily Extract | Anthropic 托管 |
| 接口 | MCP + 命令行 + JSON 桥接 | 仅 MCP | 仅内置 |
| 在 Bedrock 上可用 | 是 | 是 | 否 |
| 可自托管 | 是 | 视情况而定 | 否 |

许可证

Apache-2.0