AI 测试工具平台 — 设计思路
项目链接：https://github.com/ywq2019/ai_test_agent
一、核心出发点：让测试人员少写代码
传统测试平台门槛高——测试工程师需要掌握编程、维护脚本框架、理解底层驱动。这个项目的起点是反向思考：能让 AI 做的事，人不做。
| 环节 | 传统做法 | 本平台做法 |
|---|---|---|
| 用例设计 | 人工逐条编写 | 上传文档 → AI 分段生成 |
| 需求变更 | 人工逐条比对、手动改用例 | 上传新文档 → AI Diff + 用例级增量更新 |
| 脚本编写 | Python/JS 脚本 |
{{fn(arg)}} 占位符，零代码 |
| 报告分析 | 人工逐条看日志 | 执行完自动调 LLM 输出修复建议 |
| 覆盖度评估 | 凭经验判断 | AI 分析盲区，自动追加补充用例 |
二、整体架构
Vue 3 前端
│ HTTP / WebSocket
FastAPI 路由层（auth / webui / ai_cases / api_test / workspaces）
│
┌───┴─────────────┐
UI 自动化引擎 接口自动化引擎
Playwright 驱动 httpx 异步驱动
└───────┬─────────────┘
│
LangGraph Agent（可选，配置了大模型才初始化）
│
共用基础设施（WebSocket / DB / JWT / AI）
两类引擎职责分离：UI 测试依赖浏览器状态天然串行，接口测试是纯 HTTP 天然并发，强行统一会相互污染。LangGraph 作为可选层，核心测试功能不依赖 Agent。
三、AI 集成：统一接口 + Prompt 配置化
所有 AI 调用统一读取「大模型配置」页，自动判断 Anthropic / OpenAI 格式，切换模型即切换全部 AI 功能。
Prompt 统一提取到 skills/prompts/*.yaml，懒加载 + LRU 缓存，修改 YAML 后无需重启即可生效，调优效果不改代码。
四、需求变更增量更新：用例级精准合并
需求变更后重新生成的最大问题是旧用例全量覆盖。平台的解法：
AI Diff 分析（模块级）：把旧用例模块名注入 Prompt，强制 AI 输出 changed / added / removed / unchanged 四分类，漏分的旧模块用关键词搜索二次判断。
用例级保守合并：默认保留所有旧用例，LLM 只找「功能点完全消失」的用例标为 deprecated，新场景追加新用例。deprecated 超过 50% 自动重置（防 LLM 过激）。
版本追踪：每次更新创建新版本（parent_id 指向旧版），废弃用例前端默认隐藏，可开关查看。
五、废弃与禁用：两个概念分开存储
| 字段 | 语义 | 执行影响 | 覆盖率影响 |
|---|---|---|---|
enabled |
用户手动启用/禁用 | 由前端传 case_ids 控制 | 计入覆盖率 |
deprecated |
需求变更自动废弃 | 强制跳过 | 排除 |
禁用是「有效的测试设计，暂时不跑」；废弃是「真正无效」，必须分开存储。
六、需求 - 用例追踪矩阵
覆盖度分析只能回答「用例写得好不好」，无法回答「有没有漏测」。追踪矩阵从需求出发建立双向映射：
- 需求提取：AI 从文档中提取结构化需求条目（ID / 模块 / 标题 / 优先级）
- 映射建立：AI 对每条用例判断覆盖了哪些需求 ID，分批处理，进度实时推送
-
矩阵计算：
covered（≥2 条）/insufficient（1 条）/uncovered（0 条）
对覆盖不足的需求，AI 从 8 个测试维度分析缺口，用户勾选后生成补充用例，矩阵实时刷新。所有数据存在 AICaseFile 的 JSON 列，不新建表，向后兼容。
七、接口测试的两个 AI 增强
代码驱动用例生成：直接粘贴接口实现代码（Python/Java/Go/Node.js/PHP），AI 解析入参、边界、异常路径，生成覆盖 P0/P1/P2 的用例，解决 Swagger 滞后问题。
代码可行性分析：同时提供需求文档和代码，AI 识别 missing（未实现）/ mismatch（行为不一致）/ extra（隐式限制）/ risk（潜在风险）四类偏差，自动生成差异验证用例，一键保存到用例库。
八、变量池：打通执行链路
全局变量池 {{gvar:token}} → 跨项目持久化，scope=global 时写入
局部变量 {{var:user_id}} → 当次执行链内存共享，scope=local（默认）
占位符函数 {{uuid()}} → 执行时动态计算
变量提取时 scope 字段决定写入层级。测试计划中所有步骤共享同一 var_store，实现真正的端到端链路测试。自定义脚本函数存入 DB，执行时动态编译，用 {{sign(key, data)}} 调用，不接触运行时。
九、网络层可配置：面向真实测试环境
代理：HTTP / HTTPS / SOCKS5，留空直连。
Hosts 映射：自定义 httpx.AsyncHTTPTransport 子类拦截连接请求，域名重定向到指定 IP，保留原域名作为 Host 头，不改系统 hosts，应用内隔离。
优先级：测试计划级 > 项目级，不冲突的条目合并生效。
十、实时推送：全程 WebSocket，不轮询
所有耗时任务（用例生成、测试执行、压测、AI 分析）HTTP 请求立即返回，后台异步执行，WebSocket 推送进度。服务端每 30 秒心跳保活，超 40 秒无响应主动清理僵尸连接。断线兜底：任务结果写库，前端轮询状态恢复进度。
十一、鉴权与用户管理
JWT 中间件统一验证所有 /api/ 请求，白名单（登录、健康检查、下载、CI/CD Webhook）直接放行。密码 bcrypt 哈希，Token 有效期 7 天。
前端 axios 拦截器 401 后用 router.replace 软跳转（非 window.location.href 硬跳转），避免页面重载触发初始化请求死循环；App.vue 在登录页时跳过所有初始化请求。
十二、工作空间与多用户数据隔离
工作空间作为顶层隔离单元，AI 用例、WebUI 任务、接口项目、测试计划、全局变量均挂在工作空间下。成员 role 分 owner（管理成员）/ member（读写数据），admin 可跨空间查看全部。升级时旧数据自动归入「默认空间」，无感知兼容。
十三、数据库：向前兼容 + asyncpg 事务隔离
启动时 create_all 自动建表，新字段用 ALTER TABLE ... ADD COLUMN 兼容旧库。SQLite（本机开发）/ PostgreSQL（Docker 生产）双兼容，只改 DATABASE_URL，代码零改动。
关键设计：asyncpg 遇到任何错误会把当前事务标记为 aborted，后续语句被 PostgreSQL 静默拒绝。因此每条 DDL 必须独立 engine.begin() 事务，任何一条失败只影响自己，不连累建表操作。
十四、RAG 知识库：分段检索替代硬截断
文档按 900 字/段（200 字重叠）分段入库，生成时按模块名检索最相关段落（pgvector 余弦相似度 / SQLite 降级关键词匹配）替代截取前 N 字，确保超长文档后半部分不被遗漏。DeepSeek / Anthropic 不支持 embedding 时自动降级，不中断流程。
十五、稳定性保障
截断 JSON 修复：LLM 被 max_tokens 截断时，逐字符扫描找最后一个完整元素，补齐闭合括号，保留已生成内容。
WebUI 三级兜底：元素 > 3 → 正常分析；元素 ≤ 3 → 文档驱动；无文档 → 页面正文兜底。配合分屏自动滚动（最多 40 屏）抓取懒加载内容。
中文 PDF：pymupdf 优先（直接读 Unicode 映射），PyPDF2 降级，避免乱码导致 LLM 理解失败。
Anthropic 代理兼容：防御性解析 content 字段，过滤 thinking block，多备选字段兜底，兼容各类中转代理格式。
附：技术选型
| 问题 | 选型 | 原因 |
|---|---|---|
| 异步服务 | FastAPI + Uvicorn | 原生 async，自动 API 文档 |
| Agent 编排 | LangGraph + LangChain | 工作流状态机 + 工具注册 |
| 数据库 | SQLite / PostgreSQL | 开发零配置，生产多并发 |
| 浏览器自动化 | Playwright | async API，networkidle，多浏览器 |
| 接口执行 | httpx | 原生异步，支持自定义 Transport |
| 实时通信 | WebSocket | 服务端主动推送，拒绝轮询 |
| 前端 | Vue 3 + Element Plus | 组件成熟，适合工具类产品 |
| AI 调用 | 统一 HTTP API | 支持任意模型，不依赖本机 CLI |
| 鉴权 | JWT + bcrypt | 中间件统一验证，密码安全存储 |
| Prompt 管理 | YAML + prompt_loader | 与代码解耦，修改无需重启 |
| 限流 | slowapi | 按真实 IP，支持反向代理 |
一句话总结
平台的设计主线是把 AI 能力嵌入测试生命周期的每个环节，用插件化架构保证可扩展，用 WebSocket 保证实时体验，用增量更新避免旧用例丢失，用工作空间支持团队协作，用三层变量池打通接口链路，用 RAG 替代硬截断，用多级兜底保证各种场景下都能生成——整体目标是让测试工程师从重复劳动中解放出来，专注于测试策略和质量判断。