contextatlas

快速开始 → · 基准测试结果 → · 为何不用基于图的方法？→ · 架构 → · ADR →

---

ContextAtlas 提供两种效果相同的使用方式——CLI 和 Claude Code Skills—— 两者都会生成相同的 atlas.json。设置方法请参阅快速开始。

问题所在

目前，Claude Code 通过蛮力方式了解你的代码库。每次会话都从头开始。每次询问“X 在哪里？”都会触发多次 grep 调用。每次询问“哪些内容依赖 Y？”都会引发又一轮文件读取。在中型代码库中，回答一个架构问题就可能消耗 40+ 次工具调用和 100,000+ 个 token，Claude 才能获得足够的上下文来进行良好推理。

更糟的是，支配代码的架构意图——ADR、设计决策以及“我们这样做的原因”——对 Claude 来说不可见。OrderProcessor 必须保持幂等这一规则存放在 docs/adr/ 中。当 Claude 提出更改时，它无从得知这项约束的存在。

昨天的理解不会延续到今天。每次对话都从零开始。你的 ADR、提交历史、测试覆盖率——这些信息都不在 Agent 手中。

如果昂贵的理解过程只在索引时发生一次，而每次查询都变成字典查找，会怎样？

这就是 ContextAtlas。

ContextAtlas 是什么

ContextAtlas 是一个 MCP 服务，可为 Claude Code 提供一份精心整理的代码库地图——将 LSP 级别的结构精度与从 ADR、文档和 Git 历史中提取的架构意图相融合，并通过单次调用的上下文包交付给 Claude。

Claude 收到的每个上下文包都会结合关于某个符号的四种独立信号：

1. 结构数据，来自语言服务器——定义、引用、类型、诊断。具备编译器级别的精度。
2. 架构意图，来自 ADR、README 和设计文档——由 Opus 4.7 在索引时提取结构化主张，并关联到特定代码符号。
3. 历史上下文，来自 Git——涉及该符号的近期提交、活跃/冷门指标、共同变更模式。
4. 测试关联——哪些测试引用了该符号，覆盖率位于何处。

一次 MCP 调用即可返回融合后的全部四种信号。你的仓库还没有 ADR？你仍可在一次调用中获取 LSP、Git 和测试信息，而不必调用十五次——这是实实在在的基础改进。添加 ADR 后，上下文包会更加丰富。该架构经过设计，可让任意子集的信号都能发挥价值。

假设某份 ADR 规定 OrderProcessor 必须具备幂等性，调用 get_symbol_context("OrderProcessor") 会返回：

SYM OrderProcessor@src/orders/processor.ts:42 class
  SIG class OrderProcessor extends BaseProcessor<Order>
  INTENT ADR-07 hard "must be idempotent"
    RATIONALE "All order processing must be safely retryable."
  INTENT ADR-12 soft "prefer async base class for new processors"
  REFS 23 [billing:14 admin:9]
    TOP ref:ts:src/billing/charges.ts:88
    TOP ref:ts:src/admin/orders.ts:12
  GIT hot last=2026-03-14
    RECENT "Fix idempotency bug in retry path" a3f2c1d
  TESTS src/orders/processor.test.ts (+11)

当 Claude 被要求修改 OrderProcessor 时，它会在提出更改方案之前看到幂等性约束，而不是等用户审查发现违规之后才看到。

适用人群。 ContextAtlas 面向使用 Claude Code 处理实际代码库的普通开发者，而不只是大型组织中维护 500,000 个文件单体仓库的工程师。节省 Token 的效果会随代码库规模增长——对于 200 个文件的框架，效果显著；对于 30 个文件的库，效果有限。但架构意图的捕获与规模无关。 一个 30 个文件的库也可能包含值得呈现的重要架构决策，而 Claude 遵循这些决策同样重要。

超越 Token：设计对齐案例研究

效率和质量不可或缺，但仅有二者还不够。在非简单代码变更任务中，上下文奠基带来的实质价值体现在设计选择上。

v0.3 开发期间的 A/B 试验。 在两个 ContextAtlas 克隆环境中使用相同的三段式提示词：修复一个已知缺陷——定位缺陷、设计并实现修复、编写测试，并通过 ADR 记录。唯一的环境差异：MCP 是否可用。

组别	MCP	采用的方案
A（原生）	无	先召回方案（匹配范围更广；噪声与项目的精确性主张相冲突）
B（借助 CA）	ContextAtlas	精度优化方案（与项目「预先提取主张并进行结构化归因」的主张一致）

B 组的方案最终合入了主分支。 两组都以相近的实际耗时和 Token 成本修复了缺陷。实质区别在于是否与项目的设计主张对齐——借助 CA 的组可以从地图中读取相关 ADR 和先前的架构工作，并做出符合项目方向的选择。原生组看不到这些上下文，因而选择了一个虽可行、却与架构相悖的方案。

A 组的实质性考量并未丢失——它被记录为未来工作的调查触发条件。召回率与精度之间的权衡得以保留。

完整综合分析见 v0.3 第 3 轮 dogfood 证据。

N=1 的试验；这是轶事，不是基准测试。 系统化基准测试套件（hono / httpx / cobra）衡量效率和质量（见下方 §数据）。这项 A/B 试验衡量的是实质上独立的设计对齐维度——它不适用于基准测试套件的方法（每项代码变更任务都与具体仓库相关），但这是为真实代码库开发的开发者群体提供的实质价值。

数据

我们在三个仓库上将 ContextAtlas 与基线 Claude Code 进行基准测试，这些仓库旨在反映真实的开发者工作负载：

仓库	语言	源文件数	用途
honojs/hono	TypeScript	186	中型框架
encode/httpx	Python	23	专注于生产环境的库
spf13/cobra	Go	19	CLI 框架

方法。 每个仓库 24 个提示词，分为 6 个任务类别，盲法人工评分，预先注册评分标准，不挑选有利结果。完整方法见 RUBRIC.md。

效率：架构类提示词的工具调用减少 50-71%

hono 上的 Phase 5 参考运行，使用六个预先注册的提示词：

提示词	类别	Alpha 调用数	CA 调用数	Δ	Alpha $	CA $
h1-context-runtime	胜出	18	9	−50%	$2.36	$1.52
h2-router-contract	胜出	11	5	−55%	$0.60	$0.53
h3-middleware-onion	胜出	5	5	0%	$0.38	$0.47
h4-validator-typeflow	胜出	21	6	−71%	$2.95	$0.52
h5-hono-generics	平局	11	13	+18%	$0.79	$1.17
h6-fetch-signature	陷阱	3	4	+33%	$0.17	$0.29
合计		69	42	−39%	$7.25	$4.50 (−38%)

最突出的案例：h4-validator-typeflow 的运行成本低 7.3×（$2.95 → $0.52）， 而答案深度相当。CA 会按编号打开起主导作用的 ADR； 基线则从源代码重建架构。在平局和陷阱类别（h5、h6）中，结果显示 CA 净表现较差，正如评分标准所预测——对于架构意图无关紧要的问题，CA 会过度设计。按类别区分的方法能揭示这些预期情况，而不是将它们掩盖起来。

跨语言复现：同样的架构意图优势机制也适用于 Python（Phase 6 — httpx） 和 Go（Phase 7 — cobra）。 Phase 8 使用锁定的提示词集合，对 v0.3 强化版图谱在相同固定目标 SHA 上重新运行：在所有三种目标语言的架构意图提示词中，令牌数减少 45-72%。完整综合分析见 phase-8-v0.3-reference-run.md。

质量：盲法评分、配对 t 检验及置信区间

v0.5 采用配对模式匿名化方式交付了 LLM 评审方法（依据 ADR-19）。跨单元汇总的配对 t 检验，每个维度有 N=27 个差值（5 个锚点单元 × 每组 n=5 次试验 × 2 个条件；hono h1 自动扩展至 n=8）：

质量维度	平均 Δ（0-3 分制）	95% CI	级别
事实正确性	+0.370	[0.176, 0.565]	明确
幻觉	+0.296	[0.032, 0.561]	临界
可执行性	+0.148	[0.005, 0.291]	临界
完整性	+0.037	[-0.039, 0.113]	无法区分

阈值预先注册： 三档划分（≥0.05 为明确； 0.001-0.05 为临界；≤0 为无法区分）在计算精确值前就已锁定。数据产生后没有移动目标。76% 的平局率证实匿名化有效——在四分之三的比较中，评审无法分辨哪一项对应哪个条件。

各维度的完整数值及 9 项具体发现见 Phase-9 参考文档。 诚实的方法局限记录于下文的§方法与诚实局限。

ContextAtlas 与替代方案的比较

我们对 ContextAtlas 是什么、相对于相邻工具又不是什么，做了几项有意的界定：

与基于图的代码智能工具（Graphify 等）比较。 我们属于同一类别——两者都通过 MCP 为 LLM Agent 构建代码库的预计算索引。这确实存在类别重叠，我们希望坦诚说明。我们的不同之处：

• 以 LSP 为依据，而非通过启发式提取。 ContextAtlas 将所有结构性问题交由语言服务器（tsserver、Pyright、gopls、ruby-lsp、csharp-ls）处理。Graphify 则通过解析和提取来推导结构。
• 预组合的信息包，而非图原语。 ContextAtlas 的 MCP 工具在一次调用中返回融合的信息包。Graphify 则提供图操作（graph_query、get_neighbors、shortest_path），由调用方组合使用。
• 范围较窄，而非范围广泛。 ContextAtlas 为代码、散文和 git 建立索引。Graphify 则会导入文档、图表、研究论文等内容。
• 以声明为先，而非以图为先。 ContextAtlas 存储带严重程度标签的离散声明，针对“哪些约束适用于此符号？”进行优化。Graphify 将世界建模为节点和边，针对“什么与此节点相连？”进行优化。

对于特定工作负载，我们的选择是否能带来更好的结果，这是一个需要实证回答的问题。请参阅上面的数据。

与会话记忆工具（claude-mem、engram、anamnesis）比较。 这些工具会捕获累积的会话历史——Claude 在过去的对话中学到了什么或做了什么。ContextAtlas 则提供从你的代码、ADR 和文档中提取的静态架构事实。两者的信息来源不同，偶尔会有重叠（例如会话讨论形成 ADR 或提交时），但要解决的问题本质上不同。会话记忆工具也无法真正提交到仓库；ContextAtlas 的图谱则可以。

与 MCP 中的 LSP（LSP-AI 等）比较。 ContextAtlas 使用 LSP 作为结构事实的来源。如果你只需要 MCP 中的 LSP，这些项目已经很好地解决了这个问题。ContextAtlas 则在此基础上叠加架构意图和 git 历史记录。

与基于嵌入的搜索比较。 我们评估过这种方案，最终选择了以符号为键的声明。嵌入结果模糊，而 LSP 符号精确。基于嵌入的排序属于 MVP 之后的增强功能，是否纳入取决于基准测试是否证明它有帮助——完整理由请参阅 ADR-09。

已提交 atlas 模式

ContextAtlas 会生成一个可提交的团队资产——atlas.json—— 与代码和 ADR 一同保存在代码库中。这正是 ContextAtlas 从个人效率工具转变为团队资产的关键。

• **新团队成员克隆代码库：**他们会和其他内容一起拉取 atlas.json。 首次运行时，ContextAtlas 会将已提交的 atlas 直接导入本地缓存——无需调用提取 API，也无需等待 10 分钟。打开 Claude Code 后即可开始工作。
• **贡献者提交 PR：**如果代码变更影响架构声明，他们会在提交中一并重新生成 atlas.json。审核者可以在 PR 中同时查看代码变更和 atlas 差异。
• **开发者在不同设备间切换：**atlas 状态受版本控制，而不是困在某台笔记本电脑上。
• **离开项目几个月后再回来：**拉取最新的 main，atlas 就会反映团队在你离开期间完成的所有工作。 只有上次拉取后发生变更的文件需要增量重新索引。
• **开源项目：**普通贡献者无需承担任何设置成本，就能立即受益。项目积累的架构知识会自动传递给他们。

对于无法提交 atlas 的团队，可在配置中设置 atlas.committed: false。 每位开发者自行运行提取。团队资产的优势将不复存在，但 ContextAtlas 仍可作为个人工具使用。

这种模式——已提交的团队资产搭配用于提升查询性能的本地缓存——与会话记忆工具和知识图谱工具有本质区别。详见 ADR-06。

架构

                INDEX TIME (once per source change)
                ──────────────────────────────────────
                ADRs ──────────┐
                Docstrings ────┤
                Git commits ───┼──► Opus 4.7 extraction
                LSP symbols ───┘              │
                                              ▼
                              atlas.json (committed to repo)
                                              │
                                              ▼
                              SQLite + FTS5 BM25 (local cache)

                QUERY TIME (every Claude call, zero API)
                ──────────────────────────────────────
                Claude Code:  get_symbol_context("X")
                                              │
                                              ▼
                              One fused bundle, sub-100ms
                              (LSP refs + intent + git + tests)

五层各司其职：

1. **MCP 接口。**向 Claude 提供 get_symbol_context、find_by_intent 和 impact_of_change 工具。
2. **查询融合。**按查询组合各信号源的结果。
3. **信号源。**LSP（通过 tsserver/Pyright/gopls/ruby-lsp/csharp-ls）、 意图注册表（来自 SQLite）、git、测试。
4. **提取流水线。**Opus 4.7 阅读说明性文档，并输出以符号为键的结构化声明。
5. **存储。**SQLite 索引，以 SHA 为键进行增量重新索引。

查询时的信号融合本质上是一种低成本查找： 当 Claude 调用 get_symbol_context("OrderProcessor") 时，MCP 处理程序会通过 LSP 获取实时结构事实（定义、 引用、类型），再从 SQLite 读取该符号预先提取的意图声明，并结合 git 热度和测试结果。返回给 Claude 的信息包是组合而成，而非计算得出——实质性的关联在索引时就已完成。这与基于图的替代方案有本质区别：后者暴露的是原语（get_neighbors、shortest_path），由调用方在查询时进行组合。

架构承诺：昂贵的理解只在索引时进行一次；查询是本地字典查找，不产生 API 调用。 这让成本、延迟和不确定性都受到约束——这是一项严格不变的保证，而非优化手段。

完整设计见 DESIGN.md。

数据流与隐私

ContextAtlas 会和不会将哪些数据发送到你的设备之外：

仅在索引时发送到 Anthropic 的 API：

• .contextatlas.yml 中 adrs.path 和 docs.include 匹配的每个文件的完整文本：默认包括 ADR、README 和其他 Markdown 文档。如果 docs.include glob 匹配源文件（例如，docs/** 匹配 docs/examples/*.ts），则会发送这些文件的完整内容，包括代码；请缩小 glob 的匹配范围，仅包含文档文件，以避免这种情况
• 源文件中导出符号的文档字符串文本（仅注释文本，不含代码），每个请求处理一个符号
• 通过提交筛选条件的提交消息（主题和正文，不含差异），每个请求处理一个提交
• 每个源只会在发生变更时发送一次：首次索引时，以及对已更改文件和新提交进行增量重新索引时。每个提交只会发送一次。
• contextatlas index 默认会发送这三类内容（v1.2+）。在 .contextatlas.yml 中设置 extraction.streams: [adr]，即可仅发送 ADR 和文档。/index-atlas Skill 会在 Claude Code 会话中以相同方式处理 ADR、文档字符串和提交消息；它不会提取 docs.include 页面。
• contextatlas generate-adrs（CLI）发送的是结构清单：源文件路径，以及语言服务器为每个文件列出的符号名称（顶层声明，以及类、接口和命名空间成员，无论是否导出），还会逐字发送 README.md、DESIGN.md 和 CLAUDE.md，以及任何 --reference-context 文档。

绝不会发送到任何地方：

• 你的源代码，但上面提到的文档字符串文本和 docs.include glob 匹配的任何源文件（会按上述方式发送完整内容）除外
• 你的 git 历史记录，但上面提到的经筛选的提交消息除外
• LSP 引用和类型数据
• 运行时查询内容

仅本地存储：

• 提取的声明数据库（默认为 .contextatlas/index.db）
• 所有运行时查询解析都基于此本地 SQLite 文件进行

在查询时——也就是 Claude 在工作过程中进行的每次 get_symbol_context 调用——ContextAtlas 都会执行本地 SQLite 查询和本地 LSP 调用。不会产生网络流量，也不会调用模型。正常使用时，你的代码绝不会离开你的设备。

索引时提取会按照标准 API 条款使用 Anthropic API。如果你的 ADR、文档字符串或提交消息包含敏感的架构决策，这些内容会像任何其他提交到 API 的内容一样，按照这些条款进行处理。

三种工具

这三种 MCP 工具并非三个并行的功能，而是一个融合的上下文基底，提供三种访问方式。

get_symbol_context — 基础工具。“我知道这个符号；把相关信息都给我。”单次调用即可返回完整的融合信息包（签名、ADR 声明、引用、git 活跃度、测试和类型）。多符号模式每次请求最多可处理 10 个符号（根据 ADR-15）。

find_by_intent — 语义查询组合工具。“我不知道符号；按它的功能帮我查找。”使用本地 SQLite FTS5 根据已索引的声明文本进行 BM25 排序——无需嵌入服务或外部调用，结果确定（根据 ADR-09）。

impact_of_change — 影响范围组合工具。“我正要改这个；会有什么东西出问题？”在基础工具的基础上，增加 git 联合变更模式和测试影响。

刷新可发现性

ContextAtlas atlas 是一次构建、在代码或 ADR 发生变更后刷新即可的底层基础。每条 cohort 路径只有一个规范入口；具体行为会根据底层基础的状态调整：

	CLI	Skills
冷启动	contextatlas index（完整提取）	/index-atlas（完整提取）
刷新	contextatlas index（第 4 阶段 SHA 差异增量处理）	/index-atlas（支持刷新的工作流）

根据 ADR-12，SHA 差异增量刷新所需的工作量实质上远低于冷启动搭建。未发生变化的 ADR 和文档字符串源会跳过，已提取过的提交不会再次提取；只有变更过的源会重新提取。自 v1.2 起，CLI index 与 Skill 一样涵盖全部三个数据流（ADR/文档、文档字符串、提交消息）；详见配置中的 extraction.streams。

快速开始

**状态：**v0.9.0 已于 2026-05-16 发布。v1.0 公共发布所需的底层基础已完成。软件包尚未发布到 npm；下方安装说明描述的是预期形式。

运行时要求：

• Node.js 20 或更高版本。
• 为配置的每种语言安装一个语言服务器：
  • TypeScript — typescript-language-server（声明为对等依赖而非直接依赖，因此版本由你控制）。请与 ContextAtlas 一起安装（例如 npm i -D typescript-language-server typescript@6）；支持 4 到 6 版。TypeScript 7 原生移植版不包含 tsserver.js，因此 typescript-language-server 无法在其上运行。请在仓库中使用 TypeScript 5 或 6。
  • Python — PATH 上的 Pyright（也是对等依赖）。
  • Go — PATH 上的 gopls（通过 go install golang.org/x/tools/gopls@latest 安装）。
  • Ruby — ruby-lsp 0.26.x。推荐通过项目 Gemfile 使用 Bundler 安装（在 group :development 下添加 gem 'ruby-lsp', '~> 0.26.0', require: false）。Rails 项目也可以安装 ruby-lsp-rails 0.4.x。要求 Ruby 3.3 及更高版本（推荐 4.0 及更高版本）。
  • C# / .NET — PATH 上的 csharp-ls 0.24.x（Roslyn LSP 封装）。通过 dotnet tool install --global csharp-ls 安装。最低要求 .NET SDK 8（推荐 10 及更高版本；与 cohort 后端固定版本一致）。在 Windows 上，%USERPROFILE%\.dotnet\tools 目录必须位于 PATH 中 — 对于 SDK 安装程序仅配置 PowerShell 的情况，适配器会自动为 Bash/Git-Bash 扩充 PATH。

路径 A — Claude Code Skills（60 秒，无需 API 密钥）

npm install -g contextatlas
contextatlas init

然后在 Claude Code 中：

/generate-adrs   # Skip if you already have ADRs (any path; see Using existing ADRs below)
/index-atlas     # Build the atlas
/prime-atlas     # Verify connection (once per session)

路径 B — CLI（90 秒，需要 API 密钥）

npm install -g contextatlas
export ANTHROPIC_API_KEY=sk-...
contextatlas init
contextatlas generate-adrs   # Skip if you already have ADRs (any path; see Using existing ADRs below)
contextatlas index
contextatlas doctor          # Verify health

使用现有 ADR 和文档

ContextAtlas 会从你已有的 ADR 和文档中提取架构意图 — generate-adrs 适用于尚无 ADR 底层基础的仓库。

• **现有 ADR 位于 docs/adr/？**跳过 generate-adrs；ContextAtlas 会自动提取现有 ADR。
• **ADR 位于其他路径？**在 .contextatlas.yml 中设置 adrs.path（默认值：docs/adr/）。
• **README、设计文档或其他文本资料？**ContextAtlas 也会通过 docs.include 提取这些内容（默认值：README.md + docs/**/*.md）。添加自定义路径即可提取其他文档内容。

提取流水线会从配置指定的任何文本源中生成结构化声明 — 现有底层基础不会被闲置。完整架构请参阅下文的配置。

保持 Atlas 更新

contextatlas hooks install      # once per clone (init offers it; --yes accepts)
contextatlas hooks status       # hooks, run in progress, pending sources, last run
contextatlas index --structural # by hand: refresh symbols + git signal, no model calls
contextatlas index              # extract the pending sources (paid; preview first)
contextatlas refresh-claims     # or extract them on your Claude subscription (Tier 1)

每次提交、合并和切换分支后，钩子都会在后台运行 contextatlas index --structural --no-export。这样无需调用模型，也不会修改 atlas.json，就能让本地缓存中的符号、行号和 Git 信号保持最新。发生更改的源会列在 .contextatlas/local/pending.json 中（不会提交），直到调用模型的 index 提取这些源。运行中的 MCP 服务会立即提供刷新的缓存，并在拉取或运行 index 更改 atlas.json（atlas.committed: true）时自行重新加载。

第 1 层（声明，使用你的订阅）。 推送前钩子会在后台启动 contextatlas refresh-claims --if-due。有待处理的源时，它会通过无头 Claude Code（claude -p，仅限订阅登录；如果运行会产生 API 密钥费用，则会停止）运行 /refresh-atlas 技能。每次最多重新提取 refresh.max_sources_per_run 个待处理源。不会重新提取那些更改后所有文档字符串都保持不变的源。自动运行会遵循 refresh.min_interval_minutes 和 refresh.max_utilization（上次运行时看到的订阅用量）。将 refresh.auto_claims: false 设为 false 可关闭自动运行。每次运行都会记录在 .contextatlas/local/refresh-log.jsonl 中。若要按计划运行，而不是在推送时运行，或同时采用两种方式：

# cron (Linux/macOS): nightly at 02:30
30 2 * * * cd /path/to/repo && contextatlas refresh-claims --if-due

# Windows Task Scheduler
schtasks /Create /SC DAILY /ST 02:30 /TN "ContextAtlas refresh" ^
  /TR "cmd /c cd /d C:\path\to\repo && contextatlas refresh-claims --if-due"

MCP 服务注册

在 Claude Code 设置中将 ContextAtlas 配置为 MCP 服务。根据 contextatlas 是否位于 PATH 中进行选择：

选项 A — PATH 中的全局二进制文件（例如，通过 npm install -g 或 npm link 安装）：

{
  "mcpServers": {
    "contextatlas": {
      "command": "contextatlas"
    }
  }
}

选项 B — 直接调用 dist（无需全局安装）：

{
  "mcpServers": {
    "contextatlas": {
      "command": "node",
      "args": ["/absolute/path/to/contextatlas/dist/index.js"]
    }
  }
}

首次运行行为

• 如果 atlas.json 已提交（队友已先行运行，或该文件随代码库一同提供），ContextAtlas 会立即导入，无需调用 API。几秒内即可就绪。
• 如果尚无 Atlas，ContextAtlas 会运行完整提取。根据 ADR 的数量和大小，这需要 1-10 分钟，并会消耗几美元的 Opus API 额度（CLI 路径）或会话令牌（Skills 路径）。生成的 atlas.json 可以提交，以便后续贡献者跳过此步骤。
• 文档字符串和提交会增加首次运行的工作量（v1.2+）。 CLI index 还会针对每个带文档的导出符号和每个通过筛选的提交各调用一次 API。首次调用前，它会将估算值输出到 stderr：每个流的调用次数和输入令牌数，以及费用范围。在此代码库首次运行三个流时（在提交 9d2bf4c 处规划，未调用 API），预计进行 479 次调用（13 个 ADR/文档文件、461 个文档字符串、5 次提交），估算费用为 $4.42 到 $10.35。 extraction.streams: [adr] 可将提取范围限制为 ADR 和文档，而 --budget-warn <usd> 会在运行费用超过阈值时发出警告。
• 费用预测说明。 在 v1.2 之前，本说明称平台计费的实际费用通常比脚本报告的费用低约 3 倍，这是因为提示词缓存折扣（v0.4：cobra $5.44 → $1.82，httpx $5.53 → $1.85，hono $10.89 → $3.65）。这种解释很可能是错误的。v0.4 脚本使用了过时的每百万令牌 $15/$75 价格，正好是实际 $5/$25 的 3 倍（已在 v0.6 更正），而提取请求不会使用提示词缓存。预计按 $5/$25 计算的 cost_usd 会与实际账单相符；不要将其或预览中的费用范围打 3 折。
• 后续运行时，只会重新处理自上次索引以来 SHA 已更改的文件。通常只需几秒。

配置

在代码库根目录创建 .contextatlas.yml：

version: 1
languages:
  - typescript
  - python
  - go
  - ruby
  - csharp
adrs:
  path: docs/adr/
  format: markdown-frontmatter
docs:
  include:
    - README.md
    - docs/**/*.md
git:
  recent_commits: 5
atlas:
  committed: true    # default; commits atlas.json to your repo
# extraction:
#   streams: [adr]   # CLI `index`: ADRs/docs only. Default: all three
#                    # (adr, docstring, commit). Must include adr.

完整参考：DESIGN.md 中的配置架构。

方法论与诚实的局限

明确说明我们不声称什么，才能建立可信度。

统计方法。 所有质量测量均采用配对 t 检验，并给出 95% 置信区间——不报告 p 值。n=5 时，NHST 在统计学上毫无意义；置信区间则能保留效应量的可见性。阈值预注册严格照原文执行（在计算精确值之前，已锁定选项 α 的严格三级框架）。

单评审模型。 v0.5 质量测量以 Sonnet 4.6 为评审模型，各维度的评审者内部一致性 ≥80%（第 1 轮与第 2 轮相比）。跨厂商评审小组的验证工作将在 v1.0 之后进行。

三个基准仓库。 所有定量结论的范围仅限于 hono（TypeScript，186 个文件）、httpx（Python，23 个文件）和 cobra（Go，19 个文件），以及我们自己的内部使用项目。超出这些范围的泛化将在发布后的样本群体工作中进行。

v0.5 基础范围。 质量维度测量涵盖 5 个锚点单元格 × n≥5 次试验 × 2 种条件（hono h1 自动扩展至 n=8）；并非完整矩阵复现。矩阵补全验证将在 v1.0 之后进行。

v0.6 跨周期复现注意事项。 v0.6 中针对矩阵复现的子集（8 个单元格 × n=5）显示，与 v0.5 锚点单元格相比，4 个质量维度中的 2 个出现衰减（factual_correctness 从 CLEAN→BORDERLINE；actionability 从 BORDERLINE→NOT distinguishable）。根本原因是：v0.5 的测量针对的是较早版本的 atlas，而跨周期方法未对 atlas 基础版本进行控制。完整的因果调查推迟至发布后进行。详情见第 10 阶段参考文档。

v0.3 单次运行方法。 第 8 阶段报告每个单元格 n=1；盲评质量维度测量是在 v0.5 中加入的。第 8 阶段对 Beta 与 Beta+CA 的报告附有 atlas 文件可见性注意事项（偏差方向偏保守——CA 的实际贡献可能大于已发布数据所显示的结果）。

内部使用不等于测量过的基准测试。 在整个开发过程中，ContextAtlas 都会索引自身的 ADR，并在开发 ContextAtlas 时供 Claude Code 使用。这是一种开发实践，不属于四条件矩阵——该矩阵仅针对三个外部目标运行。

有利与不利结果均予以发布。 第 7 阶段关于跨工具链不对称性的假设在 v0.3 基础上被证伪。v0.6 中 atlas 基础版本的混杂因素已被揭示并披露。平局和陷阱类别经常显示 CA 净负面；我们会直接报告，而不会将其隐藏。

状态与路线图

当前版本： v0.9.0（2026-05-16 发布）。v1.0 公开发布基础工作 已完成；发布执行工作将纳入 v1.0.0，不会单独发布 v0.9.1 标签。

近期周期亮点（各周期的完整范围见 docs/release-history.md）：

• v0.9（5 月 16 日）： 发布 Ruby 适配器——通过 ruby-lsp + ruby-lsp-rails 支持 第四种语言，遵循 ADR-21。仓库发布基础工作 （MIT 许可证 + 社区基础建设 + 周期文档迁移至 docs/cycles/v0_X/）。发布定位工作正在进行。
• v0.8（5 月 14 日）： 基础等效性 + 路径可比性 + BM25 启用。在 hono/httpx/cobra 基准测试中，技能基础与 CLI 的 声明比例达到 65-83%，完成了两者的对等性。
• v0.7（5 月 12 日）： 承载发布的周期——由入口点决定的 架构（根据 ADR-02 毕业流程实现 CLI/技能等效性）+ generate-adrs 功能，并通过 validate-adrs 强制执行规范的深度下限。
• v0.6（5 月 9 日）： 流水线机制 + 定向矩阵复现 子集（8 个单元格 × n=5 × 2 种条件）。发现 F1 PRIMARY atlas-substrate- version 混杂因素；完整的因果调查推迟至 发布后进行。
• v0.5（5 月 4 日）： 质量方法周期——LLM 评审框架 + 根据 ADR-19 进行成对模式匿名化 + 成对 t 检验统计 基础组件（ADR-19 §4 修订）。V1.0 发布门槛条件 #1 括号内的事项已解决。
• v0.4（4 月 29 日）： 基础加固——通过两个就绪信号提升 LSP 计时竞争的稳健性（ADR-18）+ 成本预测 免责声明 + Dogfood 基础 + doctor 诊断脚本。
• v0.3（4 月 28 日）： Atlas 精度周期——缩小归因范围
  • 根据 ADR-15 支持多符号 API + atlas schema v1.3，包含 contextatlas_commit_sha + Phase 8 跨目标验证 （范围为 45-72%）。
• v0.2（4 月 25 日）： 三语言基线——通过 gopls 支持 Go 适配器（ADR-14）+ 跨语言 cobra/httpx 参考运行。
• v0.1（初始 MVP）： 三个 MCP 工具 + TS/Python 适配器 + Opus 4.7 提取流水线 + SQLite 增量重建索引 + Phase 5 hono 参考运行（架构优势提示词中的工具调用减少 50-71%）。

路线图（v1.0 之后）：

• 使用已延续的招募基础设施执行队列曝光（v1.0 发布门槛条件 #3）
• 完成完整基准测试矩阵 + 跨厂商评审小组
• 为 find_by_intent 添加语义嵌入层（以证据为准）
• 任务定向的捆绑查询：why_does_this_fail、 onboard_to_feature、audit_change
• 根据需求添加语言适配器：Rust、Java、Kotlin
• 支持非 Markdown 意图源：RST、AsciiDoc

里程碑进程和各周期范围的详情见： ROADMAP.md、docs/cycles/、 docs/release-history.md 和 research/v1.1-candidates.md。

语言支持

语言适配器接口是稳定的插件扩展面——每种新语言都能以增量方式 贡献，而无需修改核心。贡献者入门指南请参阅 docs/language-adapter-guide.md。

语言	适配器	LSP 服务端	发布版本
TypeScript	TypeScriptAdapter	typescript-language-server	v0.1
Python	PyrightAdapter	Pyright	v0.1
Go	GoAdapter	gopls	v0.2
Ruby	RubyAdapter	ruby-lsp（+ ruby-lsp-rails）	v0.9
C# / .NET	CsharpAdapter	csharp-ls（Roslyn）	v1.1

贡献

ContextAtlas 采用 MIT 许可证，欢迎大家贡献。以下领域的贡献尤为宝贵：

• 新增语言适配器。 LanguageAdapter 接口精简且稳定。为 Java、.NET、Rust、Kotlin 或其他语言添加支持，是一个独立的项目。请参阅 docs/language-adapter-guide.md。
• 非 Markdown 的意图来源。 目前我们支持带 YAML frontmatter 的 Markdown ADR。欢迎支持 RST、AsciiDoc 和其他格式。
• 基准测试仓库。 在更多代码库上增加基准测试覆盖范围，有助于增强评估效果。

基准测试与方法论

基准测试与方法论位于单独的仓库中： github.com/traviswye/ContextAtlas-benchmarks。 该仓库包含测试框架代码、锁定的提示词集、已发布的测量结果，以及完整的方法论文档（RUBRIC.md）。将测试框架放在本仓库之外，可以确保基准测试衡量的是已发布的 contextatlas 软件包的实际行为，而非内部 monorepo 构建版本。

致谢

在 “Build anything with Opus 4.7” 黑客松期间构建。

ContextAtlas 使用：

• Claude Opus 4.7 提取索引时意图
• typescript-language-server 解析 TypeScript 符号
• Pyright 解析 Python 符号
• gopls 解析 Go 符号
• ruby-lsp 解析 Ruby 符号
• csharp-ls 解析 C# / .NET 符号（Roslyn LSP 封装器）
• better-sqlite3 作为索引存储
• @modelcontextprotocol/server（MCP TypeScript SDK v2）实现 MCP 服务

许可证

MIT。请参阅 LICENSE。