多模型协作

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

可用工具

gemini-agent — 探索者

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

codex-agent — 顾问

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

如何写 Prompt

两层提示词有不同职责：

code

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

任务类型：事实 vs 建议

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

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

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

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

code

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

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

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

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

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

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

code

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

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

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

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

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

对比示例

code

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

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

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

Prompt 禁止清单

无论哪种类型，都不要写：

•具体的 Gemini/Codex prompt 工程
•"请输出 JSON 格式"之类的格式指令
•Haiku 如何收集文件（那是 Haiku 的事）
•"请给我代码"（Codex 不输出代码）

角色分工

Opus（你）的角色

code

你是指挥官和决策者

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

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

code

Haiku 是转发器和整理者

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

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

Opus 正确姿态

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

Opus 错误姿态

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

决策流程：先侦察再分发

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

code

阶段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 字符输出限制。超出会被截断。

code

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

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

任务粒度原则：

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

组合模式

先侦察再并行（推荐）

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

code

示例：探索一个陌生项目

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

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

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

按维度并行

code

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

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

串行深入

code

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

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

单点咨询

code

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

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

成本意识

code

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 生效。