init: Search Hub - 统一多搜索引擎聚合服务

docs/architecture.md

@@ -0,0 +1,78 @@
+# Search Hub 架构
+
+## 项目定位
+
+统一多搜索引擎聚合服务，提供 Web UI + RESTful API + 管理面板。
+
+## 目录结构
+
+```
+search-hub/
+├── app.py                      # Flask 主入口 — API 路由 / 页面路由 / 启动
+├── config.py                   # 配置加载（Hermes 配置 → config.yaml → 管理面板）
+├── config.yaml                 # 搜索源密钥 / base_url 等配置
+├── requirements.txt            # Python 依赖
+│
+├── providers/                  # 搜索源适配器层
+│   ├── base.py                 # 抽象基类 BaseProvider + SearchResult
+│   ├── tavily_provider.py      # Tavily API
+│   ├── baidu_provider.py       # 百度千帆（网页搜索 / 智能检索）
+│   ├── duckduckgo_provider.py  # DuckDuckGo（免费，默认关闭）
+│   ├── searxng_provider.py     # SearXNG 自托管元搜索引擎
+│   └── ai_provider.py          # AI 总结服务（非搜索源）
+│
+├── hub/                        # 核心逻辑层
+│   ├── router.py               # 搜索路由器 — 多源路由 / 去重合并 / 自动选择
+│   └── config_manager.py       # 配置管理 — 读写 config.yaml / 字段 schema / 密钥脱敏
+│
+├── templates/                  # Jinja2 模板
+│   ├── index.html              # 搜索页面（Deepseek 风格 UI）
+│   └── admin.html              # 管理面板 + API 文档
+│
+├── static/                     # 前端资源
+│   ├── css/style.css           # 全局样式
+│   ├── js/app.js               # 搜索页交互逻辑
+│   └── js/admin.js             # 管理面板交互逻辑
+│
+└── docs/                       # 项目文档
+    ├── architecture.md         # 本文件 — 技术架构与设计决策
+    └── providers.md            # 搜索源接入指南
+```
+
+## 数据流
+
+```
+用户输入
+    │
+    ▼
+app.py: /api/search
+    │
+    ▼
+hub/router.py: SearchRouter.search()
+    │  ├─ source='auto'     → 按优先级遍历可用源，去重合并
+    │  ├─ source='tavily'   → 单一源搜索
+    │  └─ source='a,b,c'    → 多源并发搜索
+    │
+    ▼
+providers/*.search()        ← 各搜索源适配器调用外部 API
+    │
+    ▼
+SearchResult 列表 → 去重 → 排序 → JSON 响应
+```
+
+## 配置优先级
+
+管理面板保存 > config.yaml > Hermes 配置
+
+修改配置后调用 `_reload_providers()` 热加载，无需重启。
+
+## 搜索源优先级
+
+| 源 | 优先级 | API Key | 说明 |
+|---|---|---|---|
+| Tavily | 10 | 需要 | 默认首选 |
+| 百度搜索 | 20 | 需要 | 千帆网页搜索 |
+| 百度智能检索 | 21 | 需要 | 千帆 AI 检索 |
+| SearXNG | 25 | 不需要 | 自托管元搜索 |
+| DuckDuckGo | 30 | 不需要 | 国内不可用，默认关闭 |
+| AI 总结 | 50 | 需要 | 仅用于总结，非搜索源 |