understand-chat 是一个技能,用于通过知识图谱回答关于代码库的问题,帮助用户理解代码结构。
用途
该技能在用户需要就代码库提问或借助知识图谱理解代码时使用。它基于项目数据目录中的知识图谱文件提供问答能力。
主要能力
- 读取并利用知识图谱中的项目元数据(名称、描述、语言、框架、分析时间、git 提交哈希)。
- 支持多种节点类型:代码节点(file、function、class、module、concept)、非代码节点(config、document、service、table、endpoint、pipeline、schema、resource)以及领域/知识节点(domain、flow、step、article、entity、topic、claim、source)。
- 支持边类型如 imports、contains、calls、depends_on、configures、documents、deploys、triggers、contains_flow、flow_step、related、cites,用于追踪依赖和调用链。
- 提供 layers 和 tour 结构,帮助理解架构分层和导览。
- 指导高效读取:使用 Grep 在 JSON 中搜索相关条目,仅读取所需部分,避免上下文过载。
使用方式
- 解析数据目录 $UA_DIR:运行 UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua),即优先使用旧版 .understand-anything/,否则使用新版 .ua/。检查当前项目根目录下 $UA_DIR/knowledge-graph.json 是否存在。若不存在,提示用户先运行 /understand。
- 检查图谱新鲜度:从图谱元数据读取 project.gitCommitHash 作为 GRAPH_COMMIT_RAW,将其解析为提交后与 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 -- . 必须使用 -- . 路径规范,避免同级 monorepo 项目的提交导致误判。仅在 GRAPH_COMMIT_RAW 成功解析时运行提交差异。忽略所选数据目录(.ua/ 或旧版 .understand-anything/)的输出,因为其中包含生成的图谱产物。如果已提交差异或任何工作区命令报告项目文件,则在回答前警告图谱派生上下文可能遗漏这些变更,并建议运行 /understand 刷新图谱。若图谱提交或 Git 元数据缺失、无效或不可用,给出简要的最佳努力警告并继续,而不是阻塞。
- 仅读取项目元数据:使用 Grep 或带行限制的 Read 从文件顶部提取 "project" 部分,获取名称、描述、语言、框架。
- 搜索相关节点:使用 Grep 在知识图谱文件中搜索用户查询关键词 "$ARGUMENTS":在 "name" 字段中不区分大小写搜索;在 "summary" 字段中搜索语义匹配;在 "tags" 数组中搜索主题匹配;记录所有匹配节点的 id 值。
- 查找连接的边:对每个匹配节点 ID,在 edges 部分用 Grep 搜索该 ID,找出它导入或依赖的内容(下游)以及调用或导入它的内容(上游),从而获得查询周围的一跳子图。
- 读取层上下文:Grep 搜索 "layers",了解匹配节点属于哪些架构层。
- 仅使用相关子图回答查询:引用图谱中的具体文件、函数和关系;解释哪些层相关及原因;简洁但全面,将概念链接到实际代码位置。如果查询不匹配任何节点,说明情况并建议图谱中的相关术语。
适用场景
适用于需要理解代码库、查找特定功能实现、追踪依赖关系、了解架构分层等场景。
限制
- 依赖已生成的知识图谱文件;若文件不存在需先运行 /understand。
- 图谱可能因代码变更而过时,需检查新鲜度并在必要时刷新。
- 回答基于图谱中的信息,若查询不匹配节点则无法直接回答。