# 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 -k # 精确回归 python main.py diff -r -k -a HEAD~3 # 领域分析(不调 LLM,免费) python main.py analyze -r -k ``` ## 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 -k sk-xxx # 方式3:环境变量 export DEEPSEEK_API_KEY=sk-xxx python main.py run -r # 方式4:交互式输入 python main.py run -r # 请输入 API Key: **** # 方式5:.env 文件 echo "DEEPSEEK_API_KEY=sk-xxx" > .env python main.py run -r ``` ## 配置 在 `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//analyze` | POST | DDD 领域分析 | | `/api/repos//generate` | POST | 生成测试用例 | | `/api/repos//diff` | POST | 精确回归 | | `/api/repos//full` | POST | 全流程(扫描+分析+生成) | | `/api/tasks` | GET/POST | 任务列表 / 创建任务 | | `/api/tasks//stop` | POST | 停止任务 | | `/api/tasks//logs` | GET | SSE 日志流 | | `/api/reports` | GET | 报告列表 | | `/api/reports/` | 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/.json` - 生成的测试:`output//` - 截图:`platform_artifacts/screenshots/` - 前端构建产物:`frontend/dist/` - 自动清理:任务超过 100 个时自动清除最旧 50 个及其关联资产