docs: design AI unit test plugin v1
This commit is contained in:
张家训
@@ -0,0 +1,129 @@
|
|||||||
|
# WorkUtils AI 单测生成插件 V1 设计
|
||||||
|
|
||||||
|
## 目标
|
||||||
|
|
||||||
|
为 WorkUtils 项目列表中的 JDK 8、Maven、JUnit 5 项目提供增量单测生成闭环：以分支或 Commit 为基线分析变更，调用已登录的公司 `codefree-cli` 生成候选测试，在隔离 Git worktree 中自动编译、运行和修复测试，以 85% 增量行覆盖率为默认门禁；验证通过后由用户审核，并可把仅包含测试文件的提交集成到指定本地分支。
|
||||||
|
|
||||||
|
## V1 范围
|
||||||
|
|
||||||
|
- 项目来源复用 `data/project_paths.txt`。
|
||||||
|
- 目标项目固定为 JDK 8、Maven、JUnit 5；支持 Maven 多模块。
|
||||||
|
- AI 仅实现 `codefree-cli`，不实现 MixMax3；通过 Provider 接口保留扩展点。
|
||||||
|
- 基线支持本地/远程分支名称与 Commit ID，采用 merge-base 计算 `baseline...HEAD`。
|
||||||
|
- 默认只分析已提交变更，可选包含已暂存及未暂存修改。
|
||||||
|
- 默认增量行覆盖率目标为 85%；分支覆盖率只展示，不作为 V1 门禁。
|
||||||
|
- 最多进行三轮测试修复。
|
||||||
|
- 不修改生产代码、POM、Maven settings，不自动 Fetch、Pull、Push。
|
||||||
|
- 手机 UI 自动化、Gradle、JUnit 4、JDK 17/21 目标项目不在 V1 范围。
|
||||||
|
|
||||||
|
## 用户流程
|
||||||
|
|
||||||
|
1. 检查全局 JDK 8、Maven 和 CodeFree CLI。
|
||||||
|
2. 从现有项目列表选择项目。
|
||||||
|
3. 自动解析 Maven 模块；唯一 `artifactId` 以 `-start` 结尾时自动选中，零个或多个匹配时由用户选择，并按项目记忆选择。
|
||||||
|
4. 输入分支或 Commit 基线，选择是否包含工作区修改。
|
||||||
|
5. 分析整个项目的增量文件、类和可执行行。
|
||||||
|
6. 组合可编辑默认规范、项目专属规范和相关现有测试样例。
|
||||||
|
7. 在临时 worktree 中按生产类调用 CodeFree 生成或补充测试。
|
||||||
|
8. 自动执行测试编译、相关测试、模块测试与 JaCoCo 报告。
|
||||||
|
9. 对可修复的测试错误或未覆盖行最多调用 CodeFree 修复三轮。
|
||||||
|
10. 达到 85% 后展示测试 Diff；用户选择目标本地分支。
|
||||||
|
11. 创建只包含所选模块 `src/test/java/**/*.java` 的候选 Commit，在目标分支隔离环境 Cherry-pick 并二次验证。
|
||||||
|
12. 二次验证成功后更新本地目标分支；任何冲突或分支移动均停止集成。
|
||||||
|
|
||||||
|
## 工具链
|
||||||
|
|
||||||
|
全局配置保存 JDK 8 主目录、Maven 主目录、CodeFree CLI 命令、默认覆盖率目标和最大修复轮次。首次使用自动探测，允许用户覆盖。WorkUtils 自身继续运行在 Java 17；启动目标 Maven 子进程时显式注入目标 JDK 8 的 `JAVA_HOME` 和 `PATH`。
|
||||||
|
|
||||||
|
执行前必须验证：
|
||||||
|
|
||||||
|
- `java -version` 为 Java 8；
|
||||||
|
- `mvn -version` 的 Java Home 指向配置的 JDK 8；
|
||||||
|
- `codefree --version` 可执行；
|
||||||
|
- 一次 `CI + plan + JSON` 的非交互探测成功，或用户明确重试。
|
||||||
|
|
||||||
|
跨平台解析 Windows 的 `mvn.cmd`/`codefree.cmd` 与 macOS/Linux 的 `mvn`/`codefree`。路径以 `Path` 处理，不拼接平台分隔符。
|
||||||
|
|
||||||
|
## 单测规范
|
||||||
|
|
||||||
|
默认质量规范是可编辑模板，首次生成到 `data/ai-test/default-test-spec.md`，支持编辑、恢复默认、导入和导出。项目专属规范保存在 WorkUtils 数据目录 `data/ai-test/projects/<project-id>/test-spec.md`，不写入业务仓库。
|
||||||
|
|
||||||
|
最终提示词优先级为：项目专属规范、可编辑默认规范、现有测试样例风格。文件和仓库安全限制不属于可编辑规范，始终由程序强制：只允许所选模块 `src/test/java` 中的 Java 文件，拒绝绝对路径、路径逃逸、生产源码、POM、脚本和二进制内容。
|
||||||
|
|
||||||
|
相关样例从所选 `-start` 模块及其依赖模块中选取同包、同类后缀和依赖风格最接近的 3 至 5 个测试。
|
||||||
|
|
||||||
|
## 增量与覆盖率
|
||||||
|
|
||||||
|
使用 `git merge-base <baseline> HEAD` 获得共同祖先，再通过零上下文 diff 提取新增和修改行。可选工作区范围合并 staged 与 unstaged diff。删除行、注释和 JaCoCo 未标记的非执行行不进入分母。
|
||||||
|
|
||||||
|
增量行覆盖率为：
|
||||||
|
|
||||||
|
`已覆盖的增量可执行行 / 增量可执行行总数 * 100%`
|
||||||
|
|
||||||
|
JaCoCo 行记录满足 `mi + ci > 0` 时视为可执行，`ci > 0` 时视为覆盖。无增量可执行行显示“不适用”，不判失败。汇总所选模块及其依赖模块的 XML，并以模块、完整类名、源码文件和行号匹配，避免多模块同包同名冲突。
|
||||||
|
|
||||||
|
项目已有 JaCoCo 时复用；否则通过命令行临时调用固定兼容版本，不修改 POM。构建从项目根目录运行 `mvn -pl <module-path> -am ...`。
|
||||||
|
|
||||||
|
## CodeFree 协议
|
||||||
|
|
||||||
|
定义 `TestGenerationProvider`，V1 仅提供 `CodeFreeCliTestGenerationProvider`。调用固定使用：
|
||||||
|
|
||||||
|
```text
|
||||||
|
codefree <prompt> --channel CI --approval-mode plan \
|
||||||
|
--max-session-turns 1 --output-format json
|
||||||
|
```
|
||||||
|
|
||||||
|
不传 `--model`，使用公司 CLI 当前登录配置。解析外层 JSON 最后一个成功的 `type=result` 记录；其 `result` 必须是无 Markdown 围栏的结构化 JSON，包含测试路径、完整内容、目标类、计划覆盖行、场景、假设和警告。
|
||||||
|
|
||||||
|
每次按一个生产类生成，控制上下文大小。完整提示词和业务源码默认不落盘；任务记录只保存路径、行号、Hash、退出码、覆盖率和候选 Commit 等审计信息。
|
||||||
|
|
||||||
|
## Maven 失败与 AI 介入
|
||||||
|
|
||||||
|
WorkUtils 先根据退出码、编译器输出、Surefire XML 和 JaCoCo 结果分类：
|
||||||
|
|
||||||
|
- 测试编译、测试失败、Mockito/测试上下文问题、覆盖率不足：允许 CodeFree 修改候选测试。
|
||||||
|
- JDK/Maven 配置、仓库/网络/认证、POM、依赖下载、磁盘、超时：CodeFree 仅给结构化诊断，不自动执行修复。
|
||||||
|
- 生产代码编译或疑似生产行为缺陷：停止并要求用户审核，不修改生产代码。
|
||||||
|
|
||||||
|
修复轮依次携带精简错误、失败测试、相关源码、当前候选和未覆盖增量行。每轮先 `testCompile`，再运行相关测试、模块测试和 JaCoCo。连续相同输出、不可修复分类、用户取消或达到三轮时停止。
|
||||||
|
|
||||||
|
## 隔离与分支集成
|
||||||
|
|
||||||
|
生成任务在当前 HEAD 的临时 Git worktree 中执行；勾选工作区修改时复制受控 diff。候选测试可以创建新的 `XxxTest`，也可以修改匹配的现有测试，但只发生在临时 worktree。
|
||||||
|
|
||||||
|
验证通过后创建测试专用 Commit。所谓“合并到指定分支”实现为只 Cherry-pick 该测试 Commit，禁止普通 merge 带入来源分支生产代码。目标分支集成前后记录 HEAD；目标分支被其他 worktree 使用、存在未提交修改、验证期间移动或产生冲突时停止，不自动 stash 或选择冲突侧。
|
||||||
|
|
||||||
|
目标分支必须重新执行 Maven 和增量覆盖率验证。失败时目标分支保持原状并保留候选 Commit；成功时只更新本地分支，不推送远程。
|
||||||
|
|
||||||
|
## UI 与任务状态
|
||||||
|
|
||||||
|
插件作为现有 `Plugin + VisualPluginFactory` 的内嵌页面。配置区包含项目、自动/手选生成模块、基线、工作区修改开关、覆盖率目标和规范入口。结果区包含增量代码、生成计划、测试与覆盖率、文件 Diff 四个页签。
|
||||||
|
|
||||||
|
状态机覆盖环境检查、增量分析、等待确认、生成、Maven 验证、覆盖率检查、修复、等待审核、分支集成、二次验证、成功、失败和取消。长任务复用 WorkUtils 现有异步与 Loading 能力，不阻塞 JavaFX 线程。
|
||||||
|
|
||||||
|
任务历史保存到 `data/ai-test/runs/<run-id>/`，记录请求摘要、分析、前后覆盖率、生成文件清单、执行日志和集成结果。V1 不支持异常中断后的断点续跑；运行中退出记为异常中断。
|
||||||
|
|
||||||
|
## 组件边界
|
||||||
|
|
||||||
|
- `AiTestPlugin` / `AiTestWindow`：插件注册与页面交互。
|
||||||
|
- `AiTestWorkflow`：单一状态机编排，不包含命令解析细节。
|
||||||
|
- `ToolchainValidator` / `ProcessExecutor`：全局工具验证与受控进程执行。
|
||||||
|
- `MavenProjectAnalyzer` / `StartModuleSelector`：Maven 模块模型、依赖可达性和生成模块选择。
|
||||||
|
- `GitIncrementAnalyzer` / `TemporaryWorktreeManager` / `TargetBranchIntegrator`：增量、隔离与本地分支集成。
|
||||||
|
- `JacocoXmlParser` / `IncrementalCoverageCalculator`：报告解析和门禁。
|
||||||
|
- `TestGenerationProvider` / `CodeFreeCliTestGenerationProvider` / `CodeFreeResultParser`：AI 协议。
|
||||||
|
- `MavenRunner` / `MavenErrorClassifier` / `SurefireReportParser`：构建、错误分类和测试结果。
|
||||||
|
- `TestSpecificationService` / `GeneratedFileValidator`：规范持久化和生成内容安全边界。
|
||||||
|
|
||||||
|
外部进程依赖通过接口注入，自动化测试使用 Fake，不依赖真实 CodeFree 登录、网络或目标 JDK。Git 集成测试使用临时仓库，覆盖率测试使用固定 XML fixture，UI 测试覆盖可访问状态、按钮门禁、取消和结果展示。
|
||||||
|
|
||||||
|
## 验收标准
|
||||||
|
|
||||||
|
- 唯一 `*-start` 自动选中；无或多个匹配时用户可选并记忆。
|
||||||
|
- 分支/Commit 基线和可选工作区修改能准确生成项目级增量行。
|
||||||
|
- CodeFree 非交互调用只产生受控测试候选，非法 JSON 或路径不落盘。
|
||||||
|
- 可修复 Maven 错误触发最多三轮测试修复；基础设施和生产问题只诊断。
|
||||||
|
- 达到默认 85% 增量行覆盖率且测试通过后才能进入审核。
|
||||||
|
- 审核前原项目不产生修改；取消和失败不污染项目。
|
||||||
|
- 测试专用 Commit 可在指定本地分支二次验证并安全集成，且绝不包含生产代码或 POM。
|
||||||
|
- WorkUtils 全量测试、编译和跨平台路径测试通过，`git diff --check` 无错误。
|
||||||
Reference in New Issue
Block a user