GitNexus 重构技能（gitnexus-refactoring）用于在 GitNexus 索引的代码库中安全地执行代码重构，包括重命名、提取、拆分、移动与结构调整。
适用场景
当你需要“安全重命名这个函数”“把它提取成一个模块”“拆分这个服务”“把它移到一个新文件”，或任何涉及重命名、提取、拆分与结构调整的任务时使用。
先绑定仓库
重命名会写入磁盘，dry_run: false 会在解析出的仓库中编辑文件，因此绑定身份是安全关卡。首次调用工具前先调用 list_repos {}。只有一个已索引仓库时按示例直接使用；多于一个时，每次调用都传 repo。不确定目标仓库时应停下并询问。在审阅同一绑定仓库中的预览前，绝不要以 dry_run: false 运行 rename——预览返回的 file_path 值可表明即将写入哪个检出目录。list_repos 分页，需用 offset: pagination.nextOffset 翻页直到 hasMore 为 false 再判断仓库不存在。detect_changes 在编辑 MCP 服务器未从其启动的关联 worktree 时需传 worktree。
工作流
- list_repos {} → 绑定仓库（与 worktree）
- impact({target: "X", direction: "upstream"}) → 映射所有依赖方
- query({search_query: "X"}) → 查找涉及 X 的执行流程
- context({name: "X"}) → 查看所有传入/传出引用
- 规划更新顺序：接口 → 实现 → 调用方 → 测试
若提示“Index is stale”，在终端运行 node .gitnexus/run.cjs analyze。仅对 behind 或 diverged 重新分析。
检查清单
重命名符号
- list_repos {} 绑定仓库；多个已索引仓库时显式指定 repo，含糊时询问
- rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) 预览语义编辑（省略 dry_run 也是预览）
- 确认预览文件路径在绑定仓库/worktree 内
- 审阅基于图谱的语义跨度、覆盖范围与限制
- 满意后：rename({..., dry_run: false}) 应用编辑
- detect_changes() 验证仅预期文件变更
- 对受影响流程运行测试
提取模块
- list_repos {} 绑定仓库
- context({name: target}) 查看所有传入/传出引用
- impact({target, direction: "upstream"}) 查找所有外部调用方
- 定义新模块接口
- 提取代码、更新导入
- detect_changes() 验证受影响范围
- 对受影响流程运行测试
拆分函数/服务
- list_repos {} 绑定仓库
- context({name: target}) 了解所有被调用方
- 按职责对被调用方分组
- impact({target, direction: "upstream"}) 映射待更新调用方
- 创建新函数/服务
- 更新调用方
- detect_changes() 验证受影响范围
- 对受影响流程运行测试
工具
rename 为语义重命名，先预览再应用。省略 dry_run 或为 true 时预览且不写盘；dry_run: false 才应用。以 GITNEXUS_MCP_READ_ONLY=1 启动的 MCP 服务器仍会列出 rename，但仅为预览模式，会拒绝除省略或 true 之外的 dry_run，因此应用需从非只读客户端执行。
rename 使用已索引图谱与 GitNexus 自有语义层。语言提供方通过作用域与绑定解析当前源码，不加载编译器或语言服务。不支持的语法、含糊绑定、过时声明与不完整出现覆盖会失败关闭。覆盖范围描述被所选提供方接受的已索引文件，不包括未索引文件与外部消费者。所有已注册源码语言提供方均提供重命名规则。声明与覆盖家族需要完整语义证据。动态或计算引用在提供方无法解析时会阻止重命名。不存在正则回退：legacy graph_edits 与 text_search_edits 为零。注释、字符串与无关同名字符不会替换。
预览与应用使用同一规划器。结果使用 result_version: 2；total_edits 统计出现次数而非匹配行数。需检查 planning_status、application_status 与 applied。成功的预览尚未写入文件。rename 不接受 branch，它检查当前检出。
错误与恢复
- stale_graph：重新分析绑定仓库，再预览。
- source_changed：针对当前源码重新预览并审阅；若在应用中出现，见 partial 行。
- unsupported_*：停止自动重命名，检查限制，必要时手工重构。
- 含糊目标（ambiguous 带候选）：查看候选或 context，用所选 symbol_uid 预览。
- ambiguous_reference、incomplete_semantics：规划器无法证明引用被覆盖，停止自动重命名。
- name_collision：新名称会冲突，换名再预览。
- invalid_name：新名称无效或与当前相同。
- invalid_argument：dry_run 非布尔。
- no_locations：规划器未产出编辑，不要应用。
- overlapping_edits、invalid_edit：跨度冲突，计划在写入前被拒绝。
- duplicate_file、missing_snapshot、outside_repository：规划器安全检查失败，重新分析并预览。
- source-unavailable（content-retention 或 checkout-missing）：重新以完整保留分析，或对检出运行。
- rename_failed：写入前的意外错误（application_status: not_started）。
- application_status 为 partial 或 failed：写入非事务性，检查 landed changes、failed_files、unattempted_files，重新协调、重建索引并审阅新预览，切勿盲目重试。应用后运行项目验证套件。
impact 先映射所有依赖方；detect_changes 用于重构后校验变更，partial: true 或 truncated: true 表示结果不完整，需重跑。cypher 用于自定义引用查询。
风险规则
- 调用方多（>5）：用 rename 自动更新。
- 跨区域引用：用 detect_changes 验证范围。
- 字符串/动态引用：用 query 查找。
- 外部/公开 API：妥善版本化与弃用。
- 另一已索引仓库有同名符号：绑定仓库，应用前验证预览路径。
示例：将 validateUser 重命名为 authenticateUser
- list_repos {} → total: 2，两者都定义了 validateUser，需显式绑定
- rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true}) → 12 处语义出现
- 审阅语义跨度与提供方覆盖，单独检查动态引用
- rename({..., dry_run: false}) → 应用 12 处编辑，涉及 8 个文件
- detect_changes({scope: "all", repo: "my-app"}) → 受影响流程 LoginFlow、TokenRefresh，风险 MEDIUM，对这些流程运行测试。
只有一个已索引仓库时，步骤 0 返回 total: 1，后续调用可省略 repo 参数。