AtomicBot-ai/atomic-agent

一个本地优先的 AI agent，在您的机器上运行控制循环和所有状态。它可以驱动您的桌面：浏览网页、读取和编辑文件、运行批准的 shell 命令、检查文档、跨会话记住上下文、安排后续任务，以及通过 MCP 调用外部工具。您可以通过 HTTP 或 Tauri sidecar 将其嵌入到您自己的应用中。以 `llama.cpp` 为核心，因此小型量化模型在消费级硬件上也能胜任长时间、多步骤的工作。 ## 快速安装 macOS / Linux: ``` curl -fsSL https://atomicagent.io/install | sh ``` Windows (PowerShell): ``` irm https://atomicagent.io/install.ps1 | iex ``` 安装程序会下载发布归档文件，校验 checksum，并安装 CLI 以及支持资产（`grammars/`、原生预构建文件和内置的 `ripgrep`）。Atomic Agent 会自动进行原地更新；更新后，TUI 会提示您重新启动。 ### 运行 ``` atomic-agent ``` ### 故障排除 如果出现故障： 1. 复制您的错误日志和系统配置。 2. 在 [GitHub](https://github.com/AtomicBot-ai/atomic-agent/issues) 上提交 issue。 3. 或者在我们的 [Discord](https://discord.com/invite/Us7qXtDGw) 寻求帮助。 ## 基准测试 在公开的 **GAIA 验证 Level 1** 拆分集（53 项任务）中，Atomic Agent 和 Hermes 驱动了**相同**的本地 `qwen-3.6-35b-a3b`（`llama-server`，UD-Q4_K_XL），并设置了相同的步数预算和超时时间。唯一的变量是 agent 循环。  | 指标 | Atomic Agent | Hermes | |---|---|---| | **准确率** | **37/53 = 69.8%** | 31/53 = 58.5% | | 平均耗时 / 任务 | **~217 s** | ~351 s | | 胜负关系 | **+15 仅 atomic 获胜** | +9 仅 Hermes 获胜 |

图表（准确率与速度）

``` %%{init: {"themeVariables": {"xyChart": {"backgroundColor": "transparent", "titleColor": "#0b63f6", "plotColorPalette": "#0b63f6"}}}}%% xychart-beta title "GAIA L1 accuracy (higher is better, %)" x-axis ["Atomic Agent", "Hermes"] y-axis "Accuracy (%)" 0 --> 100 bar [69.8, 58.5] ``` ``` %%{init: {"themeVariables": {"xyChart": {"backgroundColor": "transparent", "titleColor": "#0b63f6", "plotColorPalette": "#0b63f6"}}}}%% xychart-beta title "Avg wall time per task (lower is better, s)" x-axis ["Atomic Agent", "Hermes"] y-axis "Seconds / task" 0 --> 400 bar [217, 351] ```

### 模型缩放 随着本地模型规模的缩小，相同的循环依然能够保持良好的性能。在相同的 GAIA L1 拆分集下，仅使用 Atomic Agent： | Chat 模型 | 准确率 | 平均耗时 / 任务 | |---|---|---| | `qwen-3.6-35b-a3b` (UD-Q4_K_XL) | **37/53 = 69.8%** | ~217 s | | `qwen-3.5-9b` (Q4_K_M) | **28/53 = 52.8%** | ~152 s | | `gemma-4-12b` (it-qat UD-Q4_K_XL) | **24/53 = 45.3%** | ~423 s | 即使是 9B 模型，通过相同的节省上下文的循环，也能完成 GAIA L1 一半的任务。（每行使用了不同的 Atomic Agent 版本；有关出处请参阅详细说明。） 完整的可复现说明：[`GAIA-L1-EXPERIMENT.md`](eval-agents/docs/GAIA-L1-EXPERIMENT.md) · 原始产物（矩阵、NDJSON 轨迹、日志）：[gaia-l1-eval-2026-06-11 发布版](https://github.com/AtomicBot-ai/atomic-agent/releases/tag/gaia-l1-eval-2026-06-11)。 ## 为何选择本地优先 控制循环和所有状态都在您的机器上运行，而不是在托管服务上： - **您的数据永远不会离开。** 会话、记忆、任务、轨迹、技能、浏览器配置和配置文件都保存在磁盘上的 `` 目录下。除非您主动配置，否则不会有任何数据外传。 - **无 API 费用。** 通过 `llama.cpp` 在本地运行量化模型。您可以自带 `llama-server`，或者让 CLI 为您管理一个。 - **没有任何隐藏。** 检查 prompt、回放轨迹漂移、编辑技能、替换组件，无需等待供应商。一切尽在普通的本地模型、SQLite 文件和 NDJSON 轨迹中。 - **在您的硬件上运行。** 小型量化模型可以在日常消费级 GPU 和 CPU 上运行，不需要数据中心。 ## 核心理念 ### Agent 循环如何工作 Agent 本质上是一个循环：模型选择一个动作，某处执行它，结果反馈回来，如此重复直到任务完成。问题在于成本。每一轮都会将不断增长的上下文重新发送给模型，因此简单的循环会随着每次迭代变得更慢、更昂贵，而小型本地模型会最先因为负载过重而崩溃。 Atomic Agent 保持了循环的低成本。一次推理生成一个包含工具调用的 JSON 数组，并在执行它们时无需在每一轮都重新编码整个世界状态： ``` flowchart LR A[Prompt] --> B[Decide] B --> C[Run] C --> D[Compress] D -->|not done| A D -->|done| E[Reply] ``` 1. **Prompt：** 将一个精简的 prompt 发送给本地模型。 2. **决策：** 模型返回一个包含工具调用的 JSON 数组，经过 grammar 检查，确保格式始终有效。 3. **执行：** 核心执行这些调用；独立的读取操作并行运行，危险动作会先请求许可。 4. **压缩：** 对结果和状态进行总结，而不是全量粘贴回来。 5. **重复：** 再次循环，直到给出回复、完成、取消或达到最大步数限制。 模型负责选择动作。Atomic Agent 则掌控循环、状态、审批、轨迹、停止条件和故障边界。 ### 专为本地模型打造 我们在自己开发的 TurboQuant `llama.cpp` 上运行本地模型 ([`AtomicBot-ai/atomic-llama-cpp-turboquant`](https://github.com/AtomicBot-ai/atomic-llama-cpp-turboquant))： - **TurboQuant KV-cache：** 基于 WHT 旋转的低比特量化技术，可将 KV-cache 相较于 F16 压缩高达约 6.4 倍，并搭配融合的 Metal 解码内核，让长上下文会话占用的内存大幅减少。 - **TurboQuant 权重：** 采用带 WHT 旋转和融合 Metal/Vulkan 内核的 Lloyd-Max 权重量化技术，在保持高质量的同时，让小模型也能在消费级硬件上运行。 - **自定义投机解码：** 专门构建的 Gemma 4 MTP 和 Qwen 3.6 NextN head 复用已加载的模型（无需加载第二个上下文、tokenizer 或模型），实现 +30-50% 的吞吐量提升。 - **精心挑选的量化模型：** 精选的 GGUF 量化版本，在满足真实 VRAM 预算的同时保持高准确率。 - **托管模式：** CLI 为您下载、固定版本并运行后端和模型，无需手动设置 `llama.cpp`。 ### 为小型本地模型优化 Atomic Agent 的 prompt 经过精心设计，使得小型模型永远不会浪费 token 或破坏格式： - **稳定前缀：** 人设、规则、工具、技能、能力和指令在会话内保持按字节级别的稳定，因此 `cache_prompt` 和 `slot_id` 可以复用 KV-cache，而不必在每一轮都重新编码 prompt。 - **限定尾部：** 对话、记忆、世界状态、回忆笔记、经验教训、操作流程和已加载的技能主体会被裁剪到一个可预测的 prompt 预算内。 - **状态外置：** 会话、记忆、任务、技能、轨迹、浏览器快照和模型配置都存在于 prompt 之外。 - **GBNF 工具调用：** 将补全结果约束为一个包含工具调用的 JSON 数组，包括单个调用的情况 `[{...}]`。 - **并行读取批次：** 独立的只读调用可以在一次推理后并发执行；危险动作仍需经过审批门控。 - **紧凑的浏览器视图：** 普通的网页操作使用无障碍 / ARIA 快照，而不是消耗大量截图的页面转储。 这就是为什么小型本地模型能够在长时间、重度依赖工具的工作中保持实用性的原因。 ## 功能一览 Atomic Agent 驱动着全面的桌面工具集。危险动作会经过审批流程；独立的只读调用则并行运行。 | 领域 | 功能 | |---|---| | **浏览器** | 通过 `playwright-core`（Chrome / Edge / Chromium）进行导航、点击、输入、搜索、管理标签页、滚动并读取紧凑的 ARIA 状态。 | | **Web & HTTP** | 使用可配置的提供商进行网络搜索，获取并提取网页（具备 SSRF 防护），以及发出任意的 HTTP 请求（独立于浏览器之外）。 | | **文件系统与 shell** | 读取、写入、编辑、打补丁、glob 匹配、grep 搜索、对比差异、监视、哈希计算、列出文件、解压归档、运行批准的 shell 命令，以及检查或终止进程。 | | **桌面** | 读取/写入剪贴板、桌面通知以及窗口列表/聚焦。 | | **文档** | 在本地提取 PDF, DOC, DOCX, XLSX, PPTX, ODT, RTF 和纯文本文件中的文本。 | | **Git** | 只读的状态查看、日志、对比差异、展示、追责 (blame) 和分支检查。 | | **记忆** | 配置文件事实、带有混合召回功能的笔记、链接、经验教训、操作流程、投票和反思。 | | **任务** | 持久化的延迟轮次、cron 定时任务、间隔触发、webhook 以及由 agent 创建的提醒。 | | **技能** | 查看并运行 Markdown 技能手册（脚本需经过审批），从 ClawHub 安装更多技能。内置 17 个入门技能（Docker、GitHub、Notion、Obsidian、PDF 等），首次运行时自动安装。 | | **视觉** | 为带有 `mmproj` 的多模态模型提供可选的 `vision.describe` 功能，保留在文本记录之外。 | | **MCP** | 连接外部 MCP server；它们的工具、资源和 prompt 会加入同一个注册表。 | | **提供商** | 默认使用本地 `llama-server`；配置后可支持兼容 OpenAI 的、OpenRouter 风格的以及 AI/ML API 提供商。 | | **Telegram** | 支持单用户远程控制，包含所有者配对和内联审批按钮。 | ### 在 Prompt 之外不断增长的记忆 Atomic Agent 的记忆不是简单地全量粘贴回 prompt 的巨大聊天日志。它是一个本地、可检查的存储库：持久的身份信息、情景笔记、关联关系、提炼出的经验教训和可重用的操作流程。Prompt 只能看到紧凑的指针，只有在 agent 需要时，才会通过工具调用检索完整的主体内容。 - **配置文件事实** 渲染到 `### profile` 中并带有上下文关键字门控；事实具有版本记录，并拥有可查询的历史。 - **笔记** 存储在 SQLite + FTS5 中，可选与 embedding 配合以实现混合召回。 - **链接** 将相关记忆连接成一个有界的图结构。 - **经验教训** 将重复发生的情景提炼为可重用的原则。 - **操作流程** 将操作指南模板化提炼出来且不会自动执行。 - **投票** 允许有用或有害的记忆、经验教训、操作流程和配置文件事实的权重上下浮动。 - **去重与淘汰** 合并近乎重复的记忆，并默认根据其实用性而非时间长短进行淘汰。 - **反思** 在轮次结束后运行，在主 agent 槽位之外进行，并在不阻塞回复的情况下写入记忆。 ## 使用方式

TUI 和 CLI

使用 CLI 进行简单的会话、自动化和调试。使用 TUI 作为交互式控制台：管理审批、日志、模型、技能、任务、记忆、MCP、Telegram 和轨迹。 ``` atomic-agent run --cwd /path/to/work atomic-agent tui --cwd /path/to/work atomic-agent skill list atomic-agent task list atomic-agent trace list --limit 10 ```

托管的本地模型

CLI 可以管理用于 chat 和 embedding 的配对 `llama.cpp` 设置： ``` atomic-agent models update atomic-agent models list atomic-agent models pull qwen-3.5-4b atomic-agent models use qwen-3.5-4b atomic-agent models list-embeddings atomic-agent models pull-embedding atomic-agent models use-embedding atomic-agent models start atomic-agent tui --cwd /path/to/work ``` 托管模式会下载后端、拉取 GGUF 模型、选择活动模型，并在配置后启动分离的 chat / embedding daemon。

外部 llama-server

已经有您自己的 `llama.cpp` 进程了？将 `atomic-agent` 指向它： ``` export ATOMIC_AGENT_LLAMA_URL=http://127.0.0.1:8080 ./llama-server -m Qwen3.5-9B-Q4_K_M.gguf \ --slots 4 \ --parallel 4 \ --port 8080 \ --cache-reuse 256 atomic-agent tui --cwd /path/to/work ```

兼容 OpenAI 的 HTTP

将 `atomic-agent` 作为本地 HTTP 服务运行： ``` atomic-agent serve \ --host 127.0.0.1 \ --port 8787 \ --cwd /path/to/work \ --api-key "$ATOMIC_AGENT_API_KEY" ``` `POST /v1/chat/completions` 将一个请求映射为一个完整的宏轮次：`user -> 0..N 工具步骤 -> 回复`。Atomic 特定的路由暴露了会话、审批、任务、webhook、事件、轨迹、配置和功能。

Tauri sidecar

sidecar 通过 stdio 传输换行分隔的 JSON，使其非常容易嵌入到桌面应用中： ``` {"kind":"request","id":"r-1","type":"start_session","payload":{"workingDir":"/home/me"}} {"kind":"request","id":"r-2","type":"send_message","payload":{"sessionId":"s-1","text":"Check the inbox and summarize urgent mail."}} ``` 随着轮次的运行，事件会以流的形式返回： ``` {"kind":"event","id":"e-1","type":"turn_started","correlationId":"r-2","payload":{"sessionId":"s-1","turnIndex":0}} {"kind":"event","id":"e-2","type":"tool_call_result","correlationId":"r-2","payload":{"sessionId":"s-1","stepIndex":0,"tool":"browser.read_aria","status":"ok","summary":"url: https://mail.google.com/ ..."}} {"kind":"event","id":"e-3","type":"assistant_reply","correlationId":"r-2","payload":{"sessionId":"s-1","text":"You have 3 urgent threads."}} ```

Telegram 远程控制

启用个人 Telegram 机器人并从您的手机驱动同一个 agent： ``` // /config.json { "telegram": { "enabled": true, "ownerUserId": null } } ``` ``` # /.env TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token ``` TUI 可以存储 token、启动通道、打开配对模式并显示状态。审批会作为内联按钮出现在您的私信中。Telegram 在设计上有意仅支持单用户。

MCP 客户端

在 `config.json` 中配置 MCP server，它们的工具就会像本地工具一样加入同一个注册表。受信任的只读 server 可以与其他读取操作一起批处理；不受信任的 server 默认需要经过审批才能执行。 ``` { "mcp": { "servers": [ { "name": "docs", "enabled": true, "transport": { "kind": "stdio", "command": "npx", "args": ["-y", "@example/mcp-server"] }, "trust": "pure_read" } ] } } ``` TUI 的 MCP 面板支持在不重启进程的情况下实时添加/删除。

## 安全性与可观测性 Atomic Agent 的所有操作都是可检查且可中断的： - **审批门控：** shell、文件系统写入、补丁、归档提取、进程终止、HTTP 请求、技能脚本和不受信任的 MCP 工具都受到策略的门控管理。 - **仅追加的轨迹：** prompt、补全、工具调用、结果、故障分类、投票和生命周期事件都将作为本地 NDJSON 记录。 - **Prompt 漂移重放：** `atomic-agent trace replay ` 将当前的稳定前缀哈希与记录的轨迹进行比较。 - **故障分类体系：** 跨事件、轨迹、指标、TUI、sidecar 和 HTTP 对传输、语法、模型、工具和取消引起的故障进行分类。 - **无进展保护：** 连续相同的工具调用在重复 3 次时会发出警告，在 5 次时执行硬性否决；在连续 3 次否决后，agent 将被迫输出一个优雅的回复。 - **按会话的 FIFO：** 所有接口都进入同一个 `TurnController`；一个会话内保持有序，而不同会话之间并发运行。 - **明确的状态：** 会话、记忆、任务、技能、浏览器配置文件、MCP 配置和轨迹都是普通的本地文件或 SQLite 数据库。 ### 隐私与流出流量 默认情况下，Atomic Agent 不需要托管的 agent 提供商。模型调用会发送到您配置的后端，本地生成的产物都保留在 `` 目录下。 本地优先界定了控制权所在的位置，而不是数据包的去向。只有在以下情况才会发生网络流出： - 浏览器导航到某个网站时； - HTTP 工具调用被请求的 endpoint 时； - 配置的云端 LLM 或 embedding 提供商接收到其请求时； - MCP server 接收到您路由给它的工具调用时。 这个承诺并不是什么神奇的魔力保密。它的真正承诺是：agent 的控制平面不需要放在远端。 ## 环境要求与配置

环境要求（Node, llama-server, 浏览器, git）+ Linux 注意事项

- 开发环境需要 Node.js；发布版本以 Node SEA 二进制文件形式提供。 - 可访问的 `llama-server`，由 `atomic-agent models` 管理或在外部启动。 - Chrome、Microsoft Edge 或其他已配置的 Chromium 系列可执行文件。不包含浏览器二进制文件。 - git 工具所需的 `git`。 - macOS 的工作流可能需要辅助功能、屏幕录制、自动化或提醒权限。 **Linux 注意事项：** - **桌面工具**（通过您的包管理器安装）：`ripgrep`（文件搜索；存在时使用内置的二进制文件）、`xclip`/`xsel`（X11）或 `wl-clipboard`（Wayland）用于剪贴板、`libnotify-bin` 用于通知、`wmctrl` 用于窗口控制（仅限 X11/XWayland）、`gio` (glib2) 或 `trash-cli` 用于 `fs.trash`。 - **浏览器：** Chromium 系列的沙盒在某些 Linux 环境下可能会失效（如容器、某些特定内核）。如果 Chrome 拒绝启动，请加上 `--no-sandbox` 运行。 - **GPU 加速（托管模式）：** 后端始终会启动，并在没有可用 GPU 驱动程序时回退到 CPU。要进行 GPU 卸载，请安装 Vulkan 驱动程序。Intel/AMD：`mesa-vulkan-drivers`（+ `vulkan-loader`/`libvulkan1`）；NVIDIA：自带的专有驱动捆绑了其 Vulkan ICD。设备在启动时自动选择；可以通过 `atomic-agent models use-device ` 覆盖，使用 `atomic-agent models devices` 检查，或在 TUI 的 Models 选项卡中按 `G` 键。

配置与机密（状态目录、环境变量、.env）

面向用户的配置位于 `/config.json` 中。 实用的环境变量： - `ATOMIC_AGENT_STATE_DIR`：状态、配置、技能、浏览器配置文件、记忆、任务、轨迹。默认为：`~/.atomic-agent`。 - `ATOMIC_AGENT_LLAMA_URL`：外部 `llama-server` 的 URL。 - `ATOMIC_AGENT_LLAMA_API_KEY`：可选的 `llama-server` bearer token。 - `ATOMIC_AGENT_LLAMA_MAX_TOKENS`：补全上限。 - `ATOMIC_AGENT_BROWSER_CHANNEL`：`chrome`、`msedge` 或 `chromium`。 - `ATOMIC_AGENT_BROWSER_EXECUTABLE_PATH`：明确的 Chromium 系列可执行文件路径。 - `ATOMIC_AGENT_BROWSER_CDP_URL`：通过 CDP 附加到已经在运行的浏览器。 用于技能和频道的机密信息应存放在 `/.env` 中，而不是放在 `config.json` 中： ``` NOTION_API_KEY=ntn_xxxxxxxx GITHUB_TOKEN=ghp_xxxxxxxx TELEGRAM_BOT_TOKEN=123456789:AA-your-bot-token EXA_API_KEY=exa_xxxxxxxx OBSIDIAN_VAULT_PATH=/Users/me/Documents/Obsidian Vault ``` Shell 导出的变量优先级高于 `.env` 中的定义。内置的解析器有意仅支持简单的 `KEY=VALUE` 行。

## 开发 ``` npm install npm run lint npm test npm run build ``` 核心文档： - [PROMPT.md](PROMPT.md)：prompt 解析 - [MEMORY.md](MEMORY.md)：记忆与召回 - [MEMORY_FABRIC_V2.md](MEMORY_FABRIC_V2.md) / [MEMORY_FABRIC_V2.5.md](MEMORY_FABRIC_V2.5.md)：记忆路线图 - [SKILLS.md](SKILLS.md)：技能格式 - [BUNDLING.md](BUNDLING.md)：发布打包 - [AGENTS.md](AGENTS.md)：贡献者不变式 ## 致谢 站在巨人的肩膀上构建： - [llama.cpp](https://github.com/ggml-org/llama.cpp)：TurboQuant 所基于的本地推理引擎 - [Playwright](https://github.com/microsoft/playwright)：agent 驱动的浏览器自动化工具 - [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)：用于本地记忆和状态的嵌入式 SQLite (FTS5) - [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)：外部工具和资源集成 - [Ink](https://github.com/vadimdemedes/ink) + [React](https://github.com/facebook/react)：终端 UI - [grammY](https://github.com/grammyjs/grammY)：Telegram 频道 - [pdf.js](https://github.com/mozilla/pdf.js)：由 Mozilla 开发的 PDF 文本提取工具 - [Tauri](https://github.com/tauri-apps/tauri)：agent 作为 sidecar 运行于其中的桌面外壳程序

标签：AI代理, GNU通用公共许可证, llama.cpp, MITM代理, Node.js, RAG, Tauri, 本地大模型, 特征检测, 网络调试, 自动化, 自动化攻击