gradle-run

Gradle 运行

核心原则

将完整的 Gradle 输出视为临时敏感产物。Agent 发起的每条 Gradle 命令都必须通过精简输出封装器运行；绝不要流式输出、使用 tee、粘贴或重新打开完整构建日志。

每次 create、run、status 和 finish 调用都必须是该工具调用中的完整 Shell 命令。即使 Gradle 成功，添加前缀、赋值、条件语句、管道、命令链或后续检查，也会使生命周期证据失效。

流程

1. 对请求进行分类。如果源代码和输入未发生变化，且已有的成功结果已能回答问题，则复用该结果。验证其他改动的专项任务属于附带验证；以构建、检查、警告或失败处理为核心的工作则属于 Gradle 工作流。

2. 确定此技能的目录。如果 python3 或 scripts/gradle_run.py 不可用（独立运行 create 失败即可表明这一点），则停止并报告此前置条件；绝不要改为直接运行 Gradle。按原样调用项目指定的入口点（通常是 ./gradlew）；不要读取其源代码来质疑它，也不要换用其他启动脚本。

3. 在执行第一条命令前创建一个工作流，并保留其不透明 ID：

   python3 <skill-dir>/scripts/gradle_run.py create
   

   将 create、每次 run 和 finish 都作为独立的 Shell 命令运行。不要将它们与 ls、test、变量设置、git、rg、&&、;、管道，或包含其他命令的换行组合在一起。若 create 失败，则先独立重试一次新的 create，之后才能运行 run。只能使用此封装器；除非已选择控制台行为或用户授权使用 --scan，否则它会提供 --console=plain 和 --no-scan。仅在查找警告或用户明确要求时添加 --warning-mode all。如果 run 或 finish 报告 workflow is busy，请检查状态并等待当前所有者；保持单一执行所有者，避免重复构建。

   如果工具会话消失，或运行结果未知，请使用同一工作流 ID（以及之前提供的同一全局 --root）：

   python3 <skill-dir>/scripts/gradle_run.py status --workflow <id>
   

   状态查询是只读的，会立即返回最多 16 KiB 的 JSON。run 会按序列号标识当前或最近一次运行，并提供封装器/子进程 PID、开始时间、工作目录、命令和问题。result 是最近一次存储的、有界终端摘要，通过 result_sequence 标识；如果有新运行正在进行，它可能描述的是前一次运行。状态查询绝不会打开日志。在状态为 running 时轮询状态；仅该运行持有的锁可作为活动证据，而 PID 仅用于标识。无关工作流的锁竞争会使已被放弃的运行保持为 uncertain。completed 包括构建失败和启动错误：请检查 result.exit_status。interrupted 必须有记录在案的信号。uncertain 表示活动记录已被放弃、锁缺失、账本不完整或为旧版本，以及缺少充分证据的状态转换。请报告此不确定性；下一步应调查所有权，而不是根据 PID 推断任务已完成、重新运行（包括有条件地或稍后重跑）、清理、执行 finish 或终止进程。新工作流的状态为 idle；执行 finish 后状态变为 finished，且结果会被删除。对于未知 ID，系统会采取拒绝操作的安全策略。只有在获取所需结果后，才能执行 finish。

4. 对于附带验证，请留在当前 Agent 中，运行能够回答非空验证问题的最精简任务：

   python3 <skill-dir>/scripts/gradle_run.py run \
     --workflow <id> --scope targeted \
     --question "Does :module:test pass after this change?" -- \
     ./gradlew :module:test
   

   不要用编译替代要求的夹具测试，也不要因为可能找不到测试而跳过要求的运行；请运行并报告这一注意事项。 只读取有界 JSON 摘要；报告托管包装器和嵌套 Gradle 任务、问题以及有界答案。

5. 对于以 Gradle 为中心的工作，默认由当前实现负责人处理诊断、仓库编辑和包装器执行。只有在能提供有价值的独立分析时，才委派有明确范围的只读调查。使用共享的 选择与交接参考来选择并简要说明可选助手。 同一时间只保留一个包装器执行负责人；助手向该负责人报告证据和建议。没有可用助手时，直接继续。

6. 重用可操作的摘要，按指纹归类警告／失败，并返回源码／行号证据以及范围最窄的下一条命令。只有在定向证据无法回答汇总性问题时，才进行广泛检查。主要源码／编译器指纹重复出现时，停止重新构建；在修改诊断之前，先检查所引用的源码行及其附近的声明、导入或接收者上下文。每次源码更改后，都使用同一包装器和适用范围最窄的任务进行验证。在最终诊断中，将有针对性的检查列为下一步操作；在此之前不要声称已修复源码。新问题不意味着可以盲目重复：在问题标签改变后重跑未更改的任务，仍属于重复。

7. 将完整日志视为原始敏感材料，即使摘要和记录表会对常见凭据进行脱敏。切勿将其暴露在模型可见上下文中。发生中断时，使用包装器记录的信号和有界部分诊断；由包装器负责清理进程组／进程树并持久更新记录表。仅保留最近运行有界记录表中仍列出的日志。如果有界结果报告 Gradle 启动前访问缓存遭拒，请报告确切路径，并且只建议用户授权为该现有缓存目录显式添加一个可写根目录条目。到此为止：不要应用该条目、安排后续重跑、执行 finish 或启动新工作流，也不要禁用沙盒或迁移缓存。

8. 最后一项要求的验证（定向或广泛）通过后结束；否则报告未解决的指纹以及无法继续验证的原因。在最终回复中，逐一引用每个非空的 --question，并给出其有界答案；命令历史不能替代证据报告。然后运行：

   python3 <skill-dir>/scripts/gradle_run.py finish --workflow <id>
   

   报告 finish 仅移除了包装器拥有的日志。对于已完成的已知 ID，操作是幂等的；对于未知 ID 或正在运行的工作流，操作会安全失败并保留文件。此技能不约束无关的审查、实现或子代理。