内容
# Weavatrix
**本地仓库智能，供 AI 编码代理使用 — 快速理解应用程序，然后有证据地修改它。**
Weavatrix 为任何本地仓库构建可重用的动态图谱 — 文件、符号、导入、调用、继承、健康检查结果、克隆家族和 Git 历史耦合 — 并为 Claude Code、Codex 或任何 MCP 客户端提供有界映射，以便快速理解和减少重复上下文。然后，该图谱回答变更影响、健康状况、死代码审查、重复代码、历史记录和预期架构问题。**34 个无需网络的工具。仓库数据不会离开您的机器。**
- 官方网站：[weavatrix.com](https://weavatrix.com)
- 源代码：[github.com/sergii-ziborov/weavatrix](https://github.com/sergii-ziborov/weavatrix)
- npm: [`weavatrix`](https://www.npmjs.com/package/weavatrix) — `npx -y weavatrix <repoRoot>`
此软件包是完整的离线引擎，遵循 MIT 许可协议：它读取并分析您的代码，不发起任何 outbound HTTP 请求，并且从不编辑您的源代码。它是一个只读的底层栈 — 添加 [`weavatrix-refactor`](https://github.com/sergii-ziborov/weavatrix-refactor)（Apache-2.0）以应用哈希验证、可逆编辑，或添加 [`weavatrix-online`](https://github.com/sergii-ziborov/weavatrix-online) 以进行授权的云或自托管同步。每个都是可选的超集，依赖于此核心，通过支持的扩展 API；离线/在线分离在 [docs/adr/0001-v0.3-offline-online-split.md](docs/adr/0001-v0.3-offline-online-split.md) 中有记录。
## 安装
需要 Node ≥ 18。
```sh
# Claude Code
claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot>
# Codex CLI
codex mcp add weavatrix -- npx -y weavatrix <repoRoot>
```
```toml
# 或在 ~/.codex/config.toml 中
[mcp_servers.weavatrix]
command = "npx"
args = ["-y", "weavatrix", "C:/path/to/repo"]
startup_timeout_sec = 20
tool_timeout_sec = 60
```
或从克隆仓库开始：
```sh
git clone https://github.com/sergii-ziborov/weavatrix
cd weavatrix && npm install
claude mcp add -s user weavatrix -- node <path-to>/weavatrix/bin/weavatrix-mcp.mjs <repoRoot>
```
`<repoRoot>` 是要启动的仓库。图谱是派生数据，永远不会存活在您的仓库中：它们存储在 `~/.weavatrix/graphs/<repository-storage-key>/graph.json` 的用户注册表中（旁边有一个稳定的 `.repository-id`）。如果没有图谱？请让代理调用 `rebuild_graph`，或直接使用工具 — 图谱和健康检查读取会自动协调工作图谱，然后再回答。
一个带有食谱的代理技能包含在 [skill/SKILL.md](skill/SKILL.md) 中 — 将其安装为 `~/.claude/skills/weavatrix/SKILL.md`（Claude Code）或 `~/.codex/skills/weavatrix/SKILL.md`（Codex）。
## 配置
**安全配置文件** — 将配置文件作为最终的位置参数传递（省略 = `offline`）：
| 配置文件 | 本地仓库切换 | 跨仓库图谱读取 | 网络请求 | 工具 |
|---|---:|---:|---:|---:|
| `offline`（默认） | 是，仅通过 `open_repo` | 是，仅通过 `trace_api_contract` | 无 | 34 |
| `pinned` | 否 | 否 | 无 | 31 |
```sh
# 硬编码一个仓库，不暴露跨仓库工具：
claude mcp add -s user weavatrix -- npx -y weavatrix <repoRoot> pinned
```
高级注册可能会传递确切的逗号分隔的功能集：`graph,search,source,health,build,retarget,crossrepo`。自定义列表必须包含 `crossrepo` 以公开 `trace_api_contract`。遗留的 `online`/`osv`/`hosted`/`full` 名称会大声失败并指向 `weavatrix-online`。
**语义精度** — 默认情况下，为新的图谱和升级启用有界的只读 TypeScript/JavaScript 语言服务器覆盖层，以确认对 `EXACT_LSP` 的引用。将其关闭以进行仅解析器操作，设置 `WEAVATRIX_PRECISION=off`（env），`precision:"off"` 在 `rebuild_graph`/`open_repo` 上，或使用 MCPB 安装程序的精度选择。Java 和 Rust 没有捆绑的语言服务器；它们的边缘保持解析器导出。
启动预热查询默认情况下会排名 32 个符号（不超过 64 个），对于故意的高预算传递，设置 `WEAVATRIX_PRECISION_MAX_SYMBOLS` 超过 64 或 `WEAVATRIX_PRECISION_PREWARM=full` 以覆盖每个合格目标，最高可达 10,000 个符号的天花板；`WEAVATRIX_PRECISION_MAX_REFERENCES`、`WEAVATRIX_PRECISION_MAX_LINKS` 和 `WEAVATRIX_PRECISION_TIMEOUT_MS` 调整预算。超过硬性天花板的仓库保持诚实的 `PARTIAL`。
**仓库配置文件**（所有可选，仓库根目录）：
- `.weavatrixignore` — 仅分析排除项，应在 Git 中跟踪（`*`, `**`, `?`, 根锚定 `/patterns`, 目录后缀，有序 `!` 重新包含）。
- `.weavatrix.json` — 跨仓库 HTTP 客户端/包装器合约 (`httpContracts`) 和 `classify.product` 覆盖。
- `.weavatrix-deps.json` — `entrypoints`, `nonRuntimeRoots`, 和 Python `managedDependencies` / `ignoreDependencies` 以适应无法安全推断的约定。
**测试执行** — 默认情况下，`verified_change` 是只读的。运行现有的包测试/检查/验证脚本需要同时设置 `run_tests:true` 和 `WEAVATRIX_ALLOW_TEST_RUNS=1`；任意命令始终被拒绝。
升级后，请重新连接 MCP 服务器或启动新的代理任务，然后再检查工具列表 — 许多客户端会快照 `tools/list` 以用于连接的整个生命周期。`graph_stats` 报告正在运行的版本、启用的功能和已注册的工具数量，以便缓存进程与安装的包区分开来。
## 工具
34 种方法将相同的可重用图谱投射到任务所需的最小视图中。
- **图谱** — `graph_stats`, `get_node`, `get_neighbors`, `query_graph`, `god_nodes`, `shortest_path`, `get_community`, `list_communities`, `module_map`, `get_dependents`, `change_impact`, `verified_change`, `git_history`, `graph_diff`, `get_architecture_contract`, `prepare_change`. 运行时、TypeScript 类型专用和语言编译专用边缘分别报告；每个边缘都带有版本化的出处 (`EXTRACTED` / `RESOLVED` / `INFERRED`，仅由捆绑的 TS/JS 覆盖层升级到 `EXACT_LSP`，当证据不一致时为 `CONFLICT`）。
- **搜索/源代码** — `search_code`（ripgrep 支持，具有纯 Node 备用和仓库相对路径通配符），`read_source`, `context_bundle`, `inspect_symbol`, `list_endpoints`（Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum & actix-web/Spring），`trace_endpoint`.
- **健康状况** — `find_dead_code`, `run_audit`（功能矩阵 + 未使用文件/导出/依赖项，缺失/重复依赖项，离线 OSV 漏洞，域名钓鱼，lockfile 漂移；`base_ref` + `debt: new|existing|all` 用于审查范围的结果），`find_duplicates`（MOSS 筛选，捕获重命名克隆），`coverage_map`, `hot_path_review`, `verify_architecture`, `explain_architecture_violation`, `propose_architecture_exception`.
- **构建** — `rebuild_graph`（报告结构增量，保持先前状态为 `graph.prev.json`）。
- **重定向** *(在 `offline` 中，`pinned` 中不存在)* — `open_repo`, `list_known_repos`.
- **跨仓库** *(在 `offline` 中，`pinned` 中不存在)* — `trace_api_contract`（加入路由到客户端调用站点，跨已注册的本地图谱；不读取源代码）。
每个发现都是审查证据，而不是自动删除判决：`find_dead_code` / `run_audit category=unused` 始终返回 `REVIEW_REQUIRED` 且 `autoDelete:false`。类型检查、测试和运行时检查仍然是发布权限。
## 始终保持新鲜的图谱
没有运行的守护进程，也没有手动刷新步骤：每个图谱/健康检查调用都会在回答之前协调图谱。当 Git 令牌新鲜度探测器（HEAD + 脏/未跟踪内容， debounce 2 秒）确定有变化时，有界增量刷新会重新解析仅更改的文件及其反向导入者（≤ 24 个更改 / ≤ 80 个解析的 JS/TS 文件），并将作用域结果合并到以前的图谱中，处于文件锁之下。配置/锁定文件编辑、导出表面更改、桶文件和非 JS/TS 语言会回落到完整重建 — 正确性始终胜过速度。每个刷新答案都带有结构化的 `refresh` 记录（`none` / `incremental` / `full`，更改的文件计数），因此代理可以准确地了解它正在推理哪个仓库状态。相同的保证适用于共享一个规范图谱的并发 MCP 客户端。
## 基准测试
仓库中提供了两个门控：
- `npm run benchmark` — TypeScript、JavaScript、Python、Go、Java 和 Rust 的可复制金色套件，以及跨仓库 HTTP 匹配、框架约定和 MCP 图谱生命周期。
- `npm run benchmark:real` — 将修订固定的本地快照与已检查的 0.2.1 关系基线进行比较；如果出现无法解释的信号丢失，则失败（`MISSING`/`STALE`/`UNBASELINED` 保持不完整，而不是绿色）。
代表性本地回归运行（Windows x64，Node 24.15.0）：
| 门控 | 结果 | 选择的证据 |
|---|---:|---|
| 六种语言装置 | 6/6 通过 | 确切的符号/边缘和完整的边缘出处 |
| 跨仓库装置 | 通过，大约 432 毫秒冷启动 | 端点匹配，类型化包装器，外部使用 |
| 生命周期 | 通过 | `full → incremental → none → reconnect/none` |
| 总装置冷启动 | 大约 1.31 秒 | 所有六种语言图谱 |
| 真实仓库基线 | 6/6 通过 | TS、JS、Python、Go、Java 和 Rust 快照 |
真实快照的范围从 473 个节点 / 1,165 个边缘，耗时 0.22 秒（Go）到 8,192 个节点 / 21,814 个边缘，耗时 9.44 秒（TypeScript）。这些是在一台机器上的回归测量，而不是竞争对手的基准测试。请参阅 [benchmark/cases.mjs](benchmark/cases.mjs) 和 [docs/benchmarking.md](docs/benchmarking.md)。
## 安全模型
套件功能警报描述了本地代码分析工具的预期权限；它们不是漏洞发现。根据每个功能来自哪里以及其范围界定：
| 功能警报 | 为什么存在 | 激活和边界 |
|---|---|---|
| 网络访问 | 核心中没有 MIT | `offline`/`pinned` 仅公开本地工具；在线集成是一个单独的软件包 |
| Shell 访问 | 本地 `git`（陈旧/影响），`rg`（搜索），捆绑的 tsserver 用于 JS/TS 语义，Windows 子树终止，可选的 `verified_change` 测试脚本 | 语义提供程序从不运行仓库代码；测试执行需要 `run_tests:true` + `WEAVATRIX_ALLOW_TEST_RUNS=1` 并拒绝任意命令 |
| 调试/动态加载 | 缓存破坏的 `import()` 热加载观察到的 MCP 工具模块；`createRequire` 加载包元数据和解析器依赖项 | 仅加载安装包的文件；无 `eval` |
| 环境访问 | 读取本地 `WEAVATRIX_*` 设置；子级继承一个凭证剥离的环境 | 连接器秘密被移除；tsserver 仅接收允许列出的 OS/临时/本地值 |
| 文件系统访问 | 读取活动仓库、图谱、锁定文件和覆盖率；写入派生图谱和缓存 | 实路径包含块阻止遍历和符号链接逃逸；`pinned` 删除 `open_repo` |
| URL 字符串 | 咨询发现可能包含固定的 OSV 文档链接 | 核心没有出站请求实现 |
`read_source` 仅接受仓库相对正则文件，限制读取 2 MB，并拒绝词法或实路径逃逸。如 [SECURITY.md](SECURITY.md) 中所述，请私下报告疑似漏洞。
## 语言
JavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · Solidity · HTML · CSS — 使用 [web-tree-sitter](https://github.com/tree-sitter/tree-sitter) WASM 语法分析；无需 Python 安装，也无需本机编译。
SQL 被索引而没有语法：`.sql` 文件贡献表、视图、列、函数、索引和触发器作为一流图谱符号，SQL 位于任何其他语言的字符串字面量中，将封闭函数链接到它查询的表。这使架构对象对 `change_impact`/`get_dependents`（谁触摸此表？）可见，并让死代码检查标记列，没有语句引用的列 — 保守地：判决需要存储库中的字面 SQL 证据，`SELECT *` -consumed 表永远不会因名称而被其列判断（ORM 生成的 SQL 保持不可见，因此也永远不会被判断）。
测试表面按文件分类（路径约定加上 `.weavatrix.json` 覆盖），对于 Rust，按符号：`#[cfg(test)]` 模块和 `#[test]`/`#[bench]` 项目在生产 `.rs` 文件内携带一个节点级 `test_surface` 标志，因此死代码、查询、热点和中心工具将它们视为测试而不是生产代码。
## 开发
```sh
npm install
npm test # 单元/集成测试加上快速的金色基准测试
npm run benchmark # 完整的 TS/JS/Python/Go/Java/Rust + MCP 生命周期门控
npm run benchmark:real # 当地可用的真实仓库与无源 0.2.1 基线
```
`src`、`bin`、`scripts`、`test` 下维护的 JavaScript/TypeScript 有一个严格的 300 行物理上限，由发布套件强制执行；较大的问题被分成面向所有者的模块，位于精简的立面后面。weavatrix.com 驻地生活在其自己的仓库中（`weavatrix-site`）。
## 发布历史
每个版本的补丁说明都存放在 [docs/releases/](docs/releases/) 中 — 从最新的条目开始。
## 许可证
此仓库中的 Weavatrix 源代码遵循 [MIT 许可协议](LICENSE) © 2026 Sergii Ziborov。第三方依赖项保留其自身的许可协议。请参阅公共 [许可页面](https://weavatrix.com/license) 以获取相同的通知。
