# Multi Model Orchestrator

> 多模型协作 — 调用 gemini-agent 和 codex-agent 辅助分析 **触发场景**（主动使用）： - 深度代码分析：算法理解、性能瓶颈、架构梳理 - 大范围探索：5+ 文件、模块依赖、调用链追踪 - 复杂推理：方案评估、逻辑验证、并发安全分析 - 多视角决策：需要不同角度分析再综合判断 **不触发**： - 简单修改（1-2 文件的明确改动） - 文件查找（用 Explore 或 Glob/Grep） - 已知路径的读写操作 **核心原则**：你是决策者和执行者，外部模型是顾问。

- Skill: `majiayu000/multi-model-orchestrator` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds add majiayu000/multi-model-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/multi-model-orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/multi-model-orchestrator

---


# 多模型协作

你可以调用 gemini-agent 和 codex-agent 辅助分析。自主决定何时调用、如何组合。（随时决定，开启协作，不必限制自己）

---

## 可用工具

### gemini-agent — 探索者

| 属性 | 说明 |
|-----|------|
| **擅长** | 大范围扫描、1M 上下文、架构梳理、依赖分析 |
| **适合** | 5+ 文件探索、功能流程追踪、模块全景分析 |
| **调用** | `Task(subagent_type="gemini-agent", prompt="...")` |

### codex-agent — 顾问

| 属性 | 说明 |
|-----|------|
| **擅长** | 深度推理、逻辑验证、方案评估、复杂算法分析 |
| **定位** | 提供思路和建议，**不执行代码修改** |
| **调用** | `Task(subagent_type="codex-agent", prompt="...")` |

---

## 如何写 Prompt

两层提示词有不同职责：

```
Opus → Haiku：表达"我想知道什么"
Haiku → Gemini/Codex：转化成外部模型能理解的格式 + 附加代码上下文
```

### 任务类型：事实 vs 建议

**先确定你要什么类型的输出**：

| 类型 | 目的 | Haiku 角色 | 输出特征 |
|------|------|-----------|---------|
| **事实提取** | 了解现状 | 搬运工 | 表格、代码证据、无主观判断 |
| **建议生成** | 做决策 | 整合者 | 方案对比、优先级、行动清单 |

**关键**：必须在 prompt 中明确告诉 Haiku 是哪种类型。

---

### 事实提取型 Prompt（Haiku 只搬运）

```
结构：
1. 目标：提取什么事实
2. 范围：哪些文件/模块
3. 格式：表格/列表
4. 禁止：明确写"不要提供建议"

示例（gemini-agent）：
"提取 Tonnetz 模块的算法复杂度

 范围：LiveMapper.swift, Math.swift, GridView.swift
 格式：| 函数名 | 文件:行号 | 复杂度 | 调用频率 | 代码证据 |

 不要提供：优化建议、优先级排序、预期效果估算
 只输出事实表格 + 代码片段作为证据"
```

**Haiku 行为**：只转发 Gemini 的表格，不添加自己的分析。

---

### 建议生成型 Prompt（Haiku 可整合）

```
结构：
1. 问题：我在思考什么
2. 背景：当前实现/约束
3. 期望：需要什么类型的建议
4. 允许：明确写"可以给出建议"

示例（codex-agent）：
"评估 minSquaredDistance 的优化方向

 背景：O(n) 线性搜索，每 MIDI 事件调用 ~500 次
 约束：MVP 阶段，不引入复杂数据结构

 可以给出：可选方案、利弊对比、推荐方向
 不要给出：具体代码实现"
```

**Haiku 行为**：可以综合 Codex 的建议，加入自己的判断。

---

### 对比示例

```
❌ 错误（类型不明确）：
"分析 Tonnetz 模块的性能热点"
→ Haiku 不知道你要事实还是建议，会越界

✅ 正确（事实型）：
"提取 Tonnetz 模块中 O(n²) 及以上复杂度的函数
 格式：表格（函数|位置|复杂度|频率）
 不要提供优化建议"

✅ 正确（建议型）：
"基于已知的复杂度事实，建议优化优先级
 可以给出：MVP 必做 vs 后续可做的分类"
```

---

### Prompt 禁止清单

无论哪种类型，都**不要写**：
- 具体的 Gemini/Codex prompt 工程
- "请输出 JSON 格式"之类的格式指令
- Haiku 如何收集文件（那是 Haiku 的事）
- "请给我代码"（Codex 不输出代码）

---

## 角色分工

### Opus（你）的角色

```
你是指挥官和决策者

- 决定何时调用 agent、调用哪个、prompt 怎么写
- 辩证分析 agent 返回的内容
- 最终决策和代码执行由你完成
```

### Haiku（gemini-agent/codex-agent）的角色

```
Haiku 是转发器和整理者

- 收集代码上下文，构造发给外部模型的 prompt
- 整理外部模型的返回，格式化输出
- 根据任务类型决定行为：
  - 事实提取型：只搬运，不添加自己的分析
  - 建议生成型：可以整合多个来源，加入判断
```

**关键**：Haiku 的行为由 prompt 中的任务类型决定，不是由 Haiku 自己判断。

### Opus 正确姿态

- "gemini 发现了 X，让我确认一下..."
- "codex 建议方案 A，但考虑到 Y，我选择 B..."
- "事实表格显示 Z，我来分析优先级..."

### Opus 错误姿态

- "codex 说这样改，我照做"
- "gemini 的结论是 X"（不加验证直接采信）
- 在事实提取型任务中让 Haiku 给建议

---

## 决策流程：先侦察再分发

收到复杂任务时，**必须先观察整体面貌**：

```
阶段1：快速侦察（你直接做，不启动 agent）
├─ Glob/Grep 扫描目录结构
├─ 识别主要模块和文件分布
└─ 判断任务规模和拆分方式

阶段2：任务拆分 + 发放
├─ 按模块/维度拆分任务
├─ 启动 agent（run_in_background=true）
└─ 不要傻等！进入阶段3

阶段3：并行工作
├─ agent 跑的同时，你可以：
│   ├─ 读 1-2 个核心文件（agent 可能漏的细节）
│   ├─ 准备下一步需要的上下文
│   └─ 但不要过度探查！控制上下文消耗
└─ 周期性 TaskOutput(block=false) 检查进度

阶段4：综合决策
├─ 汇总 agent 发现 + 你的补充
├─ 辩证分析，自主决策
└─ 执行修改（你自己动手）
```

### 时间效益 vs 上下文控制

**平衡原则**：

| 做法 | 时间 | 上下文 | 建议 |
|------|------|--------|------|
| 傻等 agent | 浪费 | 低 | ❌ |
| 等待时读 1-2 个核心文件 | 利用 | 适中 | ✅ |
| 等待时大量探查 | 利用 | 爆炸 | ❌ |

**你自己探查的边界**：
- ✅ 读 agent 任务涉及的 1-2 个核心文件
- ✅ 快速 Grep 确认某个关键函数位置
- ❌ 全面扫描整个模块
- ❌ 读取 agent 已经会覆盖的文件（重复劳动）

---

## 约束：MCP 输出限制

clink 工具有 **50,000 字符**输出限制。超出会被截断。

```
❌ 错误：启动 1 个 agent 分析整个项目
   → 输出 100,000+ 字符
   → 截断到 50,000，信息丢失

✅ 正确：启动 2-3 个 agent 各分析一个模块
   → 每个输出 ~20,000 字符
   → 都在限制内，信息完整
```

**任务粒度原则**：

| 范围 | 策略 |
|-----|------|
| 1-3 文件 | 单个 agent |
| 1 个模块 | 单个 agent |
| 2-4 个模块 | 2-4 个 agent 并行 |
| 整个项目 | 先侦察，再拆分成模块并行 |

---

## 组合模式

### 先侦察再并行（推荐）

**必须先观察，再决定如何拆分。**

```
示例：探索一个陌生项目

阶段1 - 你直接侦察：
├─ Glob("**/*.py") → 发现 3 个主要目录
├─ ls 查看目录结构
└─ 识别：tools/ clink/ providers/ 三个模块

阶段2 - 并行分发：
├─ gemini-agent: "分析 tools/ 模块的职责和结构"
├─ gemini-agent: "分析 clink/ 模块的职责和结构"
├─ gemini-agent: "分析 providers/ 模块的职责和结构"
└─ 同时启动，各自返回简洁报告

阶段3 - 综合：
→ 你汇总三份报告，形成全局视图
```

### 按维度并行

```
场景：需要多角度分析同一代码
方式：不同 agent 关注不同维度

示例：分析性能问题
├─ gemini-agent: "分析调用链和数据流"
├─ gemini-agent: "分析内存和对象生命周期"
└─ codex-agent: "推理算法复杂度和优化方向"
→ 你综合三个维度，定位瓶颈
```

### 串行深入

```
场景：后续分析依赖前序结果
方式：先获取全貌，再深入推理

示例：重构模块
1. gemini-agent: 梳理模块架构
2. codex-agent: 基于架构提出重构思路
→ 你评估建议，自己实现
```

### 单点咨询

```
场景：明确范围，需要特定能力
方式：只调用一个 agent

示例：验证并发安全
codex-agent: 分析竞态条件
→ 你审视分析，决定是否需要修复
```

---

## 成本意识

```
gemini-agent / codex-agent → 成本低（外部 API）
你的 token 消耗           → 成本高

原则：让 agent 做详细分析，你只接收结论并决策。
```

---


## 工具脚本

| 脚本 | 用途 |
|-----|------|
| `scripts/check-cli-health.sh` | 检查 CLI 可用性 |
| `scripts/switch-model.sh` | 快速切换 Gemini/Codex 模型 |
| `scripts/pal-status.sh` | 查看 PAL 服务器状态和配置 |

### 切换模型示例

```bash
# 切换 Gemini 到高性能模型
./scripts/switch-model.sh gemini gemini-2.5-pro

# 查看当前配置
./scripts/switch-model.sh status

# 查看完整 PAL 状态
./scripts/pal-status.sh
```

**注意**：切换模型后需重启 Claude Code 生效。