TBC/docs/API.md
D-Robotics 637b1026df release: v1.2.0 - 安全加固与性能优化
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
2026-07-16 15:00:05 +08:00

6.8 KiB
Raw Permalink Blame History

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)。