weavatrix-js

Weavatrix JS

Weavatrix 生态系统的一部分，参见 Weavatrix 生态系统。此仓库保留了独立的 JavaScript 引擎版本线。

这是 Weavatrix 的 JavaScript 引擎，现以 weavatrix-js 之名延续。 从 1.0.0 起，npm 包 weavatrix 提供 来自 weavatrix-rust 的原生 Rust 引擎； 如需继续使用 JavaScript 实现（包括 LSP 辅助的 TypeScript 路径），请固定使用 [email protected]，或安装 weavatrix-js。

为 AI 编码 Agent 提供本地代码仓库智能——快速理解应用，再基于证据进行修改。

Weavatrix 为任意本地代码仓库构建可复用、持续更新的图谱——涵盖文件、符号、导入、调用、继承、Health 发现、克隆代码族及 Git 历史关联——并为 Claude Code、Codex 或任何 MCP 客户端提供范围明确的地图，助其快速理解代码并减少重复上下文。该图谱还可回答变更影响、Health、死代码审查、重复代码、历史记录和预期架构相关问题。34 个无需联网的工具。代码仓库数据不会离开你的设备。

• 网站：weavatrix.com
• 源码：github.com/Weavatrix/weavatrix-js
• npm：weavatrix-js — npx -y weavatrix-js <repoRoot>

主要原生 Rust 引擎

weavatrix-rust 是纯 Rust 实现的只读 MCP 服务和库。其默认构建提供 39 个工具，覆盖此 JavaScript 版本线的 34 项只读功能，并通过独立的 MIT crate 增加跨代码仓库 Git、向量搜索、语义/SEO 链接以及时间记忆上下文。

cargo install weavatrix-rust
weavatrix mcp <repoRoot> --profile=code

Rust 引擎不会调用 git、rg、Node.js、Python、语言服务器或被分析代码仓库中的代码。使用 --profile=all、code 或 seo 可启用一个范围明确的视图，无需运行重复的 MCP 服务。相同修订版本的基准测试和限制已发布在其 基准测试报告中。

此软件包是在 MIT 许可下提供的完整离线引擎：它会读取并分析你的代码，不会发起任何出站 HTTP 请求，也绝不会修改源代码。它是分层技术栈中的只读基础层——添加 weavatrix-refactor（Apache-2.0）即可应用经哈希验证、可撤销的编辑；添加 weavatrix-online 即可进行经授权的 Cloud 或可自托管同步。两者都是可选的超集，通过受支持的扩展 API 依赖此核心；离线/在线拆分详见 docs/adr/0001-v0.3-offline-online-split.md。

安装

需要 Node ≥ 18。

# Claude Code
claude mcp add -s user weavatrix-js -- npx -y weavatrix-js <repoRoot>

# Codex CLI
codex mcp add weavatrix-js -- npx -y weavatrix-js <repoRoot>

# or in ~/.codex/config.toml
[mcp_servers.weavatrix-js]
command = "npx"
args = ["-y", "weavatrix-js", "C:/path/to/repo"]
startup_timeout_sec = 20
tool_timeout_sec = 60

或从克隆的仓库运行：

git clone https://github.com/Weavatrix/weavatrix-js
cd weavatrix-js && npm install
claude mcp add -s user weavatrix-js -- node <path-to>/weavatrix-js/bin/weavatrix-mcp.mjs <repoRoot>

<repoRoot> 是要开始处理的代码仓库。图谱是派生数据，绝不会存放在你的代码仓库中： 它们保存在每位用户的注册表中，路径为 ~/.weavatrix/graphs/<repository-storage-key>/graph.json （旁边还会有稳定的 .repository-id）。还没有图谱？让 Agent 调用 rebuild_graph，或者 直接使用工具——图谱和 Health 读取操作会在回答前自动协调工作图谱。

skill/SKILL.md 中附有包含操作指南的 Agent 技能——将其安装为 ~/.claude/skills/weavatrix-js/SKILL.md（Claude Code）或 ~/.codex/skills/weavatrix-js/SKILL.md（Codex）。

配置

本地能力配置 — 将配置作为最后一个位置参数传入（省略时默认为 offline）：

配置	本地仓库切换	跨仓库图谱读取	网络请求	工具
offline（默认）	是，仅通过 open_repo	是，仅通过 trace_api_contract	无	34
pinned	否	否	无	31

# hard-pin one repository and expose no cross-repo tools:
claude mcp add -s user weavatrix-js -- npx -y weavatrix-js <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（环境变量）、在 rebuild_graph/open_repo 中设置 precision:"off"，或在 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 服务或启动新的 Agent 任务，然后再检查工具列表——许多客户端会在连接期间缓存 tools/list。graph_stats 会报告正在运行的版本、启用的能力和注册工具数量，以便区分缓存进程和已安装的软件包。

工具

34 种方法将同一可复用图投射为任务所需的最精简视图。

• graph — 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 / source — search_code（由 ripgrep 支持，提供纯 Node 回退方案，并支持相对于仓库的路径 glob）、read_source、context_bundle、inspect_symbol、 list_endpoints（Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum & actix-web/Spring）、 trace_endpoint。
• health — find_dead_code、run_audit（能力矩阵 + 未使用的文件/导出/依赖、缺失/重复依赖、拼写相似的恶意包和锁文件漂移；使用 base_ref + debt: new|existing|all 获取与评审范围相关的结果）、find_duplicates（MOSS winnowing，可发现重命名克隆）、coverage_map、hot_path_review、verify_architecture、 explain_architecture_violation、propose_architecture_exception。
• build — rebuild_graph（报告结构差异，并将先前状态保留为 graph.prev.json）。
• retarget （在 offline 中提供，在 pinned 中不可用） — open_repo、list_known_repos。
• crossrepo （在 offline 中提供，在 pinned 中不可用） — trace_api_contract（将路由与已注册本地图中的客户端调用点关联；不读取源代码）。默认情况下，结果精简且分页（page_size、不透明的 cursor 和有上限的 per_item_limit 样本）；response_detail="full" 是显式选择启用的选项，且仍采用分页。

每条发现结果都是评审证据，绝不是自动删除判定：find_dead_code / run_audit category=unused 始终返回 REVIEW_REQUIRED，且 autoDelete:false。类型检查、测试和运行时检查仍是发布的最终依据。

始终保持图最新

无需运行监视器守护进程，也无需手动刷新：每次图/健康检查调用都会在作答前协调图。Git 令牌新鲜度探测（HEAD + 已修改/未跟踪内容，防抖 2 秒）会判断是否有任何更改；若有，则执行有界增量刷新，仅重新解析更改的文件及其反向导入者（≤ 24 个更改文件 / ≤ 80 个重新解析的 JS/TS 文件），并在文件锁保护下将限定范围的结果合并到先前的图中。配置/锁文件编辑、导出接口变化、barrel 文件以及非 JS/TS 语言会回退到完整重建——正确性始终优先于速度。 在 Git 工作树之外，没有可读取的探测信息，因此无法证明新鲜度；此时仅通过防抖时间窗口限制工作量：每个窗口重建一次，而非每次调用都重建。 每个刷新后的答案都会带有结构化的 refresh 记录（none / incremental / full，以及更改的文件数），因此 Agent 能准确判断其推理所依据的仓库状态。多个共享同一规范图的并发 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 PASS	符号/边完全匹配，边的溯源信息完整
跨仓库测试夹具	PASS，冷启动约 432 ms	端点匹配、类型化封装器、外部使用
生命周期	PASS	full → incremental → none → reconnect/none
测试夹具冷构建总耗时	约 1.31 s	全部六种语言的图
真实仓库基线	6/6 PASS	TS、JS、Python、Go、Java 和 Rust 快照

真实快照的规模和耗时从 Go 的 473 个节点 / 1,165 条边（0.22 s），到 TypeScript 的 8,192 个节点 / 21,814 条边（9.44 s）不等。这些是单台机器上的回归测量，不是竞品基准测试。请参阅 benchmark/cases.mjs 和 docs/benchmarking.md。

安全模型

套接字能力警报描述的是本地代码分析工具预期具备的权限；它们并非漏洞发现。以下说明各项权限的来源及其限制：

能力警报	存在原因	激活条件与边界
网络访问	MIT 核心不涉及网络访问	offline/pinned 仅提供本地工具；在线集成属于单独的软件包
Shell 访问	本地 git（用于过时状态/影响分析）、rg（用于搜索）、捆绑的 JS/TS 语义分析用 tsserver、Windows 子进程树终止、可选的 verified_change 测试脚本	语义提供程序不会运行仓库代码；运行测试需要设置 run_tests:true + WEAVATRIX_ALLOW_TEST_RUNS=1，且不接受任意命令
调试/动态加载	对监视中的 MCP 工具模块使用缓存失效的 import() 进行热重载；使用 createRequire 加载软件包元数据和解析器依赖	仅加载已安装软件包中的文件；不使用 eval
环境访问	读取本地 WEAVATRIX_* 设置；子进程继承剔除了凭据的环境	会移除连接器密钥；tsserver 仅接收允许列表中的 OS/临时目录/区域设置值
文件系统访问	读取当前仓库、图、锁文件和覆盖率数据；写入派生图和缓存	通过真实路径限制阻止路径遍历和符号链接逃逸；pinned 会移除 open_repo
read_source 仅接受相对于仓库目录的常规文件，单次读取上限为 2 MB，并拒绝词法路径或真实路径逃逸。请按照 SECURITY.md 中的说明，私下报告疑似漏洞。

依赖项漏洞匹配、公告更新和已安装软件包的恶意软件审查不属于本软件包的功能。这些需要联网的安全审查工作流位于 weavatrix-online，因此本地 JS 引擎不会声称给出无法核实的安全结论。

语言

JavaScript · TypeScript · TSX · Python · Go · Java · C# · Rust · Solidity · HTML · CSS — 使用 web-tree-sitter WASM 语法进行解析；无需安装 Python，也无需本机编译。

SQL 不使用语法进行索引：.sql 文件会将表、视图、列、函数、索引和触发器作为一等图符号；其他任意语言的字符串字面量中发现的 SQL，则会将所属函数关联到其查询的表。这样一来，change_impact/get_dependents 可以显示架构对象（哪些代码会访问此表？），死代码检查也能标记没有语句引用的列——判定会采取保守策略：只有仓库中的字面 SQL 证据才会触发判定；被 SELECT * 使用的表，其列永远不会按名称进行判定（ORM 生成的 SQL 不可见，因此也永远不会被判定）。

测试范围按文件分类（依据路径约定和 .weavatrix.json 覆盖设置）；Rust 还会按符号分类：生产 .rs 文件中的 #[cfg(test)] 模块和 #[test]/#[bench] 项带有节点级 test_surface 标记，因此死代码、查询、热点路径和枢纽工具会将其视为测试代码，而非生产代码。

开发

npm install
npm test                 # unit/integration tests plus the quick golden benchmark
npm run benchmark        # full TS/JS/Python/Go/Java/Rust + MCP lifecycle gate
npm run benchmark:real   # locally available real repos vs source-free 0.2.1 baselines

在 src、bin、scripts、test 下维护的 JavaScript/TypeScript 代码，必须遵守物理行数不超过 300 行的硬性上限，并由发布测试套件强制执行；更大的功能会拆分为职责明确的模块，并通过精简的门面提供接口。weavatrix.com 的落地页位于其独立仓库（weavatrix-site）中。

发布历史

各版本的补丁说明位于 docs/releases/ 中——请从最新条目开始阅读。发布流程和检查关卡见 scripts/verify-release.mjs。

许可证

此仓库中的 Weavatrix 源代码采用 MIT 许可证 © 2026 Sergii Ziborov。 第三方依赖保留各自的许可证。相同声明也见公开的 许可证页面。