Codex Atlas · 架构与源码

内置固定版本 Codex 源码的交互架构地图。从系统结构逐层进入实现，查看真实源码及引用。独立学习工具。

启动

用户只需要 Node.js 20+（含 npm）。发布到 npm 后：

npx codex-atlas

自动选择本机空闲端口并打开默认浏览器，按 Ctrl+C 停止。安装后阅读无需网络、Git、Python、Rust 或本地 Codex 仓库；不执行内置源码。首次 npx 从 npm 下载包仍需网络。

npx codex-atlas --port 4180   # 指定端口，已占用时明确报错
npx codex-atlas --no-open     # 只打印地址
npx codex-atlas --version     # 查看工具与源码版本

本地发布候选包也能运行：npx --yes --package ./dist/codex-atlas-0.2.0.tgz codex-atlas。当前打包不等于已经发布，需维护者执行 npm publish 后才可使用公开包名。

内置源码版本

• Atlas：0.2.0。
• Codex：068c49f075cf287a1fe7d1ee36cf005efac922e7，提交日期 2026-08-24。
• 该提交无对应的正式发布标签；源码包清单为 0.0.0-dev，不将其标成 Codex 正式版本号。
• 包含提交的 6,524 个文件及预生成索引，未包含 .git 历史、本机修改或未跟踪文件。精确版本也显示在页面和 --version 中。

源码固定随包发布；更新 Atlas 包才能更新源码与经过复核的架构说明。

浏览

• 全景按包含关系展示接入客户端、服务接入、Core、执行与隔离、持久化、扩展实现和公共支撑。外部模型单独标示。
• 点击框标题或组件进入内部结构；Core 的会话、上下文、工具、模型客户端、扩展接入和配置嵌套在 Core 内。
• 左侧为组件树，展开路径保持一致。灰色关联组件位于当前范围之外，点击后按其原始归属进入对应结构。
• 关键实现关系优先展示；其他 crate 依赖通过“其余依赖与关联”查看，不因布局而删除数据。
• 继续下钻可到真实接口与方法定义，再通过源码依据打开原文。结构视图和“回合流程”分开；流程步骤引用相同组件，不重新定义归属。
• 单文件的实现层采用定义目录与源码同屏阅读：筛选方法，查看签名、原注释和带行号的实现。打开完整源码后返回会保留所选定义。
• ModelClient 的职责分组、重点方法说明和会话关系经过源码核对，并绑定文件哈希；源码版本变化后停用这些归纳。其他实现范围按源码可见性分组。本类型引用只连接唯一匹配的 self.foo / Self::foo 表达式，不代表完整调用图。
• 源码页显示真实组件归属，同时单独保留进入前的图作为返回位置；从原始目录打开时可跳到对应架构。选择符号后高亮行立即可见。搜索优先当前模块及非测试/示例候选。
• 原始源码目录保留全部已跟踪文件。画布可缩放、平移与适应窗口，详情按需展开。

Source of truth

1. 发布快照直接读取 package.json 中固定 commit 的 Git 对象。打包逐文件核对提交原文与索引哈希，版本、覆盖或归纳依据不一致时拒绝打包。开发模式的索引可以来自已跟踪文件的工作区内容。
2. 包身份由 JSON / TOML 解析取得。Rust 路径依赖支持 workspace 继承、重命名、平台条件、可选与开发 / 构建依赖；只有能够映射到仓库内包的依赖产生连线。
3. 架构分组是编辑性阅读视角，规则公开展示在详情中。每组都映射到真实文件；其余文件归入“基础设施与仓库”，不会凭名称生成虚构包。
4. Rust 类型、函数、模块等定义由 Tree-sitter 提取。use 与调用表达式保留实际位置；未执行类型解析、宏展开或 features 求值，因此不生成猜测的调用图。其他语言目前提供文件级浏览。
5. 每个文件保存 SHA-256。打开源码时同时核对前端索引版本和实际内容；不同则返回 409，避免旧行号配新代码。发布快照内的符号链接按提交中的目标解析，不读取用户磁盘。开发模式生成索引时若 HEAD 或清单内容改变则中止。
6. 二进制和大于 2 MB 的文件保留身份与哈希，不显示正文。Rust 解析缺口在文件页和“索引范围与依据”中明确展示。

组件模型在 architecture-model.mjs，记录 107 个归纳实体及结构父级，再从实际语法树提取实现叶子。当前索引生成 99 个可进入的结构范围和 1,653 个实现定义。节点归属、跨范围关系与流程映射均有一致性检查；这些数量不是“人工绘制了 99 张架构图”的声明。

经阅读的依据共有 138 段；Cargo 依赖和语法定义另标为索引提取。架构组件 ID 稳定，语法叶子按当前源码快照定位。相关文件改变后，旧的语义解释标为待复核；更新索引不会自动为旧解释背书。职责模型是对关键实现的归纳，未对每个源文件都编写业务说明，完整文件仍可通过源码目录访问。

commit、日期、覆盖数量和解析提示均取自生成结果。快照不是上游最新版本或运行时轨迹。

开发与打包

只有维护者重建索引时需要 Git、Python 3.11+ 及 web-tree-sitter / tree-sitter-rust。索引器优先使用本项目依赖，其次读取 ATLAS_PARSER_ROOT，最后兼容本机 Understand Anything 的已安装解析器。

CODEX_SOURCE=/absolute/path/to/codex npm run index
npm run dev -- --port 4180  # 工作区模式，保留更新索引
npm test
mkdir -p dist
npm pack --pack-destination dist  # prepack 自动生成、核对并压缩快照
npm run test:package             # 在空目录用 npx 离线启动实际 tgz

更新源码时先调整 package.json 的 codexSource.commit，重建索引，再复核架构依据和实现阅读说明。发布包使用显式文件白名单，不含工作区索引、QA 截图、旧版学习地图或本机配置。打包机制见 npm package.json 文档。

许可

Atlas 应用采用 MIT。内置 Codex 源码遵循上游 Apache-2.0 及各第三方文件原有许可，未被改为 MIT；原始头部、许可和 NOTICE 均保留。可读副本位于 bundle/licenses/，完整原文件字节位于 bundle/sources.json.gz（路径、Git mode 和 Base64 内容）。见 Apache-2.0 再分发条款 及随包 NOTICE。

实现与检查

• scripts/manifests.py：Git 文件集合、清单语义和依赖声明位置。
• source-index.mjs：文件内容校验、Rust AST、模块文件匹配、架构路径分组，生成 data/source-index.json。
• architecture.mjs：流程视图及经审阅的基础依据；architecture-model.mjs：组件目录、归属、关联和结构投影。
• navigation.mjs：从源码位置反查组件归属，独立于进入来源。
• implementation.mjs：实现层定义映射、经核对的阅读说明与同类型显式引用。
• server.mjs：仅监听本机；源码只通过索引白名单和哈希校验读取，拒绝跨仓库链接、外域 Origin 和伪造 Host。
• cli.mjs：npx 入口、空闲端口、默认浏览器启动及版本输出；scripts/build-bundle.mjs：从固定提交生成离线快照。
• atlas.html / atlas.css / atlas.js：原生浏览器交互，无前端运行依赖。
• test/source-index.test.mjs：AST 的注释 / 字符串隔离、继承依赖与条件行号、源码读取 / 搜索 / 变更 / 访问边界检查。
• test/architecture.test.mjs：源码原文、组件树、Core 包含关系、所有主分支可下钻、外部关联和流程引用。

npm test

测试需允许临时监听本机端口。data/ 是开发用本机索引，不应提交或上传；bundle/ 是经校验且去除本机元数据的发布内容，随 npm 包分发。

开发目录的旧版学习地图仍可从 /index.html 访问；这些旧文件未参与新版索引与架构事实生成，也不进入 npm 包。