来源：GitHub (★677)
URL: https://github.com/Nanako0129/pilotfish
精读日期：2026-08-28
模型：DeepSeek V4 Flash（AI 生成，人工未审校）
正文获取：全文

一、核心论点/事实

  • pilotfish 是 Claude Code 的多模型编排层：前沿模型（Opus）负责规划、审批、集成与最终判断，廉价模型（Sonnet/Haiku）执行有界任务，验证环节保障质量。
  • 核心动机：大多数编码会话 token 消耗在搜索、重复编辑、测试和文档上，而非前沿判断；将这些有界路径路由到廉价模型可显著降本。
  • 采用 hook 驱动的环境激活机制，支持一键安装；全局配置安装仍是可选方案，属于成本感知的默认策略，而非声称单一模型在所有任务上胜出。
  • 提供两种安装路径：Plugin beta（基于 Claude Code 原生 Plugin 生命周期）与 legacy 全局安装（直接目标配置）。
  • 路由策略（pilotfish-codex 自适应意图路由）：结果或验收不明确时用主会话；方向宽泛或高影响时用主会话；有清晰有界结果时才委派给角色代理。
  • 风险（而非文件数量）触发独立审查；安全敏感工作由 security-reviewer 在审批前做只读证据收集，security-executor 执行已批准的敏感实现。
  • 实验性 beta 仅支持 macOS 与 Linux（Ubuntu 20.04+ / Debian 10+ / Alpine 3.19+），Windows 被排除；macOS 已实测（Claude Code 2.1.239），Linux 仅契约级验证、未实测。

二、方法/架构拆解

  • 角色代理（Role Agents）设计：
  • main session：Opus 家族别名，负责规划、审批、集成、最终判断。
  • explorer / co_discover：只读大范围搜索，不继承主模型上下文。
  • security-reviewer：审批前只读安全证据收集。
  • security-executor：已批准的安全敏感实现，需本地判断。
  • verifier：实现后以全新上下文做结果证伪（CONFIRMED / REFUTED / INCONCLUSIVE）。
  • 路由决策流程：在 Baton 或直接/委派路由之前，pilotfish 按优先级选择首个匹配策略——主会话处理不明确或高影响任务，委派仅在有稳定契约且净收益为正时触发。
  • 生命周期控制：指令可抑制 Agent 派发，用户级覆盖优先；关键生命周期场景需显式请求 "Use pilotfish. Follow its dispatch brake..."。
  • 安装与迁移：支持用户级 marketplace 命令、从 global v1 迁移、更新、禁用/启用、卸载与回滚；要求 SessionStart hooks，Plugin 不得与 legacy 全局安装共存。
  • 安装步骤：克隆 v1.4.1 发布版（git clone --branch v1.4.1 --depth 1），读取 install/AGENT-INSTALL.md，展示完整变更计划并获用户批准后写入；安装后需重启以重载 agent 目录与模型设置。
  • 基准与测量：rationale 与 measurements 存放于仓库文档（文中未给出具体数字，需查阅仓库）。

三、值得注意的局限/争议

作者承认的局限：

  • beta 不声称稳定可靠性、跨版本兼容性或运行时命名空间冲突防护。
  • Linux 仅契约级合格，未经测试、验证或实测；Windows 完全排除。
  • 成本感知默认策略是行为观察记录，不是派发率指标或活跃用户规模的证明。
  • Plugin 与 legacy 全局安装不得共存，存在安装路径冲突风险。

AI 判断的局限/争议：

  • 路由决策依赖"有界任务"的清晰定义，实际编码中边界模糊时可能频繁回退主会话，削弱降本效果。
  • verifier 使用全新上下文做证伪，但未说明验证覆盖范围（如测试深度、静态分析 vs 运行时验证），存在验证盲区风险。
  • 多模型协同引入额外延迟与上下文切换开销，文中未量化端到端延迟影响。
  • 依赖 Claude Code 特定 hook 机制与版本，跨版本兼容性未验证，可能限制在 RRLab 自有 harness 中的可移植性。

四、与 RRLab 研究的关联

  • Harness 工程：pilotfish 的 hook 驱动激活与角色代理生命周期管理（dispatch brake、用户级覆盖）可作为 RRLab harness 设计多模型调度层的参考模板，特别是"风险触发独立审查"而非文件数量触发，值得借鉴。
  • 多模型协同：其"前沿规划 + 廉价执行 + 独立验证"的三层架构，与 RRLab 多模型协同研究方向高度契合；可借鉴其角色边界定义（只读 vs 执行 vs 证伪）与路由优先级策略。
  • 模型评测：pilotfish 的 verifier 采用全新上下文证伪机制（CONFIRMED/REFUTED/INCONCLUSIVE），可作为 RRLab 模型输出质量评测的自动化验证框架参考；其"行为观察而非派发率"的测量立场也值得在评测设计中采纳。
  • Agent 落地：其安装/迁移/回滚的完整生命周期管理（marketplace 命令、版本化安装）为 RRLab Agent 产品的工程化落地提供了实践范式；"展示变更计划并获批准后写入"的安全安装流程值得复制。
  • AI 原生产品：成本感知的默认路由策略（非单一模型全胜论）可作为 RRLab 产品定价与模型选型的决策依据；用户级覆盖机制体现了"AI 辅助 + 人类控制"的产品设计原则。

本笔记由 DeepSeek V4 Flash 自动生成，未经人工审校。原文链接：https://github.com/Nanako0129/pilotfish