dev-context-code-graph

代码图谱

为单个代码仓库构建确定性、机器可读的代码图谱。将图谱视为供 LLM 维护的代码仓库 Wiki 或上下文中心使用的机器可读基础，而不仅仅是仅供终端查看的报告。此技能沿用 dev-context-multi-repo 的产物工作流，但处理的是文件和符号级别，而非代码仓库集合级别。

在以下情况使用此技能：

• 需要可提交的 graphs/code-graph.json 产物
• 需要单个代码仓库的文件和符号映射
• 需要分析导入、调用、继承和测试链接
• 需要图论审查信号，例如关节点、桥、环、拓扑顺序和替代路径
• 需要评估变更文件或符号的影响范围，并获取最小审查上下文
• 需要通过 Personalized PageRank 获取围绕 1–3 个热点符号、受预算限制的上下文
• 需要根据图数据生成有依据的代码仓库或模块描述，而不是临时编写代码库介绍

以下情况不要使用此技能：

• 发现整个代码仓库集合或绘制跨代码仓库系统图
• 为多个代码仓库制定架构或迁移计划
• 不生成图谱，只清理文字文档

请改用相关技能：

• dev-context-multi-repo：用于代码仓库集合和中心级知识图谱
• dev-context-engineering：用于判断应该使用代码图谱、上下文图谱还是代码仓库图谱
• docs-ai-prd：用于代码图谱规范和验收标准
• docs-codebase：用于发布基于图谱的文档和报告

快速参考

需求	从这里开始
生成基础产物集	## Workflow
验证架构和图谱完整性	### Phase 3: Validate
查询影响范围或符号邻域	### Phase 4: Query
显示图谱结构风险	query_code_graph.py --articulation-points、--bridges、--cycles、--topo-sort、--from ... --to ... --k N
运行热点符号 PPR 检索	query_code_graph.py --ppr --seed <id> [--seed <id> ...] --top N
通过社区检测模块	query_code_graph.py --communities [--resolution γ] [--community-seed N]
为审查选择合适的查询	references/query-recipes.md
加载脚本、架构和报告	## Navigation

标准输出

每次运行都应采用相同的输出模型：

• code-profiles/<repo>.json 符合 schemas/code-profile.schema.json 的机器可读代码档案。
• graphs/code-graph.json 主要机器可读产物。符合 schemas/code-graph.schema.json、可供查询的符号图谱。
• reports/code-graph-validation.json (可选，但推荐) scripts/validate_code_graph.py --output ... 的输出。
• reports/code-graph-report.md (可选，但推荐) 根据图谱生成的人工可读摘要报告。
• reports/query-*.md (可选，但推荐) 持久化值得归档到代码仓库知识库中的影响范围、邻域和关系查询结果。
• reports/code-graph-report.html (可选) 用于本地审查的静态 HTML 报告。
• reports/code-graph.mmd (可选) 导出图谱邻域或影响视图的 Mermaid 图表。

工作流

Phase 1：扫描

1. 按扩展名识别受支持的源文件，同时跳过生成目录和供应商构建目录。
2. 将文件分类为 source、test、config 或 unknown。
3. 使用可用的最佳确定性策略解析每个文件。
4. 明确记录解析状态：parsed、heuristic、unsupported、error 或 skipped。

主要辅助脚本：scripts/scan_code_repo.py

ASCII 流程图

single-repo code graph request
  -> scan files and classify source, test, config, or unknown
  -> parse symbols with deterministic or heuristic parser
  -> build nodes and edges into graphs/code-graph.json
  -> validate schema, references, duplicates, orphans, and parse confidence
  -> query neighborhoods, impact, paths, PPR, communities, or structural risk
  -> persist useful reports back into repo context
  -> use findings for review, docs, onboarding, or blast-radius planning

阶段 2：构建

1. 读取一个或多个 code-profiles/*.json 文件。
2. 将规范节点和边写入 graphs/code-graph.json。
3. 添加从 repo 到 file，以及从父级符号或 file 到子级符号的结构边。
4. 为无法解析或指向第三方的导入／调用目标合成 external_symbol 节点。

主要辅助脚本：scripts/build_code_graph.py

阶段 3：验证

每次构建后都运行验证：

python3 scripts/validate_code_graph.py graphs/code-graph.json \
  --output reports/code-graph-validation.json

验证器会检查：

• 模式和枚举是否符合要求
• 是否存在悬空引用
• 是否存在孤立节点
• 是否存在重复 ID
• 包含关系／父级边是否一致
• 是否存在循环导入
• 验证元数据是否过时
• 解析状态和置信度是否在限定范围内

阶段 4：查询

常见查询模式：

# Neighborhood around a file or symbol
python3 scripts/query_code_graph.py graphs/code-graph.json --node <id> --hops 1

# Blast radius from a file or symbol
python3 scripts/query_code_graph.py graphs/code-graph.json --impact <id> --hops 2

# Path between two nodes
python3 scripts/query_code_graph.py graphs/code-graph.json --from <id> --to <id>

# Up to three node-disjoint shortest paths
python3 scripts/query_code_graph.py graphs/code-graph.json --from <id> --to <id> --k 3

# Personalized PageRank from one or more hot symbols
python3 scripts/query_code_graph.py graphs/code-graph.json --ppr --seed <id> --top 30

# Module detection via Louvain communities (γ=1 default; >1 = smaller modules, <1 = larger)
python3 scripts/query_code_graph.py graphs/code-graph.json --communities --format table
python3 scripts/query_code_graph.py graphs/code-graph.json --communities --resolution 1.4 --top 25

# Search by label, path, summary, or tags
python3 scripts/query_code_graph.py graphs/code-graph.json --search "invoice service"

# Structural risk
python3 scripts/query_code_graph.py graphs/code-graph.json --articulation-points --relations imports --top 20
python3 scripts/query_code_graph.py graphs/code-graph.json --bridges --relations imports --top 20
python3 scripts/query_code_graph.py graphs/code-graph.json --cycles --relations imports,inherits,calls
python3 scripts/query_code_graph.py graphs/code-graph.json --topo-sort imports

# Mermaid diagram export
python3 scripts/query_code_graph.py graphs/code-graph.json --diagram --output reports/code-graph.mmd

主要辅助脚本：scripts/query_code_graph.py

如果查询结果能形成持久知识，请将其写入 Markdown 或 Mermaid，而不是只留在聊天输出中。

使用查询输出生成：

• repo 区域说明
• 模块摘要
• 变更影响说明
• 针对高风险符号或子系统的审查材料包

阶段 5：发布

生成人类可读的静态报告：

python3 scripts/export_code_graph_report.py graphs/code-graph.json \
  --output-dir reports/

优先使用 Markdown、Mermaid 或 HTML 输出，以便在 Obsidian 中审阅或归档到更广泛的上下文中心。

阶段 6：增强

对基于图的知识执行轻量级健康检查：

1. 检查验证结果，查找缺失的边、解析缺口，以及需要说明的支持不足区域。
2. 请 LLM 根据图中连接密集或连接薄弱的区域，提出可复用报告、概念页面或后续问题。
3. 将持久的发现归档到 reports/ 或更高层级的 repo 知识库，而不是日后重复相同的探索。

如果图用于生成 repo 说明，请限制生成范围：

• 仅总结图能够支持的内容
• 明确指出解析缺口
• 不要仅凭符号名称臆造所有权、运行时行为或架构职责

V1 支持范围

v1 解析器流水线具有确定性，并采取保守策略。

• 完整解析器：通过 ast 解析 Python
• 启发式解析器：JavaScript、TypeScript、TSX、C#、Swift
• 不支持的语言：仅生成 file 节点，并明确标记

v1 中对 Swift 的支持有意采用启发式方案。扫描器会从 .swift 文件中提取顶层类型和函数符号，以保守方式记录 imports 和继承／协议边，并避开 .build、DerivedData、Pods、Carthage 和 SourcePackages 等 Apple 生成的构建输出。

该图涵盖：

• repo、file、class、function、method、test、external_symbol 节点
• contains、defines、imports、calls、inherits、references、tests 边

该图不会尝试实现：

• 语义嵌入
• 监视模式或 IDE 同步
• SQLite 持久化
• 全程序类型推断
• 保证精确解析动态代码中的所有调用

对于小型和中型 repo，直接查询图并生成精简的 Markdown 报告通常已经足够。在图 JSON 和摘要无法继续满足实际需要之前，不要添加更重型的检索或索引层。

命令模式

从以下指令中任选一条开始：

• “使用 dev-context-code-graph 为此 repo 构建代码图。”
• “使用 dev-context-code-graph 查找 <file-or-symbol> 的影响范围。”
• “使用 dev-context-code-graph 找出覆盖 <module> 的测试。”
• “使用 dev-context-code-graph 导出此代码库区域的 Mermaid 图。”
• “使用 dev-context-code-graph 根据图中的证据生成 repo 区域说明。”

推荐目录布局

code-hub/
├── AGENTS.md
├── code-profiles/
├── graphs/
├── reports/
├── schemas/
└── scripts/

将生成的图数据保存在 code-profiles/、graphs/ 和 reports/ 中。不要将清单或原始符号列表粘贴到根目录的指令文件中。

稳定类型

该技能采用以下规范契约：

• schemas/code-profile.schema.json
• schemas/code-graph.schema.json

除非下游系统要求添加转换层，否则不要创建其他结构。

验证清单

• 每个扫描的代码仓库都生成一个 code-profiles/<repo>.json。
• 每个节点都有稳定的规范化 ID。
• 每个带有 parent_id 的节点都有对应的 contains 或 defines 边。
• 明确标记所有不受支持的解析或解析失败。
• graphs/code-graph.json 通过验证。
• 影响范围和路径查询返回范围有限、易于阅读的结果。
• 将外部目标表示为 external_symbol 节点，而不是悬空边。
• 将值得复用的发现写入 markdown 或图表文件，而不是只留在聊天记录中。
• 任何生成的代码仓库或模块描述都应以图谱证据为依据，并明确指出解析缺口。

已知陷阱

• 当文件格式或语言支持不完整时，将启发式解析器的输出视为语义上的事实。
• 跳过明确的解析状态和置信度字段，导致下游摘要显得比图谱实际所能支持的更确定。
• 直接从临时脚本或 LLM 摘要构建图边，而不是通过配置文件和架构契约进行规范化。
• 假设不受支持的语言可以被悄然忽略，而不是记录会影响影响范围查询的覆盖缺口。
• 每个问题都使用一个庞大的图谱查询，尽管有限范围的邻域或影响查询已经足够，而且更易于验证。
• 将代码图谱视为读取源文件的替代品；它是用于路由和影响范围分析的基础，并非判断行为的最终依据。
• 将整个代码仓库的图谱输出放入 LLM 提示词，而不是使用图谱节点 ID、路径和范围有限的查询，按需获取上下文。

常见反模式

• 将图谱变成充斥文字的报告生成器，丢失使其可信的机器可读基础。
• 随意发明新的节点或边类型，而不是保留稳定架构，并在需要时添加转换层。
• 将外部库和无法解析的符号视为缺失数据，而不是将其表示为 external_symbol 节点。
• 发布基于图谱输出的代码仓库或模块描述，却不指出解析缺口、启发式方法和不受支持的部分。
• 在确定性图谱和查询工作流尚未达到实际所需水平之前，就添加更重型的检索或嵌入方案。
• 将生成的摘要重新输入图谱提取流程，并把它们当作源证据。
• 让每个代码仓库的符号节点泄漏到组合知识图谱中，而不是发布带链接的代码图谱报告或精选摘要。

导航

参考资料

• references/code-graph-patterns.md
• references/parser-support-matrix.md
• references/query-recipes.md

架构

• schemas/code-profile.schema.json
• schemas/code-graph.schema.json

脚本

• scripts/scan_code_repo.py
• scripts/build_code_graph.py
• scripts/validate_code_graph.py
• scripts/query_code_graph.py
• scripts/export_code_graph_report.py
• scripts/test_code_graph_regressions.py

示例

• examples/python-mini-repo.md
• examples/typescript-mini-repo.md

事实核查

• 对已知错误、回归问题、框架／编译器／运行时中的易踩坑点，以及特定版本的崩溃或解决方法，必须先根据当前的网络一手资料进行核实，才能将其视为当前事实。
• 如果实现发生变化，在面向用户的答复中提及解析器支持情况前，必须重新核实。
• 有关解析器运行时、AST 行为和 JSON Schema 语义，优先采用一手参考资料。
• 使用 data/sources.json 作为精选来源索引。