Quilt 是一个命令行工具，用于在多个 AI 编码代理共享同一个 Git 检出时，追踪每一行代码由哪个代理编写。它捕获工具边界的每次编辑，维护逐行的作者记录，并在提交时重建每个代理自己的更改。Git 仍是唯一事实来源，Quilt 不调用 LLM 也不生成代理，其状态保存在可删除的 .quilt/ 侧车目录中，不会影响仓库本身。
用途
Quilt 旨在解决多个 AI 编码代理在同一个 Git 检出中协作时的常见问题：普通的 git 命令会意外地将其他代理未提交的文件卷入提交，代码生成和锁文件变动可能被错误归因，两个代理偶尔会修改同一行导致静默覆盖。Quilt 让共享检出变得安全，每个代理只提交自己的行，互不干扰，当两个代理确实需要同一段代码时，会变成协调的交接而非静默丢失。
主要能力
- 行级归属：
commit --mine只提交你自己的行，即使与其他代理共享同一个代码块。 - 符号级声明：可以声明
utils.js#formatPrice这样的符号，而不是整个文件，这样编辑不同函数的代理不会冲突。支持通过 tree-sitter 解析的十种语言，其他语言则使用整文件声明。 - 冲突预防：当写入其他代理已声明的代码时，会在任何字节改变之前被拒绝，并显示持有者的声明意图。
- 推送感知：声明一个依赖于其他代理正在修改的函数的符号时，Quilt 会在声明时发出警告。
- 检测与保留：如果一个代理覆盖了另一个代理未提交的行，Quilt 会快照受害者的版本，确保不会静默丢失。
- 每个提交都是普通 Git 提交：Quilt 信任 Git 且从不重写它，所有状态本地保存在 .quilt/ 下。无需账户，无需守护进程。
- 自动命名代理：每个 Claude Code 会话或 MCP 连接都会获得自己的 ID，无需设置即可区分并行代理。
使用方式
- 在包含多个仓库的目录中运行
quilt setup，它会配置工作区根目录和内部每个仓库，每次编辑都会捕获到文件所属的仓库中。 - 无需设置 QUILT_ACTOR 或每个终端的仪式，捕获钩子会自动将每次编辑归属到其会话。
- 使用
quilt fleet实时查看，当会话的工作准备就绪时，让代理运行quilt commit --mine -m "..."。每个提交只包含该会话的行，即使两个会话修改了同一个文件。 quilt ui在浏览器中打开实时视图：谁写了什么（每个文件每个代理的行数）、活跃声明、谁被谁阻塞、以及任何需要人工处理的事项。仅本地（127.0.0.1），只读，一条命令。- 终端用户可以使用
quilt fleet --watch获得相同的文本视图。 - 需要跨会话稳定的 ID 时，可以显式设置。
- 在共享 shell 中，使提交者明确（
quilt --as auth-agent commit --mine ...）。当脏树显示其他代理时，Quilt 拒绝检出全局会话身份。 - 如果部署提供商要求可识别的 Git 邮箱，可以设置一次，同时保持代理名称不同。
适用场景
- 多个 AI 编码代理需要在同一个仓库中并行工作，共享一个 node_modules、一个构建、一个开发服务器、一个环境。
- 代理处理不相交的文件或同一文件的不同函数，需要确保各自的更改独立提交。
- 需要协调两个代理对同一代码的修改，避免静默覆盖。
- 希望保持 Git 作为唯一事实来源，不引入额外的工作树或复杂的环境隔离。
限制
- Quilt 不调用 LLM 也不生成代理，仅追踪和协调编辑。
- 符号级声明支持十种语言（通过 tree-sitter），其他语言仅支持整文件声明。
- 状态保存在本地 .quilt/ 目录，删除该目录不会影响仓库，但会丢失追踪信息。
- 需要运行
quilt setup来配置捕获钩子和共享 MCP 服务器。 - 对于完全独立、长时间运行的任务，工作树可能更合适；Quilt 和工作树可以互补使用。
- 遥测：每天一次匿名心跳（quilt 版本、操作系统、Node 主版本、随机本地 ID），除非在
quilt setup时选择加入，否则不收集其他信息，且从不收集代码、路径、仓库或代理名称。可以通过quilt telemetry off、QUILT_TELEMETRY=0或DO_NOT_TRACK=1关闭。
更多信息请参阅 docs/orchestrators.md（运行代理舰队）、docs/reference.md（完整命令列表、归属工作原理和 .quilt/ 状态布局）以及 bench/（测试场景阶梯）。
