aiagent/docs/virtual-team.md

虚拟团队 — 软件公司协作开发

Virtual Software Company Team — 基于多 Agent 角色编排的自动化软件开发流水线

---

一、功能概述

虚拟团队是天工智能体平台的核心高级功能，将软件公司的五大经典角色（PM / 设计师 / 开发 / 测试 / DevOps）映射为 AI Agent，组成一个可自动协作的虚拟开发团队。用户只需输入项目描述，团队即可自动完成从需求分析到部署上线的全流程，并产出实际代码文件。

核心能力

能力	说明
一键创建团队	点击"软件公司模板"，自动创建 5 个角色 Agent 并组建团队
PM 智能规划	项目经理 Agent 分析需求，输出包含阶段划分的 JSON 开发计划
顺序流水线执行	按 PM → Designer → Developer → QA → DevOps 顺序执行各阶段
文件产出	各 Agent 将代码、文档、配置写入指定项目目录
QA 自动审查	测试 Agent 审查全部交付物，输出缺陷报告和评分
流式进度推送	SSE 实时推送每个阶段的开始/完成状态
项目文件追溯	执行完成后展示项目文件路径和完整文件清单

---

二、系统架构

2.1 角色定义

┌─────────────────────────────────────────────────────────────┐
│                    虚拟软件团队 (5 Roles)                      │
├──────────┬──────────┬──────────┬──────────┬─────────────────┤
│  📋 PM   │  🎨 UI   │  💻 Dev  │  🔍 QA  │  🚀 DevOps     │
│ 项目经理 │ 设计师   │ 全栈开发 │ 测试工程 │ DevOps工程师    │
│          │          │          │          │                 │
│ 需求分析 │ 交互设计 │ 前后端   │ 审查交付 │ 部署配置        │
│ 任务分解 │ 视觉规范 │ 代码编写 │ 发现缺陷 │ CI/CD           │
│ 计划制定 │ 组件规划 │ 数据库   │ 验收标准 │ 环境管理        │
│          │          │          │          │                 │
│ Lead ✅  │          │          │          │                 │
├──────────┴──────────┴──────────┴──────────┴─────────────────┤
│  温度: 0.4    0.6        0.3        0.3        0.3          │
│  模型: v4-pro flash      v4-pro     flash      flash        │
│  迭代: 15     12         25         15         12           │
└─────────────────────────────────────────────────────────────┘

2.2 执行流程

用户输入项目描述
       │
       ▼
┌──────────────────┐
│  Phase 0: PM 规划 │  ─── 输出 JSON 执行计划（4~7 个阶段）
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│  Phase 1..N      │  按角色顺序执行：
│  各阶段 Agent     │  Designer → Developer → QA → DevOps
│  写入项目文件     │  每个 Agent 接收上下文 + 项目目录路径
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│  QA 审查          │  汇总审核全部交付物，给出评分
└──────┬───────────┘
       │
       ▼
┌──────────────────┐
│  最终交付物汇总   │  项目路径 + 文件清单 + 评审报告
└──────────────────┘

---

三、数据模型

3.1 Team（团队）

字段	类型	说明
id	UUID	团队唯一标识
name	str	团队名称（默认"软件公司虚拟团队"）
description	str	团队描述
workspace_id	UUID?	所属工作区
user_id	UUID	创建者
is_template	bool	是否为模板（模板创建时为 True）
config	JSON	扩展配置（角色列表等）
status	str	状态：active / archived

3.2 TeamMember（团队成员）

字段	类型	说明
id	UUID	记录 ID
team_id	UUID FK	所属团队
agent_id	UUID FK	关联的 Agent
role	str	角色标识：pm / designer / developer / qa / devops
position	int	排序位置
is_lead	bool	是否为该角色 Leader

---

四、API 参考

Base: /api/v1/teams

4.1 团队 CRUD

方法	路径	说明
GET	/teams	列出用户的所有团队
POST	/teams	创建团队
GET	/teams/{id}	获取团队详情（含成员列表）
PUT	/teams/{id}	更新团队信息
DELETE	/teams/{id}	删除团队

4.2 成员管理

方法	路径	说明
GET	/teams/{id}/members	列出团队成员
POST	/teams/{id}/members	添加成员（agent_id + role）
DELETE	/teams/{id}/members/{mid}	移除成员

4.3 模板工厂

方法	路径	说明
POST	/teams/template/software-company	一键创建软件公司模板 — 自动创建 5 个角色 Agent + 团队
GET	/teams/preset-roles	获取预置角色定义（名称、图标、描述）

4.4 项目执行

方法	路径	说明
POST	/teams/{id}/execute	同步执行 — 返回完整执行结果（含计划、各阶段产出、文件清单）
POST	/teams/{id}/execute/stream	流式执行 — SSE 事件流，实时推送执行进度

同步执行响应结构

{
  "data": {
    "team_id": "uuid",
    "team_name": "软件公司虚拟团队",
    "project_description": "...",
    "project_path": "D:\\aaa\\aiagent\\team_projects\\{team_id}\\{project}/",
    "files": ["D:\\...\\index.html", "D:\\...\\api.py", ...],
    "plan": { "project_name": "...", "phases": [...] },
    "phases": [
      {
        "phase": 1,
        "name": "需求分析与产品定义",
        "role": "pm",
        "agent_name": "项目经理 (PM)",
        "output": "...",
        "success": true,
        "iterations": 1,
        "tool_calls": 2,
        "files": ["..."]
      }
    ],
    "qa_review": { "pass": true, "score": 85, "issues": [...] },
    "final_deliverable": "# 全部交付物汇总 ...",
    "success": true
  }
}

SSE 流式事件类型

事件类型	说明	关键字段
plan_start	PM 开始规划	team_name, member_count, project_path
plan_done	PM 规划完成	plan (JSON), success
phase_start	阶段开始执行	phase, name, role, agent
phase_done	阶段执行完成	output, success, iterations, tool_calls, files
qa_done	QA 审查完成	output, review (JSON)
final	全部完成	deliverable, project_path, files, phase_count
error	错误	content

---

五、Agent 系统提示词设计

每个角色 Agent 在创建时被注入专用的系统提示词，确保执行风格符合角色定位：

PM 系统提示词要点

• 分析需求 → 用户故事 → 阶段分解（4-7 个）
• 每个阶段指定 role + 描述 + 期望产出
• 输出严格 JSON 格式

Designer 系统提示词要点

• 用户流程 / 线框图 / 组件层级 / 视觉设计 tokens
• 指定颜色、字体、间距系统
• 输出结构化 Markdown + HTML/CSS 原型

Developer 系统提示词要点

• 技术栈：Python/FastAPI + Vue 3/TypeScript + SQLAlchemy + Element Plus
• 使用 file_write 产出完整、可运行的代码文件
• 包含类型标注、错误处理、输入验证

QA 系统提示词要点

• 审查验收标准覆盖、边界情况、安全漏洞、API 契约一致性
• 输出 JSON 评审报告（pass / score / issues / overall_assessment）

DevOps 系统提示词要点

• Dockerfile + docker-compose + nginx.conf
• .env.example + 健康检查 + 部署 README

---

六、前后端文件索引

后端

文件	说明
backend/app/models/team.py	Team / TeamMember SQLAlchemy 模型
backend/app/api/teams.py	12 个 API 端点（CRUD + 模板 + 执行）
backend/app/services/team_service.py	TeamService + 模板工厂 + 5 种角色系统提示词
backend/app/services/team_orchestrator.py	TeamOrchestrator 执行引擎（同步 + SSE 流式）

前端

文件	说明
frontend/src/views/TeamBuilder.vue	虚拟团队主页面（~850 行），含角色槽位、拖拽、执行结果展示
frontend/src/api/teams.ts	TypeScript API 客户端（接口 + 请求函数）
frontend/src/router/index.ts	/teams 路由注册
frontend/src/components/MainLayout.vue	导航栏"虚拟团队"菜单项

---

七、使用指南

7.1 创建虚拟团队

1. 访问 http://localhost:3001/teams
2. 点击 "软件公司模板" 按钮
3. 系统自动创建 5 个角色 Agent（如已有同名则复用）并组建团队
4. 5 个角色槽位自动填充对应 Agent

7.2 手动分配 Agent

1. 左侧面板显示所有可用 Agent
2. 拖拽 Agent 到中间对应的角色卡片上
3. 也可从槽位中移除已分配的 Agent

7.3 执行项目

1. 在底部输入框输入项目描述，例如：

   做一个支持用户注册登录的个人博客系统，包含文章发布、评论功能

2. 点击 "执行项目"（同步，有 tab 页展示）或 "流式执行"（实时进度推送）

3. 观察执行过程：

   • PM 需求分析 → 生成开发计划
   • 各阶段按角色顺序执行
   • QA 审查最终交付物

4. 查看结果：

   • "项目计划" tab：PM 的 JSON 规划
   • 各阶段 tab：Agent 的产出内容（Markdown 渲染）
   • "QA 审查" tab：质量报告
   • "最终交付物" tab：汇总的全部产出
   • "项目文件" tab：保存路径 + 产出文件清单

7.4 查找交付文件

执行完成后，文件保存在：

<项目根目录>/team_projects/<team_id>/<项目名>/

页面上的"项目文件"区域会显示完整路径（可复制）和所有产出文件的列表。

---

八、技术要点

8.1 项目目录管理

• 执行前在 <workspace_root>/team_projects/<team_id>/<safe_name>/ 创建目录
• 安全命名：取项目描述前 40 字符，仅保留 ASCII 字母数字和连字符
• 每个阶段 Agent 通过 prompt 获取该路径，file_write 工具将文件写入此目录

8.2 Agent 配置构建

_build_agent_config() 从 Agent 的 workflow_config JSON 中提取：

• nodes[type=llm].data.prompt → 系统提示词
• nodes[type=llm].data.model → 模型名称
• nodes[type=llm].data.temperature → 温度参数
• nodes[type=llm].data.selected_tools → 工具白名单
• nodes[type=llm].data.max_iterations → 最大 ReAct 迭代次数

8.3 上下文传递

每个阶段 Agent 接收前序阶段产出的摘要（上限 2000 字符），形成渐进式上下文积累，确保后续阶段了解之前的工作。

8.4 文件追踪（双保险机制）

1. AgentResult.steps 提取：扫描 AgentResult.steps 中的 file_write 工具调用记录
2. 目录扫描：每个阶段后对比项目目录快照，检测新创建的文件
3. 最终文件列表以目录扫描为准，同时合并 AgentResult 提取的路径

---

九、与相关功能的对比

功能	Agent 编排	虚拟团队
编排方式	可视化 DAG 画布（节点+连线）	固定角色流水线
角色定义	无（通用节点）	PM/Designer/Dev/QA/DevOps 五种角色
执行模式	5 种协作模式（顺序/并行/投票/Swarm/辩论）	顺序执行
适用场景	通用多 Agent 协作	软件项目开发
文件产出	依赖节点配置	强制写入项目目录
项目路径	无	自动创建并返回

---

最后更新：2026 年 6 月 16 日