Union Search Skill

🚀 统一的多平台搜索解决方案 — 一次调用，触达全网

📖 目录

快速开始
支持的平台
统一 CLI 命令
使用示例
搜索日志记录
配置指南
项目结构
故障排查
贡献指南
许可证

🎯 特性亮点

🌐 全网覆盖 — 支持 30+ 搜索平台，涵盖开发者社区、社交媒体、通用搜索引擎
⚡ 统一接口 — 单一 CLI 命令调用所有平台，标准化输出格式
🔧 灵活配置 — 支持分组搜索、并发控制、结果过滤、多格式输出
📦 开箱即用 — 最小依赖设计，按需启用高级功能
🛡️ 生产就绪 — 完整的错误处理、速率限制、健康检查
🏆 渠道最多 — 与其他开源项目相比，本项目支持最多的搜索渠道和备用方案
🔄 自动降级 — 多渠道冗余设计，主渠道失败自动切换备用方案

💡 为什么选择这个项目？

特性	Union Search	其他开源项目
支持平台数量	30+	通常 1-5 个
备用渠道	✅ 多平台冗余	❌ 单一渠道
统一 CLI	✅ 标准化接口	❌ 各自为政
图片搜索	✅ 18 个平台	❌ 少见
社交媒体	✅ 抖音/小红书/B 站	❌ 主要面向海外
全媒介下载	🔄 即将支持	⚠️ 功能分散

核心优势：

渠道最多：一个项目解决所有搜索需求，无需在不同项目间切换
容错性强：某个 API 失效时，自动切换到其他可用渠道
持续扩展：不断添加新的搜索渠道和下载功能

📋 路线图

即将上线

功能	描述	状态
全媒介下载工具	支持抖音视频、小红书图文、B 站视频、YouTube 视频等平台的完整内容下载	🔄 开发中
更多搜索渠道	添加 Wikipedia 镜像、学术搜索（Google Scholar、Semantic Scholar）	📝 计划中
渠道自动切换	主渠道失败时无缝切换到备用渠道	📝 计划中
结果缓存	减少重复请求，节省 API 配额	📝 计划中

🚀 快速开始

1. 安装依赖

# 基础依赖（所有搜索功能）
pip install requests python-dotenv lxml

# 图片搜索（可选）
pip install pyimagedl

# Bilibili 搜索（可选）
pip install curl_cffi

# Tavily 搜索（可选）
pip install tavily-python

# RSS 订阅搜索（可选）
pip install feedparser

2. 配置环境变量

# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入 API 密钥

3. 运行第一个搜索

# 统一搜索（开发者相关平台）
python union_search_cli.py search "AI Agent" --group dev --limit 3 --pretty

# 或直接调用单个平台
python union_search_cli.py google "Python tutorial" --limit 5

🌍 支持的平台

开发者搜索

平台	功能	状态
GitHub	仓库/代码/Issues/PRs 搜索	✅ 稳定
Reddit	帖子/子版块/用户搜索	✅ 稳定
Zhihu	知乎问答搜索	✅ 稳定

社交媒体与视频

平台	功能	状态
Xiaohongshu (小红书)	笔记搜索	✅ 稳定
Douyin (抖音)	视频搜索	✅ 稳定
Bilibili	视频/UP 主搜索	✅ 稳定
Twitter / X	推文搜索	✅ 稳定
YouTube	视频/评论搜索	✅ 稳定
Weibo (微博)	微博搜索	⚠️ 需要 Cookie

通用搜索引擎

平台	API 密钥	状态
Google	需要	✅ 稳定
Bing	需要	✅ 稳定
DuckDuckGo	无需	✅ 稳定
Brave	无需	✅ 稳定
Yahoo	无需	✅ 稳定
Baidu	需要	✅ 稳定
Yandex	无需	✅ 稳定

AI 驱动搜索

平台	特性	状态
Tavily	AI 摘要/智能搜索	✅ 稳定
Metaso (秘塔)	AI 生成答案	✅ 稳定
Volcengine (火山)	融合搜索+AI 摘要	⚠️ 偶发解析问题
Jina	内容提取	✅ 稳定

图片搜索（18 个平台）

搜索引擎: 百度、Bing、Google、360、搜狗、DuckDuckGo、Yandex、Yahoo
图库网站: Pixabay、Pexels、Unsplash、Foodiesfeed
动漫图片: Danbooru、Gelbooru、Safebooru
其他: 花瓣网、次元小镇、火山引擎

内容订阅

类型	功能	状态
RSS	多源聚合/关键词过滤	✅ 稳定
小宇宙 FM	播客搜索/AI 摘要	✅ 稳定

📊 实测数据

基于 2026-03-05 真实搜索测试，关键词: AI agent

搜索引擎组 (search) 实测

平台	默认结果数	响应时间	状态
metaso	10	1.00s	✅
baidu	10	1.60s	✅
yandex	10	2.15s	✅
bing	3	2.22s	✅
wikipedia	10	2.34s	✅
google	10	2.95s	✅
tavily	5	3.19s	✅
brave	10	3.20s	✅
duckduckgo	6	3.58s	✅
jina	10	3.68s	✅
yahoo	7	2.62s	✅
volcengine	10	6.45s	✅

汇总统计

指标	数值
搜索平台数	12
成功平台	12/12 (100%)
总耗时	11.14 秒
总结果数	91 条
平均每平台	7.6 条
最快响应	metaso (1.00s)

去重后预估

搜索引擎结果存在一定重叠（约 20-30%）
去重后预估有效结果: 约 65-70 条
信息覆盖度: 远超单一搜索引擎

各平台默认返回数量

平台	默认值	限制原因
google	10	Custom Search API 限制
tavily	5	API 默认设置
jina	10	API 默认设置
duckduckgo	6	非 API，结果不稳定
brave	10	非 API
yahoo	7	非 API
yandex	10	SerpAPI
bing	3	SerpAPI 免费限制
wikipedia	10	API 默认设置
metaso	10	API 默认设置
volcengine	10	API 默认设置
baidu	10	API 默认设置

💡 提示: 使用 --limit 参数可自定义每平台返回数量

🖥️ 统一 CLI 命令

命令总览

python union_search_cli.py --help

命令	描述
`search`	多平台聚合搜索
`platform <name>`	单平台搜索
`image`	图片搜索与下载
`list`	列出可用平台/分组
`doctor`	健康检查
`<platform>`	平台直达命令（如 `google`、`bing`）

全局选项

选项	简写	描述
`--format <type>`	-	输出格式：`json` / `markdown` / `text`
`--pretty`	-	美化 JSON 输出
`--output <file>`	`-o`	输出到文件
`--env-file <path>`	-	环境变量文件路径

📚 使用示例

多平台聚合搜索

# 搜索开发者相关内容
python union_search_cli.py search "machine learning" --group dev --limit 5

# 搜索社交媒体内容
python union_search_cli.py search "AI trends" --group social --limit 3

# 指定多个平台
python union_search_cli.py search "Python" --platforms github google tavily --limit 5

# 带并发和超时控制
python union_search_cli.py search "Rust" --max-workers 10 --timeout 120

单平台搜索

# GitHub 搜索
python union_search_cli.py platform github "awesome python" --limit 10

# 或使用直达命令
python union_search_cli.py github "machine learning" --limit 5
python union_search_cli.py bing "AI news" --limit 10
python union_search_cli.py bsearch "deep learning" --limit 10  # 使用别名

图片搜索与下载

# 搜索并下载图片
python union_search_cli.py image "cute cats" \
  --platforms google bing pixabay \
  --limit 20 \
  --output-dir ./cat_images

# 自定义下载线程数
python union_search_cli.py image "landscape" --threads 10 --limit 50

列出能力

# 列出所有平台和分组
python union_search_cli.py list --format markdown

# 只看图片平台
python union_search_cli.py list --type images

健康检查

# 检查环境配置
python union_search_cli.py doctor --env-file .env

# 严格模式（警告也返回非零）
python union_search_cli.py doctor --strict

📝 搜索日志记录

每次搜索请求的日志和结果会自动保存到 search_logs/ 目录，文件格式为 JSON，包含完整的请求信息和搜索结果。

日志文件格式

{
  "version": "1.0.0",
  "timestamp": "2026-03-05T21:38:28.502062",
  "request": {
    "query": "Python教程",
    "platforms": ["search"],
    "total_results": 24
  },
  "results": [
    {
      "title": "9. Classes — Python 3.14.3 documentation",
      "link": "https://docs.python.org/3/tutorial/classes.html",
      "source": "google",
      "snippet": "Classes provide a means of bundling data and functionality together..."
    }
    // ... 更多结果
  ],
  "statistics": {
    "total_count": 24,
    "platform_counts": {
      "google": 2,
      "tavily": 2,
      "jina": 2,
      // ...
    }
  },
  "metadata": {
    "response_time": 6.5,
    "status": "success"
  }
}

使用日志模块

from scripts.search_logger import SearchLogger

# 创建日志记录器
logger = SearchLogger()

# 记录搜索结果
logger.log(
    query="Python教程",
    platforms=["search"],
    results=[...],  # 搜索结果列表
    metadata={"response_time": 2.5, "status": "success"}
)

示例响应文件

项目包含一个示例响应文件，展示完整的日志格式：

search_logs/example_python_tutorial_search.json - Python教程搜索示例

注意: search_logs/ 目录已被添加到 .gitignore，本地日志不会提交到远程仓库。

🔧 配置指南

环境变量参考

变量名	平台	获取地址	备注
`GITHUB_TOKEN`	GitHub	GitHub Settings	公共搜索无需权限
`TIKHUB_TOKEN`	小红书/抖音/Twitter	TikHub	💰 $5 约 5000 次调用
`SERPAPI_KEY`	Google/Bing (SerpAPI)	SerpAPI	⚠️ 免费 250 次/月，需手机号注册
`GOOGLE_API_KEY`	Google	Google Cloud Console	官方 API 替代方案
`GOOGLE_SEARCH_ENGINE_ID`	Google	Programmable Search Engine	需与 API Key 配合使用
`YOUTUBE_API_KEY`	YouTube	Google Cloud Console	10000 单位/天
`TAVILY_API_KEY`	Tavily	Tavily Dashboard	免费 1000 积分/月
`METASO_API_KEY`	秘塔搜索	Metaso	AI 生成答案
`VOLCENGINE_API_KEY`	火山引擎	火山引擎控制台	字节官方 API
`ZHIHU_COOKIE`	知乎	浏览器开发者工具	手动获取
`WEIBO_COOKIE`	微博	浏览器开发者工具	手动获取

💡 API 成本提示：

SerpAPI 免费账户每月仅 250 次请求，注册需要手机号验证。适合测试和低频使用。

TikHub 5 美元充值约可使用 5000 次（取决于具体平台和参数），正常使用足够。

建议优先使用 无需 API 密钥 的引擎（DuckDuckGo、Brave、Yahoo 等）作为日常搜索。

生产环境建议配置多个渠道，自动降级切换。

平台分组

# 查看可用分组
python union_search_cli.py list --type groups

分组	包含平台
`dev`	GitHub, Reddit, Zhihu
`social`	小红书，抖音，Twitter, Weibo
`video`	Bilibili, YouTube
`search`	Google, Bing, DuckDuckGo, Brave, Yahoo
`ai`	Tavily, Metaso, Volcengine, Jina

📁 项目结构

union-search-skill/
├── union_search_cli.py      # 统一 CLI 入口
├── scripts/
│   ├── cli/                 # CLI 核心模块
│   │   ├── main.py          # CLI 主程序
│   │   ├── adapters.py      # 平台适配器
│   │   ├── registry.py      # 平台注册表
│   │   └── validators.py    # 参数验证
│   ├── github/              # GitHub 搜索
│   ├── reddit/              # Reddit 搜索
│   ├── xiaohongshu/         # 小红书搜索
│   ├── douyin/              # 抖音搜索
│   ├── bilibili/            # Bilibili 搜索
│   ├── twitter/             # Twitter 搜索
│   ├── youtube/             # YouTube 搜索
│   ├── google_search/       # Google 搜索
│   ├── bing/                # Bing 搜索
│   ├── baidu/               # 百度搜索
│   ├── duckduckgo/          # DuckDuckGo 搜索
│   ├── brave/               # Brave 搜索
│   ├── yahoo/               # Yahoo 搜索
│   ├── wikipedia/           # Wikipedia 搜索
│   ├── tavily_search/       # Tavily 搜索
│   ├── metaso/              # 秘塔搜索
│   ├── volcengine/          # 火山引擎搜索
│   ├── zhihu/               # 知乎搜索
│   ├── union_image_search/  # 图片搜索
│   ├── rss_search/          # RSS 订阅搜索
│   └── xiaoyuzhoufm/        # 小宇宙 FM 播客
├── references/              # 参考文档
├── responses/               # API 响应存档
├── search_logs/             # 搜索日志（本地记录，不提交到远程）
│   └── example_*.json      # 示例响应文件
├── scripts/
│   └── search_logger.py    # 日志记录模块
├── .env.example             # 环境变量模板
└── README.md                # 项目文档

🐛 故障排查

常见问题

1. 平台返回 403 错误

原因: API 密钥无效或请求频率过高

解决方案:

# 检查 API 密钥配置
python union_search_cli.py doctor --platforms github google

# 降低并发数
python union_search_cli.py search "query" --max-workers 2

2. 图片下载失败

原因: 缺少 pyimagedl 依赖

解决方案:

pip install pyimagedl

3. 火山引擎解析错误

状态: 已知问题，修复中

临时方案: 使用其他 AI 搜索平台替代

python union_search_cli.py search "query" --platforms tavily metaso

获取帮助

📖 查看参考文档
🔍 搜索历史问题
💬 提交 Issue

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

🙏 致谢

感谢以下开源项目和 API 服务：

requests - Python HTTP 库
lxml - XML/HTML 解析
TikHub - 社交媒体 API
Tavily - AI 搜索引擎
yt-dlp - 视频下载工具

Made with ❤️ by the Union Search Team

⬆ 返回顶部

Name		Name	Last commit message	Last commit date
Latest commit History 62 Commits
references		references
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
HANDOVER.md		HANDOVER.md
README.md		README.md
SKILL.md		SKILL.md
uniarch.py		uniarch.py
union_search_cli.py		union_search_cli.py

Folders and files

Latest commit

History

Repository files navigation

Union Search Skill

📖 目录

🎯 特性亮点

💡 为什么选择这个项目？

📋 路线图

即将上线

🚀 快速开始

1. 安装依赖

2. 配置环境变量

3. 运行第一个搜索

🌍 支持的平台

开发者搜索

社交媒体与视频

通用搜索引擎

AI 驱动搜索

图片搜索（18 个平台）

内容订阅

📊 实测数据

搜索引擎组 (search) 实测

汇总统计

去重后预估

各平台默认返回数量

🖥️ 统一 CLI 命令

命令总览

全局选项

📚 使用示例

多平台聚合搜索

单平台搜索

图片搜索与下载

列出能力

健康检查

📝 搜索日志记录

日志文件格式

使用日志模块

示例响应文件

🔧 配置指南

环境变量参考

平台分组

📁 项目结构

🐛 故障排查

常见问题

1. 平台返回 403 错误

2. 图片下载失败

3. 火山引擎解析错误

获取帮助

🤝 贡献指南

📄 许可证

🙏 致谢

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages