1. 项目概述：一个为团队协作设计的AI多智能体开发框架
如果你和你的团队正在使用Cursor或者Claude Code这类AI编程工具，并且已经不止步于简单的代码补全和问答，而是希望将AI的能力系统化、工程化地融入到日常的开发流程中，那么你很可能已经遇到了一个瓶颈：如何让多个AI智能体（Agent）像一支训练有素的开发团队一样，各司其职、协同工作，完成从需求分析到代码测试的完整闭环？
这正是JahnelGroup开源的multi-agents项目要解决的核心问题。它不是一个独立的软件，而是一套精心设计的“脚手架”和“最佳实践”集合。你可以把它理解为一个为AI智能体协作而生的“开发规范”或“团队工作流模板”。这个项目将零散的、基于单次对话的AI交互，升级为结构化的、可重复的、多角色参与的自动化流水线。简单来说，它教会了你的AI助手们如何像人类团队一样开会、分工、写代码、评审和测试。
我花了几天时间深入研究了这个项目的三个层级（Foundation, Practitioner, Expert），并尝试将其应用到自己的一个前端组件库项目中。我的感受是，它最大的价值在于将“如何用好AI”这个模糊的经验问题，转化成了清晰、可复制、可教学的工程问题。无论你是想个人提效，还是带领团队规模化应用AI编码，这套框架都提供了一个极具参考价值的起点。
2. 核心架构与设计哲学拆解
2.1 什么是智能体、规则与流水线？
在深入代码之前，我们必须统一语言。multi-agents项目建立在三个核心概念之上，理解它们是使用这套框架的前提。
智能体是框架中的“角色扮演者”。每个智能体都是一个独立的AI实例，拥有特定的模型、明确的职责、输入输出规范和行为指令。例如：
- 规划者：负责将模糊的需求拆解成具体的、可执行的任务清单。
- 执行者：接收具体任务，编写实现代码。
- 评审者：检查代码质量，确保符合团队规范。
- 测试者：为生成的代码编写或运行测试用例。
每个智能体都对应一个.md文件，里面定义了它的“人设”和“工作流程”。这比在每次对话中手动输入“请你扮演一个资深架构师...”要高效和稳定得多。
规则是框架中的“交通法规”和“公司制度”。它们是始终生效或由特定文件触发的行为准则，会被自动注入到相关智能体的思考上下文中。规则文件以.mdc为后缀，通常包含YAML头信息来定义其适用范围。例如：
planner-first.mdc：一条“始终应用”的规则，强制要求任何开发任务都必须先由规划者智能体进行分析，生成计划后才能执行。这避免了AI跳过规划直接写代码可能带来的架构混乱。commit-conventions.mdc：一条“当.git/目录下的文件被修改时触发”的规则，它会自动提醒智能体遵循团队的Git提交信息规范（如Conventional Commits）。
规则是确保智能体行为符合团队预期、保持代码库一致性的关键护栏。
流水线则是将智能体和规则串联起来的“自动化生产线”。它定义了完成一个功能或修复一个Bug的标准工作流。一个典型的流水线可能如下运行：
- 用户提出需求：“为登录表单添加手机号验证功能。”
- 规划者智能体被触发，分析需求，输出一个结构化的“计划工件”，包含任务列表、文件变更预估等。
- 流水线工具（
pipeline/check.py）验证该计划工件的格式和完整性。 - 执行者智能体接收通过验证的计划，开始编写
LoginForm.vue和validation.js的代码。 - 评审者智能体检查新代码，提出修改建议。
- 测试者智能体为新增的验证逻辑编写单元测试。
- 所有步骤通过后，Git智能体（如果配置了）可以生成格式规范的提交。
整个过程中，相应的规则文件（如代码规范、安全规则）会在后台默默发挥作用，约束每个智能体的输出。
2.2 分层能力模型：从入门到专家
项目最巧妙的设计之一是它的“三级能力模型”（Foundation, Practitioner, Expert）。这不仅仅是一个教学路径，更是一种可扩展的架构思想。
基础层面向AI新手。它只包含3个核心智能体（规划者、执行者、Git）和1条基础规则（规划优先）。它的目标是让开发者理解“多智能体协作”的基本概念和模式。通过6个概念性练习，你能搞明白智能体、规则、流水线到底是什么，以及为什么需要它们。这一层的关键是建立认知，而不是急于求成。很多团队跳过这一步，直接上复杂流水线，结果因为基础概念不牢，遇到问题无从排查。
实践者层是大多数团队应该直接采用的“生产就绪”套件。它包含了8个智能体、4条规则、2项技能和完整的流水线工具。在这里，你会接触到子规划者（处理复杂任务中的子任务）、调试者（分析错误日志）、基准测试者（评估性能）等更专业的角色。这一层的11个练习是动手实操的，要求你真正指挥智能体们协作完成一个功能。我的体会是，从这一层开始，你才真正从“使用AI”转变为“驾驭AI”。你需要学习如何撰写清晰的指令、如何设计有效的“工件”（Artifact，即智能体间传递的结构化数据），并理解流水线中的各个“关卡”检查。
专家层面向架构师和团队负责人。它引入了约15个分层级智能体、复杂的路由规则、成本追踪和系统设计。在这一层，核心问题变成了“如何用最合适的模型（和成本）完成工作”。例如，简单的代码格式化任务可能路由到便宜快速的claude-3-haiku，而复杂的架构决策则交给能力更强但也更贵的gpt-4或claude-3-opus。这一层关注的是规模化、成本优化和系统可靠性，包括如何设计监控、如何让智能体在遇到困难时自动“升级”给更强大的模型处理。
实操心得：如何选择起步层级？不要因为“专家”听起来更厉害就直接复制专家层。对于新项目或AI经验尚浅的团队，强烈建议从实践者层开始。它的配置已经足够应对80%的日常开发场景。先跑通整个流程，建立信心和理解，然后再根据实际遇到的瓶颈（如成本过高、复杂任务处理不佳），有选择地从专家层借鉴思路（如成本路由规则）进行增强。直接使用专家层过于复杂，容易让人望而却步。
3. 项目结构与核心文件详解
3.1 目录布局：一切皆有定式
multi-agents的目录结构非常清晰，遵循“约定大于配置”的原则。了解每个文件夹的作用，是自定义和扩展的基础。以.cursor-practitioner/目录为例：
.cursor-practitioner/ ├── agents/ # 智能体定义库 │ ├── planner.md # 规划者 │ ├── worker.md # 执行者 │ ├── reviewer.md # 代码评审者 │ └── ... # 其他智能体 ├── rules/ # 行为规则库 │ ├── planner-first.mdc # 强制先规划 │ ├── commit-conventions.mdc # 提交规范 │ └── ... # 其他规则 ├── skills/ # 按需调用的技能 │ ├── pipeline-artifact-io/ │ │ └── SKILL.md # 如何读写流水线工件 │ └── benchmark-ops/ │ └── SKILL.md # 如何运行基准测试 ├── pipeline/ # 流水线核心工具 │ ├── schema.py # 验证工件JSON格式 │ ├── check.py # 关卡检查逻辑 │ └── README.md # 工件格式文档 ├── templates/ # 创建新组件的模板 ├── walkthrough/ # 完整流水线运行示例（只读） ├── tutorials/ # 练习目录（含验证脚本） ├── AGENTS.md # 智能体注册表（索引与执行顺序） └── README.md # 本层级的说明文档关键文件解读：
agents/*.md: 每个文件定义一个智能体。内容通常包括：role（角色）、model（使用的AI模型）、input（期望的输入格式）、output（输出的格式）、以及详细的instructions（行为指令）。Cursor会根据这些文件自动发现可用的subagent_type。rules/*.mdc: 规则文件。其YAML头信息是灵魂，例如：--- description: “所有代码变更必须经过评审” alwaysApply: false # 非始终应用 globs: ["**/*.js", "**/*.ts", "**/*.py"] # 仅当这些文件被修改时触发 ---AGENTS.md: 这是智能体的“总调度表”。它列出了所有可用智能体、它们在流水线中的默认执行顺序，以及它们对应的subagent_type名称。当你通过Cursor的指令（如@agent）调用时，就是参考的这个映射关系。
3.2 核心机制：工件、关卡与技能
工件是智能体之间通信的“标准化信封”。它通常是一个JSON文件，包含了当前任务的所有上下文信息，例如需求描述、计划、生成的代码、评审意见等。pipeline/schema.py文件使用Pydantic等库定义了工件的严格数据结构。这确保了信息传递的准确性和可追溯性。在设计自己的智能体时，定义清晰的工件Schema是第一步，也是避免混乱的关键。
关卡是流水线上的“质量检查点”。pipeline/check.py脚本会在关键节点（如规划完成后、代码编写完成后）被调用，验证当前工件的状态是否满足进入下一阶段的条件。例如，检查“计划工件”是否包含了所有必要的任务项；检查“代码工件”是否已经通过了所有静态分析检查。关卡是实现“自动化流水线”而非“随意对话”的核心，它强制了流程的纪律性。
技能与规则不同，它不是自动注入的，而是像“工具书”一样，在智能体需要执行特定复杂操作时，被其主动查询和引用。例如，pipeline-artifact-io技能详细说明了如何正确地读取上一个智能体输出的工件，以及如何将本步骤的结果格式化成下一个智能体需要的工件。技能的存在，使得智能体可以处理标准化但复杂的操作，而无需在每次指令中重复说明。
4. 实战部署与个性化定制指南
4.1 如何将框架集成到你的项目？
部署过程非常简单，但正确的步骤能避免后续的混乱。
选择层级并复制：进入你的项目根目录，执行以下命令。对于大多数团队，我推荐从实践者层开始。
# 假设你的项目名为 my-app cd path/to/my-app # 复制实践者层全套配置到项目的 .cursor 目录 cp -r /path/to/multi-agents/.cursor-practitioner/ .cursor/这会在你的项目下创建一个
.cursor/目录，里面包含了所有智能体、规则和流水线配置。验证环境与模型：确保你的Cursor设置中启用了框架所需的AI模型。有些高级模型（如
gpt-5.1-codex-max）默认是隐藏的。你需要打开Cursor Settings > Models，并勾选你需要的模型。框架中的智能体定义文件（如agents/planner.md）会指定它使用的模型，如果本地未启用，流水线会报错。进行“冒烟测试”：运行项目自带的教程来验证配置是否成功。进入
.cursor/tutorials/目录，按照README.md的指示完成第一个练习。这能帮你快速理解整个工作流是如何运转的。
4.2 个性化定制：打造属于你团队的智能体团队
直接使用默认配置是第一步，但要让AI真正融入你的团队，必须进行定制。
1. 定制智能体行为：打开agents/worker.md（执行者），你会发现其instructions部分包含了通用的编程指令。你需要在这里注入你团队的特定知识。
- 添加技术栈规范：例如，“本项目使用React函数组件与TypeScript，禁止使用
any类型，样式采用Tailwind CSS。” - 引入项目结构约定：“工具函数请放在
src/utils/下，API请求层放在src/services/，组件必须放在src/components/的对应功能文件夹内。” - 定义代码风格：“使用ESLint和Prettier的默认规则，缩进为2个空格。”
2. 创建团队专属规则：在rules/目录下创建以team-为前缀的新.mdc文件。例如team-security.mdc：
--- description: “安全编码规范检查” alwaysApply: true --- 严禁在代码中硬编码API密钥、数据库密码等敏感信息。 所有用户输入在拼接SQL或渲染到DOM前必须进行验证或转义。 ...这条规则会对所有能写代码的智能体（如执行者、调试者）始终生效。
3. 扩展流水线关卡：你可以修改pipeline/check.py，在现有检查基础上增加团队特有的质量门禁。例如，在代码评审阶段后，增加一个“安全检查”关卡，调用一个简单的安全扫描脚本：
def security_check(artifact): """自定义安全检查关卡""" code_path = artifact.get("output_path") if not code_path: return True # 如果没有代码输出，跳过 # 调用一个简单的自定义安全脚本（示例） import subprocess result = subprocess.run(['python', 'team_scripts/security_linter.py', code_path], capture_output=True, text=True) if result.returncode != 0: print(f"安全检查失败: {result.stderr}") return False return True # 在主要的检查流程中集成这个函数重要命名约定与升级策略项目采用了清晰的命名前缀来管理文件来源：
jg-*： 来自 JahnelGroup 原始仓库的共享文件。切勿修改。它们是上游依赖，升级时会被覆盖。<team>-*或my-*： 你或你的团队自定义的文件。例如team-security.mdc,my-special-agent.md。升级框架时，这些文件会被保留。- 无前缀文件： 谨慎使用。通常是个人的临时实验文件。
升级框架的正确姿势：当你想从实践者层升级到专家层，或获取框架的新版本时：
- 备份你自定义的
team-*和my-*文件。- 用新的
.cursor-expert/覆盖.cursor/目录。- 将备份的自定义文件复制回来。
- 使用
diff工具对比新旧版本的jg-*文件，了解变更内容，并决定是否需要将某些改动同步到你的自定义文件中。这套机制确保了你可以持续获得框架的更新，同时保留自己的定制化内容。
5. 与Claude Code的兼容性与成本考量
5.1 跨IDE适配：概念一致，实现不同
multi-agents的设计是IDE无关的。其核心概念——智能体角色、工件、流水线阶段——在任何支持AI编程助手的环境中都适用。但具体的“接线”方式因IDE而异。
| 概念 | 在 Cursor 中的实现 | 在 Claude Code 中的近似实现 |
|---|---|---|
| 规则 | .cursor/rules/*.mdc文件 | 在项目根目录的CLAUDE.md文件中，以常驻指令的形式存在。 |
| 智能体 | .cursor/agents/*.md文件，通过subagent_type调用 | 在CLAUDE.md中，通过章节或引用其他文档来描述不同任务下的角色和指令。 |
| 技能 | .cursor/skills/*/SKILL.md目录 | 项目.claude/commands/目录下的.md文件，作为可调用的命令。 |
| 流水线调度 | 通过@agent指令和subagent_type自动路由 | 更多地依赖于在对话中手动或通过提示词序列，引导Claude按阶段（规划、编码、评审）工作。 |
迁移要点：虽然配置文件不能直接复制粘贴，但walkthrough/目录下的示例工件（结构化的JSON输出）以及智能体的核心指令文本，完全可以复用到Claude Code中。你需要做的是在CLAUDE.md中重建这套工作流和角色系统的上下文。
5.2 成本控制与优化策略
使用多智能体流水线意味着一次任务会调用多次AI模型API，成本是必须考虑的因素。专家层专门为此设计了策略。
1. 分层模型路由：这是最有效的成本优化手段。其核心思想是“让合适的模型做合适的事”。在agents/配置中，你可以为不同智能体指定不同模型：
- 规划者/评审者：处理需要深度理解和逻辑推理的文本任务，可以使用能力强的模型（如
claude-3-opus,gpt-4）。 - 执行者：进行常规的代码编写和修改，可以使用性价比高的模型（如
claude-3-sonnet,gpt-3.5-turbo）。 - 格式化者/简单任务执行者：处理代码格式化、重命名等简单任务，可以使用轻量级模型（如
claude-3-haiku）。
通过在AGENTS.md中配置路由逻辑，可以让一个智能体任务根据复杂度自动选择不同层级的模型。
2. 上下文管理：AI模型的成本与输入输出的令牌数直接相关。务必在智能体指令中强调“简洁”、“只输出必要内容”。避免让智能体在输出中复述整个需求或历史对话。利用好“工件”系统，将关键信息结构化传递，而不是塞在冗长的自然语言对话里。
3. 监控与审计：专家层提到了成本追踪。你可以通过简单的脚本来记录每次流水线运行所调用的模型和估计的令牌消耗。例如，在流水线的每个阶段结束后，将相关信息追加到一个日志文件。定期分析这些日志，找出成本高的环节并进行优化（例如，是否某个规则注入了过多的上下文？是否某个智能体的指令过于冗长？）。
成本意识实践：在项目初期，可以在Cursor的设置中为每个模型设置一个较低的月度预算上限，或者先使用速率限制更严格的模型进行探索。同时，养成一个习惯：在启动一个复杂的多智能体流水线任务前，先手动评估一下这个任务是否真的需要动用“全流程”。有时候，一个简单的问题，直接问AI可能比启动整个流水线更经济快捷。
6. 常见问题、排查技巧与安全实践
6.1 实战问题速查表
在实际使用中，你可能会遇到以下典型问题。这里提供我的排查思路：
| 问题现象 | 可能原因 | 排查步骤与解决方案 |
|---|---|---|
Cursor无法识别或调用智能体（@agent不生效） | 1..cursor/目录位置错误。2. AGENTS.md中subagent_type映射错误或缺失。3. 智能体 .md文件格式错误。 | 1. 确认.cursor/在项目根目录。2. 检查 AGENTS.md，确保智能体名称与@agent调用的名称匹配。3. 打开有问题的智能体 .md文件，检查其YAML头信息或内容是否有语法错误。 |
| 流水线卡住，不进入下一阶段 | 1. 上一个智能体的输出不符合“工件”Schema。 2. pipeline/check.py中的关卡检查失败。3. 智能体指令不清晰，导致输出混乱。 | 1. 运行python .cursor/pipeline/schema.py手动验证上一个输出的JSON文件。2. 查看 check.py的运行日志或错误信息。3. 简化并明确当前阶段智能体的指令，要求其严格按指定JSON格式输出。 |
| 智能体行为不符合预期（如写了不符合规范的代码） | 1. 对应的规则（.mdc）未生效。2. 智能体自身的 instructions不够具体或与规则冲突。3. 模型“忘记”了长指令。 | 1. 检查规则文件的globs或alwaysApply设置是否正确。2. 强化智能体指令，将关键规范放在指令最前面。 3. 考虑将非常长的规范拆分成独立的“技能”文件，让智能体在需要时引用。 |
| 成本异常高 | 1. 使用了过于强大的模型处理简单任务。 2. 上下文窗口过大，注入了太多不必要的历史信息。 3. 流水线步骤过多，存在冗余。 | 1. 实施分层模型路由策略。 2. 审查规则和技能文件，移除冗余的上下文信息。 3. 审视流水线设计，合并可以一步完成的步骤。 |
6.2 安全护栏设置：给AI戴上“紧箍咒”
让AI自动写代码和操作Git是强大的，但也伴随着风险。multi-agents项目内置了一些安全思想，你需要根据自己团队的情况强化它。
权限隔离原则：
- 只读智能体：像
planner（规划者）、reviewer（评审者）这类只进行分析和提议的智能体，应在其定义中明确设置readonly: true（如果框架支持）或在指令中强调“你只提供建议，不直接修改任何文件”。 - 写权限智能体：只有
worker（执行者）、debugger（调试者）等少数智能体被允许直接写代码。严格控制它们的数量。 - 系统操作智能体：
tester（测试者）、git（Git操作）智能体可以运行命令。必须在其指令中严格限定可执行的命令范围，并禁止执行rm -rf、:wq等危险操作。
Git操作安全：在git智能体的指令中，必须明确禁止以下行为：
严禁执行 `git push --force`。 严禁绕过 pre-commit 钩子。 严禁直接向 `main` 或 `master` 分支推送代码。所有变更必须通过Pull Request。 在创建PR后，必须等待人类审查员（你）的明确批准指令后，才能进行合并操作。代码安全扫描集成：可以将简单的安全扫描作为流水线的一个强制关卡。例如，在pipeline/check.py中的代码评审阶段后，集成调用bandit（Python安全扫描）或npm audit（Node.js依赖检查）的脚本。只有扫描通过，才允许进入提交阶段。
6.3 版本控制与团队协作
.cursor/目录应该被纳入版本控制（Git），这样团队所有成员都使用同一套智能体配置。但是，要注意忽略运行时文件：
- 在你的项目
.gitignore文件中，确保添加.pipeline/。这个目录是流水线运行时的临时状态，不应提交。 walkthrough/目录下的示例工件是只读的学习材料，可以提交。- 团队成员个人的、未成熟的实验性智能体或规则，建议使用
my-前缀，并谨慎提交，或者通过.gitignore个人化配置来排除。
最后，我想分享一点个人体会：引入multi-agents这类框架，最大的挑战不是技术，而是工作习惯的转变。你需要从与AI进行自由对话的模式，转变为设计流程、定义规范、审查结果的“管理者”模式。初期可能会觉得繁琐，但一旦这套流程跑顺，它将极大地提升复杂任务完成的确定性、代码质量的一致性和团队协作的效率。它让AI从一位才华横溢但不可预测的“独行侠”，变成了一个遵守流程、值得信赖的“团队伙伴”。
