企业官网建设流程全解析

GitNexus 安全重构指南：用知识图谱驱动的 rename / extract / split 工作流

【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus

GitNexus 是一个零服务器、运行在浏览器/本地的代码智能引擎（client-side knowledge graph），会为放入的 Git 仓库（GitHub、GitLab、Azure、本地）或 ZIP 建立交互式知识图谱并内置 Graph RAG Agent。当开发者需要安全地重命名、提取、拆分、移动或重构代码时，gitnexus-refactoringskill 定义了完整、可复现的操作协议：先绑定仓库、再遍历影响面、预览全部编辑、最后用detect_changes验证改动范围。读完本文，你将掌握list_repos / impact / query / context / rename / detect_changes / cypher这一组 MCP 工具的配合方式、跨多仓库与 linked worktree 的边界处理，以及一套"只改预期文件、不漏动态引用"的可验证重构流程。

本文以 gitnexus-claude-plugin/skills/gitnexus-refactoring/SKILL.md 为主体（其在 gitnexus/skills/gitnexus-refactoring.md 存在同内容副本），并结合 MCP 工具的真实 schema 定义进行源码级验证。

适用场景：什么时候调用本技能

任何涉及重命名、提取、拆分、移动或重构代码的任务，都属于该技能的适用范围，典型触发语句包括：

• "Rename this function safely"（安全地重命名函数）
• "Extract this into a module"（提取成模块）
• "Split this service"（拆分服务）
• "Move this to a new file"（移动到新文件）
• 任何"重命名 / 提取 / 拆分 / 重构"类需求

之所以强调 safe / safely，是因为重构会写盘。rename工具在dry_run: false时会直接编辑被解析到的仓库文件，因此整个协议的第一步不是调用改名工具，而是先建立确定的仓库身份。

第一步：绑定仓库（Bind the repository first）

SKILL.md 将"绑定仓库"定义为安全闸门而非记账动作：rename会在当前解析到的仓库上落盘编辑，所以必须让"你要改的仓库"与"工具将要写的仓库"成为同一对象。

具体规则：

• 在首次工具调用前先执行list_repos {}；
• 若只有一个已索引仓库，可直接按本文示例调用（省略repo参数）；
• 若有多个已索引仓库，每次调用都要显式传repo。省略repo通常直接报错，但在配置了默认仓库的 MCP 策略下，会静默解析到该默认仓库——这正是需要警惕的隐含绑定；
• 若无法判断用户指的是哪个仓库，停下来询问，不要猜；
• 在dry_run: true的预览（返回的file_path值会标明即将写入的 checkout）通过复核之前，绝不执行dry_run: false——预览里的文件路径就是仓库身份的确认凭证。

关于list_repos的两个底层细节（与 gitnexus/src/mcp/tools.ts 第 87 行起的 schema 描述一致）：

• 分页遍历：list_repos是分页的，返回结构带pagination。当pagination.hasMore为true时，必须以pagination.nextOffset作为下一次调用的offset继续翻页，直到hasMore为false，才能断言某个仓库"不存在"。不能只翻一页就下结论。原因是该结果集是分页限长的，避免超过 MCP/LLM 的 token 上限。
• 稳定顺序：仓库按稳定顺序返回，在注册表未变化的前提下翻页不会跳过或重复条目。

linked worktree 的坑：detect_changes需要显式worktree

当你编辑的是 MCP server并非从其启动目录发起的 linked worktree 时，必须在detect_changes里传worktree参数；否则git diff会在错误的 checkout 上执行、报告"没有任何变更"——这会被误读为"重构已验证、零副作用"。实际上这是错误的 diff 目标造成的空结果。

这一行为在工具定义中有对应说明（gitnexus/src/mcp/tools.ts 第 354-377 行）：GitNexus 会自动检测 MCP server 是否从 linked worktree 内部启动并自动在该 worktree 上运行git diff，常规场景无需额外参数；只有 server 启动目录与你正在编辑的 worktree 路径不一致时才需显式传入worktree（该路径下.git是文件而非目录，是判断 worktree 的标志）。

标准重构工作流

SKILL.md 给出 5 步主流程，核心是"先摸清影响面，再动手，最后验证"：

0. list_repos {} → 绑定仓库（以及 worktree） 1. impact({target: "X", direction: "upstream"}) → 找出全部依赖者（上游影响面） 2. query({search_query: "X"}) → 找到涉及 X 的执行流程 3. context({name: "X"}) → 查看 X 的全部入/出引用 4. 规划更新顺序: interfaces → implementations → callers → tests

若出现 "Index is stale"（索引过期）提示：在终端执行node .gitnexus/run.cjs analyze重新分析后再继续。

第 4 步的更新顺序很有讲究：先接口、后实现、再调用方、最后测试，每一步的修改都可以用detect_changes交叉验证，把"重构出问题"的定位成本降到最低。

工具速查：rename / impact / context / query / cypher / detect_changes

GitNexus MCP server 对重构开放的工具体系在 gitnexus/src/mcp/server.ts 顶部有总览注释（"Tools: list_repos, query, cypher, context, impact, detect_changes, rename"），并会在每次工具返回后给出"下一步"提示，形成引导链。

rename：基于知识图谱的多文件协同改名

rename是重构的"执行器"，它的安全优势来自双通道检索（gitnexus/src/mcp/tools.ts 第 426-461 行的 schema 定义）：

• graph edits（高置信度）：通过知识图谱的关系边（CALLS / IMPORTS / EXTENDS / IMPLEMENTS 等）找到的引用，属于结构化解析结果，可以放心接受；
• text_search edits（低置信度）：通过正则文本搜索命中的引用（例如配置文件、字符串、JSON 键里的动态引用），需要人工逐一复核。

每个编辑都带有confidence标注，返回结构形如Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]：

rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true}) → 12 edits across 8 files → 10 graph edits (high confidence), 2 text_search edits (review) → Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]

关键参数与默认值（来源为工具 schema）：

两点重要的源码级细节：

• 默认就是dry_run: true。也就是说不带dry_run参数调用只做预览，真正的写盘必须显式传dry_run: false——这也是 SKILL.md 把"先预览、确认路径、再应用"定为铁律的原因。
• 歧义处理：当symbol_name对应多个符号时，rename不会默默挑一个，而是返回status: "ambiguous"、带排名的候选列表与totalCandidates（真实匹配数）。此时应改为携带symbol_uid重调，或用file_path缩小范围，实现零歧义定位。

另外，rename在 MCP 注解中被标记为DESTRUCTIVE_TOOL（破坏性工具），这与 read-only 策略直接相关（见下文"只读模式的边界"）。

impact：先画爆炸半径

重构前必做的第一件事是impact，它分析"改动某个符号会炸到谁"（blast radius）。SKILL.md 用它做上游遍历以覆盖全部依赖者：

impact({target: "validateUser", repo: "my-app", direction: "upstream"}) → d=1: loginHandler, apiMiddleware, testUtils → Affected Processes: LoginFlow, TokenRefresh

direction的语义（gitnexus/src/mcp/tools.ts 第 529-532 行）：upstream是"谁依赖它"（dependents），downstream是"它依赖谁"（dependencies）。

结果的深度分级是判断优先级的核心：

• d=1：WILL BREAK——直接调用方/导入方，一改就崩；
• d=2：LIKELY AFFECTED——间接影响；
• d=3：MAY NEED TESTING——传递性波及。

返回还包含risk（LOW / MEDIUM / HIGH / CRITICAL / UNKNOWN）、affected_processes（哪些执行流程在哪一步断裂）、affected_modules（波及的功能区域）以及byDepth分组符号。一个值得注意的语义：上游遍历如果解析到零调用方，风险报告的是UNKNOWN而不是LOW——因为"没有调用者"既可能是真无人使用，也可能是索引覆盖不到的引用类别（普通对象属性访问、裸标识符读取模块级 const 等），需要用文本搜索进一步确认后再行动。

若索引较旧，部分影响面元数据可能缺失而无法被识别为"解析缺口"，此时应重新执行gitnexus analyze再信任零结果。impact同样支持gitnexus impactCLI（见 gitnexus/src/cli/index.ts 第 380 行起的命令定义，可用--direction upstream|downstream、--depth等参数，详见 gitnexus/src/cli/i18n/en.ts）。

query / context：找执行流、看引用全景

• query({search_query: "X"})用于定位"哪些执行流程与 X 相关"，是捕获动态/字符串引用类问题的关键手段；
• context({name: "X"})返回符号的入向/出向引用全貌（incoming / outgoing），并附带与impact相同的认识论包络（epistemic envelope），是理解单个符号依赖关系最直接的入口。rename的歧义消解正是复用context()的 payload：符号名歧义时返回候选排序。

这两步在重构里承担不同职责：context看"这个符号跟谁连着"，query找"哪些流程会执行到它"，impact算"改它会碎哪些下游"。三者组合即可在动手前建立完整的心理模型。

detect_changes：验证"只改了预期文件"

重构完成后用detect_changes收尾验证，它会分析未提交的 git 变更并把 diff hunk 映射回索引符号、追溯受影响执行流程（工具定义见 gitnexus/src/mcp/tools.ts 第 347-385 行）：

detect_changes({scope: "all"}) → Changed: 8 files, 12 symbols → Affected processes: LoginFlow, TokenRefresh → Risk: MEDIUM

scope支持四档：unstaged（默认，未暂存）、staged（已暂存）、all（全部）、compare（与base_ref指定分支/提交对比，如main）。

两个必须读懂的完整性标记：

• partial: true：某一步图查询失败被吞掉，结果不是全量真相。短结果或空列表不能证明"只有预期文件被改动"——务必重跑，而不是把重构当作已验证；
• truncated: true：changed_symbols 列表被截断，summary.changed_count才是真实观测总数（通常准确、在partial时是下界），要拿它与数组长度对比而不是轻信数组。

而"错误 worktree 导致的零变更"不带任何标记，与"干净的验证结果"无法区分——所以确认 diff 的 checkout 正是你编辑的那个（即前文worktree参数的意义所在）。

cypher：自定义引用查询

当内置工具表达不了你的查询意图时，可以写 Cypher 直接查知识图谱。SKILL.md 示例为查找validateUser的所有调用者：

MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"}) RETURN caller.name, caller.filePath ORDER BY caller.filePath

cypher是低层逃生舱：例如在rename的 text_search 命中过多时，用它按CALLS、IMPORTS、EXTENDS、IMPLEMENTS、HAS_METHOD、ACCESSES等边类型做定向核查（完整 EdgeType 枚举见impact工具 schema，gitnexus/src/mcp/tools.ts 第 505 行）。

三个可复制的操作清单

重命名符号（Rename Symbol）

- [ ] list_repos {} — 绑定仓库；多索引仓库显式传 repo，有歧义先询问 - [ ] rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — 预览全部编辑 - [ ] 确认预览的 file_path 都在绑定的仓库/worktree 内 - [ ] 复核 graph edits（高置信）与 text_search edits（需仔细人工审查） - [ ] 确认无误: rename({..., dry_run: false}) — 应用编辑 - [ ] detect_changes() — 验证只有预期文件被改动 - [ ] 运行受影响流程的测试

提取模块（Extract Module）

- [ ] list_repos {} — 绑定仓库；多索引仓库显式传 repo，有歧义先询问 - [ ] context({name: target}) — 查看 target 的全部入/出引用 - [ ] impact({target, direction: "upstream"}) — 找出全部外部调用方 - [ ] 定义新模块接口 - [ ] 提取代码、更新 import - [ ] detect_changes() — 验证受影响范围 - [ ] 运行受影响流程的测试

拆分函数/服务（Split Function/Service）

- [ ] list_repos {} — 绑定仓库；多索引仓库显式传 repo，有歧义先询问 - [ ] context({name: target}) — 弄清所有被调对象（callees） - [ ] 按职责对 callees 分组 - [ ] impact({target, direction: "upstream"}) — 画出需要同步更新的调用方 - [ ] 创建新的函数/服务 - [ ] 更新调用方 - [ ] detect_changes() — 验证受影响范围 - [ ] 运行受影响流程的测试

三条清单共享同一骨架：绑定 → 摸影响面 → 预览/规划 → 执行 → 验证 → 测试。

风险规则对照表

SKILL.md 归纳了五类典型风险及对应缓解手段：

最后一行尤其常见于 monorepo 或多仓库场景：两个仓库里都有validateUser时，漏传repo等于在错误的仓库上执行编辑——这也再次印证绑定仓库是一道安全闸门。

完整示例：把validateUser重命名为authenticateUser

以下来自 SKILL.md 的端到端演练，展示了多仓库场景下的完整交互与输出判读：

0. list_repos {} → total: 2 (my-app, billing-api) — 两个仓库都定义了 validateUser，必须显式绑定 1. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: true}) → 12 edits: 10 graph (safe), 2 text_search (review) → Files: validator.ts, login.ts, middleware.ts, config.json... 2. 复核 text_search edits（config.json 是动态引用！） 3. rename({symbol_name: "validateUser", new_name: "authenticateUser", repo: "my-app", dry_run: false}) → Applied 12 edits across 8 files 4. detect_changes({scope: "all", repo: "my-app"}) → Affected: LoginFlow, TokenRefresh → Risk: MEDIUM — 为这些流程运行测试 Repository: my-app (/abs/path/my-app) Worktree: same Index: current

解读每一步的含义：

• 第 0 步：total: 2直接触发"显式绑定"规则——billing-api中也有同名符号，不带repo: "my-app"就可能改错仓库；
• 第 1 步：预览返回 12 处编辑，其中 10 处来自图关系（高置信、安全），2 处来自文本搜索（低置信、需要复核）；
• 第 2 步：发现config.json的命中属于动态引用（配置文件中的字符串对符号名的引用无法被图关系捕获，只有文本搜索能发现），这是重构最容易漏掉、也最需要人工确认的一类；
• 第 3 步：复核通过后才写盘；
• 第 4 步：detect_changes给出受影响流程与风险评级，Risk: MEDIUM意味着应针对LoginFlow、TokenRefresh两个流程补充运行测试。返回中还带有Repository: my-app (/abs/path/my-app) Worktree: same Index: current元数据，用于确认被 diff 的 checkout 正是你编辑的那一个。

若只有一个已索引仓库，第 0 步会返回total: 1，此后所有调用都可以省略repo参数。

延伸边界：只读模式、CLI 回退与配套技能

• MCP 只读模式的边界：GitNexus MCP 有 read-only 策略（见 gitnexus/src/mcp/read-only-policy.ts），该模式下rename、cypher等破坏性/低层工具会被剔除——描述文本中会附带 "GitNexus MCP read-only mode excludes raw Cypher, mutation, and group routing" 之类的说明。也就是说，即使有该技能在手，rename这类写盘操作在只读策略下也不可用，符合"重构会落盘、必须先确认身份"的安全设计。
• CLI 回退：同一套能力在 CLI 侧也有对应入口——gitnexus impact [target]与gitnexus detect-changes（别名detect_changes），命令定义见 gitnexus/src/cli/index.ts 第 380、433 行；gitnexus impact的用法帮助在 gitnexus/src/cli/i18n/en.ts 中有完整参数（--uid、--file、--kind、--direction upstream|downstream等）。若 MCP 服务不可用或需要在脚本中批量执行，可以直接走 CLI。
• 配套技能：本文依赖的impact影响面分析还有独立专文 gitnexus/skills/gitnexus-impact-analysis.md；涉及执行流程（process）级理解时可参考 gitnexus/skills/gitnexus-debugging.md；需要语句级依赖切片的场景可结合 gitnexus/skills/gitnexus-pdg-query.md（impact的mode: 'pdg'，要求使用gitnexus analyze --pdg建索引）。

小结

安全重构的本质是"知道你在改谁、改了什么、还能改回什么"。GitNexus 把这一过程编码为一套显式协议：list_repos绑定身份（分页翻完、多仓库必传repo）→impact+context+query建立完整影响面与动态引用清单 → 以dry_run: true预览rename的双通道（graph 高置信 + text_search 需复核）编辑 →dry_run: false落盘 →detect_changes用partial/truncated标记识别"看起来干净但实际不完整"的结果 → 为受影响流程补测。配合只读策略的安全兜底与gitnexus impact/gitnexus detect-changes的 CLI 回退，这套工作流无论由 Agent 在 MCP 中驱动，还是由开发者在终端执行，都能把重构的爆炸半径控制在可视、可验证的范围内。

【免费下载链接】GitNexusGitNexus: The Zero-Server Code Intelligence Engine - GitNexus is a client-side knowledge graph creator that runs entirely in your browser. Drop in a git repository (Github, Gitlab, Azure, Local) or ZIP file, and get an interactive knowledge graph with a built in Graph RAG Agent. Perfect for code exploration项目地址: https://gitcode.com/GitHub_Trending/gi/GitNexus