Weave 增量 AST 解析与实体追踪：从行级合并到语义级冲突消解

Git 的默认合并策略基于行级差异比对，当两位开发者在同一文件的相邻行进行修改时，即使修改的是完全不同的函数，也会触发冲突。Weave 通过引入语义级合并驱动，将解析粒度从文本行提升到代码实体（函数、类、模块），在 31 个跨语言测试场景中实现零冲突合并。这一能力的核心支撑是 Tree-sitter 的增量 AST 解析机制与实体追踪系统。

增量 AST 解析：从全量重建到脏子树修复

传统解析器在文件发生变更时需要重新解析整个文件，时间复杂度与文件大小成正比。Weave 采用的 Tree-sitter 基于 GLR（Generalized LR）算法，支持真正的增量解析：当源代码发生编辑时，系统仅标记受影响的子树为 "脏节点"（dirty subtree），并在重新解析时复用未变更的 AST 分支。

Tree-sitter 的增量解析通过 edit/repair hooks 实现。当文件内容变更时，解析器首先计算变更的 byte range，然后在现有 AST 中定位包含该 range 的节点，将其标记为需要重新解析。关键优化在于：如果变更仅影响表达式内部（如修改变量名），而表达式结构保持不变，则该表达式节点本身可以被复用，只需更新其内部 token。这种细粒度的复用策略使得大型文件的增量重解析时间呈亚线性增长。

在 Weave 的合并场景中，这一机制尤为重要。当比较 base、ours、theirs 三个版本的文件时，Weave 不需要为每个版本构建完整的 AST，而是利用 Tree-sitter 的增量能力快速计算版本间的 AST 差异。对于 4,917 个真实文件的合并测试中，增量解析将平均处理时间控制在毫秒级，支撑了生产环境的可用性。

语义实体追踪：函数与类的身份识别

AST 解析只是第一步，Weave 的核心创新在于语义实体的提取与追踪。系统通过 sem-core 层在 AST 之上构建实体图，识别函数定义、类声明、导入语句等可合并单元。每个实体被赋予稳定的身份标识（identity），基于其在代码中的语义角色而非文本位置。

实体追踪面临的首要挑战是变更传播。当函数 A 调用函数 B，而 B 被重命名时，Weave 需要识别这种跨实体的引用变更。系统通过查询语言（Tree-sitter 的 S-expression 查询）在 AST 中定位引用点，建立实体间的依赖图。在合并阶段，如果两个分支分别修改了函数签名和函数体，系统可以判断这些变更是否正交，从而决定是否产生冲突。

Weave 的 CRDT State 层进一步扩展了实体追踪能力，支持 Agent 在编辑前声明对特定实体的占用。这种预声明机制将冲突检测从合并阶段前置到编辑阶段，使得 AI Agent 在并行工作时能够提前感知潜在的编辑冲突。

多语言 Grammar 适配：统一的实体提取抽象

Weave 支持 28 种编程语言的语义合并，这一能力建立在 Tree-sitter 的多语言 grammar 生态之上。每种语言的解析通过独立的 grammar.js 文件定义，Weave 通过统一的实体提取层屏蔽语言差异。

Tree-sitter 的 grammar 定义采用 JavaScript DSL，支持序列（seq）、选择（choice）、重复（repeat）等组合子。对于实体提取，Weave 定义了跨语言的通用实体类型：函数（function）、类（class）、方法（method）、导入（import）等。每种语言的 grammar 通过查询文件（queries/*.scm）将具体语法节点映射到通用实体类型。

以函数提取为例，Python 的函数定义对应 function_definition 节点，而 JavaScript 对应 function_declaration 或 arrow_function。Weave 的查询层通过 S-expression 模式匹配统一处理这些差异：

(function_definition
  name: (identifier) @function.name
  body: (block) @function.body) @function

(function_declaration
  name: (identifier) @function.name
  body: (statement_block) @function.body) @function

这种抽象使得新增语言支持只需提供对应的 Tree-sitter grammar 和查询定义，无需修改核心合并逻辑。目前 Weave 已覆盖 TypeScript、Python、Go、Rust、Java 等主流语言，以及 Vue、Svelte 等框架特定语法。

工程实践：性能参数与监控策略

在生产环境部署语义合并驱动时，需要关注以下可落地参数：

解析性能基线：Tree-sitter 的增量解析在 10,000 行代码文件上的平均重解析时间应低于 50ms。可通过 tree-sitter parse --time 命令进行基准测试。

内存占用控制：AST 节点数约为 token 数的 1.5-2 倍。对于大型文件（>50,000 行），建议设置 AST 缓存上限，避免内存膨胀。

回滚策略：Weave 作为 Git merge driver，在解析失败或超时（默认 30 秒）时应自动回退到行级合并，确保合并流程不中断。可通过 git config merge.weave.timeout 调整超时阈值。

监控指标：

• 语义合并成功率（目标 >95%）
• 平均合并耗时（P99 < 500ms）
• 解析失败率（按语言统计）
• 回退到行级合并的频率

局限与权衡

语义合并并非万能。当两个分支修改了同一函数内部的逻辑时，Weave 仍会报告冲突，因为此时需要人工判断逻辑兼容性。此外，Tree-sitter 的解析在存在语法错误时仍能生成部分 AST，但这可能导致实体识别不准确。建议在 CI 流程中先进行语法检查，再执行语义合并。

多语言支持的深度也存在差异。主流语言（Python、JavaScript、Go）的 grammar 经过充分测试，而小众语言的解析质量可能参差不齐。生产环境中建议对关键语言进行回归测试，验证实体提取的准确性。

资料来源

• Weave 官方文档：https://ataraxy-labs.github.io/weave/
• Tree-sitter 增量解析技术详解：https://tomassetti.me/incremental-parsing-using-tree-sitter/

systems