# MiMo Web Search Plugin for Hermes Agent

将小米 MiMo 的**联网搜索**（server-side web search）接入 Hermes Agent 的 `web_search` 工具。

MiMo 在服务端执行搜索、浏览网页、提取内容，通过 Chat Completions API 的 `url_citation` 注释返回结构化结果。适合中文搜索场景。

## 快速开始

### 1. 独立使用（无需 Hermes）

```bash
# 安装依赖
pip install httpx

# 设置 API Key
export XIAOMI_API_KEY="your-api-key-here"

# 如果使用 Token Plan（国内端点），还需设置 base URL
export XIAOMI_BASE_URL="https://token-plan-cn.xiaomimimo.com/v1"

# 搜索
python3 test_search.py "小米17解锁"
python3 test_search.py "YU7 GT 价格" --limit 10
python3 test_search.py "今天天气" --raw   # 输出完整 API 响应
```

### 2. 接入 Hermes Agent

将插件复制到 Hermes 的用户插件目录：

```bash
cp -r ~/mimo-search-plugin ~/.hermes/plugins/web/mimo
```

在 `~/.hermes/config.yaml` 中启用：

```yaml
plugins:
  enabled:
    - web-mimo

web:
  search_backend: "mimo"
```

环境变量（在 `~/.hermes/.env` 中设置）：

```
XIAOMI_API_KEY=your-api-key-here
# 可选：Token Plan 国内端点
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1
```

重启 Hermes 后，`web_search` 工具将使用 MiMo 作为搜索后端。

## 获取 API Key

1. 访问 [platform.xiaomimimo.com](https://platform.xiaomimimo.com)
2. 注册/登录小米账号
3. 创建 API Key
4. 在控制台 → 插件管理中**开通联网服务插件**（付费功能）

## 可选配置

在 `~/.hermes/config.yaml` 的 `web.mimo` 下可调整：

```yaml
web:
  search_backend: "mimo"
  mimo:
    model: "mimo-v2.5"       # 可选: mimo-v2.5-pro, mimo-v2.5, mimo-v2-flash 等
    max_keyword: 3            # 每轮搜索最大关键词数（影响调用次数和费用）
    timeout: 30               # 请求超时秒数
```

## 计费

- **联网搜索工具**：国内 ¥16/1000 次，海外 $5/1000 次
- **Token 消耗**：搜索结果拼入 prompt，按模型输入 token 标准价计费
- 每轮搜索可能触发 `max_keyword` 个关键词，每个关键词算一次调用

## 工作原理

```
Hermes web_search 工具
    ↓
MiMoWebSearchProvider.search(query, limit)
    ↓
POST {base_url}/chat/completions
    tools: [{type: "web_search", force_search: true, ...}]
    ↓
MiMo 服务端搜索 → 返回 annotations: [{type: "url_citation", ...}]
    ↓
解析为 Hermes 标准格式: {title, url, description, position}
```

## 文件说明

| 文件 | 说明 |
|---|---|
| `provider.py` | `WebSearchProvider` 子类，核心搜索逻辑 |
| `__init__.py` | 插件注册入口 |
| `plugin.yaml` | Hermes 插件清单 |
| `test_search.py` | 独立测试脚本（可脱离 Hermes 使用） |

## API 参考

- [MiMo 联网搜索文档](https://mimo.mi.com/docs/zh-CN/guides/text-generation/web-search)
- [MiMo 平台](https://platform.xiaomimimo.com)
- [Hermes Web Search Provider 插件开发指南](https://hermes-agent.nousresearch.com/docs/developer-guide/web-search-provider-plugin)