第 16 章 Rust Atlas

定位：本章讲代码图 provider——查结构而非查文本：构建、查询、新鲜度与 冻结模式。前置依赖：第 8 章的符号语义。基于 agent-spec 1.0.0 （rust-atlas crate 0.1.0）。

为什么不用 grep

Agent 理解代码时反复 grep 是在用文本近似结构。Atlas 用 syn 在 stable 工具链 上把 Rust 源码提取成项目图：模块、类型、trait、impl、调用边——每条边带 provenance（syn / scip / mir），每个分片带源文件 blake3。

agent-spec atlas build --code .            # 构建/增量刷新(逐文件分片+blake3)
agent-spec atlas query spec_verify::Verifier --format json
agent-spec atlas refs Verifier             # 谁引用/调用它
agent-spec atlas impls Verifier            # 哪些 impl 触及该 trait/类型
agent-spec atlas tree --code .             # 确定性模块大纲
agent-spec atlas check --code .            # 新鲜度门:任何分片滞后即非零退出

graph TD
    SRC["src/**.rs"] -->|syn 提取| SH["逐文件分片<br/>nodes+edges+源文件 blake3"]
    SCIP["SCIP 索引(可选)"] -.叠加锐化边.-> SH
    SH --> Q["query/refs/impls/tree"]
    SH --> CK["check:分片 hash × 当前文件 hash"]
    CK -->|滞后| STALE["点名 stale 文件,exit≠0"]
    Q -->|"--frozen"| FR["拒绝静默陈旧答案"]

新鲜度是门，不是提示

分片记录它来自哪个字节状态的源文件。check 在 CI 里把“图落后于代码“变成硬失败； 读命令加 --frozen 则拒绝在陈旧图上给出答案。第 8 章的 atlas-stale 优先语义、 第 14 章 bind 的滞后即失败，根源都在这里：宁可说“我不知道“，不给过期事实。

图的消费者们

• 合同符号验证（第 8 章）：lifecycle 拿新鲜图核对 ### Symbols。
• 代码绑定（第 14 章）：ready 工作单元解析成带图指纹的代码目标。
• 类型化 trace 目标：通过验证的运行把 provider/node/kind/file/provenance/ 图指纹写进 trace 证据。
• MCP：atlas_tree / atlas_query / atlas_refs / atlas_impls / atlas_status 五个只读工具，任何 MCP 客户端“问谁调用了它“得到的是带 provenance 的边， 不是 grep 命中（详见第 17 章）。

增量与自托管

分片只在源文件 hash 变化时重建——大仓库重索引的成本是一个文件而不是全世界。 agent-spec 仓库自托管：写作时 85 个源文件全图零 unparsed。MIR 层（rustc 驱动 的深度事实）是 0.7 弧的 additive 深化，已列入路线图合同。

版本演化说明

本章核心分析基于 rust-atlas 0.1.0。截至 rust-atlas 0.2.0（schema v4）， 本章的构建、查询、新鲜度与冻结模式语义不变，有两处 additive 演化：节点 id 带上了 # 消歧后缀（裸名引用仍可解析）；语法基线之上新增可选的 SCIP 语义 叠加层——atlas scip-gen 调 rust-analyzer 产出 index.scip，叠加 Calls/UsesType 等语义边（provenance=Scip，syn 基线永不改写）。 路线图见仓库 docs/atlas-roadmap.md。