Ontology Atlas

English | 한국어 | 日本語 | 简体中文

当 AI Agent 不断更改代码时，了解你的系统。

将代码的功能及其背后的原因绘制成地图，以 Markdown 形式保存在代码库中
供你和编码 Agent 共同阅读。

下载 macOS 版 · 在浏览器中试用 · 指南

为什么

如今，编码 Agent 修改代码的速度，已经快过团队在脑海中形成完整认知的速度。Atlas 将这幅图景保存在代码旁：每个部分的用途、实现它的文件、各部分之间的依赖关系，以及目前尚无人知晓的内容。你的 Agent 会在执行任务前读取这些信息，并在之后提出更新；你可以通过 Markdown 差异保留、更正或拒绝每项更改。

• 让 Agent 从上下文开始。 Claude Code、Codex、Cursor 和 Antigravity 通过 MCP 读取任务涉及的概念、代码路径、依赖关系和待解决问题。
• 记录由你掌控。 每个概念在 atlas/ 文件夹中对应一个 Markdown 文件，并像代码一样在 Git 中进行版本管理和评审。
• 由你判断哪些内容属实。 Agent 的提议在你接受之前始终只是提议。
• 明确标示未知之处。 地图上的连线表示已声明的关系，并不能证明运行时影响；缺少证据时会显示为未知，绝不会显示为安全。精简的任务交接会保留完整的不确定性说明；如果有所遗漏，则会报告遗漏内容以及检查所需的文档读取操作。初始分析还会排除 Markdown 中的字面示例，并将被截断的文档证据标记为待审查，同时提供与哈希绑定的原始来源后续检查。任务匹配和导航使用作者撰写的证据；代码示例、隐藏注释和引用块不能作为能力声明或工作坐标。

查看效果

项目 — 所有项目及其代码证据覆盖程度。	知识库 — 导入文档，生成带引用的 wiki 页面。
Git — 保存前查看精确的 Markdown 差异。	洞察 — 根据度量数据了解下一步要修复什么，而不是看评分。
Harness — 查看代码仓库为 Agent 提供的指引、限制和监控内容。	自动化 — 让文件夹保持最新的定时检查。

平面地图展示领域标签，能力分支向外延伸并留有间距，依赖关系则以细线标出方向。缩放时，标记大小和细节会根据可用行距逐渐变化。实现元素会在其对应能力旁组成紧凑的分组，并显示易读的名称和归属连线。概览会尽量避免连线交叉；检查端点时，可以查看记录的连接和明确标注的捆绑数量。轻柔的局部曲线和适合屏幕显示的箭头让方向一目了然。在关系审查中，可以查看单条关系的说明及其声明文档。始终显示的亮色轮廓用于突出选中项，琥珀色感叹号表示需要重新检查证据；地图图例会说明这两种标记及方向含义。较大的地图沿用相同的分支规则，同时缩短预览内容并保持列分组稳定。“更多”／“折叠”控件用于显示或隐藏实际能力；聚焦区域沿用相同规则，并提供带标签的返回入口以回到完整地图。“概念”面板将搜索、选择和展开树状结构分开处理。在 1280 px 以下，面板会暂时折叠到检查器旁；检查器关闭后，面板会恢复显示；用户仍可通过显式操作重新打开面板。项目详情会在 检查记录 下保留带日期的来源检查记录。

从其他屏幕返回地图时，空文件夹和没有关系的概念会显示相应的开始操作。创建入门内容时，即使写入失败（包括部分创建），也会保留可持续使用的重试操作。重试会保留现有文件并写入缺失的入门文件；完成后只会显示一条成功通知。弹出式导览已停用。文件夹打开指引、上下文帮助和键盘帮助仍然可用。从概念的完整阅读视图返回时，该概念仍会在地图上保持选中。通过主导航返回时，对于本次会话中同一个已打开的文件夹，会在内存中恢复地图上的选中概念和“概念”搜索内容。普通的未发送聊天文本会在切换屏幕时保留在同一已打开文件夹的内存中；恢复文本不会发送请求。

知识库服务只能在应用中设置：Atlas 会在激活前确认文件夹和钥匙串已保存。浏览器会提供打开应用或“添加文件”的选项，不会收集服务令牌。本地设置不会验证服务访问权限。知识库检查历史会优先列出已执行的检查；可以通过显式显示控件查看记录的休眠间隔。

快速开始

1. 安装：从下载页面安装应用，或打开浏览器版本。
2. 打开文件夹。 Atlas 会直接读取其中的 Markdown 文件，或在你的代码仓库中创建 atlas/ 文件夹，并在写入任何内容前显示路径。
3. 连接你的 Agent。 在 Agents › MCP 中，点击对应工具的 Connect，重启 Agent，然后询问它你的下一个任务。

macOS（Apple Silicon）版本已签名并经过公证，且应用内置 MCP 服务。Windows x64 版本为未签名的 Beta 版。在 Linux 上，请使用浏览器版本，或从源代码检出中运行 CLI 和 MCP 服务 。Releases 列出了各版本的文件和校验和。

工作原理

your-repo/
├── src/
└── atlas/                 ← cloned, branched and reviewed with the code
    ├── project.md
    ├── domains/  capabilities/  elements/
    ├── sources/           documents kept exactly as they arrived
    └── wiki/              pages written from those sources, every fact cited

frontmatter 中包含 kind: 的 Markdown 文件代表一个概念。它的 uid 永不更改，slug 是它当前的地址，path 则指向它所描述的代码。地图、文档、Library、Insights 和 Git 页面都会读取这些文件。

你的 Agent 可通过两种方式访问该文件夹：

• MCP： Agent 会启动 Atlas MCP 服务，该服务可读取和写入磁盘上的文件夹，即使应用已关闭也不例外。连接 Agent · MCP 参考
• ACP： Claude Agent 和 Codex 也可以在应用自带的聊天中运行；每次写入都必须等待你批准。Agent

修复项目源路径时，会打开受影响的概念和记录的相对路径；对于过时或缺失的目标，需要重新测量。

项目检查会区分自上次含义审查后有所更改的文档和格式错误的输入。检查会要求进行审查并明确重新定稿；受支持的代码路径和已保存的更改不会被视为对含义的认可。分析会根据源证据已更改、缺失或未经检查的情况筛选功能，同时保持所选声明处于打开状态。

分析会比较不同职责之间记录的依赖关系，然后在所选声明旁打开对应的确切概念和声明文档。实现记录、未经检查的源和缺失的解释会分别处理。在 macOS 应用中，可以根据各自绑定的 Git 仓库，为文档和引用的文件确定日期；如果访问权限或历史记录缺失，状态会保持未知；选择用于读取的文件夹必须与现有连接相符。分析

本地优先

已安装应用中的 Changes 原型无需本体即可读取选定的 Git 仓库。建议先读取公开的 GitHub PR；仅解释提交仍是明确受限的替代方案。PR 刷新失败时，会保留之前读取的版本和说明，并显示新鲜度警告。明确读取的公开 PR 原文会在本地保留有时限的副本，应用重启后仍可重新打开，并标注其原始读取时间，同时不检查当前 GitHub 状态。即使没有源文件夹，也可以在 Changes 中清除保存的副本。遇到已知的 GitHub 速率限制时，会显示重试时间并暂停读取 PR，但本地来源仍可使用。可选择本地日期范围：每日、每周、每月、每年或自定义；也可在 Atlas 中查看完整提交消息、受影响的文件和有范围限制的代码比较。明确告知的读取序列会读取所有符合条件且已收集的完整记录；会为会话 Stop/Continue 保留已完成的部分，并根据选定的原始段落生成简短概览；来源、处理和概览中的缺漏都会明确标示。它读取当前分支的第一父级历史；作者描述和可选的本体分组不能证明行为变化已得到验证。变更简报

• 无后端、账号或遥测。文件夹在你的磁盘上保持为普通 Markdown。
• 使用你的 API 密钥或本地模型进行模型调用是可选的；每次调用都会在 .ontology-atlas/llm-audit.jsonl 中记录目标位置。
• 已连接的编码 Agent 可能会将你的提示词和它读取的内容发送给其自身的服务提供方；Atlas 的日志不涵盖这些传输。

信任 · 安全

状态

Atlas 尚处于早期阶段。我们的基准测试尚未显示使用 Atlas 能获得更好的答案，而且 Atlas 的速度更慢（更正说明）。 构建试验、失败情况和限制见 构建测量。

文档

Atlas 是什么？ · 前五分钟 · 什么会成为节点？ · 关系 · 规范 · 功能 · CLI · 架构

贡献

请阅读 CONTRIBUTING.md；外部拉取请求来自 fork。 AGENTS.md 是所有参与者（包括 Agent）都应遵守的约定。

pnpm install
pnpm dev
pnpm checks:changed -- --run

pnpm pr:land <number> 会合并经过审查的拉取请求，并保留其原始提交。开发检查是完整的检查门槛参考。

推送前会检查即将推送的提交，并并行运行受影响的 lint、单元测试和 Node 测试，以及相关的轻量检查。CI 负责浏览器、完整契约 和依赖图验证。仅修改 CI 工具测试的改动会运行相应的回归测试，而不会启动无关的产品测试套件；修改规划器 实现的改动仍需通过全面的 CI 检查。

仓库命令

| 命令 | 解答的问题 | |---|---| | `node scripts/ci/run-playwright-ci.mjs --help` | 浏览器分片选项，不会发现或运行测试；未知选项会在执行前导致失败 | | `pnpm agents:check` | 每个执行环境的指令文件均有效；Codex 和 Claude 文件无需保持一致 | | `pnpm brief:new -- --slug= --owns=` | 填写了端口、临时目录、检查项和合并说明的委派简报 | | `pnpm build:static` | `out/` 中的静态导出；仅当上次构建后有构建输入发生变化时才重新构建 | | `pnpm bundle:plan` · `pnpm bundle:prune` | 规划将多个分支合并为一个，然后清理 main 已包含的分支（`/merge`） | | `pnpm checks:changed` | 此次更改需要通过哪些门禁 | | `pnpm conflicts:scan` | 哪些未关闭的拉取请求修改了与此分支相同的文件，以及试合并是否会产生冲突 | | `pnpm decisions:find ` · `pnpm decisions:check` | 应引用或推翻的决策，以及此次更改是否需要记录决策 | | `pnpm design:tokens -- [--prefix=]` | 当前的令牌色阶，解析自 app/styles | | `pnpm doc:new -- --type= --area= --slug=` | 根据 `docs/.templates/` 中的模板创建新的常设文档 | | `pnpm docs:check` | 文档门禁，包括 `pnpm docs:language`、`pnpm source:language`、`pnpm changelog:check`、`pnpm dev-checks:check`、`pnpm docs:meta` | | `pnpm docs:meta` · `pnpm doc:history -- ` | 每份常设文档的类型、状态和领域；单份文档在移动前后的提交记录 | | `pnpm docs:move` | 移动 `docs/.moved.json` 中的文档并重写引用（`-- --check` 仅报告） | | `pnpm e2e:durations -- ` | 根据下载的 `playwright-timings-*` 报告重新平衡浏览器分片 | | `pnpm e2e:sleeps:check` | 如果新增固定的 `waitForTimeout` 却未添加 `// measurement window:` 注释，则拒绝通过 | | `pnpm gates:yield -- --runs=200` | 根据 CI 上传的流水线报告，按运行列出曾经失败过的 CI 检查 | | `pnpm gateway:capture -- --base-url=` | 以韩语和英语重新截取下载页面上的 6 个应用界面 | | `pnpm harness:tokens -- --since=` | 根据本地转录记录，按 Agent 类型查看 Claude Code 令牌的使用去向，以及哪些运行突破了压缩窗口或轮次上限（[预算](docs/engineering/agent-effort.md#token-budget)） | | `pnpm knip` | 未使用的文件、导出项和类型 | | `pnpm licenses:check` · `pnpm notice:build` · `pnpm notice:check` | 已发布的软件包是否在许可证允许列表中，以及 `NOTICE.md` 是否为最新版本（[规则](docs/engineering/third-party-code.md)） | | `pnpm messages:build` · `pnpm messages:check` · `pnpm messages:adopt` | 根据每个命名空间对应的单个文件合成 `messages/.json`，验证其为最新版本，并接续旧分支的编辑内容 | | `pnpm messages:coverage -- --locale ` | 检查一个区域设置的字符串与 `en` 是否一致：参数、复数形式、文字脚本、保留词和排版 | | `pnpm perf:mcp:memory` · `pnpm perf:mcp:memory:check` | MCP 服务在重复调用时是否释放内存；耗时约 1 分钟 | | `pnpm pr:ci ` | 立即在草稿拉取请求上触发 CI | | `pnpm pr:land --plan ` · `pnpm pr:land --conduct` | 试运行合并，或持续合并队列中的拉取请求，直到队列清空 | | `pnpm pr:land ` · `pnpm pr:queue` | 将拉取请求加入合并队列（通过检查的拉取请求会在一次 CI 运行后一起合并），并显示队列 | | `pnpm review:facts -- --base=` | 审查者原本需要手动统计的机械性事实：行数增长、超过 800 行的文件、导出项和依赖项更改、未触及的同级测试、安全路径 | | `pnpm seo:check` | 在 `pnpm build` 后检查：`out/` 中的每个站点地图 URL 均规范化为自身，`/` 和每个区域设置根路径均指向 `/{locale}/download/`，且各区域设置内的标题和描述均不重复 | | `pnpm typecheck` | 检查所有文件中的类型，包括 Next 生成的路由和页面类型 | | `pnpm ui:audit -- --url= --route=` | 按宽度检查渲染结果：水平溢出、被遮挡或无法触及的控件、过小的触控目标、偏离色阶的类型／半径／阴影值、对比度不足、重复集合不一致、滚动末端预留空间 | 使用 `--scope=` 审计一个可见模态框或区域。选择器必须恰好匹配一个可见元素；报告会包含测得的元素数量。

许可证

MIT。第三方声明见 NOTICE.md，完整许可证文本见 public/third-party-licenses.txt。像素吉祥物及其来源说明见 品牌。