admin/aiagent
1
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add education-training and platform-engineering team templates

Browse Source 
- Add 2 new team templates: 教育培训团队 (4 roles) and 天工平台工程团队 (5 roles)
- Fix orchestrator to support multi-template workflow types (remove hardcoded PM planner)
- Add _resolve_planner_role() to auto-detect planner based on team.config.workflow
- Add frontend buttons and API clients for new templates
- Merge 14 preset roles from 3 template families in get_preset_roles()
- Add creation guide and platform engineering usage docs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
renjianbo
2026-06-17 00:09:54 +08:00
parent 7f4aeb021b
commit f612248f9e
8 changed files with 4046 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

321
docs/agent-guides/创建团队模板.md Normal file
View File

@@ -0,0 +1,321 @@
# 创建虚拟团队模板指南
> 本文档记录如何为新业务场景创建虚拟团队模板，基于已有 3 个模板的实现经验总结。
---
## 一、模板系统架构
### 1.1 什么是团队模板
团队模板是一键创建的虚拟团队，包含预定义角色 + 专属 Agent（含系统提示词），用户点击按钮即可获得一个可执行项目的完整团队。
### 1.2 现有模板
| # | 模板 | 角色数 | 适用场景 |
|---|------|--------|----------|
| 1 | 软件公司虚拟团队 | 5 | 新项目从零开发 |
| 2 | 教育培训团队 | 4 | 在线教育课程建设 |
| 3 | 天工平台工程团队 | 5 | 已有平台持续迭代运维 |
### 1.3 涉及文件
创建新模板需要修改 **4 个文件**：
| 层级 | 文件路径 | 改动内容 |
|------|----------|----------|
| 后端服务 | `backend/app/services/team_service.py` | 角色定义 + 系统提示词 + 工厂方法 |
| 后端 API | `backend/app/api/teams.py` | 新增路由端点 |
| 前端 API | `frontend/src/api/teams.ts` | 新增请求函数 |
| 前端页面 | `frontend/src/views/TeamBuilder.vue` | 新增按钮 + 事件处理 |
---
## 二、创建步骤（以教育培训团队为例）
### 步骤 1：设计角色体系
先确定角色数量（建议 4-5 个）、每个角色的职责边界和产出物。
**示例 — 教育培训团队：**
- 课程设计师：课程体系、学习目标、评估方法
- 主讲讲师：课件、讲授方案、互动设计
- 作业助教：批改、辅导、进度跟踪
- 教务管理：排课、学员管理、证书
### 步骤 2：编写系统提示词
在 `team_service.py` 中为每个角色编写专属提示词。遵循以下规范：
```python
ROLE_NAME_PROMPT = """You are a [Role Name] for [context]. Your responsibilities:
1. [职责 1]
2. [职责 2]
...
When you receive a task:
- [行为规范 1]
- [行为规范 2]
Output format — include [期望输出格式说明]:
{
"key": "value"
}"""
```
**提示词编写要点：**
- 用英文写角色定义（与 LLM 训练数据对齐），中文写具体场景说明
- 明确输出格式（JSON schema 或 Markdown 结构）
- 指定工具使用偏好（什么时候用 `file_write`，什么时候用 `web_search`）
- 给出 3-5 条具体行为规范，避免模糊描述
- 提示词长度控制在 30-60 行
### 步骤 3：定义角色元数据
在 `PRESET_ROLES` 同级位置添加新角色字典：
```python
EDUCATION_ROLES = {
"curriculum_designer": {
"label": "课程设计师",
"icon": "📐",
"description": "设计课程体系、学习目标、知识模块、评估方法",
},
"instructor": {
"label": "主讲讲师",
"icon": "🎓",
"description": "授课讲解、制作课件、设计互动、辅导答疑",
},
# ... 其他角色
}
```
**要点：**
- `key` 用英文下划线命名（与 role 标识一致）
- `label` 用中文显示名称
- `icon` 用一个 emoji 表示
- `description` 用一句话概括职责
### 步骤 4：编写工厂方法
在 `TeamService` 类中添加 `create_*_template()` 方法。可直接复制已有模板方法，修改以下内容：
```python
def create_education_training_template(
self, user_id: str, workspace_id: Optional[str] = None
) -> Dict[str, Any]:
"""创建「模板名称」模板：N 个角色 Agent + 1 个 Team。"""
role_configs = [
{
"role": "curriculum_designer", # 角色 key
"name": "课程设计师", # Agent 名称
"description": "...", # Agent 描述
"system_prompt": CURRICULUM_DESIGNER_PROMPT, # 提示词常量
"tools": ["web_search", "file_write", ...], # 工具列表
"temperature": 0.4, # 温度参数
"model": "deepseek-v4-pro", # 模型
"max_iterations": 15, # 最大迭代次数
"is_lead": True, # 是否为团队 Leader
},
# ... 其他角色
]
# Agent 创建/复用逻辑（无需修改，直接复制）
created_agents: List[Dict] = []
for rc in role_configs:
existing = (
self.db.query(Agent)
.filter(Agent.name == rc["name"], Agent.user_id == user_id)
.first()
)
if existing:
created_agents.append({"agent": existing, **rc})
continue
agent = Agent(...) # 标准 Agent 创建
# ...
# Team 创建（需修改名称和描述）
team = Team(
name="模板团队名称",
description="团队描述",
config={"workflow": "模板标识", "roles": list(EDUCATION_ROLES.keys())},
# ...
)
```
**参数选择经验：**
| 角色类型 | 推荐模型 | 推荐温度 | 推荐迭代 |
|----------|---------|---------|---------|
| 需要创造力的角色（设计/产品/讲师） | v4-pro | 0.4-0.6 | 15-20 |
| 需要精确执行的角色（开发/测试/运维） | v4-pro 或 flash | 0.3-0.4 | 12-25 |
| 批处理/管理类角色（教务/助教） | v4-flash | 0.3 | 12-15 |
### 步骤 5：注册 API 端点
在 `teams.py` 中添加新路由，直接复制已有端点并修改路径和方法名：
```python
@router.post("/template/education-training")
def create_education_training_template(
workspace_id: Optional[str] = Query(None),
db: Session = Depends(get_db),
current_user: User = Depends(get_current_user),
):
"""模板说明 docstring"""
svc = TeamService(db)
result = svc.create_education_training_template(
user_id=current_user.id,
workspace_id=workspace_id,
)
return {"data": result}
```
**命名规范：**
- URL 路径：`/template/{kebab-case-模板名}`
- 函数名：`create_{snake_case_模板名}_template`
### 步骤 6：合并预设角色
更新 `get_preset_roles()` 函数，将新角色集合并进去：
```python
def get_preset_roles() -> Dict[str, Any]:
"""返回所有预置角色定义（供前端展示）。"""
return {**PRESET_ROLES, **EDUCATION_ROLES, **NEW_TEAM_ROLES}
```
> 这一步很关键，否则前端不会渲染新角色的槽位。
### 步骤 7：前端 API 客户端
在 `frontend/src/api/teams.ts` 中添加：
```typescript
/** 一键创建教育培训团队模板 */
export function createEducationTrainingTemplate(workspaceId?: string) {
return api.post('/api/v1/teams/template/education-training', null, {
params: workspaceId ? { workspace_id: workspaceId } : {},
})
}
```
### 步骤 8：前端 UI 按钮
在 `frontend/src/views/TeamBuilder.vue` 中做 3 处修改：
**a) 导入函数**
```typescript
import {
// ... 已有导入
createEducationTrainingTemplate,
} from '@/api/teams'
```
**b) 添加按钮**
```vue
<el-button type="warning" @click="handleCreateEducationTemplate"
:loading="creatingEduTemplate">
<el-icon><MagicStick /></el-icon> 教育培训模板
</el-button>
```
**c) 添加 handler**
```typescript
const creatingEduTemplate = ref(false)
async function handleCreateEducationTemplate() {
creatingEduTemplate.value = true
try {
const res = await createEducationTrainingTemplate()
const team = (res.data as any)?.data
if (team) {
currentTeamId.value = team.id
teamName.value = team.name
await loadAgents()
const slots: Record<string, any> = {}
if (team.members) {
for (const m of team.members) {
const agent = agents.value.find(a => a.id === m.agent_id)
if (agent) slots[m.role] = { ...agent, is_lead: m.is_lead, member_id: m.id }
}
}
roleSlots.value = slots
ElMessage.success('教育培训团队创建成功！')
}
await loadTeams()
} catch (e: any) {
ElMessage.error(e?.response?.data?.detail || '创建模板失败')
} finally {
creatingEduTemplate.value = false
}
}
```
> 该 handler 逻辑与 `handleCreateTemplate` 完全相同，只需修改函数名和成功提示文字。
### 步骤 9：验证
```bash
# 1. 清除 Python 缓存并重启后端
find backend -name "*.pyc" -path "*__pycache__/*" -delete
# 重启 uvicorn（端口以实际为准）
# 2. 验证预设角色
curl http://127.0.0.1:8041/api/v1/teams/preset-roles
# 应包含新增角色
# 3. 获取 token 并创建模板
TOKEN=$(curl -s -X POST "http://127.0.0.1:8037/api/v1/auth/login" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "username=admin&password=123456" \
| python -c "import json,sys; print(json.load(sys.stdin)['access_token'])")
curl -X POST "http://127.0.0.1:8041/api/v1/teams/template/education-training" \
-H "Authorization: Bearer $TOKEN"
# 4. 前端验证：访问 http://localhost:3001/teams，点击新按钮
```
---
## 三、模板设计原则
### 3.1 角色数量
- 最少 3 个，最多 6 个
- 少于 3 个失去团队协作意义
- 多于 6 个导致执行链条过长，容易失败
### 3.2 角色分工
- 每个角色职责边界清晰，避免重叠
- 设置 1-2 个 Leader 角色（负责规划和决策）
- 执行类角色负责具体产出
### 3.3 提示词设计
- 明确输入是什么、输出是什么
- 给出输出格式约束（JSON Schema 优先）
- 注明需要使用的工具
- 中文场景用中文输出，英文场景用英文
### 3.4 工具选择
- 核心工具必选：`file_write`、`file_read`
- 信息获取：`web_search`
- 分析和处理：`text_analyze`、`json_process`
- 代码相关：`execute_code`、`grep_search`
- 平台专用：`database_query`、`git_operation`、`docker_manage`
---
## 四、后续优化方向
1. **模板参数化**：允许用户在创建时自定义角色数量、模型选择
2. **模板市场**：用户可自行创建和分享模板
3. **模板版本管理**：模板升级时不影响已创建的团队
4. **前端模板选择器**：统一为弹窗选择，而非多个按钮
5. **动态角色加载**：根据模板类型动态渲染不同角色槽位
---
> 最后更新：2026-06-16
> 基于「软件公司」「教育培训」「天工平台工程」三个模板的实现经验

249
docs/agent-guides/天工平台工程团队使用指南.md Normal file
View File

@@ -0,0 +1,249 @@
# 天工平台工程团队 — 使用指南
> 如何使用虚拟团队自举维护和迭代天工智能体平台本身
---
## 一、快速开始
### 1.1 创建团队
1. 访问 `http://localhost:3001/teams`
2. 点击红色 **「天工平台工程团队」** 按钮
3. 系统自动创建 5 个角色 Agent 并组建团队，5 个角色槽位自动填充
### 1.2 团队角色分工
| 角色 | 负责范围 | 规划者 |
|------|----------|--------|
| 📊 产品负责人 | 需求分析、任务分解、优先级排序、计划制定 | **是** |
| 🏗️ 全栈开发 | 代码实现、Bug 修复、API 开发、数据库迁移 | **是** |
| 🎯 前端体验 | 工作流编辑器、移动端、交互打磨、飞书 Bot 体验 | 否 |
| 🚀 平台运维 | 部署、CI/CD、监控、日志、K8s | 否 |
| 🔍 质量保障 | 测试、性能压测、安全审计、回归测试 | 否 |
> 执行项目时，📊**产品负责人**会自动负责规划阶段，将任务分解后分配给对应角色。
---
## 二、不同场景的使用方法
### 场景 1：修复 Bug
**输入示例：**
```
修复 Bug：用户执行 Agent 对话时，超过 30000ms 报 timeout 错误。
现象：
- 前端对话框中显示 "发送失败: timeout of 30000ms exceeded"
- 后端日志显示 Celery Worker 无法连接 Redis
线索：
- backend/.env 中 REDIS_URL 可能配置错误
- 检查 app/core/celery_app.py 的超时配置
```
**执行流程：**
1. 产品负责人 → 分析 Bug 影响范围，制定修复计划
2. 全栈开发 → 检查代码、定位根因、编写修复
3. 质量保障 → 验证修复、回归测试
4. 平台运维 → 确认配置正确、验证健康检查
**输出位置：** `team_projects/{team_id}/{project-name}/` 包含修复 diff、测试脚本
---
### 场景 2：开发新功能
**输入示例：**
```
新增功能：Agent 市场模板评分系统
需求：
- 用户可以对 Agent 市场中的模板进行 1-5 星评分
- 显示平均评分和评分人数
- 用户只能评分一次（可以修改）
涉及：
- 后端：新增评分表 + API（已预设 POST /api/v1/agent-market/{id}/rate）
- 前端：Agent 市场详情页添加星级评分组件
- 测试：评分增删改查 + 权限验证
```
**执行流程：**
1. 产品负责人 → 拆分为后端/前端/测试三个子任务
2. 全栈开发 → 后端数据库迁移 + API 实现
3. 前端体验 → 星级组件 + 交互优化
4. 质量保障 → 接口测试 + 边界用例
5. 平台运维 → 数据库迁移执行 + 部署验证
---
### 场景 3：性能优化
**输入示例：**
```
性能优化：Agent 列表页加载缓慢
现状：
- /api/v1/agents 接口响应时间 p95 = 2.3s
- 页面首次加载 100 个 Agent 需要 4s+
目标：
- API 响应 p95 < 500ms
- 前端首屏渲染 < 1.5s
优化方向：
- 后端：添加数据库索引、分页优化、Redis 缓存
- 前端：虚拟滚动、懒加载
```
**执行流程：**
1. 产品负责人 → 确定性能目标、划分优化优先级
2. 全栈开发 → 后端查询优化、缓存策略
3. 前端体验 → 虚拟滚动实现、代码分割
4. 质量保障 → 压测验证、基准对比
5. 平台运维 → 生产环境监控配置
---
### 场景 4：安全加固
**输入示例：**
```
安全加固：全平台安全审计与修复
检查项：
- SQL 注入风险扫描
- JWT Token 过期与刷新机制
- 文件上传路径遍历防护
- API 接口鉴权覆盖率检查
- 依赖库漏洞扫描（pip-audit / pnpm audit）
- 密码加密强度验证
已有工具：CodeQL、Trivy、Gitleaks 已配置在 CI 中
```
---
### 场景 5：系统升级迭代
**输入示例：**
```
平台迭代 v2.1.0：
1. 多租户支持（数据隔离 + 工作区管理）
2. 飞书 Bot 体验优化（反馈按钮 + 会话摘要）
3. Android App 完成度提升至 90%
4. 模板市场上线（支持用户发布/安装模板）
5. 开发文档完善至 80%
```
---
## 三、编写任务描述的最佳实践
### 3.1 好的任务描述六要素
| 要素 | 说明 | 示例 |
|------|------|------|
| **做什么** | 一句话概括 | "修复 Agent 执行超时 Bug" |
| **现象/背景** | 当前问题或需求来源 | "用户反馈：点击执行后 30s 报错" |
| **涉及范围** | 哪些模块/文件可能需要改动 | "backend/app/core/celery_app.py + .env" |
| **期望结果** | 完成后的行为 | "Agent 执行成功返回结果，不再超时" |
| **约束条件** | 不破坏什么 | "不影响已有 Agent 的执行逻辑" |
| **技术提示** | 已知的线索或方向 | "怀疑 Redis URL 配置不一致" |
### 3.2 避免的错误描述
**不好：** "修一下超时"
**不好：** "前端有点慢，优化一下"
**不好：** "所有东西都检查一遍"
**好的：** "修复 Agent 对话超时（30000ms），检查 Redis 连接和 Celery 配置，在 backend/.env 和 app/core/celery_app.py 中排查，完成后验证 /health 接口正常"
---
## 四、执行过程与产出
### 4.1 两种执行模式
| 模式 | 操作 | 特点 |
|------|------|------|
| **同步执行** | 点击「执行项目」 | 等待完成后一次性查看所有产出 |
| **流式执行** | 点击「流式执行」 | 实时推送每个阶段的进度 |
推荐日常任务用**同步执行**，大型任务用**流式执行**观察中间过程。
### 4.2 产出物的存放与查看
执行完成后，文件保存在：
```
D:\aaa\aiagent\team_projects\{team_id}\{project-name}/
```
页面会展示：
- **项目计划** tab：产品负责人的 JSON 规划
- **各阶段** tab：每个角色的产出内容
- **项目文件** tab：所有生成文件的路径清单
### 4.3 产出的典型文件类型
| 任务类型 | 典型产出 |
|----------|----------|
| Bug 修复 | 修复代码 diff、测试用例、根因分析报告 |
| 新功能 | 完整代码文件、API 接口定义、前端组件、测试脚本 |
| 性能优化 | 优化前后对比、压测报告、配置变更 |
| 安全加固 | 漏洞报告、修复代码、安全配置 |
| 文档完善 | Markdown 文档、API 参考、使用教程 |
---
## 五、注意事项与技巧
### 5.1 执行前检查
- [ ] 5 个角色槽位都已分配 Agent（未分配的角色会被跳过）
- [ ] 任务描述足够具体，包含明确的目标和约束
- [ ] 如有参考文件/配置，在描述中提及具体路径
### 5.2 执行后验证
- [ ] 检查「项目文件」tab 确认文件已生成
- [ ] 在本地文件系统中验证生成的文件内容
- [ ] 对于代码产出，不要直接复制到生产目录，先 review
- [ ] 数据库迁移类产出，先备份再执行
### 5.3 迭代式使用
大型任务建议**分多次执行**，而非一次描述所有需求：
```
第 1 轮: "分析平台当前性能瓶颈，输出性能评估报告"
↓ 拿到报告后
第 2 轮: "根据报告前三项问题，实施优化方案"
↓ 验证优化效果后
第 3 轮: "继续优化剩余问题"
```
### 5.4 与其他模板配合
| 场景 | 使用模板 |
|------|----------|
| 平台核心引擎升级 | 天工平台工程团队 |
| 为平台开发全新子模块 | 软件公司虚拟团队（新项目从零开发） |
| 平台文档/培训体系 | 教育培训团队（制作使用教程） |
---
## 六、已知限制
1. **编排引擎依赖 Leader 做规划** — 如果产品负责人的规划质量不佳（角色分配不合理），后续阶段会受影响
2. **顺序执行** — 不同于 Agent 编排的并行模式，团队按顺序执行，不适合需要实时协作的任务
3. **产出需人工审核** — AI 生成的代码/配置必须 review 后才能合入主分支
4. **每次执行是独立的** — 不会记住上次执行的内容，需要在新描述中提供足够上下文
---
> 最后更新：2026-06-17
> 配套修改：编排引擎已支持多模板类型，自动识别团队 workflow 选择规划者

323
docs/virtual-team.md Normal file
View File

@@ -0,0 +1,323 @@
# 虚拟团队 — 软件公司协作开发
> **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 日