workutils/docs/superpowers/specs/2026-08-04-ai-unit-test-plugin-v1-design.md

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。调用固定使用：

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 无错误。