用途
本页是 Windmill CLI 文档中专注于 GraphQL 脚本编写的指南，面向需要在 Windmill 中编写 GraphQL 查询或变更（mutation）的用户。它不介绍 Windmill 的整体概念，而是给出 GraphQL 脚本的结构写法，以及配套的 CLI 工作流。
主要能力
GraphQL 脚本可编写查询或变更。查询参数通过 GraphQL 变量声明，例如 query GetUser($id: ID!)，变量作为脚本参数传入并自动绑定到查询。变更写法类似，如 mutation CreateUser($input: CreateUserInput!)。
脚本输入即参数。凭据与配置应以资源类型（resource type）参数的形式传入，不能硬编码或从环境变量读取。当某服务没有对应资源类型时，可自定义类型（命名形如 c_<name>，TypeScript 中参数取 RT.C<Name>，Python 中为 c_<name> TypedDict），把连接字段集中管理，密钥放在资源引用的变量中。可用 wmill resource-type list --schema 发现可用资源类型，用 wmill resource-type list 检查工作区是否已有该类型。
使用方式
编写后按用户意图选择命令：本地迭代时用 wmill script preview <script_path>，它运行本地文件而不部署；运行工作区中已部署脚本时用 wmill script run <path>，仅当用户明确要测试已部署版本时使用；编辑了脚本内容（尤其增删 import 或改动 main 的参数）后，运行 wmill generate-metadata 重新生成本地 .script.yaml（输入 schema）和 .lock（解析后的依赖），并刷新 wmill-lock.yaml 中的内容哈希。不带路径参数时只重新生成哈希漂移的项；若范围过大可先 wmill generate-metadata --dry-run 查看每个过期项及原因，再用路径参数或 --strict-folder-boundaries 收窄。若磁盘上的 .lock 与 .script.yaml 已正确、只需刷新哈希，可用 wmill generate-metadata rehash。
部署（git push 或 wmill sync push，取决于仓库接线方式）是唯一修改远端状态的操作，仅在用户明确要求 deploy/publish/push 时执行。用户说“run”“try”“test”且存在本地改动时应使用 preview，而不是先推送再运行。执行生成元数据后应 diff 重新生成的 .lock / .script.lock，告知用户哪些依赖版本变化，以便在部署前发现不希望的版本提升；代码中固定版本可保持稳定。
预览不部署但仍会执行脚本代码，可能产生副作用，应在用户要求测试/预览或确认执行意图后运行。若用户已在原始请求中要求测试，则直接执行 wmill script preview <path> -d '<args>'。
适用场景
适用于在 Windmill 中编写、迭代和测试 GraphQL 查询或变更脚本，并需要将本地改动与工作区、元数据保持一致的工作流。
限制
本页未提供 GraphQL 之外的语言细节；关于部署的具体方式需参考 AGENTS.wmill.md 的 Deploying 部分。本页面未提供任何收费、价格、平台或效果信息。