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

docs/providers.md

@@ -0,0 +1,107 @@
+# 搜索源接入指南
+
+## 新增一个搜索源
+
+### 1. 创建 Provider 类
+
+在 `providers/` 下新建文件，继承 `BaseProvider`:
+
+```python
+from providers.base import BaseProvider, SearchResult
+
+class MyProvider(BaseProvider):
+    name = 'mysearch'              # 唯一标识
+    display_name = 'MySearch'       # 展示名称
+    needs_api_key = False           # 是否需要 API key
+    enabled = True                  # 是否默认启用
+    priority = 35                   # 优先级（越小越优先）
+
+    def __init__(self, config: dict):
+        super().__init__(config)
+        # 从 config 中读取配置
+        mc = config.get('mysearch', {})
+        self.api_key = mc.get('api_key')
+        self.base_url = mc.get('base_url', 'https://api.mysearch.com')
+
+    def is_available(self) -> bool:
+        return True  # 或 return bool(self.api_key)
+
+    def search(self, query: str, max_results: int = 10) -> list:
+        # 调用外部搜索 API
+        results = []
+        # ... 解析响应 ...
+        results.append(SearchResult(
+            title='标题',
+            url='https://example.com',
+            content='摘要内容',
+            score=0.8,
+            source=self.name,
+            published_date='2024-01-01',
+        ))
+        return results[:max_results]
+```
+
+### 2. 注册到 app.py
+
+两处注册：初始化时 + `_reload_providers()` 中
+
+```python
+from providers.my_provider import MyProvider
+
+_providers = {
+    # ... 已有源 ...
+    'mysearch': MyProvider(_raw_config),
+}
+```
+
+### 3. 添加配置加载（config.py）
+
+在 `load_config()` 返回值中加入配置：
+
+```python
+'mysearch': {
+    'api_key': my_api_key,
+    'base_url': my_base_url,
+},
+```
+
+### 4. 添加字段 Schema（hub/config_manager.py）
+
+在 `get_source_schema()` 中加入字段定义：
+
+```python
+'mysearch': [
+    {'key': 'api_key', 'label': 'API Key', 'type': 'password', 'required': True},
+    {'key': 'base_url', 'label': 'API 地址', 'type': 'text', 'required': False},
+],
+```
+
+### 5. 添加本地配置（config.yaml）
+
+```yaml
+sources:
+  mysearch:
+    api_key: "sk-xxx"
+    base_url: "https://api.mysearch.com"
+```
+
+## Provider 基类属性
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `name` | str | 唯一标识，用于路由 |
+| `display_name` | str | UI 展示名 |
+| `needs_api_key` | bool | 管理面板是否显示编辑按钮 |
+| `enabled` | bool | auto 模式是否自动使用 |
+| `priority` | int | 越小越优先（auto 模式排序用） |
+
+## SearchResult 字段
+
+| 字段 | 说明 |
+|---|---|
+| `title` | 标题 |
+| `url` | 链接 |
+| `content` | 摘要/内容 |
+| `score` | 相关性分数（0~1），用于去重排序 |
+| `source` | 来源标识 |
+| `published_date` | 发布日期（可选） |