Nanako0129/pilotfish

pilotfish – 協調 Claude Code 的代理程式

這是什麼

• 一個策略套件，讓 Claude Code（Anthropic 的程式設計助理）將程式設計會話拆分成多個輕量級的「角色代理」。
• 每個角色在不同的 Claude 模型（Opus、Sonnet、Haiku）上執行，根據成本與能力選擇，讓主會話專注於高階規劃與判斷，而較便宜的模型則處理重複性或低風險的工作。

為什麼重要

• 在長時間的程式設計會話中，大多數 token 花費在搜尋、重構、測試與文件編寫上，而非核心設計決策。
• pilotfish 自動將這些有界任務導向較便宜的模型，降低 token 成本，並讓主模型能專注於前沿推理與最終審核。

如何運作

1. 安裝 – 可選擇 插件（macOS/Linux），直接整合至 Claude Code 的原生插件生命週期，或使用 舊版全域安裝，將檔案寫入 ~/.claude/（或自訂的 CLAUDE_CONFIG_DIR）。
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 每次會話都會讀取，因此行為會自動套用。

安裝步驟（摘要）

• 插件測試版 – 請依照 install/PLUGIN-INSTALL.md；支援 macOS（Claude Code 2.1.239）與 Linux（Ubuntu 20.04+、Debian 10+、Alpine 3.19+）。需 Claude Code 2.1.219+。插件必須是唯一安裝方式（無法與舊版全域安裝共存）。
• 舊版全域安裝 – 克隆標記版本的程式碼庫，執行 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；未推斷任何額外功能。