用途
本技能是一份针对 Windmill 平台编写 PowerShell 脚本的编写指南，规定了脚本的组织方式、参数声明方式、返回值写法，以及配套 CLI 命令的使用时机。
主要能力与约定
脚本应放在一个文件夹内。PowerShell 脚本没有 main 入口函数，参数通过在第一行调用 param 函数获取，例如 param($Name, $Count = 0, [int]$Age)。参数可指定类型，如 [string]、[int]、[bool]、[array]，并可设置默认值。脚本通过在末尾输出对象来返回结果，例如输出 @{ name = $Name; count = $Count } 这样的哈希表；返回值应为 JSON 可序列化的值。
脚本的输入即其参数。凭据与配置应通过资源类型参数传入，不应硬编码或从环境变量读取。当某服务没有现成资源类型时，可用自定义类型（命名 c_<name>）承载连接字段（基础 URL、账号标识、凭据），密钥放在资源引用的变量中。库会被自动安装，无需展示安装说明。若语言存在 Windmill 客户端 wmill，可用其与平台交互。脚本输入结构可包含顶层 prompt_for_ai 字符串，用于指示 AI 如何选择输入参数。
另有预处理脚本（preprocessor）机制，用于在流程接收触发数据前处理原始数据，使用 TypeScript 或 Python 编写，函数名为 preprocessor，接收单一参数 event，返回对象决定传入流程的参数值。
使用方式（CLI 命令）
写完脚本后，应根据用户意图选择命令：
- wmill script preview <script_path>：迭代本地脚本时的默认选择，运行本地文件而不部署。
- wmill script run <path>：运行工作区中已部署的脚本，仅在用户明确要求测试已部署版本、而非本地改动时使用。
- wmill generate-metadata：为改动的脚本重新生成本地 .script.yaml（输入 schema）与 .lock（解析后的依赖），并刷新 wmill-lock.yaml 中的内容哈希。仅写本地文件，不是部署。不带路径参数时只重新生成内容哈希发生漂移的项；可用 --dry-run 查看哪些项过期及原因，再用路径参数缩小范围，或使用 --strict-folder-boundaries。若磁盘上的 .lock 与 .script.yaml 已正确、只需刷新 wmill-lock.yaml 哈希，可用 wmill generate-metadata rehash。
- 部署本地改动：通过 git push 或 wmill sync push（取决于仓库接线方式）。仅在用户明确要求部署、发布、推送时执行。
预览与运行的选择
若用户说“运行脚本”“试试”“测试一下”“能用吗”，而脚本文件存在本地改动，应使用 script preview，不要先推送再运行——推送即部署，为测试而部署会用未测试的改动覆盖工作区版本。仅在用户明确要求“运行已部署版本”，或当前没有正在编辑的本地脚本（只是调用现有脚本）时，才使用 script run。仅在用户明确要求部署、发布、推送、上线，或预览已验证改动且用户希望其进入工作区时，才使用 sync push。
元数据同步
wmill-lock.yaml 跟踪每一项的内容哈希。编辑脚本内容（尤其是增删导入或修改 main 参数）会使哈希失效，导致 .lock、.script.yaml 输入 schema 及哈希行过期。此类编辑后应运行 wmill generate-metadata（限定到改动范围），使解析锁定、自动生成的参数 UI 与 wmill-lock.yaml 与代码一致。保持过期会在 git-sync 与 CI 中产生伪差异。该命令只写本地文件（不是部署），但会重新解析依赖，可能提升未固定版本（与从 UI 部署相同，属预期行为而非缺陷）。因此默认应主动提出并在用户同意后运行，而不是每次编辑后静默执行；若项目 AGENTS.md 选择自动运行元数据则例外。无论哪种方式，命令由执行者运行，而非用户。运行后应对照重新生成的 .lock/.script.lock 文件，告知用户哪些依赖版本发生变化（例如 requests 2.31.0 → 2.32.0），以便在部署前发现不需要的版本提升。在代码中固定版本可保持其不变。
适用场景与限制
适用于在 Windmill 中编写、迭代、测试与部署 PowerShell 脚本的流程，以及需要保持脚本元数据与依赖锁定同步的场景。限制与注意事项包括：preview 不部署但仍会执行脚本代码，可能产生副作用，应在用户要求测试/预览或确认执行意图后再运行；generate-metadata 不部署但会重新解析依赖，可能提升未固定版本；部署（git push 或 wmill sync push）是唯一会改变远程状态的操作，仅在用户明确要求时执行。若实例报告未同步 Windmill Hub 的资源类型，可提示超级管理员进行同步。使用资源类型前可运行 wmill resource-type list 查看工作区是否具备该类型。