基于 AST 的代码合并工具 Weave：解决重构场景下的语义冲突

Git 的三路合并算法是软件工程中最优雅的工具之一，但它有一个根本局限：它只理解行，不理解代码。当 Alice 在文件末尾添加 validateToken() 函数，Bob 在同一文件添加 formatDate() 函数时，Git 会因为上下文行重叠而报冲突 —— 尽管这两个函数完全独立、互不干扰。这种 "假冲突" 在多人协作和 AI Agent 批量作业场景下被急剧放大。

Weave 是 Ataraxy Labs 推出的实体级语义合并驱动，它通过 AST（抽象语法树）解析替代传统的文本行比对，从根本上解决这个问题。

核心机制：从行级到实体级

传统 diff3 算法的工作单元是文本行。它比较 base、ours、theirs 三个版本的行号范围，一旦发现重叠就保守地标记冲突。Weave 改变了这一范式：

第一步，语义解析。Weave 使用 tree-sitter 将三个版本的代码解析为结构化实体：函数、类、方法、JSON 键值对等。每个实体携带类型、名称、作用域等元数据。

第二步，实体匹配。通过复合标识符 file:type:name:parent 在三版本间匹配同一实体。即使代码被移动或重排，只要语义身份不变，就能正确追踪。

第三步，独立合并。Weave 以实体为最小合并单元：若双方修改的是不同实体，自动合并无冲突；若修改同一实体，则尝试实体内的三路合并；仅当同一实体被不兼容修改时才标记真实冲突。

这种设计带来一个关键性质 ——合流性（Confluence）：如果双方修改的实体集合无交集，合并结果与顺序无关，必然收敛。这对 AI Agent 工作流至关重要，Agent 可以在编辑前检查目标实体是否被占用，获得数学级的合并成功保证。

工程化落地参数

将 Weave 集成到现有工作流需要以下配置：

安装与注册：

brew install ataraxy-labs/tap/weave
git config merge.weave.name "Entity-level semantic merge"
git config merge.weave.driver "/usr/local/bin/weave-driver %O %A %B %L %P"

文件类型绑定（.gitattributes）：

*.ts *.tsx *.js *.py *.go *.rs *.json *.yaml *.toml *.md merge=weave

Weave 目前支持 TypeScript、JavaScript、Python、Go、Rust、JSON、YAML、TOML、Markdown。对于不支持的文件类型或超过 1MB 的大文件，自动回退到传统行级合并。

预览模式（推荐在 CI 中启用）：

weave-cli preview feature-branch

输出示例会标明每个文件的合并状态：auto-resolved、unchanged、conflict，以及冲突实体的具体信息如 function 'process': both modified。

冲突标记的语义增强

当真实冲突发生时，Weave 提供的冲突标记包含语义上下文：

<<<<<<< ours — function `process` (both modified)
export function process(data: any) {
    return JSON.stringify(data);
}
=======
export function process(data: any) {
    return data.toUpperCase();
}
>>>>>>> theirs — function `process` (both modified)

相比 Git 的匿名冲突块，开发者能立即识别冲突实体类型、名称和原因，大幅降低人工介入的认知负担。

架构与扩展性

Weave 采用模块化架构：

• weave-core：核心库，负责实体提取、三路合并算法、代码重构
• weave-driver：Git 合并驱动二进制文件，处理 % O % A % B % L % P 参数
• weave-cli：命令行工具，提供 setup 和 preview 命令
• weave-crdt：基于 Automerge 的 CRDT 协调状态层
• weave-mcp：MCP 服务器，提供 9 个工具供 AI Agent 调用

实体提取依赖 sem-core 库，底层使用 tree-sitter 语法解析器。这种分层设计使得添加新语言支持只需提供对应的 tree-sitter grammar，无需改动合并逻辑。

适用场景与限制

最佳适用场景：

• 多 Agent 并行作业同一仓库，频繁出现 "假冲突"
• 大型配置文件（JSON/YAML）的多键独立修改
• 重构场景下的代码移动与重命名

已知限制：

• 文件大小超过 1MB 时回退到行级合并
• 极度复杂的跨实体依赖变更仍需人工审查
• 需要 tree-sitter 支持的语法才能生效

总结

Weave 代表了版本控制从文本层面向语义层面的演进。它不改变 Git 的工作流，不替换存储模型，仅在合并环节介入，用 AST 解析消除结构性假冲突。对于正在构建 AI Agent 协作平台的团队，Weave 提供的合流性保证和语义冲突标记，能显著降低自动化流水线的中断率。

参考来源：

• Ataraxy Labs, "weave — Entity-Level Git Merge Driver", https://ataraxy-labs.com/weave
• Ataraxy Labs, "What if Merges Understood Your Code?", https://ataraxy-labs.com/blogs/what-if-merges-understood-code

systems