阶段 5-7：从编码到交付

本章目标：体验 AI Agent 编码执行、测试验证和部署交付的完整流程。
预计时长：60 分钟
重要程度：⭐⭐ 这是看到 AI 真正工作的阶段！

前面 4 个阶段主要是"人类决策"，从阶段 5 开始，AI Agent 开始真正的"执行"工作。

阶段 5：编码实现

进入编码阶段

当你推进到阶段 5 时，界面会发生显著变化：

任务看板出现 — 主工作区变成 Kanban 风格的任务管理界面
Agent 开始工作 — 你会看到 Agent 状态从"空闲"变为"忙碌"
实时进度更新 — 任务状态会实时更新

任务执行流程

1. 任务自动分配

系统会根据任务类型自动分配给合适的 Agent：

T001: 项目初始化 → Backend Agent
T004: 前端项目初始化 → Frontend Agent
T002: 数据库模型 → Backend Agent
T005: 主页面布局 → Frontend Agent

你会在任务卡片上看到：

任务标题：T001: 项目初始化
分配角色：Backend
执行 Agent：agent-backend-01
当前状态：assigned → running

2. Agent 编码过程

Agent 接到任务后会：

加载上下文 — 读取项目的技术方案、已有代码
调用 AI 模型 — 根据任务描述生成代码
应用变更 — 在工作区创建/修改文件
Git 提交 — 自动提交代码变更
汇报结果 — 更新任务状态为 reviewing

你可以点击任务卡片查看详细进度：

markdown

## 任务执行日志

**14:23:15** 任务开始执行
**14:23:18** 加载项目上下文完成
**14:23:45** AI 模型调用完成，生成代码方案
**14:24:12** 创建文件: main.py, requirements.txt, models.py
**14:24:15** Git 提交: feat: 初始化 FastAPI 项目结构
**14:24:16** 任务执行完成，等待审核

3. 查看代码产出

任务完成后，点击「查看代码」可以看到 Agent 的产出：

新增文件：

main.py — FastAPI 应用入口
requirements.txt — 项目依赖
models.py — 数据模型定义
database.py — 数据库连接配置

代码示例（main.py）：

python

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from database import engine, Base
from routers import todos

# 创建数据表
Base.metadata.create_all(bind=engine)

app = FastAPI(
    title="待办事项管理 API",
    description="个人待办事项管理应用的后端 API",
    version="1.0.0"
)

# 配置 CORS
app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

# 注册路由
app.include_router(todos.router, prefix="/api/v1")

@app.get("/")
async def root():
    return {"message": "待办事项管理 API"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

审核代码产出

这是你作为"决策者"的重要职责。

1. 审核要点

对于每个完成的任务，检查：

功能完整性：

[ ] 是否实现了任务描述中的所有要求？
[ ] 代码逻辑是否正确？
[ ] 是否遗漏了重要功能？

代码质量：

[ ] 代码结构是否清晰？
[ ] 变量命名是否合理？
[ ] 是否有明显的 Bug？

架构一致性：

[ ] 是否遵循了阶段 3 的技术方案？
[ ] 文件结构是否符合约定？
[ ] API 接口是否符合设计？

2. 审核操作

通过审核：点击「✅ 通过」，任务状态变为 done

打回重做：点击「❌ 打回」，并在反馈框中说明问题：

请修改以下问题：
1. requirements.txt 中缺少 sqlalchemy 依赖
2. models.py 中 Todo 模型缺少 updated_at 字段
3. 数据库连接应该使用环境变量配置

Agent 会根据你的反馈重新生成代码。

3. 补充上下文

如果发现任务描述不够详细，可以点击「补充说明」：

请注意以下额外要求：
- 所有 API 接口都要有详细的文档字符串
- 数据验证要使用 Pydantic 模型
- 错误处理要返回标准的 HTTP 状态码
- 日志记录使用 Python logging 模块

处理任务失败

常见失败原因

1. 上下文不足

错误信息：无法理解任务要求，缺少必要的技术细节
解决方案：补充更详细的任务描述

2. 任务粒度太大

错误信息：任务复杂度超出单次处理能力
解决方案：将任务拆分为更小的子任务

3. 模型能力不够

错误信息：当前模型无法生成符合要求的代码
解决方案：为该角色分配更强的模型

4. 依赖未满足

错误信息：依赖的任务尚未完成或产出不可用
解决方案：检查任务依赖关系，确保前置任务已完成

失败处理流程

查看错误日志 — 点击任务卡片查看详细错误信息
分析失败原因 — 根据错误类型选择处理方式
采取修复措施 — 补充说明、拆分任务或升级模型
重新执行 — 点击「重试」按钮重新执行任务

并行执行监控

多个任务可以并行执行，你需要监控整体进度：

📊 执行统计
┌─────────────────┐
│ 总任务：15      │
│ 已完成：3       │
│ 执行中：2       │
│ 等待中：8       │
│ 失败：1         │
│ 成功率：75%     │
└─────────────────┘

🤖 Agent 状态
┌─────────────────┐
│ Backend-01: 忙碌 │
│ Frontend-01: 忙碌│
│ Tester-01: 空闲  │
│ DevOps-01: 空闲  │
└─────────────────┘

阶段 6：集成测试

测试阶段目标

编码完成后，需要验证各模块集成后的整体功能。

重要认知

"能跑"不等于"可交付"。单个任务通过不代表整个系统正常工作。

测试执行流程

1. 自动生成测试用例

进入阶段 6 后，Tester 角色会：

分析已完成的代码 — 扫描所有 API 接口和前端组件
生成测试用例 — 覆盖主要功能路径
创建测试脚本 — 可执行的自动化测试

生成的测试用例示例：

markdown

# 集成测试用例

## 1. API 接口测试

### TC001: 创建待办事项
- 前置条件：后端服务正常启动
- 测试步骤：
  1. POST /api/v1/todos 创建新任务
  2. 验证返回状态码为 201
  3. 验证返回数据包含正确的任务信息
- 期望结果：任务成功创建并返回完整信息

### TC002: 获取待办事项列表  
- 前置条件：数据库中存在测试数据
- 测试步骤：
  1. GET /api/v1/todos 获取任务列表
  2. 验证返回状态码为 200
  3. 验证返回数据格式正确
- 期望结果：返回正确的任务列表

## 2. 前端功能测试

### TC003: 添加任务界面
- 前置条件：前端应用正常加载
- 测试步骤：
  1. 点击"添加任务"按钮
  2. 填写任务信息
  3. 点击"确定"保存
  4. 验证任务出现在列表中
- 期望结果：新任务成功添加到列表

### TC004: 标记完成功能
- 前置条件：列表中存在未完成任务
- 测试步骤：
  1. 点击任务前的复选框
  2. 验证任务状态变为已完成
  3. 验证任务样式更新
- 期望结果：任务状态正确更新

## 3. 端到端测试

### TC005: 完整工作流
- 测试步骤：
  1. 添加新任务
  2. 编辑任务信息
  3. 设置优先级和截止时间
  4. 标记任务完成
  5. 使用筛选功能
- 期望结果：整个流程顺畅无错误

2. 执行测试

测试执行分为几个层次：

单元测试：

bash

# 后端单元测试
pytest tests/test_todos.py -v

# 前端单元测试  
npm run test:unit

集成测试：

bash

# API 集成测试
pytest tests/test_integration.py -v

# 前端集成测试
npm run test:e2e

端到端测试：

bash

# 启动完整环境
docker-compose up -d

# 运行 E2E 测试
npm run test:e2e:full

3. 测试结果分析

测试完成后会生成报告：

markdown

# 测试执行报告

## 测试概况
- 总用例：25 个
- 通过：22 个  
- 失败：3 个
- 跳过：0 个
- 成功率：88%

## 失败用例详情

### TC007: 批量删除功能
- 错误信息：API 返回 500 错误
- 失败原因：批量删除接口未正确处理空数组
- 修复建议：在 delete_todos 函数中添加参数验证

### TC012: 移动端适配
- 错误信息：按钮点击区域过小
- 失败原因：CSS 媒体查询未生效
- 修复建议：检查响应式样式配置

### TC018: 数据持久化
- 错误信息：重启后数据丢失
- 失败原因：SQLite 数据库文件路径配置错误
- 修复建议：修正 DATABASE_URL 环境变量

4. 修复失败测试

对于失败的测试，需要：

创建修复任务 — 将测试失败转化为具体的修复任务
分配给相应角色 — Backend/Frontend/DevOps
重新执行测试 — 修复完成后重新运行测试
确认通过 — 所有测试通过后推进到下一阶段

修复任务示例：

任务：修复批量删除 API 错误
描述：批量删除接口在接收空数组时返回 500 错误，需要添加参数验证
输入：测试失败报告、相关代码文件
输出：修复后的 API 代码、更新的测试用例
分配：Backend
优先级：高

阶段 7：部署交付

部署准备

1. 代码整理

确保所有代码都已正确提交：

bash

# 检查 Git 状态
git status

# 查看提交历史
git log --oneline

# 检查是否有未提交的变更
git diff

2. 文档完善

自动生成项目文档：

README.md — 项目介绍和快速开始
API 文档 — 接口说明和示例
部署文档 — 环境配置和部署步骤
用户手册 — 功能使用说明

3. 部署配置

DevOps 角色会生成部署相关文件：

Dockerfile：

dockerfile

# 后端 Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

docker-compose.yml：

yaml

version: '3.8'

services:
  backend:
    build: ./backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=sqlite:///./todos.db
    volumes:
      - ./data:/app/data

  frontend:
    build: ./frontend
    ports:
      - "3000:80"
    depends_on:
      - backend

部署验证

1. 本地部署测试

bash

# 构建并启动服务
docker-compose up --build

# 验证服务状态
curl http://localhost:8000/health
curl http://localhost:3000

2. 功能回归测试

部署完成后进行完整的功能验证：

markdown

# 部署验证清单

## 基础功能
- [ ] 应用正常启动
- [ ] 数据库连接正常
- [ ] API 接口响应正常
- [ ] 前端页面加载正常

## 核心功能
- [ ] 添加待办事项
- [ ] 编辑待办事项
- [ ] 删除待办事项
- [ ] 标记完成状态
- [ ] 筛选和排序

## 性能指标
- [ ] 页面加载时间 < 2 秒
- [ ] API 响应时间 < 500ms
- [ ] 支持 100+ 待办事项

## 兼容性
- [ ] Chrome 浏览器正常
- [ ] Firefox 浏览器正常
- [ ] 移动端适配正常

创建项目 Checkpoint

交付前建议创建项目快照，用于：

演示回归 — 随时恢复到稳定版本进行演示
版本对比 — 对比不同版本的差异
风险控制 — 出问题时快速回滚

1. 创建 Checkpoint

在项目页面点击「创建 Checkpoint」：

Checkpoint 名称：v1.0-release
描述：待办事项管理应用首个完整版本
备份模式：完整备份（包含源码）

2. Checkpoint 内容

系统会备份：

项目数据 — 所有阶段文档、任务记录
代码仓库 — 完整的 Git 历史
配置信息 — 模型配置、角色分配
执行日志 — Agent 执行记录

3. 恢复使用

需要时可以：

查看历史版本 — 浏览之前的 Checkpoint
恢复到指定版本 — 一键恢复项目状态
对比版本差异 — 查看两个版本间的变化

交付文档

最终交付包含：

📦 交付包结构
├── 📁 source-code/          # 源代码
│   ├── backend/            # 后端代码
│   ├── frontend/           # 前端代码
│   └── docker-compose.yml  # 部署配置
├── 📁 documentation/        # 项目文档
│   ├── README.md           # 项目说明
│   ├── API.md              # API 文档
│   ├── DEPLOYMENT.md       # 部署指南
│   └── USER_MANUAL.md      # 用户手册
├── 📁 tests/               # 测试相关
│   ├── test-cases.md       # 测试用例
│   ├── test-report.html    # 测试报告
│   └── coverage-report/    # 覆盖率报告
└── 📁 deployment/          # 部署文件
    ├── Dockerfile          # 容器配置
    ├── nginx.conf          # Web 服务器配置
    └── init.sql            # 数据库初始化

完成项目检查清单

✅ 编码质量

[ ] 所有任务都已完成并通过审核
[ ] 代码结构清晰，遵循最佳实践
[ ] 没有明显的 Bug 和安全问题
[ ] Git 提交历史清晰，消息规范

✅ 测试覆盖

[ ] 单元测试覆盖率 > 80%
[ ] 集成测试覆盖主要功能
[ ] 端到端测试验证用户流程
[ ] 所有测试用例都通过

✅ 部署就绪

[ ] Docker 配置正确，可一键部署
[ ] 环境变量配置完整
[ ] 数据库初始化脚本可用
[ ] 服务健康检查正常

✅ 文档完整

[ ] README 包含完整的使用说明
[ ] API 文档详细准确
[ ] 部署文档步骤清晰
[ ] 用户手册易于理解

✅ 功能验证

[ ] 所有核心功能正常工作
[ ] 用户界面友好易用
[ ] 性能指标符合要求
[ ] 兼容性测试通过

常见问题解决

Q: Agent 编码速度很慢？

A: 可能原因：

模型 API 响应慢 → 检查网络或换供应商
任务上下文太复杂 → 简化任务描述
并发任务太多 → 控制同时执行的任务数量

Q: 生成的代码质量不高？

A: 改进方法：

为关键角色分配更强的模型
在任务描述中明确代码规范要求
通过审核反馈持续改进 AI 输出

Q: 测试失败率很高？

A: 分析原因：

需求理解偏差 → 回到前置阶段完善文档
技术方案不合理 → 调整架构设计
任务拆分不当 → 重新分解任务

Q: 部署后功能异常？

A: 排查步骤：

检查环境变量配置
查看服务启动日志
验证数据库连接
测试 API 接口可用性

本章输出

完成本章后，你应该：

[x] 体验了完整的 AI 编码流程
[x] 学会了如何审核和指导 AI 产出
[x] 掌握了测试和部署的验证方法
[x] 获得了一个可用的待办事项管理应用
[x] 创建了项目的 Checkpoint 备份

恭喜！你已经完成了第一个 VAI TEAM 项目的完整开发流程。现在你可以将这个经验应用到更复杂的实际项目中。

阶段 5-7：从编码到交付 ​

阶段 5：编码实现 ​

进入编码阶段 ​

任务执行流程 ​

1. 任务自动分配 ​

2. Agent 编码过程 ​

3. 查看代码产出 ​

审核代码产出 ​

1. 审核要点 ​

2. 审核操作 ​

3. 补充上下文 ​

处理任务失败 ​

常见失败原因 ​

失败处理流程 ​

并行执行监控 ​

阶段 6：集成测试 ​

测试阶段目标 ​

测试执行流程 ​

1. 自动生成测试用例 ​

2. 执行测试 ​

3. 测试结果分析 ​

4. 修复失败测试 ​

阶段 7：部署交付 ​

部署准备 ​

1. 代码整理 ​

2. 文档完善 ​

3. 部署配置 ​

部署验证 ​

1. 本地部署测试 ​

2. 功能回归测试 ​

创建项目 Checkpoint ​

1. 创建 Checkpoint ​

2. Checkpoint 内容 ​

3. 恢复使用 ​

交付文档 ​

完成项目检查清单 ​

✅ 编码质量 ​

✅ 测试覆盖 ​

✅ 部署就绪 ​

✅ 文档完整 ​

✅ 功能验证 ​

常见问题解决 ​

本章输出 ​

阶段 5-7：从编码到交付

阶段 5：编码实现

进入编码阶段

任务执行流程

1. 任务自动分配

2. Agent 编码过程

3. 查看代码产出

审核代码产出

1. 审核要点

2. 审核操作

3. 补充上下文

处理任务失败

常见失败原因

失败处理流程

并行执行监控

阶段 6：集成测试

测试阶段目标

测试执行流程

1. 自动生成测试用例

2. 执行测试

3. 测试结果分析

4. 修复失败测试

阶段 7：部署交付

部署准备

1. 代码整理

2. 文档完善

3. 部署配置

部署验证

1. 本地部署测试

2. 功能回归测试

创建项目 Checkpoint

1. 创建 Checkpoint

2. Checkpoint 内容

3. 恢复使用

交付文档

完成项目检查清单

✅ 编码质量

✅ 测试覆盖

✅ 部署就绪

✅ 文档完整

✅ 功能验证

常见问题解决

本章输出