用途：用于升级、提升或更新 Gradle wrapper（gradlew、distributionUrl、gradle-wrapper.properties 及项目 Gradle 版本）。先区分用户意图：要求“升级”则执行步骤并验证报告；问“如何升级”则只给出命令，不执行。
主要能力与要点：升级必须运行内置 wrapper 任务，不能手改文件，因为 gradlew、gradlew.bat、gradle-wrapper.jar 是生成物，下次运行会覆盖。范围限于已存在的 wrapper；为无 wrapper 项目添加属于另一项工作（用系统 Gradle 执行 gradle :wrapper）。
使用方式：
- 确认项目根目录有 gradlew，从 gradle/wrapper/gradle-wrapper.properties 读取 distributionUrl，得到当前版本与发行类型（-bin 或 -all）。
- 固定目标版本与校验和。未指定版本时用 curl -s https://services.gradle.org/versions/current 解析最新版本；校验和为发行 URL 加 .sha256，例如 curl -sL https://services.gradle.org/distributions/gradle-9.0.0-bin.zip.sha256，注意用 .sha256 而非 .sha256sum，且需 -L 跟随重定向。
- 先建立基线：./gradlew --console=plain tasks（若启用 configuration-on-demand 则用 tasks --all），保留退出码；失败则停止升级。再用 git status --short gradlew gradlew.bat gradle/wrapper 确认可回滚，非 git 环境需先做快照。
- 运行两次同一命令：./gradlew --console=plain :wrapper --gradle-version=8.14.4 --gradle-distribution-sha256-sum=<sha256>。第一次用旧模板重写文件，第二次下载新版本并用新模板重写。若原为 -all 类型，两次都加 --distribution-type=all。
- 验证：git status 应显示四个文件均被修改，./gradlew --version 报告目标版本，再重跑基线命令。
- 若 wrapper 任务失败或基线失败（构建无法配置），按回滚流程恢复四个文件并停止，不要重试或改构建脚本强行通过。
限制：修复构建不在范围内；配置失败与执行失败（编译错误、测试失败）需区分，后者应保留新 wrapper 并报告。版本格式支持 latest、release-candidate 等，但固定校验和时建议用具体版本；Gradle 9.0 起 properties 中必须写完整 X.Y.Z。