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-agentAtomic Agentatomic-agent是一个本地优先的 AI 智能体项目它通过 llama.cpp 在你自己的机器上运行开源权重量化的本地模型驱动浏览器、编辑文件、执行受审批的命令并在会话之间记忆上下文。想读懂它的源码并贡献代码关键路径只有两条——先吃透 AGENTS.md 里写给自动化贡献者的架构不变式再弄明白eval/、eval-agents/、eval-memory/三大评测框架分别在验证什么。本文带你完成这次源码之旅。一、项目全貌为什么它是本地优先Atomic Agent 的核心承诺是控制循环和全部状态都运行在你的机器上。它由三类入口组成CLIatomic-agent本地调试与自动化见 src/cli/Tauri 侧车以 NDJSON over stdin/stdout 协议嵌入桌面应用见 src/sidecar/HTTP 服务atomic-agent serve暴露 OpenAI 兼容接口见 src/http/模型侧则连接一个外部的llama-serverllama.cppLLM 运行时、模型权重都不属于本项目。所有 LLM 步骤都被压在约 2.5k token 以内——这是理解整个代码库的钥匙。二、AGENTS.md贡献者的第一份地图AGENTS.md 自称是自动化贡献者LLM 智能体、代码生成的 source-of-truth。对人类贡献者它同样是最快的入门读物。它开篇就给出六条使命级约束其中最值得记住的四条架构不变式是1. 项目 ≠ 提示词Project ≠ Prompt会话状态、压缩后的工具结果、世界快照都存放在模型外面提示词永远只是其中一小片。这样智能体才能无限跑而不会把上下文撑爆。2. 稳定前缀Stable Prefix提示词按稳定前缀 可变尾部组织buildStablePrefixpersona rules skills 目录 tools capabilities instructions在一个会话内字节级稳定让 llama-server 的 KV-cachecache_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 JSONLfailures列能帮你定位是哪一类回归。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/ 下有独立目录族代表实验回答的问题微基准E1混合召回精度BM25向量混合召回是否比纯 BM25 强链接图扩展是精度增益还是噪声配对会话E2多轮记忆 ON vs OFF记忆开着时任务正确率是否更高、或工具调用更少质量审计E3–E6反思/蒸馏/投票审计反思写入的记忆有多少是有用 / 琐碎 / 错误生命周期基准E7/E8纯确定性、无 LLM按年龄淘汰、投票弃用是否严格按契约执行长对话基准LoCoMo、LongMemEval跨会话单跳/多跳/时间/开放域/对抗性问题的召回E2E跨会话画像召回、教训应用、过时事实会话 N 形成的知识能否影响会话 N1每个实验都写明了判定边界decision boundary例如 E1 规定混合召回 P5 不领先 BM25 至少 5 个百分点就把memory.embeddings.enabled默认值翻回false——评测结论直接反哺配置决策这是非常值得学习的贡献文化。四、贡献前的动手清单读 AGENTS.md使命、六条不变式、模块地图、布局规则跑构建与测试npm install→npm run lint→npm test→npm run buildCLI 入口是 src/cli/index.ts侧车入口是 src/sidecar/main.ts读配套文档PROMPT.md提示词解剖、MEMORY_GUIDE.md记忆全链路、MEMORY_FABRIC_V2.md记忆织物设计改代码时每个新工具必须在TOOL_RESOURCE_CLASS和默认参数 schema 中登记有测试强制检查文件超过 300 行先拆分改行为时想清楚它落在哪一层评测——单步行为进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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考