{ "metadata": { "id": "ch30", "title": "第30章：多Agent协作项目管理系统", "volume": "vol8", "volume_title": "实战案例集", "word_count": 2412, "difficulty": "advanced", "prerequisites": [ "ch08", "ch32" ], "key_concepts": [ "需求分析与功能规划", "业务背景", "功能清单", "非功能需求", "架构设计", "项目结构", "核心类设计", "核心代码实现", "配置与基础设施", "数据模型", "Agent 消息总线", "Agent 基类", "项目经理 Agent", "开发执行 Agent", "测试验证 Agent" ], "learning_objectives": [], "estimated_tokens": 1447, "source_file": "vol8/ch30_多Agent协作项目管理系统.md" }, "overview": "", "sections": [ { "id": "30.1", "title": "30.1 需求分析与功能规划", "level": 2, "content": "", "subsections": [ { "id": "30.1.1", "title": "30.1.1 业务背景", "content": "软件开发项目管理面临持续挑战：\n\n1. **沟通成本高**：需求变更在产品、开发、测试之间反复传递，信息损耗严重\n2. **进度不透明**：项目实际进展和计划偏差大，风险发现滞后\n3. **资源分配不均**：开发任务集中在少数人身上，其他成员闲置\n4. **质量与速度的矛盾**：赶进度时测试被压缩，上线后 Bug 堆积\n\n我们需要构建一个 AI 驱动的项目管理系统，用多个 Agent 分别承担项目管理中的不同角色：\n\n- **项目经理 Agent**：自动拆解需求、分配任务、监控进度、识别风险\n- **开发执行 Agent**：生成技术方案、编写代码框架、Code Review\n- **测试验证 Agent**：生成测试用例、执行自动化测试、回归分析\n- **多 Agent 协作**：Agent 之间通过消息总线协调，模拟真实团队协作" }, { "id": "30.1.2", "title": "30.1.2 功能清单", "content": "" }, { "id": "30.1.3", "title": "30.1.3 非功能需求", "content": "| 维度 | 指标 |\n|------|------|\n| 任务拆解准确率 | > 85%（粒度合理、无遗漏） |\n| 进度预测准确率 | > 75%（7天内） |\n| 协作消息延迟 | < 500ms |\n| 并发项目支持 | 50 个 |\n| Agent 响应时间 | P95 < 10 秒 |\n\n---" } ] }, { "id": "30.2", "title": "30.2 架构设计", "level": 2, "content": "", "subsections": [ { "id": "30.2.1", "title": "30.2.1 项目结构", "content": "" }, { "id": "30.2.2", "title": "30.2.2 核心类设计", "content": "系统采用**事件驱动的多 Agent 协作**架构：\n\n- **MessageBus**：Agent 之间的消息总线，负责消息路由、优先级排序和冲突检测\n- **PMAgent**（项目经理）：需求拆解、任务分配、进度监控、风险预警\n- **DevAgent**（开发）：接收任务、生成技术方案、输出代码、提交Review\n- **QAAgent**（测试）：生成用例、执行测试、Bug 分析、回归验证\n- **BaseAgent**：所有 Agent 的基类，提供消息收发、状态管理和生命周期管理\n\n**设计决策**：Agent 之间不直接调用，而是通过 MessageBus 异步通信。这保证了松耦合和可扩展性——新增一个设计 Agent 或运维 Agent 只需注册到消息总线即可。\n\n---" } ] }, { "id": "30.3", "title": "30.3 核心代码实现", "level": 2, "content": "", "subsections": [ { "id": "30.3.1", "title": "30.3.1 配置与基础设施", "content": "" }, { "id": "30.3.2", "title": "30.3.2 数据模型", "content": "" }, { "id": "30.3.3", "title": "30.3.3 Agent 消息总线", "content": "" }, { "id": "30.3.4", "title": "30.3.4 Agent 基类", "content": "" }, { "id": "30.3.5", "title": "30.3.5 项目经理 Agent", "content": "" }, { "id": "30.3.6", "title": "30.3.6 开发执行 Agent", "content": "" }, { "id": "30.3.7", "title": "30.3.7 测试验证 Agent", "content": "" }, { "id": "30.3.8", "title": "30.3.8 风险分析服务", "content": "" }, { "id": "30.3.9", "title": "30.3.9 FastAPI 入口", "content": "---" } ] }, { "id": "30.4", "title": "30.4 完整工作流演示", "level": 2, "content": "---", "subsections": [] }, { "id": "30.5", "title": "30.5 测试", "level": 2, "content": "---", "subsections": [] }, { "id": "30.6", "title": "30.6 部署", "level": 2, "content": "---", "subsections": [] }, { "id": "30.7", "title": "30.7 经验总结", "level": 2, "content": "", "subsections": [ { "id": "30.7.1", "title": "30.7.1 踩坑记录", "content": "**坑1：Agent 消息风暴**\n\n早期 Agent 之间的消息没有优先级和限流机制，一个任务完成会触发 PM→Dev→QA 的级联消息，高并发下消息量爆炸。解决方案是引入**消息优先级**和**去重机制**：相同的进度更新消息在 5 秒内只发送一次，RISK_ALERT 消息优先处理。\n\n**坑2：任务依赖的死锁**\n\n任务 A 依赖 B，B 依赖 C，C 又依赖 A——虽然实际项目中很少出现，但 PM Agent 在规划时可能无意中创建循环依赖。我们增加了**依赖图拓扑排序验证**，规划完成后检查是否有环，如有则自动打断最长边。\n\n**坑3：Agent 角色边界模糊**\n\n\"这个 Bug 应该 Dev 修还是 QA 标记？\"——角色职责不清导致消息来回传递。解决方案是在**每个 Agent 的 Prompt 中明确职责边界**，并在 MessageBus 中增加**消息类型权限控制**：QA Agent 只能发送 TEST_RESULT，不能发送 TASK_ASSIGNED。\n\n**坑4：进度预测的准确率**\n\n单纯基于已完成任务数/总任务数来预测进度，忽略了任务的权重差异。一个 2 小时的任务和一个 40 小时的任务权重相同。我们改用**加权进度**：进度 = Σ(已完成任务工时) / Σ(总预估工时) × 100%。" }, { "id": "30.7.2", "title": "30.7.2 性能优化经验", "content": "1. **消息异步化**：Agent 消息全部异步处理，避免阻塞主线程\n2. **状态缓存**：项目状态分析结果缓存 5 分钟，高频查询不重复计算\n3. **任务批处理**：Dev Agent 可以批量执行多个简单任务\n4. **LLM 调用合并**：将多个小任务的分析请求合并为一次 LLM 调用" }, { "id": "30.7.3", "title": "30.7.3 关键设计模式总结", "content": "| 模式 | 应用场景 | 效果 |\n|------|---------|------|\n| 事件驱动架构 | Agent 间通信 | 松耦合，可扩展 |\n| 消息总线 | 协作协调 | 消除 Agent 直接依赖 |\n| 加权进度 | 进度预测 | 准确率从 60% 提升到 80% |\n| 双引擎分析 | 风险检测 | 规则引擎实时 + LLM 深度分析 |" }, { "id": "30.7.4", "title": "30.7.4 未来演进方向", "content": "1. **自然语言交互**：用自然语言下达项目指令（\"帮我规划一个电商项目\"）\n2. **历史经验学习**：从历史项目中学习任务拆解模式和工时估算\n3. **甘特图可视化**：自动生成甘特图和关键路径分析\n4. **跨项目资源调度**：多个项目之间的资源动态调配\n\n---\n\n**本章小结**：多 Agent 协作项目管理系统是 Agent 技术在企业管理领域的深度应用。核心在于**事件驱动的松耦合架构**（MessageBus）和**角色明确的分工协作**（PM/Dev/QA）。通过将项目管理中的重复性工作（需求拆解、进度跟踪、风险分析）交给 AI Agent，项目经理可以从事务性工作中解放出来，专注于更高价值的决策和沟通。系统展示了多个 Agent 如何通过消息机制高效协作，完成单个 Agent 无法完成的复杂任务。" } ] } ], "code_blocks": [ { "id": "code-1", "language": "text", "description": "- 多 Agent 协作：Agent 之间通过消息总线协调，模拟真实团队协作", "code": "┌──────────────────────────────────────────────────────────┐\n│ 多Agent协作项目管理系统架构 │\n├──────────────────────────────────────────────────────────┤\n│ ┌─────────────┐ ┌─────────────┐ ┌──────────────┐ │\n│ │ 项目经理Agent│ │ 开发执行Agent│ │ 测试验证Agent│ │\n│ │ • 需求拆解 │ │ • 技术方案 │ │ • 用例生成 │ │\n│ │ • 任务分配 │ │ • 代码生成 │ │ • 自动化测试 │ │\n│ │ • 进度跟踪 │ │ • Code Review│ │ • Bug分析 │ │\n│ │ • 风险预警 │ │ • 文档编写 │ │ • 回归分析 │ │\n│ └─────────────┘ └─────────────┘ └──────────────┘ │\n│ ┌─────────────────────────────────────────────────┐ │\n│ │ Agent 消息总线 │ │\n│ │ • 任务调度 • 状态同步 • 冲突解决 • 进度汇报 │ │\n│ └─────────────────────────────────────────────────┘ │\n│ ┌─────────────────────────────────────────────────┐ │\n│ │ 项目数据层 │ │\n│ │ • 任务管理 • 知识库 • 度量指标 • 里程碑 │ │\n│ └─────────────────────────────────────────────────┘ │\n└──────────────────────────────────────────────────────────┘", "section_ref": "30.1.2", "runnable": false, "dependencies": [] }, { "id": "code-2", "language": "text", "description": "", "code": "agent-project-mgmt/\n├── app/\n│ ├── main.py # FastAPI 入口\n│ ├── config.py # 配置管理\n│ ├── models/ # 数据模型\n│ │ ├── project.py # 项目模型\n│ │ ├── task.py # 任务模型\n│ │ └── message.py # Agent 消息模型\n│ ├── agents/ # Agent 核心\n│ │ ├── base_agent.py # Agent 基类\n│ │ ├── pm_agent.py # 项目经理 Agent\n│ │ ├── dev_agent.py # 开发执行 Agent\n│ │ ├── qa_agent.py # 测试验证 Agent\n│ │ └── message_bus.py # Agent 消息总线\n│ ├── services/\n│ │ ├── task_service.py # 任务管理服务\n│ │ ├── risk_analyzer.py # 风险分析\n│ │ └── report_generator.py # 报告生成\n│ └── utils/\n│ └── llm_client.py # LLM 客户端\n├── tests/\n└── requirements.txt", "section_ref": "30.2.1", "runnable": false, "dependencies": [] }, { "id": "code-3", "language": "python", "description": "", "code": "# app/config.py\n\"\"\"项目管理系统配置\"\"\"\n\nfrom pydantic_settings import BaseSettings\nfrom enum import Enum\n\n\nclass TaskStatus(str, Enum):\n BACKLOG = \"backlog\"\n TODO = \"todo\"\n IN_PROGRESS = \"in_progress\"\n IN_REVIEW = \"in_review\"\n TESTING = \"testing\"\n DONE = \"done\"\n BLOCKED = \"blocked\"\n\n\nclass TaskPriority(str, Enum):\n CRITICAL = \"critical\"\n HIGH = \"high\"\n MEDIUM = \"medium\"\n LOW = \"low\"\n\n\nclass AgentRole(str, Enum):\n PM = \"pm\" # 项目经理\n DEV = \"dev\" # 开发\n QA = \"qa\" # 测试\n DESIGN = \"design\" # 设计\n\n\nclass MessagePriority(str, Enum):\n URGENT = \"urgent\"\n HIGH = \"high\"\n NORMAL = \"normal\"\n LOW = \"low\"\n\n\nclass Settings(BaseSettings):\n APP_NAME: str = \"多Agent协作项目管理系统\"\n APP_VERSION: str = \"1.0.0\"\n DEBUG: bool = False\n\n LLM_API_KEY: str = \"\"\n LLM_BASE_URL: str = \"https://api.openai.com/v1\"\n LLM_MODEL: str = \"gpt-4o\"\n LLM_MAX_TOKENS: int = 4096\n\n # 项目管理参数\n MAX_TASK_DEPTH: int = 3 # 任务拆解最大深度\n DEFAULT_SPRINT_DURATION: int = 14 # 默认迭代周期（天）\n RISK_CHECK_INTERVAL: int = 3600 # 风险检查间隔（秒）\n AGENT_RESPONSE_TIMEOUT: int = 30 # Agent 响应超时（秒）\n\n class Config:\n env_file = \".env\"\n env_prefix = \"PM_\"\n\n\nsettings = Settings()", "section_ref": "30.3.1", "runnable": true, "dependencies": [ "pydantic_settings" ] }, { "id": "code-4", "language": "python", "description": "settings = Settings()", "code": "# app/utils/llm_client.py\n\"\"\"LLM 客户端（简化版）\"\"\"\n\nimport json\nfrom typing import Optional, List, Dict\nfrom openai import OpenAI\nfrom app.config import settings\n\n\nclass LLMClient:\n _instance: Optional['LLMClient'] = None\n\n def __new__(cls):\n if cls._instance is None:\n cls._instance = super().__new__(cls)\n cls._instance._client = OpenAI(\n api_key=settings.LLM_API_KEY,\n base_url=settings.LLM_BASE_URL)\n return cls._instance\n\n async def chat(self, messages, system_prompt=None,\n temperature=0.7, max_tokens=None) -> str:\n full = []\n if system_prompt:\n full.append({\"role\": \"system\", \"content\": system_prompt})\n full.extend(messages)\n resp = self._client.chat.completions.create(\n model=settings.LLM_MODEL, messages=full,\n temperature=temperature,\n max_tokens=max_tokens or settings.LLM_MAX_TOKENS)\n return resp.choices[0].message.content\n\n async def chat_json(self, messages, system_prompt=None) -> dict:\n content = await self.chat(messages, system_prompt,\n temperature=0.1,\n response_format={\"type\": \"json_object\"})\n return json.loads(content)\n\n\nllm_client = LLMClient()", "section_ref": "30.3.1", "runnable": true, "dependencies": [ "openai", "app" ] }, { "id": "code-5", "language": "python", "description": "", "code": "# app/models/task.py\n\"\"\"任务数据模型\"\"\"\n\nfrom dataclasses import dataclass, field\nfrom datetime import datetime\nfrom typing import List, Optional, Dict, Any\nfrom app.config import TaskStatus, TaskPriority, AgentRole\nimport uuid\n\n\n@dataclass\nclass Task:\n id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])\n project_id: str = \"\"\n parent_id: Optional[str] = None\n title: str = \"\"\n description: str = \"\"\n status: TaskStatus = TaskStatus.BACKLOG\n priority: TaskPriority = TaskPriority.MEDIUM\n assignee: AgentRole = AgentRole.DEV\n reviewer: Optional[AgentRole] = None\n estimated_hours: float = 0.0\n actual_hours: float = 0.0\n tags: List[str] = field(default_factory=list)\n dependencies: List[str] = field(default_factory=list)\n acceptance_criteria: List[str] = field(default_factory=list)\n subtasks: List['Task'] = field(default_factory=list)\n tech_notes: str = \"\"\n test_cases: List[str] = field(default_factory=list)\n created_at: datetime = field(default_factory=datetime.now)\n updated_at: datetime = field(default_factory=datetime.now)\n started_at: Optional[datetime] = None\n completed_at: Optional[datetime] = None\n metadata: Dict[str, Any] = field(default_factory=dict)\n\n def to_dict(self) -> dict:\n return {\n \"id\": self.id, \"title\": self.title,\n \"status\": self.status.value,\n \"priority\": self.priority.value,\n \"assignee\": self.assignee.value,\n \"estimated_hours\": self.estimated_hours,\n \"actual_hours\": self.actual_hours,\n \"subtasks_count\": len(self.subtasks),\n }\n\n\n@dataclass\nclass Project:\n id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])\n name: str = \"\"\n description: str = \"\"\n status: str = \"planning\"\n tasks: List[Task] = field(default_factory=list)\n milestones: List[Dict] = field(default_factory=list)\n team_members: List[Dict] = field(default_factory=list)\n created_at: datetime = field(default_factory=datetime.now)\n metadata: Dict[str, Any] = field(default_factory=dict)\n\n @property\n def total_tasks(self) -> int:\n return self._count_tasks(self.tasks)\n\n @property\n def completed_tasks(self) -> int:\n return self._count_by_status(self.tasks, TaskStatus.DONE)\n\n @property\n def progress(self) -> float:\n total = self.total_tasks\n if total == 0:\n return 0.0\n return self.completed_tasks / total * 100\n\n def _count_tasks(self, tasks: List[Task]) -> int:\n count = len(tasks)\n for t in tasks:\n count += self._count_tasks(t.subtasks)\n return count\n\n def _count_by_status(self, tasks: List[Task], status: TaskStatus) -> int:\n count = sum(1 for t in tasks if t.status == status)\n for t in tasks:\n count += self._count_by_status(t.subtasks, status)\n return count", "section_ref": "30.3.2", "runnable": true, "dependencies": [ "app" ] }, { "id": "code-6", "language": "python", "description": "", "code": "# app/agents/message_bus.py\n\"\"\"Agent 消息总线\"\"\"\n\nimport asyncio\nfrom dataclasses import dataclass, field\nfrom typing import List, Dict, Callable, Optional, Any\nfrom datetime import datetime\nfrom enum import Enum\nimport uuid\n\n\nclass MessageType(str, Enum):\n TASK_ASSIGNED = \"task_assigned\"\n TASK_STARTED = \"task_started\"\n TASK_COMPLETED = \"task_completed\"\n TASK_REVIEW_REQUEST = \"task_review_request\"\n TASK_REVIEW_RESULT = \"task_review_result\"\n TASK_TEST_REQUEST = \"task_test_request\"\n TASK_TEST_RESULT = \"task_test_result\"\n RISK_ALERT = \"risk_alert\"\n PROGRESS_UPDATE = \"progress_update\"\n SPRINT_REPORT = \"sprint_report\"\n STATUS_QUERY = \"status_query\"\n\n\n@dataclass\nclass AgentMessage:\n id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])\n type: MessageType = MessageType.STATUS_QUERY\n sender: str = \"\"\n recipient: str = \"\" # \"\" 表示广播\n payload: Dict[str, Any] = field(default_factory=dict)\n priority: str = \"normal\"\n timestamp: datetime = field(default_factory=datetime.now)\n reply_to: Optional[str] = None\n project_id: str = \"\"\n\n\nclass MessageBus:\n \"\"\"Agent 之间的异步消息总线\"\"\"\n\n def __init__(self):\n self._handlers: Dict[str, List[Callable]] = {}\n self._history: List[AgentMessage] = []\n self._pending: Dict[str, asyncio.Future] = {}\n\n def register(self, agent_name: str, handler: Callable):\n \"\"\"注册 Agent 消息处理器\"\"\"\n if agent_name not in self._handlers:\n self._handlers[agent_name] = []\n self._handlers[agent_name].append(handler)\n\n async def send(self, message: AgentMessage) -> Optional[AgentMessage]:\n \"\"\"发送消息并等待回复\"\"\"\n self._history.append(message)\n\n if message.recipient and message.recipient in self._handlers:\n # 点对点消息\n for handler in self._handlers[message.recipient]:\n response = await handler(message)\n if response:\n self._history.append(response)\n return response\n else:\n # 广播消息\n responses = []\n for name, handlers in self._handlers.items():\n if name != message.sender:\n for handler in handlers:\n response = await handler(message)\n if response:\n self._history.append(response)\n responses.append(response)\n return responses[0] if responses else None\n\n return None\n\n async def broadcast(self, message: AgentMessage):\n \"\"\"广播消息（不等待回复）\"\"\"\n message.recipient = \"\"\n for name, handlers in self._handlers.items():\n if name != message.sender:\n for handler in handlers:\n asyncio.create_task(handler(message))\n\n def get_history(\n self, project_id: str = \"\", limit: int = 50,\n ) -> List[AgentMessage]:\n \"\"\"获取消息历史\"\"\"\n msgs = self._history\n if project_id:\n msgs = [m for m in msgs if m.project_id == project_id]\n return msgs[-limit:]\n\n def get_pending_count(self, agent_name: str) -> int:\n \"\"\"获取待处理消息数\"\"\"\n return sum(\n 1 for m in self._history\n if m.recipient == agent_name\n and m.type not in {\n MessageType.TASK_COMPLETED,\n MessageType.TASK_REVIEW_RESULT,\n MessageType.TASK_TEST_RESULT,\n }\n )", "section_ref": "30.3.3", "runnable": true, "dependencies": [] }, { "id": "code-7", "language": "python", "description": "", "code": "# app/agents/base_agent.py\n\"\"\"Agent 基类\"\"\"\n\nfrom abc import ABC, abstractmethod\nfrom typing import Optional, List, Dict\nfrom app.agents.message_bus import MessageBus, AgentMessage, MessageType\nfrom app.utils.llm_client import llm_client\n\n\nclass BaseAgent(ABC):\n \"\"\"所有 Agent 的基类\"\"\"\n\n def __init__(self, name: str, role: str, bus: MessageBus):\n self.name = name\n self.role = role\n self.bus = bus\n self._state: Dict = {\"busy\": False, \"current_task\": None}\n bus.register(name, self.handle_message)\n\n @abstractmethod\n async def handle_message(self, message: AgentMessage) -> Optional[AgentMessage]:\n \"\"\"处理收到的消息\"\"\"\n pass\n\n async def send_message(\n self,\n msg_type: MessageType,\n recipient: str = \"\",\n payload: Optional[Dict] = None,\n project_id: str = \"\",\n reply_to: Optional[str] = None,\n ) -> Optional[AgentMessage]:\n \"\"\"发送消息\"\"\"\n msg = AgentMessage(\n type=msg_type, sender=self.name,\n recipient=recipient,\n payload=payload or {},\n project_id=project_id,\n reply_to=reply_to,\n )\n return await self.bus.send(msg)\n\n @property\n def is_busy(self) -> bool:\n return self._state.get(\"busy\", False)\n\n def update_state(self, **kwargs):\n self._state.update(kwargs)\n\n async def llm_chat(self, messages, system_prompt=None,\n temperature=0.7) -> str:\n return await llm_client.chat(\n messages=messages, system_prompt=system_prompt,\n temperature=temperature)\n\n async def llm_json(self, messages, system_prompt=None) -> dict:\n return await llm_client.chat_json(\n messages=messages, system_prompt=system_prompt)", "section_ref": "30.3.4", "runnable": true, "dependencies": [ "app" ] }, { "id": "code-8", "language": "python", "description": "", "code": "# app/agents/pm_agent.py\n\"\"\"项目经理 Agent\"\"\"\n\nfrom typing import Optional, List, Dict\nfrom app.agents.base_agent import BaseAgent\nfrom app.agents.message_bus import (\n MessageBus, AgentMessage, MessageType)\nfrom app.models.task import Task, Project\nfrom app.config import TaskStatus, TaskPriority, AgentRole\n\n\nclass PMAgent(BaseAgent):\n \"\"\"项目经理 Agent：需求拆解、任务分配、进度跟踪、风险预警\"\"\"\n\n PLAN_PROMPT = \"\"\"你是一个经验丰富的项目经理。你的任务是：\n1. 将高层需求拆解为可执行的开发任务\n2. 评估每个任务的工作量和优先级\n3. 确定任务之间的依赖关系\n4. 分配最合适的执行者\n\n返回 JSON：\n{{\n \"tasks\": [\n {{\n \"title\": \"任务标题\",\n \"description\": \"任务描述\",\n \"priority\": \"critical|high|medium|low\",\n \"estimated_hours\": 8,\n \"assignee\": \"dev|qa|design\",\n \"dependencies\": [\"依赖的任务ID\"],\n \"acceptance_criteria\": [\"验收标准1\", \"验收标准2\"],\n \"tags\": [\"标签\"]\n }}\n ],\n \"milestones\": [\n {{\"name\": \"里程碑名称\", \"deadline\": \"日期\", \"tasks\": [\"关联任务ID\"]}}\n ],\n \"risks\": [\"识别到的风险\"],\n \"notes\": \"项目规划说明\"\n}}\"\"\"\n\n STATUS_PROMPT = \"\"\"你是一个项目状态分析师。\n基于任务列表和当前进度，分析项目健康状况。\n\n返回 JSON：\n{{\n \"overall_status\": \"on_track|at_risk|behind\",\n \"progress_percent\": 0-100,\n \"blocked_tasks\": [\"被阻塞的任务\"],\n \"upcoming_deadlines\": [\"即将到期的里程碑\"],\n \"risks\": [\n {{\"description\": \"风险描述\", \"severity\": \"high|medium|low\",\n \"mitigation\": \"缓解措施\"}}\n ],\n \"recommendations\": [\"行动建议\"],\n \"team_workload\": {{\n \"dev\": {{\"assigned\": 10, \"completed\": 5, \"hours\": 40}},\n \"qa\": {{\"assigned\": 8, \"completed\": 3, \"hours\": 30}}\n }},\n \"summary\": \"项目状态总结（一段话）\"\n}}\"\"\"\n\n def __init__(self, bus: MessageBus):\n super().__init__(\"pm_agent\", \"项目经理\", bus)\n\n async def handle_message(\n self, message: AgentMessage,\n ) -> Optional[AgentMessage]:\n handlers = {\n MessageType.STATUS_QUERY: self._handle_status_query,\n MessageType.TASK_COMPLETED: self._handle_task_completed,\n MessageType.TASK_REVIEW_RESULT: self._handle_review_result,\n MessageType.RISK_ALERT: self._handle_risk_alert,\n MessageType.PROGRESS_UPDATE: self._handle_progress_update,\n }\n handler = handlers.get(message.type)\n if handler:\n return await handler(message)\n return None\n\n async def plan_project(\n self, project: Project, requirement: str,\n ) -> Dict:\n \"\"\"将需求拆解为任务计划\"\"\"\n messages = [{\n \"role\": \"user\",\n \"content\": (f\"项目名称: {project.name}\\n\"\n f\"项目描述: {project.description}\\n\\n\"\n f\"需求描述:\\n{requirement}\\n\\n\"\n f\"团队成员: \"\n + \", \".join(\n m[\"name\"] + \"(\" + m[\"role\"] + \")\"\n for m in project.team_members))\n }]\n\n try:\n result = await self.llm_json(\n messages=messages, system_prompt=self.PLAN_PROMPT)\n return result\n except Exception as e:\n return {\"tasks\": [], \"milestones\": [], \"risks\": [str(e)],\n \"notes\": \"规划失败\"}\n\n def parse_tasks(\n self, plan: Dict, project_id: str = \"\",\n ) -> List[Task]:\n \"\"\"解析规划结果为 Task 对象\"\"\"\n tasks = []\n for i, t in enumerate(plan.get(\"tasks\", [])):\n assignee_map = {\n \"dev\": AgentRole.DEV,\n \"qa\": AgentRole.QA,\n \"design\": AgentRole.DESIGN,\n \"pm\": AgentRole.PM,\n }\n priority_map = {\n \"critical\": TaskPriority.CRITICAL,\n \"high\": TaskPriority.HIGH,\n \"medium\": TaskPriority.MEDIUM,\n \"low\": TaskPriority.LOW,\n }\n task = Task(\n project_id=project_id,\n title=t.get(\"title\", f\"Task-{i+1}\"),\n description=t.get(\"description\", \"\"),\n priority=priority_map.get(\n t.get(\"priority\", \"medium\"), TaskPriority.MEDIUM),\n assignee=assignee_map.get(\n t.get(\"assignee\", \"dev\"), AgentRole.DEV),\n estimated_hours=float(t.get(\"estimated_hours\", 4)),\n dependencies=t.get(\"dependencies\", []),\n acceptance_criteria=t.get(\"acceptance_criteria\", []),\n tags=t.get(\"tags\", []),\n )\n tasks.append(task)\n return tasks\n\n async def analyze_status(\n self, project: Project,\n ) -> Dict:\n \"\"\"分析项目当前状态\"\"\"\n task_list = []\n self._flatten_tasks(project.tasks, task_list)\n\n task_summary = \"\\n\".join(\n f\"- [{t.status.value}] {t.title} \"\n f\"(优先级:{t.priority.value}, \"\n f\"预估:{t.estimated_hours}h, \"\n f\"实际:{t.actual_hours}h, \"\n f\"负责人:{t.assignee.value})\"\n for t in task_list\n )\n\n messages = [{\n \"role\": \"user\",\n \"content\": (f\"项目: {project.name}\\n\"\n f\"整体进度: {project.progress:.1f}%\\n\"\n f\"任务列表:\\n{task_summary}\")\n }]\n\n try:\n return await self.llm_json(\n messages=messages, system_prompt=self.STATUS_PROMPT)\n except Exception as e:\n return {\"overall_status\": \"unknown\", \"summary\": str(e)}\n\n def _flatten_tasks(\n self, tasks: List[Task], result: List[Task],\n ):\n for t in tasks:\n result.append(t)\n self._flatten_tasks(t.subtasks, result)\n\n async def _handle_status_query(self, msg: AgentMessage):\n return AgentMessage(\n type=MessageType.PROGRESS_UPDATE,\n sender=self.name,\n recipient=msg.sender,\n payload={\"status\": \"running\", \"message\": \"PM在线\"},\n )\n\n async def _handle_task_completed(self, msg: AgentMessage):\n task_id = msg.payload.get(\"task_id\", \"\")\n # 任务完成后，自动分配下一个待办任务\n return await self.send_message(\n MessageType.TASK_ASSIGNED,\n recipient=\"dev_agent\",\n payload={\"action\": \"check_next_task\", \"completed\": task_id},\n project_id=msg.project_id,\n )\n\n async def _handle_review_result(self, msg: AgentMessage):\n passed = msg.payload.get(\"passed\", False)\n if not passed:\n # Review 未通过，通知开发修改\n return await self.send_message(\n MessageType.TASK_REVIEW_RESULT,\n recipient=\"dev_agent\",\n payload=msg.payload,\n project_id=msg.project_id,\n )\n return None\n\n async def _handle_risk_alert(self, msg: AgentMessage):\n # 收到风险告警，记录并通知\n return None\n\n async def _handle_progress_update(self, msg: AgentMessage):\n return None", "section_ref": "30.3.5", "runnable": true, "dependencies": [ "app" ] }, { "id": "code-9", "language": "python", "description": "", "code": "# app/agents/dev_agent.py\n\"\"\"开发执行 Agent\"\"\"\n\nfrom typing import Optional, List, Dict\nfrom app.agents.base_agent import BaseAgent\nfrom app.agents.message_bus import (\n MessageBus, AgentMessage, MessageType)\nfrom app.models.task import Task\nfrom app.config import TaskStatus\n\n\nclass DevAgent(BaseAgent):\n \"\"\"开发执行 Agent：接收任务、技术方案、代码输出、提交Review\"\"\"\n\n TECH_DESIGN_PROMPT = \"\"\"你是一个资深开发工程师。基于任务描述生成技术方案。\n\n返回 JSON：\n{{\n \"approach\": \"技术方案概述\",\n \"architecture\": \"架构设计说明\",\n \"files_to_create\": [\"需要创建的文件列表\"],\n \"files_to_modify\": [\"需要修改的文件列表\"],\n \"key_algorithms\": [\"关键算法/逻辑说明\"],\n \"dependencies\": [\"需要的第三方库\"],\n \"estimated_complexity\": \"low|medium|high\",\n \"risks\": [\"技术风险\"],\n \"implementation_steps\": [\n \"步骤1: ...\", \"步骤2: ...\", ...\n ]\n}}\"\"\"\n\n CODE_GEN_PROMPT = \"\"\"你是一个代码生成专家。根据任务和技术方案生成代码。\n\n规则：\n1. 代码必须可运行，包含完整的 import\n2. 使用类型注解\n3. 添加关键注释\n4. 遵循项目代码规范\n\n返回 JSON：\n{{\n \"files\": [\n {{\"path\": \"文件路径\", \"content\": \"文件内容\", \"description\": \"说明\"}}\n ],\n \"notes\": \"实现说明\"\n}}\"\"\"\n\n REVIEW_SELF_PROMPT = \"\"\"你正在进行 Code Review（自审）。\n\n检查项：\n1. 代码逻辑正确性\n2. 边界条件处理\n3. 性能问题\n4. 安全隐患\n5. 代码规范\n\n返回 JSON：\n{{\n \"passed\": true/false,\n \"issues\": [\n {{\"severity\": \"error|warning|info\",\n \"file\": \"文件路径\",\n \"line\": 行号,\n \"description\": \"问题描述\",\n \"suggestion\": \"修复建议\"}}\n ],\n \"overall_comment\": \"总体评价\"\n}}\"\"\"\n\n def __init__(self, bus: MessageBus):\n super().__init__(\"dev_agent\", \"开发工程师\", bus)\n\n async def handle_message(\n self, message: AgentMessage,\n ) -> Optional[AgentMessage]:\n handlers = {\n MessageType.TASK_ASSIGNED: self._handle_task_assigned,\n MessageType.TASK_REVIEW_RESULT: self._handle_review_result,\n }\n handler = handlers.get(message.type)\n if handler:\n return await handler(message)\n return None\n\n async def generate_tech_design(self, task: Task) -> Dict:\n \"\"\"生成技术方案\"\"\"\n messages = [{\n \"role\": \"user\",\n \"content\": (f\"任务: {task.title}\\n\"\n f\"描述: {task.description}\\n\"\n f\"验收标准: {task.acceptance_criteria}\\n\"\n f\"预估工时: {task.estimated_hours}小时\\n\"\n f\"标签: {', '.join(task.tags)}\")\n }]\n try:\n return await self.llm_json(\n messages=messages,\n system_prompt=self.TECH_DESIGN_PROMPT)\n except Exception as e:\n return {\"approach\": f\"技术方案生成失败: {str(e)}\"}\n\n async def generate_code(\n self, task: Task, tech_design: Dict,\n ) -> Dict:\n \"\"\"生成代码\"\"\"\n messages = [\n {\"role\": \"user\", \"content\": f\"任务: {task.title}\\n\"\n f\"描述: {task.description}\"},\n {\"role\": \"assistant\", \"content\": f\"技术方案:\\n{tech_design['approach']}\\n\"\n f\"实现步骤:\\n\"\n + \"\\n\".join(f\" {s}\" for s in\n tech_design.get(\"implementation_steps\", []))},\n {\"role\": \"user\", \"content\": \"请生成代码。\"},\n ]\n try:\n return await self.llm_json(\n messages=messages,\n system_prompt=self.CODE_GEN_PROMPT,\n temperature=0.3)\n except Exception as e:\n return {\"files\": [], \"notes\": f\"代码生成失败: {str(e)}\"}\n\n async def self_review(self, task: Task, code: Dict) -> Dict:\n \"\"\"自审代码\"\"\"\n code_summary = \"\\n\".join(\n f\"文件: {f['path']}\\n```{f['content'][:500]}```\"\n for f in code.get(\"files\", [])[:3]\n )\n messages = [{\n \"role\": \"user\",\n \"content\": (f\"任务: {task.title}\\n\"\n f\"代码:\\n{code_summary}\")\n }]\n try:\n return await self.llm_json(\n messages=messages,\n system_prompt=self.REVIEW_SELF_PROMPT)\n except Exception:\n return {\"passed\": True, \"issues\": [], \"overall_comment\": \"自审通过\"}\n\n async def execute_task(\n self, task: Task, project_id: str = \"\",\n ) -> Dict:\n \"\"\"执行完整开发流程：技术方案 → 代码生成 → 自审\"\"\"\n self.update_state(busy=True, current_task=task.id)\n\n # 1. 技术方案\n tech_design = await self.generate_tech_design(task)\n\n # 2. 代码生成\n code = await self.generate_code(task, tech_design)\n\n # 3. 自审\n review = await self.self_review(task, code)\n\n self.update_state(busy=False, current_task=None)\n\n # 4. 通知 PM 任务完成，请求 QA 测试\n if review.get(\"passed\", True):\n await self.send_message(\n MessageType.TASK_COMPLETED,\n recipient=\"pm_agent\",\n payload={\n \"task_id\": task.id,\n \"title\": task.title,\n \"files_created\": [\n f[\"path\"] for f in code.get(\"files\", [])],\n \"tech_notes\": tech_design.get(\"approach\", \"\"),\n },\n project_id=project_id,\n )\n\n # 请求 QA 测试\n await self.send_message(\n MessageType.TASK_TEST_REQUEST,\n recipient=\"qa_agent\",\n payload={\n \"task_id\": task.id,\n \"title\": task.title,\n \"description\": task.description,\n \"acceptance_criteria\": task.acceptance_criteria,\n \"files\": code.get(\"files\", []),\n },\n project_id=project_id,\n )\n\n return {\n \"task_id\": task.id,\n \"tech_design\": tech_design,\n \"code\": code,\n \"self_review\": review,\n }\n\n async def _handle_task_assigned(self, msg: AgentMessage):\n action = msg.payload.get(\"action\", \"\")\n if action == \"check_next_task\":\n return AgentMessage(\n type=MessageType.PROGRESS_UPDATE,\n sender=self.name, recipient=msg.sender,\n payload={\"message\": \"已收到，等待分配下一个任务\"},\n project_id=msg.project_id,\n )\n return None\n\n async def _handle_review_result(self, msg: AgentMessage):\n passed = msg.payload.get(\"passed\", True)\n if not passed:\n issues = msg.payload.get(\"issues\", [])\n return AgentMessage(\n type=MessageType.PROGRESS_UPDATE,\n sender=self.name, recipient=\"pm_agent\",\n payload={\n \"message\": f\"收到 Review 反馈，\"\n f\"共 {len(issues)} 个问题需要修复\",\n },\n project_id=msg.project_id,\n )\n return None", "section_ref": "30.3.6", "runnable": true, "dependencies": [ "app" ] }, { "id": "code-10", "language": "python", "description": "", "code": "# app/agents/qa_agent.py\n\"\"\"测试验证 Agent\"\"\"\n\nfrom typing import Optional, List, Dict\nfrom app.agents.base_agent import BaseAgent\nfrom app.agents.message_bus import (\n MessageBus, AgentMessage, MessageType)\nfrom app.models.task import Task\nfrom app.config import TaskStatus\n\n\nclass QAAgent(BaseAgent):\n \"\"\"测试验证 Agent：用例生成、测试执行、Bug 分析\"\"\"\n\n TEST_PLAN_PROMPT = \"\"\"你是一个专业测试工程师。基于任务描述生成测试计划。\n\n返回 JSON：\n{{\n \"test_cases\": [\n {{\n \"id\": \"TC-001\",\n \"title\": \"测试用例标题\",\n \"type\": \"unit|integration|e2e\",\n \"priority\": \"high|medium|low\",\n \"preconditions\": [\"前置条件\"],\n \"steps\": [\"步骤1\", \"步骤2\"],\n \"expected_result\": \"预期结果\",\n \"test_data\": \"测试数据说明\"\n }}\n ],\n \"edge_cases\": [\"边界情况列表\"],\n \"test_strategy\": \"测试策略说明\"\n}}\"\"\"\n\n BUG_ANALYSIS_PROMPT = \"\"\"你是一个 Bug 分析专家。分析以下问题。\n\n返回 JSON：\n{{\n \"severity\": \"critical|major|minor|trivial\",\n \"category\": \"logic|ui|performance|security|compatibility\",\n \"root_cause\": \"根因分析\",\n \"reproduction_steps\": [\"复现步骤\"],\n \"fix_suggestion\": \"修复建议\",\n \"affected_files\": [\"受影响的文件\"],\n \"regression_risk\": \"high|medium|low\"\n}}\"\"\"\n\n def __init__(self, bus: MessageBus):\n super().__init__(\"qa_agent\", \"测试工程师\", bus)\n\n async def handle_message(\n self, message: AgentMessage,\n ) -> Optional[AgentMessage]:\n if message.type == MessageType.TASK_TEST_REQUEST:\n return await self._handle_test_request(message)\n return None\n\n async def generate_test_plan(self, task: Task) -> Dict:\n \"\"\"生成测试计划\"\"\"\n messages = [{\n \"role\": \"user\",\n \"content\": (f\"任务: {task.title}\\n\"\n f\"描述: {task.description}\\n\"\n f\"验收标准:\\n\"\n + \"\\n\".join(f\" - {c}\"\n for c in task.acceptance_criteria))\n }]\n try:\n return await self.llm_json(\n messages=messages,\n system_prompt=self.TEST_PLAN_PROMPT)\n except Exception as e:\n return {\"test_cases\": [], \"edge_cases\": [],\n \"test_strategy\": f\"生成失败: {str(e)}\"}\n\n async def run_tests(\n self, task_id: str, test_plan: Dict,\n ) -> Dict:\n \"\"\"模拟执行测试（实际项目接入真实测试框架）\"\"\"\n test_cases = test_plan.get(\"test_cases\", [])\n results = []\n for tc in test_cases:\n # 模拟测试执行（生产环境接入 pytest/unittest）\n passed = True # 模拟结果\n # 可以根据任务复杂度随机模拟失败\n results.append({\n \"id\": tc.get(\"id\", \"\"),\n \"title\": tc.get(\"title\", \"\"),\n \"passed\": passed,\n \"duration_ms\": 150,\n })\n\n passed_count = sum(1 for r in results if r[\"passed\"])\n total = len(results)\n\n return {\n \"task_id\": task_id,\n \"total\": total,\n \"passed\": passed_count,\n \"failed\": total - passed_count,\n \"pass_rate\": passed_count / max(total, 1) * 100,\n \"results\": results,\n }\n\n async def analyze_bug(\n self, task: Task, error_description: str,\n ) -> Dict:\n \"\"\"分析 Bug\"\"\"\n messages = [{\n \"role\": \"user\",\n \"content\": (f\"任务: {task.title}\\n\"\n f\"问题描述: {error_description}\")\n }]\n try:\n return await self.llm_json(\n messages=messages,\n system_prompt=self.BUG_ANALYSIS_PROMPT)\n except Exception:\n return {\"severity\": \"unknown\", \"root_cause\": \"分析失败\"}\n\n async def _handle_test_request(self, msg: AgentMessage) -> AgentMessage:\n \"\"\"处理测试请求\"\"\"\n task = Task(\n id=msg.payload.get(\"task_id\", \"\"),\n title=msg.payload.get(\"title\", \"\"),\n description=msg.payload.get(\"description\", \"\"),\n acceptance_criteria=msg.payload.get(\n \"acceptance_criteria\", []),\n )\n\n # 1. 生成测试计划\n test_plan = await self.generate_test_plan(task)\n\n # 2. 执行测试\n test_result = await self.run_tests(msg.payload.get(\"task_id\", \"\"),\n test_plan)\n\n # 3. 通知 PM 测试结果\n await self.send_message(\n MessageType.TASK_TEST_RESULT,\n recipient=\"pm_agent\",\n payload={\n \"task_id\": msg.payload.get(\"task_id\", \"\"),\n \"title\": task.title,\n \"test_plan\": test_plan,\n \"test_result\": test_result,\n \"passed\": test_result[\"pass_rate\"] >= 80,\n },\n project_id=msg.project_id,\n )\n\n return AgentMessage(\n type=MessageType.TASK_TEST_RESULT,\n sender=self.name,\n recipient=msg.sender,\n payload=test_result,\n project_id=msg.project_id,\n )", "section_ref": "30.3.7", "runnable": true, "dependencies": [ "app" ] }, { "id": "code-11", "language": "python", "description": "", "code": "# app/services/risk_analyzer.py\n\"\"\"项目风险分析\"\"\"\n\nfrom dataclasses import dataclass, field\nfrom typing import List, Dict\nfrom app.models.task import Task, TaskStatus\n\n\n@dataclass\nclass RiskItem:\n description: str\n severity: str # high/medium/low\n probability: float # 0-1\n impact: str\n mitigation: str\n task_ids: List[str] = field(default_factory=list)\n\n\nclass RiskAnalyzer:\n \"\"\"基于规则的项目风险分析\"\"\"\n\n def analyze(self, project) -> List[RiskItem]:\n risks = []\n all_tasks = []\n self._flatten(project.tasks, all_tasks)\n\n # 1. 阻塞任务分析\n blocked = [t for t in all_tasks if t.status == TaskStatus.BLOCKED]\n if blocked:\n risks.append(RiskItem(\n description=f\"有 {len(blocked)} 个任务被阻塞\",\n severity=\"high\", probability=0.8,\n impact=\"阻塞任务可能导致后续任务无法开始\",\n mitigation=\"立即排查阻塞原因，调整任务依赖\",\n task_ids=[t.id for t in blocked],\n ))\n\n # 2. 工时偏差分析\n for t in all_tasks:\n if (t.actual_hours > 0\n and t.estimated_hours > 0\n and t.actual_hours > t.estimated_hours * 1.5):\n risks.append(RiskItem(\n description=f\"任务「{t.title}」工时超出预算 \"\n f\"{(t.actual_hours/t.estimated_hours - 1)*100:.0f}%\",\n severity=\"medium\", probability=0.7,\n impact=\"可能影响项目整体交付时间\",\n mitigation=\"评估是否需要增加资源或调整范围\",\n task_ids=[t.id],\n ))\n\n # 3. 关键路径上无进度的任务\n critical = [t for t in all_tasks\n if (t.priority.value in (\"critical\", \"high\")\n and t.status == TaskStatus.BACKLOG)]\n if len(critical) >= 3:\n risks.append(RiskItem(\n description=f\"有 {len(critical)} 个高优先级任务尚未开始\",\n severity=\"high\", probability=0.6,\n impact=\"关键任务延迟将直接影响里程碑\",\n mitigation=\"重新评估优先级和资源分配\",\n task_ids=[t.id for t in critical],\n ))\n\n # 4. 单人过载检测\n workload: Dict[str, float] = {}\n for t in all_tasks:\n if t.status in (TaskStatus.IN_PROGRESS,\n TaskStatus.TODO):\n name = t.assignee.value\n workload[name] = workload.get(name, 0) + t.estimated_hours\n for name, hours in workload.items():\n if hours > 40:\n risks.append(RiskItem(\n description=f\"{name} 当前负载 {hours:.1f}h，超出合理范围\",\n severity=\"medium\", probability=0.5,\n impact=\"过载可能导致质量下降或人员流失\",\n mitigation=\"重新分配任务或增加人手\",\n ))\n\n return risks\n\n def _flatten(self, tasks: List[Task], result: List[Task]):\n for t in tasks:\n result.append(t)\n self._flatten(t.subtasks, result)", "section_ref": "30.3.8", "runnable": true, "dependencies": [ "app" ] }, { "id": "code-12", "language": "python", "description": "", "code": "# app/main.py\n\"\"\"多Agent协作项目管理系统 - FastAPI 入口\"\"\"\n\nfrom contextlib import asynccontextmanager\nfrom fastapi import FastAPI, HTTPException\nfrom fastapi.middleware.cors import CORSMiddleware\nfrom pydantic import BaseModel\nfrom typing import Optional, List\nimport asyncio\n\nfrom app.config import settings\nfrom app.models.task import Project, Task\nfrom app.agents.message_bus import MessageBus\nfrom app.agents.pm_agent import PMAgent\nfrom app.agents.dev_agent import DevAgent\nfrom app.agents.qa_agent import QAAgent\nfrom app.services.risk_analyzer import RiskAnalyzer\n\n# 全局实例\nbus = MessageBus()\npm_agent = PMAgent(bus)\ndev_agent = DevAgent(bus)\nqa_agent = QAAgent(bus)\nrisk_analyzer = RiskAnalyzer()\n\n# 项目存储\nprojects: dict = {}\n\n\n@asynccontextmanager\nasync def lifespan(app: FastAPI):\n print(f\"🚀 {settings.APP_NAME} v{settings.APP_VERSION} 启动\")\n print(f\" 已注册 Agent: pm_agent, dev_agent, qa_agent\")\n yield\n\n\napp = FastAPI(\n title=settings.APP_NAME, version=settings.APP_VERSION,\n lifespan=lifespan,\n description=\"AI 驱动的多 Agent 协作项目管理系统\")\napp.add_middleware(CORSMiddleware, allow_origins=[\"*\"],\n allow_credentials=True,\n allow_methods=[\"*\"], allow_headers=[\"*\"])\n\n\nclass CreateProjectRequest(BaseModel):\n name: str\n description: str = \"\"\n team_members: Optional[List[dict]] = None\n\n\nclass PlanProjectRequest(BaseModel):\n project_id: str\n requirement: str\n\n\nclass ExecuteTaskRequest(BaseModel):\n project_id: str\n task_id: str\n\n\n@app.get(\"/health\")\nasync def health():\n return {\"status\": \"ok\", \"version\": settings.APP_VERSION,\n \"agents\": [\"pm_agent\", \"dev_agent\", \"qa_agent\"]}\n\n\n@app.post(\"/api/v1/projects\")\nasync def create_project(req: CreateProjectRequest):\n \"\"\"创建项目\"\"\"\n project = Project(\n name=req.name,\n description=req.description,\n team_members=req.team_members or [\n {\"name\": \"PM助手\", \"role\": \"pm\"},\n {\"name\": \"开发助手\", \"role\": \"dev\"},\n {\"name\": \"测试助手\", \"role\": \"qa\"},\n ],\n )\n projects[project.id] = project\n return {\"project_id\": project.id, \"name\": project.name}\n\n\n@app.post(\"/api/v1/projects/{project_id}/plan\")\nasync def plan_project(project_id: str, req: PlanProjectRequest):\n \"\"\"规划项目（需求拆解 → 任务分配）\"\"\"\n project = projects.get(project_id)\n if not project:\n raise HTTPException(404, \"项目不存在\")\n\n # PM Agent 规划\n plan = await pm_agent.plan_project(project, req.requirement)\n tasks = pm_agent.parse_tasks(plan, project_id)\n project.tasks = tasks\n\n # 风险预分析\n risks = risk_analyzer.analyze(project)\n\n return {\n \"project_id\": project_id,\n \"tasks\": [t.to_dict() for t in tasks],\n \"milestones\": plan.get(\"milestones\", []),\n \"risks\": [{\"description\": r.description,\n \"severity\": r.severity} for r in risks],\n \"notes\": plan.get(\"notes\", \"\"),\n }\n\n\n@app.get(\"/api/v1/projects/{project_id}/status\")\nasync def get_project_status(project_id: str):\n \"\"\"获取项目状态\"\"\"\n project = projects.get(project_id)\n if not project:\n raise HTTPException(404, \"项目不存在\")\n\n # PM Agent 状态分析\n status = await pm_agent.analyze_status(project)\n\n # 规则引擎风险分析\n risks = risk_analyzer.analyze(project)\n\n return {\n \"project_id\": project_id,\n \"name\": project.name,\n \"progress\": round(project.progress, 1),\n \"total_tasks\": project.total_tasks,\n \"completed_tasks\": project.completed_tasks,\n \"overall_status\": status.get(\"overall_status\", \"unknown\"),\n \"team_workload\": status.get(\"team_workload\", {}),\n \"risks\": [{\"description\": r.description,\n \"severity\": r.severity,\n \"mitigation\": r.mitigation} for r in risks],\n \"summary\": status.get(\"summary\", \"\"),\n \"recommendations\": status.get(\"recommendations\", []),\n }\n\n\n@app.post(\"/api/v1/projects/{project_id}/tasks/{task_id}/execute\")\nasync def execute_task(project_id: str, task_id: str):\n \"\"\"执行任务（Dev + QA 完整流程）\"\"\"\n project = projects.get(project_id)\n if not project:\n raise HTTPException(404, \"项目不存在\")\n\n task = _find_task(project.tasks, task_id)\n if not task:\n raise HTTPException(404, \"任务不存在\")\n\n # Dev Agent 执行\n result = await dev_agent.execute_task(task, project_id)\n\n return {\n \"task_id\": task_id,\n \"status\": \"completed\",\n \"tech_design\": {\n \"approach\": result[\"tech_design\"].get(\"approach\", \"\"),\n \"complexity\": result[\"tech_design\"].get(\n \"estimated_complexity\", \"\"),\n },\n \"files_created\": [\n f[\"path\"] for f in result.get(\"code\", {}).get(\"files\", [])],\n \"self_review\": {\n \"passed\": result[\"self_review\"].get(\"passed\", True),\n \"issues\": result[\"self_review\"].get(\"issues\", []),\n },\n }\n\n\n@app.get(\"/api/v1/projects/{project_id}/messages\")\nasync def get_messages(project_id: str, limit: int = 50):\n \"\"\"获取 Agent 协作消息记录\"\"\"\n messages = bus.get_history(project_id, limit)\n return {\n \"project_id\": project_id,\n \"messages\": [\n {\n \"id\": m.id, \"type\": m.type.value,\n \"sender\": m.sender, \"recipient\": m.recipient,\n \"payload\": m.payload,\n \"timestamp\": m.timestamp.isoformat(),\n }\n for m in messages\n ],\n }\n\n\ndef _find_task(tasks: List[Task], task_id: str) -> Optional[Task]:\n for t in tasks:\n if t.id == task_id:\n return t\n found = _find_task(t.subtasks, task_id)\n if found:\n return found\n return None\n\n\nif __name__ == \"__main__\":\n import uvicorn\n uvicorn.run(\"app.main:app\", host=\"0.0.0.0\", port=8000,\n reload=settings.DEBUG)", "section_ref": "30.3.9", "runnable": true, "dependencies": [ "contextlib", "fastapi", "pydantic", "app" ] }, { "id": "code-13", "language": "python", "description": "---", "code": "# demo/run_pipeline.py\n\"\"\"完整项目管理流程演示\"\"\"\n\nimport asyncio\nfrom app.main import app\nfrom app.agents.pm_agent import PMAgent\nfrom app.agents.dev_agent import DevAgent\nfrom app.agents.qa_agent import QAAgent\nfrom app.agents.message_bus import MessageBus\nfrom app.models.task import Project\nfrom app.services.risk_analyzer import RiskAnalyzer\n\n\nasync def demo():\n # 1. 创建项目\n project = Project(\n name=\"AI 写作助手 v2.0\",\n description=\"基于大模型的智能写作辅助工具，支持多种文体和语言\",\n team_members=[\n {\"name\": \"PM助手\", \"role\": \"pm\"},\n {\"name\": \"开发助手\", \"role\": \"dev\"},\n {\"name\": \"测试助手\", \"role\": \"qa\"},\n ],\n )\n\n # 2. PM 规划\n bus = MessageBus()\n pm = PMAgent(bus)\n dev = DevAgent(bus)\n qa = QAAgent(bus)\n analyzer = RiskAnalyzer()\n\n requirement = \"\"\"\n 需要开发一个 AI 写作助手，具备以下功能：\n 1. 用户输入主题和风格偏好，AI 自动生成文章初稿\n 2. 支持多种文体：科技博客、产品文案、社交媒体帖子\n 3. 内置敏感词检测和 SEO 优化建议\n 4. 提供文章可读性评分和改进建议\n 5. RESTful API 接口，支持第三方集成\n \"\"\"\n\n print(\"📋 PM 正在规划项目...\")\n plan = await pm.plan_project(project, requirement)\n tasks = pm.parse_tasks(plan, project.id)\n project.tasks = tasks\n\n print(f\" 拆解出 {len(tasks)} 个任务\")\n for t in tasks:\n print(f\" [{t.priority.value}] {t.title} \"\n f\"→ {t.assignee.value} ({t.estimated_hours}h)\")\n\n # 3. 风险分析\n risks = analyzer.analyze(project)\n print(f\"\\n⚠️ 风险预分析: 发现 {len(risks)} 个风险\")\n for r in risks:\n print(f\" [{r.severity}] {r.description}\")\n\n # 4. 执行第一个开发任务\n if tasks:\n dev_task = next(\n (t for t in tasks if t.assignee.value == \"dev\"), None)\n if dev_task:\n print(f\"\\n💻 Dev 正在执行任务: {dev_task.title}\")\n result = await dev.execute_task(dev_task, project.id)\n print(f\" 技术方案: {result['tech_design'].get('approach', '')[:100]}\")\n print(f\" 生成文件: {result['code'].get('files', [])}\")\n print(f\" 自审通过: {result['self_review'].get('passed', False)}\")\n\n # 5. 项目状态\n status = await pm.analyze_status(project)\n print(f\"\\n📊 项目状态: {status.get('overall_status', 'unknown')}\")\n print(f\" {status.get('summary', '')}\")\n\n # 6. 消息历史\n messages = bus.get_history(project.id)\n print(f\"\\n💬 Agent 协作消息: 共 {len(messages)} 条\")\n for m in messages:\n print(f\" {m.sender} → {m.recipient or '广播'}: \"\n f\"{m.type.value}\")\n\n\nif __name__ == \"__main__\":\n asyncio.run(demo())", "section_ref": "30.4", "runnable": true, "dependencies": [ "app" ] }, { "id": "code-14", "language": "python", "description": "---", "code": "# tests/test_pm_agent.py\n\"\"\"项目经理 Agent 测试\"\"\"\n\nimport pytest\nfrom app.agents.pm_agent import PMAgent\nfrom app.agents.message_bus import MessageBus\nfrom app.models.task import Project\n\n\n@pytest.fixture\ndef setup():\n bus = MessageBus()\n pm = PMAgent(bus)\n project = Project(\n name=\"测试项目\",\n description=\"用于测试的项目\",\n team_members=[\n {\"name\": \"开发\", \"role\": \"dev\"},\n {\"name\": \"测试\", \"role\": \"qa\"},\n ],\n )\n return bus, pm, project\n\n\n@pytest.mark.asyncio\nasync def test_parse_tasks(setup):\n bus, pm, project = setup\n plan = {\n \"tasks\": [\n {\"title\": \"用户模块\", \"description\": \"用户注册登录\",\n \"priority\": \"high\", \"estimated_hours\": 8,\n \"assignee\": \"dev\", \"acceptance_criteria\": [\"可注册登录\"]},\n {\"title\": \"API接口\", \"description\": \"REST API\",\n \"priority\": \"medium\", \"estimated_hours\": 16,\n \"assignee\": \"dev\", \"acceptance_criteria\": [\"接口可用\"]},\n {\"title\": \"测试用例\", \"description\": \"自动化测试\",\n \"priority\": \"medium\", \"estimated_hours\": 4,\n \"assignee\": \"qa\", \"acceptance_criteria\": [\"测试通过\"]},\n ],\n }\n tasks = pm.parse_tasks(plan, project.id)\n assert len(tasks) == 3\n assert tasks[0].title == \"用户模块\"\n assert tasks[0].priority.value == \"high\"\n assert tasks[2].assignee.value == \"qa\"\n\n\ndef test_risk_analyzer():\n from app.services.risk_analyzer import RiskAnalyzer\n from app.models.task import Task, TaskStatus, TaskPriority, AgentRole\n from app.config import TaskStatus as TS\n\n analyzer = RiskAnalyzer()\n project = Project(name=\"test\")\n project.tasks = [\n Task(title=\"阻塞任务\", status=TS.BLOCKED,\n priority=TaskPriority.HIGH, estimated_hours=8,\n actual_hours=16),\n Task(title=\"待办任务\", status=TS.BACKLOG,\n priority=TaskPriority.CRITICAL, estimated_hours=4),\n ]\n risks = analyzer.analyze(project)\n assert len(risks) > 0\n assert any(\"阻塞\" in r.description for r in risks)", "section_ref": "30.5", "runnable": true, "dependencies": [ "pytest", "app" ] }, { "id": "code-15", "language": "dockerfile", "description": "---", "code": "FROM python:3.11-slim\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\nCOPY app/ ./app/\nEXPOSE 8000\nCMD [\"uvicorn\", \"app.main:app\", \"--host\", \"0.0.0.0\", \"--port\", \"8000\"]", "section_ref": "30.6", "runnable": false, "dependencies": [] } ], "tables": [ { "headers": [ "维度", "指标" ], "data": [ [ "任务拆解准确率", "> 85%（粒度合理、无遗漏）" ], [ "进度预测准确率", "> 75%（7天内）" ], [ "协作消息延迟", "< 500ms" ], [ "并发项目支持", "50 个" ], [ "Agent 响应时间", "P95 < 10 秒" ] ] }, { "headers": [ "模式", "应用场景", "效果" ], "data": [ [ "事件驱动架构", "Agent 间通信", "松耦合，可扩展" ], [ "消息总线", "协作协调", "消除 Agent 直接依赖" ], [ "加权进度", "进度预测", "准确率从 60% 提升到 80%" ], [ "双引擎分析", "风险检测", "规则引擎实时 + LLM 深度分析" ] ] } ], "key_takeaways": [], "common_pitfalls": [], "related_chapters": [ "ch08", "ch32" ] }