SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场claude-code-merge-queue

claude-code-merge-queue

智能体与模型

查看项目

更新于 10-16 15:54

技能介绍

用途

Claude Code Merge Queue 是面向并行 Claude Code 智能体的本地合并队列。当同时运行多个 claude --worktree 会话时，它用于解决以下问题：

  • 推送竞争：多个智能体推送到同一分支，导致推送被拒和反复 rebase
  • 构建争抢：并发构建压垮机器
  • 测试冲突：测试访问共享资源（数据库、端口）时相互干扰

该工具通过 FIFO 队列串行化代码落地，并在所有 lane 之间协调构建。

主要能力

  • 串行化落地：同一时间机器范围内只有一个 lane 可以推送
  • 检查先行：推送前必须通过 checkCommand
  • 自动清理：移除已落地的同级 lane worktree
  • 构建锁：通过 build-lock 串行化重构建命令
  • 端口分配：按 lane 编号派生开发服务器端口
  • 工作树预览：将 lane 工作树（含未提交变更）镜像到主检出目录
  • 两阶段分支模型：支持 integration 分支到 production 分支的晋级流程

安装

npm install --save-dev claude-code-merge-queue

其他包管理器：

pnpm add -D claude-code-merge-queue
yarn add -D claude-code-merge-queue
bun add -d claude-code-merge-queue

使用方式

初始化：

npx claude-code-merge-queue init

初始化会自动配置 claude-code-merge-queue.config.mjs、CLAUDE.md、.claude/settings.json 中的 WorktreeCreate 钩子、.husky/pre-push、package.json 脚本以及推送前预检安全机制。

核心命令：

  • claude-code-merge-queue hook worktree-create：Claude Code 的 WorktreeCreate 钩子，运行 claude --worktree 时自动创建编号 lane，生成 ../project-lane-1、../project-lane-2 等 worktree
  • claude-code-merge-queue land：将当前 lane rebase 到 integration 分支并通过 FIFO 队列推送
  • claude-code-merge-queue sync：将主检出目录快进到最新，并在需要时重装依赖
  • claude-code-merge-queue promote：将 integration 分支发布到生产，仅限人工执行
  • claude-code-merge-queue preview / preview:restore：将 lane 工作树镜像到主检出目录或切回
  • claude-code-merge-queue build-lock -- <cmd>：在所有 lane 之间串行化重构建命令
  • claude-code-merge-queue port：返回 lane 的开发服务器端口
  • claude-code-merge-queue prune：立即移除已落地的同级 worktree

典型日常流程：

claude --worktree feature-x        # 启动隔离 lane
npm run land                       # 测试通过后落地
npm run sync                       # 更新主检出目录
npm run preview                    # 无需构建即可预览
npm run preview:restore            # 切回
npm run promote                    # 发布到生产

配置

配置文件为 claude-code-merge-queue.config.mjs（ES module 格式），可配置项包括：lane 命名（branchPrefix、worktreeSuffix）、端口分配（portBase）、分支策略（integrationBranch、productionBranch、protectedBranches）、落地要求（checkCommand、checksRequired）、构建协调（regenerableFiles、buildOutputDirs）以及共享资源软链接（symlinks，如 .env、node_modules）。

两阶段分支模型示例中，integrationBranch 设为 staging，productionBranch 设为 main，智能体落地到 staging，人工决定何时通过 promote 发布到 main。

预推送钩子会阻止：直接推送到 integration 分支、推送到 production 分支、以及任何未通过 checkCommand 的推送。紧急情况下可使用 CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 绕过队列，该机制为约定而非加密强制。

适用场景

  • 同时运行多个隔离 worktree 智能体的项目
  • 需要串行化落地以避免推送竞争和 rebase 的团队
  • 并发构建会压垮机器、需要构建锁的场景
  • 测试使用共享资源（端口、数据库、临时文件），需要隔离的场景
  • 多包仓库（monorepo）中需要为每个 lane 分配独立数据库目录的测试
  • 需要 staging 到 production 两阶段发布流程的项目
  • 希望智能体在本地测试通过后自动落地、无需人工介入的工作流

限制

  • 运行时零依赖，全部锁定与协调基于内置 fs 模块、进程 ID 检查和 Git 原生 worktree 支持
  • 紧急绕过机制为约定，不具备加密强制力
  • 队列实现使用 os.tmpdir() 中的文件系统锁，通过独占文件创建实现原子操作，PID 标记保证崩溃安全
  • 若 lane 相对 origin 已过期，会出现 command not found: claude-code-merge-queue，需 fetch 并 rebase 到最新 integration 分支
  • 若进程在 land 中途崩溃，下一次 land 会检测到 PID 已死并回收锁
  • lane 中测试失败但本地通过时，多为共享资源冲突，需检查端口、数据库隔离和临时文件位置
  • 队列负责本地协调，CI 是已落地代码的第二道检查点