Test_Agent/AGENTS.md
jiawei.chen 6f6053ff51 feat: TestAgent 智能测试平台 v1.0
- CLI + Web 双平台,基于 LLM 的 TDD+DDD 自动化测试生成
- 集成 unified-test-platform 903 个 D-Cloud 用例 + 13 个 Robogo 场景
- Agent 5 步流水线: 扫描 -> DDD -> LLM 生成测试
- 精确回归 + UI 变更检查
- 可视化 HTML 测试报告
- 暗色/亮色主题切换
- 19 个 API 端点 + 6 个 SPA 页面
- 15/15 项 TDD+DDD 合规
2026-07-08 11:27:38 +08:00

182 lines
6.4 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 平台
```bash
# 启动后端(托管前端 SPA)
python -m backend
# 访问 http://localhost:5002
# 前端开发模式(热更新)
cd frontend && pnpm dev
# 访问 http://localhost:5174,API 代理到 5002
# 前端构建(生产)
cd frontend && pnpm build
# 产物输出到 frontend/dist/,由 Flask 直接托管
```
### CLI 命令行
```bash
# 完整扫描生成
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 配置
```bash
# 方式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>
```
## 配置
在 `config.yaml` 中配置:
```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
```
## API 路由
| 路由 | 方法 | 说明 |
|------|------|------|
| `/api/health` | GET | 健康检查 |
| `/api/repos` | GET/POST | 仓库列表 / 扫描新仓库 |
| `/api/repos/<id>/analyze` | POST | DDD 领域分析 |
| `/api/repos/<id>/generate` | POST | 生成测试用例 |
| `/api/repos/<id>/diff` | POST | 精确回归 |
| `/api/repos/<id>/full` | POST | 全流程(扫描+分析+生成) |
| `/api/tasks` | GET/POST | 任务列表 / 创建任务 |
| `/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 | 控制台统计 |
## 生成规则
1. 严格遵循 SOUL.md 定义的测试架构师角色
2. 所有测试按 DDD 限界上下文组织,而非按源文件一对一映射
3. 领域层测试使用 Mock 隔离所有基础设施依赖
4. 基础设施层测试可以使用真实依赖
5. 每个测试函数必须有 docstring 描述测试意图
6. 使用 pytest 标记标注测试类型(smoke/integration/regression/e2e)
7. 自动注入指标门禁断言(覆盖率 >= 60%,通过率 >= 95%)
8. 不生成不安全的测试代码(eval、exec、硬编码密钥)
9. 只生成测试代码,不修改被测源代码
10. Session 领域测试独立成套件,覆盖创建/持久化/上下文携带/清除/销毁
## 数据持久化
- 数据库:`platform_db.json`(项目根目录)
- 任务日志:`platform_reports/<task_id>.json`
- 生成的测试:`output/<repo_id>/`
- 截图:`platform_artifacts/screenshots/`
- 前端构建产物:`frontend/dist/`
- 自动清理:任务超过 100 个时自动清除最旧 50 个及其关联资产