runningz1/union-search-skill

简体中文 · English

快速开始 · 渠道一览 · Agent 接入 · 服务商入驻 · 技能说明

Union Search 把一次搜索做宽：51 个渠道，默认把每个渠道这次取到的全部结果都带回来，再按页面地址合并重复项。给 Claude Code、Codex 和命令行用。

渠道分成 25 个免密钥网页与社区入口、23 个付费或需要密钥的搜索接口、3 个本机 AI 工具。一次查询可以打开其中任意组合。不加 --limit 时，本地不截断条数；各渠道自己的一页容量、接口上限和超时仍然有效。要少一点再用 --limit 或 --preset。

能做什么

快速开始

1. 获取代码并安装依赖

git clone https://github.com/runningZ1/union-search-skill.git
cd union-search-skill
python -m pip install -r requirements.txt

如果已将此目录安装为 Skill，直接进入技能目录执行后续命令。Agent 使用前先阅读 SKILL.md。

2. 检查环境

python union_search_cli.py doctor --platforms github --pretty

doctor 检查依赖与凭据是否存在，不会验证远程服务是否可用。图片、下载和正文提取的依赖各不相同，按配置与依赖启用。

需要配置 API 时，从模板创建 .env。以下命令只在文件不存在时复制，保留已有配置：

python -c "from pathlib import Path; p = Path('.env'); p.exists() or p.write_bytes(Path('.env.example').read_bytes())"

按需要填入对应渠道的凭据，不必配置全部服务。GitHub 仓库搜索可先不填 Token；认证通常能提高请求额度。

3. 执行第一次搜索

python union_search_cli.py platform github "readme topic:documentation" --limit 3 --pretty --fail-on-platform-error

默认输出 JSON，--pretty 只调整缩进。先看顶层 ok，再读取成功结果中的 data.items。统一 CLI 的搜索、图片和媒体下载命令不接受 --json 参数；defuddle --json 用于请求提取元数据，外层输出格式仍由 --format 控制。

使用示例

指定渠道联合搜索

python union_search_cli.py search "AI agent" --platforms github wikipedia --limit 3 --deduplicate --pretty --fail-on-platform-error

默认不限制本地返回条数，把每个渠道这次取到的结果都交出来；--limit 0 同样表示不限，正整数 --limit N 才是每个平台的上限。相同页面默认合并，--no-deduplicate 可以留下重复。--max-workers 控制并发，--timeout 设置超时秒数。渠道失败不会自动换成另一家服务。

“不限”不等于无限翻页：API 单次请求量、站点页面容量、模型输出窗口和超时仍然生效。API 保留合法的请求批量参数，返回数据不会被默认截取为前 5 / 10 / 20 条。图片命令默认保留本次取得的全部结果，原生图片搜索只获取单页有限结果，不自动遍历全部分页。显式 --preset 会启用相应条数上限。

按分组搜索

python union_search_cli.py list --type groups --pretty
python union_search_cli.py search "Python" --group general --preset small --pretty
python union_search_cli.py search "AI agent" --group api --preset small --pretty

general 无需配置必填 API Key，也是未指定渠道和分组时的默认范围。api 会调用整个 API 分组，需要先配置各服务的凭据；只想用其中几家时，改用 --platforms tavily metaso。small、medium、large、extra 分别对应每渠道 3、5、10、20 条。

网页渠道与参数

默认 8 个网页渠道依次为 baidu_direct、so360_direct、sogou_direct、duckduckgo、brave、yahoo、yandex_direct、quark_direct。网页渠道由本项目独立实现，无外部项目运行依赖；360、搜狗、DuckDuckGo、Brave 和 Yahoo 使用 curl_cffi>=0.16,<0.17，Yandex 与 Quark 使用匿名访问。

python union_search_cli.py platform duckduckgo "Python packaging" --param page=2 --limit 3 --pretty

platform --param key=value 可重复使用，网页参数包含 page、timelimit、proxy、region、country、safesearch；支持范围取决于具体渠道，不支持的参数会明确失败。DuckDuckGo 网页仅支持 page，不支持 timelimit 或非 wt-wt 的 region。duckduckgo_html、brave_direct、yahoo_direct 保留为兼容入口，与同服务渠道共用实现；一次联合请求会按来源去重，仅执行同服务的首个入口。这与 --deduplicate 的结果去重分别生效。

保存便于阅读的结果

python union_search_cli.py search "Python packaging" --platforms github --limit 5 --format markdown -o out/search.md

JSON、Markdown 和文本输出都保留完整数据，Markdown 用 JSON 代码块呈现各渠道的完整字段。-o 保存到文件，目标目录会自动创建。

提取网页正文

安装 Node.js 与下文列出的 Node 依赖后：

python union_search_cli.py defuddle "https://example.com" --pretty
python union_search_cli.py defuddle "https://example.com" --format markdown -o out/article.md

这里调用本地 Defuddle 引擎。Jina、Firecrawl 等其他正文提取引擎见 url_to_markdown 模块。

搜索与下载图片

python union_search_cli.py image "mountain landscape" --search-only --limit 5 --pretty
python union_search_cli.py image "mountain landscape" --platforms bing --limit 5 --output-dir image_downloads --pretty

默认图片平台为 baidu bing wikicommons，使用本项目独立实现。--search-only 仅搜索原生平台并返回元数据，不支持的平台明确报错；默认搜索后下载，可通过 --platforms 显式选择保留的 SDK 平台。平台失败不自动切换来源。

图片结果以字典保留标题、图片地址、来源页面、缩略图、尺寸、作者、许可与版本信息，缺失字段输出 null。image_variant 标明来源原始或最大可用版本，具体字段见图片模块说明。下载文件经过 Pillow Image.verify() 检查，并记录 sha256、bytes、文件位置和下载状态。单张图片失败记录单独保留；部分失败时 ok: false，信封仍保留 data。

从搜索结果下载媒体

python union_search_cli.py search "Python tutorial" --platforms youtube --limit 3 -o out/videos.json --pretty --fail-on-platform-error
python union_search_cli.py download --from-file out/videos.json --select 1 --output-dir downloads --pretty

第一步需要 YOUTUBE_API_KEY。搜索结果中的 download_candidates 提供候选索引，先查看候选再用 --select 选择。媒体下载依赖 yt-dlp；合并音视频或提取音频还需要 FFmpeg。下载能力取决于目标站点与登录状态，详见 CLI 文档。

渠道一览

当前注册表共有 52 项能力，其中 51 个搜索渠道：25 个无需必填 API Key、23 个需要 API Key、3 个使用本机 AI coding 工具登录态；另有 1 个正文提取工具（Defuddle）和 24 个图片平台（12 个原生平台、12 个 SDK 平台）。同一服务的不同访问方式按独立渠道计算。以运行结果为准：

python union_search_cli.py list --pretty
python union_search_cli.py schema --pretty

原生图片平台：baidu、bing、sogou、quark、pixabay、flickr、pinterest、500px、wikicommons、naver、artstation、findthatmeme。

保留的 SDK 图片平台：google、i360、yandex、yahoo、unsplash、gelbooru、safebooru、danbooru、pexels、huaban、foodiesfeed、volcengine。

各渠道的原生响应、模块保留字段、统一 CLI 映射、空值规则、常用参数及单次结果容量见搜索输出字段文档索引，具体分析保存在对应服务目录的 output-analysis.md。容量表区分官方请求上限、模块默认数量、分页与本地截断，并附核查来源；取得非空成功结果的渠道在本目录 examples/ 中保留真实 JSON 样例与来源说明。

已知边界

• TikHub 接入已移除，包括小红书、抖音、Bilibili、Twitter、微博及旧知乎搜索；独立的 zhihu_official 保留。
• 火山引擎标记为 degraded，历史上有响应解析不稳定的问题。
• 注册表中的 stable 只是代码元数据，不代表实时健康状态。零条结果也可能源于验证码或选择器失效。
• 无需 API Key 不等于不访问远程接口：GitHub、Wikipedia 等匿名调用，仍可能遇到验证码、限流或空结果。
• 未注册为统一 CLI 渠道的独立模块见 RSS、微信。
• bing、yandex 使用 SerpAPI，bing_cn_direct、bing_int_direct、yandex_direct 使用无需 API Key 的网页入口。Yahoo 的 yahoo_direct 为 yahoo 的兼容名称，共用实现；联合查询按来源去重。

配置与依赖

npm install
npm --prefix scripts/url_to_markdown/engines/defuddle-node ci
python union_search_cli.py doctor --pretty

命令默认从当前工作目录读取 .env，请在仓库根目录执行，或通过 --env-file 指定路径。全部变量见 .env.example，更多说明见渠道说明与速率限制说明。

用 Agent 自动配置 API Key

涉及 API 密钥配置时，推荐使用 Ego Lite 浏览器配合具备本地文件读写能力的 Agent：自动访问官方控制台、获取或创建密钥、写入本地 .env，再执行真实搜索验证。Ego Lite 支持 macOS 和 Windows，浏览器准备完成并授权后，无需用户逐个平台查找、复制和粘贴密钥。

使用前，在 Ego Lite 首次启动的图形界面引导中，从日常 Google Chrome 个人资料导入登录状态、Cookie、扩展程序和书签，并检查登录身份。API Key 由各平台控制台、本地配置或密码管理器管理，Chrome 没有统一的“默认 API 密钥”资料项；官方迁移说明未明确承诺导入已保存密码或 API Key，需另行核对。部分网站仍可能要求重新登录、验证码或双重验证。

Ego Lite 无法使用时，可使用当前环境已提供 Computer Use 能力的 Codex 或 ChatGPT 桌面端，先确认该版本支持网页操作、本地文件写入及所需登录状态。基于截图的 Computer Use 通常需要更多视觉输入和操作轮次，可能消耗更多 token，因此优先使用 Ego Lite。验证码、实名认证和需要本人决定的付费操作仍由用户完成。

完整的批量配置、授权回复、失败续接提示词，以及各平台的查找方向，见 Agent 自动获取与配置 API Key 指南。凭据可存放在项目本地文档文件夹 local_dev_doc/api-credentials/，通过 --env-file 加载；也可按用户选择写入根目录 .env。保存密钥后仍需检查依赖、权限、额度与接口响应，才能确认对应渠道可用。

Agent 接入

Agent 先阅读 SKILL.md，再通过 CLI 发现当前能力：

python union_search_cli.py schema --pretty
python union_search_cli.py errors --pretty
python union_search_cli.py doctor --platforms github --pretty

统一入口把 JSON 写入 stdout，把诊断信息写入 stderr，--quiet 可关闭诊断日志。程序应读取 schema_version、ok、type 和 meta，读取 data 中的结果，失败时同时读取 error 和各渠道状态。以下只示意成功信封的结构，省略兼容字段：

{
  "schema_version": "1.0",
  "ok": true,
  "type": "result",
  "data": {},
  "meta": { "request_id": "req_example", "duration_ms": 42 }
}

失败时检查 error.code、error.retryable、error.outcome 和 error.next_actions。错误建议中出现的 union-search … 可替换为 python union_search_cli.py …。

搜索默认在平台失败时仍返回退出码 0，此时 JSON 的 ok 为 false，不能只靠退出码判断成功。需要脚本严格失败时，在 search 或 platform 命令上添加 --fail-on-platform-error，平台失败将返回 4。部分渠道失败时信封保留 data，调用方可以读取成功渠道的结果，并检查 error 和各渠道状态。

服务商入驻

如果你提供网页搜索、AI 联网搜索、垂直领域搜索或正文提取 API，欢迎接入 Union Search。目前已有 Tavily、Exa、Serper、Firecrawl、秘塔、Kimi、智谱、DeepSeek、腾讯元宝、阿里云百炼等 23 家 API 服务在 api 分组中。

接入后，你的服务会出现在这些位置：

入驻需要准备：

• 公开的 HTTP API 与文档，返回结果至少包含标题、链接和摘要。
• 用于验收的测试 Key 或免费额度。
• 明确的认证方式、计费和限流规则。
• 服务条款允许通过 Agent 和命令行工具调用。

申请方式：

1. 填写服务商入驻申请，说明 API 文档、认证方式、额度和返回字段。请勿在 Issue 中粘贴真实 Key。
2. 维护者评估后在 Issue 中回复接入计划；也欢迎服务商直接提交 Pull Request，按下面的清单实现。
3. 用真实搜索验收：本地命令通过，且线上接口返回有效结果。
4. 合并后，你的服务进入注册表、api 分组、README 渠道墙和凭据指南。

新用户专属额度、联合发布、文档互链等合作形式，可以在申请表的“合作意向”中说明。

故障排查

详细说明见故障排查文档。

项目结构

union-search-skill/
├── union_search_cli.py          # 统一命令入口
├── SKILL.md                     # Agent 使用指引与模块导航
├── AGENTS.md                    # 项目职责、开发与验证规则
├── CLAUDE.md                    # 导入 AGENTS.md
├── agents/                      # 技能界面与执行元数据，含 _meta.json
├── .env.example                 # 环境变量模板
├── scripts/
│   ├── cli/                     # 参数解析、能力注册、错误码与输出信封
│   ├── union_search/            # 多渠道并发编排、分组与凭据元数据
│   ├── evals/                   # 技能结构与触发边界检查
│   ├── tests/                   # 离线回归测试
│   ├── channels/                # 搜索渠道，每个服务一个目录
│   │   ├── no_api/              #   网页请求、跨进程节流与兼容基类
│   │   ├── ai_tools/            #   Claude Code / Codex / Grok Build 原生搜索
│   │   ├── tavily_search/       #   API 服务商，例如 Tavily、Exa、Kimi
│   │   ├── baidu/               #   同一服务的 API 与直连脚本放在同一目录
│   │   └── …
│   ├── union_image_search/      # 图片搜索编排与下载
│   │   ├── providers/           #   图片来源适配器
│   │   └── native_images.py     #   统一字段、下载与图片验证
│   ├── url_to_markdown/         # 网页正文提取（Defuddle、Jina、Firecrawl）
│   └── downloader/              # yt-dlp 媒体下载
├── references/                  # 凭据、渠道、限流、排障与第三方说明
└── assets/readme/               # README 视觉素材

运行时产生的数据不进入版本库：联合搜索日志写入 search_logs/，各渠道的原始响应写入对应目录下的 responses/。完整参数见 CLI 文档，编排说明见联合搜索模块。

参与维护

使用中遇到功能不可用、结果异常、升级兼容问题或文档错误，请到 GitHub Issues 反馈。提交前可先搜索已有 Issue；没有相同问题时，新建 Issue 描述情况，也欢迎提交 Pull Request。

为便于复现，请尽量提供：

• 所用版本或提交号，以及操作系统、Python / Node.js 版本。
• 出问题的渠道、完整执行命令和最少复现步骤。
• 预期表现、实际表现、退出码，以及脱敏后的错误信息或截图。
• 对应渠道的 doctor 检查结果，以及问题是否每次都能复现。

请勿上传真实 API Key、Token、Cookie、完整 .env 文件或包含凭据的截图。暂时无法判断原因也可以先提 Issue，说明已观察到的情况即可。

添加或修改渠道时，同步检查渠道脚本、分组、凭据元数据、CLI 帮助与模块文档，并区分“脚本存在”“本地命令通过”和“远程返回有效结果”，避免把一次测试写成长期可用承诺。

许可证与致谢

本项目现阶段暂定采用 MIT 开源协议，完整文本见 LICENSE。本仓库原创代码与文档按该协议提供，使用、修改和分发时请保留相应版权与许可声明。第三方代码、依赖及其附带资源保留各自的许可证，不因本项目采用 MIT 而改变。

完整的直接依赖、可选组件、迁入代码来源、外部服务边界与文档参考见 第三方项目与依赖说明。该清单依据当前仓库整理，不代表已完成全部传递依赖的许可证审计。

MIT 协议不包含第三方 API 的使用额度、账号权限或搜索结果内容的授权。各搜索服务、本机 AI 客户端及其账号仍按各自条款使用。Computer Use 配置指南是一套由用户授权后交给 Agent 执行的流程，需要用户自己的工具、账号与凭据。

返回顶部