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 事件流，实时推送执行进度 |

#### 同步执行响应结构

```json
{
  "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 日