Understand-Anything 如何用 jq 查询 knowledge-graph.json 中的节点、边与分层？
【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything
你在一个项目里跑过 Understand-Anything 的/understand技能后，数据目录里会生成一个knowledge-graph.json，里面以纯 JSON 形式记录了项目的节点、边和架构分层。如果你不想每次都打开可视化面板，而是想直接在终端里提取"某个文件的节点""某个节点出发了哪些边""每一层有多少节点"这类信息，jq就是项目文档推荐的方式：knowledge-graph-guide 代理文档 明确列出了jq查询作为查询图文件的操作路径，并给出了可直接套用的命令模板。
前置条件只有两个：项目数据目录里已经存在knowledge-graph.json，以及系统上可以执行jq。
先定位 knowledge-graph.json 文件
/understand技能会把图写入项目的数据目录（understand 技能文档中的说明）：新目录是.ua/，如果项目里已经存在旧目录.understand-anything/，则继续使用旧目录。数据目录下的文件包括结构图knowledge-graph.json、可选的业务域图domain-graph.json和元数据meta.json。
下面的解析方式取自 understand-dashboard 技能文档，把它改成在你自己的项目根目录执行即可：
PROJECT_DIR=$(pwd -P) # 若图在别的项目里，把这里换成该项目的绝对路径 if [ -d "$PROJECT_DIR/.understand-anything" ]; then UA_DIR="$PROJECT_DIR/.understand-anything" else UA_DIR="$PROJECT_DIR/.ua" fi # 图文件不存在时会进入这个分支，说明还没跑过 /understand if [ ! -f "$UA_DIR/knowledge-graph.json" ]; then echo "No knowledge graph found. Run /understand first to analyze this project." exit 1 fi echo "$UA_DIR/knowledge-graph.json"最后一步echo输出的路径就是后续所有jq命令要用的文件位置。如果走到了 "No knowledge graph found" 的分支，先执行/understand生成图，再来查询。
文件结构：jq 要用的字段都来自哪里
knowledge-graph.json的顶层结构在 knowledge-graph-guide 代理文档 和 核心包的类型定义 中是一致的：
{ "version": "1.0.0", "project": { "name", "languages", "frameworks", "description", "analyzedAt", "gitCommitHash" }, "nodes": [...], "edges": [...], "layers": [...], "tour": [...] }三类查询对象对应的字段如下：
| 对象 | 关键字段 | 说明 |
|---|---|---|
节点nodes[] | id、type、name、filePath、summary、tags、complexity，可选lineRange | id有固定格式，例如文件节点是file:<relative-path>，函数节点是function:<relative-path>:<name>，类节点是class:<relative-path>:<name> |
边edges[] | source、target、type、direction、weight，可选description | source/target都是节点 ID；边类型分为 Structural（imports、contains、inherits等）、Behavioral（calls等）、Data flow（reads_from、writes_to等）、Dependencies、Semantic、Infrastructure、Domain 共 7 个类别 |
分层layers[] | id、name、description、nodeIds | 每个层是一组节点 ID 的集合，如 API、Service、Data、UI 这类架构分组 |
两点范围说明：guide 文档列出结构图的 16 种节点类型（5 代码 + 8 非代码 + 3 业务域）和 29 种边类型；而 types.ts 中的类型联合目前包含 27 种节点、38 种边，多出的 knowledge / design 类型服务于/understand-knowledge和 Figma 等其他图类型。查询knowledge-graph.json时按前者的类别表理解即可。
查询节点
guide 文档给出的第一个例子是按filePath找节点。注意其中的"src/index.ts"是文档示例值，换成你项目里的真实相对路径：
jq '.nodes[] | select(.filePath == "src/index.ts")' "$UA_DIR/knowledge-graph.json"输出是匹配到的节点对象，包含id、type、summary、tags等字段。同一模式可以替换成任意字段条件，比如按节点类型筛选：
# 列出所有函数节点 jq '.nodes[] | select(.type == "function") | {id, name, filePath}' "$UA_DIR/knowledge-graph.json"想快速判断图里某类节点的数量时，套用 guide 文档中边计数的数组模式即可：
jq '[.nodes[] | select(.type == "class")] | length' "$UA_DIR/knowledge-graph.json"查询边
guide 文档给出的第二个例子是统计某个节点发出的边数，"file:src/app.ts"同样是文档示例值，替换为你从节点查询中拿到的真实节点 ID：
jq '[.edges[] | select(.source == "file:src/app.ts")] | length' "$UA_DIR/knowledge-graph.json"顺着同一条select链取字段，就能追踪依赖方向和具体类型：
# 某个节点发出的所有边：目标节点 + 边类型 jq '.edges[] | select(.source == "file:src/app.ts") | {target, type, weight}' "$UA_DIR/knowledge-graph.json" # 只看某一类边，例如所有 calls 边 jq '.edges[] | select(.type == "calls") | {source, target}' "$UA_DIR/knowledge-graph.json"direction字段取值为forward、backward或bidirectional，可用于过滤方向：
jq '.edges[] | select(.source == "file:src/app.ts" and .direction == "forward")' "$UA_DIR/knowledge-graph.json"查询分层
guide 文档给出的架构概览命令直接列出每一层的名称和节点数量：
jq '.layers[] | {name, count: (.nodeIds | length)}' "$UA_DIR/knowledge-graph.json"想看某一层由哪些文件组成，把nodeIds展开即可：
# 展开指定层的成员节点 ID jq '.layers[] | select(.id == "layer:api") | .nodeIds[]' "$UA_DIR/knowledge-graph.json"反向查询——某个节点属于哪一层——用index在nodeIds数组里匹配：
jq '.layers[] | select(.nodeIds | index("file:packages/core/src/index.ts")) | {name, description}' "$UA_DIR/knowledge-graph.json"业务域图domain-graph.json（由/understand-domain生成）顶层形状相同，但 layers 可能为空数组，分层查询主要面向knowledge-graph.json。
用仓库自带的示例图验证
这个仓库的 dashboard 演示数据 自带一份完整的knowledge-graph.json（顶层version为1.0.0，包含nodes、edges、layers、tour），没有生成过自己项目图时可以先拿它练习。以分层查询为例：
jq '.layers[] | {name, count: (.nodeIds | length)}' understand-anything-plugin/packages/dashboard/public/knowledge-graph.json在这份演示数据上，输出形如下面的文档示例（层名与数量均来自该文件）：
{ "name": "Types & Schema Layer", "count": 2 } { "name": "Analysis Engine Layer", "count": 5 }验证方式很直接：jq无报错并输出 JSON，说明文件可解析；抽查任一节点，其id应符合type:filePath[:name]的约定，边中的source/target应能在.nodes[].id中找到。
边界与替代路径
- 数据目录是二选一的：
.understand-anything/（遗留目录存在时优先）或.ua/，不要两个目录各查一遍。 domain-graph.json只有跑过/understand-domain的项目才有，节点查询可以同样套用，例如jq '.nodes[] | select(.type == "flow")' domain-graph.json（guide 文档示例）。- 如果目的是整体浏览而不是取特定数据，文档给出的替代路径是
/understand-dashboard启动交互式面板（见 understand-dashboard 技能文档），它直接读取同一份knowledge-graph.json。 - 本文只覆盖结构图
knowledge-graph.json；tour字段（导览步骤，含order、title、description、nodeIds）同样可以按上面的select模式查询，例如jq '.tour[0]' "$UA_DIR/knowledge-graph.json"。
【免费下载链接】Understand-AnythingGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
