AtomCode 完整文档

快速开始

三步走：安装、配置一个 provider、在项目里跑起来。

1. 一键安装

复制# macOS / Linux / HarmonyOS PC
curl -fsSL https://atomgit.com/atomgit_atomcode/atomcode/raw/main/install.sh | sh

# Windows · PowerShell
irm https://atomgit.com/atomgit_atomcode/atomcode/raw/main/install.ps1 | iex

2. 首次运行 — 3 步向导

在终端任意位置执行 atomcode，会进入交互式向导：

Welcome to AtomCode! Let's set up your first provider.

Select provider:
  [1] Claude (Anthropic)
  [2] OpenAI
  [3] OpenAI Compatible (DeepSeek, Qwen, Zhipu, Moonshot...)
  [4] Ollama (local)

3. 在项目里跑起来

cd your-project
atomcode

# 然后用自然语言描述任务
> 修复 OAuth 回调后用户被重定向到 404 的登录 bug
> 把数据库模块重构为使用连接池
> 给设置页加一个深色模式切换

安装

三种安装方式：一键脚本、源码构建、下载预编译二进制。

一键脚本（推荐）

脚本会按 uname -s / -m 自动判断平台并下载对应二进制，写入 /usr/local/bin/atomcode（若不可写则降级到 ~/.local/bin），并自动写 PATH。

# 可选环境变量
export ATOMCODE_VERSION=v4.22.1        # 指定版本（默认 latest）
export ATOMCODE_PREFIX=/opt/atomcode    # 指定安装目录（绝对路径）

curl -fsSL https://atomgit.com/atomgit_atomcode/atomcode/raw/main/install.sh | sh

从源码构建

# 需要 Rust 1.88+
git clone https://atomgit.com/atomgit_atomcode/atomcode.git
cd atomcode
cargo install --path crates/atomcode-cli --locked
atomcode --version  # 验证

编译产物位于 ~/.cargo/bin/atomcode（macOS / Linux / HarmonyOS）或 %USERPROFILE%\.cargo\bin\atomcode.exe（Windows）。如果只想编译不安装：cargo build --release。

下载预编译二进制

从 Releases 页下载对应平台的二进制：

卸载

atomcode uninstall                  # 交互式：分组询问
atomcode uninstall --keep-data      # 仅删二进制 + PATH
atomcode uninstall --purge          # 一并删除 ~/.atomcode/
atomcode uninstall --dry-run        # 打印计划不执行

配置

配置文件位于 ~/.atomcode/config.toml。最小可用配置只需要一个 provider。

最小配置 — 单 Provider

复制default_provider = "deepseek"

[providers.deepseek]
type           = "openai"
api_key        = "sk-..."
model          = "deepseek-chat"
base_url       = "https://api.deepseek.com/v1"
context_window = 64000

多 Provider 配置

配置多个 provider，运行时用 /model 或 /provider 切换：

default_provider = "claude"

[providers.claude]
type    = "claude"
api_key = "sk-ant-..."
model   = "claude-sonnet-4-6"

[providers.openai]
type    = "openai"
api_key = "sk-..."
model   = "gpt-4o"

[providers.glm]
type     = "openai"
api_key  = "..."
model    = "glm-5"
base_url = "https://open.bigmodel.cn/api/paas/v4"

[providers.ollama]
type           = "openai"
base_url       = "http://localhost:11434/v1"
model          = "qwen2.5-coder"
context_window = 32000

Datalog 配置

每个对话轮（turn）都可以写入结构化日志，便于回放、调试和评测：

[datalog]
enabled = true
dir     = "~/.atomcode/datalog"   # 默认
# dir = "/abs/path"           # 绝对，不受 /cd 影响
# dir = "rel/path"            # 相对，跟随 /cd

通知配置

[notifications]
enabled           = true
min_duration_secs = 8      # 任务超过 8 秒才通知
terminal          = true   # 优先终端原生（kitty/WezTerm/iTerm2）
system            = true   # 回退系统通知（osascript / notify-send）
bell              = true
background_only   = true   # 仅在程序失焦时通知

斜杠命令

18 个内置斜杠命令。在 TUI 里输入 / 即触发命令补全。

键盘快捷键

输入

导航

内置工具（21 个）

所有工具都通过 Tool trait 注册到 ToolRegistry。破坏性操作会经 InteractivePermissionDecider 走交互式审批。

文件与 Shell（11 个）

代码图谱（8 个 → 见下节）

list_symbols · read_symbol · find_references · trace_callers · trace_callees · trace_chain · file_deps · blast_radius

自动化（2 个）

代码图谱

语言感知的代码智能 —— 让模型真正读懂大型代码库，而不是退化到 grep。基于 tree-sitter + ripgrep。

Skills

Skills 是用户自定义的命令模板，从 ~/.atomcode/skills/ 加载，像普通斜杠命令一样调用。

Skill 文件结构

在 ~/.atomcode/skills/ 目录下创建任意 markdown 文件，文件名（去 .md）就是 skill 名：

# ~/.atomcode/skills/code-review.md

name: code-review
description: 审阅当前修改的代码

---

请帮我审阅当前 git diff 中的修改。重点关注：
1. 是否有潜在的 bug
2. 错误处理是否完整
3. 测试覆盖是否充足
4. 命名和注释是否清晰

先用 /diff 查看修改，再给出具体改进建议。

调用 Skill

# TUI 内直接像斜杠命令一样调用
> /code-review

# 或者让 agent 主动调用（通过 use_skill 工具）
> 用你的 code-review skill 检查一下我刚才的修改

MCP 集成

AtomCode 实现了 Model Context Protocol 客户端，可以通过 .mcp.json 接入任何 MCP server，将其 tools 暴露为与内建工具一致的可调用工具（含审批链路）。

配置文件位置

• 项目级：项目根目录/.mcp.json
• 用户级：~/.atomcode/mcp.json
• 项目级同名 server 覆盖用户级

模板 — stdio 服务器

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"],
      "env": { "NODE_ENV": "production" },
      "timeout_ms": 30000
    }
  }
}

模板 — HTTP 服务器

{
  "mcpServers": {
    "github": {
      "url": "https://api.example.com/mcp",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" },
      "timeout_ms": 30000
    }
  }
}

字符串里可用 ${VAR} 或 ${VAR:-default}，启动时由程序展开。

工具命名约定

每个远端 tool 映射为 mcp__<server_key>__<tool_name>。例如 playwright server 的 browser_navigate → mcp__playwright__browser_navigate。

权限

MCP 适配器对每次调用返回 RequireApproval，走与内建工具一致的交互式审批。PermissionStore 的 session grant / override 按完整工具名 mcp__... 索引。

OAuth（仅 HTTP）

# 显式登录，后台连接不会自动弹浏览器
atomcode mcp login <server>

# 或在 TUI 内
> /mcp login <server>

项目指令文件 .atomcode.md

在项目根目录创建 .atomcode.md，AtomCode 会自动读取并注入到系统提示，给 AI 提供持久化项目上下文。

复制# Project Instructions

本项目是 Vue 3 + TypeScript，使用 Pinia 做状态管理。

## 代码规范
- 始终使用 `<script setup>` 风格的 Composition API
- 样式使用 TailwindCSS，不写内联样式
- 组件命名遵循 PascalCase

## 工作流
- 编辑 .vue/.ts 文件后运行 `npm run lint`
- 提交前必须跑 `npm test`
- 不要修改 src/legacy/ 下的任何文件

## 项目约定
- API 调用统一走 src/api/，错误处理在拦截器里
- 国际化字符串只能放 src/locales/zh.json 和 en.json

权限模型

AtomCode 用统一的权限模型控制文件、目录、shell 命令的访问。目标：阻止未确认的工作区外访问、阻止 shell 绕过文件工具、保持权限行为显式可追踪。

三种访问动作

三种审批结果

路径审批规则

敏感路径前缀

下列路径会被识别为敏感（除非匹配例外规则）：

• /System · /bin · /sbin · /usr · /var · /private/etc · /private/var
• 凭据目录：~/.ssh · ~/.aws · ~/.gnupg · ~/.config/gh
• Shell 配置：.bashrc · .zshrc · .profile
• .env 文件 · *.pem · *.key · *.crt

Headless 与 Daemon

Headless 模式（一次性 prompt）

# 跑一条 prompt，结果输出到 stdout
atomcode -p "简要说明这个仓库的 agent loop"

# 从文件读取 prompt
atomcode --prompt-file task.md

# 在 CI 里使用
atomcode -p "修复 lint 错误" > output.txt

在 headless 模式下，需要确认的 bash 会自动批准并写到 stderr；其他需要确认的工具会被自动拒绝。

Daemon 模式（HTTP / SSE API）

# 启动后台服务（独立 binary）
atomcode-daemon

# 暴露 HTTP API：
# GET  /sessions            列出会话
# GET  /sessions/:id        获取会话历史
# POST /sessions/:id/turn   SSE 流式对话

架构

AtomCode 是一个 Rust workspace，由四个 crate 组成。核心引擎与 UI 解耦，通过 channel 通信。

Workspace 结构

atomcode/
  crates/
    atomcode-core/       # 无头核心库，不依赖 TUI
      agent/             # AgentLoop：自主工具调用循环
      turn/              # TurnRunner、datalog、权限决策器
      config/            # 配置加载、provider 配置
      conversation/      # 消息类型、窗口化上下文
      provider/          # LlmProvider trait + OpenAI/Claude/Ollama
      tool/              # Tool trait + 内置工具实现
      session/           # 持久化会话
      skill.rs           # 用户自定义 skill
      mcp/               # MCP 客户端 + stdio/HTTP 传输

    atomcode-tuix/       # 终端 UI — retained-mode 渲染器
      event_loop/        # App 状态机、命令分发
      render/            # cell-level 渲染、diff、帧循环
      modals/            # picker（dir、model、session、provider、issue）

    atomcode-cli/        # 可执行入口（TUI + headless -p 模式）
      main.rs            # CLI 参数、首次运行向导、启动
      auth/              # AtomGit OAuth 客户端

    atomcode-daemon/     # 基于 atomcode-core 的 HTTP/SSE API 服务

    atomcode-telemetry/  # 匿名遥测客户端（可关）

设计原则

1. 技术栈无关 —— 核心引擎不硬编码任何特定语言的逻辑，通过 package.json、Cargo.toml、pyproject.toml、pom.xml 等描述文件动态探测项目类型
2. Agent 解耦 —— AgentLoop 作为独立的异步任务运行，通过 channel（AgentCommand / AgentEvent）与 TUI 通信。核心库完全不依赖 TUI，这也是 daemon 得以存在的基础
3. 工具安全 —— 所有破坏性操作必须经用户显式确认。工具失败会作为 observation 返回给模型，绝不 panic
4. 上下文感知 —— token 预算感知的会话窗口、项目文件树注入、每轮系统提醒

遥测与隐私

AtomCode 默认开启匿名遥测，用于了解使用情况、改进产品。遥测不收集你的代码、prompt 内容或文件路径。

采集内容

• 启动事件（版本、平台、首次运行 vs 二次）
• 工具调用计数（按工具名，不含参数）
• 错误码（不含上下文）
• Agent loop 步数分布

关闭遥测

# config.toml
[telemetry]
enabled = false

或环境变量：ATOMCODE_TELEMETRY=0

FAQ

为什么换行键不工作？

Shift+Enter / Ctrl+Enter / Ctrl+J 都需要终端支持 Kitty 键盘协议。如果你的终端不支持，可以用万能写法 \ + Enter（输入反斜杠后按回车，反斜杠会被自动删除）。

Windows 下 Ctrl+V 粘不上图？

Windows Terminal 和 conhost 默认把 Ctrl+V 绑给它们自己的 paste action，只读 CF_UNICODETEXT，剪贴板上只有图片时什么都不会发。两种解法：

• 用 /paste 斜杠命令 —— 直接读剪贴板图片以 [Image #N] 附加
• 在 Windows Terminal 的 settings.json 里删掉 { "command": "paste", "keys": "ctrl+v" }

API 返回"reasoning_content must be passed back"？

这是 DeepSeek-R1 / OpenAI o1 类思考模型的 history-echo 策略问题。在 config.toml 的 provider 段显式设置：

[providers.deepseek-r1]
type              = "openai"
model             = "deepseek-reasoner"
reasoning_history = "include"   # 或 "exclude"

如何回滚 AI 的修改？

用 /undo —— 它通过 file_history 快照 + git stash checkpoint 一键回滚上一轮所有文件编辑。每文件最多保留 50 个历史版本，按 session 隔离。

能在 CI 里用吗？

可以。用 headless 模式：

atomcode -p "修复 lint 错误" > output.txt

headless 下需要确认的 bash 自动批准（写 stderr），其他需要确认的工具自动拒绝。

会话历史在哪？

~/.atomcode/sessions/ 下按 session id 组织。可用 atomcode -c 继续上一次会话，或 /resume 在 TUI 内挑选历史会话。

如何接入私有部署的 OpenAI 兼容服务？

[providers.private]
type           = "openai"
api_key        = "..."
model          = "my-model"
base_url       = "https://api.internal.company.com/v1"
context_window = 32000

任何实现了 OpenAI function calling 接口的服务都可接入。

报 bug / 反馈？

欢迎提 Issue，或在 TUI 内用 /issue 一键创建。