Atomic Agent 源码阅读与贡献指南：从 AGENTS.md 不变式到三大评测框架

Atomic Agent 源码阅读与贡献指南：从 AGENTS.md 不变式到三大评测框架

【免费下载链接】atomic-agentAtomic Agent is a local-first AI agent. Runs open-weight models on your own machine via llama.cpp.项目地址: https://gitcode.com/gh_mirrors/at/atomic-agent

Atomic Agent（atomic-agent）是一个本地优先的 AI 智能体项目：它通过 llama.cpp 在你自己的机器上运行开源权重量化的本地模型，驱动浏览器、编辑文件、执行受审批的命令，并在会话之间记忆上下文。想读懂它的源码并贡献代码？关键路径只有两条——先吃透 AGENTS.md 里写给自动化贡献者的架构不变式，再弄明白eval/、eval-agents/、eval-memory/三大评测框架分别在验证什么。本文带你完成这次源码之旅。

一、项目全貌：为什么它是"本地优先"

Atomic Agent 的核心承诺是：控制循环和全部状态都运行在你的机器上。它由三类入口组成：

• CLI（atomic-agent）：本地调试与自动化，见 src/cli/
• Tauri 侧车：以 NDJSON over stdin/stdout 协议嵌入桌面应用，见 src/sidecar/
• HTTP 服务：atomic-agent serve暴露 OpenAI 兼容接口，见 src/http/

模型侧则连接一个外部的llama-server（llama.cpp），LLM 运行时、模型权重都不属于本项目。所有 LLM 步骤都被压在约 2.5k token 以内——这是理解整个代码库的钥匙。

二、AGENTS.md：贡献者的第一份地图

AGENTS.md 自称是"自动化贡献者（LLM 智能体、代码生成）的 source-of-truth"。对人类贡献者，它同样是最快的入门读物。它开篇就给出六条使命级约束，其中最值得记住的四条架构不变式是：

1. 项目 ≠ 提示词（Project ≠ Prompt）

会话状态、压缩后的工具结果、世界快照都存放在模型外面，提示词永远只是其中一小片。这样智能体才能无限跑，而不会把上下文撑爆。

2. 稳定前缀（Stable Prefix）

提示词按"稳定前缀 + 可变尾部"组织：buildStablePrefix（persona + rules + skills 目录 + tools + capabilities + instructions）在一个会话内字节级稳定，让 llama-server 的 KV-cache（cache_prompt + slot_id）可以复用；### conversation之后才是每一步都可能变化的尾部。改前缀 = 一次性失效缓存，这就是为什么技能安装、工具角色切换都被谨慎对待。

3. 每步一次推理（One inference per step）

模型单次推理输出一个JSON 工具调用数组（[{tool, args}, ...]），循环由运行时驱动，而不是模型内部自转。运行时用资源类别（pure_read并行、写操作串行、审批门工具必须单独执行）把"读 4 个 CSV"从 4 次串行调用压缩成 1 个批量步骤——核心实现在 src/agent/batch-executor.ts 与 src/agent/tool-resource-class.ts。

4. 语法约束的工具调用（GBNF）

每次需要工具调用的补全请求都附带一份 GBNF 语法（grammars/tool-call.gbnf），保证小模型输出的格式永远合法。根规则被刻意收敛为仅数组，消除小模型"首 token 偏向{而非["的陷阱。

除此之外，AGENTS.md 还规定了布局规则（按特性分目录、每文件一个职责、单文件不超过 300 行、测试与源码同目录命名）和一份完整的模块地图（src/agent/负责循环、src/tools/负责工具、src/memory/负责记忆织物、src/llm/负责提供方抽象……），是定位任何改动落点的第一索引。

💡 提示：AGENTS.md 里几乎每条"锁定不变式（Locked invariants）"后面都附了对应测试文件的相对路径（如 src/agent/loop-detector.test.ts）。读不变式 → 跳测试 → 回读实现，是最高效的源码阅读顺序。

三、三大评测框架：智能体行为如何被验证

这个项目有三个平级的评测目录，各测不同维度。理解它们是"贡献评测用例"的前提。

1.eval/—— 端到端行为评测

eval/README.md 解释了它为什么独立于npm test：单元测试必须快且封闭，而每个用例都要真实拉起一个atomic-agent run子进程、喂一条提示词、然后断言三样东西：助手回复（正则）、文件系统结果、会话 trace（调用了哪些工具、状态如何）。

• 用例目录：eval/cases/ —— 一个场景一个.case.ts文件，例如fs-grep-todo.case.ts、coding-fix-cart-total.case.ts
• 运行：npm run eval（需先配置 eval/.env.example 里的ATOMIC_AGENT_EVAL_LLAMA_URL）
• 开放式用例（摘要类）走LLM-as-judge期望，默认用云端评审模型，避免"7B 模型给自己作业打分"的偏差

添加用例三步走：在eval/cases/新建<id>.case.ts→ 在 eval/cases/index.ts 追加导出 → 跑npm run eval:lint。报告输出为 CSV + JSONL，failures列能帮你定位是哪一类回归。

2.eval-agents/—— 多智能体 GAIA 基准

eval-agents/README.md 描述了一场"控制变量"实验：atomic-agent、Hermes、OpenClaw 三个智能体跑同一个本地聊天模型、同一份 GAIA validation Level 1 数据集（53 题），唯一变量是智能体循环本身。

• 评分路径完全确定性：从回复中提取FINAL ANSWER:行，再用官方 GAIA 评分器归一化比较（eval-agents/harness/score-gaia.ts），评分链路里没有 LLM 评审
• 每个任务独立的工作目录 + 状态目录，跑完先拷出 trace 再清理
• 环境快照（模型、git SHA、采样参数）写入environment.json，保证可复现

README 里的基准结论（同一qwen-3.6-35b-a3b下 Atomic Agent 69.8% vs Hermes 58.5%、单任务均时 217s vs 351s）的完整实验记录就在 eval-agents/docs/GAIA-L1-EXPERIMENT.md——它同时展示了"可复现实验写文档"的良好范式。

3.eval-memory/—— 记忆织物专项评测

eval-memory/PLAN.md 说清了它为什么单独存在：eval/测"一次一题"，记忆评测需要相反的轴——多轮共享stateDir的配对运行（记忆开/关）、对memory.sqlite的直接检查，以及绕过智能体直接调用MemoryStore的检索精度实验。

实验分几族，每个都在 eval-memory/experiments/ 下有独立目录：

每个实验都写明了"判定边界"（decision boundary），例如 E1 规定"混合召回 P@5 不领先 BM25 至少 5 个百分点，就把memory.embeddings.enabled默认值翻回false"——评测结论直接反哺配置决策，这是非常值得学习的贡献文化。

四、贡献前的动手清单

1. 读 AGENTS.md：使命、六条不变式、模块地图、布局规则
2. 跑构建与测试：npm install→npm run lint→npm test→npm run build（CLI 入口是 src/cli/index.ts，侧车入口是 src/sidecar/main.ts）
3. 读配套文档：PROMPT.md（提示词解剖）、MEMORY_GUIDE.md（记忆全链路）、MEMORY_FABRIC_V2.md（记忆织物设计）
4. 改代码时：每个新工具必须在TOOL_RESOURCE_CLASS和默认参数 schema 中登记（有测试强制检查）；文件超过 300 行先拆分
5. 改行为时：想清楚它落在哪一层评测——单步行为进eval/用例，跨智能体对比进eval-agents/，记忆相关进eval-memory/

五、写在最后

Atomic Agent 的源码像一份"可执行的工程手册"：AGENTS.md 把不变式、原因、反例和锁定测试写在同一页；三个评测目录把"智能体到底行不行"拆成了行为正确性、基准竞争力、记忆有效性三条可度量的轴。对新手而言，从 eval/cases/ 里挑一个简单的fs-*.case.ts用例读起，顺着 harness 反向追到src/agent/，是性价比最高的入门路线——你读到的每一行不变式背后，都是真实线上事故换来的教训。

【免费下载链接】atomic-agentAtomic Agent is a local-first AI agent. Runs open-weight models on your own machine via llama.cpp.项目地址: https://gitcode.com/gh_mirrors/at/atomic-agent