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?}
- Code node types: file, function, class, module, concept
- Non-code node types: config, document, service, table, endpoint, pipeline, schema, resource
- Domain/knowledge node types: domain, flow, step, article, entity, topic, claim, source
- IDs use the node type as prefix, e.g.
```
file:path
```
  ,
```
function:path:name
```
  ,
```
config:path
```
  ,
```
article:path
```
```
edges[]
```
— each has {source, target, type, direction, weight}
- Key types: imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
```
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
- 非代码节点类型：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[]}

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-level nodes (including non-code types) 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"
```
  ）
- 这会找到文件级节点（包括非代码类型）以及这些文件中定义的function/class节点
- 记录所有匹配节点的
```
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覆盖内容。",