| name | multi-model-orchestrator |
| description | 多模型协作 — 调用 gemini-agent 和 codex-agent 辅助分析
**触发场景**（主动使用）：
- 深度代码分析：算法理解、性能瓶颈、架构梳理
- 大范围探索：5+ 文件、模块依赖、调用链追踪
- 复杂推理：方案评估、逻辑验证、并发安全分析
- 多视角决策：需要不同角度分析再综合判断
**不触发**：
- 简单修改（1-2 文件的明确改动）
- 文件查找（用 Explore 或 Glob/Grep）
- 已知路径的读写操作
**核心原则**：你是决策者和执行者，外部模型是顾问。
|
多模型协作
你可以调用 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 服务器状态和配置 |
切换模型示例
./scripts/switch-model.sh gemini gemini-2.5-pro
./scripts/switch-model.sh status
./scripts/pal-status.sh
注意：切换模型后需重启 Claude Code 生效。
