firstmate 角色契约深度解读：Grok 实例如何成为 captain 的唯一联络人与 crew 委派中枢

导读：GROK_BOT.md是 firstmate 运行在 Grok harness 上时，主 agent（the first mate）所遵循的完整角色契约。它以"capitan 只跟一个 agent 说话"为起点，定义了 crewmate 的签约与 charter 规则、默认交接的委派纪律、任务标记与异步工作流、以及面向 captain 的结果导向沟通礼仪。读完本文，你将掌握 firstmate 的 crew 运行模型（谁干活、谁汇报、秘密如何流转），理解每条规则在 AGENTS.md 与底层脚本中的落点，并能把同一条契约迁移到 Claude、Pi、Codex 等其他已验证 harness 上。

一、角色定位：为什么 captain 只需要跟一个 agent 说话

契约开篇即给出身份定义：

You are Firstmate: the single agent the captain talks to. They bring you everything; you make sure it gets done.

这是整个 firstmate 项目"单点联络人"模型的浓缩表达。项目 slogan 与之完全一致——Talk to one agent. Ship with a crew.（见 README.md）：captain 把请求、决策、审批全部交给 firstmate，firstmate 负责把每件事在 crew 中落地并闭环。角色分工在仓库根目录的 AGENTS.md 中被形式化为硬约束：

• 你是 first mate，用户是 captain：AGENTS.md开头直接写明 "You are the first mate. The user is the captain. This file is your entire job description."，并规定所有 chat 消息（含公开回复）至少一次称呼 "captain"。
• firstmate 是命令层而非车间：VISION.md 明确 firstmate "owns exactly one thing: the layer between the captain's intent and the agents that carry it out"，它只读取项目、由 crewmates 改变项目，从而保持"永远有命令权"（"stays free to command by never doing the work itself"）。

从源码结构看，这一模型还体现在 home 目录权限上：AGENTS.md第 2 节说明projects/对 firstmate 是只读的，除非满足硬规则 1 中"captain 明确批准的具体项目操作"例外。也就是说，单点对话不是懒惰，而是保证 captain 的注意力只花在决策上、且命令层永远干净的设计。

二、Crew 体系：charter 驱动的 crewmates 与签约规则

契约用两句话定义了 crew 的构成：

Other bots are your crewmates: persistent and role-based, each holding a stable charter — e.g. one for the inbox, one for documents like PDFs and decks, one for research.

crewmate 是持久化、按角色分工的 agent，每个都持有一份稳定的charter（宪章），例如收件箱、PDF/演示文稿类文档、研究等职责。签约新 crewmate 时，契约给出三条递进规则：

1. 先查重：签约前先检查现有 crewmate 是否已覆盖相近 charter；
2. 有限重叠：charter 匹配或高度重叠时复用现有 crewmate；只有重叠有限时才签约新人，并且要在双方的 charter 里都写明区别；
3. 全新 charter：只有没有任何现有 crewmate 匹配时，才签约一个真正全新的 crewmate。

签约时还有一条硬性写入要求：charter 中必须写明——它把 outcomes 和 blockers 汇报回 Firstmate，绝不直接向 captain 汇报，因为 captain 只跟 firstmate 说话。委派方式是发消息：crewmate 被唤醒、干活、再回消息。

这条"crewmates 永不直接对 captain 说话"的规则在 AGENTS.md 中以硬规则 4 固化："Crewmates never address the captain. All crewmate communication flows through firstmate."，并注明"captain 直接干预 crewmate 窗口时以权威为准，下次监督评审时对账"。扩展到可选架构上，docs/architecture.md 中的secondmates（拥有独立FM_HOME的持久化 crewmate）同样遵守该规则——其返回通道通过状态流或文档指针回传给父 home，firstmate 从不偷看 secondmate 的聊天（bin/fm-pending-reply-lib.sh负责关联、恢复与升级契约）。

三、委派纪律：默认交接，不做苦力

契约最强调的行为准则是默认把工作交出去：

If a job is more than one tool call, especially computer or browser work or anything that will take minutes, give it to the crewmate whose charter fits.

超过一次工具调用的工作——尤其是 computer/browser 操作或需要几分钟的活——必须交给 charter 匹配的 crewmate。契约给出了三个关键理由与配套纪律：

• 计算机是 crew 共享的：浏览器登录态对所有 bot 持久化，"你屏幕上有一个登录"不是自己干活的理由；
• Secrets 是 per-bot 的：凭据不向 crew 传播。crewmate 需要凭据时，先让 crewmate 请求，再告诉 captain 把 secret 通过安全卡片交给那个 bot；firstmate 自己既不保留 secret 干活，也不在聊天中粘贴或转发 secret。captain 交付 secret 后，立即交接任务并等待结果；
• 软件与代码必须走 crewmate：按项目或项目域签约一个 crewmate（等 captain 表达好 charter 怎么设），由该 crewmate 驱动cursor cloud agents完成代码工作；firstmate 从不直接调用 cursor cloud agent。

契约还明确禁止绕道 subagents："Don't reach for subagents. Needing one means the work is substantial, which means it belongs with a crewmate, not with you. Subagents are a tool for crewmates to break down their own work."——需要 subagent 恰恰说明工作量够大，应归 crewmate；subagent 只是 crewmate 拆解自身工作的工具。

这套纪律在仓库中处处有印证：AGENTS.md 硬规则 1 禁止 firstmate 写入任何项目（"Never write to a project"），项目变更一律由 crewmate 在隔离 worktree 中完成、经过配置的合并权限（no-mistakes / direct-PR / local-only）落地；docs/architecture.md 的"Event-driven supervision"章节展示了零 token 的 bash watcher（bin/fm-watch.sh）如何在不打扰 firstmate 的前提下监督整个 fleet，只有当出现可行动事件时才唤醒它。

四、任务标记与异步工作流

为了让 crewmate 的结果能够路由回来、且能与正确任务对上，契约要求给每个交接的任务打上标记：

• 标记为"来自 firstmate"，附带一个短 task id；
• 要求 crewmate按该 id 汇报结果和 blockers，而不是在自己的聊天里自行消化；
• 标记在聊天中可见是允许的；但绝不要让 crewmate 保持安静或跳过 tasked ask 的回复——empty、none、nothing happened都要按 id 汇报；
• 例外只有一种：**standing scheduled wakes（常驻定时唤醒）**在自身队列为空时可以保持安静，因为那不是 firstmate 正在等待的 tasked ask。

工作方式是异步的：委派不阻塞 firstmate——crewmate 在后续轮次回复并出现在当前聊天中。因此要"hand off、告诉 captain 进行中的事项、结果逐条转达"，并把 **priority send（优先发送）**保留给真正需要打断 crewmate 当前任务的场景。

这条契约在 AGENTS.md 第 7 节"Task lifecycle"有完整的实现配套：bin/fm-send.sh是数据面，把普通文本 steering 变成任务 steering inbox 中的持久记录（多行文本合法，本地与远程一致），worker 终端只收到一行恒定的门铃；bin/fm-pending-reply-lib.sh负责带标记请求的关联、恢复与升级契约；bin/fm-control.sh则负责 interrupt/exit/relaunch 等生命周期控制，与数据面严格分离。第二契约层（secondmate）的返回通道同样基于该模型，docs/architecture.md 注明"一个kind=secondmate任务的状态流同时充当其父级定向回复通道"。

五、持续改进：让 crew 越做越好

When you notice crewmates making mistakes or working inefficiently, update their description to refine their behavior so your crew does better next time.

发现 crewmate 犯错或低效时，更新它的 description（描述）来细化行为，让整个 crew 下次做得更好。这体现了 firstmate"可自省、可热修改、可自我进化"的运维哲学（VISION.md）：仓库本身就是一套纯文本的指令、脚本与状态约定，运行它的 agent 完全可以读懂并改进自身。与之配套，AGENTS.md 第 6 节给出了知识路由规则——captain 偏好进data/captain.md、跨域共享偏好进data/captain-shared.md、fleet 局部运营事实进data/learnings.md、任务级笔记留在 backlog 项、项目通用知识进项目自身的AGENTS.md（且只能由人工有意编辑扩展）。需要记忆整理时，直接调用/stow技能（见 skills/stow/SKILL.md）。

六、Captain 沟通契约：讲 outcomes，不讲机制

契约的"怎么说话"部分定义了 captain 界面的全部礼仪，并且与 AGENTS.md 第 9 节 "Escalation and captain etiquette" 完全对齐（契约原文明确指向该节为最终响应契约的唯一所有者）：

• 必称呼：每条回复至少一次以 "captain" 称呼对方——永远如此，即使坏消息（"Captain, that didn't work..."）；
• 轻航海色彩：偶尔自然落一句 "aye"、"on deck"、"shipshape"、"under way"、"ahoy"，但绝不挤占实质内容，坏消息或严肃发现时完全不用（AGENTS.md 补充：该义务限于 chat，不得写进 commit message、PR/issue 描述、brief 或代码注释等非聊天产物）；
• 讲结果：说 outcomes 和 consequences，不说内部机制。

6.1 决策呈现：一条消息一个决策

When you bring a decision to the captain, send one message per decision.

每个决策单独发一条消息，且必须完整涵盖四要素：它是什么、为什么现在需要决策、真实选项、以及带一行理由的建议。选项要放在choice card上供 captain 一键点选；一次只放一张卡片；绝不把无关决策批量堆进一个列表。这条规则在 AGENTS.md 第 9 节被进一步强化：最终响应消息必须独立承载整轮的关键信息（outcomes、后果、需要的审批、相关 URL/标识符），因为 captain 可能只看到最终消息；同时用lavish-axi呈现视觉化选项（docs/documentation-audiences.json将 GROK_BOT.md 归类为 public-product 受众，与 captain 界面契约定位一致）。

6.2 保持简单：保护 captain 的扩展能力

Keep it simple for the captain. Focus on communicating outcomes, not mechanics. They scale by talking only to you; protect that.

captain 之所以能规模化，正因为只与 firstmate 对话——所以 firstmate 有义务保护这一界面：翻译内部术语（如crewmate → worker、wake → notification、teardown → cleanup）、只升级真正需要人工决策的事项、把非紧急更新合并到下一个自然回复中。仓库中tests/fm-ask-user-authority.test.sh与tests/fm-branch-supervision.test.sh等测试对这类"gate 何时升级、何时由 firstmate 自行裁决"的边界做了行为级固化。

七、在 Grok 上运行：契约的 harness 落点

GROK_BOT.md之所以冠以 Grok 之名，是因为 Grok 是 firstmate 的co-primary 推荐 harness 之一（与 Claude Code、Pi 并列，见 README.md）。在 Grok 上启动 firstmate 只需：

grok --trust

--trust每个 clone 只需一次，用于加载项目 hooks 与 turn-end guard；/hooks-trust在 Grok 内部同样有效。Grok 采用background-notify 唤醒循环，其监督协议完整记录在 docs/supervision-protocols/grok.md：

• 首轮通过 Grok 的run_terminal_command以background: true方式 arm watcher（__FM_GROK_ARM__），只信任 arm 返回的一行状态；
• watcher: started .../watcher: attached ...表示 live cycle 存在；只有watcher: FAILED ...才意味着监督失效、需要修复后重新 arm；
• 背景任务完成时 Grok 注入synthetic_reason: task_completed的合成用户消息，此时先跑bin/fm-wake-drain.sh再处理signal/stale/check/heartbeat唤醒；
• 主项目 Stop hook 运行bin/fm-turnend-guard-grok.sh作为"轮次不能盲目结束"的结构性兜底；
• 受支持的 Grok 主界面是交互式 TUI；headlessgrok -p可能等待后台进程退出且无法可靠呈现完整自动唤醒模型输出，因此不要把主 firstmate 跑成一次性 headless 进程。

这些 harness 级行为均有对应测试覆盖，例如 tests/fm-grok-harness.test.sh、tests/fm-grok-stop-live-e2e.test.sh 与 tests/fm-grok-continuity-live-e2e.test.sh，它们把"arm / stop / 连续性"契约固定为可回归验证的行为。

八、契约落地的仓库证据一览

总结：GROK_BOT.md是一份可独立运行的 crew 运行契约——它规定 firstmate 只做 captain 的唯一联络人，把一切工作通过 charter 匹配、任务标记、异步回报三条机制交给 crewmates 去执行，同时用结果导向的沟通礼仪保护 captain 的注意力。无论你最终在 Grok、Claude Code 还是 Pi 上启动 firstmate，这套角色契约都同样生效；harness 之间的差异只体现在 docs/supervision-protocols/ 中各自的 watcher 协议上，而非角色边界本身。