Weavatrix Refactor

Weavatrix 生态系统 的显式源码写入层；Core 保持只读。

跨文件重构，无需让代理猜测。

Weavatrix Refactor 是一个面向编码代理的原生 MCP 服务器。它通过仓库图谱查找符号，预览字节级精确的编辑，报告所有无法证明的同名出现位置，并且仅在显式、基于哈希的确认之后才执行写入。

关键区别不在于“AI 能重命名一个词”，而在于代理在写入之前获得证据，在写入之后获得可恢复的事务。

安装

通过 npm 运行原生二进制：

npx -y weavatrix-refactor mcp /absolute/path/to/repository

或者通过 Cargo 安装：

cargo install weavatrix-refactor --locked
weavatrix-refactor mcp /absolute/path/to/repository

MCP 客户端可以直接启动它：

{
  "mcpServers": {
    "weavatrix-refactor": {
      "command": "weavatrix-refactor",
      "args": ["mcp", "/absolute/path/to/repository"],
      "env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"}
    }
  }
}

保持 WEAVATRIX_ALLOW_SOURCE_EDITS 未设置以进行仅预览会话。预览是读取操作；只有确认的 apply 或 rollback 才需要该门控。

作为插件安装

该仓库还附带一个适用于 Cursor、Codex、Claude Code 和 Grok Build 的插件包。该插件启动仅扩展配置文件，因此它贡献 11 个 Refactor 方法，而无需重复 Weavatrix Core 的 43 个只读方法定义。当两个表面都需要时，请安装单独的 Weavatrix 插件。

捆绑的技能是可选的，仅在明确请求重构工作时激活。其入口点保持简短；每个方法都有一个单独的参考卡片，仅在需要时加载。

• Cursor：市场批准后搜索 Weavatrix Refactor。

• Codex：从 .agents/plugins 添加 Weavatrix/weavatrix-refactor 市场，然后添加 weavatrix-refactor@weavatrix-refactor。

• Claude Code：从 .claude-plugin 添加相同的仓库市场，然后安装 weavatrix-refactor@weavatrix-refactor。

• Grok Build：运行 grok plugin marketplace add Weavatrix/weavatrix-refactor，打开 /marketplace 并安装它。

插件会打开 WEAVATRIX_ALLOW_SOURCE_EDITS=1，但每次写入仍然需要精确预览的短期、绑定计划的一次性令牌。

对于重命名任务，只暴露代理需要的两个工具：

weavatrix-refactor mcp /absolute/path/to/repository --profile=rename

rename 配置文件保留 rename_symbol 和 rollback_last_apply；所有无关的图谱和重构工具都不存在且无法调用。省略该选项（或使用 --profile=refactor）以获取全部 11 个 Refactor 方法。更窄的目录减少了重复的代理上下文；它不会削弱预览哈希、写入门控、确认令牌或回滚检查。

当 Weavatrix Core 已作为单独的 MCP 安装时，只暴露 Refactor 新增的 11 个方法：

weavatrix-refactor mcp /absolute/path/to/repository --profile=refactor

refactor 配置文件是 MCP 和 list-tools 的默认配置，包括市场插件。以前的 full 兼容配置文件已被移除，并被这两个命令拒绝：Refactor 不再重新发布 Core 方法。当还需要只读的仓库智能时，请将 Weavatrix Core 安装为独立的 MCP。

Related MCP server: repository-analyzer-mcp

三次调用完成安全跨文件重命名

假设两个文件声明了 resolveTarget。裸名称是有歧义的，因此服务器拒绝选择一个并返回精确的 id：

// rename_symbol
{"symbol":"resolveTarget","new_name":"locateTarget","output_format":"json"}

{
  "status": "NOT_FOUND",
  "reason": "the name matches more than one symbol; pass one of the candidate ids",
  "candidates": [
    "symbol:src/core.ts#function:resolveTarget@2:1",
    "symbol:src/shadow.ts#function:resolveTarget@3:1"
  ]
}

使用预期的 id 重试。结果仍然是只读的：它包含编辑计划、内容哈希、已证明的编辑数量，以及后端拒绝猜测的引用。

// rename_symbol
{
  "symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
  "new_name": "locateTarget",
  "output_format": "json"
}

{
  "status": "PLANNED",
  "completeness": "PARTIAL",
  "renamedEdits": 7,
  "uncertainReferences": ["... three named locations ..."],
  "confirmToken": "single-use-token",
  "plan": {"schemaVersion":"weavatrix.edit-plan.v1","files":["..."]}
}

审查计划后，使用相同的输入及其令牌重复相同的操作：

// rename_symbol
{
  "symbol": "symbol:src/core.ts#function:resolveTarget@2:1",
  "new_name": "locateTarget",
  "mode": "apply",
  "confirm_token": "single-use-token",
  "output_format": "json"
}

{"status":"APPLIED"}

此精确流程已针对真实的 stdio MCP 服务器进行测试。仓库夹具需要跨三个文件进行七次编辑，保留四个陷阱（更长的标识符、字符串、注释和无关的遮蔽），并且必须仍然可以编译；它得分 12/12。

当前自动化的内容

这十一个工具并非都声称具有相同的自动化级别：

Refactor 在内部使用 Rust Weavatrix 图谱作为证据，但从不导出 Core 方法。请安装单独的 Weavatrix 插件以获取只读的仓库智能。Refactor MCP 恰好拥有其 11 个扩展方法；--profile=rename 是一个可选的更窄的双方法工作流。

安全模型和精确限制

• 有歧义的名称会以候选 id 失败，而不是选择第一个匹配项。

• PARTIAL 表示图谱证明了计划中的编辑，但未证明不存在其他语义引用。uncertainReferences 列出了需要审查的位置。

• 计划中的每个文件都带有内容哈希。工作树发生变化会使预览过期，而不是应用旧的坐标。

• Apply 需要 WEAVATRIX_ALLOW_SOURCE_EDITS=1 以及绑定到该仓库和精确重新计算计划的短期、一次性令牌。

• rollback_last_apply 拒绝覆盖事务后发生漂移的文件。

• 多文件写入是日志记录且可崩溃恢复的。它们对无关进程不是观察上的原子操作：另一个进程可能短暂观察到中间文件系统状态。

只有具有已证明来源的编辑才会被应用。词法或图谱后端故意比语言服务器更保守，不应被解读为完整编译器语义的声明。

实测基准，不同层保持分离

已检入的 2026 年 8 月基准使用等效的对抗性 TypeScript、Rust 和 Python 夹具。每个都有七次必需编辑、四个陷阱和构建/测试门控。协议运行计算精确的 o200k_base 初始化、目录、请求和响应令牌。代理运行使用 Codex CLI 报告的实际累计使用量，并固定 gpt-5.6-sol / 中等推理。不使用字节代理或估计的每秒令牌转换。

新的仅重命名配置文件将所有九次协议运行保持在 12/12，同时将固定的 MCP 上下文从 9,331 个令牌减少到 485 个令牌。其引导的 TypeScript 代理 A/B 是：

完整的代理矩阵在所有 27 次 TypeScript/Rust/Python 运行中均为 12/12；每次运行也在操作上完成并通过了清理后的编辑通道审计。确定性协议矩阵还暴露了一个特定于语言的 Serena 缺陷：其建议的 find_symbol → rename_symbol 流程在 TypeScript 上的三次运行中均得分 7/12，而 Rust 和 Python 通过。它还发现并推动了 Rust 宏调用和 Python f-string/模块级调用证据的修复。

在这个玩具 TypeScript 仓库上，裸 Codex 仍然比窄配置文件更快、更便宜。Weavatrix 的展示价值是写入前预览、命名不确定性、过期计划拒绝、显式授权和回滚——而不是普遍的小仓库令牌优势。

请参阅完整方法论、所有语言中位数、原始结果链接和限制。

契约

11 个 Refactor 工具名称、模式和结果状态在 contract/refactor-tools.v1.json 中冻结。所有重构操作都是原生 Rust；主机在内部使用只读的 weavatrix-rust 引擎获取图谱证据，而不会在默认表面上导出其方法。

0.1.x 版本使用 JavaScript 引擎。该系列继续作为 weavatrix-refactor-js，并保持单独的状态目录、令牌存储和回滚日志。

许可证

MIT。