From 3ab124f9c84e8d8a7485c905452fa83b94ff40e8 Mon Sep 17 00:00:00 2001 From: ntzyz Date: Tue, 7 Jul 2026 12:51:48 +0800 Subject: feat: split README and INSTALL, add setup.sh - Split README.md (overview) and INSTALL.md (install for agents) - Add setup.sh (reference only) - Unify author to ntzyz - Add Windows PowerShell equivalents and reuse tip --- INSTALL.md | 113 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 102 ++++++++++++++---------------------------------------- plugin.yaml | 2 +- setup.sh | 76 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 215 insertions(+), 78 deletions(-) create mode 100644 INSTALL.md create mode 100755 setup.sh diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..807f817 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,113 @@ +# MiMo Web Search — 安装说明（给 Agent 看） + +> **提示**：如果你已经安装过其他 MiMo 插件（如 mimo-asr、mimo-tts）并已配置过 `XIAOMI_API_KEY` 和 `XIAOMI_BASE_URL`，可以直接复用已有的环境变量配置，无需重复询问 API Key 和端点。 + +## 前置条件 + +- Hermes Agent 已安装并可运行 +- Xiaomi MiMo API Key（获取地址：https://platform.xiaomimimo.com） +- 在 MiMo 控制台开通**联网服务插件**（付费功能） +- `httpx` Python 包 + +## 安装 + +> **注意**：`setup.sh` 仅供参考，请勿直接运行。请阅读以下步骤，根据用户的环境自行完成安装。 +> 以下命令中的 `~/.hermes` 仅为 Unix 典型路径，**不要硬编码**。安装前请先确认 Hermes 的实际安装目录（如 `$HERMES_HOME`、`$env:HERMES_HOME` 等）。 + +### 安装依赖 + +```bash +pip install httpx +``` + +### 安装插件 + +将插件文件复制到 Hermes 的插件目录并启用： + +```bash +mkdir -p ~/.hermes/plugins/web/mimo +cp plugin.yaml __init__.py provider.py ~/.hermes/plugins/web/mimo/ +hermes plugins enable web/mimo +``` + +```powershell +# Windows (PowerShell) +mkdir -Force "$env:USERPROFILE\.hermes\plugins\web\mimo" +cp plugin.yaml,__init__.py,provider.py "$env:USERPROFILE\.hermes\plugins\web\mimo\" +hermes plugins enable web/mimo +``` + +### 配置 Hermes + +在 Hermes 的 `config.yaml` 中启用： + +```yaml +plugins: + enabled: + - web-mimo + +web: + search_backend: "mimo" +``` + +### 配置环境变量 + +在 Hermes 的 `.env` 文件中设置： + +```env +XIAOMI_API_KEY=your-api-key-here +# 可选：Token Plan 国内端点 +XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1 +``` + +> 中国站用户：`https://token-plan-cn.xiaomimimo.com/v1` +> 国际站用户：`https://api.xiaomimimo.com/v1` + +重启 Hermes 后，`web_search` 工具将使用 MiMo 作为搜索后端。 + +### 可选：安装独立测试脚本 + +```bash +cp test_search.py ~/test_search.py +chmod +x ~/test_search.py +``` + +```powershell +# Windows (PowerShell) +cp test_search.py "$env:USERPROFILE\test_search.py" +``` + +## 独立使用（不依赖 Hermes） + +```bash +export XIAOMI_API_KEY="your-api-key-here" +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 +``` + +```powershell +# Windows (PowerShell) +$env:XIAOMI_API_KEY="your-api-key-here" +$env:XIAOMI_BASE_URL="https://token-plan-cn.xiaomimimo.com/v1" + +python test_search.py "小米17解锁" +python test_search.py "YU7 GT 价格" --limit 10 +``` + +## 卸载 + +```bash +hermes plugins disable web/mimo +rm -rf ~/.hermes/plugins/web/mimo +rm -f ~/test_search.py +``` + +```powershell +# Windows (PowerShell) +hermes plugins disable web/mimo +rm -Recurse -Force "$env:USERPROFILE\.hermes\plugins\web\mimo" +rm -Force "$env:USERPROFILE\test_search.py" +``` diff --git a/README.md b/README.md index d26e2b2..211be0b 100644 --- a/README.md +++ b/README.md @@ -4,65 +4,24 @@ 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 工具 + ↓ +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} ``` -重启 Hermes 后，`web_search` 工具将使用 MiMo 作为搜索后端。 - -## 获取 API Key - -1. 访问 [platform.xiaomimimo.com](https://platform.xiaomimimo.com) -2. 注册/登录小米账号 -3. 创建 API Key -4. 在控制台 → 插件管理中**开通联网服务插件**（付费功能） - ## 可选配置 -在 `~/.hermes/config.yaml` 的 `web.mimo` 下可调整： +在 Hermes 的 `config.yaml` 的 `web.mimo` 下可调整： ```yaml web: @@ -79,32 +38,21 @@ web: - **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) + +## 文件说明 + +``` +mimo-websearch-for-hermes/ +├── README.md # 本文档（介绍） +├── INSTALL.md # 安装说明（给 Agent 看） +├── plugin.yaml # Hermes 插件清单 +├── setup.sh # 安装/卸载脚本（仅供参考） +├── __init__.py # 插件注册入口 +├── provider.py # WebSearchProvider 实现 +└── test_search.py # 独立测试脚本（可脱离 Hermes 使用） +``` diff --git a/plugin.yaml b/plugin.yaml index a7e620d..d6ea52e 100644 --- a/plugin.yaml +++ b/plugin.yaml @@ -1,7 +1,7 @@ name: web-mimo version: 1.0.0 description: "Xiaomi MiMo Web Search — server-side web search via MiMo's 联网搜索 tool (Chat Completions API). Requires XIAOMI_API_KEY (https://platform.xiaomimimo.com)." -author: NousResearch +author: ntzyz kind: backend provides_web_providers: - mimo diff --git a/setup.sh b/setup.sh new file mode 100755 index 0000000..42224ce --- /dev/null +++ b/setup.sh @@ -0,0 +1,76 @@ +#!/bin/bash +# MiMo Web Search — Hermes Agent Plugin Setup +# 用法: bash setup.sh [--uninstall] + +set -euo pipefail + +HERMES_HOME="${HERMES_HOME:-$HOME/.hermes}" +PLUGIN_DIR="$HERMES_HOME/plugins/web/mimo" +SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)" + +GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; NC='\033[0m' +ok() { echo -e "${GREEN}✓${NC} $*"; } +warn() { echo -e "${YELLOW}⚠${NC} $*"; } +fail() { echo -e "${RED}✗${NC} $*" >&2; } + +# ── Uninstall ────────────────────────────────────────────────────── +if [[ "${1:-}" == "--uninstall" ]]; then + echo "Uninstalling MiMo Web Search plugin..." + command -v hermes &>/dev/null && hermes plugins disable web/mimo 2>/dev/null || true + rm -rf "$PLUGIN_DIR" + rm -f "$HOME/test_search.py" + ok "Done. Restart Hermes session (/reset) to take effect." + exit 0 +fi + +# ── Install ──────────────────────────────────────────────────────── +echo "Installing MiMo Web Search plugin for Hermes Agent..." + +# 1. Pre-flight checks +[[ -d "$HERMES_HOME" ]] || { fail "Hermes not found at $HERMES_HOME"; exit 1; } + +if [[ -f "$HERMES_HOME/.env" ]]; then + grep -q "^XIAOMI_API_KEY=" "$HERMES_HOME/.env" 2>/dev/null \ + && ok "XIAOMI_API_KEY found" \ + || warn "XIAOMI_API_KEY missing in $HERMES_HOME/.env" +else + warn ".env not found — add XIAOMI_API_KEY before using web search" +fi + +# 2. Check httpx dependency +python3 -c "import httpx" 2>/dev/null && ok "httpx available" \ + || { fail "httpx not installed — run: pip install httpx"; exit 1; } + +# 3. Install plugin +mkdir -p "$PLUGIN_DIR" +cp "$SCRIPT_DIR/plugin.yaml" "$PLUGIN_DIR/plugin.yaml" +cp "$SCRIPT_DIR/__init__.py" "$PLUGIN_DIR/__init__.py" +cp "$SCRIPT_DIR/provider.py" "$PLUGIN_DIR/provider.py" +ok "Plugin installed → $PLUGIN_DIR" + +# 4. Copy test script +cp "$SCRIPT_DIR/test_search.py" "$HOME/test_search.py" +chmod +x "$HOME/test_search.py" +ok "Standalone test script → $HOME/test_search.py" + +# 5. Enable in Hermes +if command -v hermes &>/dev/null; then + hermes plugins enable web/mimo 2>/dev/null && ok "Enabled in Hermes" \ + || warn "Run manually: hermes plugins enable web/mimo" +else + warn "hermes not in PATH — run: hermes plugins enable web/mimo" +fi + +# 6. Done +echo "" +echo "── Next steps ──────────────────────────────────────" +echo " hermes config set web.search_backend mimo" +echo "" +echo " Install httpx: pip install httpx (if not already)" +echo "" +echo " Standalone test:" +echo " export XIAOMI_API_KEY=your-key-here" +echo " python3 ~/test_search.py \"search query\"" +echo "" +echo " /reset # restart session" +echo "────────────────────────────────────────────────────" -- cgit v1.3.1