firstmate

与一个 agent 对话。带领整个团队交付。

## 它是什么 你可以轻松运行一个编程 agent。 但当你想要并行处理三个项目任务——修复、调查、计划、审计——时，你就会变成一个疯狂切换标签页的人：时刻盯着各种会话，在不同的 repo 之间来回复制粘贴上下文，甚至忘了哪个终端里运行着失败的测试。 firstmate 颠覆了这种模式。 你只需与一个 agent——即大副（first mate）——对话，它就会为你管理整个团队：在可见的会话后端中生成自主 agent，为每个 agent 分配一个干净的 git worktree，监督它们直到完成，最后将完成的 PR、已批准的本地合并或独立的调查报告交到你手中。 对于更大规模的集群，你可以选择启用持久化的 secondmate：它们是领域主管，虽然仍然是普通的直接下属，但运行在各自隔离的 firstmate 主目录中。 无需安装任何应用；编排器是 `AGENTS.md`、内置的 firstmate 技能以及任何终端编程 agent 都能遵循的辅助脚本。 这不是一个 agent 框架。这不是一个单一的技能。这不是一个 CLI。 这是……一个能让任何 agent 变成你的大副（firstmate），并让你成为船长的目录。 ## 功能 - **单一联络人** - 你只需与大副对话；它负责分发任务、进行监督、仅在遇到真正需要决策时才向上汇报，并汇报最终的实际结果。 - **可见的团队** - 每个团队成员都在自己独立的 tmux 窗口、实验性的 herdr/zellij 标签页、cmux 工作区或 Orca 终端中工作，你可以随时查看或输入内容；由大副进行统筹协调。 - **一次性 worktree** - 每个任务都在一个干净的 [treehouse](https://github.com/kunchenguid/treehouse) git worktree 中运行，或者在 `backend=orca` 时使用由 Orca 管理的 worktree，因此针对同一个 repo 的并行工作绝不会发生冲突。 - **两种任务形态** - ship 任务用于交付更改；scout 任务用于调查、计划、复现或审计，并最终留下报告。 - **明确的项目模式** - 每个项目都通过 `no-mistakes`、`direct-PR` 或 `local-only` 模式进行交付，并带有可选的 `+yolo` 自主标志。 - **可选的 secondmate** - 可选择启用持久化的领域主管，它们运行在隔离的 firstmate 主目录中，拥有各自的 `FM_HOME`、状态、项目和会话锁，并通过受保护的本地 fast-forward 更新保持在主要的 firstmate 版本上。 - **事件驱动、零 token 监督** - 一个 bash 监视器在集群上休眠，仅当有需要你处理的事情时才唤醒大副；在 Claude 上，当有工作正在进行且监督未激活时，一个主要的 turn-end hook 也会阻止盲目的停止操作。 - **可选的 X 模式** - 通过一个本地 `.env` token 选择性启用，以便 firstmate 能够回复你对 `@myfirstmate` 的公开提及，通过与聊天请求相同的生命周期来处理正常的、可逆的提及请求，确认生成的工作，并在七天内针对真正的里程碑和最终结果发布最多三条公开安全的后续跟进，而不会改变非 X 行为；dry-run 预览会在正式上线前将拟议的回复和驳回记录在本地。 - **设计上的安全防护** - 除了受保护的 clone 刷新、安全的分支清理以及已批准的 `local-only` fast-forward 合并之外，大副对你的项目保持只读状态；团队成员在你批准合并之前不会对项目进行任何更改。 - **重启无忧** - 所有状态都保存在磁盘和活动会话后端中（默认硬选为 tmux，在选中或自动检测时使用 herdr 或 cmux，在明确选中时使用 zellij/orca）；随时终止会话，下一次会话将进行协调并继续工作。 关于每个功能的完整详细信息，请参阅 [docs/architecture.md](docs/architecture.md)。 ## 快速开始 **前提条件：** 一个经过验证的 agent 框架（claude、codex、opencode、pi 或 grok），配置了 GitHub auth 的 git，以及用于参考会话后端的 tmux。 大副会自动检测并主动帮你安装其他所有内容。 ``` gh auth login git clone https://github.com/kunchenguid/firstmate cd firstmate && claude # launch your harness here; AGENTS.md takes over ``` 然后只需开始对话： ``` > ahoy! look at my github project xyz, then fix the flaky login test and add dark mode # firstmate 检查其 toolchain（在安装任何内容之前征求您的同意）， # 将项目克隆到 projects/ 下，并在当前活跃的 backend 中生成两个 crewmate # fm-fix-login-k3 和 fm-dark-mode-p7。 # 几分钟后： PR ready for review, captain: https://github.com/you/xyz/pull/42 (fix flaky login test - risk: low - CI green) > alright merge it ``` tmux（默认）及所有其他受支持的后端（herdr、zellij、Orca、cmux）的设置指南可在下方的[文档](#documentation)中找到。 ## 工作原理 ``` you (the captain) │ chat: requests, decisions, "merge it" ▼ ┌─────────────────────────────────────┐ │ firstmate (this repo) │ │ reads projects/ + firstmate routes │ │ writes guarded backlog/briefs/state │ └──┬──────────────┬───────────────┬───┘ │ backend sends / status files │ ▼ ▼ ▼ ┌────────┐ ┌────────┐ ┌────────┐ │fm-task1│ │fm-task2│ ... │fm-taskN│ tmux windows, herdr/zellij tabs, cmux workspaces, or Orca terminals │crewmate│ │crewmate│ │crewmate│ one autonomous agent each └───┬────┘ └───┬────┘ └───┬────┘ ▼ ▼ ▼ treehouse worktree, Orca worktree, or isolated secondmate home │ ├─ ship: project mode ► PR/local merge ► teardown │ └─ scout: report at data//report.md ► relay findings ► teardown ``` 你与大副进行聊天。 它将每个请求路由到位于其独立会话 endpoint 和 git worktree 中的团队成员，使用零 token 的事件驱动监视器监督整个集群，并为你带来完成的 PR、已批准的本地合并或调查报告。 可选的 secondmate 将此功能扩展到持久化的领域主管，dispatch 配置文件让你能够控制哪个框架处理哪个任务，而可选的 X 模式则允许同一个集群回复公开的提及。 完整的架构——监督引擎、worktree 隔离、secondmate、dispatch 配置文件、项目模式、可选的 X 模式、集群同步以及自我更新——请参阅 [docs/architecture.md](docs/architecture.md)。 ## 内置技能 Firstmate 附带了这些可由用户调用的内置技能。 Claude 和 grok 使用此处所示的斜杠形式；codex 使用带有 `$` 的相同名称，例如 `$afk`。 | 技能 | 作用 | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `/afk` | 进入离开模式监督：子主管在 bash 中自行处理常规唤醒任务，仅将与船长相关的事件作为一批摘要进行上报，从而在你离开时降低监督成本 | | `/updatefirstmate` | 将正在运行的 firstmate 及其 secondmate 通过 fast-forward-only 拉取自我更新到 origin 的最新版本，然后重新读取指令并提醒 secondmate | | `/stow` | 扫描会话中未捕获的持久知识，根据 AGENTS.md 将每项发现路由到其在磁盘上的存放位置，将未完成的下一步记录到 backlog 中，并报告当前可以安全重置的内容 | 仅供 agent 使用的参考技能位于 `.agents/skills/` 下，并由 firstmate 在 [`AGENTS.md`](AGENTS.md) 中指定的触发点加载。 ### 双层技能布局 Firstmate 的技能分布在两个不同的位置，面向不同的受众： - `.agents/skills/` - agent 加载的技能（本节的表格，加上 firstmate 仅供 agent 使用的参考技能）。所有这些技能都假定存在一个活动的 firstmate 主目录，如果安装在其它任何地方，它们将毫无意义，甚至会产生误导。因此，每个技能的前置元数据中都包含 `metadata.internal: true`。该标志将它们从安装程序的发现范围中隐藏起来（例如 [skills.sh](https://skills.sh) 的 `npx skills add` 安装程序等工具），而不会影响 firstmate 本身加载它们的方式——前置元数据对于 agent 自身的技能加载器是无效的。 - `skills/` - 公开的、面向安装程序的技能，旨在独立安装到任何项目中，不依赖于 firstmate。 每一个都是独立的技能，不依赖于 firstmate 的路径、工具或词汇。 目前这包括 `skills/stow`，这是一个通用的会话知识扫描技能，它首先根据明确的指令路由发现的内容，然后依据现有的本地约定，最后使用当前目录下的私有 `.stow-notes.md` 后备文件，并在结束时为下一次会话留下一个恢复指针。 它故意不与其同名的 firstmate 内部技能 `.agents/skills/stow` 共享任何代码，以便两者能够独立发展。 ## 文档 - [docs/architecture.md](docs/architecture.md) - 团队、监督、worktree、secondmate 和项目模式的运行方式。 - [docs/configuration.md](docs/configuration.md) - 环境变量、`FM_HOME`、运行时后端选择、可选的 X 模式、你设置的文件以及框架支持。 - [docs/tmux-backend.md](docs/tmux-backend.md) - tmux 参考后端的设置指南：前提条件、附加会话以及监视团队成员窗口。 - [docs/herdr-backend.md](docs/herdr-backend.md) - 实验性 herdr 后端的设置指南，及其验证说明和已知缺陷。 - [docs/zellij-backend.md](docs/zellij-backend.md) - 实验性 zellij 后端的设置指南，及其验证说明和已知缺陷。 - [docs/orca-backend.md](docs/orca-backend.md) - 实验性 Orca 后端的设置指南，及其生命周期说明和已知缺陷。 - [docs/cmux-backend.md](docs/cmux-backend.md) - 实验性 cmux 后端的设置指南，及其验证说明和已知缺陷。 - [docs/turnend-guard.md](docs/turnend-guard.md) - 主会话的结构化“防止盲目结束回合”兜底机制：经验证的 Claude Code Stop-hook 机制、作用域和已知缺陷。 - [docs/scripts.md](docs/scripts.md) - `bin/` 工具带的参考。 - [`AGENTS.md`](AGENTS.md) - 面向编排器 agent 的 firstmate 完整操作手册。 - [CONTRIBUTING.md](CONTRIBUTING.md) - 如何贡献代码，包括开发/测试命令。 ## 贡献 欢迎你的贡献——有关工作流程、repo 约定以及如何运行测试，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MIT - 请参阅 [LICENSE](LICENSE)。

标签：AI代理, 人工智能, 任务编排, 多代理系统, 应用安全, 开发效率, 用户模式Hook绕过, 网络可观测性