gitnexus-impact-analysis

用途

GitNexus 的 Impact Analysis 技能用于回答代码变更的安全性问题：某个函数是否安全修改、改动 X 会破坏什么、代码的“爆炸半径”有多大、谁在使用这段代码。它适合在非平凡代码改动之前，以及提交之前，用来理解改动的影响范围。

主要能力

impact：符号爆炸半径分析的主工具，使用 direction: "upstream" 查找调用方。
detect_changes：基于 git diff 的影响分析，用于提交前检查。
读取仓库的进程信息（gitnexus://repo/{name}/processes），检查受影响的执行流程。
按深度给出风险分层：
- d=1：WILL BREAK，直接调用方/导入方；
- d=2：LIKELY AFFECTED，间接依赖；
- d=3：MAY NEED TESTING，传递性影响。
按受影响范围给出风险等级：<5 个符号且流程少为 LOW；5-15 个符号、2-5 个流程为 MEDIUM；>15 个符号或流程多为 HIGH；关键路径（认证、支付）为 CRITICAL；未找到调用方为 UNKNOWN。

使用方式

先调用 list_repos {} 绑定仓库。若只有一个已索引仓库，可按下文示例直接调用；若多于一个，则每次调用都要传 repo，否则通常会报错（在配置了默认值的 MCP 策略下会静默解析为该默认值）。若无法判断指哪个仓库，应停下来询问。list_repos 是分页的，需用 offset: pagination.nextOffset 翻页直到 hasMore 为 false，才能断定某仓库不存在。

当改动位于服务器启动时所在之外的链接工作树中，detect_changes 需要传入 worktree；服务器只有在从工作树内部启动时才会自动检测工作树，否则 git diff 会在错误的检出中运行并报告零个变更符号，产生一个不带任何降级标记的“假干净”检查。CLI 回退中，--repo . 表示当前检出；不在该仓库中时应传目标仓库路径。

工作流：

list_repos {} → 绑定仓库（及工作树）
impact({target: "X", direction: "upstream"}) 或 node .gitnexus/run.cjs impact "X" --direction upstream --repo .
READ gitnexus://repo/{name}/processes → 检查受影响的执行流程
detect_changes({scope: "all"}) 或 node .gitnexus/run.cjs detect-changes --scope all --repo .
评估风险并报告给用户，同时回显仓库/工作树/索引身份

风险报告需写明身份：Repository: <name> (<path>) Worktree: <path> Index: <commit>, <n> behind HEAD。

若提示 “Index is stale”，在终端运行 node .gitnexus/run.cjs analyze。热工具过时信息会指明回答的是哪个索引（branch/lastCommit）以及新鲜度（status）；只有 behind 或 diverged 才需重新分析——current 表示身份一致，unknown 表示不可测量。若 .gitnexus/run.cjs 不存在，将回退命令中的 node .gitnexus/run.cjs 替换为 npx gitnexus。

工具调用示例：

impact({
  target: "validateUser",
  repo: "my-app",          // 索引超过一个仓库后必填
  direction: "upstream",
  minConfidence: 0.8,
  maxDepth: 3
})

detect_changes({scope: "all"})

索引超过一个仓库后需再次传 repo，当改动位于服务器启动时所在之外的链接工作树时传 worktree: "<abs path>"。

适用场景

修改非平凡代码之前；
提交之前，理解改动影响；
判断是否可安全修改或删除某个符号；
检查受影响的执行流程。

限制与注意事项

UNKNOWN 不是该风险量表上的低档，而是表示这次遍历无法给出答案。空的调用方集合既可能表示“确实未使用”，也可能表示“索引无法解析调用方”（普通对象属性访问、动态派发、跨语言调用），因此“调用方少 ⇒ LOW”不成立，此时结果会带 riskNote 说明。若要把符号视为可安全修改或删除，需先用文本搜索确认。

risk 是编辑的门禁：HIGH/CRITICAL 要警告，UNKNOWN 要停止直到不确定性被解决。单仓库模式下，将 File 与符号目标的 local riskSharedAxes（仅 direct/total）比较；组模式下只比较组结果，它们的 riskSharedAxes 会在该本地值上叠加已解析的跨仓库交叉。不要用任一字段来豁免编辑门禁。比较种类前先检查 riskScale.unusedAxes：MCP File 遍历省略 process/module 轴，而 web Graph-RAG 会在富化前把 File 目标扩展成文件内符号。

partial: true（某次图查询失败）或 truncated: true（变更符号列表被截断）意味着结果不完整，其零值含义同 UNKNOWN：表示“未看到”，而非“未受影响”，应重跑而不是勾选提交前检查。错误工作树导致的零结果不带这两个标记，形状与真正的干净结果相同，因此在把空变更集当作通过的检查之前，要确认所编辑的检出正是被 diff 的那个。检查清单还要求先查看 d=1 项（这些会直接破坏），检查高置信度（>0.8）依赖，并确认所编辑的检出与被 diff 的检出一致。

技能介绍

用途

主要能力

使用方式

适用场景

限制与注意事项