// 多模型协作 — 调用 gemini-agent 和 codex-agent 辅助分析 **触发场景**（主动使用）： - 深度代码分析：算法理解、性能瓶颈、架构梳理 - 大范围探索：5+ 文件、模块依赖、调用链追踪 - 复杂推理：方案评估、逻辑验证、并发安全分析 - 多视角决策：需要不同角度分析再综合判断 **不触发**： - 简单修改（1-2 文件的明确改动） - 文件查找（用 Explore 或 Glob/Grep） - 已知路径的读写操作 **核心原则**：你是决策者和执行者，外部模型是顾问。
项目架构约定：通过 Root/Folder/File 三层极简元数据（_dir.md + I/O/Pos 注释） 让 AI 在任意位置自定位。 **AI 创建文件夹时自动触发**：hook 会生成 _dir.md 模板，AI 填写 Input/Output/Pos。
在编写、更新、维护 roadmap.md 的时候触发
代码风格规范 / Code style conventions。在编写、编辑、评审 Python 代码时使用。包括类型注解、Decimal 精度、Docstring、模块组织等规范。Use when writing, editing, or reviewing Python code. Enforces type hints, Decimal precision, docstrings, and module organization.
分层架构规范 / Architecture and layering rules (v0.3.1)。在设计新组件、修改导入、检查分层时使用。核心约束：cli → flows → data，core 向内不向外。Use when designing components, changing imports, or reviewing layering decisions. Enforces cli/flows/core/data separation.
命名规范 / Naming conventions。在创建类、函数、变量，或重命名、检查命名时使用。核心原则：简洁优先，上下文消歧义，类型提示已提供足够信息。Use when naming classes/functions/variables, renaming code, or reviewing names. Prioritizes brevity over self-documentation.
用于梳理和可视化代码流程，生成清晰的 ASCII 流程图、数据流图和表格分析。适用于已有代码的梳理、新功能设计的说明、以及技术文档的编写。
| name | multi-model-orchestrator |
| description | 多模型协作 — 调用 gemini-agent 和 codex-agent 辅助分析 **触发场景**（主动使用）： - 深度代码分析：算法理解、性能瓶颈、架构梳理 - 大范围探索：5+ 文件、模块依赖、调用链追踪 - 复杂推理：方案评估、逻辑验证、并发安全分析 - 多视角决策：需要不同角度分析再综合判断 **不触发**： - 简单修改（1-2 文件的明确改动） - 文件查找（用 Explore 或 Glob/Grep） - 已知路径的读写操作 **核心原则**：你是决策者和执行者，外部模型是顾问。 |
你可以调用 gemini-agent 和 codex-agent 辅助分析。自主决定何时调用、如何组合。（随时决定，开启协作，不必限制自己）
| 属性 | 说明 |
|---|---|
| 擅长 | 大范围扫描、1M 上下文、架构梳理、依赖分析 |
| 适合 | 5+ 文件探索、功能流程追踪、模块全景分析 |
| 调用 | Task(subagent_type="gemini-agent", prompt="...") |
| 属性 | 说明 |
|---|---|
| 擅长 | 深度推理、逻辑验证、方案评估、复杂算法分析 |
| 定位 | 提供思路和建议，不执行代码修改 |
| 调用 | Task(subagent_type="codex-agent", prompt="...") |
两层提示词有不同职责：
Opus → Haiku：表达"我想知道什么"
Haiku → Gemini/Codex：转化成外部模型能理解的格式 + 附加代码上下文
先确定你要什么类型的输出：
| 类型 | 目的 | Haiku 角色 | 输出特征 |
|---|---|---|---|
| 事实提取 | 了解现状 | 搬运工 | 表格、代码证据、无主观判断 |
| 建议生成 | 做决策 | 整合者 | 方案对比、优先级、行动清单 |
关键：必须在 prompt 中明确告诉 Haiku 是哪种类型。
结构：
1. 目标：提取什么事实
2. 范围：哪些文件/模块
3. 格式：表格/列表
4. 禁止：明确写"不要提供建议"
示例（gemini-agent）：
"提取 Tonnetz 模块的算法复杂度
范围：LiveMapper.swift, Math.swift, GridView.swift
格式：| 函数名 | 文件:行号 | 复杂度 | 调用频率 | 代码证据 |
不要提供：优化建议、优先级排序、预期效果估算
只输出事实表格 + 代码片段作为证据"
Haiku 行为：只转发 Gemini 的表格，不添加自己的分析。
结构：
1. 问题：我在思考什么
2. 背景：当前实现/约束
3. 期望：需要什么类型的建议
4. 允许：明确写"可以给出建议"
示例（codex-agent）：
"评估 minSquaredDistance 的优化方向
背景：O(n) 线性搜索，每 MIDI 事件调用 ~500 次
约束：MVP 阶段，不引入复杂数据结构
可以给出：可选方案、利弊对比、推荐方向
不要给出：具体代码实现"
Haiku 行为：可以综合 Codex 的建议，加入自己的判断。
❌ 错误（类型不明确）：
"分析 Tonnetz 模块的性能热点"
→ Haiku 不知道你要事实还是建议，会越界
✅ 正确（事实型）：
"提取 Tonnetz 模块中 O(n²) 及以上复杂度的函数
格式：表格（函数|位置|复杂度|频率）
不要提供优化建议"
✅ 正确（建议型）：
"基于已知的复杂度事实，建议优化优先级
可以给出：MVP 必做 vs 后续可做的分类"
无论哪种类型，都不要写：
你是指挥官和决策者
- 决定何时调用 agent、调用哪个、prompt 怎么写
- 辩证分析 agent 返回的内容
- 最终决策和代码执行由你完成
Haiku 是转发器和整理者
- 收集代码上下文，构造发给外部模型的 prompt
- 整理外部模型的返回，格式化输出
- 根据任务类型决定行为：
- 事实提取型：只搬运，不添加自己的分析
- 建议生成型：可以整合多个来源，加入判断
关键：Haiku 的行为由 prompt 中的任务类型决定，不是由 Haiku 自己判断。
收到复杂任务时，必须先观察整体面貌：
阶段1：快速侦察（你直接做，不启动 agent）
├─ Glob/Grep 扫描目录结构
├─ 识别主要模块和文件分布
└─ 判断任务规模和拆分方式
阶段2：任务拆分 + 发放
├─ 按模块/维度拆分任务
├─ 启动 agent（run_in_background=true）
└─ 不要傻等！进入阶段3
阶段3：并行工作
├─ agent 跑的同时，你可以：
│ ├─ 读 1-2 个核心文件（agent 可能漏的细节）
│ ├─ 准备下一步需要的上下文
│ └─ 但不要过度探查！控制上下文消耗
└─ 周期性 TaskOutput(block=false) 检查进度
阶段4：综合决策
├─ 汇总 agent 发现 + 你的补充
├─ 辩证分析，自主决策
└─ 执行修改（你自己动手）
平衡原则：
| 做法 | 时间 | 上下文 | 建议 |
|---|---|---|---|
| 傻等 agent | 浪费 | 低 | ❌ |
| 等待时读 1-2 个核心文件 | 利用 | 适中 | ✅ |
| 等待时大量探查 | 利用 | 爆炸 | ❌ |
你自己探查的边界：
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 生效。