Weavatrix Git

Weavatrix Git

属于 Weavatrix 生态：为 AI 软件 Agent 提供有界的 Git 证据。

weavatrix-git 为 AI 编码 Agent 提供快速、有界且只读的 Git 证据。 Rust crate、CLI、MCP 服务和 npm 包遵循相同的契约： 直接解析仓库存储。不调用 git 子进程，不使用 C 库、钩子、过滤器或网络访问，也不执行检出或修改。所有接口都不提供写入 API。

在已提交的精确一致性基准测试中，1,000 条热历史记录在 Weavatrix 中耗时 0.355 ms，在 gix 中耗时 0.884 ms，在 libgit2 中耗时 1.552 ms。 在八个仓库中，Weavatrix 在全部五项已测量的 p50 契约中均胜出。这些是发布构建的引擎测量结果；MCP 传输开销有意不包含在此声明中。

运行 MCP 服务

无需 Rust 工具链：

npx -y [email protected] --repository /absolute/path/to/repository

通用 stdio 客户端配置：

{
  "mcpServers": {
    "weavatrix-git": {
      "command": "npx",
      "args": [
        "-y",
        "[email protected]",
        "--repository",
        "/absolute/path/to/repository"
      ]
    }
  }
}

npm 包包含经过验证的原生二进制文件，适用于 Windows x64、Linux x64 和 ARM64，以及 macOS x64 和 ARM64。Node 仅负责选择并启动匹配的二进制文件；仓库解析和 MCP 处理均使用安全 Rust 实现。

面向 Agent 的工具

MCP 工具	返回的证据
git_head	仓库身份、哈希类型、符号化 HEAD、精确目标 ID、pack 数量
git_history	分页提交 ID、树、父项、签名、时间戳、摘要
git_diff	分页列出新增／删除／修改／类型变更的路径，以及旧／新对象 ID
git_status	已跟踪的索引和工作区状态；未跟踪文件由 Repository::worktree_safety() 处理
git_snapshot	修订版本对应的规范化不可变路径、模式、类型和对象 ID 清单
git_worktree_safety	Clean / IgnoredOnly / HasUntracked / DirtyTracked / Unknown；未跟踪和已忽略文件的数量

每个列表工具都会返回 nextCursor、精确对象 ID 和 truncated 标志。 对于非 UTF-8 路径，pathHex 会保留其原始字节；展示文本绝不会被悄然当作精确证据。

运行时限制

MCP 二进制文件使用 mcport 提供的受控、无 Tokio 运行时：

• 请求大小上限为 256 KiB，响应大小上限为 1 MiB；
• 最多四个处理程序同时运行，并使用有界请求／输出队列；
• 处理程序截止时间为 30 秒，并支持协作式取消检查；
• 隔离 panic，并以原子方式报告响应溢出错误；
• 对 Git 对象、历史、树、位图、reflog 和索引读取进行限制；
• 可选进度通知，并支持配置响应批处理。

默认设置适用于交互式 stdio。--help 提供字节预算、并发数、队列、截止时间和批大小的覆盖选项。服务只向 stdout 写入以换行符分隔的 UTF-8 JSON-RPC；诊断信息写入 stderr。

也可通过 Cargo 原生安装：

cargo install weavatrix-git --version 0.3.3 --features mcp \
  --bin weavatrix-git-mcp
weavatrix-git-mcp --repository /absolute/path/to/repository

为什么要单独使用一个 crate？

扫描器负责发现文件。代码图负责对关系建模。这个 crate 负责版本控制证据。将这一边界独立出来后，任何 Rust 应用都能复用 Git 智能，而无需引入更大的产品。

支持的合同

区域	支持情况
布局	worktree、bare、.git 间接引用、通过 commondir 关联的 worktree
哈希	SHA-1 和 SHA-256 对象标识符
引用	松散引用、符号引用、分离的 HEAD、打包引用、reflog
对象	commit、tree、blob、带注释的 tag
松散存储	由此 crate 解码的有界 zlib/DEFLATE
打包存储	PACK v2/v3、索引 v2、OFS_DELTA、REF_DELTA
对象查找	alternates、经典 MIDX、缓存、共享零拷贝快照
Commit 加速	单体和分层 commit-graph 链
路径加速	changed-path Bloom 过滤器 v1/v2
可达性	使用 RIDX 排序的 pack 和 MIDX EWAH 位图
索引	DIRC v2/v3/v4、自动刷新的共享快照
查询	类型化读取、惰性 revwalk、历史、跟踪状态、worktree 安全检查、tree 差异
不可变视图	包含路径、模式和对象证据的规范 commit 快照
横向扩展	并行打开、感知修订的时间线、变更集、关联
扩展	有序、线程安全、只读的自定义 ODB 后端

所有公开读取都在进程内完成。库代码不包含子进程回退。 对于不支持的数据，会返回类型化错误，而非近似结果。

Rust 库

use weavatrix_git::{PathBloom, Repository};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let repository = Repository::open(".")?;
    let head = repository.resolve("HEAD")?;

    for id in repository.revwalk().push_head()?.take(100) {
        println!("{}", id?);
    }

    if repository.commit_maybe_changed_path(head, b"src/lib.rs")?
        == Some(PathBloom::DefinitelyNot)
    {
        println!("the commit definitely did not change src/lib.rs");
    }

    if let Some(objects) = repository.bitmap_reachable(head)? {
        println!("{} reachable objects", objects.len());
    }
    Ok(())
}

自定义存储使用相同的对象合同：

use std::sync::Arc;
use weavatrix_git::{Limits, MemoryObjectBackend, Repository};

let backend = Arc::new(MemoryObjectBackend::default());
let repository =
    Repository::open_with_backends(".", Limits::default(), vec![backend])?;
# Ok::<_, weavatrix_git::GitError>(repository)

进行跨仓库分析时，RepositorySet 会隔离各对象存储，并返回确定性的串行或并行结果：

use weavatrix_git::{HistoryOptions, RepositorySet};

let repositories = RepositorySet::open_parallel([
    ("service", "/code/service"),
    ("client", "/code/client"),
])?;
let histories =
    repositories.histories_from_parallel("HEAD", HistoryOptions::default())?;
let snapshots = repositories.snapshots_parallel("HEAD")?;
let timeline = repositories.timeline("HEAD", HistoryOptions::default())?;
let shared = repositories.shared_commits(HistoryOptions::default())?;
# Ok::<_, weavatrix_git::GitError>((histories, snapshots, timeline, shared))

诊断 CLI 使用此库：

weavatrix-git [-C repository] head
weavatrix-git [-C repository] log [revision] [max-count]
weavatrix-git [-C repository] cat <object>
weavatrix-git [-C repository] diff <old-commit> <new-commit>

架构

Repository
  +-- refs + reflog
  +-- commit-graph chain + changed-path Bloom
  +-- index -> tracked status
  +-- custom ODB backends
  +-- object directories + alternates
        +-- loose object -> bounded zlib
        +-- MIDX -> pack -> bounded delta chain
        +-- pack/MIDX bitmap -> reachable object IDs

Limits 限制对象字节数、缓存字节数、delta/ref/tree 深度、tree 和索引条目数、reflog/历史长度、父对象数量以及位图扩展量。此 crate 禁止使用不安全 Rust。默认库功能集不依赖任何依赖项；只有独立的 mcp 功能会添加 mcport。

源代码树遵循明确的模块边界：

层	职责
model	对象 ID、类型化 Git 对象、错误和验证合同
storage	loose/pack/MIDX/commit-graph 解码、有界解压和缓存
repository	引用、历史、差异、状态、快照、trees 和 revwalk
workspace	确定性的多仓库查询与关联
mcp	基于此库的可选只读协议适配器
facade / CLI	稳定的 Rust 导出和诊断命令入口

已签入的严格架构合同会拒绝超过 300 个物理行的文件、超过 100 个物理行的函数、运行时循环依赖、混用 foo.rs 与 foo/ 的模块所有权，以及协议无关库对可选 MCP 适配器的任何依赖。它没有基线或例外。

正确性

测试套件会创建真实的 Git 仓库并验证：

• 松散对象以及经过激进打包的 OFS/REF delta 对象；
• SHA-1 和 SHA-256 仓库；
• bare 和关联的 worktree 布局；
• 经典 MIDX 查找；
• 多层分段 commit-graph 和 changed-path Bloom 答案；
• 与 git rev-list --objects 对比的 pack 和 MIDX 位图可达性；
• 索引 v2 和 v4、reflog 顺序、revwalk 隐藏/重置以及跟踪状态；
• 确定性的并行结果和跨仓库结果；
• 不可变修订快照、合并后的时间线以及批量变更集；
• 恶意格式和超出配置限制时的失败行为。

目前核心代码行覆盖率为 85.27%。CI 会在 Linux、Windows 和 macOS 上运行 Rust 1.88，并运行 Clippy（将警告视为错误）、覆盖率检查、审计、文档构建和包验证。

性能

Windows 上的发布测量结果，日期为 2026-07-27。每一行都会实际生成结果，并在计时前验证标识符、路径、对象字节或状态完全一致：

完全一致的操作	weavatrix-git p50	git.exe p50
6,000 个对象的位图可达性	0.431 ms	72.656 ms
读取单条目索引	0.033 ms	60.758 ms
干净的已跟踪状态	0.186 ms	72.735 ms
查找缓存的提交	0.001 ms	65.267 ms
1,000 次提交历史，复用仓库	0.086 ms	66.961 ms

在同一个包含 2,000 次提交的打包测试样本上进行的进程内直接比较：

完全一致的操作	Weavatrix p50	gix 0.86 p50	git2 0.21 p50
1,000 次提交历史，热缓存	0.355 ms	0.884 ms	1.552 ms
1,000 次提交历史，重新打开	2.521 ms	3.940 ms	10.483 ms
读取 1,000 个缓存对象	0.082 ms	0.068 ms	5.640 ms
历史记录加 1,000 个原始对象	0.494 ms	0.992 ms	1.375 ms

在另一份包含 10,000 个路径的索引上，热缓存读取的测量结果分别为 1.160/1.100/1.489 ms；重新打开的测量结果为 5.225/7.745/11.251 ms。基准测试会轮换引擎顺序，并在计时前验证历史 ID、原始对象字节和规范索引路径完全一致。请参阅 BENCHMARKS.md。

在 8 个独立仓库中选取 8,000 次提交时，Weavatrix 的测量结果为：串行历史 5.667 ms、并行历史 4.080 ms、重新打开 11.810 ms、共享提交关联 4.148 ms，以及不可变清单 1.736 ms。它在全部 5 项 p50 指标上均优于 gix 和 libgit2；此前已验证各仓库的历史顺序、共享位置、路径和对象 ID 完全一致。

与其他方案的定位

功能	weavatrix-git	Git CLI	gix	libgit2
进程内运行	是	否	是	是
纯安全 Rust	是	否	是	否，采用 C 核心
Crate 依赖	零	不适用	多个模块化 crate	原生库
对象/增量缓存	是	是	是	是
MIDX 和可达性位图读取	是	是	是	是
拆分提交图和路径 Bloom 读取	是	是	是	提交图
自定义只读 ODB	是	不适用	存储抽象	是
延迟遍历修订、引用日志、索引和已跟踪状态	是	是	是	是
一流的跨仓库证据查询	是	应用程序代码	应用程序代码	应用程序代码
规范不可变提交清单	是	应用程序代码	遍历 API	树遍历 API
网络和变更操作	否	是	是	是

有意排除的功能包括 pack 索引 v1、reftable、增量 MIDX 链、拆分/稀疏索引扩展、浅克隆和替换对象语义、修订表达式语法、未跟踪/忽略/过滤器感知状态、子模块工作树状态、网络操作和变更操作。

若需要完整客户端，请使用 Git、gix 或 libgit2。如果重视范围受限的本地证据、精简的审计面、确定性读取和零依赖，请使用此 crate。

许可证

MIT