整个工具的核心结构从上图可以一眼看穿：安装方式三种，配置支持多种模型，命令体系包含斜杠命令和快捷键，工具类分为文件操作、代码图谱、Web自动化三大块，另外还有Skills扩展和Headless模式等高级特性。下面按照从零到一的顺序逐一展开。
二、系统要求 ????️
AtomCode 支持主流操作系统：macOS、Linux（包括 x86_64 和 ARM 架构）、Windows（通过 WSL 或原生终端）。对内存的要求不算苛刻，但如果你要跑本地模型（比如通过 Ollama），建议至少 8GB 可用内存。此外，终端需要支持 True Color——目前大多数现代终端模拟器都已经默认支持。
术语解释 ????
- Headless 模式：无交互界面，通过 CLI 参数或 HTTP API 进行命令批量处理，适合 CI/CD 流水线。
- Daemon 模式：后台常驻服务，以 HTTP 接口形式提供 AI 能力，可作为其他工具的中间层。
- Skills：用户自定义的行为扩展，通过 DSL 文件定义新的斜杠命令。
- AtomGit OAuth：通过 AtomGit 账号进行一键身份认证，自动获取 API 额度。
三、三种安装方式 ✨
安装之前先确认一下：你手里这台机器有没有 curl 或 git？基本命令行工具都是必须的。下面三种方式根据你的场景任选一种就行。
3.1 一键安装（推荐 ✅）
在终端里执行下面这行命令，脚体会自动检测系统并下载对应二进制包：
curl -fsSL https://atomcode.dev/install.sh | bash
安装完成后会有一个提示，告诉你 atom 命令已添加到 PATH。
3.2 源码构建 ????️
适合希望自定义编译参数或需要调试的人群。前提是本地需要安装 Rust 工具链：
git clone https://github.com/atomcode/atomcode.git
cd atomcode
cargo build --release
得到的二进制在 target/release/atom，可以手动复制到 /usr/local/bin 或直接添加别名。
3.3 Cargo 安装 ????
如果你已经安装了 Rust 环境，一句命令完事：
cargo install atomcode
这个方式会从 crates.io 拉取预编译版本，通常比源码构建快很多。
验证安装 ✔️
不管用哪种方式，安装后执行 atom --version 就能看到版本号。如果输出版本信息，说明安装成功。
四、首次运行 & 登录配置 ????
第一次运行 atom 时，它会自动检查是否有配置文件。如果没有，会提示你进行登录。目前支持三种认证/配置方式。
4.1 AtomGit OAuth（推荐 ????）
运行 atom login 会打开浏览器跳转到 AtomGit 授权页面。登录后自动获得一个 API Key，存储在本地 keychain 里。这是最省心的方式，不需要手动维护 key。
4.2 手动 API Key 配置
如果你已经订阅了 OpenAI、Claude 或其他 API 服务，可以手动写入配置文件：
atom config set openai_api_key "sk-xxxx"
或者直接编辑配置文件 ~/.config/atomcode/config.toml。
最小配置模板
[model]
provider = "openai"
model = "gpt-4o"
api_key = "sk-xxxx"
4.3 本地 Ollama 配置 ????️
如果你更倾向本地模型，只要本地跑着 Ollama 服务（默认端口 11434），把配置改成：
[model]
provider = "ollama"
model = "llama3.2"
ollama_host = "http://localhost:11434"
然后 atom chat 就会通过本地模型回答问题。
五、配置文件全解析 ????
配置文件位于 ~/.config/atomcode/config.toml（Linux/macOS）或 %APPDATA%\atomcode\config.toml（Windows）。第一次运行如果不存在，会自动生成默认配置。
5.1 顶层字段
| 字段 | 说明 | 示例值 |
|---|
model.provider | 模型提供商 | "openai"、"claude"、"ollama" |
model.model | 模型名称 | "gpt-4o"、"claude-3-5-sonnet" |
model.api_key | API Key（手动方式） | "sk-xxxx" |
editor.exclude_paths | 不发送给 AI 的路径 | ["node_modules", ".git", "target"] |
editor.code_map_mode | 代码图谱模式 | "always"、"on_request"、"never" |
5.2 主流模型官方配置
Claude
[model]
provider = "claude"
model = "claude-3-5-sonnet-20241022"
api_key = "sk-ant-xxxx"
OpenAI GPT-4o
[model]
provider = "openai"
model = "gpt-4o"
api_key = "sk-xxxx"
智谱 GLM
[model]
provider = "zhipu"
model = "glm-4-plus"
api_key = "your-zhipu-api-key"
通义千问
[model]
provider = "qwen"
model = "qwen-plus"
api_key = "your-qwen-api-key"
六、基础使用 ????
AtomCode 的核心用法就是 atom 命令后面跟不同的子命令。atom chat 进入交互模式（聊天界面），atom 直接跟任务描述则属于一次性执行。
6.1 常用 CLI 参数
| 参数 | 说明 |
|---|
--context 或 -c | 手动指定需携带给 AI 的上下文文件路径 |
--model 或 -m | 临时切换模型（覆盖配置文件） |
--no-stream | 禁用流式输出，一次性完整返回 |
--headless | 启用无头模式 |
--verbose | 输出详细日志（排查问题时用） |
6.2 任务描述原则
描述越具体，AI 给的结果越精准。一个通用公式是：目标 + 约束 + 输出格式。比如：“把这个 JSON 转成 YAML，键顺序保持原有，输出到 config.yaml”。
6.3 快速体验
atom "用 Python 写一个快速排序，支持降序参数"
然后你会在终端看到代码一行行流出来。按 Ctrl+C 可以中断。
七、17个斜杠命令大全 ????
斜杠命令是 AtomCode 的灵魂——在聊天框里输入 / 加前缀，就能触发特定行为。分为三类。
核心命令
/add —— 将文件或目录加入当前上下文/drop —— 从上下文中移除文件/clear —— 清空当前对话上下文/undo —— 撤销最近一次由 AI 发起的文件修改/commit —— 根据当前文件变更自动生成 git commit 信息/chat —— 切换到纯对话模式（不附加上下文）/review —— 对当前上下文中的代码进行审查
工具命令
/bash —— 执行一条 Shell 命令并带回结果/code —— 仅获取代码片段，不包含解释/doc —— 为当前文件或函数生成文档/test —— 针对当前代码生成单元测试/explain —— 逐行解释代码
配置命令
/config —— 查看或修改当前配置（实时生效）/model —— 临时切换模型/help —— 显示帮助信息/skill —— 列出或启用/禁用自定义 Skills/exit —— 退出交互模式
八、快捷键速查 ⌨️
交互模式下，熟练使用快捷键可以大幅提升操作效率。
输入操作
Ctrl + A —— 移动到行首Ctrl + E —— 移动到行尾Ctrl + U —— 清空当前行Ctrl + K —— 删除光标到行尾Ctrl + W —— 删除前一个单词
浏览操作
Up/Down —— 切换历史输入Ctrl + D —— 向下翻页（长输出时）Ctrl + C —— 取消当前生成Ctrl + L —— 清屏
权限确认
y/n —— 当 AI 需要执行文件写入或命令时，会等待你确认a —— 总是允许（对当前会话永久信任）r —— 拒绝并记住（阻止类似操作）
九、21个内置工具 ????️
这些工具通过斜杠命令或上下文触发，不需要额外配置。
文件 & Shell（9个）
- read —— 读取文件内容并返回
- write —— 将 AI 生成的内容写入文件
- edit —— 对已有文件进行局部替换修改
- delete —— 删除指定文件
- ls —— 列出目录结构
- glob —— 使用通配符匹配文件
- grep —— 在文件中搜索文本
- bash —— 执行 Shell 命令（需确认）
- diff —— 显示文件差异
代码图谱（8个）⭐（核心特色）
代码图谱是 AtomCode 最亮眼的功能。它能分析项目的结构、类层级、函数调用链，并在聊天时自动提供给 AI 作为上下文，从而让回答更准确。
- code_map —— 生成当前项目的代码结构图
- file_map —— 仅显示文件目录关系
- class_map —— 提取类继承关系
- function_map —— 显示函数调用关系
- import_map —— 分析模块导入依赖
- dependency_graph —— 综合 dependency 的图结构
- symbol_search —— 搜索并定位符号定义
- git_reflog —— 基于 git 提交的变更分析
Web & 自动化（4个）
- web_search —— 在聊天中集成网络搜索（需配置搜索引擎）
- web_fetch —— 获取指定 URL 的文本内容
- notify —— 发送系统通知（仅桌面环境）
- screenshot —— 捕获指定区域截图并分析（需 GUI 环境）
十、会话管理 & 撤销操作 ↩️
恢复会话
AtomCode 默认会保存历史会话。在交互模式下输入 /chat --history 可查看历史，用 session resume 恢复之前的对话。你也可以通过 --session 参数启动时指定某个 session。
回滚文件修改
AI 写坏代码了？用 /undo 可以回滚最近一次由 AI 触发的文件写入或编辑。注意，这个操作依赖 git（未跟踪的文件会通过内置的备份机制恢复），所以强烈建议项目使用 git 版本管理。
十一、项目指令文件 .atomcode.md ????
在项目根目录创建 .atomcode.md 文件，你可以定义全局指令。里面的内容会每次 chat 时自动附加给 AI。例如：
# 项目约定
- 语言：Python 3.12
- 风格：PEP8
- 测试框架：pytest
- 请勿修改 requirements.txt 文件
这样一来，AI 的所有回答都会遵循这些约束，省得每次手动强调。
十二、Headless & Daemon 模式 ????️
这两个模式是为自动化流程准备的。
12.1 Headless 无头模式（脚本/CI）
通过在命令后加上 --headless，不会有任何交互提示。适用于 CI 流水线中的代码审查或自动修复：
atom --headless "修复 src/main.py 中的所有 lint 错误"
12.2 Daemon 服务（HTTP API）
如果你想将 AtomCode 作为后台服务运行，供其他程序（比如 VS Code 扩展、自定义脚本）调用，可以启动 daemon 模式：
atom daemon --port 8080
之后通过 HTTP POST http://localhost:8080/chat 发送 JSON 格式的请求即可。返回结果支持流式 SSE。
十三、Skills 自定义扩展 ????
Skills 允许你编写类 YAML 的 DSL 文件，定义新的斜杠命令。一个典型的 Skill 文件（~/.atomcode/skills/review.yml）长这样：
name: "review"
description: "审查当前文件的变更"
prompt: |
你是一位资深代码审查者。请检查以下代码变更，重点关注：
1. 安全性漏洞
2. 性能瓶颈
3. 代码风格
{{ diff }}
注册后，在聊天中输入 /review 就会自动生成审查结果。极大的扩展性——团队可以共享一套 Skills 库。
十四、新手高频报错 & 解决方案 ????
14.1 安装报错
- 错误：
permission denied
- 安装脚本需要写
/usr/local/bin 权限。用 sudo bash install.sh 重新执行，或者把安装路径改到用户目录下。
- 错误：
command not found: cargo
- Rust 未安装。先执行
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 安装。
14.2 登录 & 网络报错
- 错误：
401 Unauthorized
- API Key 过期或错误。重新
atom login 或检查配置文件中的 key。
- 错误：
HTTP 429 Too Many Requests
- 触发了 API 速率限制。稍等一会儿再试，或者降低请求频率。
14.3 权限 & 工具报错
- 错误：
Tool execution denied
- 因为权限策略禁止了该工具。使用
a 键允许，或修改配置里的 trusted_tools 列表。
- 错误：
No such file or directory
- 上下文中的路径错误。确认文件存在，或使用绝对路径。
十五、FAQ 常见问题 ❓
- Q1：AtomCode 会上传代码吗？
- 只有在执行需要文件内容的命令（如 /add）时才会发送数据。所有传输都经过 TLS 加密。OAuth 登录后 token 储存在本地 keychain，不会被上传。你可以查看配置中的
exclude_paths 来自定义哪些路径不被发送。
- Q2：OAuth 登录重启后失效？
- 检查系统的 keychain 服务是否正常运行。在某些轻量级 Docker 容器或无桌面环境中，keychain 可能不可用。改用手动 API Key 配置可解决。
- Q3：/undo 能回滚一切吗？
- 不能。它只能撤销当前会话中由 AI 发起的文件写入或编辑操作。手工执行 /bash 创建的临时文件、或通过外部编辑器保存的修改无法撤销。
- Q4：Linux ARM 可以用吗？
- 可以。官方提供 ARM64 二进制包。通过
curl -fsSL https://atomcode.dev/install.sh | bash 会自动选择对应架构。源码构建也支持。
- Q5：Skill 不显示？
- 检查
~/.atomcode/skills/ 目录是否存在，Skill 文件后缀必须是 .yml 或 .yaml。修改后重新启动 atom chat 即可发现新命令。
官方资源链接 ????
结语 ????
AtomCode 的终端原生体验，让 AI 编码助手不再是 IDE 的附属品。熟练使用它的斜杠命令、代码图谱和 Skills 自定义，工作效率会有明显的提升。如果你在安装或使用中遇到了本文没覆盖到的问题，欢迎在社区提问或查阅官方文档。祝各位编码愉快。
