📚 编程进阶教程站

第 16 章 · 实战一：搭建个人开发舰队 ​

本章目标：从零搭建并跑通第一条完整的 FirstMate 舰队链路——安装前置、启动第一副手、完成一次 scout 调研任务和一次 ship 交付任务，亲手体验「只对一个 agent 说话，却带着一支船员交付」的工作方式。

16.1 实战蓝图与验收标准 ​

本章是一条端到端的最小闭环：你（captain）只与 firstmate 对话，由它派生船员（crewmate）在隔离的 git worktree 中干活，最终把 PR 或调研报告交回给你。

text
你下达请求
   │
   ▼
firstmate（唯一联络人）
   │  检查工具链 → 克隆项目到 projects/ → 派生 crewmate
   ▼
crewmate（tmux 窗口中的自主 agent）
   │  在 treehouse worktree 中工作
   ├── scout：产出 data/<id>/report.md 调研报告
   └── ship ：推送分支 → 开 PR → 等待你授权合并

完成本章后，你应该能够勾掉这份验收清单：

  • [ ] firstmate 在受支持的 harness 中加载了 AGENTS.md 并以 captain 称呼你；
  • [ ] 一个 scout 任务产出了落盘的调研报告；
  • [ ] 一个 ship 任务产出了真实 PR；
  • [ ] 合并只在你明确说出口之后发生。

16.2 安装前置：四件套检查 ​

按官方 Quick Start，运行 firstmate 需要三类前置。逐项在终端确认：

bash
# 1) Git 与 GitHub CLI，并完成 GitHub 认证
git --version
gh --version
gh auth status        # 未认证则执行 gh auth login 按向导走完

# 2) 会话后端：tmux 是参考默认后端
tmux -V               # 报错则安装：brew install tmux 或 sudo apt install tmux

# 3) 任一 co-primary harness（三选一即可）
claude --version      # Claude Code
pi --version          # Pi
grok --version        # Grok CLI

三点官方说明需要记住：

  1. co-primary 三选一：Claude Code、Grok、Pi 是并列推荐的 primary harness；Codex 与 OpenCode 也已验证可用，但监督机制各有更多 harness 相关的取舍。
  2. --trust 只需每克隆一次：Grok 需要 --trust 才会加载项目 hooks 与 turn-end guard（也可以在会话内用 /hooks-trust 授权）；Pi 首次启动时批准项目信任提示，让 .pi/extensions/*.ts 自动加载。
  3. 缺什么先问再装：firstmate 启动后会自检工具链，缺工具时会征得你的同意才安装——它不会自作主张动你的机器。

16.3 克隆仓库并启航 ​

FirstMate 没有 App 可装：克隆下来的仓库本身就是 distro。进入目录后启动任一 co-primary harness，AGENTS.md 就会接管：

bash
gh auth login                                   # 若上一步还没做
git clone https://github.com/kunchenguid/firstmate
cd firstmate

claude        # 或 pi，或 grok --trust

启动后的第一条消息建议就用官方示例的问候语，顺便验证身份是否加载成功：

text
> ahoy! are you the first mate?

你应该看到什么：回复中出现对 captain 的称呼（这是 AGENTS.md 的强制要求），语气带一点航海调味但技术内容清晰。如果它自称别的角色或没有称呼 captain，说明项目指令没有被加载——最常见原因是你在错误的目录启动了 harness。

16.4 准备一个练手项目 ​

ship/scout 任务都需要一个真实的 GitHub 项目作为靶子。准备一个你自己拥有的小仓库（或 fork 一个开源小工具），要求很低：

  • 至少有一个可复现的小 bug 或一个明确的待办 issue；
  • 是你拥有的仓库（这样 PR 流程可以完整走通）。

不需要提前克隆到本地——firstmate 会把项目克隆到自己的 projects/ 目录下并保持对该目录只读，真正的修改全部发生在船员的隔离 worktree 里。这条边界来自硬规则 1（Never write to a project）：firstmate 自己不写你的项目，改动由船员完成。

16.5 第一个 scout 任务：只读调研 ​

scout 任务不产生任何代码变更、绝不 push，产出是一份落盘的独立调研报告。用自然语言下达：

text
> 派一个 scout 去调研 myname/tiny-api 这个仓库：
> 列出目录结构、入口文件、测试组织方式，
> 并指出哪里的错误处理最薄弱。只要报告，不要改任何东西。

你应该看到什么：

  1. firstmate 复述任务要点并派生一个船员（新 tmux 窗口出现）；
  2. 船员完成后，报告落在 data/<task-id>/report.md，同时给出一份 decision inventory（供你决策的事项清单）；
  3. firstmate 向你转述结论摘要，而不是让你自己去读原始输出。

你可以直接验证产物确实落盘：

bash
ls data/*/report.md | tail -3     # 最近的任务报告

16.6 第一个 ship 任务：从 issue 到 PR ​

现在下达第一个 ship 任务。继续用官方 Quick Start 的对话风格：

text
> look at my github project myname/tiny-api,
> then fix the flaky login test.

firstmate 的动作序列与官方描述一致：检查工具链（缺工具先征求同意）→ 把项目克隆到 projects/ → 在活跃后端中派生一个隔离船员 → 船员在干净的 treehouse worktree 中修复 → 监督至完成。几分钟后你会收到类似这样的汇报：

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

注意汇报的结构：链接 + 一句话变更说明 + risk 标注 + CI 状态。这就是第 11 章 watcher 监督机制的出口形态——过程不用你盯，结果以决策友好的格式送达。

16.7 合并与复盘：体验 hard rule 2 与 /bearings ​

PR 到手后，先亲自 review，再决定是否合并：

text
> alright, merge it.

只有你说出这句明确授权，firstmate 才会让合并发生——这是硬规则 2（Never merge a PR without the captain's explicit word）。反过来试一下也很有教育意义：不置可否地问「这个 PR 怎么样？」，firstmate 只会给分析意见而不会动手合并。

随后用 /bearings 做一次舰队状态盘点：

text
> /bearings

它会基于本地舰队状态生成一份四段式聊天摘要；加上参数还有两个变体：/bearings file 会同时把今天的日期版报告写入 data/，/bearings include PRs 则附加实时 PR 信息。三个变体可以组合使用。

16.8 收尾：teardown 与常见故障排查 ​

任务结束后 firstmate 会执行 teardown 清理船员会话与 worktree。teardown 有安全闸：未落地（unlanded）的工作绝不会被拆除——有未提交改动的 worktree 会拒绝清理，除非你明确授权丢弃。所以放心让它自动收尾即可。

新手最常见的三类故障：

现象原因处理
项目 hooks/guard 没加载Grok 未加 --trust，或 Pi 首次信任提示被拒在该克隆里重新授权
船员窗口没出现tmux 未安装或版本过旧安装 tmux 后重试
无法感知 GitHub 状态gh 未认证或 token 过期重跑 gh auth login

16.9 本章小结 ​

  • FirstMate 的最小闭环 = 你下达自然语言请求 → firstmate 路由 → 船员在隔离 worktree 干活 → PR/报告回传 → 你做决策；
  • scout 任务零副作用：只出 data/<id>/report.md 报告，绝不 push；ship 任务才触碰代码；
  • 合并权在你手里：没有 captain 的明确指令就没有 merge（hard rule 2）；
  • /bearings 是低成本的状态仪表盘，file / include PRs 参数按需叠加；
  • teardown 自带 unlanded-work 保护，正常收尾无需人工干预。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 首次启动 firstmate 时，下列哪组是官方并列推荐（co-primary）的 primary harness？

2. 关于 scout 任务，下列说法正确的是？

3. firstmate 回报「PR ready for review, captain: ...(risk: low - CI green)」之后，合并何时会发生？

4. teardown 时发现某个 worktree 还有未提交（unlanded）的改动，firstmate 会怎么做？

🛠️ 动手实践 ​

  1. 完成 16.2–16.3 的环境搭建，在你的练手仓库所在目录之外启动 firstmate，并用「are you the first mate?」验证 captain 称呼与航海语气出现；若失败，按 16.8 的排查表定位原因。
  2. 给同一个练手仓库先后下达一个 scout 任务和一个 ship 任务，分别记录两次任务的 tmux 窗口数量变化，并在 data/ 下找到 scout 报告文件的完整路径。
  3. 在收到 ship 任务 PR 后，故意先不授权合并，而是追问「这个 PR 的风险点在哪？」，观察 firstmate 是否只给分析不动手；然后再用 /bearings file include PRs 生成一份带 PR 信息的日报并核对 data/status-report-*.md 文件确实生成。