AI智能体结构化工作空间模板：用文件系统解决记忆与角色漂移难题

1. 项目概述一个为AI智能体设计的结构化工作空间模板如果你正在尝试构建一个多智能体系统或者哪怕只是一个需要长期记忆和稳定身份的单一AI助手你很可能已经遇到了一个核心难题如何让AI在多次会话中保持连贯的“人格”和“记忆”每次对话重启模型就像被重置了一样之前的决策逻辑、学到的经验、甚至项目上下文都可能丢失。为了解决这个问题开发者们往往需要搭建复杂的向量数据库、设计精巧的提示工程或者编写冗长的上下文管理代码。但有没有一种更简单、更本质的方法今天要聊的这个agent-template项目就提供了一种极简而优雅的答案。这个由 ExpertVagabond 维护的模板本质上是一个为AI智能体设计的标准化工作空间文件结构。它不依赖任何特定的框架或基础设施仅仅通过一组约定俗成的Markdown文件就定义了智能体的身份、职责、记忆和自维护协议。它的核心思想是“文件即状态结构即规范”将智能体的长期记忆和角色认知从脆弱的提示词和临时的会话中固化到可版本控制、可复制的文件系统里。无论是用于大名鼎鼎的 Antfarm 多智能体开发流水线还是集成到你自己的AI应用里这套模板都能立刻解决智能体“健忘”和“角色漂移”的顽疾。2. 核心设计哲学为什么是文件而不是数据库在深入文件细节之前我们得先理解这个模板背后最根本的设计选择为什么用纯文本的Markdown文件而不是更“先进”的向量数据库或专用存储这恰恰是项目最精妙的地方。对于AI智能体尤其是开发类智能体其工作产出代码、文档和协作媒介Git提交、PR描述本身就是文本。将记忆和身份也文本化实现了媒介的统一。2.1 基础设施零依赖的优势首先文件系统是任何计算环境中最普遍、最稳定的存在。这意味着你的智能体工作空间可以在任何地方运行本地开发机、CI/CD流水线、云端容器甚至是离线环境。你不需要为了管理智能体的记忆而去部署和维护一个向量数据库服务这极大地降低了系统的复杂性和运维成本。对于初创项目或需要快速原型验证的场景这种“开箱即用”的特性是无价的。其次Git友好性。所有的记忆文件MEMORY/目录下的内容都是纯文本可以自然地纳入版本控制。每一次智能体的运行、每一次决策、每一条经验教训都可以通过Git提交历史来追溯和回滚。这为调试智能体行为、分析其决策路径提供了前所未有的透明度和可审计性。想象一下你可以像git blame代码一样去追溯某条关键决策是由哪次会话中的智能体做出的依据是什么。2.2 结构即约束文件即接口这个模板的另一个核心哲学是通过文件结构来强制分离关注点。它将一个智能体的复杂状态清晰地拆解为几个具有单一职责的部分身份与职责(AGENTS.md,SOUL.md)定义“我是谁”和“我该做什么”。运行时记忆(MEMORY/下的文件)记录“我经历过什么”和“我现在在哪儿”。维护协议(HEARTBEAT.md)规定“我如何保持健康”。这种强制分离避免了将所有信息都堆砌在一个庞大的提示词或上下文窗口里。当你要修改智能体的行为时你很清楚该去编辑哪个文件。例如想调整它的决策风格就去改SOUL.md想让它记住一个新的项目规范就更新MEMORY/context.md。这种清晰度对于长期维护和团队协作至关重要。3. 文件结构深度解析每个文件的使命与实操让我们像拆解一个精密仪器一样逐个文件地深入这个模板。理解每个文件的具体内容、更新频率和交互逻辑是你能否用好它的关键。3.1 身份基石AGENTS.md 与 SOUL.md这两个文件共同构成了智能体的“宪法”通常在一次设定后很少改动除非智能体的核心角色发生变更。AGENTS.md智能体的岗位说明书这个文件回答“做什么”和“怎么做”。它不应该是一个模糊的愿景描述而应该是一份可操作、可验证的行动指南。一个优秀的AGENTS.md应该包含明确职责范围清晰列出智能体被授权执行的所有任务类型。例如对于一个“代码审查智能体”其职责可能包括检查代码风格、寻找潜在bug、评估性能影响、验证测试覆盖率。详细的工作流程一步一步地描述智能体处理一个任务的典型步骤。这能极大地提高其行为的可预测性和一致性。例如“1. 读取本次提交的diff。2. 对照项目编码规范逐行检查。3. 运行静态分析工具并解析结果。4. 综合以上信息生成包含优先级高/中/低的审查意见。”具体的验收标准定义什么是“完成任务”。标准必须客观、可衡量。例如“生成的审查意见必须至少包含3条实质性建议”、“所有指出的语法错误必须附有修复示例代码”、“对于高优先级问题必须引用相关的项目文档条目”。可用工具列表明确智能体可以调用哪些外部工具或命令。例如“你可以使用eslint进行JavaScript代码检查使用grep搜索特定模式可以读取package.json和tsconfig.json文件。”实操心得编写AGENTS.md时不妨想象你在给一个非常敬业但缺乏常识的新人实习生写指导手册。越细致、越没有歧义效果越好。避免使用“写出高质量的代码”这种主观表述取而代之的是“函数长度不超过50行”、“必须为公开API添加JSDoc注释”等具体规则。SOUL.md智能体的价值观与沟通风格这个文件定义“如何思考”和“如何表达”。它塑造了智能体的“人格”影响其决策权衡和沟通方式。内容可以包括核心原则与价值观例如“安全优于性能”、“可读性优于巧妙的技巧”、“在提出问题时必须同时提供至少一个解决方案选项”。决策框架当面临选择时智能体应遵循的思考路径。例如“在优化方案选择上优先考虑方案A简单明了除非方案B能带来超过50%的性能提升且复杂度增加可控。”沟通语气与格式规定智能体输出内容的风格。例如“所有反馈采用‘观察-影响-建议’三段式结构”、“使用平和、专业的语气避免感叹号”、“代码示例使用Markdown代码块并指定语言”。禁忌与边界明确什么不该做。例如“不得对开发者的能力进行人身评价”、“不得建议使用已知存在严重安全漏洞的第三方库”。SOUL.md的妙处在于它能将团队文化或项目规范“编码”进智能体。一个激进创新的原型项目和一个保守稳定的金融系统它们的智能体应该拥有截然不同的“灵魂”。3.2 动态记忆MEMORY/ 目录的协同工作记忆目录是智能体在多次运行间保持连续性的核心。四个文件各司其职共同构成一个不断进化的“经验库”。MEMORY/context.md当前会话的快照这是每次会话都必须更新的文件。它回答“我们现在在项目的什么位置”。内容应包括当前正在处理的功能模块、相关的API接口、已达成共识的设计决策、本次会话要达成的具体目标等。它就像是智能体工作台面上摊开的所有相关图纸和笔记。更新时机会话开始时读取会话中随着进展不断更新会话结束时保存最终状态。这确保了即使会话意外中断下次也能从“断点”续上。示例## 当前项目状态 (2023-10-27) **项目**用户认证微服务 **当前焦点**实现“忘记密码”功能的重置邮件发送模块。 **进展** - 已设计 PasswordResetService 接口包含 generateResetToken 和 sendResetEmail 方法。 - 邮件模板 (reset_email.html) 已初步完成位于 /templates/ 目录。 - 待办集成邮件发送服务SMTP配置编写单元测试。 **相关文件** - src/services/PasswordResetService.ts - src/config/smtp.ts - templates/reset_email.htmlMEMORY/decisions.md决策日志这是一个只追加的文件。记录所有重要的、有争议的或可能被遗忘的决策及其背后的理由。目的避免智能体或后续的维护者反复讨论已经解决的问题。它提供了决策的“上下文”解释了“为什么我们选择了方案A而不是方案B”。格式建议采用时间线或条目式记录每个决策包含日期、问题描述、考虑的选项、最终选择及原因。## 决策记录 * **2023-10-26**: 选择邮件服务提供商 * **问题**需要为密码重置功能选择一个邮件发送服务。 * **选项**A) 直接使用Nodemailer配置公司SMTP B) 使用SendGrid第三方API。 * **决策**选择A。 * **理由**本项目对邮件发送量预期较低直接SMTP更简单、无额外成本、且符合公司对内部服务数据不出域的安全要求。SendGrid的高级功能如数据分析目前非必需。MEMORY/lessons.md经验模式库同样是一个只追加的文件。用于记录从成功或失败中总结出的通用模式、最佳实践或有效技巧。目的让智能体“越用越聪明”。例如它可能记录下“在本代码库中使用async/await处理数据库查询时务必用try-catch包裹并将错误日志写入app.log文件而非仅控制台输出。”与decisions.md的区别decisions.md记录具体的、一次性的选择lessons.md提炼抽象的、可复用的知识。MEMORY/blockers.md已知问题与变通方案这是一个动态维护的列表。记录当前阻碍进展的已知问题、bug或限制以及临时解决方案。目的防止智能体在每次运行时都在同一个问题上“撞墙”。它像一个团队内部的“已知问题wiki”。内容每个阻塞项应描述问题现象、根本原因如果已知、影响范围以及当前可用的变通方案或跟踪链接如Issue编号。## 当前阻塞项 * **问题**在Docker构建时sharp 原生模块编译失败。 * **原因**构建环境缺少 libvips 库。 * **影响**所有涉及图像处理的部署。 * **变通方案**在Dockerfile中使用 npm install --ignore-scripts 跳过 sharp 的编译并改用预构建的二进制版本。长期方案已创建Issue #45。3.3 自我维护协议HEARTBEAT.md这个文件定义了智能体如何“照顾自己”防止在长期运行后产生状态腐化或性能下降。它通常包含一些周期性任务的检查清单。健康检查例如检查工作空间目录是否超过一定大小、临时文件是否需要清理、依赖版本是否需要更新。清理任务定期归档旧的日志文件、删除node_modules/.cache等缓存目录。报告生成定期总结一段时间内的工作成果、决策数量、解决的问题等形成简报告知用户。更新时机这个文件的执行频率远低于记忆文件的更新。可能每运行10次、或每周执行一次其中的检查项。它确保了智能体工作空间的长期整洁和高效。4. 集成实践如何在你自己的项目中落地理解了每个文件的作用后下一步就是将其融入你的智能体工作流。无论你是使用现成的框架还是自研系统集成模式都是相通的。4.1 与Antfarm等框架的集成如项目所述在Antfarm的配置中你可以直接为每个智能体角色指定其专属的工作空间文件。agents: - id: architect name: 系统架构师 workspace: files: AGENTS.md: agents/architect/AGENTS.md SOUL.md: agents/architect/SOUL.md HEARTBEAT.md: agents/architect/HEARTBEAT.md MEMORY/: agents/architect/MEMORY/在这种模式下框架会在智能体启动时自动将这些文件的内容作为系统提示词或初始上下文加载给LLM。在智能体运行过程中框架会提供API或指令让智能体能够更新MEMORY/context.md或向decisions.md等文件追加内容。会话结束时框架负责将最终的记忆状态写回文件。4.2 在自定义智能体中的手动集成如果你在构建自己的智能体循环集成同样直接。核心逻辑如下初始化阶段在智能体启动时读取AGENTS.md、SOUL.md和MEMORY/下的所有文件内容将它们拼接成一个强大的、结构化的“超级提示词”作为本次会话的初始指令和上下文。运行阶段设计你的智能体指令使其在做出重要决策后能输出一段格式化的文本如## DECISION: ... REASON: ...。在发现有效模式或遇到阻塞时也能输出对应的格式化记录。收尾阶段在会话结束时编写一个后处理脚本解析智能体本次运行产生的所有输出。将最新的项目状态更新到MEMORY/context.md覆盖写入。将识别到的决策、经验、阻塞项分别追加到decisions.md、lessons.md、blockers.md追加写入。定期如每10次运行触发HEARTBEAT.md中定义的清理和检查任务。这个过程可以用一个简单的Python脚本来示意import os from datetime import datetime class AgentMemoryManager: def __init__(self, agent_workspace_path): self.workspace agent_workspace_path def load_agent_context(self): 加载智能体身份和记忆 context for file in [AGENTS.md, SOUL.md, MEMORY/context.md, MEMORY/blockers.md]: path os.path.join(self.workspace, file) if os.path.exists(path): with open(path, r, encodingutf-8) as f: context f\n\n## From {file}:\n{f.read()} return context def save_session_memory(self, new_context, decisions, lessons, blockers): 保存本次会话记忆 # 更新当前上下文 with open(os.path.join(self.workspace, MEMORY/context.md), w) as f: f.write(new_context) # 追加决策和经验 self._append_to_file(MEMORY/decisions.md, decisions) self._append_to_file(MEMORY/lessons.md, lessons) # 更新阻塞列表可能需要合并去重 self._update_blockers(blockers) def _append_to_file(self, filename, content): if content: path os.path.join(self.workspace, filename) with open(path, a, encodingutf-8) as f: f.write(f\n\n## Entry on {datetime.now().date()}:\n{content})4.3 多智能体协作中的工作流WORKFLOWS.md文件则指导了多个智能体如何接力工作。其核心思想是上一个智能体的输出尤其是MEMORY/context.md是下一个智能体的主要输入。例如一个经典的“规划-开发-测试”流水线规划智能体接收需求输出技术方案和任务分解并更新自己的context.md包含架构图、API设计等。开发智能体启动时不仅读取自己的身份文件还会读取规划智能体的context.md作为项目背景。它进行编码并更新自己的context.md包含实现的模块、遇到的代码问题等。测试智能体启动时读取开发智能体的context.md和代码变更生成测试用例并执行。它将测试结果和发现的bug记录到自己的blockers.md中。通过这种context.md的传递知识和工作状态在智能体间实现了无损流动形成了一个真正的协作团队而不是几个孤立的任务执行器。5. 高级技巧与避坑指南在实际使用这套模板一段时间后我积累了一些能极大提升效率的经验和需要避免的陷阱。5.1 编写高质量身份文件的技巧为AGENTS.md编写“测试用例”在定义验收标准时尝试构思几个具体的输入输出示例。这不仅能帮你理清要求未来甚至可以用来做智能体输出的自动化验证。在SOUL.md中注入“元认知”可以加入这样的指令“如果你对某个任务要求不确定应主动列出你的理解并请求澄清而不是基于猜测执行。” 这能减少智能体因误解而做无用功的情况。版本化身份文件当智能体角色需要重大调整时不要直接覆盖旧文件。可以像AGENTS_v2.md这样进行版本管理并在decisions.md中记录升级的原因和日期。5.2 高效管理记忆系统定期回顾与提炼lessons.md和decisions.md文件会随时间增长。建议定期如每月人工回顾将过于具体或过时的条目归档将重复出现的模式提炼成更简洁的准则甚至可以反向更新到AGENTS.md中。为context.md设计模板强制要求context.md必须包含几个固定章节如“目标”、“进展”、“下一步”、“待决问题”。这能保证信息的结构化便于智能体和人类快速抓取重点。处理冲突更新在多智能体并行修改同一记忆文件如blockers.md时可能会遇到Git冲突。一个简单的策略是规定每个智能体只负责更新自己“名下”的区块或者使用文件锁等机制。对于简单场景也可以接受在合并时手动解决冲突这本身也是一个审查过程。5.3 常见问题与解决方案问题上下文长度爆炸。智能体运行多次后MEMORY/下的文件内容越来越多全部加载会超出LLM的上下文窗口。解决方案实现一个“上下文窗口管理器”。策略包括1) 只加载最近N次的context.md快照2) 为decisions.md和lessons.md生成一个基于时间的摘要3) 仅加载与当前任务高度相关的阻塞项。核心是动态选择最相关的记忆而不是加载全部。问题记忆信息过时或错误。智能体早期基于不完整信息做出的错误决策被记录在案可能误导后续运行。解决方案建立记忆的“置信度”或“状态”标签。例如在decisions.md中可以为每个决策添加status: valid|superseded|deprecated标签。HEARTBEAT.md中的维护任务可以包括“审查并标记过时的决策”。问题智能体不按格式更新记忆。LLM的输出可能不稳定导致后处理脚本无法正确解析出需要保存的记忆片段。解决方案在给智能体的指令中严格要求其使用非常明确、无歧义的分隔符来标记需要保存的内容。例如要求所有决策记录必须以%%% DECISION START %%%和%%% DECISION END %%%包裹。同时后处理脚本要有一定的容错和日志记录能力当解析失败时能发出警告而不是静默丢失记忆。6. 模板的扩展与定制化思考agent-template提供的是一个优雅的最小可行结构。在实际复杂项目中你完全可以也应当对其进行扩展。添加TOOLS.md如果你的智能体可以使用多种外部工具API、命令行、数据库可以单独创建一个工具说明书文件详细描述每个工具的调用方式、参数、返回格式和错误处理这比全部堆在AGENTS.md里更清晰。添加PROJECT_KNOWLEDGE.md对于大型项目可以将项目特有的领域知识、业务规则、架构规范等静态信息单独存放与动态的MEMORY/context.md分离。记忆文件的子目录化当项目非常庞大时可以考虑在MEMORY/下创建子目录如MEMORY/sprint_12/来按迭代管理记忆或者MEMORY/frontend/、MEMORY/backend/来按模块划分。这套模板的魅力在于它的简单和本质性。它没有发明任何复杂的新概念只是用一种极其清晰的方式将我们人类团队协作中天然存在的“角色定义”、“工作记录”和“经验传承”机制翻译成了AI智能体能够理解和使用的语言。它或许不是解决智能体记忆问题的唯一方案但它一定是理解这个问题本质的最佳起点。