atomcode:基于终端的 AI 编码代理项目

      _   _                  ____          _
     / \ | |_ ___  _ __ ___ / ___|___   __| | ___
    / _ \| __/ _ \| '_ ` _ \ |   / _ \ / _` |/ _ \
   / ___ \ || (_) | | | | | | |__| (_) | (_| |  __/
  /_/   \_\__\___/|_| |_| |_|\____\___/ \__,_|\___|

基于 Rust 开发的开源终端 AI 编码助手

English · 简体中文

安装 · 快速开始 · 功能特性 · 架构设计 · 开发指南 · 贡献代码 · 社区交流

本项目 100% 由 AI 生成。每一行代码、每一个架构决策的实现以及每一次提交均由 AI 编写。人类开发者仅作为决策者和产品经理——负责定义构建内容，而非实现方式。

AtomCode 是一款运行在终端中的 AI 编码助手。您只需用自然语言下达任务，它就能自主读取代码库、编辑文件、运行命令并验证工作成果。

您可以将其视为 Claude Code / Cursor Agent 的开源替代方案，但它完全在终端中运行，并且可以连接到任何兼容 OpenAI 的 API。

功能特性

智能助手循环

• 自主多步骤执行 — 读取文件、编辑代码、运行测试、修复错误，全程自动循环
• 验证循环 — 在确认任务完成前，通过语法检查自动验证编辑内容
• 动态步骤预算 — 根据编辑文件数量动态调整步骤，每轮设置上限以控制成本
• 循环检测 — 识别并跳出重复的工具调用模式
• 三层 JSON 修复 — 恢复格式错误的工具调用参数
• 轮次级数据日志 — 结构化的每轮日志，支持回放、调试和评估测试

内置工具

文件与 shell：

• read_file、write_file、edit_file、search_replace
• bash、grep、glob、list_directory、change_dir
• web_search、web_fetch

代码图谱（具备语言感知能力的代码智能）：

• list_symbols、read_symbol、find_references
• trace_callers、trace_callees、trace_chain
• file_deps、blast_radius

自动化：

• auto_fix — 自动 lint/类型检查修复循环
• use_skill — 调用用户定义的技能

多提供商支持

连接任何支持 OpenAI 函数调用 API 的大模型：

会话与登录

• 持久会话 — 所有对话均会保存；使用 atomcode --continue / -c 继续上次会话，或在 TUI 中通过 /resume 恢复/切换会话
• AtomGit OAuth 登录 — /login（或 atomcode login）将您的 CLI 与 AtomGit 账户关联
• SSO 登录 — /login-with-sso 供 GitCode 内部用户使用
• 无头模式 — atomcode -p "..." 以非交互方式运行单个提示并在标准输出流中返回回复（Claude Code -p 风格）；需要批准的 bash 调用会自动批准，而其他需要批准的工具则会被拒绝
• 守护进程模式 — atomcode-daemon 公开 HTTP API，用于会话历史记录和 SSE 流式聊天

终端界面

• 实时流式传输，支持 markdown 渲染和语法高亮
• 代码块，带有语言标签、行号和 base16-ocean.dark 主题
• 多行输入，支持 Shift+Enter（或 \ + Enter）、高度自动增长、输入历史记录
• 鼠标拖拽文本选择、自动滚动和剪贴板复制
• 斜杠命令 — /model、/provider、/resume、/bg、/diff、/undo、/cost、/clear、/compact 等（见下表）
• 文件附件 — 粘贴文件路径以附加内容作为上下文
• 括号粘贴 — 长粘贴内容折叠为简洁指示器
• 技能 — 从技能目录加载的用户定义命令，可像任何斜杠命令一样调用

Web UI

• /webui（在 TUI 中）或 atomcode webui（CLI）会启动本地浏览器界面，作为终端界面的替代方案 —— 相同的智能体，相同的会话，在浏览器中呈现
• 仅本地回环 —— 服务器绑定到 127.0.0.1 并使用一次性令牌；不会向网络公开任何内容
• /webui stop 停止进程内服务器（之后使用 /webui 可重新启动）

Safety

• 破坏性命令检测 —— rm -rf、git push --force、DROP TABLE 等命令需要明确批准
• 路径感知确认 —— 根据风险级别，外部读取、敏感路径以及工作区外的所有写入可能需要确认
• 敏感文件保护 —— 受保护的系统路径、凭据目录、shell 配置、.env 文件以及密钥/证书文件采用更严格的确认规则
• Shell 绕过保护 —— 常见的 shell 文件命令，如 cat、head、ls、cp、mv 和 tee，继承与文件工具相同的路径批准模型
• 每会话权限授予 —— 按工具模式批准一次，或始终允许
• 源文件删除需要批准 —— 对代码文件执行 rm 操作永远不会自动批准
• 撤销 —— /undo 通过文件历史快照回滚上一轮的文件编辑

完整设计和当前边界请参见 Permission Model。

Privacy

• 📊 匿名遥测（可选择退出）—— 参见 docs/telemetry.md

Installation

From Source (recommended)

git clone https://atomgit.com/atomgit_atomcode/atomcode.git
cd atomcode
cargo install --path crates/atomcode-cli --locked

二进制文件将生成在 target/release/atomcode 并安装到 macOS / Linux / 鸿蒙 PC 的 ~/.cargo/bin/atomcode，以及 Windows 的 $env:USERPROFILE/.cargo/bin/atomcode.exe。请确保 ~/.cargo/bin（Windows 上为 %USERPROFILE%\.cargo\bin）已添加到你的 PATH 中。

若要编译但不安装，请运行：

cargo build --release

二进制文件将生成在 target/release/atomcode 路径下。

包管理器

AtomCode CLI 也可通过以下包管理器进行安装：

# Install using npm
npm install -g @atomgit.com/atomcode

# Install using Homebrew
brew install --cask atomcode

系统要求

• Rust 1.88 或更高版本（用于构建；旧版 Cargo 无法解析当前锁定文件）
• 来自任何受支持提供商的 API 密钥（或用于 /login 的 AtomGit 账户）

卸载

移除 AtomCode 并（可选）删除其数据：

atomcode uninstall                # interactive: per-group prompts
atomcode uninstall --keep-data    # only remove binary + PATH edit
atomcode uninstall --purge        # remove everything, including ~/.atomcode
atomcode uninstall --dry-run      # show plan, change nothing

如果二进制文件已损坏或丢失：

curl -fsSL https://raw.atomgit.com/atomgit_atomcode/atomcode/raw/main/scripts/uninstall.sh | sh
# Windows:
irm https://raw.atomgit.com/atomgit_atomcode/atomcode/raw/main/scripts/uninstall.ps1 | iex

默认情况下会保留凭据（auth.toml、mcp.json、config.toml、ATOMCODE.md）；传递 --purge 也会将其删除。

快速开始

1. 首次运行

atomcode

首次运行时，设置向导将引导你完成 LLM 提供商的配置：

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)

2. 配置

配置文件存储在 ~/.atomcode/config.toml。一个最小化的单一提供程序设置如下：

default_provider = "deepseek"

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

您可以声明多个提供商，并使用 /model 或 /provider 在它们之间切换。涵盖 Claude / OpenAI / OpenAI 兼容端点（DeepSeek、GLM、SiliconFlow、OpenRouter...）/ Ollama 以及 [datalog] 部分的完整参考，可在 docs/config.example.toml 中找到 — 复制并编辑您需要的部分。

手动编辑 config.toml 后，在 atomcode 内运行 /reload 即可应用更改，无需重启。

3. 开始编码

# Open in your project directory
cd your-project
atomcode

# Or specify directory
atomcode -C /path/to/project

# Or specify model
atomcode --model gpt-4o

# Headless (single prompt, reply on stdout)
atomcode -p "Explain the agent loop in this repo"

# Read prompt from file
atomcode --prompt-file task.md

在无头模式下，需要批准的 bash 调用会自动获得批准并记录到标准错误输出；其他需要批准的工具将被拒绝。

然后只需输入您想要的内容：

> Fix the login bug where users get redirected to 404 after OAuth callback

> Add a dark mode toggle to the settings page

> Refactor the database module to use connection pooling

> Write tests for the payment processing module

快捷键

输入

换行组合键的终端兼容性：

• Shift+Enter、Ctrl+Enter 和 Ctrl+J 都需要支持 Kitty 键盘协议的终端 — kitty、WezTerm、Alacritty、iTerm2 ≥3.5、Windows Terminal ≥1.21。旧版终端会将它们识别为普通 Enter（即发送消息）。
• Alt+Enter 在大多数终端上可通过字节级操作工作，但 Windows Terminal 默认将其绑定为“切换全屏” — 需在设置 → 操作中移除该绑定以释放功能。
• Xshell 不支持 Kitty 协议；可在其键盘映射设置中，将某个未使用的组合键映射为发送 ESC, Enter（\x1b\r）以实现相同效果，或通过剪贴板粘贴多行文本（已启用带括号的粘贴功能）。

在 Windows 上粘贴图片： Windows Terminal 和 conhost 将 Ctrl+V 绑定到自身的 粘贴 操作，该操作仅转发剪贴板中的 CF_UNICODETEXT — 纯图片剪贴板不会发送任何内容，因此应用内的 Ctrl+V 处理程序无法触发。有两种解决方法：

1. 使用 /paste — 该斜杠命令会提取剪贴板图片并将其附加为 [Image #N]。适用于所有终端，包括 Windows Terminal、PowerShell 7、conhost 和 git bash。Windows 系统上 TUI 的右下角提示会自动显示 Image in clipboard · /paste。
2. 若希望保留 Ctrl+V 的使用习惯：打开 Windows Terminal 的 settings.json（Ctrl+, → “打开 JSON 文件”），删除 "actions" 下的 { "command": "paste", "keys": "ctrl+v" } 条目，或将其重新绑定为 ctrl+shift+v。重启后，Ctrl+V 会直接传递给 atomcode。

Git Bash（MinTTY）不会拦截 Ctrl+V，因此可直接使用。

导航

斜杠命令

架构

AtomCode 是一个 Rust 工作区，包含四个 crate：

atomcode/
  crates/
    atomcode-core/     # Headless library — no TUI dependency
      agent/           # AgentLoop: autonomous tool-use loop
      turn/            # TurnRunner, datalog, permission decider
      config/          # Config loading, provider configs
      conversation/    # Message types, windowed context
      provider/        # LlmProvider trait + OpenAI/Claude/Ollama
      tool/            # Tool trait + built-in tool implementations
      session/         # Persistent sessions
      skill.rs         # User-defined skills

    atomcode-tuix/     # Terminal UI — retained-mode renderer (CC-style normal mode)
      event_loop/      # App state machine, command dispatch
      render/          # Cell-based renderer, diff, retained-mode frame loop
      modals/          # Picker UIs (dir, model, session, provider, issue)

    atomcode-cli/      # Binary entry point (TUI + headless -p mode)
      main.rs          # CLI args, first-run wizard, launch
      auth/            # AtomGit OAuth client

    atomcode-daemon/   # HTTP/SSE API server over atomcode-core

设计原则

1. 技术栈无关 — 绝不硬编码特定语言的逻辑。通过描述文件（package.json、Cargo.toml、pyproject.toml、pom.xml 等）动态检测项目类型。

2. 解耦代理 — AgentLoop 作为独立的异步任务运行，通过通道（AgentCommand / AgentEvent）与 TUI 通信。核心库完全没有 TUI 依赖，这也是守护进程得以实现的基础。

3. 工具安全性 — 所有破坏性操作均需用户明确批准。工具故障会成为 LLM 的观察结果，绝不会导致程序崩溃。

4. 上下文感知 — 支持令牌预算感知的对话窗口管理、项目文件树注入以及每轮系统提醒，确保模型在不超出上下文限制的前提下保持专注。

项目指令文件

在项目根目录创建 .atomcode.md 文件，为 AtomCode 提供持久化上下文：

# Project Instructions

This is a Vue 3 + TypeScript project using Pinia for state management.

- Always use Composition API with `<script setup>`
- Use TailwindCSS for styling, no inline styles
- Run `npm run lint` after editing .vue/.ts files

AtomCode 会自动读取此文件并将其包含在系统提示中。AtomCode 还支持 AGENTS.md（AI 编码代理的 开放标准）作为替代方案 — 若两个文件同时存在，.atomcode.md 将优先生效。

开发

先决条件

• Rust 1.88+ — 通过 rustup 安装
• Git
• 受支持的 LLM 提供商 API 密钥（用于运行时测试）

从源代码构建

git clone https://atomgit.com/atomgit_atomcode/atomcode.git
cd atomcode

# Debug build (fast compilation, slower runtime)
cargo build

# Release build (slower compilation, optimized binary)
cargo build --release

开发环境运行

# Run the TUI directly (debug mode)
cargo run -p atomcode-cli

# With arguments
cargo run -p atomcode-cli -- -C /path/to/project
cargo run -p atomcode-cli -- --model gpt-4o

# Headless mode
cargo run -p atomcode-cli -- -p "summarize this repo"

# Daemon (HTTP API)
cargo run -p atomcode-daemon

测试

# Run all tests
cargo test

# Run tests for a specific crate
cargo test -p atomcode-core
cargo test -p atomcode-tuix

# Run a specific test
cargo test -p atomcode-core test_name

实用命令

# Check compilation without building
cargo check

# Format code
cargo fmt

# Run linter
cargo clippy

# Build and install to ~/.cargo/bin
cargo install --path crates/atomcode-cli

贡献指南

欢迎参与贡献！atomcode 目前处于积极开发阶段。

贡献步骤

1. ** Fork **项目到您的 AtomGit 仓库
2. 克隆您的仓库到本地：

   git clone https://atomgit.com/<your-username>/atomcode.git
   cd atomcode
   

3. 创建分支用于您的修改：

   git checkout -b feat/your-feature
   # 或
   git checkout -b fix/your-bugfix
   

4. 进行修改，确保项目能够构建且测试通过：

   cargo build && cargo test && cargo clippy
   

5. 提交修改并撰写清晰的提交信息：

   git commit -m "feat: add xxx support"
   

6. 推送分支并向 main 分支提交Pull Request

分支命名规范

开发准则

• 遵循项目核心原则——尤其注意技术栈中立性
  （核心引擎中不应包含特定语言/框架的逻辑；通过探测 package.json / Cargo.toml / pom.xml 等文件，由适配器处理特定逻辑）
• 所有工具故障必须优雅处理——将错误作为观察结果返回给 LLM，绝对禁止程序崩溃（panic）
• 破坏性操作必须获得用户批准
• 保持系统提示简洁（约 1.5K tokens）
• 提交前运行 cargo fmt 和 cargo clippy

入门方向

• 添加新工具——在 crates/atomcode-core/src/tool/ 中实现 Tool trait
• 添加新 provider——在 crates/atomcode-core/src/provider/ 中实现 LlmProvider
• 改进 UI——渲染逻辑位于 crates/atomcode-tuix/src/render/
• 修复缺陷——查看 Issues 中的开放缺陷

社区交流

扫描下方二维码添加微信，加入 atomcode 社区交流群——分享反馈、报告问题，与其他用户和维护者交流：

许可协议

MIT 许可协议。详情参见 LICENSE。

使用 Rust、ratatui 开发，倾注了无数个深夜的心血。