1. 项目概述一个为现代LLM设计的Markdown原生多智能体框架如果你和我一样每天都在和Cursor、Claude、GPT这些现代大语言模型打交道那你肯定也遇到过这样的困境想让AI帮你写个复杂功能比如一个完整的用户认证模块你需要在聊天窗口里反复切换角色一会儿扮演架构师描述设计一会儿扮演开发者写代码还得自己扮演评审员去检查安全漏洞。整个过程就像在指挥一个混乱的乐队每个乐手AI都很强但缺乏统一的乐谱和指挥最终出来的声音杂乱无章。这就是为什么当我第一次看到scscodes/mide-liteGen 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 核心架构组件深度解读让我们拆开项目结构看看每个目录和文件具体承担了什么角色AGENTS.md- 总调度中心这是整个框架的单一入口。它本身内容很“薄”主要作用是作为一个路由表清晰地指向所有其他核心组件的位置。这种设计遵循了“单一职责”和“明确入口”的原则无论是开发者还是AI模型都能第一时间知道从哪里开始了解整个系统。src/system_prompt.md- 系统内核这是框架的“大脑”。它定义了最核心的协作协议包括智能体Agents的协作机制不同智能体之间如何交接任务、传递上下文。编排Orchestration逻辑如何根据工作流程协调多个智能体的行动顺序。记忆Memory协议智能体如何读取和更新共享的工作状态与决策历史。“推理优先”原则强制要求每个智能体在输出最终答案前必须在一个reasoning标签内展示其思考过程。这是确保AI行动透明、可控的关键。src/agents/- 角色定义库这里存放着各个“虚拟员工”的岗位说明书。每个.md文件定义一个智能体例如architect.md、builder.md、critic.md。文件里会详细描述该角色的专长领域、职责边界、思考问题的角度以及输出格式要求。AI通过读取这些文件来“扮演”相应的角色。src/workflows/- 流程自动化脚本如果说智能体是“员工”那么工作流程就是“生产线”。index.md是流程目录里面可能定义了如feature-dev功能开发、bug-fix缺陷修复、parallel-review并行评审等标准化流程。每个流程详细规定了针对某类任务需要按什么顺序调用哪些智能体以及它们之间如何传递“工件”。src/rules/- 质量与规范守则这里是代码规范和开发规则的集合。base_rules.md是总索引可能链接到更具体的规则文件如typescript.md、python.md、security.md。智能体在编写代码时必须遵守这些规则这保证了产出代码的一致性、安全性和可维护性相当于把团队的编码规范直接“注入”到了AI的生成过程中。src/memory/- 项目协作记忆体这是实现持续上下文的关键。context.md工作内存。记录当前项目阶段、关注焦点、遇到的阻塞问题等临时但重要的状态。它随着项目推进而动态更新。decisions.md决策日志。这是一个只追加append-only的日志记录项目开发过程中所有重要的技术决策、方案选型的理由。这不仅是给AI看的上下文更是留给未来项目成员包括人类的宝贵文档。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本身不依赖特定的运行时环境它是一套方法论和文件结构的集合。因此集成它的核心步骤就是“复制与配置”。获取框架代码最直接的方式是从GitHub仓库scscodes/mide-lite克隆或下载项目文件。你也可以只复制其src目录下的核心结构和AGENTS.md、README.md等文件到你的项目根目录。集成到AI IDE框架的设计与Cursor IDE的理念高度契合。在Cursor中你可以直接将包含Mide-Lite文件的目录作为工作区打开。更常见的做法是在你现有项目的根目录下创建一个子目录例如/.ai或/mide将框架文件放置其中。这样既能利用框架又不会干扰主项目代码。关键配置点你需要根据自己项目的技术栈定制化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.底层流程Supervisor智能体接收到指令后会去src/workflows/index.md查找名为feature-dev的工作流程定义。该流程可能定义如下步骤Architect设计组件结构与数据流 -Builder实现前端页面与后端API -Critic进行代码审查与UI/UX评审 -Builder根据评审意见修改。Supervisor会按顺序激活这些智能体并将上一个智能体的输出工件作为下一个智能体的输入。整个过程中memory/context.md会记录当前进行到哪一步memory/decisions.md会记录关键的设计决策。适用场景开发一个完整的功能模块、系统性地重构一段代码、执行多角度的安全审计。它实现了跨智能体的、状态化的复杂任务自动化。3.3 定制属于你自己的智能体与流程框架的威力在于其可扩展性。开箱自带的智能体和流程只是例子你可以且应该根据自己团队的需求进行定制。创建新智能体在src/agents/目录下创建一个新的.md文件例如database_specialist.md。文件内容应清晰定义角色名称与目标例如“数据库专家专注于设计高效、可扩展的数据模型与查询”。核心能力擅长SQL优化、ORM配置、数据迁移策略、熟悉特定数据库如PostgreSQL的特性。工作方式在接到任务后必须首先分析业务场景与访问模式再给出设计。输出必须包含实体关系图ERD描述和关键查询示例。遵守的规则引用src/rules/database.md如果存在。在AGENTS.md或system_prompt.md中注册这个新智能体以便Supervisor能够调度它。创建新工作流程在src/workflows/目录下创建流程定义文件或在index.md中新增条目。定义流程的触发条件、阶段、每个阶段调用的智能体、以及工件传递的路径。例如一个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 调试与优化智能体协作当协作流程没有按预期工作时如何进行调试检查推理过程首先查看AI输出的reasoning部分。问题往往出在这里。可能是它误解了需求可能是它遗漏了某个关键规则也可能是它的思考路径存在逻辑漏洞。根据推理过程的问题去调整对应的智能体定义或初始指令。审查记忆状态检查context.md和decisions.md。看看AI是否正确地读取和更新了记忆。有时协作中断是因为上下文没有成功传递。隔离测试智能体如果在一个复杂流程中出错可以尝试单独调用流程中的某个智能体给它明确的输入看它是否能正确输出。这有助于定位是某个智能体的定义有问题还是流程编排的逻辑有问题。迭代优化定义文件将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框架的过程中我遇到并总结了一些典型问题及其应对策略。问题1AI似乎忽略了规则文件中的某些规定。可能原因规则描述过于冗长或分散导致模型注意力分散或者规则之间存在未被察觉的矛盾。解决方案精简与聚焦检查规则文件确保核心、重要的规则放在最前面并用加粗强调。每条规则尽量用一句话清晰表述。结构化索引确保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的协作从一种“艺术”或“技巧”变成了一种可管理、可迭代、可传承的“工程实践”。开始时会觉得增加了一些配置成本但一旦这套体系运转起来尤其是在需要长期维护和多人协作的项目中其带来的一致性、可追溯性和效率提升是非常显著的。你可以先从改造一个现有的、定义清晰的开发任务开始尝试比如为一个已有模块添加一套完整的单元测试亲自感受一下这种结构化协作与以往零散对话的区别。