kunchenguid/firstmate · 上手攻略

仓库：kunchenguid/firstmate
链接：https://github.com/kunchenguid/firstmate
分类：AI Agent · 多Agent编排
作者：Tom
更新：2026-08-09

这是什么

firstmate 是一个多 Agent 编队运行框架（agent distro），其核心理念是：

你只和一个 Agent（first mate / 大副）说话，它来管理一整支 Agent 团队（crew），在独立 git worktree 中并行完成任务，最终把结果交给你。

作者将你自己定位为"船长"（captain），firstmate 是你的"大副"，crew 成员是听命于大副的水手——你永远不直接和水手说话，一切通过大副协调。

解决什么问题：当你需要同时处理修复 bug、调研技术方案、审查 PR 等多个任务时，传统方式是开多个 terminal + 多个 Agent session，手动在它们之间复制上下文。firstmate 让你只需跟一个大副对话，它自动 spawn 独立 Agent 分头干活、监控进度、处理阻塞，最终交付 PR 或调查报告。

核心概念

概念	含义
Captain（船长）	你本人，只和大副说话
First Mate（大副）	唯一对外接口，负责编队调度和结果汇总
Crew（水手）	被大副 spawn 的独立 Agent，各自在干净 git worktree 中工作
Ship Task	产出授权变更（PR / local merge）的任务
Scout Task	调研任务，产出独立调查报告，不修改任何代码
Secondmate	可选的持久化副大副，有独立 home/状态，可在另一台 SSH 机器运行
Treehouse	每个任务独占的 git worktree，保证并行工作不冲突

快速安装

环境依赖

验证可用的 Agent harness：Claude Code / Grok / Pi / pi-signed / Codex / OpenCode（Claude Code / Grok / Pi 为共同主推）
Git + GitHub CLI（需 gh auth login 完成认证）
tmux（参考默认后端，亦可切换为 herdr / cmux / zellij / orca）

安装步骤

gh auth login   # GitHub CLI 认证
git clone https://github.com/kunchenguid/firstmate
cd firstmate

然后启动一个支持的 harness，AGENTS.md 会自动接管：

# 方式一：Claude Code（推荐）
claude

# 方式二：Grok
grok --trust

# 方式三：Pi
pi
# 或（已安装 signed wrapper 时）
FM_PI_HARNESS=pi-signed pi-signed

⚠️ Grok 的 --trust 标志每个 clone 只许用一次，用于加载项目 hooks 和 turn-end guard；Pi 需要在首次启动时同意项目信任提示以加载追踪扩展。

⚠️ firstmate 不是一个需要"安装"的应用程序——clone 下来的仓库本身就是 distro，包含 AGENTS.md、技能包和辅助脚本。

核心用法

启动任务

在 firstmate 对话框（captain 视角）输入自然语言指令：

ahoy! look at my github project xyz, then fix the flaky login test and add dark mode

大副会： 1. 检查工具链（经你同意后自动安装缺失依赖） 2. 在 projects/xyz/ 下 clone 项目 3. Spawn 两个独立 crew Agent，各自在干净 worktree 中工作 4. 监督完成，自动汇总统结果

几分钟后返回：

PR ready for review, captain: https://github.com/you/xyz/pull/42
(fix flaky login test - risk: low - CI green)

Ship vs Scout 任务模式

模式	交付物	说明
Ship Task	PR / approved local merge	产出代码变更
Scout Task	独立调查报告	仅调研，不触碰代码

项目交付模式

每个项目可配置三种交付模式： - no-mistakes — 变更经审批后合并 - direct-PR — 直接推送 PR - local-only — 仅本地 merge，可附加 +yolo 标志增加自主权

Secondmate（可选）

需要多机并行时，可启动 secondmate——有独立 FM_HOME、状态、projects 的持久 Agent，通过 SSH 在另一台可达机器运行： - 各 secondmate 有独立 session lock - 远程不可用时不会静默降级为本地替代 - 支持 guarded update 和 recovery

监控与中断

每个 crewmate 在独立 tmux window / herdr tab / cmux workspace / Orca terminal 中运行，你可以随时 watch 或输入内容
bin/fm-watch.sh 后台 watcher 在舰队上休眠，只在需要船长决策时唤醒大副（零 token 消耗的监督机制）
大副只在真正需要决策时向船长上报，不浪费 token

Relay 功能（可选）

配置本地 .env pairing token 后，大副可以： - 接收你在 X 和 Discord 的公开 @mention - 对可逆的 mention 请求执行操作（与 chat 请求走同一生命周期） - 在 7 天内最多发布三条公共安全的后续回复（真实里程碑和最终结果） - dry-run 预览会在 go-live 前本地记录所有拟回复

典型适用场景

多 repo 并行工作：同时修 bug + 写新功能 + 做 code review，各占独立 worktree 不冲突
复杂项目的任务分解：大型重构拆成多个 Ship Task，并行推进
技术调研 + 代码实施联动：Scout 调研方案 → Ship 执行变更，大副统一协调
跨机器舰队：Secondmate 在 SSH可达的远程机器运行，适合多机器开发环境
PR merge 前置审批流：no-mistakes 模式确保变更必须经过人工审批才能合并

坑与注意

Agent harness 选择影响 supervision 机制：Claude Code 用 Stop hook re-arm / Grok 用后台 notify wake cycle / Pi 用 primary watcher 扩展，三者监督路径不同，Codex 用 bounded foreground checkpoint，OpenCode 用 TUI plugin——选哪个影响监控行为。
Hard Rule 1——永远不直接写项目：大副自己不能随意修改项目，只有在船长明确授权具体操作时才能破例；Crew Agent 同样受限。
Hard Rule 2——永远不 merge PR：即使 AI 判断已经可以合并，也必须等船长说"可以"，除非项目配置了 +yolo 模式。
Worktree 隔离 ≠ 无冲突：同一 repo 的多个 worktree 并行写没问题，但若涉及共享资源（如 git config、commit message 规范）仍需注意。
Restart 可恢复但不保证零中断：状态存在磁盘和 session 后端，kill session 后重启可 reconcile，但进行中的任务可能需要重跑部分步骤。
Relay 功能有安全边界：Relay 只处理"普通可逆 mention 请求"，不改变非 Relay 行为，发布内容也有 3 条/7 天上限限制。

与同类对比

方案	定位	优点	缺点
firstmate	Agent 编队管理层	一个对话入口、worktree 隔离、零 token 监督	需要一定 Agent 使用经验、配置门槛
直接多 session	传统并行	简单直观	上下文手动复制、易混淆
LangChain Agents	LLM 工具调用框架	生态丰富	非多-Agent 编队，需要自己实现协调层
CrewAI	多 Agent 协作框架	概念清晰、有 Python SDK	以 process 为中心，非单一入口对话
AutoGen	多-Agent 对话框架	Microsoft 背书、代码生成能力强	配置复杂、偏向研究而非工程

firstmate 的核心差异化在于以"船长-大副"心智模型提供单一对话入口，配合 git worktree 隔离 + 零 token 后台 watcher，让多 Agent 并行工作对用户透明。

⚠️ 不确定处：不同 harness（Claude Code / Grok / Pi）在大规模任务（>10 并行）下的实际性能对比，以及 secondmate SSH 远程模式的最低网络延迟要求，README 未提供量化数据。

一句话推荐结论

firstmate 是为"受够了同时开 N 个 terminal 管 N 个 Agent session"的开发者设计的编队管理器，如果你已经有稳定使用的 coding agent（Claude Code / Grok / Pi），clone 下来直接用即可；如果你还不习惯多 Agent 并行工作流，它的零门槛单一入口设计可以让你平滑过渡。

来源：https://github.com/kunchenguid/firstmate README + docs/architecture.md + AGENTS.md