TestPilot —— AI 测试用例智能生成平台

滴水湖全球 OPC 人工智能挑战赛 · S3 全球青年培育赛 · Wave 3 提交物

从一份 PRD 需求文档出发，AI 自动完成需求解析、覆盖建模、用例生成、质量审核，人工确认后导出结构化测试用例包。实际处理耗时和生成规模取决于输入材料、所选模型、网络与运行配置；仓库不把单次演示结果表述为普遍效率结论。

---

快速开始

前置条件

• Python >= 3.11
• Node.js >= 20
• DeepSeek API Key（申请：https://platform.deepseek.com/api_keys）

后端

cd backend
uv sync
cp .env.example .env        # 编辑 .env 填入 DEEPSEEK_API_KEY 和随机 JWT_SECRET

前端

cd frontend
npm ci
npm run dev -- --host

---

部署启动

1. 后端启动

cd backend
uv run uvicorn app.main:app --host 0.0.0.0 --port 8004 --workers 1

--workers 1 表示显式使用单 Worker。比赛版的任务状态、SSE 订阅和部分进程内协调只按单 Worker 验证，不支持多个 Worker 之间共享这些运行态；这不是禁止使用 --workers 参数本身。

2. 数据库初始化

应用启动时会通过 SQLModel 自动创建当前版本需要的表，包括首个管理员初始化门闩。app/db/init_rbac.sql 是可选的 SQLite 兼容初始化脚本：它会补建核心表并写入内置角色、菜单和权限元数据；运行时固定权限矩阵不依赖这些元数据决定授权：

cd backend
sqlite3 data/smarttest.db < app/db/init_rbac.sql

该脚本包含：

• 用户表 users、会话表 user_sessions、审计日志表 audit_logs
• 角色表 roles、菜单表 menus、权限表 permissions
• 角色-菜单关联表 role_menus、角色-权限关联表 role_permissions
• 内置 4 个角色：超级管理员 / 管理员 / 测试工程师 / 访客
• 内置 7 个菜单项及其权限关联

3. RBAC 元数据初始化（可选）

如需展示内置角色、菜单和权限元数据，可以通过 API 初始化（需要首个超级管理员 token）：

curl -X POST http://localhost:8004/api/rbac/init \
  -H "Authorization: Bearer <admin_token>"

4. 前端启动

cd frontend
npm run dev -- --host

启动后访问 http://localhost:5190 管理员账号：admin 密码：admin123

5. 首次使用

1. 访问 http://localhost:5190
2. 由于系统无用户，会自动进入注册页面
3. 注册首个用户自动成为超级管理员
4. 如需查看 RBAC 元数据，再调用 /api/rbac/init；比赛版运行时权限采用代码中的固定角色矩阵

⚠️ .env 中必须填写有效的 DEEPSEEK_API_KEY（或 Anthropic Key），并将 JWT_SECRET 替换为至少 32 字符的随机值；未配置时登录令牌会安全地拒绝签发。

---

功能演示（完整流程）

1. 上传需求 — 上传 .docx / .pdf / .md / .txt 格式的 PRD 文档
2. 需求解析 — AI 自动提取结构化需求，识别业务疑点
3. 回答疑点 — 逐条回答 AI 发现的需求疑点，补充业务规则
4. 确认需求 — 审核并确认最终需求，进入用例生成
5. 覆盖项生成 — 在单 Worker 内按覆盖项进行 LangGraph 异步并发调度；生成数量由输入需求与覆盖模型决定
6. 质量审核 — 三维评分（规则+LLM+覆盖），不达标自动修正
7. 人工审核 — 按需求分组、批量接受/标记修改
8. 导出交付 — Excel / Markdown / JSON 三格式导出

详细的比赛交付口径、评审要点、演示脚本和隐私边界见 docs/submission/Wave3_提交说明.md。

固定演示制品的输入到交付追踪见 docs/submission/Evidence_Index.md；交叉评测 issue #2/#3/#4 的本轮处理记录见 docs/submission/CrossReview_Iteration_20260806.md。

W3 评审要点

• 可运行 Agent：FastAPI + LangGraph 工作流可从需求材料运行到审核和交付。
• 可交互 Demo：前端展示实时 Agent 进度，支持需求疑点确认、用例人工审核和版本化导出。
• Skills 集成：6 个独立 Skill 位于 backend/app/skills/，具备类型化输入输出接口。
• 用户价值：把需求理解、测试覆盖设计、用例生成和质量把关串成一个可交付流程。
• 隐私边界：仓库配置和关联代码仓库功能暂时关闭；当前流程只处理用户主动上传的需求材料，不读取业务代码仓库。

---

六大核心技能（Skills）

#	技能	能力	技术亮点
1	需求智能解析	任意长度 PRD → 结构化需求	分 chunk 增量提取 + 重叠去重
2	覆盖模型设计	需求 → 多维度覆盖策略	6 维度 + 7 种测试设计方法
3	用例并发生成	覆盖项 → 高质量测试用例	LangGraph Send 异步并发调度 + 信号量控制
4	三维质量审核	用例质量量化评估	规则层 + LLM 层 + 覆盖层加权评分
5	自愈修正回路	低质量用例自动修正	条件路由 + 最多 2 轮闭环
6	实时进度协作	全流程可视化 + 人工审核断点	SSE 流式推送 + LangGraph interrupt

---

技术架构

前端 (React + Vite, :5190)
    │
    ▼
后端 (FastAPI + LangGraph, :8004)
    │
    ├── 需求解析 → 覆盖设计 → 用例生成 → 质量审核 → 自愈修正 → 导出
    │
    ├── LangGraph 多 Agent 编排（interrupt 支持人工断点）
    ├── SQLite 持久化（任务生命周期 + 版本化交付 + RBAC）
    ├── RBAC 鉴权层（JWT + 角色权限中间件）
    └── LLM 适配层（DeepSeek / Claude 灵活切换）

比赛版使用 --workers 1。 单进程内仍会异步执行任务并通过 LangGraph Send 做 fan-out；多 Worker / 多进程共享运行态不在本次提交范围内。

---

项目结构

├── Skills/                  ← Wave 2/3 提交物（技能文档 + 证据）
│   ├── README.md            ← 技能总览
│   ├── ARCHITECTURE.md      ← 架构说明
│   └── evidence/            ← 截图 + 导出样例 + 运行日志
├── specs/                   ← Wave 1 项目提案 + 示例需求文档
├── backend/
│   ├── app/
│   │   ├── auth/            ← JWT认证、密码哈希、RBAC中间件
│   │   ├── api/             ← FastAPI 路由（auth/rbac/settings/tasks）
│   │   ├── db/              ← 数据库引擎 + 初始化DDL脚本
│   │   ├── skills/          ← 6 个独立 Skill 实现（可脱离 LangGraph 运行）
│   │   ├── graph/           ← LangGraph 图编排（节点 + 状态 + Schema）
│   │   ├── storage/         ← SQLite 持久化（lifecycle + result）
│   │   └── services/        ← 交付视图 + 审核命令
│   ├── tests/               ← 后端测试（82 项回归）
│   └── scripts/smoke_test.py ← 全链路自测
├── frontend/                ← React + Vite 前端
└── docs/                    ← 开发文档与技术设计

---

SDK API 调用

每个 Skill 可脱离 LangGraph，作为独立 SDK 调用：

from app.skills.requirement_analysis import RequirementAnalysisSkill, RequirementAnalysisInput
from app.skills.coverage_design import CoverageDesignSkill, CoverageDesignInput

# 需求解析
analysis = RequirementAnalysisSkill()
out = analysis.run(RequirementAnalysisInput(raw_text="用户登录需求...", project_name="demo"))
print(f"解析出 {len(out.requirements)} 条需求")

# 覆盖设计
coverage = CoverageDesignSkill()
out = coverage.run(CoverageDesignInput(requirements=out.requirements, project_name="demo"))
print(f"生成 {len(out.coverage_model)} 个覆盖项")

---

示例需求文档

内置示例位于 specs/samples/：

• 登录页面需求.docx — 用户登录模块
• 购物车与订单结算需求.docx — 电商购物流程

---

赛段提交记录

赛段	提交物	状态
Wave 1	Specs 项目提案	✅ 已提交
Wave 2	Skills + 可运行原型	✅ 已提交
Wave 3	可交互智能体演示	✅ 当前提交

当前分支验证

验证项	结果
后端回归测试	✅ 82/82 通过
前端 ESLint / TypeScript 检查	✅ 通过
前端生产构建	✅ npm run build 通过
Agent 冒烟测试核心链路	✅ 需求解析 → 覆盖设计 → 用例生成 → 质量审核 → 持久化通过

比赛版采用单工作区模型：所有已登录用户共享任务列表；viewer 只读，tester 与 admin 可创建、审核和导出任务，super_admin 额外管理用户与系统配置。固定权限矩阵是运行时真相源；角色/菜单元数据不提供可影响运行时授权的编辑入口。

首个管理员由数据库单例门闩保护，用户、token/session 与初始化状态在同一事务写入。后续请求会同时校验 JWT、有效 session、用户启用状态和数据库当前角色；登出、禁用或删除用户会撤销或清理相关 session。

输入支持 DOCX、UTF-8 Markdown/TXT 和含文本层的 PDF。当前不支持图片型 PDF/OCR，也不承诺自动修复损坏文件。上传文件保存在 backend/uploads/，任务与审计数据保存在 backend/data/smarttest.db，版本化结果及导出物保存在 backend/outputs/tasks/<task_id>/；运行日志默认写标准输出，除非部署环境显式重定向，否则不构成持久化日志。比赛版没有后台自动清理策略或对外暴露的批量清理能力。

质量结果由规则检查、覆盖检查和 LLM 内容审核组合而成。多层检查能减少单点误判，但相同提示、模型或需求歧义仍可能造成共享盲区，最终交付保留人工审核步骤。本版本不宣称提供多租户隔离或可用的 regenerate 后台链路。