understand-diff

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/understand-diff

Analyze the current code changes against the knowledge graph at

.understand-anything/knowledge-graph.json

针对

.understand-anything/knowledge-graph.json

中的知识图谱，分析当前代码变更。

Graph Structure Reference

图谱结构参考

The knowledge graph JSON has this structure:

```
project
```
— {name, description, languages, frameworks, analyzedAt, gitCommitHash}
```
nodes[]
```
— each has {id, type, name, filePath, summary, tags[], complexity, languageNotes?}
- Node types: file, function, class, module, concept
- IDs:
```
file:path
```
  ,
```
function:path:name
```
  ,
```
class:path:name
```
```
edges[]
```
— each has {source, target, type, direction, weight}
- Key types: imports, contains, calls, depends_on
```
layers[]
```
— each has {id, name, description, nodeIds[]}
```
tour[]
```
— each has {order, title, description, nodeIds[]}

知识图谱JSON的结构如下：

```
project
```
— {name, description, languages, frameworks, analyzedAt, gitCommitHash}
```
nodes[]
```
— 每个节点包含{id, type, name, filePath, summary, tags[], complexity, languageNotes?}
- 节点类型：file、function、class、module、concept
- ID格式：
```
file:path
```
  、
```
function:path:name
```
  、
```
class:path:name
```
```
edges[]
```
— 每条边包含{source, target, type, direction, weight}
- 主要类型：imports、contains、calls、depends_on
```
layers[]
```
— 每个层级包含{id, name, description, nodeIds[]}
```
tour[]
```
— 每个导览项包含{order, title, description, nodeIds[]}

How to Read Efficiently

高效阅读方法

Use Grep to search within the JSON for relevant entries BEFORE reading the full file
Only read sections you need — don't dump the entire graph into context
Node names and summaries are the most useful fields for understanding
Edges tell you how components connect — follow imports and calls for dependency chains

在阅读完整文件前，使用Grep在JSON中搜索相关条目
只阅读你需要的部分——不要将整个图谱都加载到上下文里
节点名称和摘要对于理解内容是最有用的字段
边信息展示了组件之间的关联——通过imports和calls跟踪依赖链

Instructions

操作步骤

Check that

.understand-anything/knowledge-graph.json

exists. If not, tell the user to run

/understand

first.

Get the changed files list (do NOT read the graph yet):
- If on a branch with uncommitted changes:
```
git diff --name-only
```
- If on a feature branch:
```
git diff main...HEAD --name-only
```
  (or the base branch)
- If the user specifies a PR number: get the diff from that PR
Read project metadata only — use Grep or Read with a line limit to extract just the
```
"project"
```
section for context.
Find nodes for changed files — for each changed file path, use Grep to search the knowledge graph for:
- Nodes with matching
```
"filePath"
```
  values (e.g.,
```
grep "changed/file/path"
```
  )
- This finds file nodes AND function/class nodes defined in those files
- Note the
```
id
```
  values of all matched nodes
Find connected edges (1-hop) — for each matched node ID, Grep for that ID in the edges to find:
- What imports or depends on the changed nodes (upstream callers)
- What the changed nodes import or call (downstream dependencies)
- These are the "affected components" — things that might break or need updating
Identify affected layers — Grep for the matched node IDs in the
```
"layers"
```
section to determine which architectural layers are touched.
Provide structured analysis:
- Changed Components: What was directly modified (with summaries from matched nodes)
- Affected Components: What might be impacted (from 1-hop edges)
- Affected Layers: Which architectural layers are touched and cross-layer concerns
- Risk Assessment: Based on node
```
complexity
```
  values, number of cross-layer edges, and blast radius (number of affected components)
- Suggest what to review carefully and any potential issues

Write diff overlay for dashboard — after producing the analysis, write the diff data to

.understand-anything/diff-overlay.json

so the dashboard can visualize changed and affected components. The file contains:

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>"]
}

After writing, tell the user they can run

/understand-anything:understand-dashboard

to see the diff overlay visually.

检查
```
.understand-anything/knowledge-graph.json
```
是否存在。如果不存在，告知用户先运行
```
/understand
```
。
获取变更文件列表（此时不要读取图谱）：
- 如果分支有未提交的变更：
```
git diff --name-only
```
- 如果在功能分支上：
```
git diff main...HEAD --name-only
```
  （或对应的基础分支）
- 如果用户指定了PR编号：获取该PR的diff
仅读取项目元数据——使用Grep或限制行数的方式，仅提取
```
"project"
```
部分作为上下文。
查找变更文件对应的节点——对于每个变更文件路径，使用Grep在知识图谱中搜索：
- 匹配
```
"filePath"
```
  值的节点（例如：
```
grep "changed/file/path"
```
  ）
- 这会找到文件节点以及这些文件中定义的函数/类节点
- 记录所有匹配节点的
```
id
```
  值
查找关联的边（1跳）——对于每个匹配的节点ID，在edges中Grep该ID，以找到：
- 哪些组件导入或依赖变更的节点（上游调用者）
- 变更的节点导入或调用了哪些组件（下游依赖）
- 这些就是“受影响组件”——可能会出现故障或需要更新的部分
识别受影响的层级——在
```
"layers"
```
部分Grep匹配的节点ID，确定涉及哪些架构层级。
提供结构化分析：
- 变更组件：直接修改的内容（来自匹配节点的摘要）
- 受影响组件：可能受到影响的内容（来自1跳边的结果）
- 受影响层级：涉及的架构层级以及跨层级关注点
- 风险评估：基于节点的
```
complexity
```
  值、跨层级边的数量，以及影响范围（受影响组件的数量）
- 建议需要重点评审的内容和潜在问题

为仪表板编写diff覆盖层——完成分析后，将diff数据写入

.understand-anything/diff-overlay.json

，以便仪表板可以可视化变更和受影响的组件。该文件的格式如下：

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

来可视化查看diff覆盖层。",