understand-explain

/understand-explain

对特定代码组件进行全面、深入的说明。

图结构参考

知识图谱 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. 使用图谱派生的上下文前，检查图谱是否最新：

   • 从图谱元数据中读取 project.gitCommitHash，记为 GRAPH_COMMIT_RAW。在任何 Git diff 中使用它之前，先将其解析为一个提交，然后将其与 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 -- .
     

   • 必须使用 -- . 路径规格：如果提交只修改了单体仓库中的同级项目，不应导致此图谱过时。仅哈希不匹配并不代表过时；如果项目 diff 为空，则不算过时。
   • 在每条命令的输出中忽略所选数据目录（.ua/ 或旧目录 .understand-anything/），因为其中包含的是生成的图谱制品，而非项目源代码变更。
   • 如果已提交 diff 或任何工作区命令报告了项目文件，先发出警告，再说明图谱派生的上下文可能未包含这些更改。建议：运行 /understand 刷新图谱。
   • 只有当 GRAPH_COMMIT_RAW 成功解析时，才运行提交 diff。如果图谱提交或 Git 元数据缺失、无效或不可用，应简短说明无法完整检查，并尽力继续，而不是阻止后续操作。

3. 查找目标节点——使用 Grep 在知识图谱中搜索组件：“$ARGUMENTS”

   • 对于文件路径（例如 src/auth/login.ts）：搜索 "filePath" 匹配项
   • 对于函数表示法（例如 src/auth/login.ts:verifyToken）：在 "name" 字段中搜索函数名，并按文件路径筛选
   • 记录节点的确切 id、type、summary、tags 和 complexity

4. 查找所有关联边——在 edges 部分中使用 Grep 搜索目标节点的 ID：

   • 匹配 "source" → 此节点调用、导入或依赖的内容（出边）
   • 匹配 "target" → 调用、导入或依赖此节点的内容（入边）
   • 记录关联节点 ID 和边类型

5. 读取关联节点——对于步骤 4 中的每个关联节点 ID，在 nodes 部分中使用 Grep 搜索这些 ID，以获取它们的 name、summary 和 type。由此构建该组件的邻域。

6. 识别所属层——在 "layers" 部分中使用 Grep 搜索目标节点的 ID，查找其所属的架构层及该层的描述。

7. 阅读实际源文件——读取节点 filePath 指向的源文件，以进行深入分析。

8. 结合上下文说明组件：

   • 说明它在架构中的作用（所属层及存在原因）
   • 说明内部结构（它包含的函数、类——来自 contains 边）
   • 说明外部连接（它导入什么、什么会调用它、它依赖什么——来自各条边）
   • 说明数据流（输入 → 处理 → 输出——来自源代码）
   • 解释清楚，并假设读者可能不了解该编程语言
   • 指出值得理解的模式、惯用写法或复杂性