用途 该技能面向使用 Windmill 编写 Bash 脚本的场景,用于约束脚本结构、输出形式以及本地预览、元数据同步与部署之间的操作边界。
脚本结构与参数 不要加入 #!/bin/bash。参数以位置参数形式获取,例如 var1="$1"、var2="$2";参数始终是字符串,通过 $1、$2 等访问。
输出方式 脚本输出会被捕获为结果。需要结构化数据时输出合法 JSON,例如用 heredoc 拼接 name、count、timestamp 等字段。脚本中可读取 Windmill 设置的环境变量,如 $WM_WORKSPACE、$WM_JOB_ID。
CLI 命令与使用方式 脚本放在文件夹中。写完后向用户说明命令与用途的匹配关系:
- wmill script preview <script_path>:迭代本地脚本时的默认选择,运行本地文件而不部署。
- wmill script run <path>:运行已部署到工作区的脚本,仅在用户明确要测试部署版本时使用。
- wmill generate-metadata:为改动过的脚本重新生成本地 .script.yaml(输入 schema)与 .lock(已解析依赖),并刷新 wmill-lock.yaml 中的内容哈希;只写本地文件,不是部署。
- 部署本地改动:视仓库接线方式通过 git push 或 wmill sync push 完成,仅当用户明确要求部署/发布/推送时才建议或执行。
预览与运行的判断标准 若用户说“运行脚本”“试试”“测试一下”“能不能用”,且脚本文件存在本地修改,应使用 script preview,不要先推送再 script run,因为推送即部署,会用未经测试的改动覆盖工作区版本。只有用户明确说“运行部署版本/服务器上的版本”,或本地没有正在编辑的脚本而只是调用已有脚本时,才使用 script run。只有用户明确要求部署/发布/推送/上线,才使用 sync push。
元数据同步 wmill-lock.yaml 为每个条目记录内容哈希。编辑脚本内容(尤其是增删 import 或修改 main 的参数)会使该哈希失效,导致 .lock、.script.yaml 输入 schema 和哈希行过时。此类编辑后应运行 wmill generate-metadata(范围限定为改动过的项),使解析后的锁文件、由 .script.yaml 驱动的参数 UI 以及 wmill-lock.yaml 与代码一致;否则 git-sync 和 CI 会出现虚假差异。该命令只写本地文件、不是部署,但会重新解析依赖,因而可能提升未固定(unpinned)的版本,这与从 UI 部署的行为一致,属预期现象。默认应主动提出并在用户同意后运行,而非每次编辑后静默执行,除非项目的 AGENTS.md 选择自动运行。无论如何都由助手执行该命令。运行后应 diff 重新生成的 .lock / .script.lock 文件并告知用户哪些依赖版本发生变化(例如 requests 2.31.0 → 2.32.0),以便在部署前发现不想要的版本提升。可在代码中固定版本以保持稳定。
无路径参数时,generate-metadata 只重新生成内容哈希漂移的项,而非全部。import 会传播:编辑被他人 import 的脚本会使所有导入方也变为过时,因此共享模块的一行改动可能重新生成许多锁文件(这是设计使然)。若影响范围超出预期,可运行 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 也不部署、只写本地文件,但按上文应先行提议(或在项目 AGENTS.md 选择自动时运行)。部署到工作区是唯一会改动远端状态的步骤,仅在用户明确要求部署/发布/推送时执行。若需要“在开发页面打开脚本”的可视化预览而非 script preview 的运行并打印结果,应使用 preview 技能。可用 wmill resource-type list --schema 查看可用的资源类型。