FirstMate Shell 工具集

项目概述

firstmate 是一套面向"代理船员团队"的运行时发行版（agent distro）。用户只需要与一个总代理（first mate，第一大副）对话，由它调度、管理一组自主船员代理（crewmate），完成并行任务。

核心动机：单个编码代理容易使用，但当需要并行执行修复、调研、规划、审计等多类任务时，会陷入在多个终端会话间手工切换、复制上下文、遗忘失败用例的困境。firstmate 把模型反过来——用户只与大副交互，大副负责派单、监督，最终交付可合并的 PR、本地合并或独立调研报告。

firstmate 本身不是模型、不是 harness、不是 skill、不是 MCP 服务器、也不是 CLI。它是一份可移植的目录，包含指令、技能、工具、策略与状态约定，把通用代理转变为专用代理。克隆下来的仓库即为发行版。

核心特性

• 单联络人：用户只与大副对话，由它派单、监督、仅在真实决策点升级，并以清晰结果回报。
• 可见船员：每个 crewmate 在独立的 tmux 窗口、herdr/zellij 标签、cmux 工作区或 Orca 终端中运行，可观察、可介入。
• 一次性 worktree：每个任务运行在独立的 git worktree（基于 treehouse，或在 backend=orca 时使用 Orca 管理的 worktree），保证并行任务互不冲突。
• 两类任务形态：ship 任务负责交付已授权变更；scout 任务仅产出独立调研报告。
• 显式项目模式：每个项目按 no-mistakes、direct-PR 或 local-only 模式交付，可选附加 +yolo 自治标志。
• 可选 secondmates：本地或通过 SSH 远端启用常驻二副，运行在隔离的 firstmate 家庭目录中，拥有独立的 FM_HOME、状态、项目与会话锁；远程不可达时不会自动回退为本地实例。
• 事件驱动、零 token 监督：bash watcher 沉睡监听舰队，仅在需要用户介入时唤醒大副；已验证的主 harness 还具备 turn-end 兜底机制，防止"盲目停止"。
• 可选 Relay：通过本地 .env 配对令牌启用，让舰队统一回复 X 和 Discord 上的公开提及，并在七天内对真实里程碑发布最多三条公开完成跟进。
• 严格项目边界：除大副按硬性规则 1 授权的窄集合受控操作外，大副对项目保持只读；其他项目变更均需走配置的合并授权路径。
• 重启可恢复：所有状态保存在磁盘与活动会话后端（tmux 为硬默认值，亦支持 herdr/cmux/zellij/orca）；会话被杀后下次启动会自动调和并继续工作。

快速开始

环境要求

已验证的主代理 harness：Claude Code、Grok、Pi（含 pi-signed）、Codex 或 OpenCode；Git 与 GitHub CLI（通过 gh auth login 认证）；所选后端对应的 CLI 与依赖（tmux 为默认参考后端）。firstmate 会检测缺失工具并在用户同意后提示安装。

安装与启动

gh auth login
git clone https://github.com/kunchenguid/firstmate
cd firstmate

随后启动任一推荐 harness，AGENTS.md 会接管会话：

claude          # Claude Code
grok --trust    # Grok（每克隆首次需要 --trust 加载项目钩子与 turn-end 防护）
pi              # Pi（首次按提示批准项目信任）
# 或使用 Pi 的签名封装：
FM_PI_HARNESS=pi-signed pi-signed

Pi 的 /calm 切换会隐藏部分转录装饰并显示一个 Calm 专属动画工作船，但所有模型上下文与会话数据保持不变。

对话示例

> 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

架构总览

用户与大副在大副主会话中对话；大副读取 projects/ 与 firstmate 路由，写入受管的 backlog、briefs 与状态。任务通过会话后端分发：tmux 窗口、herdr/zellij 标签、cmux 工作区或 Orca 终端，每个 crewmate 占用独立端点与 git worktree。Ship 任务按项目模式产出 PR 或本地合并；Scout 任务将报告写入 data/<id>/report.md。可选 secondmates 把这一模型扩展到常驻本地或整家庭远端二副；Relay 让同一舰队处理公开提及。

完整架构细节见 docs/architecture.md，配置项与 FM_HOME 见 docs/configuration.md。

内置技能

firstmate 内置以下用户可调用的技能（Codex 中以 $ 前缀调用，如 $afk）：

• /afk：进入离开模式监督，子监督以 bash 自处理常规通知，将与大副相关的事件与声明的外部等待重检打包为摘要汇报，并在投递卡住时主动告警。
• /ahoy：汇总自上次大副真实消息以来的可见会话事件与未答决策，并按影响顺序逐项引导决策；作为会话首条真实大副消息调用时回退为 /bearings。
• /bearings：基于本地舰队与已注册 secondmate 状态生成四段式简报；/bearings file 还会覆盖 data/ 下当日日期报告；追加 include PRs 启用实时 PR 富化。
• /updatefirstmate：将运行中的 firstmate 与 secondmates 自源快进更新，重新读取指令并通知 secondmates。
• /stow：扫描会话未捕获的持久知识，按衰减与冷归档策展分层启动记忆，强制执行预算或上报决策，级联到已注册二副，并报告可安全重置的内容。

技能按受众分为两层：

• .agents/skills/：仅供 firstmate 在活动家庭目录中加载，frontmatter 含 metadata.internal: true，对外部安装器不可见。
• skills/：面向公开、可独立安装到任意项目的技能；当前为 skills/stow，是与内部同名技能独立演进的通用会话知识扫描技能。

文档索引

• docs/architecture.md：crew、supervision、worktrees、secondmates、项目模式的维护者架构。
• docs/configuration.md：环境变量、FM_HOME、后端选择、Relay 配置、文件与 harness 支持。
• docs/remote-secondmates.md：整家庭远端二副的设置、路由、传输、恢复与安全行为。
• docs/calm.md：Pi /calm 当前行为与演示限制。
• 各后端文档：docs/tmux-backend.md、docs/herdr-backend.md、docs/zellij-backend.md、docs/orca-backend.md、docs/cmux-backend.md、docs/codex-app-backend.md。
• 监督与验证：docs/turnend-guard.md、docs/verification/supervision.md、docs/verification/runtime-backends.md、docs/supervision-protocols/。
• 工具与运维：docs/scripts.md（bin/ 工具参考）、docs/wedge-alarm.md（离开模式告警配置）、docs/gitlab-merge-watch.md。
• 总约与协作：AGENTS.md 为常驻运行合约与路由索引；CONTRIBUTING.md 描述贡献流程与测试命令。

许可证

MIT，详见 LICENSE。