第 2 章 · 环境搭建与首次启航
本章目标：从零准备运行 FirstMate 所需的全部工具链，完成克隆与首次启动，并跑通第一条「下达请求 → 船员干活 → PR 回传」的最小闭环。
2.1 平台与前置要求
FirstMate 是一个纯 Shell 组织的 agent distro（智能体发行版），官方支持的平台是：
macOS / Linux（不支持原生 Windows，可在 WSL2 中尝试但无官方保证）启动前需要备齐三类工具，缺一不可：
| 类别 | 工具 | 用途 |
|---|---|---|
| 认证 | GitHub CLI (gh) | 克隆仓库、创建 PR、读取 CI 状态 |
| 版本控制 | git | 项目克隆、worktree 隔离 |
| 会话后端 | tmux | 参考后端，承载每个船员的可见会话 |
| 主 harness | Claude Code / Grok / Pi 等 | 运行第一副手本人的智能体运行时 |
其中 tmux 是参考后端（reference backend）：文档中的所有监督行为都以它为基准验证过；herdr、zellij、Orca、cmux 属于实验性后端（第 7 章详述）。初学请先用 tmux。
2.2 选择主 harness
主 harness（primary harness）就是承载第一副手会话的那个终端编码智能体。FirstMate 官方验证过的 harness 有：
Claude Code grok pi pi-signed Codex OpenCode Cursor Agent CLI其中 Claude Code、Grok、Pi 是平级的三个联合主推（co-primary），任选其一即可，差别只在监督接入机制：
| Harness | 监督接入方式 |
|---|---|
| Claude Code | tracked Stop hook，tokenless 地重新武装 watcher 并在需要时唤醒 |
| Grok | background-notify 唤醒循环 |
| Pi | tracked primary watcher extension |
三者都有经过验证的 turn-end guard 路径（第 11 章详解）。Codex 和 OpenCode 也受支持，但分别依赖有界前台检查点与 TUI 插件，监督取舍更多。Cursor Agent CLI 使用项目级 .cursor/hooks.json 的 stop hook，形态上最接近 Claude Code。
选型建议：跟着你的订阅走——手头有哪家的订阅就用哪家，FirstMate 对三者一视同仁。
2.3 安装与克隆
先完成 GitHub CLI 认证，再克隆发行版本体：
# 1. 登录 GitHub（按提示走浏览器授权流程）
gh auth login
# 2. 确认认证状态
gh auth status
# 3. 克隆 firstmate 发行版并进入目录
git clone https://github.com/kunchenguid/firstmate
cd firstmate没有 app 要安装、没有全局命令要注册——克隆下来的仓库本身就是发行版：AGENTS.md 是运营契约，.agents/skills/ 是内置技能，bin/ 是脚本工具带。
2.4 首次启动
在 firstmate 目录内直接启动你选定的 harness，AGENTS.md 会自动接管成为第一副手的岗位职责：
# Claude Code
claude
# Grok（--trust 每个克隆只需一次，让项目 hooks 与 turn-end guard 加载）
grok --trust
# Pi（首次启动批准一次项目信任提示，让 .pi/extensions/*.ts 自动加载）
pi
# 或使用签名包装器
FM_PI_HARNESS=pi-signed pi-signedPi 还提供 /calm 开关：隐藏部分转写界面噪音（包括被规范分类的 Firstmate 操作行），活动运行期间用 Calm 动画小船替代普通输出，且不改变任何模型上下文与会话数据；再执行一次 /calm 即可恢复普通渲染。
2.5 启动时发生了什么：会话启动摘要
每次会话开始，第一副手都会运行一次 bin/fm-session-start.sh，产出一份启动摘要（digest）。它的固定顺序是：
1. Lock 先获取本 home 的会话锁，锁失败则全程只读
2. Bootstrap 只读探测工具/版本问题；安装必须经你当场同意
3. Wake queue 呈现持久唤醒队列（上次遗留的工作通知）
4. Supervision 输出与你当前 harness 匹配的监督操作指令块
5. Fleet-state 快速盘点每个任务的存活状态（只查"在不在"，不深读）
6. Network checks GitHub 认证、secondmate 存活等网络检查的并发结果
7. Context digest projects/secondmates/captain/learnings 各档案全文两个对新手最重要的规则：
- Bootstrap 只检测不安装：发现缺工具时会列出清单征求你的同意，你说可以它才装；
- 锁被拒即只读：如果另一个活跃会话持有锁，本次会话不会派生、合并或修改任何舰队状态，只报告诊断信息。
摘要里出现 ABSENT 标记是正常的——例如 data/captain.md 不存在表示「使用内置默认偏好」，而不是出错。
2.6 第一次对话：跑通最小闭环
启动完成后，直接用自然语言下达任务。官方示例：
> ahoy! look at my github project xyz, then fix the flaky login test and add dark mode这条消息包含两个任务，第一副手会自动拆解路由：
任务1（ship）: 修复 flaky login test → 船员 A 在独立 worktree 中工作
任务2（ship）: 新增 dark mode → 船员 B 在另一个独立 worktree 中工作几分钟后你会收到类似这样的汇报：
PR ready for review, captain: https://github.com/you/xyz/pull/42
(fix flaky login test - risk: low - CI green)
> alright merge it注意这次对话里的三个要点：
- 你只跟第一副手说话，从不直接指挥任何船员；
- 合并需要你明确点头——「alright merge it」就是那句 captain 的 explicit word（第 4 章 hard rule 2）;
- 汇报以结果开头（PR 就绪、风险低、CI 绿），而不是中间过程细节。
2.7 常见故障排查
| 现象 | 原因与处理 |
|---|---|
| 启动后没有任何 hooks 加载 | Grok 忘了 --trust；或在会话内执行 /hooks-trust 补授权 |
| Pi 没有加载 watcher extension | 首次信任提示被拒绝过；重新批准项目信任即可 |
| 提示 tmux 未安装 | brew install tmux（macOS）或 apt install tmux（Debian/Ubuntu） |
| 提示 GitHub 认证失败 | 重跑 gh auth login，确认 gh auth status 通过 |
| 会话启动摘要显示锁被拒 | 已有另一会话在管理舰队；关闭旧会话或等它释放锁 |
2.8 本章小结
- FirstMate 支持 macOS/Linux，依赖
gh+git+ tmux 参考后端 + 一个已验证的主 harness； - Claude Code / Grok / Pi 是三个平级 co-primary，差异只在监督接入机制；
- 克隆即安装：仓库本身就是 agent distro，无需额外 app；
- 会话启动摘要按 Lock → Bootstrap → Wake queue → Supervision → Fleet-state → Network checks → Context digest 固定顺序产出；
- Bootstrap 只探测不安装，一切安装需你当场同意；最小闭环 = 自然语言下单 → 双 worktree 并行 → PR 回传 → 你口头授权合并。
🧪 随堂测验
点击你认为正确的选项。答错时会展示正确答案与原因解析。
1. FirstMate 官方支持的参考会话后端是哪个？
2. 关于三个 co-primary harness（Claude Code、Grok、Pi），下列说法正确的是？
3. 会话启动摘要中 Bootstrap 区块的安装策略是？
4. 首次对话「fix the flaky login test and add dark mode」中，第一副手会如何处理这两个改动？
🛠️ 动手实践
- 在自己的机器上完整走一遍 2.3–2.4 节流程：认证
gh、克隆 firstmate、启动一个你有订阅的 co-primary harness，并把启动摘要的七个区块逐一抄录下来对照本文核对。 - 故意在未安装 tmux 的环境（或临时改名 tmux 二进制）中启动第一副手，观察 Bootstrap 如何报告缺失工具以及它给出的安装建议流程，记录「同意前」与「同意后」的差异。
- 找一个自己的练手仓库，用 2.6 节的双任务句式下达一条包含两个改动的自然语言请求，观察第一副手如何拆分任务、开出几个 tmux 窗口，以及最终汇报里是否包含 PR 完整 URL、risk 标注与 CI 状态三要素。