多模型协作

你可以调用 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 服务器状态和配置

切换模型示例

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

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

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

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