用途
这份指南面向在 Windmill 平台上编写 PostgreSQL 查询脚本的场景。它规定了如何组织脚本、声明参数、处理凭据，以及如何预览、运行或部署脚本。
主要能力
脚本参数与凭据
脚本的输入即参数。凭据和配置应通过资源类型参数传入，禁止硬编码或从环境变量读取。当某服务没有现成资源类型时，仍应将其连接作为一个资源类型参数，使用自定义类型 c_<name> 承载连接字段（基础 URL、账号标识、凭据），密钥放在该资源引用的变量中。使用 wmill resource-type list --schema 可以发现可用资源类型。
PostgreSQL 参数声明
在语句中直接使用 $1::{type}、$2::{type} 获取参数。可在脚本开头用注释为参数命名：
-- $1 name1
-- $2 name2 = default_value
SELECT * FROM users WHERE name = $1::TEXT AND age > $2::INT;
接收 S3Object 参数
将参数声明为 (s3object) 类型。Windmill 会渲染 S3 文件选择器、下载文件并以 jsonb 参数绑定。Parquet/CSV 在服务端解码为 JSON 记录数组，JSON/JSONL 直接透传。可用 jsonb_to_recordset 消费：
-- $1 file (s3object)
SELECT *
FROM jsonb_to_recordset($1::jsonb) AS r(id INT, name TEXT);
流式写入 S3
在脚本顶部添加 -- s3 指令可将结果集流式写入 S3，Windmill 写入文件并以 S3Object 形式返回脚本结果：
-- s3 prefix=exports/users format=parquet
SELECT id, name FROM users;
所有键均可选：prefix（对象键前缀）、storage（命名存储，省略则使用工作区默认）、format（json 为默认，或 parquet、csv）。适合大结果集，行会直接流式写入 S3 而非作为返回值缓冲。
使用方式
预览与运行的选择
根据意图而非习惯选择命令。当用户说“运行脚本”“试试”“测试一下”“能用吗”且脚本文件存在本地修改时，使用 script preview，不要推送后再运行——推送即部署，为了测试而部署会用未验证的改动覆盖工作区版本。
仅在以下情况使用 wmill script run：用户明确说“运行已部署版本”“运行服务器上的版本”，或者没有正在编辑的本地脚本（只是调用既有脚本）。
仅在以下情况使用 wmill sync push：用户明确要求部署、发布、推送或上线；预览已验证改动且用户希望其进入工作区。
元数据同步
wmill-lock.yaml 为每个条目记录内容哈希。编辑脚本内容（尤其是新增或删除导入、修改 main 参数）会使哈希失效，导致 .lock、.script.yaml 输入 schema 和哈希行过期。此类编辑后运行 wmill generate-metadata（限定改动范围），使解析后的 lock、自动生成的参数 UI 和 wmill-lock.yaml 与代码一致。
该命令只写本地文件（不是部署），但会重新解析依赖，可能升级未固定版本。默认应先提议，用户同意后再运行，除非项目的 AGENTS.md 选择自动运行元数据。运行后对比重新生成的 .lock / .script.lock 文件并告知用户哪些依赖版本发生变化。
不带路径参数时，generate-metadata 仅重新生成内容哈希漂移的条目。导入会传播：编辑被其他脚本导入的脚本会使所有导入者过期。若涉及超出预期，可运行 wmill generate-metadata --dry-run 列出每个过期条目及原因，再用路径参数缩小范围或使用 --strict-folder-boundaries。
若磁盘上的 .lock 和 .script.yaml 已正确，仅 wmill-lock.yaml 需要刷新哈希，使用 wmill generate-metadata rehash。
编写后的操作
如果用户尚未要求运行、测试或预览脚本，用一句话提议下一步，例如“要我用示例参数运行 wmill script preview 吗？”不要给出多选项菜单。
如果用户已在原始请求中要求测试、运行或试用脚本，跳过提议直接执行 wmill script preview <path> -d '<args>'，从脚本声明的参数中选取合理参数。参数形态因语言而异：代码语言为 main(...)，PostgreSQL 为 $1，MySQL/Snowflake 为 ?，MSSQL 为 @P1，BigQuery 为 @name，Bash 为位置参数 $1、$2，PowerShell 为 param(...)。
wmill script preview 不部署，但会执行脚本代码并可能产生副作用；在用户要求测试或预览时（或确认要执行后）再运行。部署到工作区是唯一会改变远程状态的步骤，仅在用户明确要求时执行。
如需在开发页面中可视化打开脚本进行预览而非运行打印结果，可使用 preview 技能。
适用场景与限制
适用于在 Windmill 平台上编写、调试和管理 PostgreSQL 查询脚本的开发者，尤其适合需要将查询结果导出到 S3 或接收 S3 文件作为输入的大数据处理场景。
限制与注意事项：脚本库会自动安装，无需展示安装说明。有入口函数的语言中入口命名为 main（C# 为 Main），TypeScript 中必须为 async。SQL、GraphQL、Bash、PowerShell 和 Ansible 脚本没有 main，其参数获取方式见各自语言部分。脚本输入 schema 可能带有顶层 prompt_for_ai 字符串，是作者给选择输入的 AI 的指令，选取运行参数时应遵循，重写 schema 时应保留。脚本返回值可为任何 JSON 可序列化值，SQL 脚本返回查询产生的行；返回值可通过 results.step_id 供后续流程步骤使用。预处理器脚本用于在触发数据传入流程前处理原始触发数据，以 TypeScript 或 Python 编写，函数名为 preprocessor，接收单个参数 event，返回对象决定传入流程的参数值。
定价、平台支持范围等其他信息暂未提供。