为什么Antfarm的AI智能体不会「懵圈」？深入解析Ralph循环的新鲜会话与Git记忆机制

【免费下载链接】antfarmBuild your agent team in OpenClaw with one command.项目地址: https://gitcode.com/gh_mirrors/antf/antfarm

Antfarm是一个开源的 AI 智能体团队协作工具：一条命令就能在 OpenClaw 中组建一支由 planner、developer、verifier、tester、reviewer 组成的智能体团队，以可靠、可重复的工作流自动完成开发任务。很多用过 AI 编程工具的人都有过这种经历——智能体干着干着就开始"懵圈"：忘记自己改过什么、把上一轮的任务混进这一轮、甚至"幻觉"出一个不存在的状态。Antfarm 的解法很有意思，它没有试图让单个智能体"记住更多"，而是让每个智能体每次都是全新的，把记忆外包给 Git 仓库和进度文件。这套机制就叫做Ralph 循环（Ralph Loop），本文带你拆解它背后的设计。

为什么长对话会让 AI「失忆」甚至「幻觉」

先理解问题本身。传统做法是把一个大任务丢给一个智能体，让它在一个会话里从头做到尾。随着对话变长，会发生三件事：

• 上下文窗口膨胀：几十轮对话之后，早期的关键信息被挤到窗口边缘，智能体开始"顾此失彼"；
• 状态幻觉：智能体以为自己记得的中间状态，可能与仓库里的真实代码已经不一致；
• 错误累积：第 10 步基于第 8 步的一个小误解，整个任务就偏了，而且很难察觉。

Antfarm 项目文档里对这一点的态度非常直接："每个智能体都拿到干净的会话。没有上下文窗口膨胀，没有来自 50 条消息之前的幻觉状态。"（见 README.md）

Ralph循环：新鲜会话是「重置」，不是「重来」

Ralph 循环的核心思想可以概括为一句话：每次工作都在一个全新的会话中进行，跨会话的记忆不靠上下文，而靠持久化的外部载体。

在 Antfarm 中，这个模式被用在了智能体工作流的循环步骤上。以 workflows/feature-dev/workflow.yml 的开头注释为例：

Ralph loop — each agent runs in a fresh session with clean context. Memory persists via git history and progress files.

翻译过来就是：每个智能体都在干净上下文的独立会话中运行；记忆则通过Git 历史和进度文件来持久化。

新鲜会话是怎么落地的

Antfarm 的每个智能体都由一个独立的 cron 定时任务驱动。看 src/installer/agent-cron.ts 中创建定时任务的部分，sessionTarget: "isolated"是关键——每次轮询都在隔离的会话中运行，上一次会话的对话内容不会带入这一次。

再配合 src/installer/step-ops.ts 中的claimStep逻辑：智能体每次"认领"任务时，系统会把当前任务的完整上下文（任务描述、仓库路径、分支、已完成的 stories、进度文件内容等）一次性渲染进任务模板。换句话说，智能体不靠"回忆"工作，而是每次开工前把"工作交接单"完整重读一遍。

这正是 feature-dev 工作流中implement步骤的循环配置（workflows/feature-dev/workflow.yml）：

- id: implement agent: developer type: loop loop: over: stories completion: all_done fresh_session: true # 每个故事都开一个全新会话 verify_each: true verify_step: verify

fresh_session: true就是"新鲜会话机制"的开关：每实现一个用户故事，developer 智能体都会获得一个全新的会话，干净地开始。

Git记忆机制：把「脑子」换成「档案柜」

新鲜会话解决了"上下文污染"问题，但带来一个自然疑问：新会话的智能体怎么知道之前发生了什么？Antfarm 的答案是三个互补的持久化载体：

1. Git 历史 —— 代码本身的记忆

代码和提交记录就存在 Git 仓库里。每个新会话开工的第一件事就是git pull拉取分支最新代码（见 workflows/feature-dev/workflow.yml 中 implement 步骤的指令："Pull latest on the branch"）。上一位"同事"写了什么代码、改了什么文件，git log和git diff一看便知——这是最可靠、不会幻觉的记忆。

2. 进度文件 —— 结构化的交接笔记

除了代码本身，developer 智能体还被要求维护一份进度日志progress-<run-id>.txt（定义在 workflows/feature-dev/agents/developer/AGENTS.md）。每次会话结束前必须重写这份文件，内容包括：

• 每个已完成的故事：做了什么、改了哪些文件；
• Learnings：踩过的坑、发现的项目惯例；
• Codebase Patterns：写在文件最顶部，专门沉淀可复用的模式，例如"测试用 node:test 运行"、"API 路由都在某个目录下"。

下一个新鲜会话的智能体第一步就是读这份文件。这样，"我发现了什么"这类 Git 里看不到的隐性知识，也通过文件可靠地传递了下去。

3. SQLite 数据库 —— 工作流引擎的记忆

智能体之间的"组织记忆"则由 Antfarm 的调度引擎保管。src/installer/step-ops.ts 中的readProgressFile会从智能体工作区读取进度文件，并在认领步骤时把它注入到任务模板的{{progress}}变量中；而 runs、steps、stories 的状态与输出全部记录在 SQLite 里（src/db.ts）。所以"哪些故事做完了、当前卡在哪一步、验证失败的原因是什么"，引擎自己心里有数，不依赖任何智能体的记忆。

一个完整故事的流转：重置与记忆的协作

把上面三块拼起来，一个用户故事在 feature-dev 工作流里的旅程是这样的：

1. Planner把任务拆成若干用户故事（每个故事小到"一个上下文窗口能装下"）；
2. Developer在新鲜会话中认领故事 1：读进度文件 → 拉取最新代码 → 实现并写测试 → 提交 → 重写进度文件；
3. Verifier在另一个独立会话中验收（角色权限上它甚至没有写权限，只能读和执行测试），不合格则带着ISSUES反馈打回重做；
4. 故事 1 完成后，developer 再次以全新会话开始故事 2——它对故事 1 一无所知，但通过进度文件、Git 提交和数据库中的completed_stories列表，拿到了完整、可信的交接信息。

这套"做完即重置、交接靠档案"的循环，让 20 个故事跑下来，智能体的注意力依然像第一个故事时那么"清醒"——因为它每次都确实是在第一个故事的状态。

失败也不怕：重试、升级与自我修复

新鲜会话机制还带来一个隐藏好处：重试是廉价的。失败的故事被重置为pending后（src/installer/step-ops.ts 的failStep），下一次执行就是一个带上了验证反馈的干净会话，不会在"上次失败时的错误上下文"里越陷越深。

此外还有两道保险：

• 遗弃步骤清理：cleanupAbandonedSteps（src/installer/step-ops.ts）会找出"认领了却没干完"的卡死步骤，按智能体超时阈值自动重置回待办，保证流程不会静默卡死；
• 人工升级：每个步骤都配置了max_retries和on_fail: escalate_to: human，重试耗尽后会主动通知你，而不是默默失败。

小结：少即是多的智能体工程

Antfarm 给我们新手的一个启示是：让 AI 团队协作稳定，不一定要"更强的记忆"，确定性的流程 + 干净的上下文 + 可靠的持久化交接，往往比一个"什么都记得"的智能体更靠谱。如果你想深入了解整套设计，推荐从 README.md 的 "Built on the Ralph loop" 一节读起，再配合 docs/creating-workflows.md 里的 "Loop Steps (Story-Based)" 章节，看看fresh_session、verify_each等字段如何组合出自己的多智能体流水线。

【免费下载链接】antfarmBuild your agent team in OpenClaw with one command.项目地址: https://gitcode.com/gh_mirrors/antf/antfarm