# TestAgent API 文档 Base URL: `http://localhost:5002` ## 认证 当设置了 `PLATFORM_API_TOKEN` 环境变量时,所有 API 请求(`/api/health` 除外)必须在请求头中携带 Bearer Token: ``` Authorization: Bearer ``` 未设置 `PLATFORM_API_TOKEN` 时认证关闭(仅开发模式推荐)。 ## 速率限制 以下 POST 端点受速率限制保护(按客户端 IP,滑动窗口): | 端点 | 限制 | |------|------| | `POST /api/repos` | 10 次/60 秒 | | `POST /api/repos/compare` | 10 次/60 秒 | | `POST /api/repos//full` | 5 次/60 秒 | | `POST /api/repos/check-ui` | 5 次/60 秒 | | `POST /api/repos/fix-ui` | 5 次/60 秒 | | `POST /api/tasks` | 10 次/60 秒 | 超过限制返回 `429 Too Many Requests`。 ## SSRF 防护 所有接受 Git URL 的端点(`POST /api/repos`、`GET /api/repos/branches`、`POST /api/repos/compare`、`POST /api/repos/check-ui`、`POST /api/repos/fix-ui`、`POST /api/repos//full`)均执行 URL 校验: - 仅允许 HTTPS 协议(拒绝 `git://`、`ssh://`、`git@` 等) - 拒绝内网 IP 地址(10.x / 172.16-31.x / 192.168.x / 169.254.x / 127.x / ::1 / fc00:: / fe80::) --- ## 系统 ### GET /api/health 健康检查。 **响应:** ```json { "status": "ok", "version": "1.0.0", "tasks_count": 10, "reports_count": 8, "repos_count": 0 } ``` --- ## 控制台 ### GET /api/dashboard/stats 获取控制台统计概览。 **响应:** ```json { "tasks": { "total": 10, "pass": 5, "fail": 3, "running": 2, "pass_rate": 50.0 }, "reports": { "total": 8, "pass": 5, "pass_rate": 62.5 }, "repos": { "total": 0 }, "existing_tests": { "modules": 35 } } ``` --- ## 仓库分支 ### GET /api/repos/branches?url= 获取远程仓库所有分支列表,自动识别最新提交分支。 **响应:** ```json { "branches": [{"name": "dev", "commit": "8c45c92"}, {"name": "main", "commit": "6f6053f"}], "total": 15, "default": "main", "latest": "dev" } ``` ### POST /api/repos/compare 对比两个分支的变更文件列表。 **请求体:** ```json { "url": "https://github.com/user/repo.git", "base": "main", "compare": "dev" } ``` **响应:** ```json { "base": "main", "compare": "dev", "changed_files": ["agent/llm_client.py", "backend/app.py"], "total_changes": 2 } ``` --- ## 仓库管理 ### GET /api/repos 获取所有已扫描仓库列表。 ### POST /api/repos 扫描新仓库(clone + AST 分析 + DDD 建模)。 **请求体:** ```json { "url": "https://github.com/user/repo.git", "branch": "main" } ``` > **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。 ### DELETE /api/repos/ 删除仓库。 ### POST /api/repos//analyze DDD 领域分析。 ### POST /api/repos//generate 生成测试用例。 **请求体:** ```json { "test_types": ["smoke", "unit", "integration"] } ``` > **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。 ### POST /api/repos//diff 精确回归(仅对 git diff 变更文件生成测试)。 **请求体:** ```json { "against": "HEAD~1" } ``` > **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。 ### POST /api/repos//full 全流程(扫描 + 分析 + 生成)。 ### POST /api/repos/check-ui UI 变更检查(克隆前端仓库,比对 Robogo 脚本中的 UI 选择器)。 **请求体:** ```json { "url": "https://gitea.d-robotics.cc/d-cloud/d_cloud_artificer_frontend", "branch": "main" } ``` > **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。 ### POST /api/repos/fix-ui UI 自动修复(检测 + 备份 + LLM 修复 + 覆盖原文件 + 重新测试验证)。 **请求体:** ```json { "url": "https://gitea.d-robotics.cc/d-cloud/d_cloud_artificer_frontend", "branch": "main" } ``` > **注意**:`api_key` 字段仅用于内存传递,不会持久化到数据库。也可通过 `DEEPSEEK_API_KEY` 环境变量配置。 **流程:** 克隆前端 → 提取选择器 → 比对 → 备份 → LLM 分批修复 → 覆盖 → 运行验证 --- ## 任务管理 ### GET /api/tasks 获取所有任务列表。支持 `?product=` 过滤。 ### POST /api/tasks 创建并启动任务。 **请求体:** ```json { "name": "任务名称", "task_type": "run_existing", "platform": "dcloud", "module": "data_space", "test_marker": "smoke", "test_file": "tests/data_space/tests/test_data_space_e2e.py", "headless": "false", "env": "PROD", "scope": "all" } ``` > **注意**:`api_key`、`account`、`password` 字段仅用于内存传递,不会持久化到数据库。建议通过 `.env` 环境变量配置凭据。 **任务类型 (task_type):** | 值 | 说明 | |----|------| | `scan` | 扫描仓库 | | `analyze` | DDD 分析 | | `generate` | 生成测试 | | `repo_full` | 全流程 | | `diff` | 精确回归 | | `run_existing` | 运行已有用例 | | `ui_check` | UI 变更检查 | ### DELETE /api/tasks/ 删除任务。 ### POST /api/tasks//stop 停止运行中的任务(发送 SIGKILL)。 ### GET /api/tasks//logs SSE 日志流。实时推送任务执行日志。 **Event 格式:** ``` data: {"ts":"14:21:11","level":"INFO","msg":"执行: pytest ..."} data: {"ts":"14:21:11","level":"SUCCESS","msg":"测试通过"} data: {"level":"PING","msg":"","ts":"--:--:--"} data: {"level":"DONE","msg":"","ts":"--:--:--"} ``` --- ## 测试报告 ### GET /api/reports 获取所有报告列表。 ### GET /api/reports/ 获取报告详情(含日志、结果、截图)。 --- ## 已有用例 ### GET /api/existing-tests/modules 获取已有用例模块列表。 **响应:** ```json { "dcloud": [ { "name": "data_space", "path": "tests/data_space", "test_files": [ { "name": "test_data_space_e2e.py", "tests": [ { "name": "test_dataspace_full_pipeline", "readable": "dataspace full pipeline", "doc": "创建→列表→文件→文件夹→删除" } ], "count": 10 } ], "test_count": 80 } ], "robogo": [ { "name": "robogo", "label": "Robogo 全量巡检", "description": "串行运行全部 13 个场景脚本", "section": "product" } ] } ``` ### GET /api/existing-tests/markers 获取所有 pytest 标记列表。 **响应:** ```json ["smoke", "e2e", "api", "ui", "flow", "data_space", "dataspace", ...] ``` --- ## 静态资源 ### GET /artifacts/screenshots/ 获取测试截图。 ### GET / SPA 前端(所有非 API 路径自动 fallback 到 index.html)。