code-atlas

Code Atlas 技能

目的

直接基于代码事实，构建全面且可重新生成的架构地图。代码地图是一组持续更新的文档：其中的图表、关系图和清单表格共同构成可导航的代码库地图。构建地图是一项调查工作：以图的形式对代码进行结构化推理，可以揭示线性代码审查容易遗漏的结构性错误、API 契约不匹配和架构偏移。

如果任何工程师仅凭代码地图和一份错误报告，就能追踪完整的执行路径，而无需打开源代码，那么这份地图就算完整。

分层概览

层定义以 LAYERS.yaml 为唯一真实来源。下文所有引用均使用该文件中的 slug。

Slug	名称	描述	推荐的图表类型
repo-surface	仓库概览	所有源文件、项目结构、构建系统	Mermaid flowchart TD
ast-lsp-bindings	AST+LSP 符号绑定	跨文件符号引用、死代码、接口不匹配	Mermaid flowchart LR 或 DOT 有向图
compile-deps	编译时依赖	包导入、依赖树、循环依赖	DOT 有向图（更适合处理大型依赖树）
runtime-topology	运行时拓扑	服务、容器、端口、服务间连接	带子图集群的 DOT 有向图
api-contracts	API 契约	HTTP 路由、gRPC、GraphQL、中间件链	Mermaid flowchart TD
data-flow	数据流	DTO 到存储的链路、转换步骤	Mermaid flowchart LR
service-components	服务组件架构	各服务内部的模块／包结构	Mermaid graph TD（每个服务一张）
user-journeys	用户旅程场景	从入口到结果的端到端路径	Mermaid sequenceDiagram

各层范围指南

Slug	范围目标
repo-surface	顶层目录和构建入口。不要逐一列出所有文件。
ast-lsp-bindings	导出的符号及其跨文件引用。重点关注公共 API 表面。
compile-deps	直接依赖和一层传递依赖。注明版本约束。
runtime-topology	所有已部署的服务、各自的端口及服务间协议。
api-contracts	列出每个 HTTP/gRPC/GraphQL 端点及其认证、DTO 和中间件。
data-flow	每个服务的主要读写路径。除非相关，否则跳过内部缓存流程。
service-components	每个服务中的顶层包／模块。展示耦合关系。
user-journeys	根据 api-contracts 路由和页面／CLI 入口推导。追踪 3-8 个关键旅程。

技能委派架构

code-atlas (this skill)
  Responsibilities:
    - Atlas layer orchestration (all 8 layers)
    - Language-agnostic code exploration
    - Three-pass bug-hunting workflow
    - Staleness detection triggers
    - Density management (split, not prompt)
    - Publication workflow (GitHub Pages, mkdocs, SVG)

  Delegates to:
    code-visualizer skill       Python AST module analysis (compile-deps + service-components fallback)
    mermaid-diagram-generator   Mermaid syntax generation and formatting
    lsp-setup skill             Layer ast-lsp-bindings: LSP-assisted symbol queries (optional)
    visualization-architect     Complex DOT graph rendering and cross-layer layouts
    analyzer agent              Deep codebase investigation and dependency mapping
    reviewer agent              Contradiction hunting (Passes 1, 2, 3)

何时使用此技能

触发条件	使用场景
开始处理不熟悉的代码库	编码前完整构建图谱
新工程师入职	分享图谱作为导航指南
重大重构前	绘制当前状态；根据拓扑规划变更
Bug 排查陷入停滞	通过图进行第 1 轮 + 第 2 轮 Bug 排查
文档感觉过时	检查过时情况 + 有针对性地重新构建
添加 CI/CD 质量门禁	注册图谱新鲜度检查
发布文档站点	GitHub Pages / mkdocs 发布工作流
审查不熟悉的 PR	使用当前图谱与差异对比，查看 PR 影响

快速开始

# Build a full atlas
User: Build a complete code atlas for this repository

# Run bug hunting
User: Run code atlas bug hunting passes on this service

# Check freshness
User: Are our architecture diagrams still accurate?

# Publish
User: Publish our code atlas to GitHub Pages

为什么同时使用 Mermaid 和 Graphviz

此技能默认使用这两种格式构建图谱图，因为它们能发现不同的 Bug。一项针对 7 个代码库的受控实验表明，两者发现的 Bug 只有约 15% 重叠——同时使用两者发现的 Bug 数量约为单独使用任一格式的 1.7 倍。不同的语法会促使人们通过不同的推理路径分析同一份代码。证据记录在 PR #3221 中。

用户可以改为只使用一种格式：

User: Build a code atlas using only Mermaid
User: Build a code atlas in DOT format only

图表密度策略

节点/边数量没有硬性限制。相反：

如果图表过于密集而难以阅读，就按包或服务边界拆分成多个子图。 在批处理模式下，自动分组，无需询问用户。每个子图应包含 15–40 个节点，以便于阅读。

例如，包含 80 个服务的运行时拓扑图应按领域拆分成多个子图（例如，runtime-topology-payments.mmd、runtime-topology-auth.mmd），并附上一张显示跨领域连接的高层概览图。

表格仅作为图表的配套内容生成，绝不替代图表。

配方：12 阶段图谱构建

图谱构建依次经过以下阶段：

1. 验证前置条件 -- 检查工具（mmdc、dot、kuzu），检测 LSP 模式
2. 构建第 1–4 层（结构层）-- repo-surface、ast-lsp-bindings、compile-deps、runtime-topology
3. 构建第 5–8 层（行为层）-- api-contracts、data-flow、service-components、user-journeys
4. 验证全部 8 层 -- 硬性门槛：每个 slug 都必须包含 .mmd、.dot、渲染后的 .svg，以及嵌入图片的 README
5. Bug 排查（Mermaid 分支） -- 仅使用 .mmd 图表进行 3 轮排查
6. Bug 排查（Graphviz 分支） -- 仅使用 .dot 图表进行 3 轮排查（与第 5 步并行）
7. 合并发现结果 -- 对两个分支的结果去重
8. 多 Agent 验证 -- 3 位专家独立投票；至少 2/3 确认后通过
9. 提交问题 -- 将已验证的 Bug 提交为 GitHub issue（绝不存储在图谱中）
10. Kuzu 导入 + OpenCypher -- 导入图中（必需）+ 生成独立的 .cypher 文件
11. 发布图谱 -- 渲染 SVG、编写索引、更新 mkdocs 导航
12. 最终清单审查 -- 由独立审查者验证所有交付物是否完整

每个构建阶段结束后，图表都会写入 docs/atlas/{slug}/，其中包含 .mmd 源文件、.dot 源文件、渲染后的 *-mermaid.svg 和 *-dot.svg，以及使用 ![alt](file.svg) 语法内嵌 SVG 的 README.md。

Bug 排查工作流概览

atlas 是一个持续进行的调查工具。通过三个阶段，它会从一张地图转变为高置信度的 Bug 检测引擎。每个阶段都在全新的上下文窗口中运行，以防止锚定偏差。

• 阶段 1（全面构建 + 排查）：构建所有层，然后系统地排查各层之间的矛盾。路由/DTO 不匹配、孤立的环境变量、无效的运行时路径、过时的文档引用。
• 阶段 2（全新视角交叉检查）：在新的上下文窗口中独立重新检查 atlas。确认、推翻或升级阶段 1 的发现。
• 阶段 3（场景深度分析）：对每个 user-journeys 旅程，都通过 api-contracts、data-flow、runtime-topology、service-components 和 ast-lsp-bindings 进行端到端追踪。每个旅程都会得到一个结论：PASS、FAIL 或 NEEDS_ATTENTION。

完整的检查清单、模板和输出格式：bug-hunt-guide.md

第 8 层：ast-lsp-bindings 运行模式

ast-lsp-bindings 层以以下两种模式之一运行，并始终在其 README 第 1 行标注模式：

模式	触发条件	机制
lsp-assisted	lsp-setup 报告 LSP 服务处于活动状态	将符号查询委托给 LSP
static-approximation	LSP 不可用	ripgrep + code-visualizer AST

模式标签绝不会缺失，也不会在不提示的情况下使用默认模式。

输出结构

docs/atlas/
  index.md
  staleness-map.yaml
  {slug}/
    README.md          (embeds SVG diagrams inline with ![alt](file.svg))
    *-mermaid.svg      (rendered Mermaid diagrams)
    *-dot.svg          (rendered Graphviz diagrams)
    *.mmd              (Mermaid source)
    *.dot              (Graphviz source)
    inventory.md       (where applicable)
  cypher/
    schema.cypher      (CREATE NODE/REL TABLE statements)
    atlas-layers.cypher
    atlas-services.cypher
    atlas-bugs.cypher
    atlas-relationships.cypher
    queries.cypher     (ready-to-run example queries)

三条不可妥协的输出规则：

1. Bug 排查结果绝不会存储在 atlas 中。所有发现都以带有 code-atlas-bughunt 标签的 GitHub issue 提交。
2. Kuzu 导入必须执行，不可省略。如果 Kuzu 不可用，则明确报错并尝试修复（安装 kuzu package）。绝不能悄悄跳过。
3. 始终在导入 Kuzu 的同时生成 OpenCypher .cypher 文件，以便移植到任何图数据库。

过时检测

每层的过时触发条件在 LAYERS.yaml 中以 glob 模式定义。当 git diff 匹配某个触发模式时，相应的层会被标记为过时。

完整的触发表、重建命令和增量重建策略： reference.md

CI 集成

提供三种 GitHub Actions 模式：

1. 合并后过时检查门禁，并自动提交
2. PR 影响检查，并标注受影响层
3. 每周定时进行完整重建，失败时创建 issue

完整的工作流 YAML 和配置：publication-guide.md

发布

输出适用于 GitHub Pages 的 docs/atlas/ 结构。兼容 mkdocs-material 和纯 GitHub Pages。SVG 会提交到仓库，因此读取时无需执行渲染步骤。

SVG 生成命令、mkdocs 集成和部署工作流： publication-guide.md

图表示例

各层的 Mermaid 和 DOT 示例，以及推荐的图表类型： examples.md

安全控制

所有安全控制（SEC-01 至 SEC-19）都定义在 SECURITY.md 中。 关键控制：

• 绝不输出机密值（仅解析环境文件中的键名）
• 通过 realpath() 边界验证防止路径遍历
• 对 Mermaid/DOT/SVG 标签进行清理（防止 XSS）
• 对 Bug 报告中的代码引用进行凭据模式脱敏
• 所有 file:line 引用均使用相对路径（SEC-16）

API 契约

所有技能委派和文件系统布局的类型化契约： API-CONTRACTS.md

参考

错误代码、Kuzu 导入架构、过时触发表： reference.md

成功标准

一份完整的图谱应满足：

• 在 docs/atlas/{slug}/ 中生成全部 8 个层，并包含图表
• 同时提供 DOT 和 Mermaid 源文件（除非用户要求使用单一格式）
• SVG 与源文件一同生成
• 将查错发现记录为 GitHub issues（绝不存放在图谱文档中）
• 每条已记录的 bug 都包含：层引用、文件路径、行号、代码证据
• 图表中没有孤立节点
• ast-lsp-bindings README 在第 1 行注明模式

限制

• 不是静态分析工具：使用 grep、AST、配置解析，而非编译器
• 过时判断采用启发式方法：通过 Git diff 模式匹配，而非语义分析
• 委托 Python AST 分析：Python 模块图委托给 code-visualizer（仅支持 Python）
• SVG 渲染需要 Graphviz/Mermaid CLI：CI 环境需要安装这些工具
• 查错结果具有概率性：提交前需要人工审核
• 专注于单个仓库：跨仓库依赖需要手动配置
• 没有运行时检测：调用频率和延迟需要借助 APM 工具

请牢记

绘制图表是一种调查，而不只是编写文档。

代码图谱最有价值的产出，是以图的形式推理系统时发现的 bug 和矛盾。

以下五条规则绝不容妥协：

1. 不得悄悄将图表替换为表格。 如果图表过于密集，就拆分为多个子图。
2. 模式必须始终可见。 ast-lsp-bindings README 必须始终在第 1 行注明其模式。
3. 分三轮查错。 第 1 轮查找，第 2 轮验证，第 3 轮针对每条流程作出判定。
4. Bug 应提交为 issues，绝不能放进图谱。 图谱是持续更新的架构文档，不是 bug 报告。
5. Kuzu 是必需项，不是可选项。 绝不要悄悄跳过图谱导入。遇到问题要明确报错并修复。

从真实代码重建。查找矛盾。提交有证据支撑的 bug。重复执行。