第 1 章 · FirstMate 概述：Agent Distro 与舰队理念
本章目标：理解 FirstMate 解决的核心痛点、它作为 Agent Distro 的独特定位，以及 captain/firstmate/crewmate/secondmate 四层角色体系与整体架构。
1.1 单智能体的困境：tab-juggler 问题
运行一个编码智能体（coding agent）很容易：打开终端，启动 Claude Code 或 Pi，交代任务，等待结果。
但当你想同时推进三个项目任务——修一个 bug、做一次代码审计、写一份技术方案——事情就变了味。官方 README 对此有一个精准的描述：
you become a tab-juggler: babysitting sessions, copy-pasting context
between repos, forgetting which terminal had the failing test.
（你变成了一个标签页杂耍者：看管会话、在仓库之间复制粘贴上下文、
忘记哪个终端里有跑挂的测试。）这就是 tab-juggler 问题：
- 每个智能体会话都要人工看管（babysit）；
- 任务之间的上下文靠手工复制粘贴搬运；
- 多个终端窗口并行时，很快分不清哪个会话在做什么。
传统解法是给每个任务开一个智能体窗口——但这只是把「管理代码」的问题换成了「管理智能体」的问题。
1.2 FirstMate 的翻转：Talk to one agent. Ship with a crew.
FirstMate 的口号一语道破它的模型翻转：Talk to one agent. Ship with a crew.（只跟一个智能体对话，却由一支船员队伍完成交付。）
你不再逐个指挥多个智能体，而是只对话一个固定的智能体——firstmate（第一副手）——由它替你调度整支船员队伍：
你（captain）
│ 只跟 firstmate 对话：提需求、做决策、"merge it"
▼
firstmate（本仓库即发行版）
│ 读 projects/ 并路由请求；写入受护栏的 backlog/briefs/state
├──────────────┬──────────────┐
▼ ▼ ▼
fm-task1 fm-task2 ... fm-taskN ← tmux 窗口等可见会话后端中
(crewmate) (crewmate) (crewmate) 各跑一个自主智能体
└──────────────┴──────────────┘
▼
treehouse git worktree（每任务一个干净工作树）
├─ ship 任务：项目模式 ► PR/local merge ► teardown
└─ scout 任务：data/<id>/report.md 调查报告 ► teardown整个流程中：
- 你用自然语言向 firstmate 提出请求；
- firstmate 把每个请求路由到一个 crewmate（船员），每个船员在自己的会话端点（tmux 窗口等）和独立的 git worktree 中工作；
- firstmate 用零 token 的事件驱动 watcher 监督整支舰队，只在需要你介入时才唤醒；
- 最后交到你手上的是完成的 PR、经批准的本地合并，或独立的调查报告。
官方给出的真实对话体验是这样的：
> ahoy! look at my github project xyz, then fix the flaky login test and add dark mode
# firstmate 检查工具链（安装任何东西前都会先征求你的同意），
# 把项目克隆到 projects/ 下，并在当前后端里拉起两个隔立的 worker。
# 几分钟后：
PR ready for review, captain: https://github.com/you/xyz/pull/42
(fix flaky login test - risk: low - CI green)
> alright merge it注意两个细节：firstmate 汇报时称呼你为 captain（船长）；你说一句 alright merge it 它才执行合并——合并权限始终在你手里。
1.3 FirstMate 是什么：Agent Distro
FirstMate 官方文档用一连串「不是」来精确定位它自己：
firstmate is not a model, not a harness, not a skill, not an MCP server, and not a CLI. firstmate is an agent distro for running a crew of agents.
它不是模型（model）、不是运行框架（harness）、不是单个技能（skill）、不是 MCP server、也不是命令行工具（CLI）。它是一个 agent distro（智能体发行版）：
| 概念 | 含义 | 类比 |
|---|---|---|
| model | 底层 LLM，如 Claude、GPT | 发动机 |
| harness | 承载模型的编码智能体 CLI，如 Claude Code、Pi | 整车厂 |
| skill | 单项专家能力包 | 一个零件 |
| MCP server | 外部工具协议服务 | 外接设备 |
| agent distro | 指令 + 技能 + 工具 + 策略 + 状态约定的可移植目录 | 整套改装方案 |
官方对 agent distro 的定义是：
An agent distro is a portable directory of instructions, skills,
tooling, policies, and state conventions that turns a general-purpose
agent into a specialized one.
（agent distro 是一个可移植目录：指令、技能、工具、策略与状态约定，
把通用智能体改造成专用智能体。）这意味着 There is no app to install: the cloned repo is the distro——没有应用要安装，克隆下来的仓库本身就是发行版。仓库里的三类东西构成了第一副手的全部：
firstmate/
├── AGENTS.md # 运营契约：always-loaded 的岗位说明书与路由索引
├── .agents/skills/ # firstmate 内部技能（agent 加载，带 metadata.internal=true）
├── skills/ # 面向公共安装者的独立技能
├── bin/ # fm-* 辅助脚本工具带（监督、派发、状态、控制……）
├── docs/ # 架构、配置、各后端设置指南
└── tests/ # 测试套件任何终端编码智能体只要能读懂 AGENTS.md，在这个仓库目录里被启动，就被实例化成你的第一副手。
1.4 四层角色体系
FirstMate 用航海隐喻建立了一套严格的指挥链：
| 角色 | 航海身份 | 职责 |
|---|---|---|
| captain | 船长（你） | 唯一的决策者：提需求、批合并、拍板所有真决策 |
| firstmate | 第一副手 | 唯一联络人：接收 captain 的一切指令，派发、监督、升级、汇报 |
| crewmate | 船员 | 被 firstmate 拉起的自主智能体，在独立 worktree 里干具体活 |
| secondmate | 第二副手（可选） | 从自己隔离的 FM_HOME 出发运行的「持久船员」，本质仍是直接下属 |
几条关键关系：
- 单向沟通：所有 crewmate 的通信都必须经过 firstmate 中转，船员永远不直接向 captain 汇报（这是硬规则 4，第 4 章详解）；
- secondmate 不是第二套架构：官方强调 "A secondmate is a crewmate with an isolated firstmate home and a charter, not a second architecture"——它是带隔离主目录和章程的船员，不是另一层 mini-firstmate 指挥链；
- 规模弹性：单船员足够时就不需要 secondmate；舰队变大或需要跨机器时再启用。
1.5 十大核心特性
官方 README 列出的特性清单，值得逐一认识（后续章节会分别展开）：
- One liaison——只跟 firstmate 对话：它派发任务、监督到完成、只升级真正的决策、用平实的结果汇报；
- A visible crew——每个船员都在自己的 tmux 窗口（或 herdr/zellij 标签页、cmux 工作区、Orca 终端）里工作，你可以围观甚至直接插话，firstmate 负责调和；
- Disposable worktrees——每个任务在干净的 treehouse git worktree 中运行，同一仓库的并行工作互不冲突；
- Two task shapes——ship 任务交付被授权的变更；scout 任务产出独立的调查报告；
- Explicit project modes——每个项目以
no-mistakes、direct-PR或local-only模式交付，可选+yolo合并自治标志； - Optional secondmates——持久第二副手，从隔离的 firstmate home 运行，支持本地或 SSH 可达的远程主机；
- Event-driven, zero-token supervision——bash watcher 沉睡监视舰队，只在需要你时唤醒 firstmate；已验证的主 harness 还有 turn-end 兜底，防止「盲停」；
- Optional Relay——用一个本地
.env配对令牌开启，让同一支舰队回答你在 X 和 Discord 上的公开提及； - Strict project boundary——firstmate 对你的项目默认只读，一切项目改动都由 crewmate 在配置好的合并权限后面完成；
- Restart-proof——所有状态都在磁盘和活动会话后端上，随时杀掉会话，下一个会话自动对账继续。
这十点可以归成三组：怎么干活（2/3/4）、怎么放权（5/6/9）、怎么放心（7/8/10）。第 1 条则是贯穿一切的交互原则。
1.6 与其他多智能体方案的区别
把 FirstMate 放进你已学过的框架坐标系里，能看清它的独特位置：
- Agno / CrewAI / Mastra / Flue 是让你编写多智能体应用的代码框架——你写 Python/TypeScript 定义 Agent 和编排逻辑；
- Claude Code / Pi 是单智能体运行框架——一次跑一个会话；
- FirstMate 不写一行应用代码，而是用一份
AGENTS.md契约加 shell 工具带，把你已有的编码智能体 CLI 组织成一支有纪律的舰队。
换句话说，前面学的框架解决「如何造智能体」，FirstMate 解决「如何指挥一群现成的智能体」。它的全部逻辑都发生在操作系统层面：git worktree、tmux 会话、磁盘状态文件、bash watcher——这也是为什么它的实现语言几乎全是 Shell。
本章小结
- FirstMate 解决 tab-juggler 问题：多个并行智能体任务的人工看管负担；
- 核心模型翻转：你是 captain，只与 firstmate 这一个联络人对话，由它指挥 crewmate 舰队交付 PR 或调查报告；
- FirstMate 是 agent distro——指令、技能、工具、策略与状态约定的可移植目录，克隆仓库即完成「安装」；
- 四层角色体系：captain（决策）/ firstmate（联络与监督）/ crewmate（执行）/ secondmate（持久化隔离执行），通信严格单向；
- 十大特性覆盖任务形态（ship/scout）、安全边界（项目模式、硬规则）、放心机制（零 token 监督、restart-proof、Relay）。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. FirstMate 官方如何定位自身？
2. 关于 captain 与 firstmate 的关系，正确的是？
3. crewmate 完成一个 ship 任务后，最终交付物通常是？
4. 为什么说 FirstMate 是 restart-proof（重启无恙）？
🛠️ 动手实践
- 打开 FirstMate 仓库 https://github.com/kunchenguid/firstmate ，通读 README 的 What it is 与 How It Works 两节，用自己的话（不超过 200 字）向同事解释「agent distro」与传统多智能体框架的区别。
- 画出本章 1.2 节架构图的变体：假设舰队中有 1 个 secondmate 和 3 个 crewmate，标注每条通信线谁发起、经过谁、终点是谁，并检查是否有任何一条线绕过了 firstmate。
- 对照十大特性清单，挑选你认为对「个人开发者独立开发」最重要的三条，写出理由；再挑选对「团队协作场景」最重要的三条，对比两组的差异。