Atlas 新手教程

01这是什么

一句话：Atlas 是编程智能体的源代码管理器（source control for coding agents）——它管的不是代码，是「产生代码的过程」。

你打开一个项目文件夹，在里面跑 Claude Code、Codex、Atlas 自带的 agent，或者任何符合 ACP（Agent Client Protocol）协议的 agent。agent 每一次提交都会变成一个检查点（checkpoint），并反向链接回产生它的那次会话——提示词、工具调用、它改过哪些文件，全部绑在一起。

它明确不做什么

新手最容易误解的地方，往往不是「它能干什么」，而是「它是不是又一个 X」。先把边界划清：

02为什么需要它

先看你今天是怎么凑合的——如果下面三条你一条都没中，那 Atlas 可能真的不是给你用的。

三个常见的失败 workaround

核心洞察

把这三条串起来看，会发现它们是同一个缺口的不同表现：agent 的产物（代码）已经有版本控制了，agent 的过程（提示词、工具调用、推理、失败）没有。

Atlas 的做法是给「过程」补上这一层，然后让两边在「提交」这个点上咬合起来。它有三条不变量，理解了这三条，后面所有功能你都能自己推出来：

03核心概念与流程

三个动作就能走完一圈：打开项目、跑一个会话、看检查点。

先认词

官方文档把每个术语只在「概念」页定义一次，别处一律链接过去。这里把你会立刻用到的挑出来：

主流程

下面这条链路是 Atlas 唯一真正重要的东西。注意最后一步：检查点不是一个静态记录，你可以直接跟它对话。

04安装：两条路

先想清楚你要干什么：只是想用，还是想改代码。这决定了走哪条路，也决定了要不要装 Bun 和 Rust。

源码构建：最短路径

干净克隆就能跑起来，不需要 API key，不需要 .env，不需要账号。

git clone https://github.com/pacifio/atlas
cd atlas
bun install
bun run dev:app

容易混淆的两条命令

这是这个项目里新手最容易踩的第一个坑：

# Debian / Ubuntu / Linux Mint:
sudo apt install -y libglib2.0-dev libgtk-3-dev libwebkit2gtk-4.1-dev

# Fedora / RHEL:
sudo dnf install glib2-devel gtk3-devel webkit2gtk4.1-devel

# Arch Linux / Manjaro:
sudo pacman -S glib2 gtk3 webkit2gtk-4.1

# openSUSE:
sudo zypper install glib2-devel gtk3-devel webkit2gtk3-devel

生产构建有两个目标：bun run build:app 出 .app 包，bun run build:app:dmg 再加一层 dmg 安装器。

05环境自检与 agent 选择

装完了先别急着发消息。跑四条命令，把「环境问题」和「应用问题」提前分开。

bun --version        # 期望：1.x
rustc --version      # 期望：stable，例如 1.8x
xcode-select -p      # 期望：打印 CommandLineTools 路径，而不是报错
which claude         # 只有你要用 Claude Code 才需要

最关键的一个认知分歧点

Atlas 里有两种 agent，它们在「谁负责装、在哪运行」上完全不同。这是读官方文档时最容易被跳过、但实际最影响体验的一节。

依赖总表

06第一次实战：跑通检查点

官方说得很干脆：没有安装向导，你打开一个文件夹，就在工作了。从打开文件夹到看见第一个检查点，按顺序走一遍。

第 1 步 · 打开项目

按 ⌘O，或者点 Open Folder，挑一个磁盘上的文件夹。这个文件夹就成了一个项目，Atlas 不会先问你任何配置——没有提示、没有信任对话框。

下次启动时，它会出现在欢迎界面的最近项目列表里。

第 2 步 · 选 agent

Atlas 打开时停在一个聊天面板上。点输入框里的 agent 图标可以切换，或者直接按 ⌥/ 循环切换，不用碰鼠标。

第 3 步 · 跑一个会话

发一条消息。这次对话就是一个会话，会被记录，之后能从同一个面板恢复。

当 agent 改了文件并提交时，你不需要做任何事来保留这次提交背后的上下文——Atlas 会自动把提交链接回产生它的会话。这是整个产品存在的理由，所以它必须自动。

第 4 步 · 看见检查点

那个链接就是检查点。打开 Git 面板选中那个提交，你会看到 "Produced by 1 session"，点一下就会跳回时间线里的那次会话。

时间线头部还有一个「Recent Checkpoints」列表，可以直接搜索。

如果想先跑一下源码版

git clone https://github.com/pacifio/atlas
cd atlas
bun install
bun run dev:app      # 首次 Rust 编译几分钟，之后秒级

提交之前想先检查一遍的话，这几个命令是你最常用的：

bun run lint              # oxlint on src/
bun run format:check      # oxfmt --check on src/
bun run typecheck         # 前端类型检查（含测试代码）
bun run test              # 前端与跨层测试
bun run test:rust         # 每个 Rust crate + src-tauri --lib
cargo check --workspace   # 全工作区的 Rust 类型检查

07产物结构：.atlas/ 里到底存了什么

这一节值得慢慢看。Atlas 对「你的数据归你」这件事的态度，全写在这个目录结构里。

<你的项目>/.atlas/
├── sessions.db            检查点 / 时间线记录（SQLite）+ blobs/
├── knowledge/             markdown 笔记，可以有子目录
├── shared-memory/         跨 agent 的记忆事实
├── memory/                设备端 RAG 索引（atlas-memory）
├── codebase-index/        atlas-codeindex 的输出
├── repos/                 通过 GitHub 面板克隆下来的仓库
├── skills/, agent-skills/ SKILL.md 文件
├── packs/                 已安装的包
├── plans/                 计划文档
├── screenshots/, canvas-media/
├── logs.jsonl             项目级活动日志
├── interactions.jsonl     知识库交互历史
├── canvas.json            ReactFlow 的节点/边状态（Canvas / Spaces）
├── editor-state.json      打开的标签页 + 分栏布局
├── project.json           项目级设置
├── recent-files.json      最近文件列表
└── git-status-cache.json  缓存的 git status

三个层级，别混

设计原则：只有一样东西被锁进专有格式

README 承诺「Nothing is locked in」，落实下来是这样的：

08怎么用：@ 提及、斜杠命令、快捷键

Atlas 的设计目标是「让一次会话整个发生在应用里」。所以它的键盘密度很高——学会这几个，你会明显少用鼠标。

@ 提及：本地解析，不塞全文

在任何输入框里打 @，就能把某样东西拉进上下文。可提及的类型比多数人预期得多：

把 @ 换成 ~，会打开同一个选择器，但范围只限定在知识库——和笔记编辑器里用的是同一个快捷键。

会发生什么 vs 不会发生什么

这一段是整篇教程里最值得记住的，因为它决定了你对 @ 的用法对不对：

快捷键速查

这些直接来自官方的 Power user 页。挑前十个记住就够用了：

还有一整组窗口操作：⌘1–⌘9 按序号跳标签（⌘9 是最后一个）、⌘⇧[ ⌘⇧] 循环标签、⌘\ 新建分栏、⌥; 和 ⌥' 在相邻分栏间移动焦点、⌥Z 进 Zen 模式、⌘B / ⌘⇧B / ⌘⌥B 分别开关左 / 右 / 下三块面板。

09进阶：多 agent 与共享记忆

上文那条主链路只是骨架。真正让 Atlas 值得装的，是挂在骨架上的这几块。

共享记忆：换 agent 不等于从零开始

这是整个项目最核心的一个卖点，机制值得讲清楚：agent 干活时会写下指令文件、笔记和其它持久上下文，Atlas 持续索引这些文件，把它们和你的提示做匹配，把最强的那几条交给 agent。

嵌入（embedding）在你本机跑，文本不往外发。系统里还有一个低权重的结构化事实图，但图匹配永远不会压过更强的直接匹配。

还有一层「跨项目记忆」：Atlas 只会把高置信度、且出现在不止一个项目里的偏好和约束提升上去，并且只在当前项目自身上下文稀少时才动用它。这个保守策略是对的——不然你在 A 项目定的规范会到处乱窜。

记忆面板：看得见才敢信

打开 Memory 面板可以检查 Atlas 到底「知道」什么：

另外，Atlas 会单独索引你的代码库（tree-sitter 扫描），让记忆检索始终「贴住」这个仓库。索引状态就显示在输入框附近，可以在那里重建；嵌入模型在 Settings → Local Models 里选，换模型会重建索引——Atlas 会先跟你确认。这个操作有成本，别手滑。

Agent preferences：把你散落的规则收成一张清单

Atlas 会去搜你已有的记忆和指令文件，找出 12 类偏好。每条显示的都是源文件里的原文，不是摘要；你在这里改了，它去改原文里那一段。

它还会把你措辞的强度分成两档：Strong（"must" / "never" / "always" 这类硬要求）和 Soft（供 agent 权衡的建议）。想让一条建议变成规则，就在源文件里用更硬的措辞——写软话，就别指望它变成铁律。这个设计挺诚实。

技能与包

两者都在 Settings → Skills 里管：

• 技能（Skill）是一个 SKILL.md。作用域选 global（每个项目都能用）或 project（只留在这个项目）。
• 再按 agent 分别启用——Atlas 保留一份正本，然后链接（symlink）到各个 agent 自己的 skills 目录。所以你不会在几处改同一件事。
• 技能在被 agent 调用之前不占上下文。你还可以把一个 agent 专属的老技能「收编」进 Atlas，让它跨 agent 通用。
• 包（Pack）是一批东西的合集：技能、命令、子 agent、规则、钩子、脚本。搜 skills.sh 的 registry、预览、一键装；Atlas 拉源仓库、用 lockfile 记版本、还能检查更新。

装完之后：包里的技能变成可调用的指令，而命令 / 子 agent / 规则变成你可以在输入框里 @ 的对象。

知识库与研究

知识库从左侧面板打开，块编辑器支持标题、列表、大纲、属性、图标和封面，⌘S 保存、⌘' 查看当前笔记、⌘; 开关侧栏。笔记之间可以互链并显示反向链接。

研究面板能搜 arXiv 和 Semantic Scholar，结果带标题、作者、摘要、发表日期、分类和论文 / PDF 链接。下载进项目后，用 @ 就能把它作为上下文交给 agent。

工作区本身也是记录的一部分

Atlas 同时是编辑器、终端和 git 客户端——所以它保留的记录覆盖的是提交周围的规划和手工改动，不只是 diff。几个值得一提的点：

10不止于此：几个真实场景

「源代码管理」这个定位听起来很窄。但把它落在具体场景上，会发现它其实在解决一些你没意识到的问题。

11性能、成本与限制

先说结论：Atlas 是个本地优先的桌面应用，它自己几乎不产生服务端成本。你花钱的地方，是你自己选的那个 agent 的 API 额度。

现在就该知道的限制

12FAQ 与踩坑

这些都是文档和架构笔记里明确写过的行为。遇到怪事先查这里，多数时候答案是「这是设计，不是 bug」。

13隐私、遥测与合规

这类工具会看到你的代码、你的终端、你的浏览器。所以「它往外发什么」必须能查清楚，而不是靠信任。

本地优先，具体指什么

• 代码、笔记、会话保存在本机。
• 会话捕获默认仅本地。
• 账号是可选的。
• 密钥在写入磁盘前被擦除。

遥测：一条很窄的管道

Atlas 只有一条 PostHog 管道，代码在 src-tauri/src/telemetry/。它是匿名的、粗粒度的、可关闭的（默认开启，属于 opt-out）。

官方明确列出了「任何情况下都不发送」的清单：

新增遥测事件需要先在 issue 里讨论，而且任何对管道的改动，都必须在同一个 PR 里更新 TELEMETRY.md。想彻底关掉，把 .env 留空即可——遥测会永久失效。

许可与第三方

Atlas 本体是 MIT 许可。但它调度的 agent 是另一回事：Claude Code、Codex、Cursor、OpenCode、Kilo Code 各自有自己的许可和条款；Research 面板用的 arXiv / Semantic Scholar 也各有自己的使用规则。你实际承担的义务，取决于你用了哪些。

14参考链接与仓库结构

想深入的话，按这个顺序读：先官方文档的概念页，再架构文档，最后看 ADR。

仓库长什么样

想读源码或者提 PR 的人，先记住这条调用链。几乎所有真实功能都横跨整个技术栈：

src/features/<功能>/components  →  stores (Zustand)  →  lib/*-api.ts (invoke + listen)
                                                                ↓
                                              src-tauri/src/commands/<域>.rs
                                                                ↓
                                                      crates/atlas-*

atlas/
├── src/                      React 19 前端
│   ├── features/             每个功能一个文件夹（约 30 个切片）
│   ├── components/ ui/ hooks/ lib/
│   ├── styles/ types/
│   └── App.tsx main.tsx
│
├── src-tauri/                Tauri 宿主（Rust）
│   ├── src/
│   │   ├── lib.rs            tauri::Builder + invoke_handler
│   │   ├── auth/ state/ telemetry/
│   │   └── commands/         每个 IPC 域一个 .rs
│   ├── capabilities/  icons/  resources/
│   └── tauri.conf.json Cargo.toml
│
├── crates/                   Rust crate（工作区成员）
│   ├── atlas-acp-thread      会话模型 + AgentConnection 接缝
│   ├── atlas-agent-servers   外部 ACP 传输 + 启动器 + host env
│   ├── atlas-agent-manager   连接与打开的会话
│   ├── atlas-agent-delta     线程事件 → 冻结的 SessionDelta wire
│   ├── atlas-agent-wire      冻结的 wire 形状（契约测试）
│   ├── atlas-native-agent    移植的引擎，挂在 AgentConnection 上
│   ├── atlas-thread-metadata 应用自有的会话历史（threads.db）
│   ├── atlas-bus             事件广播 + 中间件管道
│   ├── atlas-checkpoint      会话记录 / 时间线（sessions.db）
│   ├── atlas-redact          密钥擦除（单一事实源）
│   ├── atlas-git / atlas-gitdiff
│   ├── atlas-terminal        PTY（portable-pty）
│   ├── atlas-memory / atlas-embed
│   ├── atlas-codeindex       tree-sitter 代码库扫描器
│   └── atlas-kb-server       独立知识库服务（不在工作区内）
│
├── vendor/codex              Atlas Agent 背后的引擎
├── scripts/  landing/
└── README.md ARCHITECTURE.md CONTRIBUTING.md SECURITY.md TELEMETRY.md

四个 ADR：理解这个项目的最短路径