first commit

mlops/mimo-capabilities/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: mimo-capabilities
+description: MiMo 模型原生能力配置指南 - 图像理解、音频理解、视频理解、TTS 语音合成、网络搜索。当主模型为 MiMo 时使用这些方法。
+tags: [mimo, xiaomi, vision, audio, video, tts, search, multimodal]
+---
+
+# MiMo 模型原生能力配置指南
+
+## 概述
+
+MiMo 是小米研发的 AI 大模型，支持多种原生能力。当主模型为 MiMo 时，应使用 MiMo 的原生 API 而非第三方工具。
+
+## 模型感知路由规则
+
+**关键原则：根据当前主模型选择对应的方法**
+
+| 功能 | MiMo 模型 | MiniMax 模型 (mmx-cli) |
+|------|-----------|--------------|
+| 图像理解 | MiMo Vision API | `mmx vision describe` |
+| 音频理解 | MiMo Audio API | 不支持 |
+| 视频理解 | MiMo Video API | 不支持 |
+| TTS | MiMo TTS API | `mmx speech synthesize` |
+| 网络搜索 | MiMo Web Search API | `mmx search query` |
+| 图像生成 | 不支持 | `mmx image generate` |
+| 视频生成 | 不支持 | `mmx video generate` |
+| 音乐生成 | 不支持 | `mmx music generate` |
+
+## 1. 图像理解
+
+### 支持的模型
+- mimo-v2.5
+- mimo-v2-omni
+
+### 使用方法
+
+```bash
+python3 ~/.hermes/scripts/mimo_vision.py "https://example.com/image.jpg" "描述这张图片"
+python3 ~/.hermes/scripts/mimo_vision.py /path/to/image.png "这张图片里有什么？"
+```
+
+### 图片限制
+- 格式：JPEG, PNG, GIF, WebP, BMP
+- 大小：单张不超过 50MB
+
+## 2. 音频理解
+
+### 支持的模型
+- mimo-v2.5
+- mimo-v2-omni
+
+### 使用方法
+
+```bash
+python3 ~/.hermes/scripts/mimo_audio.py "https://example.com/audio.wav" "这段音频说了什么？"
+python3 ~/.hermes/scripts/mimo_audio.py /path/to/audio.mp3 "转录这段音频"
+```
+
+### 音频限制
+- 格式：MP3, WAV, FLAC, M4A, OGG
+- 大小：URL 不超过 100MB，Base64 不超过 50MB
+
+## 3. 视频理解
+
+### 支持的模型
+- mimo-v2.5
+- mimo-v2-omni
+
+### 使用方法
+
+```bash
+python3 ~/.hermes/scripts/mimo_video.py "https://example.com/video.mp4" "描述视频内容"
+python3 ~/.hermes/scripts/mimo_video.py /path/to/video.mp4 "视频里发生了什么？" --fps 2
+```
+
+### 参数说明
+- --fps: 每秒提取帧数，范围 0.1-10，默认 2
+- --resolution: default（默认）或 max（最高分辨率）
+
+### 视频限制
+- 格式：MP4, MOV, AVI, WMV
+- 大小：URL 不超过 300MB，Base64 不超过 50MB
+
+## 4. TTS 语音合成
+
+### 支持的模型
+
+| 模型 | 功能 |
+|------|------|
+| mimo-v2.5-tts | 内置音色，支持唱歌 |
+| mimo-v2.5-tts-voicedesign | 音色设计 |
+| mimo-v2.5-tts-voiceclone | 音色克隆 |
+
+### 内置音色列表
+- 中文：冰糖（默认）, 茉莉, 苏打, 白桦
+- 英文：Mia, Chloe, Milo, Dean
+
+### 使用方法
+
+```bash
+# 内置音色
+python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --voice 冰糖 --output output.wav
+
+# 音色设计（VoiceDesign）
+python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --design "年轻女性，温柔甜美" --output output.wav
+
+# 音色克隆（VoiceClone）
+python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --clone voice_sample.mp3 --output output.wav
+
+# 带风格指令
+python3 ~/.hermes/scripts/mimo_tts.py --text "你好世界" --voice 冰糖 --style "用欢快活泼的语气" --output output.wav
+```
+
+### VoiceDesign 音色设计详解
+
+通过自然语言描述从零生成全新音色，无需参考音频。
+
+**描述维度**（可自由组合）：
+- 性别年龄：年轻女性、中年男性、小女孩、年迈老先生
+- 口音语言：标准普通话、带北方口音、说英语
+- 音色特征：低沉有磁性、清脆明亮、温柔甜美、略带沙哑
+- 发声方式：像纪录片旁白、像新闻主播、声音位置靠后
+- 性格气质：沉稳而有感染力、元气满满、饱经风霜
+
+**高级特性**：
+- 对复杂、模糊、甚至相互矛盾的描述也能合理解读
+- 不局限于"男/女/青年/老年"粗粒度标签
+- 适合游戏NPC、动画角色、虚拟主播、品牌IP、有声剧
+
+**示例**：
+```
+--design "一位年迈的老先生，说带北方口音的普通话，语速缓慢而沉稳，嗓音略带沙哑和沧桑感，仿佛一位饱经风霜的老爷爷在讲故事，充满岁月的智慧。"
+```
+
+### VoiceClone 音色克隆详解
+
+只需短至数秒的参考音频，无需训练/标注/微调，直接复刻音色。
+
+**保留的特征**：
+- 原始说话人的音色身份
+- 气息、节奏、习惯性停顿等个人特征
+
+**复用能力**：克隆后的音色可叠加使用全部控制能力（自然语言指令、音频标签、导演剧本）
+
+**示例**：
+```
+# 提供参考音频 + 风格指令
+--clone reference.mp3 --style "用尖锐刻薄的嗓音，带着狐假虎威的得意感"
+```
+
+### 风格控制标签（行内音频标签）
+
+在文本中用括号插入标签，精准控制情绪/状态/风格：
+
+**标签类型**：
+- 基础情感：开心、悲伤、生气、害怕、惊讶、兴奋
+- 复杂情感：忧郁、释然、无奈、内疚、嫉妒、疲惫
+- 整体语调：温柔、冷淡、活泼、严肃、慵懒、俏皮
+- 音色定位：磁性、醇厚、清亮、空灵、天真、甜美
+- 方言：东北话、四川话、河南话、粤语
+- 唱歌：唱歌（必须放在最开头）
+
+**高级用法**：
+- 支持中英双语标签
+- 支持多标签叠加（用 `｜` 分隔）
+- 支持开放文本描述
+
+**示例**：
+```
+(调侃) 老张你当时不是说这条航线稳得很吗……
+(模仿自信，提高音量) "系统全绿，放心走。"
+(突然停顿) ……现在呢？
+(爆发，愤怒压不住) 现在整艘船都在报警！
+(低声｜情绪塌陷般平静) ……算了。
+(轻笑｜带点释然) 也挺好，至少是一起看的。
+```
+
+### 导演剧本级结构化输入
+
+对于一致性要求高的场景（有声剧、游戏NPC、角色化对话），支持分层描述：
+
+```bash
+python3 ~/.hermes/scripts/mimo_tts.py \
+  --text "你们求我垂怜..." \
+  --voice 白桦 \
+  --style "CHARACTER: 曾是守护九天的神祇，见证了凡人的无药可救后，决定以灭世来完成最终的净化。
+SCENE: 悬浮于崩塌的祭坛之上，俯视下方在火海中哀嚎的信徒。
+DIRECTION: 充分打开胸腔共鸣，声音位置靠后，音色如古钟般低沉且带有金属质感的磁性。" \
+  --output output.wav
+```
+
+**分层说明**：
+- CHARACTER：人物身份、背景、性格
+- SCENE：场景环境、情境
+- DIRECTION：详细的发声指导（共鸣、语调、气声、咬字等）
+
+### TTS API 要点
+1. 合成文本必须放在 assistant 角色的 content 中
+2. user 角色消息可选，用于传递风格指令
+3. 流式调用时输出格式指定为 pcm16
+
+## 5. 网络搜索
+
+### 支持的模型
+- mimo-v2.5-pro, mimo-v2.5, mimo-v2-pro, mimo-v2-omni, mimo-v2-flash
+
+### 前置条件
+在 MiMo Console 启用 Web Search 插件。
+
+### 使用方法
+
+```bash
+python3 ~/.hermes/scripts/mimo_search.py "武汉明天天气"
+python3 ~/.hermes/scripts/mimo_search.py "附近美食" --city 武汉 --region 湖北
+```
+
+### 参数说明
+- --max-keywords: 每轮搜索最大关键词数，默认 3
+- --force/--no-force: 是否强制搜索，默认强制
+- --limit: 搜索结果数量，默认 1
+- --country/--region/--city: 本地化搜索位置
+
+## 环境变量
+
+```bash
+XIAOMI_API_KEY=tp-xxxxx
+XIAOMI_BASE_URL=https://token-plan-sgp.xiaomimimo.com/v1
+```
+
+**注意**：环境变量需持久化到 `~/.bashrc`，否则新 terminal session 会丢失。
+
+## ⚠️ 图片输入配置（关键）
+
+MiMo chat API **不支持图片输入**。用户发图片时，如果 Hermes 把图片直接塞进 chat completions 请求，会返回 `404: No endpoints found that support image input`。
+
+### 必须设置 `image_input_mode: tool`
+
+```bash
+hermes config set agent.image_input_mode tool
+```
+
+- `auto`（默认）= 尝试直接把图片发给主模型 → MiMo 会 404
+- `tool` = 强制图片走 vision 工具 → 正确路由到 MiMo Vision API
+
+### Vision API Key 必须显式写入 config
+
+`XIAOMI_API_KEY` 环境变量**不会**自动传给 Hermes vision 工具。必须手动填入 config。
+
+**有两个 vision section 都需要 API key：**
+
+| 路径 | 用途 |
+|------|------|
+| `auxiliary.vision.api_key` | 主 vision 工具配置（含 provider/model/base_url） |
+| `tools.vision.api_key` | 工具层 vision 配置 |
+
+```bash
+# 方法：从 .bashrc 提取 key 并写入（hermes config set 无法展开未 source 的环境变量）
+python3 << 'EOF'
+import yaml
+key = open('/home/ubuntu/.bashrc').read().split('XIAOMI_API_KEY=')[1].split('\n')[0].strip().strip('"').strip("'")
+with open('/home/ubuntu/.hermes/config.yaml') as f:
+    config = yaml.safe_load(f)
+config['auxiliary']['vision']['api_key'] = key
+config['tools']['vision']['api_key'] = key
+with open('/home/ubuntu/.hermes/config.yaml', 'w') as f:
+    yaml.dump(config, f, default_flow_style=False, allow_unicode=True)
+print(f'Done. Key set: {key[:10]}...')
+EOF
+```
+
+## ⚠️ 常见问题排查
+
+### 401 Unauthorized / Invalid API Key
+1. **检查 base URL**：脚本默认值可能过时。正确 URL 是 `https://token-plan-sgp.xiaomimimo.com/v1`，不是 `https://api.xiaomimimo.com/v1`。
+2. **检查 header 格式**：MiMo API 使用 `Authorization: Bearer <key>`，而非 `api-key` header。
+3. **验证方式**：
+   ```bash
+   curl -s https://token-plan-sgp.xiaomimimo.com/v1/chat/completions \
+     -H "Content-Type: application/json" \
+     -H "Authorization: Bearer $XIAOMI_API_KEY" \
+     -d '{"model":"mimo-v2.5-tts","messages":[{"role":"assistant","content":"你好"}],"audio":{"format":"wav","voice":"冰糖"}}'
+   ```
+
+### 404: No endpoints found that support image input
+MiMo chat API 不支持图片输入。用户发图片时 Hermes 尝试直接塞进请求导致。
+**修复**：`hermes config set agent.image_input_mode tool`，并确保 vision API key 已配置（见上方"图片输入配置"章节）。
+
+### 脚本报 "No API key found"
+确认环境变量已 export：`echo $XIAOMI_API_KEY`。如果为空，添加到 `~/.bashrc` 并 `source ~/.bashrc`。
+
+**注意**：Hermes 的 config.yaml 中可能已配置了 API key（`auxiliary.vision.api_key` 或 provider 的 `api_key`），但这个 key 不会自动 export 到 shell 环境变量。脚本依赖 `XIAOMI_API_KEY` 环境变量，二者是独立的。
+
+**快速恢复方法**：从 config.yaml 提取 key 并 export：
+```bash
+export XIAOMI_API_KEY=$(python3 -c "import yaml; c=yaml.safe_load(open('/home/ubuntu/.hermes/config.yaml')); print(c.get('auxiliary',{}).get('vision',{}).get('api_key',''))")
+```
+
+### 网络搜索 400 Bad Request
+`mimo_search.py` 可能因 API 端点变更或参数格式问题返回 400。排查步骤：
+1. 先用 curl 直接测试 API 是否可达：`curl -s -o /dev/null -w "%{http_code}" https://token-plan-sgp.xiaomimimo.com/v1/models -H "Authorization: Bearer $XIAOMI_API_KEY"`
+2. 如果网络不通（`Network is unreachable`），是服务器出站网络问题，不是 API 问题
+3. 如果网络通但 400，检查请求体格式是否与最新 API 兼容
+
+### mmx search 不可用
+`mmx search query` 需要 MiniMax Token Plan 支持 `coding-plan-search` 模型。如果报错 "your current token plan not support model, coding-plan-search"，说明当前 plan 不包含搜索能力。替代方案：
+- 使用 MiMo 网络搜索（如果可用）
+- 使用 Playwright 浏览器抓取
+- 使用 `curl` 直接请求搜索引擎（注意服务器出站网络限制）
+
+## References
+
+- `references/sensenova-api.md` — SenseNova API 配置、模型列表、限流策略、已安装 skills 绑定情况
+- `references/mimo-v2.5-tts-official-doc.md` — MiMo-V2.5-TTS Series 官方文档摘要（VoiceDesign/VoiceClone/导演剧本详解）
+
+## 脚本位置
+
+所有 MiMo 辅助脚本位于 ~/.hermes/scripts/：
+- mimo_vision.py - 图像理解
+- mimo_audio.py - 音频理解
+- mimo_video.py - 视频理解
+- mimo_tts.py - TTS 语音合成
+- mimo_search.py - 网络搜索

mlops/mimo-capabilities/references/mimo-v2.5-tts-official-doc.md

@@ -0,0 +1,65 @@
+# MiMo-V2.5-TTS Series 官方文档摘要
+
+来源：https://platform.xiaomimimo.com/docs/zh-CN/news/v2.5-tts-release
+
+## 三款模型
+
+| 模型 | 用途 | 特点 |
+|------|------|------|
+| MiMo-V2.5-TTS | 内置精品音色 | 开箱即用，支持语速、情绪、语气精细控制 |
+| MiMo-V2.5-TTS-VoiceDesign | 音色设计 | 一句话定义全新音色，无需参考音频 |
+| MiMo-V2.5-TTS-VoiceClone | 音色克隆 | 少量样本高保真复刻，支持风格叠加 |
+
+## 核心能力
+
+### 1. 精准风格指令遵循
+- 从简短单句指令到整份导演笔记都能稳定理解
+- 支持情绪、语气、语速、发声方式、语言风格等多维度
+- 像给演员说戏一样描述，模型会落到对应演绎
+
+### 2. 灵活音频标签控制
+- 行内标签控制情绪、状态、风格
+- 支持中英双语和开放文本描述
+- 支持多标签叠加（用 `｜` 分隔）
+
+### 3. 丰富文本理解
+- 无 prompt 也能自动捕捉情感弧线
+- 自动识别说话人身份（年龄、气质、角色类型）
+
+## VoiceDesign 详情
+
+**适用场景**：游戏NPC、动画角色、虚拟主播、品牌IP、有声剧的非典型嗓音
+
+**描述维度**：
+- 年龄、性别、口音、音质、发声方式、性格气质
+- 支持复杂、模糊、甚至相互矛盾的描述
+- 不局限于"男/女/青年/老年"粗粒度标签
+
+**案例**：
+- "一位中年男性，说标准普通话，嗓音低沉有磁性，带有轻微的沙哑质感，像纪录片旁白解说员"
+- "一位年迈的老先生，说带北方口音的普通话，语速缓慢而沉稳，嗓音略带沙哑和沧桑感"
+
+## VoiceClone 详情
+
+**特点**：
+- 短至数秒参考音频，无需训练/标注/微调
+- 保留音色身份 + 气息、节奏、习惯性停顿
+- 复用全部控制能力（指令、标签、导演剧本）
+
+**案例**：
+- 参考音频 → 克隆音色 → 叠加风格指令（"用尖锐刻薄的嗓音，带着狐假虎威的得意感"）
+
+## 导演剧本级输入
+
+支持 CHARACTER/SCENE/DIRECTION 分层：
+- CHARACTER：人物身份、背景、性格
+- SCENE：场景环境、情境
+- DIRECTION：详细发声指导（共鸣、语调、气声、咬字）
+
+## 相关资源
+
+- MiMo Studio：https://aistudio.xiaomimimo.com/#/c
+- 使用指南：https://platform.xiaomimimo.com/docs/usage-guide/speech-synthesis-v2.5
+- Skills 开源：https://github.com/XiaomiMiMo/MiMo-Skills
+- ASR 开源：https://github.com/XiaomiMiMo/MiMo-V2.5-ASR
+- 更多案例：https://mimo.xiaomi.com/mimo-v2-5-tts

mlops/mimo-capabilities/references/sensenova-api.md

@@ -0,0 +1,61 @@
+# SenseNova API 配置
+
+## 基本信息
+
+| 字段 | 值 |
+|------|-----|
+| Base URL | `https://token.sensenova.cn/v1` |
+| API Key | 存储在 `~/.hermes/.env` 的 `SN_API_KEY` |
+| 协议 | OpenAI 兼容 |
+
+## 可用模型
+
+| 模型 | MODEL ID | 用途 | 调用限制 |
+|------|----------|------|----------|
+| SenseNova 6.7 Flash-Lite | `sensenova-6.7-flash-lite` | 多模态智能体（文本+图像理解+工具调用） | 每 5 小时 1500 次 |
+| SenseNova U1 Fast | `sensenova-u1-fast` | 信息图生成专用 | 每 5 小时 1500 次 |
+| DeepSeek V4 Flash | `deepseek-v4-flash` | 高性能对话（思考/非思考模式、256K 上下文） | 每 5 小时 150 次 |
+
+## 注意事项
+
+- **限流策略**：按 5 小时窗口计数，不是按分钟
+- **DeepSeek 限流最严**：只有 150 次/5小时，是其他模型的 1/10，深度研究等高频场景建议用 sensenova-6.7-flash-lite
+- **sensenova-6.7-flash-lite 支持图像输入**：可传 `image_url` 类型的 content 块
+- **上下文长度**：256K tokens（最大输入 252K，最大输出 64K）
+- **sensenova-u1-fast** 是图像生成专用，不支持对话接口
+
+## 调用示例
+
+```bash
+curl https://token.sensenova.cn/v1/chat/completions \
+  -H "Authorization: Bearer $SN_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "sensenova-6.7-flash-lite",
+    "messages": [{"role": "user", "content": "你好"}],
+    "max_tokens": 500,
+    "reasoning_effort": "none"
+  }'
+```
+
+## 已安装的 SenseNova Skills
+
+| Skill | 厂商绑定 | 说明 |
+|-------|----------|------|
+| sn-image-base | 🔗 绑定 SenseNova | 图像生成/识别/文本优化，调用 SenseNova 专用 API |
+| sn-infographic | 🔗 绑定 SenseNova | 信息图生成，依赖 sn-image-base |
+| sn-deep-research | 🔄 可替换 | 深度研究编排，纯 LLM 调用 |
+| sn-research-planning | 🔄 可替换 | 研究规划 |
+| sn-dimension-research | 🔄 可替换 | 单维度取证 |
+| sn-research-synthesis | 🔄 可替换 | 综合判断 |
+| sn-research-report | 🔄 可替换 | 终稿写作/改写 |
+| sn-report-format-discovery | 🔄 可替换 | 报告形态发现 |
+| sn-md-to-html-report | 🔄 可替换 | Markdown 转 HTML 阅读视图 |
+| sn-search-academic | 🔄 可替换 | 学术搜索（ArXiv/Semantic Scholar/PubMed/Wikipedia） |
+| sn-search-code | 🔄 可替换 | 开发者搜索（GitHub/Stack Overflow/Hacker News/HuggingFace） |
+| sn-search-social-cn | 🔄 可替换 | 中文社交搜索（B站/知乎/抖音） |
+| sn-search-social-en | 🔄 可替换 | 英文社交搜索（Reddit/Twitter/YouTube） |
+
+## 免费套餐
+
+在 [SenseNova 控制台 token-plan](https://platform.sensenova.cn/token-plan) 申请。