Nanako0129/pilotfish

pilotfish – 编排 Claude Code 智能体

是什么

• 一个策略包，允许 Claude Code（Anthropic 的编程助手）将编程会话拆分为多个轻量级的“角色智能体”。
• 每个角色运行在不同的 Claude 模型（Opus, Sonnet, Haiku）上，这些模型是根据成本和能力选择的，因此主会话可以专注于高层规划和判断，而更便宜的模型则处理重复性或低风险的工作。

为什么重要

• 在长时间的编程会话中，大部分 token 消耗在搜索、重构、测试和文档编写上，而不是核心设计决策上。
• pilotfish 会自动将这些受限的任务路由到更便宜的模型，从而降低 token 成本，并让主模型保持空闲，用于前沿推理和最终审批。

工作原理

1. 安装 – 可以是接入 Claude Code 原生插件生命周期的 Plugin（macOS/Linux），或者是将文件写入 ~/.claude/（或自定义的 CLAUDE_CONFIG_DIR）的 legacy global 安装方式。
2. 策略文件 –
   • settings.json 定义了主模型别名（Opus 系列）和回退链。
   • agents/*.md 描述了每个角色（例如，scout、mech-executor、security-reviewer）。
   • CLAUDE.md 包含决定何时在主会话中保留工作以及何时委派给角色的分发逻辑。
3. 分发流 – 当你与 Claude 交互时，pilotfish 会检查 交互形状（例如，co_discover、explore_then_plan、execute）。根据形状，它可能会：
   • 调用低投入的 scout（Haiku）进行仓库侦察。
   • 使用 plan-verifier（Opus）来质疑拟议的计划。
   • 在获得批准后，将机械性重复工作交给 mech-executor（Sonnet）或将高风险代码交给 executor（Sonnet）。
   • 在实现之后运行 verifier（全新的 Opus 上下文）以证伪结果。
   • 通过 security-reviewer 和 security-executor（均为 Opus，先只读后高投入）路由安全敏感型工作。
4. 策略通过 CLAUDE.md 内部的 markdown 块（pilotfish:begin/end）来表达；Claude 在每个会话中都会读取它，因此行为是自动应用的。

安装步骤（摘要）

• Plugin beta – 遵循 install/PLUGIN-INSTALL.md；适用于 macOS (Claude Code 2.1.239) 和 Linux (Ubuntu 20.04+, Debian 10+, Alpine 3.19+)。需要 Claude Code 2.1.219+。插件必须是唯一的安装方式（不能与 legacy global 安装共存）。
• Legacy global – 在标记的发布版本中 clone 仓库，运行 claude 并要求它遵循 install/AGENT-INSTALL.md 中的运行手册。安装程序会显示合并计划，备份现有文件，并且是幂等的。

系统操作

• 通过相同的安装指南启用/禁用或更新插件。
• 在 docs/usage.md 中调整模型选择、投入程度或委派规则。
• 要为某个会话激活 pilotfish，请运行提供的 /pilotfish 命令或 install/ACTIVATION-INSTALL.md 中描述的 CLI 包装器。
• 通过要求 Claude 执行卸载运行手册来安全地卸载，该手册会移除八个智能体文件和策略块。

证据与研究

• 该仓库包含设计笔记、经济分析和实地报告文档（docs/design.md、docs/research.md）。
• spontaneous-dispatch 和 dispatch-brake 等基准测试提供了关于委派发生频率的行为观察。

谁可能会使用它

• 在 Claude Code 中花费大量时间的开发者，并希望降低 token 成本。
• 需要一种可复现的、策略驱动的方式，将低风险自动化与高风险判断分离的团队。
• 对多模型编排和风险感知 AI 辅助感兴趣的研究人员。

许可与支持

• MIT 许可。
• 作者通过 Patreon 邀请赞助，以资助付费模型的验证运行。

---

所有细节均直接取自仓库的 README；未推断出任何额外功能。