admin/aiagent
1
0
Fork 0
Code Issues 23 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 选择规划者