# https://github.com/funador/claude-code-merge-queue 项目说明书

生成时间：2026-07-30 03:48:32 UTC

## 目录

- [项目概述与价值定位](#page-1)
- [系统架构与核心库实现](#page-2)
- [CLI 命令、Git/Claude 钩子与典型工作流](#page-3)
- [配置参考、紧急出口与已知的运维边界](#page-4)

<a id='page-1'></a>

## 项目概述与价值定位

### 相关页面

相关主题：[系统架构与核心库实现](#page-2), [配置参考、紧急出口与已知的运维边界](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/funador/claude-code-merge-queue/blob/main/README.md)
- [package.json](https://github.com/funador/claude-code-merge-queue/blob/main/package.json)
- [CHANGELOG.md](https://github.com/funador/claude-code-merge-queue/blob/main/CHANGELOG.md)
- [docs/overview.md](https://github.com/funador/claude-code-merge-queue/blob/main/docs/overview.md)
- [.github/workflows/release.yml](https://github.com/funador/claude-code-merge-queue/blob/main/.github/workflows/release.yml)
</details>

# 项目概述与价值定位

`funador/claude-code-merge-queue` 是一个面向 Claude Code 工作流的合并队列（Merge Queue）工具，旨在为使用 Claude Code 进行自动化协作与代码评审的团队提供受控、有序、可追溯的合并流程。仓库名称中的「merge-queue」明确指出了其核心定位：替代直接 `git merge` 的粗放模式，转而通过队列化调度来组织 PR / 补丁的合入行为，资料来源：[README.md:1-30]()。

仓库当前已发布至 `v0.5.8` 版本，从 `v0.4.0` 至 `v0.5.8` 共完成五个次版本的迭代（v0.5.0、v0.5.1、v0.5.2、v0.5.3、v0.4.0 之前），说明该工具已经从实验性原型演进到具备稳定发布节奏的工程化项目。每次发版均提供 GitHub Compare 链接，体现了项目对变更可追溯性的重视，资料来源：[CHANGELOG.md:1-60]()。

## 核心价值主张

项目的核心价值可以从「可控性」「可观察性」「可组合性」三个维度进行概括：

- **可控性**：将散落在多个工作分支中的 Claude Code 生成改动纳入统一队列，避免并发合并造成的冲突与状态丢失。队列机制使每次合入都可被策略地允许、拒绝或回滚，资料来源：[docs/overview.md:10-45]()`。
- **可观察性**：通过 Release / Workflow 自动化通道对每一次队列事件产生可审计的痕迹。`.github/workflows/release.yml` 中规定的版本发布流水线同时承担了变更记录的职责，资料来源：`.github/workflows/release.yml:1-40]()`。
- **可组合性**：作为 Claude Code 使用链路的中间层，既不替代底层 Git 平台，也不耦合特定的 CI 系统；它面向任何希望序列化 Claude Code 输出的团队，资料来源：[README.md:30-80]()`。

## 版本演进与产品成熟度

下表汇总了项目自 `v0.3.0` 以来的版本脉络，反映出从「可用」走向「稳定」的演进路径：

| 版本 | 时间坐标（按发布顺序） | 关键变化定位 |
| --- | --- | --- |
| v0.4.0 | 0.x 阶段重大节点 | 功能集合首次形成闭环 |
| v0.5.0 | 0.5 系列起点 | 队列调度模型重构 |
| v0.5.1 — v0.5.8 | 0.5 系列增量 | 缺陷修复、配置项兼容、文档完备化 |

资料来源：[CHANGELOG.md:1-60]()、各版本 Compare 链接（`compare/v0.5.7...v0.5.8` 等）。

在 0.5 系列内部的高频次版本发布（自 v0.5.0 起共 8 个次版本）表明作者在持续进行 API 收敛与边界用例修复；这种发布节奏通常意味着项目已经具备一组相对稳定的对外接口，资料来源：[package.json:1-40]()`。

## 适用场景与边界

项目的典型使用场景包括：

1. **多人协作的 Claude Code 自动化流水线**：当多个 PR 几乎同时由 Claude Code 生成并提交时，合并队列能够决定一次只允许一条改动触发最终集成。
2. **可重复的集成环境**：在 CI 中以固定顺序合入 Claude Code 输出，降低「上一次合入破坏了上一次测试」的概率，资料来源：[docs/overview.md:45-80]()`。
3. **审计与合规要求较高的团队**：每一次合入均产生可关联的队列事件，便于事后追溯。

需要注意的是，作为 `0.5.x` 阶段的工具，其语义版本号尚未升至 `1.0.0`，因此使用者应在升级路径上保留对破坏性变更的容忍度，资料来源：[package.json:1-40]()`。同时，工具并不取代 `git rebase` 或分支策略，而是作为它们的执行层而存在。

## 与上层系统的关系

```mermaid
flowchart LR
    A[Claude Code 生成改动] --> B[Merge Queue 调度]
    B --> C[策略校验 / 串行合并]
    C --> D[CI / 集成验证]
    D --> E[主干分支]
    B -.审计.-> F[可追溯事件流]
```

资料来源：[README.md:30-80]()、[docs/overview.md:10-80]()`。

综上，`claude-code-merge-queue` 的价值定位可以浓缩为一句话：**为 Claude Code 的产出物提供一条受控、可追溯、可组合的合入通道**，使自动化生成代码这一行为具备与人工提交同等量级的工程治理能力。

---

<a id='page-2'></a>

## 系统架构与核心库实现

### 相关页面

相关主题：[项目概述与价值定位](#page-1), [CLI 命令、Git/Claude 钩子与典型工作流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/bin/claude-code-merge-queue.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/bin/claude-code-merge-queue.ts)
- [src/lib/config.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/lib/config.ts)
- [src/lib/build-lock.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/lib/build-lock.ts)
- [src/lib/queue-lock.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/lib/queue-lock.ts)
- [src/lib/check-command.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/lib/check-command.ts)
- [src/lib/check-push.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/lib/check-push.ts)
</details>

# 系统架构与核心库实现

## 1. 系统定位与总体架构

`claude-code-merge-queue` 是一个面向 PR 自动串行合并的「合并队列」守护进程，其核心职责是在单一共享构建资源（如 CI runner）上，按照入队顺序依次处理待合并的 Pull Request，确保任意时刻仅有一个候选变更占用构建机。该项目以 TypeScript 实现，采用 `bin` + `lib` 目录分层，将 CLI 入口与可复用的核心库模块清晰分离。

整体架构可以分为三层：

- **入口层**：`src/bin/claude-code-merge-queue.ts` 负责解析命令行参数并装配运行时上下文，把控制流转交给库模块。
- **核心库层**：`src/lib/` 下的若干模块封装了配置、锁、检查、推送等横切能力，对外暴露纯函数式或基于 Promise 的 API。
- **外部交互层**：通过 Git 平台 API、shell 子进程和文件锁与外部系统协作。

资料来源：[src/bin/claude-code-merge-queue.ts:1-40](), [src/lib/config.ts:1-60]()

## 2. 核心库模块详解

### 2.1 配置管理（config）

`src/lib/config.ts` 是整个系统行为的中枢，定义了所有可调参数（如队列最大长度、单 PR 超时、轮询间隔、允许的目标分支等）。它通常以单一聚合对象的形式导出，默认值叠加用户提供的 JSON/YAML 覆盖，从而避免在多处硬编码常量。该模块是 CLI 入口与所有锁/检查模块之间的「共享 truth source」。

资料来源：[src/lib/config.ts:1-120]()

### 2.2 锁原语：build-lock 与 queue-lock

合并队列最难正确处理的部分是「同一构建机只能被一个 PR 占用」的语义。项目中以两个相互独立但协作的锁模块来表达：

- `src/lib/build-lock.ts`：表示构建机资源占用锁。一旦申请成功，便阻止其他 PR 进入构建阶段；构建结束后无论成功失败都必须释放。
- `src/lib/queue-lock.ts`：表示队列状态写入锁，用于序列化对队列文件（如 JSON/NDJSON）的修改，避免在并发轮询时出现状态撕裂。

两者通常基于本地文件系统（`fs.open` + `flock`）实现，部分版本也会支持分布式后端。

资料来源：[src/lib/build-lock.ts:1-80](), [src/lib/queue-lock.ts:1-90]()

### 2.3 检查与推送（check-command / check-push）

`check-command.ts` 与 `check-push.ts` 是「合并前最后一道闸门」，分别负责：

- `check-command`：在合并动作之前执行用户配置的任意检查命令（如 `npm test`、`pnpm lint`），并将退出码与超时信息回传。
- `check-push`：模拟 `git push` 等价行为或直接验证远端分支状态，确保在落盘合并结果前，远端历史与本地一致。

二者通常返回结构化的 `CheckResult`（含 `ok: boolean`、`reason: string`），以便上游调度器决定是否「放行」或「回滚」。

资料来源：[src/lib/check-command.ts:1-70](), [src/lib/check-push.ts:1-75]()

## 3. 控制流与状态机

整个守护进程的核心循环可抽象为以下流程：

```mermaid
flowchart TD
    A[CLI 启动] --> B[加载 config.ts 默认值]
    B --> C[申请 queue-lock 读取队列]
    C --> D{队列为空?}
    D -- 是 --> E[休眠轮询间隔]
    E --> C
    D -- 否 --> F[取出队首 PR]
    F --> G[申请 build-lock]
    G --> H[执行 check-command]
    H --> I{通过?}
    I -- 否 --> J[释放锁, 标记失败]
    I -- 是 --> K[执行 check-push]
    K --> L{通过?}
    L -- 否 --> J
    L -- 是 --> M[合并并推送]
    M --> N[释放 build-lock 与 queue-lock]
    N --> C
    J --> C
```

资料来源：[src/bin/claude-code-merge-queue.ts:40-100](), [src/lib/queue-lock.ts:30-90](), [src/lib/build-lock.ts:20-80]()

## 4. 版本演进与社区关注点

从社区提供的 release 记录（v0.4.0 → v0.5.8，详见 [v0.5.8 changelog](https://github.com/funador/claude-code-merge-queue/compare/v0.5.7...v0.5.8)）可以看到，过去若干次小版本几乎全部聚焦在并发安全与配置灵活性上：包括锁获取路径的修复、check-command 超时语义调整、check-push 远端校验的兼容性回填。最新 v0.5.8 相对于 v0.5.7 的变更主要在错误日志粒度与默认值收敛，说明项目维持「小步快跑、API 向前兼容」的演进节奏，这也意味着：

- 二次开发者在升级时，`src/lib/config.ts` 的字段最可能成为破坏点；
- 自定义 `check-command` 脚本需关注退出码契约是否改变；
- 锁模块虽稳定，但 `build-lock.ts` 与 `queue-lock.ts` 的内部路径若变更，会对依赖文件位置的运维脚本产生影响。

资料来源：[src/lib/config.ts:1-60](), [src/lib/build-lock.ts:1-40](), [src/lib/queue-lock.ts:1-40](), [src/lib/check-command.ts:1-50](), [src/lib/check-push.ts:1-50]()

---

<a id='page-3'></a>

## CLI 命令、Git/Claude 钩子与典型工作流

### 相关页面

相关主题：[系统架构与核心库实现](#page-2), [配置参考、紧急出口与已知的运维边界](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/bin/claude-code-merge-queue.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/bin/claude-code-merge-queue.ts)
- [src/land.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/land.ts)
- [src/sync.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/sync.ts)
- [src/promote.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/promote.ts)
- [src/preview.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/preview.ts)
- [src/build-lock.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/build-lock.ts)
</details>

# CLI 命令、Git/Claude 钩子与典型工作流

本页概述 `claude-code-merge-queue` 的命令行界面、与 Git 钩子及 Claude Code 钩子的集成方式，并串联起提交、晋级、预览与合并的端到端流程。该项目面向使用堆叠 PR（stacked PR）开发模型的团队，使用户能够在 Claude Code 环境中安全、有序地把分支合入主干。资料来源：[src/bin/claude-code-merge-queue.ts:1-1]() 是 CLI 入口文件。

## CLI 命令总览

CLI 入口位于 `src/bin/claude-code-merge-queue.ts`，按照子命令分发到不同的实现模块。仓库中可识别的核心子命令及其职责如下：

- **land**：将合并队列中的分支真正合入主干，并清理已合并的分支引用。资料来源：[src/land.ts:1-1]()
- **sync**：把堆叠分支与远程仓库同步，通常包含 rebase 与 fetch。资料来源：[src/sync.ts:1-1]()
- **promote**：在队列中把某个分支提升至队首，准备下一次合并。资料来源：[src/promote.ts:1-1]()
- **preview**：在合并之前预览分支差异、CI 状态与依赖关系。资料来源：[src/preview.ts:1-1]()

## Git 钩子与 Claude 钩子集成

合并队列的安全运行依赖两类钩子的配合：

| 钩子类型 | 触发时机 | 在本项目中的作用 |
| --- | --- | --- |
| Git 钩子 | `pre-commit`、`post-commit`、`pre-push` 等 Git 事件 | 校验堆叠分支顺序、阻止不规范的推送、维护分支元数据 |
| Claude 钩子 | Claude Code 会话内的工具调用前后（Pre/PostToolUse） | 让 Claude 在创建或修改分支时自动登记队列，并执行 `preview`/`promote` |

`src/build-lock.ts` 是钩子之间共享的并发控制模块，通过文件锁或进程间锁保证同一时刻只有一个分支能进入合并流程，避免 race condition。资料来源：[src/build-lock.ts:1-1]()

## 典型工作流

下面的 Mermaid 图展示了一个完整的堆叠 PR 从本地提交到合并入主干的过程：

```mermaid
flowchart LR
    A[本地修改] --> B[git commit]
    B --> C{Claude 钩子\nPreToolUse}
    C --> D[登记到合并队列\nbuild-lock 加锁]
    D --> E[git push]
    E --> F[CI 触发 preview]
    F --> G{CI 通过?}
    G -- 否 --> H[修复并 sync]
    H --> E
    G -- 是 --> I[promote 至队首]
    I --> J[CI 复跑]
    J --> K{通过?}
    K -- 是 --> L[land 合入主干]
    K -- 否 --> H
    L --> M[清理分支与锁]
```

整个流程的关键点：

1. **登记入队**：Claude 钩子在分支首次被引用时调用队列 API，记录依赖关系并获取 `build-lock`。资料来源：[src/build-lock.ts:1-1]()
2. **预览与同步**：`preview` 命令展示分支差异及上下游状态；`sync` 用于在底层 rebase 后重新对齐堆叠。资料来源：[src/preview.ts:1-1]()、资料来源：[src/sync.ts:1-1]()
3. **晋级**：通过 `promote` 把待合并分支送入队首，触发新一轮 CI。资料来源：[src/promote.ts:1-1]()
4. **合并**：CI 全部通过后，`land` 执行最终的快进或 squash 合并，并释放锁、删除远程分支。资料来源：[src/land.ts:1-1]()

## 命令之间的协作关系

CLI 各子命令并非彼此独立，而是围绕“队列状态机”协作：

- `preview` 是只读操作，可以在任何阶段调用，作为安全检查。
- `sync` 修改本地分支拓扑，调用前通常需要先 `preview` 确认改动范围。
- `promote` 依赖 `build-lock` 保证队首唯一，写入队列元数据后通知钩子。
- `land` 是唯一会改动主干分支的命令，必须等到 `promote` 之后且 CI 成功才可执行。

## 注意事项与最佳实践

- 在运行 `land` 之前务必先 `preview`，确认队列顺序与 CI 状态符合预期。
- `sync` 会触发 rebase，若堆叠较深，可能产生大量冲突；建议小步提交、勤于 `sync`。
- `build-lock` 是并发安全的关键，任何自定义脚本如果绕过它直接操作队列，都可能破坏一致性。
- Claude 钩子负责把对话内的分支操作同步给队列，因此保留默认钩子配置可避免状态漂移。

通过 CLI 命令、Git/Claude 钩子以及 `build-lock` 的协同，`claude-code-merge-queue` 在保留堆叠开发灵活性的同时，提供了与主干持续集成相匹配的合并保障。

---

<a id='page-4'></a>

## 配置参考、紧急出口与已知的运维边界

### 相关页面

相关主题：[项目概述与价值定位](#page-1), [CLI 命令、Git/Claude 钩子与典型工作流](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [examples/claude-code-merge-queue.config.mjs](https://github.com/funador/claude-code-merge-queue/blob/main/examples/claude-code-merge-queue.config.mjs)
- [examples/ephemeral-tmp-dir.example.ts](https://github.com/funador/claude-code-merge-queue/blob/main/examples/ephemeral-tmp-dir.example.ts)
- [src/lib/claude-md-snippet.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/lib/claude-md-snippet.ts)
- [src/lib/config.ts](https://github.com/funador/claude-code-merge-queue/blob/main/src/lib/config.ts)
- [README.md](https://github.com/funador/claude-code-merge-queue/blob/main/README.md)
</details>

# 配置参考、紧急出口与已知的运维边界

## 概览

本页面向需要为合并队列编写自动化、或在生产环境进行故障排查的工程师。内容基于仓库内的示例文件、运行时实现与说明文档，汇总三类信息：

- 配置文件如何被加载与校验；
- 紧急情况下的人工干预手段；
- 当前实现中已显式记录的运维边界。

资料来源：[README.md]()

## 配置参考

### 主配置示例

合并队列的配置入口集中在 `examples/claude-code-merge-queue.config.mjs`。该文件以 ESM 模块形式演示了顶层字段的推荐写法，包括命名空间、临时目录策略、合并判定方式等。建议把它视作 “可拷贝的样板”，而不是直接被运行时加载。

资料来源：[examples/claude-code-merge-queue.config.mjs:1-120]()

### 运行时加载逻辑

实际配置读取与默认值合并在 `src/lib/config.ts` 中完成。该模块同时承担环境变量替换、字段校验与缺失字段回退等职责。任何与默认值相关的疑问，应当先回到该文件而不是示例。

资料来源：[src/lib/config.ts:1-160]()

### 临时目录样例

`examples/ephemeral-tmp-dir.example.ts` 是 `ephemeral` 配置项启用时的标准写法。该示例展示了为每个队列项建立独立临时目录、并在合并判定完成后清理的过程，可以作为生产集成的参考模板。

资料来源：[examples/ephemeral-tmp-dir.example.ts:1-80]()

## 紧急出口

### CLAUDE.md 片段注入

`src/lib/claude-md-snippet.ts` 提供了把上下文片段渲染进 `CLAUDE.md` 的工具。当 Claude 在处理某一队列项时需要人工接管、或需要为后续会话留下 “恢复点” 时，调用方可以执行：

1. 标记目标工作项编号；
2. 在片段中追加恢复说明、待办事项或事后分析注记；
3. 重新触发写入，覆盖旧片段而不影响其他队列项。

由于该片段是幂等产物，这同时也是 “打断但可恢复” 的主要手段。

资料来源：[src/lib/claude-md-snippet.ts:1-110]()

### Drain / Re-enqueue

README 中描述的 `drain` 与 `re-enqueue` 命令用于打断等待中的项，并将其重新写回到上游 issue 列表。该路径不修改 git 历史，适用于 “PR 已合并、但下游机器人尚未确认” 的恢复场景。

资料来源：[README.md]()

## 已知运维边界

下表列出在源码注释与 README 中可被识别的限制，建议在故障排查前列入待办：

| 边界 | 触发条件 | 关联文件 |
| --- | --- | --- |
| 单进程串行处理 | 多实例并发会产生锁竞争 | `src/lib/config.ts` |
| 临时目录假设 POSIX | 在 Windows 或部分网络挂载下 `os.tmpdir()` 行为不同 | `examples/ephemeral-tmp-dir.example.ts` |
| 片段长度上限 | 单次注入超过内置阈值时会被截断 | `src/lib/claude-md-snippet.ts` |
| Node 版本依赖 | 配置示例需要较新版本的 Node 才能运行 | `examples/claude-code-merge-queue.config.mjs`、`README.md` |

资料来源：[src/lib/config.ts]() [examples/ephemeral-tmp-dir.example.ts:80-130]() [src/lib/claude-md-snippet.ts:110-180]() [README.md]()

## 小结

- 配置入口：`examples/claude-code-merge-queue.config.mjs` 与 `src/lib/config.ts`。
- 紧急出口：`src/lib/claude-md-snippet.ts` 提供的片段注入，以及 README 中的 `drain / re-enqueue`。
- 已知边界：单进程串行、POSIX 临时目录假设、片段长度上限、Node 版本约束。

当任一边界被触发时，应优先以本页指针指向的源文件为准，再回退到本维基条目作为索引。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：funador/claude-code-merge-queue

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://news.ycombinator.com/item?id=49104747 | host_targets=claude_code, claude

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://news.ycombinator.com/item?id=49104747 | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49104747 | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=49104747 | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=49104747 | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49104747 | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49104747 | release_recency=unknown

<!-- canonical_name: funador/claude-code-merge-queue; human_manual_source: deepwiki_human_wiki -->