# 天工平台工程团队 — 使用指南

> 如何使用虚拟团队自举维护和迭代天工智能体平台本身

---

## 一、快速开始

### 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 选择规划者