java-run 为 Maven 与 Gradle 的 Java 源码工作区提供统一启动入口。 它负责选定目标、准备产物、保存启动配置和运行独立 JVM，构建语义由项目使用的构建工具决定。
架构文档 定义运行契约，贡献指南 说明开发、验收与发布流程。
| 能力 | 设计与实现 | 扩展时需要保持的约束 |
|---|---|---|
| 目标与配置 | 单项目、单主类；严格校验项目配置；init 与 run 共用准备和入口选择 |
交互与非交互具有一致的配置和参数含义 |
| 构建适配 | Maven 有效模型、Gradle source set 和任务图统一为 PreparedProject |
构建工具保有依赖裁决权，目标运行类路径保持隔离 |
| Java 启动 | 编译入口扫描、Manifest 类路径、有序 JVM 与应用参数 | 路径编码、参数边界和依赖顺序保持正确 |
| 进程管理 | 异步执行、结构化错误、子环境覆盖和平台进程树清理 | 退出码可追踪，临时资源和受控进程能够清理 |
| 验证与分发 | 回归测试、真实项目夹具、五平台原生 ZIP 验收和两层 SHA-256 校验 | 支持声明与实际执行证据一致，公开产物通过发布门禁 |
这些契约使 Maven / Gradle 的启动差异集中在构建适配层，日常使用保持一套命令。
init 保存可复用的目标和参数，运行时继续由构建工具解析依赖和应用默认值。
支持范围有明确边界：
- Maven reactor 准备通过本地仓库衔接上游产物，会执行 install 生命周期
- Gradle 配置会执行项目构建逻辑，通用启动不复现所有自定义运行任务
- 主类自动发现基于传统 main 和 classpath，不包含 JPMS 或现代 main 语义
- Windows 进程树采用强制终止，不能保证应用关闭钩子执行
验证以用户可观察的行为为准：目标能否启动、配置能否复用、依赖和资源变化能否生效，以及失败后是否保留诊断并清理资源。 测试范围与夹具用途见 夹具说明。
- Check：Ubuntu、macOS、Windows 分别在 JDK 17 和 21 下执行源码回归、二进制编译和完整运行验收
- Release Verify：五个平台分别构建，JDK 21 完整运行验收，JDK 17 解压产物启动验收，再汇总并校验 ZIP
固定环境的验收提供对应系统、体系结构和 JDK 的运行证据。 其他构建工具版本、第三方插件和系统环境需要代表项目补充验证；平台范围见 安装指南。
后续工作按使用证据和收益排序。 每项能力先确定项目样本、运行契约和验收条件，再扩展接口。
优先补充 Wrapper、自定义输出、构建约定和不同 Maven / Gradle 版本的代表项目。 工具链验证同时覆盖构建 JDK 与应用启动 JDK 的选择。
验收条件是样本能够重复运行，失败边界有明确诊断，已有目标隔离与参数契约保持成立。
根据 init 和日常运行反馈，评估命名运行配置、配置编辑辅助和更直接的诊断信息。
新增配置能力需要明确读取位置、覆盖顺序和保存规则，并能直接用于脚本。
验收条件是减少有证据的重复操作，交互与非交互方式能够完成相同的运行目标。
先测量冷准备、温准备、构建工具调用次数和配置成本，再优化 Maven 模型调用或 Gradle 元数据读取。 优先复用构建工具已有的缓存与增量能力。
验收条件是在固定样本中取得可复现的收益，同时保持依赖、资源与配置变更即时生效。
JPMS、现代 main、原生任务集成和其他构建系统分别评估。 每种模式需要实际项目、明确的配置及退出契约，以及对应的执行验证。
若运行信息无法由 PreparedProject 表达，应先确定新的结果契约，再设计适配接口。