> ⏳ 演示包含 AI 生成测试用例的完整过程，AI 推理需要一定时间，请耐心观看。
---
## 快速部署
### Docker 一键部署（推荐）
**环境要求：** Docker 20.10+（含 Docker Compose v2）
```bash
git clone https://github.com/ywq2019/ai_test_agent.git
cd ai_test_agent
```
编辑 `.env.docker`，修改以下配置（其余保持默认即可）：
| 配置项 | 说明 | 生成命令 |
| --- | --- | --- |
| `SECRET_KEY` | JWT 签名密钥，默认值有安全风险 | `python -c "import secrets; print(secrets.token_hex(32))"` |
| `POSTGRES_PASSWORD` | 数据库密码，同时改 `DATABASE_URL` 里对应的密码 | — |
| `AI_API_KEY` | 大模型 API Key（也可部署后在平台「大模型配置」页填写） | — |
| `AI_API_URL` | 大模型接口地址，默认 DeepSeek，按需替换 | — |
| `AI_MODEL` | 模型名称，与 `AI_API_URL` 对应 | — |
```bash
docker compose up -d
```
访问 `http://服务器IP:4000`，默认账号 `admin / admin123`，**登录后立即修改密码**。
```bash
# 更新
git pull && docker compose up -d --build
# 查看日志
docker compose logs -f app
# 停止
docker compose down
```
> **数据备份**：数据库和文件存储在 Docker 命名卷 `pg_data` / `app_data` 中。迁移时一并复制即可。
>
> ```bash
> docker volume inspect ai_test_agent_pg_data # 查看实际路径
> ```
> **升级说明**：新版本在服务启动时自动执行数据库迁移，直接 `--build` 重启即可，无需手动操作。
> **浏览器说明**：Docker 镜像基于官方 `mcr.microsoft.com/playwright/python:v1.39.0-jammy`，Chromium 已内置，无需额外安装。**本地开发（Windows）** 需手动安装并配置 `PLAYWRIGHT_BROWSERS_PATH` 指向浏览器目录（`.env` 文件已有示例）。
#### 可选：ARQ 任务队列（多 Worker）
默认使用进程内 `BackgroundTasks`，任务重启后丢失。需要持久化任务队列时启用：
```bash
# .env.docker 中取消注释并填写：
REDIS_URL=redis://redis:6379/0
# 启动时加 --profile worker
docker compose --profile worker up -d
# 可独立横向扩容
docker compose --profile worker up -d --scale worker=3
```
#### 可选：Nginx 反向代理
默认不启动，需要域名 / HTTPS 时使用：
```bash
# 编辑 nginx.conf，填写域名，按需取消 SSL 注释
docker compose --profile nginx up -d
```
---
### 本地启动
**环境要求：** Python 3.11+，Node 18+
```bash
# 1. 克隆项目
git clone https://github.com/ywq2019/ai_test_agent.git
cd ai_test_agent
# 2. 配置文件（git clone 不包含 .env）
cp .env.docker .env
# 编辑 .env，至少填写 AI_API_KEY 和 AI_API_URL
# 本地启动使用 SQLite，DATABASE_URL 保持默认即可
# 3. 安装 Python 依赖
pip install -r requirements.txt
# 4. 安装 Playwright 浏览器
playwright install chromium
# Linux 还需要（Mac/Windows 跳过）：
# sudo playwright install-deps chromium
# 5. 构建前端
cd ui && npm install && npm run build && cd ..
# 6. 启动
python main.py # 访问 http://localhost:4000
```
**开发模式（前端热更新）：**
```bash
python main.py # 终端1：后端 4000
cd ui && npm run dev # 终端2：前端 8090（代理到后端）
```
> **本地 vs Docker 数据库**
>
> | | 本地启动 | Docker 部署 |
> | --- | --- | --- |
> | 数据库 | SQLite（项目根目录 `uitest_agent.db`） | PostgreSQL（Docker 卷 `pg_data`） |
> | RAG 向量检索 | 降级为关键词匹配（不支持 pgvector） | pgvector 完整支持 |
> | 数据位置 | 项目根目录下 `.db` 文件 | Docker 命名卷 |
> | 数据互通 | ❌ 两边数据不互通 | — |
>
> 建议生产环境直接使用 Docker 部署，避免后续迁移麻烦。
---
## 核心功能
### AI 用例生成（文档驱动）
上传需求文档，AI 按功能模块并行生成覆盖 6 种测试方法的高质量用例。
| 功能 | 说明 |
| --- | --- |
| **异步后台生成** | 提交后立即返回，完成后 WebSocket 推送，进度实时持久化（断线重连可恢复） |
| 分段并行生成 | 提取模块后并发调用 AI（Semaphore=4），每次输出可控，不超时 |
| 6 种测试方法 | 等价类、边界值、判定表、场景法、错误推测、状态转换 |
| **导出格式** | Markdown / XMind / **Excel**（含优先级色标、测试结果下拉、条件格式） |
| **需求变更增量更新** | AI Diff 分析 → 仅对变更模块做用例级合并，unchanged 模块直接保留 |
| **需求追踪矩阵** | 提取结构化需求条目，建立用例-需求双向映射，生成覆盖率矩阵；一键分析缺口并生成补充用例 |
| **覆盖度优化** | 逐模块分析覆盖盲区（并发 4，单轮 LLM，控制在 120s 内完成） |
| **RAG 知识库** | 文档分段入库（pgvector 向量检索，不支持时降级关键词匹配），生成时检索相关段落 |
| 超大文档支持 | BeautifulSoup 深度清洗 HTML；分批并行提取模块（20000字/批） |
| 截断 JSON 自动修复 | LLM 输出被截断时自动补齐，避免丢失已生成内容 |
### WebUI 自动化
Playwright 驱动浏览器，以「AI 场景规划 → 录制 → 健壮化 → 执行」为主线，用最少的脚本维护成本覆盖完整 UI 测试流程。
| 功能 | 说明 |
| --- | --- |
| **AI 场景规划** | 分析页面元素和需求文档，按核心流程/表单验证/增删改/筛选/异常反馈自动规划录制场景，支持追加/重新规划 |
| **录制 → 场景联动** | 场景规划结果在抽屉中展示，点击「开始录制」直接启动有头浏览器；录制完成自动标记场景为已录制 |
| **录制健壮化** | 保存时自动推导多候选 selector（A/B/C/D 稳定性评级），关键操作后插入 wait + assert，降低执行失败率 |
| **可视化步骤编辑器** | 三 Tab 弹窗（基本信息 / 步骤编辑器 / 前置步骤）；行内编辑 action/selector/value/expected；D 级 selector 标红；点击胶囊展开候选列表一键切换 |
| **前置步骤** | 用例级前置操作（导航/点击/填写），与主步骤共用同一 Page；前置失败则用例直接标为 failed |
| **登录态快照** | 为任务指定登录用例，批量执行前自动运行一次并保存 `storage_state`；后续每条用例直接恢复登录态，零耗时建立会话；支持 TTL 自动刷新 |
| **AI 生成用例** | 配置面板支持自然语言测试重点、指定模块、期望数量；服务端用页面真实 selector 而非 LLM 自造；按优先级硬截断到目标数量 |
| **执行状态** | 用例列表内联显示上次执行结果（通过/失败/错误原因）；实时进度浮层（右下角，非阻塞）展示步骤轨道和用例计数 |
| **多 Selector 回退** | 执行时逐候选探测，找到可用元素即执行，应对动态 id / 框架重构 |
| **多浏览器并行** | 同一批用例同时在 Chromium / Firefox / WebKit 执行，各出一份报告 |
| **元素别名库** | selector 命名为别名，步骤编辑器 `@` 触发补全，变更只改别名库 |
| **变量替换** | `{{变量名}}` 语法从任务环境变量表替换，支持多环境参数化 |
| **控制流** | 步骤编辑器支持插入 `if / else / endif`（条件分支）与 `while / endwhile`（循环轮询），条件 DSL 用 `ast` 白名单安全求值，`max_iter` 防死循环 |
| **pytest 导出** | 一键导出为标准 Python Playwright 测试脚本（zip 包） |
> 📖 步骤编辑详细说明请参阅 [WebUI 步骤编辑操作手册](./docs/webui-step-editor-guide.md)
### 接口自动化
从「项目 → 用例 → 执行 → 报告」全链路打通，支持 Swagger / 代码分析 / 自然语言三种用例来源，内置参数化引擎、前置依赖、CSV 数据驱动、压力测试和 PDF 报告，适用于日常接口回归与 CI/CD 集成。
#### 项目与鉴权管理
| 功能 | 说明 |
| --- | --- |
| 多项目管理 | 每个项目独立配置 Base URL、代理（HTTP/SOCKS5）、Hosts 映射 |
| 多种鉴权方式 | Bearer Token / Basic Auth / API Key，统一在项目级配置，执行时自动注入 |
| **多环境支持** | 每个项目可配置多套环境（测试/预发布/生产），执行时下拉切换 Base URL |
#### AI 用例生成
| 输入源 | 说明 |
| --- | --- |
| Swagger / OpenAPI | 解析接口定义，真实探测获取响应结构，自动生成正常 / 异常 / 边界用例 |
| Curl 命令 | 粘贴 curl，自动解析 method/URL/headers/body，请求体精确注入生成用例（含业务 headers），场景数量按接口复杂度动态规划，用例按「模块-场景」功能命名 |
| 自然语言描述 | 描述接口行为，AI 推理补全请求体、断言与边界 |
| 代码（Python/Java/Go/Node/PHP） | 静态分析业务代码，提取接口调用生成用例 |
| Postman/HAR 导入 | 解析 Postman Collection 或 HAR 文件，直接导入为用例 |
> AI 生成链路优化：真实接口探测 → JSON Mode 强制输出 → 容错补全（缺失字段自动填充）→ 模块名校验（防幻觉）→ json_path 自检，确保生成质量。
#### 参数化与前置依赖
| 功能 | 说明 |
| --- | --- |
| 全局变量池 | `{{gvar:name}}` 语法引用跨用例共享变量，支持提取表达式写回 |
| 内置函数 | `{{uuid()}}`、`{{timestamp()}}` 等动态值生成，开箱即用 |
| 自定义脚本函数 | 支持 Python 脚本扩展参数化逻辑，满足复杂签名/加密场景；请求体（JSON/raw）同样支持 `{{脚本函数()}}` 占位符 |
| 前置依赖 | 配置登录前置用例，自动提取 Token；鉴权失败自动重试，无需手动维护 Cookie |
| **CSV 数据驱动** | 上传 CSV 文件，每行数据作为独立参数组执行一次用例，支持多行批量验证 |
#### 执行、压测与报告
| 功能 | 说明 |
| --- | --- |
| 单次执行 | 选择全部或指定用例，实时 WebSocket 推送结果（频道按 project_id 隔离） |
| **报告详情** | 每条用例展示请求/响应完整信息，右键一键复制为 curl 命令（自动拼接 method/headers/body） |
| 压力测试 | 配置并发数 / 持续时长 / 爬坡策略，实时 TPS / P95 / P99，ECharts 图表 |
| PDF 导出 | 含用例明细 + AI 分析，一键归档 |
### Mock 服务
轻量 HTTP Mock，无需依赖真实后端即可联调前端。
| 功能 | 说明 |
| --- | --- |
| 规则匹配 | 按 method + path + 请求参数精准匹配，支持通配符路径 |
| 动态响应 | 配置响应状态码、Headers、Body（支持 JSON / 纯文本） |
| 延迟模拟 | 配置响应延迟，模拟慢接口 |
| 请求记录 | 每次命中记录请求详情，方便排查联调问题 |
### 测试计划
跨项目接口用例编排，共享变量上下文（登录 → 下单 → 查询）。
| 功能 | 说明 |
| --- | --- |
| 步骤编排 | 从任意项目拖入用例，自由排序、启用/禁用 |
| 共享变量 | 所有步骤共享 `var_store`，前步提取后步直接引用 |
| **定时执行** | Cron 表达式定时触发，APScheduler 管理，服务重启后自动恢复 |
| **CI/CD 集成** | Webhook token 触发，支持 Jenkins / GitHub Actions，可选执行完成回调 |
| **报告 PDF 导出** | 含步骤明细 + AI 分析 |
### 接口渗透测试
基于接口自动化项目中已有的用例，对目标 API 发起安全扫描，自动发现 OWASP API Top 10 及常见漏洞，每条漏洞由 AI 生成定制修复建议，并支持 PDF 报告导出。
> ⚠️ **声明**：本功能仅面向已授权的安全测试场景（内部测试、渗透测试授权委托书、CTF）。请勿对未授权目标使用。
12 个扫描模块覆盖：未授权访问、越权（IDOR）、敏感信息泄露、SQL 注入、JWT 安全缺陷、速率限制缺失、批量赋值、CORS 配置错误、HTTP 动词篡改、SSRF、文件上传漏洞、文件下载路径穿越。
### 工作空间
多租户隔离的顶层单元，一个工作空间对应一套独立的测试数据。
| 功能 | 说明 |
| --- | --- |
| 多空间管理 | 每个用户可创建多个工作空间，数据互不干扰 |
| 成员协作 | 邀请成员加入，role 分 owner（管理成员）/ member（读写数据） |
| 跨模块隔离 | AI 用例、WebUI 任务、接口项目、测试计划均按工作空间隔离 |
| **WS 推送隔离** | WebSocket 广播按工作空间路由，不同空间的执行进度互不干扰 |
| admin 穿透 | 系统管理员可跨空间查看所有数据 |
---
## 稳定性与安全
### 多用户并发
| 机制 | 默认值 | 配置项 |
| --- | --- | --- |
| 全局 LLM Semaphore | 6 并发 | `LLM_CONCURRENCY` |
| Semaphore 等待超时 | 60s | `LLM_SEM_TIMEOUT` |
| 后台生成任务上限 | 3 个 | `MAX_ACTIVE_GENERATE` |
| 浏览器 Context 并发上限 | 6 个 | `tools/browser.py: MAX_CONCURRENT` |
| 同一任务重复执行保护 | 409 响应 | 进程内 `_running_tasks` set |
| 同一任务重复录制保护 | 409 响应 | 进程内 `_active_recording_tasks` set |
| 接口 WS 频道隔离 | 按 project_id 路由 | `api_gen_{id}` / `api_exec_{id}` / `api_load_{id}` |
| 接口频率限制 | 生成 5次/分钟，优化/分析 3次/分钟 | slowapi，按真实 IP |
| 反向代理 IP 识别 | `X-Real-IP` → `X-Forwarded-For` → TCP | Nginx 反代时自动识别 |
### 数据隔离
**工作空间级**：AI 用例、WebUI 任务、接口项目、测试计划均挂在工作空间下，成员只能访问所在空间的数据。
**用户级**：未挂载工作空间的数据，普通用户只能看到自己创建的记录；admin 可查看全部。服务启动时自动将历史 NULL 数据归属到默认管理员账号，升级无感知。
**执行隔离**：每条用例独立 Playwright Context，cookie / session / storage 完全隔离，多用户并发执行互不影响。
### 自愈与告警
| 机制 | 说明 |
| --- | --- |
| 重启状态恢复 | 服务重启时自动将卡住的生成任务重置为 failed，推送 WebSocket 通知 |
| 文件自动清理 | 删除记录时清理整条版本链文件；每天 00:05 扫描孤儿文件 |
| 日志定时清理 | 每天 00:05 清理过期日志（默认保留 7 天），`LOG_RETENTION_DAYS` 可调 |
| **定时任务调度** | APScheduler 管理 Cron 定时计划，服务重启自动恢复，不丢任务 |
| Webhook 告警 | ERROR 级日志自动推钉钉/企微/飞书，5 分钟防刷屏；`ALERT_WEBHOOK_URL` 留空则静默 |
### CI/CD 集成
```bash
# 1. 生成 webhook token（需登录）
curl -X PUT "http://your-host:4000/api/v1/test-plans/1/webhook-token" \
-H "Authorization: Bearer 
