用途
understand-diff 用于分析 Git 差异或拉取请求,帮助开发者理解代码改动了什么、涉及哪些组件、可能带来哪些风险。它并不孤立地阅读补丁,而是把变更与项目知识图谱对照,从组件和架构层面给出影响分析。
主要能力
- 变更定位:根据 git diff 输出的文件列表,在知识图谱中查找匹配 filePath 的节点,包括文件级节点以及定义在这些文件中的函数、类等节点。
- 受影响组件识别:围绕匹配到的节点做一跳边检索,找出谁导入了变更节点(上游调用方)以及变更节点导入了谁(下游依赖),从而判断哪些组件可能受影响。
- 架构层次分析:在 layers 段中检索匹配节点,确定变更触及了哪些架构层,并提示跨层关注点。
- 风险评估:结合节点 complexity 值、跨层边数量和影响范围(受影响组件数量),给出风险判断和重点复核建议。
- 图谱新鲜度校验:读取图谱 project 段中的 gitCommitHash,解析为提交后与当前 HEAD 比较,并结合暂存区、工作区和未跟踪文件命令检查项目范围内的漂移;仅触碰同级 monorepo 项目的提交不会让图谱判定为过期。
- 仪表盘覆盖层输出:分析完成后把差异数据写入 $UA_DIR/diff-overlay.json,包含 baseBranch、generatedAt、changedFiles、changedNodeIds、affectedNodeIds 等字段,供仪表盘可视化。
使用方式
- 确定数据目录:运行
UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua),检查$UA_DIR/knowledge-graph.json是否存在;不存在则提示用户先运行/understand。 - 获取变更文件列表(此时不读取图谱):有未提交改动时用
git diff --name-only;在特性分支上用git diff main...HEAD --name-only(或对应的基础分支);用户指定 PR 编号时取该 PR 的差异。 - 读取项目元数据并校验新鲜度:提取 project 段中的 gitCommitHash 作为 GRAPH_COMMIT_RAW,解析为提交后与
git rev-parse HEAD比较,并检查项目范围内的已提交、暂存、工作区和未跟踪变更。若发现项目文件变动,在影响分析前提示图谱可能缺少这些改动,建议运行/understand刷新。图谱提交缺失或无效时给出简要警告并继续,不阻塞流程。所有命令输出都要忽略所选数据目录(.ua/ 或旧版 .understand-anything/),因为其中是生成的图谱产物而非源码漂移。 - 匹配节点:对每个变更文件路径,在知识图谱中检索匹配的 filePath,记录所有匹配节点的 id。
- 查找一跳关联边:对每个匹配节点 id,在 edges 中检索,识别上游调用方和下游依赖,得到受影响组件。
- 识别受影响层次:在 layers 段中检索匹配节点 id,确定触及的架构层。
- 输出结构化分析:变更组件(含节点摘要)、受影响组件(来自一跳边)、受影响层次与跨层关注点、风险评估(基于复杂度、跨层边、影响范围),并给出重点复核建议。
- 写入差异覆盖层:把 baseBranch、ISO 时间戳、变更文件、变更节点 id、受影响节点 id(排除变更节点)写入
$UA_DIR/diff-overlay.json,并告知用户可运行/understand-anything:understand-dashboard查看可视化差异覆盖层。
知识图谱结构
图谱 JSON 包含:project(name、description、languages、frameworks、analyzedAt、gitCommitHash);nodes[](id、type、name、filePath?、summary、tags[]、complexity、languageNotes?),代码节点类型有 file、function、class、module、concept,非代码节点类型有 config、document、service、table、endpoint、pipeline、schema、resource,领域/知识节点类型有 domain、flow、step、article、entity、topic、claim、source,id 以节点类型为前缀;edges[](source、target、type、direction、weight),关键类型包括 imports、contains、calls、depends_on、configures、documents、deploys、triggers、contains_flow、flow_step、related、cites;layers[](id、name、description、nodeIds[]);tour[](order、title、description、nodeIds[])。读取时建议先用 Grep 检索相关条目再读取,只读取需要的部分,节点名称和摘要最有助于理解,边用于追踪依赖链。
适用场景
- 审查特性分支或 PR 的改动范围与影响面。
- 在提交前评估变更风险,确定重点复核区域。
- 结合知识图谱在仪表盘中直观查看变更与受影响组件。
限制
- 依赖项目中已生成的知识图谱;没有图谱时需先运行
/understand。 - 图谱若缺少最新代码改动,分析结果可能不完整,需要刷新图谱。
- 图谱提交或 Git 元数据缺失、无效时只能给出尽力而为的警告。
- 该技能基于知识图谱做静态关联分析,不保证覆盖运行时行为。