weavatrix-refactor

Weavatrix Refactor

Weavatrix 生态系统中明确的源码写入层；Core 仍保持只读。

跨文件重构，不让 Agent 猜测。

Weavatrix Refactor 是面向编码 Agent 的原生 MCP 服务。它通过仓库图谱查找符号，预览字节级精确的编辑，报告所有无法确认的同名匹配项，并且仅在收到明确的、绑定哈希的确认后写入。

它的真正优势不是“AI 可以重命名一个词”，而是 Agent 在写入前能获得证据，并且写入后有可恢复的事务。

安装

通过 npm 运行原生二进制文件：

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

或使用 Cargo 安装：

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

MCP 客户端可以直接启动它。请优先使用绝对路径，或使用 Cursor 的 ${workspaceFolder}，这样写入服务就不会跟随宿主进程的当前工作目录：

{
  "mcpServers": {
    "weavatrix-refactor": {
      "command": "npx",
      "args": ["-y", "[email protected]", "mcp", "${workspaceFolder}", "--profile=refactor"],
      "env": {"WEAVATRIX_ALLOW_SOURCE_EDITS": "1"}
    }
  }
}

预览专用会话中请不要设置 WEAVATRIX_ALLOW_SOURCE_EDITS。预览属于读取操作；只有确认应用或回滚时才需要通过门控。Refactor 不提供 Core 的 open_repo，因此无法在会话中静默切换目标；启动时指定的根目录是它唯一会编辑的仓库。

作为插件安装

仓库还附带一个插件包，适用于 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，但每次写入仍需要对应精确预览的、短时有效且绑定计划的单次使用令牌。

执行重命名任务时，只向 Agent 暴露所需的两个工具：

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

rename 配置仅保留 rename_symbol 和 rollback_last_apply；其他所有图谱和重构工具都会被排除，无法调用。省略此选项（或使用 --profile=refactor）即可启用全部 11 个 Refactor 方法。较精简的目录可减少重复的 Agent 上下文；它不会削弱预览哈希、写入门控、确认令牌或回滚检查。

如果已将 Weavatrix Core 作为单独的 MCP 安装，只需暴露 Refactor 新增的 11 个方法：

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

refactor 配置是 MCP 和 list-tools 的默认配置，包括市场插件。之前的 full 兼容配置已移除，两个命令都会拒绝该配置：Refactor 不再重新发布 Core 方法。如果还需要只读仓库智能功能，请将 Weavatrix Core 作为单独的 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。

目前可自动完成的操作

这 11 个工具的自动化程度各不相同：

级别	工具	Agent 收到的内容
完整的预览/应用工作流	rename_symbol、rename_related_symbols	生成的计划和令牌；重复执行同一操作即可确认写入
生成计划	change_signature、edit_symbol、bulk_replace、organize_imports、move_file	精确到字节的编辑或审阅计划；返回编辑计划封装时，使用 apply_edit_plan
提供建议	move_symbol、delete_readiness	影响范围、循环/架构风险或删除评估；不会自动写入源代码
安全基础设施	apply_edit_plan、rollback_last_apply	验证/应用编辑计划封装，以及在无漂移的情况下恢复

Refactor 在内部使用 Rust Weavatrix 图提供证据，但不会导出 Core 方法。如需只读的仓库智能功能，请安装单独的 Weavatrix 插件。Refactor MCP 仅提供其 11 个扩展方法；--profile=rename 是一个可选的精简工作流，仅包含两个方法。

安全模型与确切限制

• 名称存在歧义时，会返回候选 ID，而不会选择第一个匹配项。
• PARTIAL 表示图已证明计划中的编辑，但未能证明不存在其他语义引用。uncertainReferences 会列出需要审阅的位置。
• 计划中的每个文件都带有内容哈希。工作树发生变化后，预览会失效，而不会应用旧坐标。
• 应用更改需要设置 WEAVATRIX_ALLOW_SOURCE_EDITS=1，并提供一个短时有效、单次使用且绑定到该仓库及精确重算计划的令牌。
• rollback_last_apply 会拒绝覆盖事务后发生漂移的文件。
• 多文件写入会记录日志，并可在崩溃后恢复。但对于无关进程，这些操作并非观察上的原子操作：其他进程可能会短暂看到文件系统的中间状态。

只会应用来源已得到证明的编辑。词法或图后端有意比语言服务器更保守；不得将其理解为声称具备完整的编译器语义。

实测基准，保持不同层级分开

已检入的 2026 年 8 月基准使用等效的 TypeScript、Rust 和 Python 对抗性夹具。每个夹具都包含 7 项必需编辑、4 个陷阱，以及构建／测试门禁。协议运行统计精确的 o200k_base 初始化、目录、请求和响应令牌。Agent 运行使用 Codex CLI 报告的实际累计用量，并固定使用 gpt-5.6-sol 和 medium 推理。未使用字节代理，也未进行令牌／秒估算转换。

新的仅重命名配置文件在将固定 MCP 上下文从 9,331 个令牌降至 485 个的同时，使全部 9 次协议运行均保持 12/12。其 TypeScript 引导式 Agent A/B 测试如下：

组别	正确性	端到端中位数	输入令牌中位数
裸用 Codex	12/12 x3	42,602 ms	72,169
Weavatrix 1.0.6 --profile=rename	12/12 x3	48,389 ms	108,155
Weavatrix 1.0.5 全部功能	12/12 x3	58,719 ms	275,784
Serena	12/12 x3	68,728 ms	388,271

完整 Agent 测试矩阵中的 27 次 TypeScript／Rust／Python 运行全部达到 12/12；每次运行也都在操作层面成功完成，并通过了净化后的编辑通道审计。确定性协议测试矩阵还发现了 Serena 的语言特定缺陷：其建议的 find_symbol → rename_symbol 流程在 3 次 TypeScript 运行中均得分 7/12，而 Rust 和 Python 测试通过。矩阵还发现并推动修复了 Rust 宏调用以及 Python f-string／模块级调用证据方面的问题。

在这个玩具 TypeScript 仓库中，裸用 Codex 仍比精简配置更快、成本更低。Weavatrix 展示出的价值在于写入前预览、明确说明不确定性、拒绝过期计划、显式授权和回滚，而不是让小型仓库普遍节省令牌。

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

契约

11 个重构工具的名称、架构和结果状态已冻结在 contract/refactor-tools.v1.json 中。所有重构操作均由原生 Rust 实现；宿主在内部使用只读的 weavatrix-rust 引擎提供图证据，但默认接口不导出其方法。

0.1.x 版本使用 JavaScript 引擎。该版本线将继续作为 weavatrix-refactor-js 发展，并使用独立的状态目录、令牌存储和回滚日志。

许可证

MIT。