Skip to main content

agg-search

tests release license python

多引擎并行召回 + RRF 融合 + Jina 精排的搜索工具链:CLI + MCP server(stdio/HTTP)+ 分层抓取,宿主机零依赖(纯 Python 标准库)。

A multi-engine search stack for agents: parallel recall across eleven engines (three of them keyless domain sources), RRF fusion, listwise reranking, domain profiles, a local feedback loop, plus a tiered fetcher. Ships as a CLI and an MCP server — stdio, or streamable HTTP — with standard library only on the host.

agg-search terminal demo

真实一次运行的输出:7 个引擎返回结果,DeepSeek 因余额不足进入冷却、被跳过;空结果不阻塞其余引擎。


为什么又一个搜索聚合器

同类项目不少,但多数是「多引擎 + 简单合并」或「零 key 依赖单一索引」。这个项目的差异在六件事:

  1. DeepSeek 搜索/抓取是一等公民 —— 官方 /v1/tools/search 自带 rerank_score,/v1/tools/fetch 服务端取页直接给 Markdown,省掉容器。
  2. 抓取是阶梯而不是一个函数 —— DeepSeek Fetch → 静态 → 动态 → 反爬,逐级升级,跑在隔离容器里,宿主机不装浏览器。
  3. 排序是两阶段 —— RRF 粗排前 15,再交给 Jina Reranker v3.5 listwise 精排;模型不可用链式回退 v3 → v2,全失败则保留 RRF 顺序,绝不阻塞。
  4. 韧性层是显式的 —— 5 分钟结果缓存 + 15 分钟页面缓存、按错误类型分级的冷却(额度 1h / 反爬 10min / 超时 90s)、引擎健康与延迟上报,缺 key 的引擎提前剔除不占线程。
  5. 面向 Agent 的协议面 —— MCP 2025-06-18(含 outputSchema/structuredContent、tool annotations、版本协商)、stdio 与 streamable HTTP 两种传输、按调用计的硬超时与 notifications/cancelled、13 家客户端的配置生成器。
  6. 领域画像 + 本地反馈回路 —— --profile academic|code|news 换的是引擎组合、RRF 权重、默认时效与摘要长度(数据驱动,不改代码);search 记录哪些引擎召回了结果、fetch 记录哪些被真正读过,agg-search-tune 据此调整引擎权重,越用越贴合本机习惯。

架构

flowchart LR
  subgraph clients[Agent clients]
    CC[Claude Code]
    CX[Codex]
    CU[Cursor]
    VS[VS Code]
    OC[OpenCode]
  end
  CC & CX & CU & VS & OC -->|stdio JSON-RPC| M[agg-search-mcp]
  CC & CU & VS -->|streamable HTTP| H[agg-search-http]
  M --> Q
  H --> Q[query expansion<br/>local ollama]
  Q --> A[exa]
  Q --> B[brave]
  Q --> C[serper]
  Q --> D[deepseek]
  Q --> E[firecrawl]
  Q --> F[anysearch]
  Q --> G[tavily]
  Q --> Hh[searxng]
  Q --> OA[openalex]
  Q --> HN[hn]
  Q --> ST[stack]
  A & B & C & D & E & F & G & Hh & OA & HN & ST --> R[RRF fusion<br/>profile weights ×<br/>learned multipliers]
  R --> J[jina rerank v3.5<br/>fallback v3 → v2]
  J --> O[top N results<br/>+ provenance + health]
  O --> AN[optional cited answer]

安装

# PyPI(0.2.0 起)
uvx --from agg-search agg-search-mcp          # 不落盘,直接跑

# 或者装成常驻命令(6 个入口:3 个 CLI + MCP stdio/HTTP + 安装器)
uv tool install agg-search

源码方式:

git clone https://github.com/TsukimioRinka/agg-search
cd agg-search
uv pip install -e .
# 或者完全不安装:
PYTHONPATH=src python3 -m agg_search.search "query"

使用

# 搜索
agg-search "rust async runtime comparison" --top-n 10 --recency month

# 域名过滤:只留 arxiv/.edu,去掉 reddit
agg-search "speculative decoding" --include-domains arxiv.org,.edu \
  --exclude-domains reddit.com

# 机器可读输出(含引擎状态、延迟、冷却与过滤计数)
agg-search "MCP server examples" --json

# RAG-Fusion 查询扩展(需要本地 ollama)
agg-search "vector database tradeoffs" --expand 3

# 带引用的答案段(本地 ollama;--answer deepseek 走 API)
agg-search "what changed in Python 3.13" --answer

# 快速模式:单池扇出,最早两个有结果的引擎就返回
agg-search "breaking news" --fast --budget-secs 20

# 诊断:打印生效配置(密钥只显示布尔值),或列出可用引擎
agg-search --show-config
agg-search --help

# 抓取正文:DeepSeek Fetch 优先,失败落容器阶梯
crawl-fetch --url https://example.com/post --tier auto --out md

密钥只从环境变量读(也兼容 ~/.config/agent-env、~/.config/ai-keys.env 的 KEY= 行)。缺失的引擎会被跳过,不会让整次搜索失败。常用默认值可用 AGG_SEARCH_ENGINES、AGG_SEARCH_TOP_N、AGG_SEARCH_PER_ENGINE、AGG_SEARCH_SNIPPET_CHARS、AGG_SEARCH_FAST、AGG_SEARCH_NO_JINA、AGG_SEARCH_PROFILE、AGG_SEARCH_NO_LEARN 覆盖,命令行显式传参优先。完整变量表见 docs/environment.md。

MCP server

暴露两个工具:

工具 主要参数 说明
search query、top_n、recency、engines、profile、include_domains、exclude_domains、snippet_chars、expand、answer、fast、budget_secs、engine_timeout、no_jina 并行召回 + RRF + 精排;返回文本内容 + structuredContent
fetch urls、tier、out、text_limit、allow_private 分层抓取正文;每 URL 一条结果

协议行为:

  • 版本协商:2025-06-18 / 2025-03-26 / 2024-11-05,按客户端请求回选支持的版本。
  • 工具带 title、annotations(readOnlyHint、openWorldHint)和 outputSchema;支持结构化输出的客户端直接拿 structuredContent,老客户端仍拿文本。
  • 每个工具调用有硬墙钟(search 120s / fetch 300s),超时杀进程组;notifications/cancelled 同样会中断。
  • 工具调用在线程池里跑,ping/tools/list 不会被慢引擎卡住。
  • search 在 MCP 下默认 fast=true(有限的召回预算),fast=false 才等全部引擎。

一行接入

agg-search-install --list                     # 支持 13 家客户端
agg-search-install -c claude-code             # 打印 claude mcp add 命令
agg-search-install -c cursor --write          # 合并进 ~/.cursor/mcp.json(自动备份)
agg-search-install -c vscode --scope project  # 写 .vscode/mcp.json
agg-search-install -c cursor --check          # 校验文件、条目与运行时是否就绪

逐客户端的路径、JSON/TOML/YAML 片段与 GUI 环境变量陷阱见 docs/adapters.md。

HTTP 传输

agg-search-http --host 127.0.0.1 --port 8765 --path /mcp

多个客户端共用一个进程(共享缓存与冷却),默认只绑回环并校验 Host/Origin(防 DNS rebinding 与浏览器跨站请求),端点不带认证——对外必须先套反向代理。协议细节与 nginx 示例见 docs/http.md。

领域定向与每 agent 策略

agg-search "speculative decoding" --profile academic   # openalex 优先,摘要 500 字,top 15
agg-search "sqlite wal corrupt" --profile code         # stack 优先,摘要 600 字
agg-search "release notes" --profile news --top-n 5    # 默认 recency=day
agg-search --list-profiles

agg-search-install -c cursor --profile code --write    # 把某个客户端钉在 code 画像上

同一套数据也通过 MCP 暴露:工具参数 profile,或环境变量 AGG_SEARCH_PROFILE。优先级 flag > env > profile > 内置默认;openalex / hn / stack 三个新引擎全部免 key,装好就能用。

反馈回路

search 记录每个结果由哪些引擎召回,fetch 成功读到其中某个 URL 时记一次「被使用」。 agg-search-tune 把 surfaced/used 折算成 0.5–2.0 的引擎权重乘数(样本少于 30 时保持 1.0), 之后所有搜索自动叠加,并进入缓存键——调权重不会命中旧结果。默认开启,--no-learn 或 AGG_SEARCH_NO_LEARN=1 关闭。

agg-search-tune --show   # 反馈表 + 当前乘数
agg-search-tune          # 写入 ~/.config/agg-search/weights.json

只存哈希与计数,不存查询词、页面正文或原始 URL。机制与公式见 docs/profiles.md。

同类项目对比

只列能核实的能力,语言一列仅在仓库自述里明确时填写:

项目 栈 它强在哪 与本项目的差别
search-cli Rust 13 个 provider,单一二进制 本项目免编译;多容器抓取阶梯与 DeepSeek Fetch 是一等路径
web-search-mcp TypeScript 注入防御(<untrusted_content> 包裹 + 隐藏字符剥离)、PDF/RSS/YouTube 抽取、本地语义重排、Recall@5 / MRR@10 评测、MCP resources/prompts 它的内容抽取与提示注入防护比本项目完整;本项目的差异在 8 引擎并行 + RRF→Jina listwise、DeepSeek Search/Fetch、RAG-Fusion 与容器阶梯。SSRF 防护两边都有,本项目覆盖到抓取前置校验(见 docs/fetching.md)
argo — 300+ 来源、18 语言、MCP/CLI 本项目只做通用网页检索,覆盖面窄;差异在排序链路与成本控制更细
Tavily MCP TypeScript 托管远端端点、search/extract/map/crawl 四件套、DEFAULT_PARAMETERS 本项目可自带引擎、离线缓存与精排链,不绑定单一供应商
Brave MCP TypeScript 官方索引,HTTP 传输带 Origin/Host 白名单 本项目多引擎融合;传输层安全策略参考了它的做法
Exa MCP TypeScript 托管端点 + OAuth、dynamic highlights 本项目无托管依赖,密钥和缓存都在本机

测试

uv venv && uv pip install -e .
python3 -m unittest discover -s tests -v

140+ 个离线测试:域名过滤、RRF、冷却分类、缓存键、SSRF 判定、安装器、MCP 协议面与 stdio/HTTP 端到端(不发起网络请求、不消耗额度)。CI 覆盖 Python 3.10–3.13 + ruff。

安全与隐私

  • 仓库内不含任何密钥、账号、内网地址;.env.example 只有空占位。
  • 密钥只在进程环境里读取,不写日志、不落盘;--show-config 只输出布尔值。
  • 抓取前置 SSRF 校验:仅 http(s)、无 userinfo、私网/回环/链路本地/云元数据地址默认拒绝(--allow-private 显式放开);响应体上限 4 MiB。
  • 抓取在容器内执行,宿主机不留浏览器与爬虫依赖。
  • 进入模型上下文的页面文本会剥离零宽与双向控制字符(隐藏指令的常见载体),MCP 指令块也声明页面内容为不可信数据。
  • HTTP 传输默认回环绑定 + Host/Origin 白名单,无认证时不得裸奔到公网。

文档

文档 内容
docs/install.md 安装方式、环境变量全表、冒烟测试
docs/adapters.md 13 家客户端的接入配置
docs/http.md HTTP 传输、安全模型、反向代理
docs/profiles.md 领域画像、每 agent 策略、反馈回路与调参
docs/fetching.md 分层抓取的梯子与容器
docs/reranking.md RRF 与 Jina 精排、参数扫描
docs/environment.md 环境变量与计费说明

License

MIT

Metadata

Release files for agg-search 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agg-search 0.3.0
File Size Uploaded Provenance Actions
agg_search-0.3.0.tar.gz 78.8 kB Without provenance Details for agg_search-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agg-search 0.3.0
File Interpreter ABI Platform Actions
agg_search-0.3.0-py3-none-any.whl Python 3 none any Details for agg_search-0.3.0-py3-none-any.whl

Total release size: 137.0 kB

Release files / agg_search-0.3.0.tar.gz

Download URL agg_search-0.3.0.tar.gz
Size 78.8 kB
Tags Source
SHA-256 checksum
How to use checksums
ac1d75a458fa43a631fea8dceed55b87010c49687dbfefc1aad988fb469109b7
BLAKE2b-256 checksum
How to use checksums
2c8590bf65e958e772e3a7e71e55893a837a53250977156531404ada5f18ce20
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / agg_search-0.3.0-py3-none-any.whl

Download URL agg_search-0.3.0-py3-none-any.whl
Size 58.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
339516307e5131ca65af190cd344d67204bf1abe5fad234bcc5677f43a359a8d
BLAKE2b-256 checksum
How to use checksums
66ad7990a7097fcfe5deefb88c3b27bcbd19c5767c2e94854da5630220e2ce35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.12.17 {"installer":{"name":"uv","version":"0.12.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for agg-search 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page