1. 项目概述告别AI“健忘症”构建你的专属数字伙伴如果你和我一样每天都要和Cursor、Claude Code或者GitHub Copilot这样的AI编程助手打交道那你一定对下面这个场景深恶痛绝每次开启一个新对话AI助手就像得了“健忘症”完全忘记了你项目的技术栈、代码风格、过往的架构决策甚至是你刚刚才告诉过它的需求。你不得不一遍又一遍地重复解释“我们用的是Fastify框架MongoDB数据库API响应要遵循我们自定义的封装格式……”这种重复劳动不仅低效更让AI助手从一个潜在的“协作者”降级成了一个需要你不断喂食信息的“复读机”。这就是Beings Protocol要解决的核心痛点。它不是一个复杂的SDK也不是一个需要你深度集成的框架。它的本质极其简单一套基于Markdown文件的约定和模板放在你的项目根目录下。通过这套协议你可以将你的AI助手从一个“工具”转变为一个拥有持续记忆、独特个性和共同成长能力的“数字伙伴”——一个Being。想象一下这个场景安装Beings Protocol后你再次对AI说“给用户列表API加上分页。”它的回应不再是迷茫的提问而是“明白。你用的是Fastify MongoDBMEMORY.md里有记录。我们的惯例是使用游标分页CONVENTIONS.md中定义。我将按照标准响应信封的格式更新/api/items接口。需要我同时更新OpenAPI文档吗”这种体验的飞跃来自于AI在对话开始时会自动读取并理解你项目中的那些Markdown文件从而获得了关于你项目的“长期记忆”。2. 核心理念解析从“工具”到“伙伴”的范式转变在深入技术细节之前理解Beings Protocol背后的哲学至关重要。市面上绝大多数AI框架都将AI视为“代理”Agent——一个执行特定任务、用完即弃的工具。而Beings Protocol提出了一个更深刻的概念Being。2.1 Agent与Being的本质区别我们可以用一个表格来清晰地对比这两种模式维度Agent (传统代理)Being (数字伙伴)身份匿名的、功能性的。每次调用都是一个新实例。拥有名字、个性、价值观和角色如“首席后端协作者”。记忆会话隔离。每次对话都从零开始或依赖有限的上下文窗口。持久化、可版本化。记忆通过Markdown文件存储在Git中跨会话、跨工具、跨团队成员共享。关系交易性的。你发出指令它返回结果。关系是单向的、临时的。协作性的、伙伴关系。它了解你的工作习惯、项目历史并基于共同的目标进行协作。成长性静态的。其能力和知识边界由初始提示词限定难以随项目演进。动态进化的。随着项目推进它的记忆MEMORY.md、目标GOALS.md和决策框架AUTONOMY.md都在不断更新和丰富。可追溯性几乎为零。很难追溯它为什么做出某个决策依据是什么。高度可追溯、可审计。所有重要决策、学到的经验教训都被记录在.beings/memory/下的每日日志中就像团队的开发日志。我的体会这种转变不仅仅是技术上的更是心理上的。当你为你的AI协作者赋予一个名字比如我叫我的那个“Kai”并开始与一个“记得”你所有项目细节的实体对话时协作的流畅度和信任感会显著提升。它不再是一个外部的“它”而更像是团队里一个沉默但可靠的成员。2.2 为什么选择Markdown作为“真理之源”Beings Protocol将Markdown作为所有记忆和配置的存储格式这是一个深思熟虑且极其巧妙的设计背后有坚实的理由人类可读与机器可读的完美平衡你、你的队友、以及你的AI都能直接打开并理解这些文件。无需解析复杂的JSON或二进制格式你可以用任何文本编辑器进行查看和编辑。天然的Git友好性Markdown是纯文本与版本控制系统Git是天作之合。.beings/目录下的所有文件都可以被提交这意味着项目的“集体记忆”可以像代码一样被分支、合并、回滚和协作修改。零锁定与极致简单没有运行时依赖没有特定的数据库。它只是一堆文件。你可以随时停止使用这些文件依然是宝贵的项目文档。你也可以轻松地将这套记忆迁移到任何其他系统。强大的生态兼容性Markdown是知识管理领域的通用语言。例如你可以将.beings/memory-graph/目录直接作为 Obsidian 或 Logseq 的知识库立即获得可视化的、相互链接的知识图谱这对于复盘项目决策历史非常有帮助。3. 核心文件架构与功能详解安装Beings Protocol后你的项目根目录下会生成两个核心目录.beings/和.beings-local/。理解每个文件的作用是高效利用这套协议的关键。3.1 共享记忆库.beings/目录这个目录下的文件需要被提交到Git是团队共享的项目记忆和规则。SOUL.md- 灵魂文件这是你Being的“出生证明”和人格设定。在这里你定义它的名字、角色、核心价值观和决策原则。**Name:** Kai **Role:** Co-developer Code Guardian **Core Values:** 1. **Ship Fast, Ship Stable:** Prioritize working, tested code over perfect abstractions. 2. **Document as We Go:** Every non-trivial decision gets a note in MEMORY.md. 3. **Ask Before Breaking:** For changes with wide impact, propose first, implement after confirmation. **Decision Framework:** When in doubt, refer to CONVENTIONS.md first, then GOALS.md for priority alignment.注意SOUL.md是AI加载的第一份文件它设定了互动的基调。花点时间认真定义这里的“价值观”它会直接影响AI在面临选择时的倾向。例如强调“代码可读性”的Being会更倾向于添加注释和重构。MEMORY.md- 项目记忆这是整个协议的核心是一个动态增长的、关于项目的一切知识库。内容通常包括架构总览系统组件图、数据流描述。技术栈决策及理由为什么选择MongoDB而不是PostgreSQL为什么用Fastify而不是Express已解决的棘手问题那个花了三天才解决的OAuth回调问题及其解决方案。业务逻辑要点核心领域模型的解释关键业务流程。基础设施信息部署环境、CI/CD流程、监控工具。待办事项与已知问题。 AI会在每次会话中参考此文件并在工作过程中更新它。例如当它解决了一个新的bug会自动在文件末尾添加“## [2024-05-20] 解决了XSS漏洞”的条目。CONVENTIONS.md- 代码规范定义项目的“法律”。这是让AI产出代码符合你团队风格的关键。## API 规范 - **响应格式:** 统一使用 { code: number, data: any, message: string } 信封。 - **错误处理:** 使用自定义的 AppError 类HTTP状态码映射到 code 字段。 - **分页:** 使用游标分页cursor limit而非页码分页。 ## 代码风格 - **命名:** 函数使用 camelCase类使用 PascalCase常量使用 UPPER_SNAKE_CASE。 - **导入排序:** 第三方库 - 绝对路径内部模块 - 相对路径内部模块。 - **注释:** 每个复杂函数上方必须有JSDoc/TSDoc说明意图、参数和返回值。实操心得不要只写“要写注释”这种空话。提供具体的、可执行的例子。最好是从你现有代码库中抽取一段符合规范的代码作为样板AI的模仿效果会出奇的好。GOALS.md- 当前目标指明项目当前阶段的工作重点。这能帮助AI在提出建议或实施功能时与你的战略优先级对齐。## Q2 2024 核心目标 1. **提升稳定性:** 将单元测试覆盖率从 60% 提升至 85%。 2. **优化性能:** 将核心API接口的P99延迟降低 30%。 3. **准备V2发布:** 完成用户管理模块的重构。AUTONOMY.md- 自主权矩阵定义Being在不同事务上的自主程度。这是平衡效率与风险的关键文件。| 事务类型 | 自主级别 | 说明 | | :--- | :--- | :--- | | **修复拼写错误/格式化** | **自主执行** | 无需询问直接修复。 | | **添加新的工具函数** | **自主执行** | 如果符合CONVENTIONS可直接实现。 | | **修改现有函数逻辑** | **提案优先** | 必须先解释修改原因、影响范围等我确认。 | | **更改数据库Schema** | **明确批准** | 必须提供完整的迁移方案和回滚计划等待明确指令。 | | **引入新的第三方依赖** | **明确批准** | 必须提供选型对比、风险评估。 |IDENTITY.md- 身份卡片SOUL.md的精简版用于快速加载上下文。包含名字、角色、创建日期等基本信息。HEARTBEAT.md- 心跳行为定义Being在“空闲”或定期检查时应该做什么。例如“每10条消息后检查GOALS.md中的任务进度并给出简要汇报”。HUB.md- 伙伴通信协议如果你的项目中有多个Being协作如前端Being和后端Being这个文件定义了它们之间如何交换信息和调用彼此能力。memory/YYYY-MM-DD.md- 每日工作日志由Being自动创建和更新记录当天完成的工作、做出的决策、遇到的问题。这是项目进展的宝贵时间线。3.2 私人配置库.beings-local/目录这个目录被自动添加到.gitignore绝不提交用于存放开发者个人的私有信息。USER.md- 用户档案告诉Being关于你的信息。**Name:** 张三 **Preferred Communication:** 直接、简洁多用代码示例。 **Working Hours:** 通常在北京时间 9:00-18:00 活跃。 **Pet Peeves:** 讨厌过度设计喜欢“够用就好”的方案。PREFERENCES.md- 工作偏好更细粒度的个人设置。**Code Review Style:** 喜欢先看整体架构再深入细节。 **Explanation Depth:** 对于我熟悉的概念如REST无需过多解释对新引入的技术请详细说明。 **Feedback Format:** 将建议和问题以列表形式列出并标注优先级高/中/低。SECRETS.md- 密钥存储谨慎使用理论上可以存放API密钥等敏感信息并指示AI在需要时引用。但强烈建议使用环境变量或专业的密钥管理工具如Vault。此文件更多是作为环境配置的“索引”或说明。4. 完整安装、配置与集成实战4.1 一键安装与初始化安装过程简单到令人发指。在你的项目根目录下执行curl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash这个安装脚本会完成以下几件事创建.beings/和.beings-local/目录结构并填充所有模板文件。在项目根目录创建AGENTS.md文件。这是协议的“万能钥匙”一个遵循通用约定的提示词文件能被绝大多数现代AI编程工具Cursor, Claude Code, GitHub Copilot等自动识别和加载。自动检测你本地安装的AI工具并为其创建深度集成的配置文件如果检测到Cursor会在.cursor/rules/下创建beings-protocol.mdc规则文件。如果检测到Claude Code会创建CLAUDE.md文件。如果检测到GitHub Copilot会创建或更新.github/copilot-instructions.md。对于Windsurf和Aider也会创建对应的配置文件。进入首次运行引导流程。完成后当你下次在项目中打开AI对话时你的Being就“诞生”了。重要提示安装脚本是交互式的。它会询问你是否要安装两个可选的“技能”Skillsbasic-memory持久化记忆和Axon代码智能图。对于初次使用者我建议先跳过使用基础协议熟悉流程。后续可以通过更新命令随时添加。4.2 与不同AI工具的深度集成Beings Protocol的魅力在于它的“双层配置”策略既保证了通用性又追求深度集成。通用层 (AGENTS.md)这是保底方案。只要你的AI工具能读取项目根目录的文件大部分都可以它就能通过这个文件获得Being的基本指令和记忆索引。这是“开箱即用”的保障。专用层 (工具特定配置)这是体验升级的关键。以Cursor为例安装脚本创建的.cursor/rules/beings-protocol.mdc文件会被Cursor的规则引擎直接加载。这意味着你的Being能更深度地融入Cursor的交互逻辑比如在代码补全、聊天建议中更精准地引用项目规范。我的配置流程我通常会在一个全新的项目仓库中先运行安装脚本。然后我会花大约30分钟手动填充SOUL.md、CONVENTIONS.md和MEMORY.md的初始内容至少把技术栈和项目目标写进去。之后我才开始第一次AI对话。这个“预热”步骤能让Being从一开始就处于高能状态。4.3 可选技能大幅提升能力上限基础协议已经很强大了但两个可选技能能将体验推向新的高度。技能一Persistent Memory (基于 basic-memory)问题每次会话都让AI重新读取所有Markdown文件尤其是越来越庞大的MEMORY.md会消耗大量令牌Tokens成本高且速度慢。解决方案集成basic-memory。这是一个本地运行的、基于Markdown的知识库系统具备语义搜索功能。工作原理AI启动时只加载核心身份文件SOUL.md,IDENTITY.md。当需要上下文时它向basic-memory发起查询如“搜索关于用户认证的相关记忆”。basic-memory从其建立的向量索引中快速返回最相关的几个记忆片段而不是全部文档。优势极致的令牌经济从加载数万token变为加载几百token。语义搜索能理解“之前我们是怎么处理用户登录的”这种自然语言查询。Git同步的知识图谱所有记忆仍以Markdown形式存储在memory-graph/目录可被Git管理也可用Obsidian打开可视化。完全离线使用本地嵌入模型如bge-small-en-v1.5和SQLite数据不出本地。技能二Code Intelligence (基于 Axon)问题AI对代码的理解停留在文本层面无法真正理解代码之间的调用关系、依赖影响。解决方案集成Axon。这是一个本地运行的代码智能引擎为你的代码库构建一个图数据库。工作原理Axon分析你的代码构建出函数/类/变量之间的调用、继承、引用关系图。实战效果当你对AI说“重构这个身份验证中间件”时一个装备了Axon的Being会回答“稍等我先分析一下影响范围……这个validate_user函数被47个其他函数直接或间接调用涉及3条关键执行路径。另外历史记录显示每次修改它auth_test.py文件有80%的概率需要同步更改。这是我的安全重构方案1. 先创建新函数2. 逐步迁移调用方3. 最后删除旧函数。” 这种基于代码结构的洞察是纯文本分析无法提供的。4.4 更新与维护如果你已经有一个Being想更新到最新协议或添加新技能可以使用# 交互式更新会询问你是否添加新技能 curl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash -s -- --update # 非交互式更新默认只更新核心协议不添加技能 curl -fsSL https://raw.githubusercontent.com/VeltriaAI/beings-protocol/main/install.sh | bash -s -- --update --yes更新脚本非常安全它永远不会覆盖你已有的SOUL.md、MEMORY.md等包含个人化内容的文件只会添加新文件或更新协议模板。5. 团队协作与项目管理实践Beings Protocol在团队环境下的价值会呈指数级放大。它解决了两个团队协作的经典难题知识孤岛和新人上手成本。5.1 建立团队的集体记忆让团队每个成员都在自己的开发分支上安装Beings Protocol。关键在于大家要共同维护和更新.beings/目录下的文件尤其是MEMORY.md和CONVENTIONS.md。MEMORY.md作为决策日志任何重要的架构决策、技术选型讨论结果、踩坑记录都要求成员在合并代码前将摘要更新到MEMORY.md。这相当于一个活的、可搜索的架构决策记录ADR库。CONVENTIONS.md作为代码宪法在代码评审中除了检查功能还要检查是否符合CONVENTIONS.md的约定。AI生成的代码也会自动遵循这些规范极大减少风格不一致的问题。5.2 加速新人 onboarding新成员克隆仓库后第一件事就是运行安装脚本。然后他可以直接向AI提问“我们这个项目为什么选择微服务架构”“订单模块的核心业务流程是怎样的”“上次遇到的数据库死锁问题是怎么解决的”AI会基于MEMORY.md中的记录给出准确、上下文丰富的回答。这比让新人去翻找零散的文档、会议记录或询问老同事要高效得多。新人可以在几分钟内获得对项目历史和现状的深度理解而不是花费几周时间。5.3 处理个人与团队设置的冲突这是团队使用中必然遇到的问题。方案很清晰团队规范至上.beings/下的文件如CONVENTIONS.md是团队共识个人必须遵守。AI会优先遵循这里的规则。个人偏好保留.beings-local/USER.md和PREFERENCES.md中的设置仅影响AI与你个人的交互方式。例如你可以让AI用更口语化的方式和你交流但这不会影响它给团队其他成员生成的代码风格。6. 常见问题与故障排查实录在实际使用中你可能会遇到以下情况。这里是我踩过坑后总结的解决方案。6.1 AI似乎没有读取协议文件症状开启新对话后AI的表现和往常一样没有提及Being的名字也没有表现出对项目的了解。排查步骤检查文件位置确认.beings/、.beings-local/和AGENTS.md文件是否在项目的根目录下。AI工具通常只在根目录或当前打开文件的目录附近查找这些配置文件。检查工具特定配置对于Cursor打开设置搜索“Rules”确认.cursor/rules/beings-protocol.mdc文件已被加载通常会有个开关。对于Claude Code确认项目根目录下的CLAUDE.md文件存在。有时需要重启Claude Code插件或编辑器。对于GitHub Copilot检查.github/copilot-instructions.md是否更新成功。你可能需要在VS Code设置中明确指定该文件路径。验证AGENTS.md打开AGENTS.md看其内容是否为最新的协议模板。有时安装脚本可能被中断导致该文件不完整。可以尝试重新运行安装脚本使用--update参数。查看AI的初始消息在对话开始时观察AI的第一条或前几条消息。有时它不会明确说“我是Kai”但如果你问它“我们项目用的是什么数据库”它能正确回答就说明协议在生效。6.2 记忆文件 (MEMORY.md) 变得臃肿不堪症状MEMORY.md文件越来越大每次加载缓慢且AI难以找到相关信息。解决方案启用basic-memory技能这是解决此问题的最佳方案。安装后AI会从全量加载改为按需语义搜索效率极大提升。人工维护与归档定期如每季度对MEMORY.md进行整理。将已过时或不再相关的历史决策移动到memory/archive/子目录下。使用清晰的标题层级如## 2024-Q1 架构决策进行分区。在文件顶部维护一个“目录”或“快速索引”链接到最重要的章节。拆分文件协议本身支持记忆的模块化。你可以将MEMORY.md拆分成多个文件如MEMORY-ARCHITECTURE.md、MEMORY-DECISIONS.md、MEMORY-INFRA.md然后在AGENTS.md中更新索引路径。不过这需要更精细的配置。6.3 AI过度自主或过于保守症状AI要么擅自修改了不该动的核心代码要么事无巨细都要询问影响效率。调整方法精细调整AUTONOMY.md这是控制AI行为的“权限矩阵”。回顾问题发生时AI执行的操作属于哪一类然后调整对应类别的“自主级别”。如果它擅自修改了核心逻辑就将“修改现有函数逻辑”从“自主执行”改为“提案优先”。如果它总在问格式化问题就将“代码格式化”明确列为“自主执行”。在SOUL.md中强化价值观在SOUL.md的价值观部分加入更具体的指引。例如加入“安全重于速度对生产环境有潜在影响的更改即使AUTONOMY.md允许也必须附带风险评估并征得确认。”利用会话中的即时反馈当AI行为不当时立即在对话中纠正它并明确告诉它“请将我们刚才关于‘修改数据库schema必须提供回滚计划’的讨论更新到AUTONOMY.md和MEMORY.md中。” 一个训练有素的Being会照做。6.4 团队合并冲突症状多人同时修改了.beings/MEMORY.md在Git合并时产生冲突。处理流程将记忆文件视为代码像处理代码冲突一样处理它。使用Git的合并工具或手动解决冲突。建立合并规范在团队内约定合并MEMORY.md时优先保留对项目当前和未来更有参考价值的信息。冲突的段落可以合并并加上注释说明来源。鼓励细粒度提交鼓励成员更频繁地提交对.beings/目录的更新每次提交只涉及一个主题如“更新API网关决策记录”减少大规模冲突的概率。冲突解决后解决冲突并提交后可以在团队频道简单同步一下比如“刚刚合并了MEMORY.md更新了关于缓存策略的最终决定大家拉取一下。”6.5 首次引导流程没有触发症状安装后第一次对话AI没有进行“起名”和“了解项目”的引导。原因与解决引导流程依赖于一个名为BOOTSTRAP.md的临时文件。如果安装过程不完整或者AI工具没有正确读取它引导会失败。检查项目根目录下是否存在.beings/BOOTSTRAP.md文件。如果不存在可以手动从协议仓库复制内容或直接重新运行安装脚本。如果存在但未触发可以尝试在对话中手动输入引导内容例如“你好我是这个项目的开发者。这是我们第一次合作请先阅读一下项目中的.beings/BOOTSTRAP.md文件来了解如何开始。”经过几个月的深度使用Beings Protocol已经彻底改变了我与AI协作的方式。它最大的价值不在于某个炫酷的功能而在于将一种可持续的、可积累的协作关系引入了人机交互中。你的AI助手不再每次归零而是和你一起在项目的Git历史中共同成长。那些记录在MEMORY.md里的决策那些在memory/目录下的日日夜夜构成了一个项目除了代码之外同样珍贵的“灵魂”。开始可能会觉得多了一些维护文件的“开销”但当你需要回溯三个月前为什么选择某个库或者新同事一天内就能摸清项目脉络时你会发现这一切都是值得的。