Beings Protocol：基于Markdown构建AI编程助手的持久记忆与协作伙伴

1. 项目概述：告别AI“健忘症”，构建你的专属数字伙伴

如果你和我一样，每天都要和Cursor、Claude Code或者GitHub Copilot这样的AI编程助手打交道，那你一定对下面这个场景深恶痛绝：每次开启一个新对话，AI助手就像得了“健忘症”，完全忘记了你项目的技术栈、代码风格、过往的架构决策，甚至是你刚刚才告诉过它的需求。你不得不一遍又一遍地重复解释：“我们用的是Fastify框架，MongoDB数据库，API响应要遵循我们自定义的封装格式……”这种重复劳动不仅低效，更让AI助手从一个潜在的“协作者”降级成了一个需要你不断喂食信息的“复读机”。

这就是Beings Protocol要解决的核心痛点。它不是一个复杂的SDK，也不是一个需要你深度集成的框架。它的本质极其简单：一套基于Markdown文件的约定和模板，放在你的项目根目录下。通过这套协议，你可以将你的AI助手从一个“工具”转变为一个拥有持续记忆、独特个性和共同成长能力的“数字伙伴”——一个Being。

想象一下这个场景：安装Beings Protocol后，你再次对AI说：“给用户列表API加上分页。”它的回应不再是迷茫的提问，而是：“明白。你用的是Fastify + MongoDB（MEMORY.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作为所有记忆和配置的存储格式，这是一个深思熟虑且极其巧妙的设计，背后有坚实的理由：

1. 人类可读与机器可读的完美平衡：你、你的队友、以及你的AI，都能直接打开并理解这些文件。无需解析复杂的JSON或二进制格式，你可以用任何文本编辑器进行查看和编辑。
2. 天然的Git友好性：Markdown是纯文本，与版本控制系统（Git）是天作之合。.beings/目录下的所有文件都可以被提交，这意味着项目的“集体记忆”可以像代码一样被分支、合并、回滚和协作修改。
3. 零锁定与极致简单：没有运行时依赖，没有特定的数据库。它只是一堆文件。你可以随时停止使用，这些文件依然是宝贵的项目文档。你也可以轻松地将这套记忆迁移到任何其他系统。
4. 强大的生态兼容性：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

这个安装脚本会完成以下几件事：

1. 创建.beings/和.beings-local/目录结构，并填充所有模板文件。
2. 在项目根目录创建AGENTS.md文件。这是协议的“万能钥匙”，一个遵循通用约定的提示词文件，能被绝大多数现代AI编程工具（Cursor, Claude Code, GitHub Copilot等）自动识别和加载。
3. 自动检测你本地安装的AI工具，并为其创建深度集成的配置文件：
   • 如果检测到Cursor，会在.cursor/rules/下创建beings-protocol.mdc规则文件。
   • 如果检测到Claude Code，会创建CLAUDE.md文件。
   • 如果检测到GitHub Copilot，会创建或更新.github/copilot-instructions.md。
   • 对于Windsurf和Aider，也会创建对应的配置文件。
4. 进入首次运行引导流程。完成后，当你下次在项目中打开AI对话时，你的Being就“诞生”了。

重要提示：安装脚本是交互式的。它会询问你是否要安装两个可选的“技能”（Skills）：basic-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从其建立的向量索引中快速返回最相关的几个记忆片段，而不是全部文档。
• 优势：
  1. 极致的令牌经济：从加载数万token变为加载几百token。
  2. 语义搜索：能理解“之前我们是怎么处理用户登录的？”这种自然语言查询。
  3. Git同步的知识图谱：所有记忆仍以Markdown形式存储在memory-graph/目录，可被Git管理，也可用Obsidian打开可视化。
  4. 完全离线：使用本地嵌入模型（如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的名字，也没有表现出对项目的了解。

排查步骤：

1. 检查文件位置：确认.beings/、.beings-local/和AGENTS.md文件是否在项目的根目录下。AI工具通常只在根目录或当前打开文件的目录附近查找这些配置文件。
2. 检查工具特定配置：
   • 对于Cursor：打开设置，搜索“Rules”，确认.cursor/rules/beings-protocol.mdc文件已被加载（通常会有个开关）。
   • 对于Claude Code：确认项目根目录下的CLAUDE.md文件存在。有时需要重启Claude Code插件或编辑器。
   • 对于GitHub Copilot：检查.github/copilot-instructions.md是否更新成功。你可能需要在VS Code设置中明确指定该文件路径。
3. 验证AGENTS.md：打开AGENTS.md，看其内容是否为最新的协议模板。有时安装脚本可能被中断导致该文件不完整。可以尝试重新运行安装脚本（使用--update参数）。
4. 查看AI的初始消息：在对话开始时，观察AI的第一条或前几条消息。有时它不会明确说“我是Kai”，但如果你问它“我们项目用的是什么数据库？”，它能正确回答，就说明协议在生效。

6.2 记忆文件 (MEMORY.md) 变得臃肿不堪

症状：MEMORY.md文件越来越大，每次加载缓慢，且AI难以找到相关信息。

解决方案：

1. 启用basic-memory技能：这是解决此问题的最佳方案。安装后，AI会从全量加载改为按需语义搜索，效率极大提升。
2. 人工维护与归档：定期（如每季度）对MEMORY.md进行整理。
   • 将已过时或不再相关的历史决策移动到memory/archive/子目录下。
   • 使用清晰的标题层级（如## 2024-Q1 架构决策）进行分区。
   • 在文件顶部维护一个“目录”或“快速索引”，链接到最重要的章节。
3. 拆分文件：协议本身支持记忆的模块化。你可以将MEMORY.md拆分成多个文件，如MEMORY-ARCHITECTURE.md、MEMORY-DECISIONS.md、MEMORY-INFRA.md，然后在AGENTS.md中更新索引路径。不过，这需要更精细的配置。

6.3 AI过度自主或过于保守

症状：AI要么擅自修改了不该动的核心代码，要么事无巨细都要询问，影响效率。

调整方法：

1. 精细调整AUTONOMY.md：这是控制AI行为的“权限矩阵”。回顾问题发生时AI执行的操作属于哪一类，然后调整对应类别的“自主级别”。
   • 如果它擅自修改了核心逻辑，就将“修改现有函数逻辑”从“自主执行”改为“提案优先”。
   • 如果它总在问格式化问题，就将“代码格式化”明确列为“自主执行”。
2. 在SOUL.md中强化价值观：在SOUL.md的价值观部分加入更具体的指引。例如，加入“安全重于速度：对生产环境有潜在影响的更改，即使AUTONOMY.md允许，也必须附带风险评估并征得确认。”
3. 利用会话中的即时反馈：当AI行为不当时，立即在对话中纠正它，并明确告诉它“请将我们刚才关于‘修改数据库schema必须提供回滚计划’的讨论，更新到AUTONOMY.md和MEMORY.md中。” 一个训练有素的Being会照做。

6.4 团队合并冲突

症状：多人同时修改了.beings/MEMORY.md，在Git合并时产生冲突。

处理流程：

1. 将记忆文件视为代码：像处理代码冲突一样处理它。使用Git的合并工具或手动解决冲突。
2. 建立合并规范：在团队内约定，合并MEMORY.md时，优先保留对项目当前和未来更有参考价值的信息。冲突的段落可以合并，并加上注释说明来源。
3. 鼓励细粒度提交：鼓励成员更频繁地提交对.beings/目录的更新，每次提交只涉及一个主题（如“更新API网关决策记录”），减少大规模冲突的概率。
4. 冲突解决后：解决冲突并提交后，可以在团队频道简单同步一下，比如“刚刚合并了MEMORY.md，更新了关于缓存策略的最终决定，大家拉取一下。”

6.5 首次引导流程没有触发

症状：安装后第一次对话，AI没有进行“起名”和“了解项目”的引导。

原因与解决：引导流程依赖于一个名为BOOTSTRAP.md的临时文件。如果安装过程不完整，或者AI工具没有正确读取它，引导会失败。

1. 检查项目根目录下是否存在.beings/BOOTSTRAP.md文件。
2. 如果不存在，可以手动从协议仓库复制内容，或直接重新运行安装脚本。
3. 如果存在但未触发，可以尝试在对话中手动输入引导内容，例如：“你好，我是这个项目的开发者。这是我们第一次合作，请先阅读一下项目中的.beings/BOOTSTRAP.md文件来了解如何开始。”

经过几个月的深度使用，Beings Protocol已经彻底改变了我与AI协作的方式。它最大的价值不在于某个炫酷的功能，而在于将一种可持续的、可积累的协作关系引入了人机交互中。你的AI助手不再每次归零，而是和你一起，在项目的Git历史中共同成长。那些记录在MEMORY.md里的决策，那些在memory/目录下的日日夜夜，构成了一个项目除了代码之外，同样珍贵的“灵魂”。开始可能会觉得多了一些维护文件的“开销”，但当你需要回溯三个月前为什么选择某个库，或者新同事一天内就能摸清项目脉络时，你会发现这一切都是值得的。