Phase 0-2: Schema cleanup, typed relations, event-driven automation

- Phase 0: AGENTS.md cleanup (dedup quotes, renumber sections, merge qmd) - Phase 1: typed relations (manage-relations.py, graph-search.py, check-staleness.py, detect-conflicts.py) - Phase 2: frontmatter validator, weekly lint, knowledge promotion, git hooks - Fix .gitignore to track tools/ and .githooks/ - Fix git remote URL (remove plaintext token) - New wiki pages: 504 pages, 34 raw sources
2026-07-01 08:05:43 +08:00
parent e544d6e04a
commit a6f05ab2d5
1067 changed files with 522992 additions and 819 deletions
@@ -0,0 +1,216 @@
+# 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-架构/`