用途
write-script-java 是一个面向 Windmill 工作区的 Java 脚本编写技能。它在编写 Java 脚本时被触发,指导作者遵循 Windmill 对 Java 脚本的结构要求,并给出本地预览、运行与部署之间的正确选择方式。
脚本结构要求
Java 脚本必须包含一个名为 Main 的公共类,并提供 public static main() 方法。要点如下:
- 类名必须为 Main。
- 方法必须是 public static Object main(...)。
- 返回类型为 Object 或 void。
示例:
public class Main { public static Object main(String name, int count) { java.util.Map<String, Object> result = new java.util.HashMap<>(); result.put("name", name); result.put("count", count); return result; } }
Maven 依赖
在文件顶部通过注释添加依赖:
//requirements: //com.google.code.gson:gson:2.10.1 //org.apache.httpcomponents:httpclient:4.5.14
import com.google.gson.Gson;
public class Main { public static Object main(String input) { Gson gson = new Gson(); return gson.fromJson(input, Object.class); } }
使用方式
将脚本放入某个文件夹,然后根据意图选择命令:
- wmill script preview <script_path>:默认用于本地脚本迭代,运行本地文件而不部署。
- wmill script run <path>:运行工作区中已部署的脚本。仅当用户明确要测试已部署版本、而非本地改动时使用。
- wmill generate-metadata:为你修改过的脚本重新生成本地 .script.yaml(输入 schema)与 .lock(解析后的依赖),并刷新 wmill-lock.yaml 中的内容哈希。仅作用于本地文件,不是部署。
- 部署本地改动到工作区:依据仓库接线方式,通过 git push 或 wmill sync push 完成。仅在用户明确要求 deploy/publish/push 时建议或执行。
预览与运行的区分应以意图为准,而非习惯:当用户说“运行脚本”“试试看”“测一下”“能用吗”,且脚本文件存在本地改动时,应使用 script preview,不要先把脚本推上去再 script run,因为推送即部署,而为了测试去部署会用未经测试的改动覆盖工作区版本。
仅在以下情况使用 script run:用户明确说“运行已部署版本”“运行服务器上的版本”;或没有正在编辑的本地脚本(只是调用已有脚本)。
仅在用户明确要求 deploy、publish、push 或 ship,且预览已验证改动、用户希望其进入工作区时,才使用 sync push。
保持元数据同步
wmill-lock.yaml 为每个条目记录内容哈希。编辑脚本内容(尤其是增加或删除 import、修改 main 的参数)会使该哈希失效,导致 .lock、.script.yaml 输入 schema 与哈希行过期。此类编辑后应运行 wmill generate-metadata(限定到你改动的内容),使解析后的 lock、由 .script.yaml 驱动的自动生成参数 UI 与 wmill-lock.yaml 都与代码一致。保持过期状态会在 git-sync 与 CI 中产生虚假差异。
该命令只写本地文件(不是部署),但会重新解析依赖,因此可能提升未固定的版本(与从 UI 部署一致,属预期而非缺陷)。因此默认先提供该操作,待用户同意后再运行,而不是每次编辑后静默执行——除非项目的 AGENTS.md 选择自动运行元数据(见其中的 “Keeping metadata in sync” 偏好)。无论哪种方式,都应由你(AI)执行该命令,而不是让用户执行。执行后对比重新生成的 .lock / .script.lock 文件,并告知用户哪些依赖版本发生变化(例如 requests 2.31.0 → 2.32.0),以便在部署前发现不想要的版本提升——即使在 Metadata: auto 下也应告知,因为这是信息而非确认门槛。在代码中固定版本可保持其不变。
不带路径参数时,generate-metadata 只重新生成内容哈希发生漂移的条目,而非全部。导入会传播:编辑一个被他人导入的脚本,会使每个导入方都变为过期,因此对共享模块的一行改动可能重新生成许多 lock(这是设计使然——它们的 lock 必须反映被导入的代码)。如果影响范围超出预期,可运行 wmill generate-metadata --dry-run,它会列出每个过期条目及原因(内容变更或依赖 <path>)而不做任何改动,然后用路径参数(wmill generate-metadata f/foo)或 --strict-folder-boundaries 缩小范围。
如果磁盘上的 .lock 与 .script.yaml 已经正确,只有 wmill-lock.yaml 需要刷新哈希(哈希漂移,或补齐缺失条目),可使用 wmill generate-metadata rehash,它从磁盘重新记录哈希,不与后端往返、不改动依赖。
写完脚本后
如果用户尚未要求你运行/测试/预览脚本,用一句话提出下一步建议即可(例如“要我用示例参数运行 wmill script preview 吗?”),不要给出多选项菜单。
如果用户在最初请求中已要求测试/运行/尝试脚本,则跳过建议,直接执行 wmill script preview <path> -d '<args>',并从脚本声明的参数中选择合理的参数值。参数形态因语言而异:代码类语言为 main(...),SQL 方言使用各自的占位符语法(PostgreSQL 用 $1,MySQL/Snowflake 用 ?,MSSQL 用 @P1,BigQuery 用 @name 等),Bash 用位置参数 $1、$2、…,PowerShell 用 param(...)。
wmill script preview 不部署,但仍会执行脚本代码并可能产生副作用;当用户要求测试/预览(或确认意图为执行)时由你运行。wmill generate-metadata 也不部署——它只写本地文件(lock、schema、哈希)——但按上文“保持元数据同步”所述,运行前应先提供(或在项目 AGENTS.md 选择自动时自动运行)。部署到工作区(依据仓库接线方式使用 git push 或 wmill sync push)是唯一改变远端状态的步骤——仅在用户明确要求 deploy/publish/push 时执行。
如果需要在开发页面可视化打开脚本进行预览(而非 script preview 的运行并打印结果),请使用 preview 技能。
可使用 wmill resource-type list --schema 发现可用的资源类型。
适用场景
- 在 Windmill 中编写、迭代与测试 Java 脚本。
- 需要为 Java 脚本声明 Maven 依赖。
- 需要区分本地预览、已部署版本运行与正式部署。
- 修改脚本后需要同步 .lock、.script.yaml 与 wmill-lock.yaml 哈希。
限制
- 资料未提供价格、收费模式或授权信息。
- 资料未提供可用平台范围、运行环境要求或性能指标。
- 资料未提供脚本可直接使用的示例参数具体取值,仅说明参数形态与如何选取。