多智能体协作框架设计：从需求到交付的自动化产品开发实践

1. 项目概述：一个为AI产品经理设计的自动化多智能体协作系统

如果你是一名AI产品经理，或者正在尝试用AI Agent来辅助完成从需求到上线的完整产品开发流程，那么你一定遇到过这样的困境：单个AI Agent能力有限，而让多个Agent协同工作又常常陷入混乱。需求理解不清、任务拆解不细、原型与代码脱节、问题打回成本高昂……这些痛点每天都在消耗我们的精力。

今天要分享的，是我在深度实践后，重构并落地的一套名为“Harness_Multi-Agent_AI_PM”的Skill体系。它不是一个简单的工具集合，而是一个高度解耦、流程清晰、具备自我校准能力的多智能体协作框架。其核心目标，是模拟一个成熟产品团队的完整工作流，将“产品想法”自动化、高质量地转化为“可交付的软件模块”。这套体系基于WorkBuddy平台构建，通过定义五个明确的阶段、七个各司其职的Agent角色，以及一套名为“Harness”的精细化控制机制，实现了从需求澄清、原型设计到编码开发、测试验收的全流程自动化管理。

简单来说，它就像给你的AI团队聘请了一位资深的产品总监（Orchestrator），并配备了需求分析师（Analyst）、架构规划师（Planner）、原型设计师（Designer）和工程指挥官（Runner）等专业角色。每个角色职责清晰，通过严格的上下文共享和阶段门控机制协同工作，最大程度避免了传统多Agent协作中常见的“方向漂移”和“返工地狱”。无论你是想从零开发一个个人工具，还是为现有系统添加复杂功能，这套体系都能提供一个稳定、可预测的自动化产出路径。接下来，我将为你彻底拆解它的设计哲学、核心架构以及每一个实操细节。

2. 架构核心：五阶段流程与三段式解耦设计

2.1 为什么是“五阶段”？—— 模拟真实产品开发的生命周期

很多自动化工具失败的原因在于试图用单一流程解决所有问题，或者流程阶段划分模糊，导致Agent在不同性质的工作间跳跃，上下文混乱。本体系采用的“五阶段流程”（P1-P5）是对经典产品开发流程（需求-设计-开发-测试-交付）的抽象和优化，每个阶段都有明确的输入、输出和“完成定义”。

第一阶段：需求→分析→拆解这是项目的奠基阶段，目标是产出清晰、无歧义的“开发宪法”。此阶段由pm-analyst和pm-planner两个Agent接力完成。pm-analyst的核心工作是“追问”，它被强制要求与用户进行至少三轮对话，以挖掘模糊需求背后的真实约束、业务目标和用户场景。其产出goal.md文件，是一个结构化的目标对象，而非一段自然语言描述。随后，pm-planner接手，将宏观目标颗粒化为可执行的模块。这里的“模块”是关键设计，每个模块包含不超过5个功能点及明确的验收标准，并构建出模块间的依赖有向无环图。这个阶段的严谨性，直接决定了后续所有工作的效率。

第二阶段：原型+UI定型这是本体系最具创新性的“校准基石”阶段。在投入一行代码之前，pm-designerAgent会基于P1的产出，生成可交互的低保真原型（通常是HTML+CSS）、组件树和页面路由图。这个原型需要经过Orchestrator和用户的共同确认。其价值在于，用一个极低的成本（相比写代码），让所有参与者——用户、产品经理、后续的开发Agent——对“要做什么”达成视觉和交互层面的一致共识。它能有效避免开发完成后才发现“这不是我想要的”巨大浪费。

第三阶段：架构→开发→测试只有当前两个阶段被确认后，开发工作才会启动。pm-runner作为本阶段的指挥官，负责调度pm-coder,pm-researcher,pm-writer等子Agent。它依据P1产生的依赖图进行智能调度，优先开发无依赖或低依赖的模块，实现并行化。更重要的是，每个开发任务都会“注入”P2确认的原型作为对齐依据，确保代码实现不偏离设计初衷。

第四阶段：打回循环任何自动化流程都无法保证一次成功。P4定义了问题出现时的标准化处理流程。其核心规则是“最小必要回退点”决策。例如，如果测试发现某个功能与原型不符，问题可能被定位到P3的开发环节；但如果发现是原型本身无法满足核心需求，则可能需要回退到P2甚至P1。这个决策由全局视角的Orchestrator做出，避免了执行层Agent（如pm-runner）因局部信息做出全局性误判。

第五阶段：整合交付这是收尾阶段，以模块为单位进行交叉验收和整合测试。Orchestrator会组织相关Agent对每个模块进行评审，并生成最终的复盘报告，将本次项目中的经验（如某个技术选型的优劣、某个模块的拆解方式）沉淀到系统的“记忆”中，用于优化未来的项目。

注意：这五个阶段是强顺序的，存在“阶段门控”。P2必须等待P1完成且产出被审核通过，P3必须等待P2的原型被确认。这种阻塞设计虽然看似降低了并发度，但极大地保障了流程的确定性和产出质量，是避免AI项目陷入混沌的关键。

2.2 “三段式解耦”如何解决传统Orchestrator的臃肿问题？

在早期的多Agent系统中，Orchestrator（编排器）常常成为一个“上帝类”，它既要理解需求，又要拆解任务，还要调度资源，监控进度，导致逻辑复杂、难以维护且容易成为性能瓶颈。本体系的核心改进就是“三段式解耦”，将Orchestrator的职责大幅精简。

瘦身后的Orchestrator：它的新定位是“流程交警”和“信息枢纽”。主要职责只剩四件：1.监听与同步：监控各阶段Agent的状态和产出。2.阶段切换决策：根据阶段完成标准，决定是否推进到下一阶段或触发打回。3.上下文收集与分发：维护并更新“上下文池”，确保正确的信息在正确的阶段被正确的Agent访问。4.用户交互：作为系统对外的统一接口。它不再直接处理需求分析、任务拆解、代码编写等具体业务。这种设计让Orchestrator变得轻量、稳定，焦点完全集中在流程控制上。

职责分发到专业Agent：

• pm-analyst：专职负责“需求澄清”。它的技能树点在了对话、追问和结构化信息提取上，确保初始输入的质量。
• pm-planner：专职负责“颗粒化拆解”。它将分析师产出的清晰目标，转化为机器可理解、可执行的模块化蓝图和依赖关系图。
• pm-runner：专职负责“调度执行”。它根据规划师提供的蓝图，像一个工程经理一样，管理子Agent资源池，处理任务调度、依赖解决和异常监控。

通过这种解耦，每个Agent都可以独立优化和迭代。例如，你可以替换一个更强大的需求分析模型给pm-analyst，而无需改动pm-planner或pm-runner的逻辑。系统的复杂度和灵活性得到了很好的平衡。

2.3 上下文池与HEARTBEAT：项目协同的“中央神经系统”

多Agent协作最大的挑战之一是信息孤岛和状态不一致。本体系通过“上下文池”和“HEARTBEAT双层记忆”机制来解决。

上下文池：这是一个虚拟的、结构化的项目共享存储区。它不是一个聊天历史，而是一系列有严格权限控制的Markdown和资源文件。例如，goal.md由pm-analyst写入，其他Agent大多只读，确保项目目标不被随意篡改。prototype/目录由pm-designer写入，pm-coder只能读取以对齐开发。这种细粒度的读写控制，模拟了真实团队中不同角色对文档的权限管理，保证了信息的权威性和一致性。

HEARTBEAT双层记忆：

1. 项目级记忆：记录全局进度、阶段状态、关键技术决策、已知风险和问题。它就像项目的仪表盘，让Orchestrator和用户一眼就能看清项目全貌。
2. 任务级记忆：记录每个具体任务（如T001: 实现用户登录API）的详细状态、执行上下文、中间输出和健康度。这帮助pm-runner进行精细化的任务管理和故障恢复。

这个“中央神经系统”确保了即使某个Agent中途失败或被重启，它也能从上下文中快速恢复工作状态，不会丢失关键项目上下文，这是实现长周期、复杂项目自动化的基石。

3. 核心Agent角色详解与实操配置

3.1 各Agent的职责边界与技能设计

每个Agent都是一个独立的Skill，其能力通过SKILL.md文件定义。理解每个Agent的精确职责和交互方式，是有效使用该体系的关键。

pm-orchestrator (主控器)

• 核心职责：流程控制、上下文同步、决策路由。它是整个系统的启动器和协调者。
• 触发词：“开发”、“实现”、“做一个”、“搭建”。当用户在WorkBuddy中输入这些关键词时，Orchestrator会被激活。
• 实操要点：它的Skill指令集主要包含阶段状态机管理、上下文文件读写、以及生成其他Agent的调用指令。它自己不进行复杂推理，而是基于规则和当前上下文做出流程判断。例如，当它发现prototype/目录下生成了新的wireframe.html且component-tree.md完整，就会触发“原型验收”流程。

pm-analyst (需求分析师)

• 核心职责：将模糊的用户需求转化为结构化的、可衡量的项目目标。
• 关键动作：“至少三轮追问”。这是硬性规定。第一轮通常澄清核心功能（What），第二轮挖掘用户场景和约束（Who, When, Where），第三轮确认非功能需求和成功标准（How well）。例如，用户说“做个记账App”，分析师会追问：“是个人用还是家庭共享？”、“需要支持多币种吗？”、“数据同步是必须的吗？”。
• 产出：product.md(项目背景)、goal.md(结构化目标)、requirements.md(需求清单)。goal.md的格式至关重要，通常包含项目名称、核心用户、主要功能、技术约束、成功指标等字段。

pm-planner (规划师)

• 核心职责：将宏观目标拆解为可并行开发的原子模块，并理清依赖关系。
• 核心产出：
  1. modules.md：模块列表。每个模块格式为：## [模块名]、功能点、验收标准、输出物。
  2. dependency-dag.md：依赖有向无环图。使用Mermaid语法绘制，必须确保无环，否则会导致调度死锁。
  3. skills-needed.md：列出完成各模块所需的子Skill（如需要调用特定的数据库操作Skill、图表绘制Skill等）。
• 避坑经验：模块粒度的把握是难点。粒度过粗（如“实现前端”），无法指导开发；粒度过细（如“实现登录按钮点击事件”），会产生海量任务，管理开销剧增。实践中，一个模块应对应一个可以独立测试、价值交付明确的子系统，如“用户认证模块”、“数据导出模块”。

pm-designer (原型设计师)

• 核心职责：在编码前，产出可视化的交互蓝图。
• 工作流：读取goal.md和modules.md-> 绘制用户交互流程图 -> 设计组件树（定义可复用的UI组件）-> 定义页面路由 -> 生成可交互的线框图。
• 工具链：通常利用AI生成Mermaid图来描述流程，生成HTML/CSS/JS来构建一个静态但可点击的原型。这个原型不需要美观，但必须完整覆盖所有核心用户路径。
• 价值：这是最重要的“防跑偏”环节。我曾在一个项目中跳过此阶段，直接进入开发，结果coder对“仪表盘”的理解与用户预期大相径庭，导致全部返工。自此之后，我强制要求所有项目必须经过P2。

pm-runner (执行指挥官)

• 核心职责：调度子Agent，按计划执行开发任务。
• 核心能力：
  1. DAG调度器：解析dependency-dag.md，识别可以并行开发的模块批次。
  2. 策略引擎：处理子任务执行中的阻塞（如前序任务失败）、超时和资源竞争。
  3. 健康监控：监控子Agent（如pm-coder）的“健康度”（一个综合了响应速度、任务成功率等指标的分数），低于阈值（如30）会向Orchestrator告警。
  4. 上报机制：它无权自行决定将任务打回至更早阶段。当遇到无法解决的问题（如依赖的技术库突然不兼容），它只能“上报”问题给Orchestrator，由后者做出全局决策。
• 实操命令：它的Skill中包含类似spawn pm-coder with task T001 and context [module_details]的指令，并能注入诸如“请参考prototype/login.html中的设计”这样的上下文提示。

3.2 Harness：为每个Agent戴上“方向盘”

Harness是本体系另一个精妙的设计。你可以把它理解为每个Agent的“个性化驾驶舱配置”。它不是一个Skill，而是一组控制Agent行为的约束和参数。

每个Agent在harnesses/目录下都有一个对应的配置文件（如analyst-harness.md）。主要配置项包括：

• mode: 工作模式，如strict（严格遵循流程）、creative（允许更多创造性发散）。
• max_turns: 最大对话轮次。对于pm-analyst，这至少是3；对于pm-coder，可能设置为10，以允许更多的调试交互。
• allowed_tools: 允许该Agent使用的工具集。例如，pm-researcher可能被允许使用网络搜索和文档读取工具，而pm-coder则被限制只能使用代码编辑器和终端。
• constraints: 行为约束。例如，为pm-planner设置约束：“单个模块功能点不得超过5个”，“依赖图必须为有向无环图”。

配置示例 (planner-harness.md):

# Planner Agent Harness Configuration **Mode:** structured **Max_turns:** 5 **Allowed_tools:** - File read/write (context_pool) - Mermaid diagram generator - Markdown formatter **Constraints:** 1. Each module MUST have no more than 5 functional points. 2. Each functional point MUST have a clear, testable acceptance criterion. 3. The dependency graph MUST be a Directed Acyclic Graph (DAG). 4. If a circular dependency is detected, re-plan the module decomposition. 5. Output must strictly follow the templates in `shared/references/`.

通过Harness，你可以精细地调控每个Agent的“性格”和能力边界，防止它们越界或做出不符合预期的行为，让整个系统运行得更稳定、更可控。

4. 完整工作流实操：从零构建一个Markdown笔记应用

让我们通过一个具体案例，串联起整个五阶段流程。假设我们的目标是：“开发一个支持Markdown编辑、实时预览、本地存储和标签管理的桌面笔记应用”。

4.1 第一阶段实操：需求澄清与模块拆解

1. 用户输入：在WorkBuddy中，我们输入：“帮我做一个Markdown桌面笔记应用，要能实时预览，存在自己电脑上，还能打标签。”
2. Orchestrator触发：识别到“做一个”这个触发词，Orchestrator被激活。它初始化上下文池，创建product.md文件，并生成指令spawn pm-analyst with user_request。
3. pm-analyst工作：
   • 第一轮追问：“您说的‘桌面应用’具体指哪种技术形式？比如Electron（跨平台）、Tauri（更轻量）还是原生系统应用？”
   • 用户回答：“用Electron吧，希望能在Windows和Mac上都能用。”
   • 第二轮追问：“‘实时预览’是边输入边渲染，还是需要一个手动切换的按钮？标签是平铺的，还是支持嵌套层级？”
   • 用户回答：“边输入边渲染最好。标签支持平铺就行，但希望能给一个笔记打多个标签。”
   • 第三轮追问：“本地存储方面，除了笔记内容和标签，需要支持附件（如图片）吗？数据备份有什么考虑？”
   • 用户回答：“暂时不需要附件。备份功能最好有，能手动导出所有数据为单个文件就行。”
   • 产出：pm-analyst将对话结果结构化，写入goal.md。内容大致如下：

     # Project Goal: Markdown Desktop Note App **Core User**: Individual users needing a lightweight, offline-first note-taking tool. **Key Features**: 1. Rich Markdown editing with live preview (side-by-side or inline). 2. File-based local storage (notes saved as `.md` files in a user-designated folder). 3. Tag management system: multiple tags per note, tag filtering and browsing. 4. Data export: ability to backup all notes and tags into a single archive file. **Tech Stack**: Electron + React (for UI) + Node.js (for file system operations). **Success Metrics**: - Launch app and create a new note within 3 seconds. - Typing in editor reflects in preview with < 100ms latency. - Tags persist correctly after app restart.

4. Orchestrator审核：Orchestrator检查goal.md，确认关键要素（功能、约束、指标）齐全，然后spawn pm-planner。
5. pm-planner工作：
   • 读取goal.md，开始功能拆解。
   • 模块化分组：
     • M01: 应用框架与窗口管理：Electron主进程/渲染进程搭建，基础窗口创建。
     • M02: 笔记数据模型与存储：定义Note对象（id, title, content, tags, createdTime），实现基于本地文件系统的CRUD操作。
     • M03: Markdown编辑器与预览器：集成一个Markdown编辑器组件（如CodeMirror），实现一个Markdown渲染组件（如Marked.js），并实现实时同步逻辑。
     • M04: 标签管理系统：Tag对象的CRUD，笔记-标签的多对多关系维护，提供按标签过滤笔记的接口。
     • M05: 用户界面与交互：主界面布局（笔记列表、编辑区、标签栏），实现上述模块的UI组件并串联交互。
     • M06: 数据导入导出：实现将整个笔记库打包为单一JSON或压缩文件的功能。
   • 构建依赖DAG：

     graph TD M01[应用框架] --> M02[数据存储]; M01 --> M03[编辑器]; M01 --> M05[UI]; M02 --> M03; M02 --> M04[标签系统]; M02 --> M06[导入导出]; M03 --> M05; M04 --> M05; M04 --> M02;

     注意：M04（标签系统）依赖于M02（数据存储）来持久化标签数据，同时M02也依赖M04来维护笔记-标签关系，这里存在一个互相依赖。pm-planner需要识别并解耦这个环，例如，将“关系维护”作为一个独立的子模块或接口。
   • 产出：modules.md,dependency-dag.md,tasks.md（将模块进一步拆分为具体任务，如M02-T01: 定义Note数据模型），以及skills-needed.md（可能需要electron-builder的打包Skill）。

4.2 第二阶段实操：原型设计作为开发锚点

1. Orchestrator触发P2：审核通过P1产出后，spawn pm-designer。
2. pm-designer工作：
   • 读取goal.md和modules.md。
   • 绘制交互流程图：描述用户从打开App、创建笔记、编辑、打标签到导出的完整路径。
   • 设计组件树：

     App ├── MainLayout │ ├── Sidebar (NoteList, TagFilter) │ └── Workspace │ ├── EditorPanel (MarkdownEditor) │ └── PreviewPanel (MarkdownPreview) ├── NoteEditorModal └── ExportModal

   • 生成低保真可交互原型：使用简单的HTML、CSS和JavaScript，构建一个静态页面。这个页面有侧边栏列表、一个文本输入框（模拟编辑器）、一个渲染区域（模拟预览）、一个标签输入框和几个按钮。虽然不能真正保存数据，但可以模拟点击笔记列表切换编辑区内容、输入Markdown后预览区实时变化等交互。
3. 原型验收：Orchestrator将原型链接呈现给用户。用户操作后确认：“对，我想要的布局和交互大概就是这样。”这个确认动作至关重要，它锁定了后续开发的视觉和交互基线。

4.3 第三阶段实操：基于原型的并行开发

1. Orchestrator触发P3：原型确认后，spawn pm-runner。
2. pm-runner启动：
   • 步骤1：技术架构讨论。pm-runner可能会同时spawn2-3个pm-coder，让它们分别提出实现M02（数据存储）的技术方案（如直接用Node.jsfs模块，或用lowdb这类轻量数据库）。pm-runner收集方案后上报给Orchestrator，由Orchestrator（或用户）做出选择。
   • 步骤2：安装Skills。根据skills-needed.md，确保必要的子Skill（如文件操作、Electron API调用等）已就绪。
   • 步骤3：DAG批次调度。分析dependency-dag.md，发现M01（应用框架）是根节点，无依赖。因此，它首先spawn pm-coder执行任务T001：“搭建Electron基础项目结构”。在给coder的指令中，会明确注入：“UI布局请严格参照prototype/wireframe.html中的设计”。
   • 步骤4：并行与监控。一旦M01完成，M02和M03就可以并行开发。pm-runner会持续监控任务状态和子Agent健康度。如果某个coder卡住或健康度下降，策略引擎会尝试重启任务或更换Agent实例。
   • 步骤5：测试与文档。每个模块开发完成后，pm-runner会调度pm-coder为模块编写单元测试。同时，pm-writer会被调度来编写用户使用文档和API文档。

4.4 第四、五阶段：问题处理与完美收尾

假设在测试M03（编辑器）时发现，实时预览在笔记内容超过1000行时出现明显卡顿。

1. 问题上报：负责测试的pm-coder或监控到性能问题的pm-runner将问题上报给Orchestrator，附上性能日志。
2. 打回决策：Orchestrator分析问题。这属于“实现未达到非功能需求（性能）”，且问题定位在M03模块的实现上。根据“最小必要回退点”规则，它决定打回至P3阶段，但仅针对M03模块的优化任务。它不会回退到P2或P1。
3. 重新调度：Orchestrator更新任务状态，pm-runner重新spawn一个pm-coder（或pm-researcher）来处理“编辑器大数据量性能优化”这个新子任务。优化方案（如虚拟滚动、防抖渲染）被实施并验证。
4. 整合交付：所有模块通过验收后，进入P5。Orchestrator组织pm-coder和pm-writer进行交叉检查，确保模块间接口兼容，最终打包生成可执行文件。同时，生成一份复盘报告，记录“Markdown实时预览在大数据量下需做性能优化”的经验，并沉淀到HEARTBEAT中，供未来项目参考。

5. 常见问题、排查技巧与进阶配置

5.1 部署与使用中的典型问题

问题1：Orchestrator没有正确触发后续阶段。

• 排查：首先检查context_pool目录下对应阶段的产出文件是否完整且格式正确。例如，P1到P2的转换依赖于goal.md和modules.md的存在。使用命令查看文件内容和权限。
• 解决：确保pm-analyst和pm-planner的Skill指令正确写入了这些文件。有时可能是文件路径权限问题，确保WorkBuddy有写入权限。

问题2：pm-runner调度任务时出现循环依赖错误。

• 排查：检查dependency-dag.md文件。使用Mermaid渲染或简单分析，确认图中是否存在环。例如，A依赖B，B又依赖A。
• 解决：这是pm-planner的拆解逻辑问题。需要手动或通过指令让pm-planner重新规划模块。通常的解决方法是引入一个第三方模块或接口来打破循环，或者将两个紧密耦合的模块合并。

问题3：子Agent（如pm-coder）执行任务失败，健康度持续下降。

• 排查：查看该任务对应的progress/TXXX.md文件，里面通常有执行日志和错误信息。同时，检查skills-needed.md中要求的子Skill是否已正确安装并授权。
• 解决：根据错误信息修复。如果是网络问题或API限额，等待后重试。如果是Skill缺失，安装对应Skill。pm-runner的策略引擎应能根据失败类型（瞬时错误、配置错误、逻辑错误）决定重试、上报还是更换Agent。

问题4：原型（P2）被确认后，开发出的功能与原型感觉不一致。

• 排查：对比prototype/中的交互说明与progress/中相关开发任务的描述。检查pm-runner在spawn coder时，是否在指令中明确注入了原型对齐要求。
• 解决：强化pm-designer的原型输出规范，要求其不仅提供视觉，还要在component-tree.md中详细描述组件的状态和行为。同时，优化pm-runner的指令模板，确保原型约束被清晰传递。

5.2 性能优化与扩展建议

1. Harness调优：根据项目类型调整Harness参数。对于探索性项目，可以将pm-analyst和pm-planner的mode设为creative，max_turns调高，允许更多发散。对于严谨的工程项目，则设为strict。
2. 上下文池优化：对于大型项目，上下文文件可能变得很大。可以考虑为pm-coder等子Agent配置只加载其所需模块的上下文片段，而不是整个文件，以节省Token消耗并提升推理速度。
3. 自定义子Agent：体系是开放的。如果你经常需要开发特定类型的功能（如地图集成、支付接口），可以专门训练或配置一个pm-map-specialist或pm-payment-integrationAgent，并在pm-planner的skills-needed.md和pm-runner的调度配置中注册它。
4. 经验库建设：重视P5的复盘报告。将这些报告结构化后存入一个知识库，并让pm-analyst和pm-planner在启动时能够检索相似历史项目的经验，可以实现“越用越聪明”的集体学习效果。

5.3 安全与合规性实践

在设计和配置Agent的Harness时，务必加入安全约束：

• 文件系统访问：严格限制每个Agent可以访问的目录范围，特别是pm-coder，防止其误操作或恶意代码影响系统。
• 网络访问：对于pm-researcher，可以限制其可访问的域名或要求通过安全的代理服务进行搜索。
• 内容过滤：在最终输出阶段（特别是pm-writer生成用户文档时），可以添加一层内容安全检查，过滤不当信息。
• 权限隔离：充分利用上下文池的读写权限控制，遵循最小权限原则。例如，pm-coder绝不应该有权限修改goal.md。

这套“Harness_Multi-Agent_AI_PM”体系，通过严谨的流程设计、清晰的职责划分和精细化的控制机制，将多智能体协作从一场充满不确定性的“布朗运动”，变成了一条可控、可预测、可复现的“工业化流水线”。它需要一定的学习和配置成本，但一旦跑通，对于标准化程度较高的产品功能开发，其效率提升和质量保障是单点AI工具无法比拟的。