understand-diff

/understand-diff

根据项目数据目录中的知识图谱（.ua/knowledge-graph.json；如果存在旧版 .understand-anything/ 目录，则使用其中的 knowledge-graph.json），分析当前代码变更。

图结构参考

知识图谱 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 使用节点类型作为前缀，例如 file:path、function:path:name、config:path、article:path
• 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[]}

高效读取方法

1. 使用 Grep 在 JSON 中搜索相关条目，然后再读取整个文件
2. 仅阅读所需部分，不要将整个图谱全部载入上下文
3. 节点名称和摘要是最有用的信息
4. 边用于了解组件之间的关联——沿着 imports 和 calls 跟踪依赖链

说明

1. 确定数据目录 $UA_DIR。 运行 UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) —— 如果旧目录 .understand-anything/ 已存在，就使用它；否则使用新的 .ua/。检查 $UA_DIR/knowledge-graph.json 是否存在。如果不存在，请告知用户先运行 /understand。

2. 获取已更改文件列表（此时不要读取图谱）：

   • 如果当前分支有未提交的更改：git diff --name-only
   • 如果当前位于功能分支：git diff main...HEAD --name-only（或与基准分支比较）
   • 如果用户指定了 PR 编号：获取该 PR 的差异

3. 读取项目元数据并检查图谱是否最新 —— 使用 Grep 或 Read 并限制行数，提取 "project" 部分，包括作为 GRAPH_COMMIT_RAW 的 gitCommitHash，然后：

   • 在用于任何 Git 差异比较之前，先将其解析为提交。从项目根目录，将解析出的提交与 git rev-parse HEAD 比较，并检查项目范围内已提交和工作区中的更改：

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .
     

   • 必须使用 -- . 路径规范：如果提交只修改了单体仓库中的同级项目，不应因此判定此图谱已过时。仅提交哈希不匹配并不代表图谱已过时，项目差异为空时尤其如此。
   • 在每条命令的输出中忽略选定的数据目录（.ua/ 或旧版 .understand-anything/），因为其中包含生成的图谱产物，而非项目源代码变更。
   • 如果已提交差异或任何工作区命令报告了项目文件，须在影响分析前警告用户：图谱可能未包含这些更改。建议：运行 /understand 刷新图谱。
   • 仅当 GRAPH_COMMIT_RAW 成功解析时才运行提交差异比较。如果图谱提交或 Git 元数据缺失、无效或不可用，简要提示当前只能尽力分析，然后继续，不要因此中止。

4. 查找已更改文件对应的节点 —— 对每个已更改文件路径，使用 Grep 在知识图谱中搜索：

   • "filePath" 值匹配的节点（例如，grep "changed/file/path"）
   • 这会找到文件级节点（包括非代码类型）以及在这些文件中定义的函数／类节点
   • 记录所有匹配节点的 id 值

5. 查找相连边（1 跳） —— 对每个匹配的节点 ID，在边中 Grep 搜索该 ID，以查找：

   • 导入或依赖已更改节点的内容（上游调用方）
   • 已更改节点导入或调用的内容（下游依赖项）
   • 这些就是“受影响的组件”——可能会出问题或需要更新的部分

6. 确定受影响层 —— 在 "layers" 部分 Grep 搜索匹配的节点 ID，以确定涉及哪些架构层。

7. 提供结构化分析：

   • 已更改组件：直接修改了哪些内容（根据匹配节点的摘要）
   • 受影响组件：可能受到影响的内容（根据 1 跳边）
   • 受影响层：涉及哪些架构层，以及跨层关注点
   • 风险评估：根据节点的 complexity 值、跨层边的数量和影响范围（受影响组件的数量）进行评估
   • 建议需要仔细检查的内容及任何潜在问题

8. 为仪表板写入差异覆盖数据 —— 完成分析后，将差异数据写入 $UA_DIR/diff-overlay.json，以便仪表板可视化已更改和受影响的组件。文件内容如下：

   {
     "version": "1.0.0",
     "baseBranch": "<the base branch used>",
     "generatedAt": "<ISO timestamp>",
     "changedFiles": ["<list of changed file paths>"],
     "changedNodeIds": ["<node IDs from step 4>"],
     "affectedNodeIds": ["<node IDs from step 5, excluding changedNodeIds>"]
   }
   

   写入后，告知用户可以运行 /understand-anything:understand-dashboard 以直观查看差异覆盖层。