用途
该技能用于编写 Ansible Playbook，并说明写完后如何配合 Windmill CLI 进行预览、运行与元数据同步。
主要能力与脚本结构
Windmill 通过 ansible-playbook 运行 Ansible Playbook。一个脚本是单个 YAML 文档，由 --- 分隔成两部分：Windmill 头部与一个或多个标准 Ansible play。
头部不是标准 Ansible，由 Windmill 解析以构建脚本输入与运行环境，支持的键包括：extra_vars 定义脚本参数，每项通过 --extra-vars 传入并可作为 Jinja 变量 {{ name }} 使用，需为每个参数指定类型以便生成输入表单；inventory 列出清单，使用 resource_type: ansible_inventory（可用 resource 固定）或 resource_type: dynamic_inventory；files 在运行前把 Windmill 资源或变量写入文件；dependencies 声明 galaxy collections/roles（用 ansible-galaxy 安装）与可用的 Python pip 包；options 传入额外的 ansible-playbook 标志，如 verbosity: vvv；vault_password 指定用作 Ansible Vault 密码的 Windmill 变量路径。
参数可直接以 Jinja 变量引用；Windmill 上下文变量可通过 env lookup 读取，例如 {{ lookup('env', 'WM_WORKSPACE') }}。要返回结果，可在作业目录中写入 result.json。
使用方式与命令选择
写完脚本后，需告知用户哪条命令符合其意图：wmill script preview <script_path> 是本地迭代的默认选择，在不部署的情况下运行本地文件；wmill script run <path> 运行已部署到工作区的脚本，仅在用户明确想测试已部署版本时使用；wmill generate-metadata 为改动过的脚本重新生成本地 .script.yaml（输入 schema）与 .lock（解析后的依赖），并刷新 wmill-lock.yaml 中的内容哈希，仅写本地文件，不是部署；部署本地改动到工作区则通过 git push 或 wmill sync push，取决于仓库配置方式，仅在用户明确要求部署、发布或推送时执行。
若用户在有本地改动时说“run the script”“try it”“test it”“does it work”，应使用 script preview，不要先推送再 script run。仅当用户明确说“run the deployed version”或没有本地脚本在编辑时，才使用 script run。仅当用户明确要求部署、发布、推送或交付，或预览已验证改动且用户希望其进入工作区时，才使用 sync push。
元数据同步
编辑脚本内容（尤其是增删 import 或更改 main 参数）会使 wmill-lock.yaml 中的内容哈希失效，导致 .lock、.script.yaml 输入 schema 与哈希行过期。此类编辑后应运行 wmill generate-metadata（限定到改动项），使解析后的 lock、自动生成的参数 UI 与 wmill-lock.yaml 一致。该命令只写本地文件，但会重新解析依赖，可能提升未固定版本（与从 UI 部署相同，属预期行为），因此默认先提出再在用户同意后运行。运行后需 diff 重新生成的 .lock / .script.lock 文件，并告知用户哪些依赖版本发生变化。不带路径参数时只重新生成内容哈希漂移的项；导入会传播，若影响超出预期可用 wmill generate-metadata --dry-run 查看每个过期项及原因，再用路径参数缩小范围或使用 --strict-folder-boundaries。若磁盘上的 .lock 与 .script.yaml 已正确、仅需刷新 wmill-lock.yaml 哈希，可使用 wmill generate-metadata rehash。
测试与限制
如果用户尚未要求运行/测试/预览，可用一句话提议下一步，例如“Want me to run wmill script preview with sample args?”，不要给出多选项菜单。若用户原本已要求测试/运行/尝试，直接执行 wmill script preview <path> -d '<args>'，并根据脚本声明的参数选择合理参数。wmill script preview 不部署，但会执行脚本代码并可能产生副作用，应在用户要求测试/预览或确认执行后再运行。wmill generate-metadata 同样不部署，只写本地文件。部署到工作区（git push 或 wmill sync push）是唯一会改动远端状态的步骤，仅在用户明确要求部署/发布/推送时执行。若需在开发页面可视化预览脚本，应使用 preview 技能。可用 wmill resource-type list --schema 发现可用资源类型。
资源与参数原则
脚本的输入即其参数；凭据与配置以资源类型参数传入，绝不硬编码或从环境读取。若某服务没有资源类型，仍应把其连接作为单个自定义类型参数（包含 base URL、账号标识、凭据等），其密钥放在资源引用的变量中；自定义类型命名为 c_<name>，在 TypeScript 中参数类型为 RT.C<Name>，在 Python 中为 c_<name> TypedDict。只有在用户要求时才使用普通字符串参数或代码内读取变量。若实例被报告未同步 Windmill Hub 的资源类型，应说明超级管理员可以同步。对于 Hub 脚本，若实例未同步其类型则该类型缺失，应先说明并请超级管理员同步，再请求该资源；Hub 脚本常内联声明类型（如 type Stripe = { token: string }），在自写代码中应按语言约定命名（如 TypeScript 中 RT.Stripe）。依赖库自动安装，不展示安装说明。有入口函数的语言（TypeScript、Python、Go、Rust、PHP、R 等）应命名为 main（C# 为 Main）且不要调用，TypeScript 中必须为 async；SQL、GraphQL、Bash、PowerShell 与 Ansible 脚本没有 main。脚本可返回任意 JSON 可序列化值，返回值可通过 results.step_id 供后续流程步骤使用。预处理脚本处理来自 webhook、自定义 HTTP 路由、SQS、WebSocket、Kafka、NATS、MQTT、AMQP、Postgres、GCP Pub/Sub、Azure 或邮件的原始触发数据，用 TypeScript 或 Python 编写，函数名为 preprocessor，接收单个参数 event，其返回对象决定传给流程的参数值。
适用场景
适合在 Windmill 平台上编写、迭代和测试 Ansible Playbook，并管理其参数、依赖与部署流程。
限制
Windmill 头部不是标准 Ansible，仅由 Windmill 解析；预览会执行代码并可能产生副作用；元数据重新生成可能提升未固定版本；部署会改动远端状态，非明确要求不应执行。