Mergetrain

mergetrain

安全地集成并行编码 Agent 提交的分支。

mergetrain 是一个面向并行大模型 Agent 的本地合并队列。这些编码 Agent 使用大模型，并在 Git 工作树中工作。mergetrain 在你的计算机上运行。一个 队列批次由一组排队等待处理的任务分支组成。一个关卡是已配置的测试或检查。 每个 Agent 都会提交自己的分支并将其加入队列。一个运行器按入队顺序合并 分支，并对合并后的结果运行关卡。只有在获得明确批准后，它才会原子地更新 你的 Git 引用。

mergetrain 专为由一位操作者管理本地仓库的场景而设计。

mergetrain 不需要账户、托管控制平面、OAuth 应用或产品遥测。队列和运行器 状态都保留在你的计算机上。只有你配置的 Git 远程端，以及受信任的关卡或 验证命令，可能会连接外部服务。

修复期间继续构建

默认批次模式：通过的工作优先合并。 需要修复的工作会退回给对应的 Agent。修复继续进行期间，通过的工作仍可合并。

检查期间继续构建。 Agent 在 mergetrain 检查较早提交的工作时，就可以 开始下一个任务。这个 14 秒循环会让相同的四个 Agent 始终保持在视野中。

两种模式下，Agent 都可以继续构建。在有序模式中，尚未解决的较早提交会阻止 后续工作合并。 比较两种模式。

暂停或重播演示 · 查看静态图片 · 复现连续工作流

此演示是如何制作的

此示意图基于记录下来的 CLI 结果。 四条泳道代表 Agent 角色；字母表示工作，而非队列任务 ID。捕获脚本会在一次性 本地仓库和裸远程仓库中记录由 Agent 编写的更改及操作者的批准。它不会启动 AI 服务。

两个测试关卡的等待时段让并行过程可重现：A 和 B 正在验证时提交 E 和 F， 随后 E 和 F 正在验证时开始起草 G 和 H。三次部署都保留了批准状态和默认的 重新检查。最终远程仓库的全新克隆可以通过六项测试。

随后，G 和 H 会在不丢失编辑内容的情况下，基于该结果刷新。I 和 J 也从该 结果开始。这四份草稿都不会提交。你的 Agent 或操作者负责创建、修复、刷新 并重新提交工作；mergetrain 负责检查并集成这些工作。14 秒动画以压缩后的 时间重复播放这段已记录的过程。

问题

工作树允许多个 Agent 在不共用同一检出目录的情况下编辑一个仓库。但它们 不会决定合并顺序、测试合并后的结果、防止推送竞争，也无法在笔记本电脑于 推送过程中宕机时告诉你发生了什么。

如果没有共享的集成工作流，操作者就必须决定分支顺序并解决跨分支故障。 操作者还需要重新运行测试并控制推送。反复执行这些操作可能会拖慢并行工作。

mergetrain 会将此工作流记录在一个持久的本地队列中：

agent branches → local queue → isolated integration worktree → combined gates
               → explicit approval → one atomic push → post-push verification

适用对象

以下情况适合使用 mergetrain：

• 多个编码 Agent 全天都在同一个仓库中完成各自的分支；
• Agent 在 Git worktree 中工作，应该将任务加入队列，而不是推送部署引用；
• 合并后的结果必须通过本地测试才能落地；
• 你只希望对明确预先批准的任务进行无人值守处理；或
• 你希望通过一个本地枢纽查看多个仓库的队列和运行器。

mergetrain 与具体的 Agent 框架无关：Codex、Claude Code、agy、脚本和人工用户都使用相同的 CLI 和 JSON 契约。

在一台笔记本电脑上运行多个 Claude Code 或 Codex 会话？单机使用指南介绍了 worktree、无人值守落地、重型门禁、睡眠与静默时段、推送保护和结果报告，且每项都经过临时仓库测试。

不适用对象

以下情况可能不需要 mergetrain：

• 一次只有一个人或 Agent 落地一个分支；
• 每项更改都已通过 PR 和代码托管平台原生的合并队列；
• 你需要托管式审查界面、组织范围的权限系统或远程运行器服务；或
• 你在寻找通用任务队列、CI 提供商或部署平台。

对于以 PR 为先的团队，请使用 GitHub Merge Queue 或 GitLab Merge Trains。mergetrain 适用于以本地 Agent 和 worktree 为先的集成流程，可在 PR 之前或与 PR 配合使用。

默认采用批处理；需要时按顺序处理

从默认的 batch 模式开始。 它适合并行 Agent 的独立工作。运行器会合并启动时队列中已有的任务；它不会等待所有 Agent 都完成。兼容的任务可以先落地，同时由 Agent 修复失败的提交。

如果每项更改都需要单独落地，并且即使发生失败和重试也必须保留原始提交顺序，请使用 ordered 模式。

比较项	batch（默认）	ordered（可选）
Agent 工作示例	A 修复登录问题，B 添加搜索筛选器，C 更新管理界面	A、B 和 C 分别进行编译器优化；每项更改都基于上一项已落地的结果进行测量
落地单位	一起落地当前可处理的提交	一次落地一个提交
如果 B 失败	隔离 B 并通过 A+C 的检查后，A+C 可以落地	A 可以落地；C 必须等到 B 修复并落地，或被明确取消后才能继续
B 执行 retry 后	加入队列末尾	保留 B 在原队列中的位置，排在 C 之前

两种模式都允许 Agent 在交接后开始下一个任务，也都保留部署审批和默认的推送前复查。由于每项提交都单独落地，按顺序处理可能会更频繁地运行检查。队列顺序从提交时开始计算，而不是从 Agent 开始工作时计算，也不表示代码依赖关系。顺序在 Git 成功落地后结束。后续推送验证警告仍会显示，同时后续任务会继续处理；如果推送状态不确定，仍需进行核对。

可用性： ordered 适用于 3.6.0 及更高版本。 普通的并行 Agent 工作请保留默认的 batch 模式。 参见Agent 工作示例、配置和升级步骤。

强制执行边界

租约令牌可限制并发和过期的 mergetrain 运行器。但它们不会拦截拥有 Shell 访问权限和集成分支凭据的任务 Agent 执行任意 git push。若要将“只有一个运行器负责推送”变为强制执行的属性，而不只是协议假设，请使用以下拓扑：

task agents: commit + exact-SHA enqueue; no integration push credential
runner:      separate deploy identity
remote:      protected integration branch; runner or reviewed PR path only

如果没有凭据隔离和远程保护，mergetrain 仍能提供安全的列车组装和恢复语义，但无法阻止参与者绕过队列。参见安全边界。

运行真实演示

uvx mergetrain demo

演示会创建一个临时仓库和本地裸远程仓库，然后按入队顺序让 4 个真实分支依次合并，演示仅合并后的门禁失败、冲突归因，以及部署兼容的队列。使用 --keep 可在之后检查结果。添加 --brief --pause，可在继续之前阅读每个步骤。扩展工作流录屏还展示了修复、验证期间提交的工作、下一批任务，以及 3 次经过验证的本地部署。

完整 CLI 录屏

安装和首次运行

# Install the machine-level CLI
uv tool install mergetrain          # or: pipx install mergetrain
# macOS: brew install yongjip/tap/mergetrain

# Codex: add the Git marketplace, then install the native skill + pinned MCP server
codex plugin marketplace add yongjip/mergetrain --ref main
codex plugin add mergetrain@mergetrain

# agy: install the native skill + pinned MCP server
agy plugin install https://github.com/yongjip/mergetrain

如需为 VS Code / GitHub Copilot 安装或直接配置 MCP，请参阅 MCP 安装与部署确认指南。

初始化仓库：

cd /path/to/your/repo
mergetrain init --project my-app --write

在 .mergetrain.yaml 中至少添加一道项目门禁。新配置的 gates: [] 表示不会运行任何项目测试。对于使用 pytest 的 Python 项目：

gates:
  - name: tests
    run: python -B -m pytest -q -p no:cacheprovider

请使用适用于你项目的测试命令。门禁必须确保组装后的检出内容保持不变。init 还会创建 AGENTS.mergetrain.md 和 CLAUDE.mergetrain.md。请在现有的 AGENTS.md 或 CLAUDE.md 中链接到这些文件。 通过常规集成流程提交并合入配置和说明，然后再创建任务工作树。

任务 Agent 在自己的工作树中将干净的分支提交后：

mergetrain status --json
mergetrain enqueue \
  --task "add health check" \
  --branch agent/health

任务 Agent 在入队后即停止。从操作员检出目录运行以下命令，以执行已获授权的验证和部署：

mergetrain status
mergetrain deploy

对于长时间运行的门禁，可提前运行 mergetrain validate；它绝不会推送，并会让一个确切的队列保持 Ready 状态，以便之后通过 deploy 确认部署。

deploy 指定配置的原子 Git 引用更新；它不表示要发布到 App Store、Kubernetes 或其他提供商。

Agent 负责提交并入队。一个运行器负责合并 → 测试 → 推送 → 验证。 无人值守的守护进程只会处理由人工使用 --auto 明确入队的任务。对于手动任务，daemon --validate-only 可在后台执行合并和门禁，但会在已验证队列的审批环节暂停，绝不会推送。

有关配置、守护进程和多仓库 Hub 设置，请参阅快速入门。

集成并行 Claude Code 会话和 Codex 工作树

当并行 Claude Code 会话或并行 Codex 工作树在同一仓库中生成已提交的分支时，请使用 Git 工作树合并队列。插件安装指南 介绍了如何将这两种客户端接入队列。任务 Agent 负责提交、入队，然后停止。另一个经过单独授权的运行器负责测试合并后的分支并处理推送。

对于由 Orca 管理的工作树，请参阅 Orca 设置和队列指南，了解经过测试的终端命令、共享队列行为、验证和修复。 Orca Agent 指南还介绍了原生 Codex、Claude Code 和 agy 插件设置，以及有范围限制的任务和验证提示词。

为什么不直接使用 worktrees 和 git merge？

Worktrees 解决的是并行编辑问题。mergetrain 解决的是串行集成问题。

集成方面	Worktrees + 手动合并	mergetrain
合并顺序	由某个人或 Agent 反复决定	按入队顺序排列的持久队列
组合验证	每次合并后手动重新运行	在精确组装好的集成队列上运行门禁
跨分支故障	手动排查	隔离运行可定位冲突的分支对
推送权限	每个会话都可能争抢引用	由一个受租约保护的运行器负责推送
审批	Shell 约定	明确指定验证或部署意图；--auto 为可选项
崩溃恢复	根据本地日志推断	对照远程引用核对 SQLite 证据

Agent 保留各自独立的 worktree。一个 mergetrain 运行器负责集成它们已提交的结果。

为什么不使用 GitHub 或 GitLab 合并队列？

它们解决的是相关问题，但面向不同的工作模式。

	Forge 原生队列	mergetrain
主要单元	Pull/Merge Request	已提交的本地任务分支
验证	Forge 合并组 + 远程 CI	本地组装的集成队列 + Shell 门禁
评审	内置对话和审批	没有代码评审界面
基础设施	Forge 集成和托管服务	本地 SQLite、Git worktree、任意 Git 远程仓库
最适合	以 PR 为先、采用分布式评审的团队	高吞吐量的本地 Agent 集成

两种模式可以共存：将经过验证的集成队列推送到评审分支并创建一个 PR，或者仅为需要讨论的更改保留单独的 PR。 PR 工作流指南 介绍了直接、单 PR、拆分 PR 和仅验证等模式。

恢复中断的 Git 推送

Git 推送停止或超时，并不能证明远程端是否已接受更新。mergetrain 会记录部署证据。其恢复流程会在再次尝试前检查远程引用。请先运行 mergetrain status --json，然后按照报告的恢复操作及其审批要求执行。请参阅 恢复指南。

核心安全保证

• 精确的列车身份。 审批会指定任务 HEAD 和集成基线； 分支发生变化或基线移动，都无法悄然复用该审批。
• 推送前通过组合门禁。 分支通过还不够。组装好的列车必须通过已配置的门禁， 否则不会有任何内容合入。
• 单一且受围栏保护的 mergetrain 所有者。 SQLite 声明和租约令牌可防止 并发或过期的 mergetrain 运行器修改同一列车；远程强制执行还需要上述凭据拓扑。
• 原子远程更新。 负载引用与永久的 refs/mergetrain/deploys/<sha> 恢复引用会一起更新。
• 依据远程真实状态恢复。 预写标记和固定的提交让 reconcile 能判断被终止的推送是否已生效，既不会重放成功的部署，也不会把未完成的部署判定为已发布。
• 明确的自动化。 直接运行不会部署。守护进程只处理预先批准的 --auto 作业，且其目标位置以及门禁／复用／验证策略必须仍然匹配；MCP 部署仍需可追溯的人工确认。
• 单一状态入口。 status 将内部细节归纳为 Waiting、Running、Ready、Attention 和 Done，并返回下一条安全命令。 只有在需要时，inspect 才会提供作业级证据。

队列状态、锁定、列车组装和门禁都在本地执行。配置的 Git 远程和推送后验证仍可能使用外部服务。门禁和验证命令属于受信任代码；启用无人值守作业前，请查看 安全边界。

这些保证已在 macOS 和 Linux 上通过 Python 3.10–3.14 测试，也在 Windows 上进行了测试，其中包括围绕 git push --atomic 的真实 Git 故障注入。专用浸泡测试仓库以 100% 的合入率完成了 20 列列车，其中包括计划内的冲突恢复，以及一次真实的推送终止后协调，其判定结果与远程状态一致。请参阅 浸泡测试证据， 然后使用 mergetrain stats --json 查看你自己的队列证据。

深入了解

• 入门：快速入门 · 安装 · CLI · 配置
• 理解：设计与架构 · 机器契约 · PR 工作流对比
• 运维：高效运维 · 故障模式与恢复 · 升级 · 守护进程 · 多仓库 Hub
• 建立信任并扩展：安全 · Agent 契约 · Agent 采用基准测试 · 不依赖产品名称的发现基准测试 · 本地多 Agent 基准测试 · MCP 服务 · 适配器模式 · 产品范围

稳定接口

常规 CLI 刻意限制为六个动词：

init  status  enqueue  validate  deploy  inspect

第 3 版是长期使用的产品语法。我们没有规划 v4：新功能必须适配这些动词，或保留在高级运维界面中；除 兼容性政策 中记录的契约版本升级外，v3 JSON 和 MCP 契约均以增量方式演进。

最新发布版本见上方的 PyPI 徽章。 欢迎通过 GitHub 提交问题和运维报告。

许可证

根据 MIT 许可证发布。