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
8.4 KiB
8.4 KiB
AGENTS.md
本项目为 TestAgent 配置与运行时文档,用于驱动 LLM 自动生成符合 TDD+DDD 规范的测试用例,并提供 Web 可视化管理平台。
运行环境
- Web 平台:Flask 后端(端口 5002)+ React SPA 前端(端口 5174 开发模式,生产构建后由 Flask 托管)
- CLI 模式:Python 3.9+,Click 命令行框架
- 语言模型:DeepSeek Chat(默认)/ OpenAI / Anthropic(通过兼容 API 接入)
- 已有用例:集成 unified-test-platform 的
tests/目录,可浏览和运行 800+ 存量测试
启动方式
Web 平台
# 启动后端(托管前端 SPA)
python -m backend
# 访问 http://localhost:5002
# 前端开发模式(热更新)
cd frontend && pnpm dev
# 访问 http://localhost:5174,API 代理到 5002
# 前端构建(生产)
cd frontend && pnpm build
# 产物输出到 frontend/dist/,由 Flask 直接托管
CLI 命令行
# 完整扫描生成
python main.py run -r <git-url> -k <api-key>
# 精确回归
python main.py diff -r <git-url> -k <api-key> -a HEAD~3
# 领域分析(不调 LLM,免费)
python main.py analyze -r <git-url> -k <api-key>
Web 平台功能
控制台 (/dashboard)
- 统计概览:仓库数、任务数、报告数、已有用例模块数
- 快速操作:跳转扫描仓库 / 运行已有用例 / 查看任务
- 能力展示:8 项平台能力卡片
仓库管理 (/repos)
- 添加 Git 仓库 → 自动扫描(clone/pull + AST 分析 + DDD 建模)
- 扫描完成后可执行:DDD 分析 / 生成测试 / 精确回归 / 全流程一键执行
- 实时 SSE 日志流显示扫描/分析/生成进度
- 展示限界上下文列表
任务管理 (/tasks)
- 任务列表:名称、类型、状态(运行中/通过/失败/等待中)、创建时间
- 实时 SSE 日志流(点击「日志」按钮)
- 运行中任务可停止,已完成任务可删除
- 5 秒轮询自动刷新状态
测试报告 (/reports)
- 报告列表:通过/失败标识、通过数/失败数、完成时间
- 详情面板:总运行/通过/失败/耗时统计
- 运行日志回放
- 失败截图查看
已有用例 (/existing)
- 左侧:22 个测试模块列表(来自 unified-test-platform)
- 中间:19 个测试标记(smoke/e2e/api/ui/flow/各模块标记)
- 右侧:运行配置(有头/无头模式)+ 运行按钮
- 选中模块后显示该模块的具体测试文件
- 实时 SSE 日志流显示 pytest 输出
知识来源
Agent 知识全部来自 skills/ 目录下的 SKILL.md 文件:
skills/tdd-methodology/— TDD 红-绿-重构循环、FIRST 原则、AAA 模式、测试替身skills/ddd-patterns/— 限界上下文、聚合根、实体、值对象、领域服务、仓储模式skills/test-framework/— 测试分层(冒烟/集成/系统/回归)、指标门禁、CI/CD 流水线skills/language-patterns/— Python/TypeScript/Go 多语言测试模式
如需更新知识:直接编辑对应的 SKILL.md 文件,无需重启。
工具
Agent 通过 plugins/ 目录加载工具:
plugins/pylint_analyzer/— 代码静态分析(行长度、TODO 标记、print 检测、复杂度评估)plugins/test_runner/— 测试运行器(执行 pytest、解析结果、指标门禁检查)
人格定义
Agent 人格定义在 SOUL.md 中,核心角色:
- 身份:资深测试架构师,精通 TDD + DDD
- 输出:可直接运行的 pytest 测试代码,无 TODO 或占位符
- 组织:按 DDD 限界上下文组织测试目录,而非按文件结构
- 隔离:领域层测试独立于基础设施层,领域层纯 Mock
- 命名:
test_should_<预期行为>_when_<条件>模式 - 模式:AAA(Arrange-Act-Assert)
API Key 配置
# 方式1:Web 平台输入框(仓库管理/任务创建页面)
# 方式2:命令行传参
python main.py run -r <git-url> -k sk-xxx
# 方式3:环境变量
export DEEPSEEK_API_KEY=sk-xxx
python main.py run -r <git-url>
# 方式4:交互式输入
python main.py run -r <git-url>
# 请输入 API Key: ****
# 方式5:.env 文件
echo "DEEPSEEK_API_KEY=sk-xxx" > .env
python main.py run -r <git-url>
安全说明:API Key 仅在内存中传递,不会持久化到
platform_db.json。任务创建后 API Key 字段从数据库记录中移除。
配置
在 config.yaml 中配置:
agent:
model: deepseek-chat # 模型名称
provider: deepseek # deepseek / openai / anthropic
base_url: https://api.deepseek.com
temperature: 0.3 # 生成温度(0=确定,1=创意)
max_tokens: 8192
test_generation:
output_dir: tests # 测试输出目录
metrics_gate:
min_coverage: 60
min_pass_rate: 95
安全配置
环境变量
| 变量 | 说明 | 默认值 |
|---|---|---|
PLATFORM_API_TOKEN |
API 认证 Token(留空则关闭认证) | - |
FLASK_ENV |
Flask 运行环境(development/production) | development |
CORS_ORIGINS |
CORS 允许来源(逗号分隔) | http://localhost:5174,... |
TASK_TIMEOUT_SECONDS |
单任务最大运行时间(秒) | 3600 |
SSH_PUBLIC_KEY |
SSH 公钥(原硬编码迁移) | - |
DM_SSH_KEY |
开发机 SSH Key(原硬编码迁移) | - |
生产部署
export PLATFORM_API_TOKEN="your-secret-token"
export FLASK_ENV=production
export CORS_ORIGINS="https://your-domain.com"
export TASK_TIMEOUT_SECONDS=3600
API 路由
认证:设置
PLATFORM_API_TOKEN环境变量后,所有 API 请求(/api/health豁免)需携带Authorization: Bearer <token>请求头。未设置时认证关闭。速率限制:关键 POST 端点按客户端 IP 限制(5-10 次/60 秒)。
SSRF 防护:所有接受 Git URL 的端点仅允许 HTTPS 协议、拒绝内网 IP。
| 路由 | 方法 | 认证 | 速率限制 | 说明 |
|---|---|---|---|---|
/api/health |
GET | 豁免 | - | 健康检查 |
/api/repos |
GET | ✅ | - | 仓库列表 |
/api/repos |
POST | ✅ | 10/60s | 扫描新仓库 |
/api/repos/branches |
GET | ✅ | - | 远程分支列表 |
/api/repos/compare |
POST | ✅ | 10/60s | 分支对比 |
/api/repos/check-ui |
POST | ✅ | 5/60s | UI 变更检查 |
/api/repos/fix-ui |
POST | ✅ | 5/60s | UI 自动修复 |
/api/repos/<id>/analyze |
POST | ✅ | - | DDD 领域分析 |
/api/repos/<id>/generate |
POST | ✅ | - | 生成测试用例 |
/api/repos/<id>/diff |
POST | ✅ | - | 精确回归 |
/api/repos/<id>/full |
POST | ✅ | 5/60s | 全流程(扫描+分析+生成) |
/api/tasks |
GET | ✅ | - | 任务列表 |
/api/tasks |
POST | ✅ | 10/60s | 创建任务 |
/api/tasks/<id>/stop |
POST | ✅ | - | 停止任务 |
/api/tasks/<id>/logs |
GET | ✅ | - | SSE 日志流 |
/api/reports |
GET | ✅ | - | 报告列表 |
/api/reports/<id> |
GET | ✅ | - | 报告详情 |
/api/existing-tests/modules |
GET | ✅ | - | 已有用例模块列表 |
/api/existing-tests/markers |
GET | ✅ | - | 已有用例标记列表 |
/api/dashboard/stats |
GET | ✅ | - | 控制台统计 |
生成规则
- 严格遵循 SOUL.md 定义的测试架构师角色
- 所有测试按 DDD 限界上下文组织,而非按源文件一对一映射
- 领域层测试使用 Mock 隔离所有基础设施依赖
- 基础设施层测试可以使用真实依赖
- 每个测试函数必须有 docstring 描述测试意图
- 使用 pytest 标记标注测试类型(smoke/integration/regression/e2e)
- 自动注入指标门禁断言(覆盖率 >= 60%,通过率 >= 95%)
- 不生成不安全的测试代码(eval、exec、硬编码密钥)
- 只生成测试代码,不修改被测源代码
- Session 领域测试独立成套件,覆盖创建/持久化/上下文携带/清除/销毁
数据持久化
- 数据库:
platform_db.json(项目根目录) - 任务日志:
platform_reports/<task_id>.json - 生成的测试:
output/<repo_id>/ - 截图:
platform_artifacts/screenshots/ - 前端构建产物:
frontend/dist/ - 自动清理:任务超过 100 个时自动清除最旧 50 个及其关联资产
- 原子写入:
platform_db.json使用tempfile + os.replace原子写入,防止崩溃时损坏 - 线程池:
ThreadPoolExecutor(max_workers=4)限制并发任务 - 任务超时:默认 3600 秒自动 kill 超时进程
- 日志轮转:
RotatingFileHandler(maxBytes=10MB, backupCount=5)