write-workflow-as-code 是 Windmill 的 Workflow-as-Code(WAC)编写技能,用于编写或修改 WAC 脚本时提供规范。WAC 以普通 Windmill 脚本形式编写,并沿用普通脚本工作流部署,不是 OpenFlow YAML 流程,也没有单独的 WAC 部署命令。
支持的编写目标
- 从 windmill-client 导入的 Bun TypeScript 脚本
- 从 wmill 导入的 Python 3 脚本
文件结构
Bun TypeScript 从 windmill-client 导入 task、taskScript、taskFlow、step、sleep、waitForApproval、getApprovalUrls、parallel、workflow,并导出 workflow 入口,通常是 export const main = workflow(async (...) => { ... })。Python 从 wmill 导入 task、task_script、task_flow、step、sleep、wait_for_approval、get_approval_urls、parallel、workflow,并用 @workflow 装饰顶层 async 函数(通常是 main)。规则包括:不要调用 main;task 函数与 taskScript/task_script 或 taskFlow/task_flow 赋值应定义在模块顶层并使用稳定名称;必须使用精确的 SDK 名称,不能对 workflow、task、taskScript、taskFlow、step、sleep、waitForApproval、task_script、task_flow、wait_for_approval 取别名。
检查点与重放模型
父工作流在任何挂起、重试、审批或子任务完成后可能从顶部重新运行,已完成的持久步骤从检查点重放。所有副作用或非确定性值都必须放在持久化 WAC 边界之后:用 task()/@task() 执行应作为独立子作业的重要工作;用 taskScript()/task_script() 调用已有脚本或相对模块文件;用 taskFlow()/task_flow() 调用已有 Windmill 流程;用 step(name, fn) 执行需要检查点结果的轻量内联工作;用 sleep(seconds) 执行不占用 worker 的服务端休眠;用 waitForApproval()/wait_for_approval() 进行外部审批挂起。绝不可把 API 调用、数据库写入、通知、随机值、时间戳或不可逆变更直接放在工作流主体中。基于 task 或 step 结果分支是安全的,因为结果有检查点;基于当前时间、随机数据、环境读取或外部状态分支则不安全,除非先用 step() 捕获该值。
任务与内联步骤
task()/@task() 用于内联函数,使其成为工作流步骤,TypeScript 建议赋值给具名顶层 const,Python 建议用顶层 async 函数并加 @task() 或 @task 装饰器。已有脚本通过 taskScript("./helper.ts") 或 task_script("./helper.py") 引用,也可传入工作区路径与 timeout 选项。已有流程通过 taskFlow("f/etl/pipeline") 或 task_flow 引用。step() 用于轻量内联值,避免重放时变化,步骤名必须稳定且具描述性,不得动态生成。
并行
将独立任务先启动再一起等待:TypeScript 可用 Promise.all 或 parallel(items, process, { concurrency: 5 });Python 可用 asyncio.gather 或 parallel(items, process, concurrency=5)。只并行独立步骤,不要在 await 之前读取任务结果。
审批
在 step() 内命名审批步骤并生成其 URL 后再发送。getApprovalUrls/get_approval_urls 返回绑定该步骤的 URL,与内置 approve/reject 按钮所用一致。多个审批需各自唯一 key,复用同一 key 会报错。getResumeUrls()/get_resume_urls() 仍可用,但会签随机 nonce,URL 不绑定特定审批步骤。selfApproval: false 与 self_approval=False 为仅企业版审批行为,除非用户要求否则不要使用。
错误处理
除非用户要求恢复逻辑,否则让任务错误导致工作流失败。Python 中 except Exception 包住 WAC 调用是安全的,因为内部挂起继承自 BaseException,避免在工作流代码中使用裸 except:。TypeScript 中避免对 WAC SDK 调用做宽泛 try/catch,SDK 在初始派发时使用内部挂起错误,捕获它可能破坏工作流挂起;若无法避免宽泛捕获,需先重新抛出内部挂起错误。被捕获的失败带有 step_key、child_job_id(step() 无子作业故缺失)、message 以及 result = {"error": {"name", "message", "stack"?, "extra"?}}。请基于这些字段分支,而不要基于原始异常类型。Python 抛出 TaskError,TypeScript 抛出名为 TaskError 的 Error。
CLI 命令
脚本放入文件夹后,根据用户意图选择命令: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、try 或 test 时。
预览与运行的选择
若用户说运行、试试、测试脚本且存在本地编辑,使用 script preview,不要先推送再 script run。仅当用户明确说要运行已部署版本/服务器上版本,或本地没有正在编辑的脚本时才用 script run。仅当用户明确要求部署、发布、推送或发布上线,或预览已验证且用户希望进入工作区时才用 sync push。
编辑后保持元数据同步
wmill-lock.yaml 为每个条目记录内容哈希。编辑脚本内容(尤其是增删导入或修改 main 参数)会使哈希失效,导致 .lock、.script.yaml 输入 schema 与哈希行过期。此类编辑后应运行 wmill generate-metadata(限定到改动范围),使解析后的 lock、自动生成的 args UI 与 wmill-lock.yaml 都与代码匹配。该命令只写本地文件但会重新解析依赖,可能提升未固定版本(与从 UI 部署相同,属预期)。默认应先提供该选项,用户同意后再运行,除非项目的 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(...),SQL 方言使用各自占位符(PostgreSQL 用 $1,MySQL/Snowflake 用 ?,MSSQL 用 @P1,BigQuery 用 @name 等),Bash 为位置参数 $1、$2…,PowerShell 为 param(...)。
wmill script preview 不部署,但会执行脚本代码并可能产生副作用;在用户要求测试/预览或确认要执行时再自行运行。wmill generate-metadata 也不部署,只写本地文件,但按上述同步规则应先提供或在 AGENTS.md 选择自动时运行。部署到工作区(git push 或 wmill sync push)是唯一改变远端状态的步骤,仅在用户明确要求部署/发布/推送时执行。如需在开发页面打开脚本的可视化预览(而非 script preview 的运行并打印结果),使用 preview 技能。可用 wmill resource-type list --schema 发现可用资源类型。