understand-chat

/understand-chat

使用项目数据目录中的知识图谱（.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. 使用图谱派生的上下文前，检查图谱是否为最新版本：

   • 从图谱元数据中读取 project.gitCommitHash，记为 GRAPH_COMMIT_RAW。在将其用于任何 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 元数据缺失、无效或不可用，请给出简短的尽力而为警告，然后继续，不要因此中止。

3. 仅读取项目元数据——使用 Grep 或 Read 并限制行数，仅提取文件顶部的 "project" 部分作为上下文（名称、描述、语言、框架）。

4. 搜索相关节点——使用 Grep 在知识图谱文件中搜索用户查询关键词：“$ARGUMENTS”

   • 搜索 "name" 字段：在图谱文件中运行 grep -i "query_keyword"
   • 搜索 "summary" 字段以查找语义匹配
   • 搜索 "tags" 数组以查找主题匹配
   • 记下所有匹配节点的 id 值

5. 查找相连的边——对每个匹配的节点 ID，在 edges 部分中使用 Grep 搜索该 ID，以查找：

   • 它导入或依赖的内容（下游）
   • 调用或导入它的内容（上游）
   • 这将得到查询周边的 1 跳子图

6. 读取分层上下文——使用 Grep 搜索 "layers"，了解匹配节点所属的架构层。

7. 仅使用相关子图回答查询：

   • 引用图谱中的具体文件、函数和关系
   • 说明哪些层相关以及原因
   • 简洁而全面地回答，并将概念关联到实际代码位置
   • 如果查询未匹配到任何节点，请说明这一点，并从图谱中建议相关术语