# CLI / MCP / Skill 三层架构关系

## 一句话说明

- **CLI** = 底层程序，在 terminal 里执行
- **MCP Server** = 通过 MCP 协议暴露工具，LLM 直接调用
- **Skill** = 使用说明书，告诉 LLM 什么时候、怎么调用前两者

---

## 架构图

```
┌──────────────────────────────────────────────────┐
│  Skill (SKILL.md)                               │
│  作用：告诉 LLM 怎么用工具                        │
│  - 何时用它（触发条件）                           │
│  - 用什么命令/参数                                │
│  - 典型示例                                      │
│  不是程序，是"使用手册"                           │
└──────────────────────┬───────────────────────────┘
                       │ 被 LLM 读取
        ┌──────────────▼───────────────┐
        │  MCP Server                   │
        │  LLM 通过 MCP 协议直接调用      │
        │  结果结构化返回给 LLM           │
        │  无需写命令，LLM 自己组织调用    │
        └──────────────┬───────────────┘
                       │ MCP 协议 / 工具调用
        ┌──────────────▼───────────────┐
        │  CLI / 外部服务               │
        │  底层执行程序                  │
        │  mmx / npx / curl / gh 等    │
        └───────────────────────────────┘
```

**关键理解：Skill 和 MCP 是不同层次的东西，不互斥。**

- **有 MCP 无 Skill**：LLM 可能不知道怎么用
- **有 Skill 无 MCP**：LLM 知道怎么用但没有工具可用
- **有 Skill + MCP**：LLM 知道怎么用且能直接调用 ✅

---

## 当前环境概览

```
MCP Servers:   6 个
Skills:        93 个（含 MiniMax/GLM 相关 10+ 个）
CLI 工具:      mmx / hermes / gh / git / curl / npx 等
主模型:        MiniMax-M2.7 (minimax-cn)
备选模型:      GLM-4.7 (zai, GLM Coding Plan)
```

---

## 当前 MCP Servers

| Server | 协议 | 功能 | Skill |
|--------|------|------|-------|
| `hermes-docs` | HTTPS | Hermes 中文文档搜索/读取 | — |
| `minimax-token` | npx (stdio) | MiniMax Coding Plan 编程辅助（代码补全/搜索） | `minimax` |
| `zread` | npx (stdio) | 通用网页读取 | — |
| `glm-reader` | HTTP Stream | GLM 网页内容读取（markdown/text） | `glm-reader` |
| `glm-search` | HTTP Stream | GLM 网络搜索（返回标题/URL/摘要） | `glm-search` |
| `zai-vision` | npx (stdio) | GLM-4.6V 图片理解/截图分析/视频解析 | `zai-vision` |

### 关系说明

```
glm-search  ──MCP──  LLM 直接调用搜索网页
glm-reader  ──MCP──  LLM 直接调用读网页内容
zai-vision  ──MCP──  LLM 直接调用理解图片/视频
minimax-token  ──MCP──  LLM 直接调用编程辅助（不是搜索/图片）
hermes-docs  ──MCP──  LLM 直接调用查 Hermes 文档
zread  ──MCP──  LLM 直接调用读网页
```

---

## 当前 Skills（重点分组）

### 🔵 MiniMax 相关（mmx CLI + MCP）

| Skill | 功能 | 底层 |
|-------|------|------|
| `minimax` | 全能力汇总：图/视频/音乐/语音/搜索 | mmx-cli |
| `minimax-image` | 文生图（MiniMax Image 01） | mmx CLI `mmx image` |
| `minimax-video` | 文生视频（Hailuo 2.3） | mmx CLI `mmx video` |
| `minimax-music` | 文生音乐（Music 2.6） | mmx CLI `mmx music` |
| `minimax-speech` | 语音合成（Speech 2.8 HD） | mmx CLI `mmx speech synthesize` |
| `minimax-search` | 网络搜索 | mmx CLI `mmx web` |

**关系：**
- Skill 告诉 LLM：`mmx image "描述"` 可以生成图片
- mmx CLI 是实际执行程序（已认证，可直接用）
- `minimax-coding-plan-mcp` 是另一个 MCP，提供编程辅助能力

### � eco9; 🟢 GLM 相关（MCP 直接暴露）

| Skill | 功能 | 底层 |
|-------|------|------|
| `glm-search` | 网络搜索 | `glm-search` MCP |
| `glm-reader` | 网页内容读取 | `glm-reader` MCP |
| `glm-coding-plan` | GLM 全能力汇总（搜索/读页/图/视频理解） | GLM MCP 组合 |
| `zai-vision` | 图片/截图/视频理解 | `zai-vision` MCP |

**关系：**
- 全是 MCP 直接暴露，无独立 CLI
- LLM 通过 MCP 协议直接调用这些工具
- Skill 告诉 LLM 工具的用法和适用场景

### 🟡 其他常用 Skills

| Skill | 功能 |
|-------|------|
| `hermes-onboarding` | Hermes 学习路径（Phase 1-5） |
| `hermes-agent` | Hermes 自身配置/扩展 |
| `subagent-driven-development` | delegate_task 并行任务编排 |
| `jupyter-live-kernel` | 交互式 Python（数据科学） |
| `arxiv` | 学术论文搜索 |
| `youtube-content` | YouTube 字幕→摘要/文章 |
| `spotify` | Spotify 控制（播放/搜索/歌单） |
| `github-pr-workflow` | GitHub PR 完整流程 |
| `openhue` | 飞利浦 Hue 智能灯光控制 |
| `xurl` | X/Twitter 发推/搜索/DM |

---

## 当前 CLI 工具

| CLI | 功能 |
|-----|------|
| `mmx` | MiniMax Token Plan 全能力入口（图/视频/音乐/语音/搜索），v1.0.13 |
| `hermes` | Hermes Agent 自身管理（config/cron/mcp/skills 等） |
| `gh` | GitHub CLI（需确认已安装） |
| `git` | 版本控制 |
| `curl` | HTTP 请求 |
| `npx` | 运行 npm 包（MCP servers 用） |

---

## 使用场景对照

### 场景 1：让 LLM 搜索网页

**MCP 路线（直接）：**
```
LLM → glm-search MCP tool → 返回搜索结果
需要 skill glm-search 告诉 LLM 怎么用
```

**CLI 路线（间接）：**
```
LLM → terminal → mmx web "关键词" → 解析输出
需要 skill minimax-search 告诉 LLM 命令格式
```

### 场景 2：生成一张图片

**CLI 路线（实测）：**
```bash
mmx image "一只橘色的猫在打哈欠" --out /tmp/cat.png
```
skill `minimax-image` 告诉 LLM 这个命令格式。

**MCP 路线：**
当前无原生图片生成 MCP，通过 mmx CLI 走 skill 路线。

### 场景 3：理解一张图片

**MCP 路线：**
```
LLM → zai-vision MCP tool → 返回图片描述/分析
skill zai-vision 告诉 LLM 工具用法
```

### 场景 4：写好笔记让 LLM 记住

**Skill 路线：**
```
skill minimax-image → 告诉 LLM 用 mmx image 生成图片
skill glm-search → 告诉 LLM 用 glm-search MCP 搜索
```

---

## 认证状态

```bash
$ mmx auth status
→ method: api-key, 已认证 ✅

$ hermes mcp list
→ 6 个 MCP servers，全部 enabled ✅

$ hermes config get tts.provider
→ minimax ✅（语音已配置）
```

---

## 常见误区

1. **"有了 Skill 就不需要 MCP"** — 错。Skill 是文档，MCP 是工具，缺一不可。
2. **"有了 MCP 就不需要 Skill"** — 错。LLM 需要 Skill 告诉它什么时候用、怎么描述参数。
3. **"MiniMax MCP 就是 mmx CLI"** — 错。`minimax-coding-plan-mcp` 是另一个工具，提供编程辅助，和 `mmx image` 等 CLI 命令是不同的东西。
4. **"配置了 Skill 就自动能用"** — 错。Skill 只是文档，底层程序必须可用（MCP server 在线，或 CLI 已安装认证）。

---

## 文件位置

- Skills：`~/.hermes/skills/`
- MCP 配置：`~/.hermes/config.yaml` → `mcp_servers:`
- Obsidian 笔记：`/home/obsidian/wiki/03-工具/layer-架构/`