基于Markdown的多智能体协作框架：提升LLM编程效率的工程化实践

1. 项目概述：一个为现代LLM设计的Markdown原生多智能体框架

如果你和我一样，每天都在和Cursor、Claude、GPT这些现代大语言模型打交道，那你肯定也遇到过这样的困境：想让AI帮你写个复杂功能，比如一个完整的用户认证模块，你需要在聊天窗口里反复切换角色，一会儿扮演架构师描述设计，一会儿扮演开发者写代码，还得自己扮演评审员去检查安全漏洞。整个过程就像在指挥一个混乱的乐队，每个乐手（AI）都很强，但缺乏统一的乐谱和指挥，最终出来的声音杂乱无章。这就是为什么当我第一次看到scscodes/mide-lite（Gen 2）这个项目时，感觉眼前一亮。它不是一个简单的提示词集合，而是一个基于Markdown的、结构化的多智能体协作框架，专门为Claude 3.5 Sonnet、GPT-4o这类“理解力”更强的现代模型设计。

简单来说，Mide-Lite的核心思想是**“让AI像专业团队一样工作”**。它通过一套定义在Markdown文件里的清晰结构，把不同的AI角色（Agent）、工作流程（Workflow）、编码规则（Rules）和记忆系统（Memory）组织起来。你不再需要每次都在聊天框里写小作文似的长篇提示词，而是通过一句简单的指令，如“Act as the Architect agent...”，就能调用一个拥有特定专长和上下文的“虚拟专家”来为你服务。这个框架特别适合需要长期、复杂协作的软件开发项目，它能将一次性的AI对话，转变为一个可追踪、可复用、有持续上下文的协作过程。无论你是独立开发者想提升效率，还是团队希望规范AI辅助开发的流程，Mide-Lite都提供了一个极具参考价值的工程化实践。

2. 核心理念与架构设计解析

2.1 从“提示词工程”到“框架工程”的范式转变

传统的AI辅助编程，我们依赖的是“提示词工程”（Prompt Engineering）。我们精心设计一段包含角色、任务、格式要求的文本，希望模型能准确理解并执行。这种方法有两个明显的痛点：一是上下文脆弱，长对话中指令容易被遗忘或曲解（即“指令漂移”）；二是协作困难，很难让AI在不同任务中保持角色一致性和知识连续性。

Mide-Lite的Gen 2版本对此做出了根本性的改变。它不再依赖于临时拼凑的提示词模板，而是构建了一套以Markdown为载体的声明式框架。你可以把它想象成给AI团队编写的一套“公司章程”和“标准操作流程”（SOP）。所有智能体的职责、工作流程的步骤、代码的规范，都以结构化的Markdown文件形式存在。这样做最大的好处是可读性、可维护性和可组合性。开发者可以像阅读项目文档一样，轻松理解整个AI协作体系是如何运作的，并且可以随时修改或扩展其中的组件。

2.2 核心架构组件深度解读

让我们拆开项目结构，看看每个目录和文件具体承担了什么角色：

1. AGENTS.md- 总调度中心：这是整个框架的单一入口。它本身内容很“薄”，主要作用是作为一个路由表，清晰地指向所有其他核心组件的位置。这种设计遵循了“单一职责”和“明确入口”的原则，无论是开发者还是AI模型，都能第一时间知道从哪里开始了解整个系统。

2. src/system_prompt.md- 系统内核：这是框架的“大脑”。它定义了最核心的协作协议，包括：

   • 智能体（Agents）的协作机制：不同智能体之间如何交接任务、传递上下文。
   • 编排（Orchestration）逻辑：如何根据工作流程协调多个智能体的行动顺序。
   • 记忆（Memory）协议：智能体如何读取和更新共享的工作状态与决策历史。
   • “推理优先”原则：强制要求每个智能体在输出最终答案前，必须在一个<reasoning>标签内展示其思考过程。这是确保AI行动透明、可控的关键。

3. src/agents/- 角色定义库：这里存放着各个“虚拟员工”的岗位说明书。每个.md文件定义一个智能体，例如architect.md、builder.md、critic.md。文件里会详细描述该角色的专长领域、职责边界、思考问题的角度以及输出格式要求。AI通过读取这些文件来“扮演”相应的角色。

4. src/workflows/- 流程自动化脚本：如果说智能体是“员工”，那么工作流程就是“生产线”。index.md是流程目录，里面可能定义了如feature-dev（功能开发）、bug-fix（缺陷修复）、parallel-review（并行评审）等标准化流程。每个流程详细规定了针对某类任务，需要按什么顺序调用哪些智能体，以及它们之间如何传递“工件”。

5. src/rules/- 质量与规范守则：这里是代码规范和开发规则的集合。base_rules.md是总索引，可能链接到更具体的规则文件，如typescript.md、python.md、security.md。智能体在编写代码时必须遵守这些规则，这保证了产出代码的一致性、安全性和可维护性，相当于把团队的编码规范直接“注入”到了AI的生成过程中。

6. src/memory/- 项目协作记忆体：这是实现持续上下文的关键。

   • context.md：工作内存。记录当前项目阶段、关注焦点、遇到的阻塞问题等临时但重要的状态。它随着项目推进而动态更新。
   • decisions.md：决策日志。这是一个只追加（append-only）的日志，记录项目开发过程中所有重要的技术决策、方案选型的理由。这不仅是给AI看的上下文，更是留给未来项目成员（包括人类）的宝贵文档。

7. src/contracts/与src/artifacts/- 输入输出标准化：

   • contracts/：定义了“工件”（Artifact）的数据结构（如schema.json）和内容约定。它规定了智能体之间传递的“东西”（如设计文档、API接口定义、代码文件）应该长什么样，有哪些必填字段。
   • artifacts/：临时存放生成的工件。由于被.gitignore忽略，它不会污染代码库，只作为AI协作过程中的临时工作区。

2.3 “推理优先”内核：从黑盒到白盒的关键

Mide-Lite特别强调的“Cognition-First”或“推理优先”原则，是其区别于许多简单提示词模板的灵魂所在。它强制要求每个智能体在行动前，必须将思考过程包裹在<reasoning>标签内输出。

为什么这个设计如此重要？

• 对开发者（你）而言：它让AI的决策过程变得透明。你不再是看到一个突兀的最终答案，而是能看到AI是如何一步步分析问题、权衡方案、做出选择的。这极大地增强了可控性和信任感。如果结果有偏差，你可以直接审查<reasoning>部分，定位是思考的哪一步出了问题，从而精准地调整提示词或规则。
• 对AI协作而言：它为智能体间的接力提供了“交接棒”。下一个智能体可以通过阅读上一个智能体的推理过程，更好地理解任务的来龙去脉和设计意图，从而实现更连贯的协作。
• 对模型自身而言：研究表明，让大语言模型“一步一步思考”（Chain-of-Thought）能显著提升其在复杂任务上的推理准确性和可靠性。<reasoning>块正是将这种技术模式化、结构化。

实操心得：在实际使用中，我发现强制<reasoning>输出有时会让模型显得“啰嗦”。一个技巧是，在system_prompt.md或具体智能体定义中，可以要求推理部分尽量简洁、结构化，例如使用列表或关键点来呈现思考路径，而不是大段的散文式描述，这样既能保证透明，又提高了可读性。

3. 实战上手：从零开始配置与使用

3.1 环境准备与项目集成

Mide-Lite本身不依赖特定的运行时环境，它是一套方法论和文件结构的集合。因此，集成它的核心步骤就是“复制与配置”。

1. 获取框架代码：最直接的方式是从GitHub仓库scscodes/mide-lite克隆或下载项目文件。你也可以只复制其src目录下的核心结构和AGENTS.md、README.md等文件到你的项目根目录。
2. 集成到AI IDE：框架的设计与Cursor IDE的理念高度契合。在Cursor中，你可以直接将包含Mide-Lite文件的目录作为工作区打开。更常见的做法是，在你现有项目的根目录下创建一个子目录（例如/.ai或/mide），将框架文件放置其中。这样既能利用框架，又不会干扰主项目代码。
3. 关键配置点：你需要根据自己项目的技术栈，定制化src/rules/下的规则文件。例如，如果你的项目是TypeScript + React，那么你需要创建或修改对应的规则文件，明确代码风格、组件规范、状态管理方式等。这是让框架产出符合你项目要求代码的关键一步。

3.2 两种核心使用模式详解

框架提供了两种调用AI智能体的模式，适用于不同场景。

模式一：直接调用智能体（点对点专家咨询）这种模式就像你直接打电话给某个领域的专家。你通过一句以“Act as the [Agent] agent”开头的指令，直接指定角色并下达任务。

• 示例指令：

  Act as the Architect agent. Design a REST API for a blog post commenting system. The system should support nested replies, moderation flags, and user mentions. Output the API specification following the OpenAPI 3.0 format contract.

• 底层发生了什么：当你发送这条指令时，Cursor或你的LLM工具会加载整个工作区的上下文。AI会读取AGENTS.md，找到src/agents/architect.md，理解架构师的职责；同时，系统内核（system_prompt.md）会要求它先进行<reasoning>；最后，它可能会参考src/contracts/中关于API设计工件的约定来格式化输出。
• 适用场景：解决一个明确的、独立的设计或评审问题。例如，评审某个数据库表结构、设计一个算法流程、为代码片段编写单元测试。

模式二：基于工作流程的编排（自动化流水线）这种模式是高级用法，你不再直接指挥某个员工，而是告诉项目经理（Supervisor）一个目标，它会自动按照预设的流程组织团队完成。

• 示例指令：

  Act as the Supervisor agent. Run the "feature-dev" workflow to implement a user profile editing page. The page should allow users to update their avatar, display name, and bio. Assume we are using Next.js 14 with App Router and Tailwind CSS.

• 底层流程：
  1. Supervisor智能体接收到指令后，会去src/workflows/index.md查找名为feature-dev的工作流程定义。
  2. 该流程可能定义如下步骤：Architect设计组件结构与数据流 ->Builder实现前端页面与后端API ->Critic进行代码审查与UI/UX评审 ->Builder根据评审意见修改。
  3. Supervisor会按顺序激活这些智能体，并将上一个智能体的输出（工件）作为下一个智能体的输入。整个过程中，memory/context.md会记录当前进行到哪一步，memory/decisions.md会记录关键的设计决策。
• 适用场景：开发一个完整的功能模块、系统性地重构一段代码、执行多角度的安全审计。它实现了跨智能体的、状态化的复杂任务自动化。

3.3 定制属于你自己的智能体与流程

框架的威力在于其可扩展性。开箱自带的智能体和流程只是例子，你可以且应该根据自己团队的需求进行定制。

创建新智能体：

1. 在src/agents/目录下创建一个新的.md文件，例如database_specialist.md。
2. 文件内容应清晰定义：
   • 角色名称与目标：例如，“数据库专家，专注于设计高效、可扩展的数据模型与查询”。
   • 核心能力：擅长SQL优化、ORM配置、数据迁移策略、熟悉特定数据库（如PostgreSQL）的特性。
   • 工作方式：在接到任务后，必须首先分析业务场景与访问模式，再给出设计。输出必须包含实体关系图（ERD）描述和关键查询示例。
   • 遵守的规则：引用src/rules/database.md（如果存在）。
3. 在AGENTS.md或system_prompt.md中注册这个新智能体，以便Supervisor能够调度它。

创建新工作流程：

1. 在src/workflows/目录下创建流程定义文件，或在index.md中新增条目。
2. 定义流程的触发条件、阶段、每个阶段调用的智能体、以及工件传递的路径。例如，一个database-migration流程可能包含：Architect评估影响 ->DatabaseSpecialist设计迁移方案与回滚计划 ->Critic进行风险评估 ->Builder执行迁移脚本编写。

注意事项：在定制时，务必保持定义的清晰和无歧义。智能体的职责边界要明确，避免重叠。工作流程的每个步骤都应该是原子化的、可验证的。过于复杂的流程可能会让AI困惑，导致执行失败。

4. 高级技巧与最佳实践

4.1 利用记忆系统实现跨会话持久化

Mide-Lite的memory/目录是其实现“项目级AI协作”而非“单次对话”的基石。有效利用它，能极大提升复杂项目开发的连贯性。

• 主动更新上下文：不要完全依赖AI自动更新context.md。在关键节点，你可以手动或通过指令去总结当前状态。例如，在完成一个模块的设计后，可以指令AI：“请基于我们刚刚确定的设计方案，更新src/memory/context.md中的‘当前焦点’部分，并记录下我们选择REST over GraphQL的主要理由到decisions.md。”
• 决策日志作为知识库：decisions.md是一个宝贵的项目知识库。当新成员（无论是人类还是AI）加入项目时，让他们首先阅读此文件，可以快速理解项目的历史技术决策和背景，避免重复讨论或做出矛盾的选择。
• 处理“记忆冲突”：当多个智能体或多次会话同时修改记忆文件时，可能会产生冲突。一个最佳实践是，在system_prompt.md中约定，更新记忆前必须先读取当前内容，并以合并或追加的方式进行更新，对于decisions.md严格采用只追加模式。

4.2 编写高质量的规则与契约

规则（Rules）和契约（Contracts）是约束AI输出质量、确保其符合项目规范的“紧箍咒”。编写它们需要技巧。

• 规则要具体、可执行：避免“代码要整洁”这样的模糊描述。取而代之的应该是：“函数长度不应超过50行”、“必须为公有API编写JSDoc/TSDoc注释”、“错误处理必须使用try-catch包裹并记录到应用日志”、“禁止使用any类型”。
• 使用负面清单：除了规定应该怎么做，明确列出禁止事项往往更有效。例如：“禁止在组件内部直接使用localStorage进行状态管理”、“禁止向第三方API发送未脱敏的用户个人信息”。
• 契约定义数据结构：Artifact.schema.json定义了工件的JSON Schema。这能强制AI输出结构化的数据。例如，一个“API设计工件”的schema可以要求包含endpoints（数组）、requestSchema、responseSchema、security等字段。这使智能体间的数据交换像API调用一样可靠。
• 内容约定提供范例：content_conventions.md可以规定非结构化工件（如设计文档）的写作模板。例如：“所有设计文档应以‘## 1. 目标’开头，然后是‘## 2. 方案对比’，最后是‘## 3. 详细设计’”，并提供一个范例。

4.3 调试与优化智能体协作

当协作流程没有按预期工作时，如何进行调试？

1. 检查推理过程：首先，查看AI输出的<reasoning>部分。问题往往出在这里。可能是它误解了需求，可能是它遗漏了某个关键规则，也可能是它的思考路径存在逻辑漏洞。根据推理过程的问题，去调整对应的智能体定义或初始指令。
2. 审查记忆状态：检查context.md和decisions.md。看看AI是否正确地读取和更新了记忆。有时协作中断是因为上下文没有成功传递。
3. 隔离测试智能体：如果在一个复杂流程中出错，可以尝试单独调用流程中的某个智能体，给它明确的输入，看它是否能正确输出。这有助于定位是某个智能体的定义有问题，还是流程编排的逻辑有问题。
4. 迭代优化定义文件：将Mide-Lite的组件（智能体、规则、流程）视为需要不断迭代的“代码”。根据实际运行效果，反复打磨它们的描述，使其更加精确、无歧义。这是一个持续的过程。

4.4 与现有开发流程的融合

Mide-Lite不应是一个孤立的系统，而应融入你现有的Git、项目管理、CI/CD流程。

• 版本控制：将src/agents/,src/workflows/,src/rules/等框架定义文件纳入Git管理。这样，团队可以协同改进AI协作流程。但src/artifacts/临时目录应保持在.gitignore中。
• 代码审查：AI生成的最终代码，必须经过人类开发者的审查才能合并。可以将Critic智能体的评审意见作为代码审查（Pull Request）描述的一部分，但人类需要拥有最终决定权。
• CI/CD集成：可以在CI流水线中增加一个步骤，使用Mide-Lite的Critic（或一个定制的Linter智能体）对提交的代码进行自动化的规则符合性检查和安全扫描，将问题以评论形式反馈到PR中。

5. 常见问题与解决方案实录

在实际应用Mide-Lite框架的过程中，我遇到并总结了一些典型问题及其应对策略。

问题1：AI似乎忽略了规则文件中的某些规定。

• 可能原因：规则描述过于冗长或分散，导致模型注意力分散；或者规则之间存在未被察觉的矛盾。
• 解决方案：
  • 精简与聚焦：检查规则文件，确保核心、重要的规则放在最前面，并用加粗强调。每条规则尽量用一句话清晰表述。
  • 结构化索引：确保base_rules.md作为清晰的索引，让AI能快速找到相关规则，而不是淹没在大段文本中。
  • 在指令中显式引用：在给智能体下达任务时，可以再次强调关键规则。例如：“...请严格遵守src/rules/typescript.md中关于‘错误处理’和‘类型定义’的规则。”

问题2：工作流程执行到一半卡住了，Supervisor不知道下一步该做什么。

• 可能原因：工作流程定义存在模糊或缺失的步骤；上一个智能体的输出不符合契约要求，导致下一个智能体无法解析。
• 解决方案：
  • 明确定义出口条件：在流程的每个步骤，明确说明该步骤完成的标志是什么（例如，“生成并通过初步评审的API设计文档”），以及输出工件应满足的契约。
  • 增强Supervisor的异常处理逻辑：在system_prompt.md中赋予Supervisor智能体基本的异常处理能力，例如：“如果某个步骤的产出物无法被验证，应记录阻塞原因到context.md，并尝试回退到上一步或请求人类干预。”
  • 人工检查中间产物：定期查看artifacts/目录下的中间文件，确保它们格式正确、内容完整。

问题3：不同智能体对同一个概念的理解不一致。

• 可能原因：项目术语没有统一定义；智能体角色定义存在职责重叠区域。
• 解决方案：
  • 建立项目术语表：在src/contracts/或项目根目录创建一个glossary.md，定义核心业务概念、技术名词的精确含义。
  • 清晰划分职责：审查智能体定义文件，确保它们的专长领域有清晰边界。如果发现重叠，重新定义或创建一个新的、职责更明确的智能体。
  • 利用记忆进行对齐：将重要的、达成一致的定义和决策记录到decisions.md中，并要求所有智能体在行动前参考此日志。

问题4：框架文件很多，感觉维护成本高。

• 可能原因：初期为了追求全面，创建了过多细分的智能体和规则，但很多并未常用。
• 解决方案：
  • 从最小集开始：不要一开始就构建庞大的智能体团队。从一个架构师（Architect）、一个构建者（Builder）和一个评审者（Critic）这三个核心角色开始，搭配1-2个最常用的流程（如feature-dev）。
  • 按需扩展：在项目实践中，当发现某个重复性任务需要特定专业知识时，再着手创建新的智能体或规则。让实际需求驱动框架的演进。
  • 模板化：为智能体和规则文件创建模板，这样新增时会更加规范快捷。

问题5：在非Cursor的LLM工具（如ChatGPT Web界面、Claude桌面端）中如何使用？

• 解决方案：Mide-Lite的核心是方法论和文件结构。你可以在任何支持长上下文和文件上传的LLM工具中使用它。操作步骤是：1) 将整个项目目录或相关Markdown文件压缩。2) 在对话中上传该压缩包作为上下文。3) 在指令中明确告诉模型：“请基于已上传的Mide-Lite框架文件，扮演[XX]智能体...”。虽然不如在Cursor中集成得那么无缝，但核心的协作逻辑依然可以运行。

我个人在几个中大型项目中应用Mide-Lite框架后，最深的体会是：它最大的价值不在于替代开发者，而在于将开发者从“低层次、重复性的AI指令编写和上下文管理中”解放出来，让我们能更专注于高层次的架构设计、流程把控和关键决策。它把与AI的协作，从一种“艺术”或“技巧”，变成了一种可管理、可迭代、可传承的“工程实践”。开始时会觉得增加了一些配置成本，但一旦这套体系运转起来，尤其是在需要长期维护和多人协作的项目中，其带来的一致性、可追溯性和效率提升是非常显著的。你可以先从改造一个现有的、定义清晰的开发任务开始尝试，比如为一个已有模块添加一套完整的单元测试，亲自感受一下这种结构化协作与以往零散对话的区别。