1 files changed, 110 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d26e2b2
--- /dev/null
+++ b/README.md
@@ -0,0 +1,110 @@
+# 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)