Security: - 添加 API 认证中间件 (PLATFORM_API_TOKEN Bearer Token) - SSRF 防护: 校验 git URL scheme + 过滤内网 IP - 路径遍历修复: module 参数添加 is_relative_to 校验 - 异常信息泄露修复: 统一错误处理不返回内部信息 - API Key 不持久化到数据库 - 硬编码 SSH Key 移至环境变量 - CORS 生产环境校验 Rate Limiting: - 新增内存滑动窗口速率限制 (6个POST端点) Performance: - ThreadPoolExecutor(max_workers=4) 限制并发 - 任务超时 _enforce_proc_timeout (默认3600s) - JSON 原子写入 tempfile+os.replace - 日志轮转 RotatingFileHandler - httpx 连接池配置 - 随机名改用 uuid4 - 前端 Error Boundary - 前端统一 EventSource 使用 Docs: - 更新 .env.example, CHANGELOG, API.md, CONFIG.md, AGENTS.md - .gitignore 添加 .venv/ 和 backend/db.json
6.8 KiB
TestAgent API 文档
Base URL: http://localhost:5002
认证
当设置了 PLATFORM_API_TOKEN 环境变量时,所有 API 请求(/api/health 除外)必须在请求头中携带 Bearer Token:
Authorization: Bearer <your-token>
未设置 PLATFORM_API_TOKEN 时认证关闭(仅开发模式推荐)。
速率限制
以下 POST 端点受速率限制保护(按客户端 IP,滑动窗口):
| 端点 | 限制 |
|---|---|
POST /api/repos |
10 次/60 秒 |
POST /api/repos/compare |
10 次/60 秒 |
POST /api/repos/<id>/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/<id>/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
健康检查。
响应:
{
"status": "ok",
"version": "1.0.0",
"tasks_count": 10,
"reports_count": 8,
"repos_count": 0
}
控制台
GET /api/dashboard/stats
获取控制台统计概览。
响应:
{
"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=
获取远程仓库所有分支列表,自动识别最新提交分支。
响应:
{
"branches": [{"name": "dev", "commit": "8c45c92"}, {"name": "main", "commit": "6f6053f"}],
"total": 15,
"default": "main",
"latest": "dev"
}
POST /api/repos/compare
对比两个分支的变更文件列表。
请求体:
{
"url": "https://github.com/user/repo.git",
"base": "main",
"compare": "dev"
}
响应:
{
"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 建模)。
请求体:
{
"url": "https://github.com/user/repo.git",
"branch": "main"
}
注意:
api_key字段仅用于内存传递,不会持久化到数据库。也可通过DEEPSEEK_API_KEY环境变量配置。
DELETE /api/repos/<repo_id>
删除仓库。
POST /api/repos/<repo_id>/analyze
DDD 领域分析。
POST /api/repos/<repo_id>/generate
生成测试用例。
请求体:
{
"test_types": ["smoke", "unit", "integration"]
}
注意:
api_key字段仅用于内存传递,不会持久化到数据库。也可通过DEEPSEEK_API_KEY环境变量配置。
POST /api/repos/<repo_id>/diff
精确回归(仅对 git diff 变更文件生成测试)。
请求体:
{
"against": "HEAD~1"
}
注意:
api_key字段仅用于内存传递,不会持久化到数据库。也可通过DEEPSEEK_API_KEY环境变量配置。
POST /api/repos/<repo_id>/full
全流程(扫描 + 分析 + 生成)。
POST /api/repos/check-ui
UI 变更检查(克隆前端仓库,比对 Robogo 脚本中的 UI 选择器)。
请求体:
{
"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 修复 + 覆盖原文件 + 重新测试验证)。
请求体:
{
"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
创建并启动任务。
请求体:
{
"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
获取已有用例模块列表。
响应:
{
"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 标记列表。
响应:
["smoke", "e2e", "api", "ui", "flow", "data_space", "dataspace", ...]
静态资源
GET /artifacts/screenshots/
获取测试截图。
GET /
SPA 前端(所有非 API 路径自动 fallback 到 index.html)。