用途
write-script-go 用于指导在 Windmill 中编写 Go 脚本。当需要编写 Go 脚本时必须使用它。文档围绕两件事展开：Go 脚本本身的结构规范，以及围绕本地脚本的预览、运行、元数据同步与部署操作。
Go 脚本结构
Go 脚本的 package 必须为 inner，并导出一个名为 main 的函数（小写）。函数返回类型必须是 ({return_type}, error)。示例：
package inner
func main(param1 string, param2 int) (map[string]interface{}, error) { return map[string]interface{}{ "result": param1, "count": param2, }, nil }
返回类型可以是任何可序列化为 JSON 的 Go 类型，例如带 json tag 的结构体：
package inner
type Result struct {
Name string json:"name"
Count int json:"count"
}
func main(name string, count int) (Result, error) { return Result{ Name: name, Count: count, }, nil }
错误处理通过第二个返回值返回，例如使用 errors.New 构造错误并在出错时返回空值与错误。
脚本通用原则
脚本的输入即其参数。凭据与配置以资源类型参数的形式传入，不得硬编码，也不应从环境变量读取。库会自动安装，无需给出安装说明。有入口函数的语言（TypeScript、Python、Go、Rust、PHP、R 等）入口名为 main（C# 中为 Main），且不应在代码中调用它。
当某服务不存在对应资源类型时，仍应把其连接作为一个资源类型参数传入，使用自定义类型承载连接字段（base URL、账户标识、凭据），其密钥放在资源引用的变量中。自定义类型命名为 c_<name>。仅当用户要求时才使用普通字符串参数或在代码内读取变量。
脚本输入 schema 可携带顶层 prompt_for_ai 字符串，用于指导选择输入的 AI；在重写 schema 时应保留它。
返回值与预处理器
脚本可返回任何 JSON 可序列化值；返回值可通过 results.step_id 供后续流程步骤使用。
预处理器脚本用于在将原始触发数据（webhook、自定义 HTTP 路由、SQS、WebSocket、Kafka、NATS、MQTT、AMQP、Postgres、GCP Pub/Sub、Azure、email 等）传入流程前进行处理。预处理器用 TypeScript 或 Python 编写，函数名为 preprocessor 而非 main，接收一个名为 event 的参数。返回对象决定传给流程的参数值。
使用方式：预览、运行与部署
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（限定于改动范围），使依赖锁定、自动生成的参数 UI 与 wmill-lock.yaml 与代码一致。
该命令只写本地文件，但会重新解析依赖，因此可能提升未固定版本（与从 UI 部署时相同，属预期行为）。因此默认应主动提出并在用户同意后运行一次，而不是每次编辑后静默执行；除非项目 AGENTS.md 选择自动运行。命令应由你执行，而非用户。运行后应对比重新生成的 .lock / .script.lock 文件，告知用户哪些依赖版本发生变化。
不带路径参数时，generate-metadata 只重新生成内容哈希漂移的条目。import 会传播：编辑被其他脚本 import 的脚本会使所有导入方标记为过期。若影响范围超出预期，可运行 wmill generate-metadata --dry-run 查看每个过期条目及原因，再用路径参数或 --strict-folder-boundaries 收窄范围。
若磁盘上的 .lock 与 .script.yaml 已正确，仅 wmill-lock.yaml 需要刷新哈希，可使用 wmill generate-metadata rehash。
编写后的下一步
若用户尚未要求运行/测试/预览脚本，应以一句话提出建议，而不是给出多选项菜单。若用户原始请求已包含测试/运行/尝试，则跳过建议，直接执行 wmill script preview <path> -d '<args>'，从脚本声明的参数中选取合理参数。
wmill script preview 不部署，但仍会执行脚本代码并可能产生副作用，应在用户要求测试/预览时（或确认要执行后）自行运行。生成元数据也只写本地文件，但应先提出再运行（或在 AGENTS.md 选择自动时自动运行）。部署到工作区是唯一会改动远程状态的操作，仅在用户明确要求时执行。
若希望以可视化方式在开发页打开脚本预览（而非 script preview 的运行并打印结果），使用 preview 技能。可使用 wmill resource-type list --schema 发现可用资源类型。
适用场景与限制
适用于在 Windmill 平台上编写和维护 Go 脚本、处理本地脚本的预览与测试、同步脚本元数据以及理解部署边界。其限制性要求包括：必须使用指定的包名与函数签名；不得硬编码凭据；不得在用户未明确要求时部署；预览会实际执行代码并可能产生副作用。