write-flow

Name: write-flow
Author: windmill-labs

github.com/windmill-labs开发541 次安装1 天前更新

代码仓库

关于 write-flow

write-flow 是面向 AI Agent 的技能指南，说明如何用 Windmill CLI 创建和测试 Windmill 工作流。指南强调正确生成骨架、遵循结构规则，并按用户意图选择本地预览或部署操作。

主要功能

01使用 `wmill flow new` 创建工作流骨架
02按 OpenFlow 规则定义模块
03选择整条或单步预览
04重新生成本地元数据和锁文件
05区分测试与部署

适用场景

01按指定路径和摘要创建 Windmill 工作流
02测试本地修改而不部署
03迭代时验证单个模块
04更新内联脚本的元数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/windmill-labs/windmill-cli-docs --skill write-flow

安装后在 Claude Code 中输入/write-flow确认已加载。

详细介绍

Windmill Flow CLI 指南

创建 Flow

你——AI Agent——应通过使用正确的标志运行 wmill flow new <path>，自行搭建 Flow。不要手动创建文件夹和 flow.yaml，也不要告诉用户“运行 wmill flow new 并按照提示操作”。

wmill flow new 会使用正确的后缀（根据工作区的 nonDottedPaths 设置，使用 __flow 或 .flow），创建文件夹、写入最简的 flow.yaml 框架，并打印针对 Claude 的后续步骤提示。手动搭建会跳过这些操作，而且经常会选错后缀。

第 1 步——询问用户路径和摘要

你需要两项信息：

路径——windmill 路径，例如 f/folder/my_flow 或 u/username/my_flow。
摘要——对 Flow 的简短描述。

如果用户的请求没有提供这两项信息，请在同一轮中一并询问。使用运行环境提供的交互式提问功能——如果有结构化多选工具，就使用该工具；否则通过普通聊天询问——并为每项提供一两个示例值（同时提供“其他”/自由填写选项）。不要猜测路径或摘要。

第 2 步——自行运行命令

wmill flow new f/folder/my_flow --summary "Short description"

如果用户提供了值得与摘要分开保留的详细说明，请添加 --description "..."。

第 3 步——填写 `flow.yaml`

打开生成的 flow.yaml（位于刚才创建的文件夹中），将空的 value.modules 和 schema 替换为实际的 Flow 定义。

对于 rawscript 模块，请使用 !inline path/to/script.ts 作为内容键。内联脚本文件名不应包含 .inline_script.（例如，使用 a.ts，而不是 a.inline_script.ts）。

Flow 填入实际内容后，主动询问是否要打开可视化预览，并用一句话提出建议（例如：“要我打开可视化预览吗？”）。不要自动打开——打开开发页面会产生副作用（打开浏览器窗口，还可能添加 launch.json 条目），应先征得用户同意。

应避免的反模式

❌ 不运行 wmill flow new，而是手动创建 __flow 文件夹和 flow.yaml。这会跳过后缀设置解析、默认结构和 Claude 提示。
❌ 告诉用户“运行 wmill flow new <path>”——你可以而且应该自行运行。
❌ 不询问用户，而是自行编造路径或摘要。

CLI 命令 — 运行、预览、部署

编写完成后，应根据用户的意图采取行动，而不是只列出命令。适合时，请自行运行 wmill flow preview（参见下文“编写完成后 — 主动提出运行，不要被动等待”）。wmill generate-metadata 会重新生成本地锁定／哈希文件（不是部署），但会重新解析依赖项——应先提出此操作，并在用户同意后运行；除非项目的 AGENTS.md 指明可以自动运行元数据生成。只能提及 wmill sync push（部署），让用户批准后再执行。可选操作：

wmill flow preview <flow_path> — 在本地流程上迭代时的默认选项。 使用本地内联脚本运行本地 flow.yaml，而不会进行部署。添加 --remote 可让 PathScript 步骤使用已部署到工作区的脚本，而不是本地文件。添加 --step <step_id> 可单独运行一个模块（参见下文“单步与全流程预览”）。
wmill flow run <path> — 运行已部署到工作区的流程。仅当用户明确希望测试已部署的版本，而不是本地修改时使用。
wmill generate-metadata — 为流程及其内联脚本重新生成过时的本地 .lock 文件，并刷新 wmill-lock.yaml 中的内容哈希。只会写入本地文件（不会部署）。编辑了导入项或参数发生变化的内联脚本后，请运行此命令，以免 wmill-lock.yaml 与实际状态不一致，并在 git-sync／CI 中引入噪声。默认情况下，它会扫描整个工作区的脚本、流程和应用，但只重新生成过时的文件；传入流程所在的文件夹作为参数（或从该子目录运行），即可将范围限制为你编辑的流程。请注意，导入了已更改共享脚本的流程（或脚本）也会被纳入；应用前运行 wmill generate-metadata --dry-run，即可准确查看哪些内容已过时以及原因（content changed 与 depends on <path>）。
通过 git push 或 wmill sync push 将本地更改部署到工作区，具体取决于仓库的配置方式（参见 AGENTS.wmill.md 中的部署部分）。只有用户明确要求部署／发布／推送时，才建议或执行部署；用户说“运行”“试试”或“测试”时，不要部署。

预览与运行 — 根据意图选择，不要习惯性操作

如果用户说“运行流程”“试一下”“测试一下”或“能正常工作吗”，且存在对 flow.yaml 的本地修改，请使用 flow preview。不要先推送流程再用 flow run——推送属于部署，仅为了测试而部署会用未经测试的修改覆盖工作区版本。

仅在以下情况下使用 flow run：

用户明确说“运行已部署的版本”／“运行服务器上的版本”。
没有正在编辑的本地 flow.yaml（你只是在调用已有流程）。

仅在以下情况下使用 sync push：

用户明确要求部署、发布、推送或交付。
预览已验证更改，且用户希望将其放入工作区。

单步与全流程预览

当用户只在迭代一个模块，且流程的上游步骤并非其验证目标时，使用 flow preview <flow_path> --step <step_id>。此命令只会运行该步骤对应的可运行项（rawscript：内联脚本；script：PathScript，如有本地文件则使用本地文件；flow：按路径运行子流程），比运行整个流程快得多，尤其是在前序步骤运行缓慢或成本高昂时。步骤 ID 通过遍历嵌套的 branchone／branchall／forloopflow／whileloopflow 模块来解析，并包含特殊的 preprocessor 和 failure 模块。

当各步骤依赖彼此的输出、用户正在验证整体控制流，或 --step 不适用时（branchone、branchall、forloopflow、whileloopflow、identity 和 AI agent 步骤都不能单独测试；对于 branchone／branchall／forloopflow／whileloopflow，可传入内部步骤的 ID 来测试其中的步骤），请使用 flow preview <flow_path>（不带 --step）。

编写完成后——主动提出运行，不要被动等待

这里指的是程序化执行（wmill flow preview -d '<args>'），它会实际运行流程并产生副作用。视觉预览（preview 技能）会单独提供——请参阅下文的“视觉预览”。

如果用户还没有告诉你运行或测试流程，就用一句话将其作为下一步提出（例如：“要我用示例参数运行 wmill flow preview 吗？”）。不要提供多选菜单。

如果用户已在原始请求中要求测试、运行或试用流程，就跳过询问，直接执行 wmill flow preview <path> -d '<args>'——根据流程的输入架构选择合理的参数。

架构中类型为资源的输入（format: resource-<type>）应将字符串 "$res:<path>" 作为其完整值——-d '{"db": "$res:f/databases/postgres_prod"}'，而不是 {"db": {"$res": "..."}}，也不是普通路径。变量也一样，使用 "$var:<path>"。请参阅 resources 技能。

你可以安全地自行运行 wmill flow preview（它不会部署）。wmill generate-metadata 也不会部署（它只会写入本地锁定/哈希文件），但会重新解析依赖——提出运行它，并在用户同意后运行，除非项目的 AGENTS.md 允许自动生成元数据。运行后，检查重新生成的 .lock 差异，并告知用户哪些内联脚本依赖版本发生了变化，以便他们在部署前发现不想要的版本升级。只有 wmill sync push 会部署；仅在用户明确要求时运行。

视觉预览

要在开发页面中以可视化方式打开流程（图表 + 实时重新加载），请使用 preview 技能。始终用一句话将其作为下一步提出（例如：“要我打开视觉预览吗？”），而不要自动打开——打开开发页面会产生副作用（浏览器窗口，且在 MCP-preview 分支下可能会添加 launch.json 条目），用户应当对此表示同意。如果用户已在原始请求中要求查看、预览或可视化流程，就跳过询问，直接调用该技能。

Windmill 流程构建指南

OpenFlow 架构

OpenFlow 架构（openflow.openapi.yaml）是流程结构的事实依据。有关完整的类型定义，请参阅 OPENFLOW_SCHEMA。

保留的模块 ID

failure - 为失败处理模块保留
preprocessor - 为预处理器模块保留
Input - 为流程输入引用保留

严格结构规则

这些是 Windmill 架构中的严格规则。请严格遵守。

value.modules 仅用于常规顺序步骤
value.preprocessor_module 和 value.failure_module 是 value 内的特殊顶层字段，不是 value.modules 中的条目
如果流程需要预处理器，请创建 value.preprocessor_module，并设置 id: preprocessor
如果流程需要失败处理器，请创建 value.failure_module，并设置 id: failure
不要在 value.modules 中创建名为 preprocessor 或 failure 的常规模块
preprocessor_module 和 failure_module 仅支持 script 或 rawscript
preprocessor_module 在常规模块之前运行，且不能引用 results.*
failure_module 可以使用 error 对象中的 error.message、error.step_id、error.name 和 error.stack
即使流程运行了 failure_module，最终状态仍为失败；除非处理器返回带有 recover: true 的对象，此时流程最终状态为成功。即使失败步骤位于循环、分支或子流程中，也适用此规则。recover 永远不会改变哪些步骤会运行；循环或分支在失败后是否继续，仍由其自身设置（skip_failures、continue_on_error）决定

正确结构：

value:
  preprocessor_module:
    id: preprocessor
    value:
      type: rawscript
      ...
  failure_module:
    id: failure
    value:
      type: rawscript
      ...
  modules:
    - id: process_event
      value:
        type: rawscript
        ...

错误结构：

value:
  modules:
    - id: preprocessor
      ...
    - id: process_event
      ...
    - id: failure
      ...

模块 ID 规则

在整个流程中必须唯一
使用下划线，不要使用空格（例如，使用 fetch_data，而不是 fetch data）
使用能体现步骤用途的描述性名称

AI Agent 模块

aiagent 模块运行一个可以调用工具的大模型。value.tools 中的每个条目都是一个形似模块的对象，并带有额外的 value.tool_type：脚本／流程工具使用 flowmodule，MCP 服务工具使用 mcp，网页搜索使用 websearch，内置的 ask_question 工具使用 question（Agent 会停止运行，不占用工作进程，直到有人在运行页面或聊天中作答；value.timeout 可选，单位为秒，默认值为 1800）。在 flowmodule 或 mcp 工具上设置 requires_approval: true，即可在每次调用运行前由人员批准或拒绝。

{
  "id": "support_agent",
  "summary": "AI agent for customer support",
  "value": {
    "type": "aiagent",
    "input_transforms": {
      "provider": {
        "type": "static",
        "value": { "kind": "openai", "resource": "$res:f/ai_providers/openai", "model": "gpt-4o" }
      },
      "output_type": { "type": "static", "value": "text" },
      "user_message": { "type": "javascript", "expr": "flow_input.query" },
      "system_prompt": { "type": "static", "value": "You are a helpful assistant." }
    },
    "tools": [
      {
        "id": "search_docs",
        "summary": "search_documentation",
        "description": "Search the product documentation. Use it whenever the user asks how a feature works.",
        "value": {
          "tool_type": "flowmodule",
          "type": "rawscript",
          "language": "bun",
          "content": "export async function main(query: string) { return ['doc1', 'doc2']; }",
          "input_transforms": { "query": { "type": "static", "value": "" } }
        }
      }
    ]
  }
}

provider 是一个对象，而不是一个单独的资源字符串：{ "kind": <provider kind>, "resource": "$res:<path>", "model": <model id> }。除非模块通过 value.agent 链接到已保存的 Agent，否则此项为必填项。从表单运行流程时，使用静态配置即可；聊天流程则会将其字段连接到流程输入——详见下文

聊天模式流程

设置了 value.chat_input_enabled: true 的流程会通过聊天而不是表单运行：消息输入框每轮发送一条消息，并呈现整个对话。流程需要一个必填的 user_message 字符串输入，供 Agent 读取。消息输入框本身不会编辑的其他流程输入，会在“配置输入”中询问。

静态的 provider 会导致聊天无法更改模型。 可以通过流程输入为其赋值，方式有两种：一个承载整个对象的输入（"expr": "flow_input.model_config"）会让每个字段都可编辑；也可以逐个连接字段，固定部分字段并显示其他字段。聊天可以写入的字段会成为消息输入框中的控件——提供商选择器、模型列表、思考控制项等；静态字段则保持固定，不会显示控件。kind 是唯一例外：只有与 resource 一起设置时，消息输入框才会写入 kind，因为提供商是成对选择的。因此，单独连接的 kind 输入仍会在“配置输入”中作为待填写项，而运行所需的内容不会因此变得无法访问。

{
  "id": "chat_agent",
  "value": {
    "type": "aiagent",
    "input_transforms": {
      "provider": {
        "type": "javascript",
        "expr": "({ kind: 'anthropic', resource: '$res:f/ai/claude', model: flow_input.model, reasoning_effort: flow_input.thinking })"
      },
      "user_message": { "type": "javascript", "expr": "flow_input.user_message" },
      "user_attachments": { "type": "javascript", "expr": "flow_input.files" },
      "memory": { "type": "static", "value": { "kind": "compaction" } },
      "streaming": { "type": "static", "value": true },
      "output_type": { "type": "static", "value": "text" }
    },
    "tools": []
  }
}

逐个连接字段时，必须使用一个对象字面量，其值为字面量或不带其他内容的 flow_input.x 引用。扩展运算符、函数调用或计算属性键都会导致消息输入框无法判断哪个输入对应哪个字段，因此不会提供任何控件——如果整个对象直接使用 flow_input.x，则会将其视为一个包含所有字段的输入
链接到已保存 Agent 的步骤（已设置 agent）自身没有 provider。它通过 model 和 reasoning_effort 输入提供相同的两个控件，用来替换 Agent 中保存的设置："model": { "type": "javascript", "expr": "flow_input.model" }。模型为空时会保留已保存的模型，effort 为空时不会发送任何值，提供商资源则始终使用 Agent 的资源
memory 使 Agent 能够看到先前的轮次；没有它，每条消息都会从头开始
启用 streaming 后，答案和思考过程会逐个 token 显示，而不是一次性显示
user_attachments 指向一个类型为 S3 对象数组的流程输入（{ "type": "array", "items": { "type": "object", "resourceType": "s3object" } }），这样随消息发送的文件就能传给 Agent
运行时需要一个 memory_id 查询参数，而不是流程参数，用于指定该轮所属的对话：新的 UUID 会启动一个对话，重复使用 UUID 则会继续该对话。聊天会自动提供此参数；通过其他方式运行时，必须传入此参数，否则服务器会拒绝该任务

工具命名规则

这些规则适用于 flowmodule 工具，也就是 Agent 按名称调用的工具。websearch 或 question 工具的 summary 是普通标签（Web Search），而 mcp 工具会公开 MCP 服务自身的工具名称，因此完全不会检查名称——这些工具的 summary 保持不变。

summary 是 Agent 调用工具时使用的名称，不是面向用户的标签。将易于理解的说明写在 description 中
summary 必须匹配 ^[a-zA-Z0-9_]+$：只能包含字母、数字和下划线。不能有空格、连字符、点号或重音符号——应使用 search_documentation，而非 Search documentation
始终设置 summary。它在该 Agent 的工具中必须唯一，且不能是保留 ID（do、bg、ctx、state、if、else、for、delete、while、new、in、 failure、preprocessor、as、Input、Result、Trigger）之一
工具名称包含上述字符集之外的字符时，任何将该工具提供给 Agent 的运行都会失败，并显示 Invalid tool name。 wmill lint <flow folder> 会在任何内容运行前报告此问题
工具 id 遵循与任何模块 ID 相同的规则——在整个流程中唯一，使用下划线而非空格
description 是可选的自由文本，用于告诉 Agent 何时以及如何调用工具。如果仅凭名称无法清楚说明，就应设置它；它会覆盖根据底层脚本生成的说明

AI 决策模块

aidecision 模块会向决策模型（TypeSafe 的 Jev、Cloudflare 的 Clef 或 OpenAI 的 Decisions API）提出关于某个 state 的类型化问题，并为每个问题返回经过校准的概率，而非文本。如果某个步骤属于判断（分类、路由、评分或是/否检查），无需工具也无需自由文本，优先使用它而非 aiagent：它速度更快、成本更低，且返回结果的结构固定。

{
  "id": "triage",
  "summary": "Classify the ticket",
  "value": {
    "type": "aidecision",
    "input_transforms": {
      "provider": {
        "type": "static",
        "value": { "kind": "typesafe", "resource": "$res:f/ai/typesafe", "model": "jev-latest" }
      },
      "state": { "type": "javascript", "expr": "flow_input.message" },
      "questions": {
        "type": "static",
        "value": {
          "intent": {
            "type": "choice",
            "instructions": "What does the customer want?",
            "criteria": { "refund": "Money back", "bug": "Something is broken", "other": "Anything else" }
          },
          "urgency": {
            "type": "score",
            "instructions": "How urgent is the ticket?",
            "criteria": ["Can wait", "This week", "Today", "Right now"]
          },
          "angry": { "type": "noul", "instructions": "Is the customer angry?" }
        }
      }
    }
  }
}

provider.kind 为 typesafe（除非固定某个版本，否则 model 为 jev-latest）、cloudflare （model 为 clef，或使用 clef-flash 获得更快的回答）或 openai（model 为 gpt-6-luna，不能使用 chat model）；资源必须与其类型相同
state 是要评估的内容：通常是文本，例如要分类的消息。若要组合多个值，请传入一个对象，其中包含说明性键，且仅包含问题所需的内容（({ message: flow_input.message, plan: results.get_account.plan })）；字符串数组也可用
questions 将每个问题名称映射到 { type, instructions, criteria }：
- choice：criteria 将每个选项映射到其说明（最多 255 个选项）。答案包含 choice、probabilities 和 confidence
- score：criteria 是一个包含 2 到 10 个等级说明的有序数组。答案包含 score、legend、probabilities 和 confidence
- noul：是/否，criteria 可选地包含 { "true": ..., "false": ... } 说明。答案包含 noul，即是的概率，范围为 0 到 1
结果为 { output, model, usage }，其中 output 按问题名称作为键，因此后续步骤可以读取 results.triage.output.intent.choice、results.triage.output.urgency.score 或 results.triage.output.angry.noul > 0.7
在 openai 中，同一组 questions 会转换为其 Decisions API 所需的格式，答案读取方式也相同（choice、score、noul），但 probabilities 是 { value, probability } 的列表（score 还包含 label），且评分结果不含 legend。如果 OpenAI 拒绝回答某个问题，该步骤就会失败。state 如果是用户消息数组（[{ role: "user", content: [{ type: "input_text", text }, { type: "input_image", image_url: "data:image/png;base64,..." }] }]），会按原样发送，这也是评估图像的方式；其他对象或数组则会作为 JSON 文本发送

根据答案分支

要根据答案进行路由，请在决策步骤后立即放置一个 branchone，每个选项对应一个分支，并让每个 expr 都按 ID 读取决策结果：

{
  "id": "route",
  "value": {
    "type": "branchone",
    "branches": [
      { "summary": "refund", "expr": "results.triage.output.intent.choice === 'refund'", "modules": [...] },
      { "summary": "bug", "expr": "results.triage.output.intent.choice === 'bug'", "modules": [...] }
    ],
    "default": [...]
  }
}

对于是／否问题，设置一个分支，其表达式为 "expr": "results.triage.output.angry.noul >= 0.5"（根据需要调整阈值），并将 default 设为“否”路径。

作为 Agent 工具

aidecision 可以作为 aiagent 的 flowmodule 工具（"tool_type": "flowmodule", "type": "aidecision"）：将 state 设为 { "type": "ai" }，由调用模型提供该值，并且只有 output 会返回给模型。其 summary 需遵循工具命名规则。只有流程自身的 Agent 步骤可以调用它，不能通过用作工具的 Agent 调用。

常见错误

缺少 input_transforms：没有它们，Rawscript 参数将无法接收值
引用后续步骤：results.step_id 仅适用于当前步骤之前执行的步骤
模块 ID 重复：流程中的每个模块 ID 都必须唯一
AI Agent 的 flowmodule 工具名称中包含空格：summary 就是工具名称，且只允许使用字母、数字和下划线

步骤间的数据流

flow_input.property - 访问流程输入参数
results.step_id - 仅当某个先前步骤的结果处于作用域内时，访问该步骤的输出
results.step_id.property - 仅当某个先前步骤的结果处于作用域内时，访问该步骤输出中的特定属性
flow_input.iter.value - 在 forloopflow 中访问当前迭代值；在 whileloopflow 中，它只是迭代索引（普通数字，与 flow_input.iter.index 相同）
flow_input.iter.index - 在循环内（forloopflow 或 whileloopflow）访问当前循环索引
在挂起步骤（审批）之后，下一步骤的 JavaScript 表达式还会获得：
- resume - 上一次恢复时的载荷（恢复表单值）；使用 continue_on_disapprove_timeout 时，拒绝或超时将改为返回 { error: { name: "SuspendedDisapproved" | "SuspendedTimedOut", message } }
- resumes - 按到达顺序排列的所有恢复载荷
- approvers - 一个普通字符串数组，每次恢复对应一个字符串：如果通过 getResumeUrls(approver) 生成的 resume／cancel URL 恢复，则为传入该函数的 approver（如果有）；否则（包括通过 approvalPage 链接恢复），为恢复用户的用户名；如果没有用户名，则为 "anonymous"，例如 approvers[0]。它不是流程状态中存储的 { resume_id, approver } 对象，因此 approvers[0].approver 始终为 undefined

循环结构规则

forloopflow 会针对 iterator 的每个元素运行一次其 modules；iterator 是一个返回数组的 JavaScript 表达式（例如 results.get_items）；parallel: true 会并发运行各次迭代，skip_failures: true 会在某次迭代失败后继续运行
对于 whileloopflow，使用模块级别的 stop_after_if 来中断循环：可以放在循环模块本身，也可以放在内部步骤上（当该步骤通过自身的 results 携带状态时必须放在步骤上，见下文）
stop_after_if 始终是流程模块上与 id 和 value 同级的字段，绝不能是循环 value 对象的直接键
stop_after_all_iters_if 用于在整个循环结束后进行检查，而非用于常规的逐次迭代中断条件
stop_after_if 会在每次迭代后求值：在循环模块上时，result 是该次迭代的结果（即最后一个步骤返回的值）；在内部步骤上时，result 是该步骤的结果
whileloopflow 中的 flow_input.iter.value 只是迭代索引（与 flow_input.iter.index 的值相同），不会携带状态，因此 flow_input.iter.value.<field> 始终为 undefined，且依赖它的循环停止条件永远无法满足
若要在迭代间传递状态，步骤应通过 results.<its_own_id> 读取自身上一轮迭代的结果，并设置首轮迭代的回退值（例如 results.b ?? flow_input.start）——但此时循环的 stop_after_if 必须放在该内部步骤上，而不能放在循环模块上：若循环体恰好只有一个普通步骤，且停止条件放在循环模块上，就会走快速路径，导致每次迭代中的 results.<step_id> 都为 null，循环永远无法终止（循环体包含 2 个或更多步骤，或其单个步骤自带 stop_after_if、重试等配置时，无论停止条件放在哪里，results 都会跨迭代解析）
若要传递的状态只是计数器，应改为根据索引计算（例如 flow_input.iter.index + 1）——这种方式适用于所有配置，包括在循环模块上使用 stop_after_if 的情况
若用户需要循环结束后的标量或对象，应在循环后添加一个普通步骤，从循环结果中提取最终值，而不是返回整个循环结果数组

正确的 whileloopflow 结构：

- id: loop_until_done
  stop_after_if:
    expr: result.done === true
    skip_if_stopped: false
  value:
    type: whileloopflow
    skip_failures: false
    modules:
      - id: advance_state
        value:
          type: rawscript
          input_transforms:
            count:
              type: javascript
              expr: flow_input.iter.index + 1
- id: return_final_state
  value:
    type: rawscript
    input_transforms:
      final_state:
        type: javascript
        expr: results.loop_until_done[results.loop_until_done.length - 1]

通过 results 携带状态的正确 whileloopflow 结构（停止条件放在内部步骤上）：

- id: loop_until_done
  value:
    type: whileloopflow
    skip_failures: false
    modules:
      - id: advance_state
        stop_after_if:
          expr: result.done === true
          skip_if_stopped: false
        value:
          type: rawscript
          input_transforms:
            state:
              type: javascript
              expr: results.advance_state ?? flow_input.initial_state

错误的 whileloopflow 模式：

- id: loop_until_done
  value:
    type: whileloopflow
    stop_after_if:
      expr: result.done === true

input_transforms:
  state:
    type: javascript
    # iter.value is a number (the iteration index); there is no previous-iteration state
    expr: flow_input.iter.value.count

input_transforms:
  final_state:
    type: javascript
    expr: results.loop_until_done

审批 / 暂停结构

审批步骤是一个普通的 script 步骤（type: rawscript 或 type: script），添加模块级别的 suspend 后即可将其变为审批步骤。其脚本会调用 wmill.getResumeUrls(approver) 来生成机密的恢复 / 取消 URL，并返回这些 URL，以便发送给审批人（Slack、电子邮件等），或从运行页面进行审批。

suspend 应放在流程模块对象上，与 id 和 value 同级
绝不要将 suspend 放在 value 内
不要对审批步骤使用 type: identity。identity 步骤会暂停，但不会生成恢复 URL，因此审批人没有可操作的链接——这不是有效的审批步骤。

正确结构：

- id: request_approval
  suspend:
    required_events: 1
    resume_form:
      schema:
        type: object
        properties:
          comment:
            type: string
        required: [comment]
  value:
    type: rawscript
    language: bun
    input_transforms:
      approver:
        type: static
        value: ''
    content: |
      import * as wmill from "windmill-client"

      export async function main(approver?: string) {
        const urls = await wmill.getResumeUrls(approver)
        // send urls.resume / urls.cancel to the approver(s), e.g. via Slack or email
        return urls
      }

错误结构（suspend 错误地放在 value 内）：

- id: request_approval
  value:
    type: rawscript
    suspend:
      required_events: 1

错误结构（identity 不会生成恢复 URL，因此不是真正的审批步骤）：

- id: request_approval
  suspend:
    required_events: 1
  value:
    type: identity

分支结果作用域规则

branchone 按顺序运行其 branches 中第一个 expr 为 true 的分支；如果没有，则运行其 default 模块；branchall 则运行所有分支（parallel: true 时并发运行）
在分支内，可以引用之前的外层步骤和同一分支内之前的步骤
在 branchone 外部，禁止引用仅存在于其分支或默认分支中的步骤 ID。请改用 results.<branchone_module_id>
在 branchall 外部，禁止引用其分支中的步骤 ID。请改用 results.<branchall_module_id>
如果后续步骤在分支运行后需要稳定的数据结构，请确保每个分支返回相同的字段
必要时，在分支后立即添加一个标准化步骤，并在该步骤中使用 results.<branch_module_id>

branchone 后的正确示例：

- id: route_order
  value:
    type: branchone
    ...
- id: send_confirmation
  value:
    input_transforms:
      routed:
        type: javascript
        expr: results.route_order

branchone 后的错误示例：

expr: results.create_shipment
expr: results.create_backorder

branchall 后的正确示例：

- id: enrich_parallel
  value:
    type: branchall
    parallel: true
    ...
- id: combine_data
  value:
    input_transforms:
      enrichments:
        type: javascript
        expr: results.enrich_parallel

输入转换

每个 rawscript 模块都需要 input_transforms，用于将函数参数映射到值：

静态转换（固定值）： {"param_name": {"type": "static", "value": "fixed_string"}}

JavaScript 转换（动态表达式）： {"param_name": {"type": "javascript", "expr": "results.previous_step.data"}}

资源引用

对于流程输入：使用类型 "object"，格式为 "resource-{type}"（例如，"resource-postgresql"）
对于步骤输入：使用静态值 "$res:path/to/resource"

重用现有脚本和流程

除非用户要求编写新代码，否则请先查找工作区中是否已有脚本或流程可完成某个步骤的任务，并按路径重用，而不是将其逻辑复制到 rawscript 中：

工作区脚本：type: script，带有 path（例如，f/folder/send_email）
工作区流程，作为子流程运行：type: flow，带有 path
Hub 脚本：type: script，路径为 hub/<version>/<app>/<name>

该步骤的 input_transforms 必须涵盖所重用项目的输入，因此请先读取其输入架构。在本地目录树和工作区中查找候选项（每个脚本旁边都有一个 .script.yaml 文件，其中包含其输入架构；每个流程文件夹中都有一个 flow.yaml），并使用 wmill script list / wmill flow list；wmill script get <path> 和 wmill flow get <path> 可显示项目详情。

给 AI 的补充提示词

流程的输入架构可以包含顶层 prompt_for_ai 字符串，脚本也可以包含：这是作者给 AI 的指示，用于指导 AI 选择输入。选择运行该流程的参数时，请遵循此指示；重写架构时也请保留该指示。

整理流程：分组与备注

分组和备注会影响流程在编辑器中的呈现方式，但都不会改变流程的行为。

每个非简单流程都应主动分段并分组，无需等待对方提出要求。 只要流程包含不止几个步骤，或连续步骤构成一个阶段（“获取”“转换”“通知”），就应将它们放入分组，并尽量让每个有意义的步骤都归入某个分组。谨慎使用备注，仅用于说明不适用于任何一段步骤的全流程信息：流程用途、关键假设、警告、TODO。通常一条备注就够了；不要用备注标注一连串步骤，这正是分组的用途。

value.groups 列出各个分组，每个分组覆盖从 start_id 到 end_id 的步骤：

start_id、end_id（必填）：分组中首个和最后一个步骤的 ID；若两者 ID 相同，则表示单步骤分组
summary：分组标题
note：标题下方显示的 Markdown 文本
color：可选值为 yellow、blue、green、purple、pink、orange、red、cyan、lime、gray；不得使用十六进制代码或 CSS 颜色；省略时由编辑器选择
autocollapse：设为 true 时，分组默认折叠

如果分组违反以下任何规则，编辑器就无法绘制流程：

start_id 和 end_id 必须属于同一列表中的步骤：二者都在顶层，或都在同一个循环体或分支中。分组可以完整包含一个循环或分支步骤，但不能从其外部开始、在其内部结束
在该列表中，start_id 不得位于 end_id 之后
分组可以嵌套（一个完全位于另一个内部），但不得部分重叠；也不得有两个分组同时使用相同的 start_id 和 end_id
分组只能包含普通步骤：不得包含 preprocessor、failure、Input、Result、Trigger 或 AI Agent 的工具

value.notes 列出便笺，每条便笺都包含唯一的 id、Markdown 格式的 text、取自同一列表的 color，以及 type: free。group 备注类型已弃用；请改用 value.groups。为每条便笺指定 position（{ x, y }）和 size（{ width, height }）：如果未指定，编辑器会在原点绘制便笺，且无法调整其大小。设置 x: -400 和 width: 275 可将便笺放在图表旁边。

最终结构自检

定稿流程前，请确认：

任何预处理器都位于 value.preprocessor_module 中
任何失败处理器都位于 value.failure_module 中
任何审批步骤都有模块级 suspend
下游步骤不会从分支外部引用分支内部步骤 ID
每个 AI Agent flowmodule 工具都有唯一的 summary，且仅由字母、数字和下划线组成
每个分组的起点和终点都属于同一列表中的步骤，起点在终点之前，分组可嵌套但不会部分重叠
wmill lint <flow folder> 未报告任何错误

S3 对象操作

Windmill 内置支持与 S3 兼容的存储操作。

要将 S3 对象作为流程输入：

{
  "type": "object",
  "properties": {
    "file": {
      "type": "object",
      "format": "resource-s3_object",
      "description": "File to process"
    }
  }
}

在流程中使用资源

在 Windmill 中，凭据和配置存储在资源中。资源类型定义了资源的格式。

作为流程输入

在流程架构中，将属性类型设为 "object"，格式设为 "resource-{type}"：

{
  "type": "object",
  "properties": {
    "database": {
      "type": "object",
      "format": "resource-postgresql",
      "description": "Database connection"
    }
  }
}

找不到合适的资源类型时

连接仍应作为一个资源输入传入，而不是拆分为单独的字符串输入（例如 URL、令牌），也不是在步骤内读取变量：将输入类型设为 resource-c_<name>，并使用自定义资源类型来存储服务的连接字段；将密钥放在资源所引用的变量中。自定义类型的 c_ 前缀可将其与之后可能以相同名称从 hub 同步的类型区分开来。

如果实例显示尚未同步 Windmill Hub 的资源类型，请说明超级管理员可以执行同步，因为 hub 已为大多数服务提供资源类型。
否则，或用户倾向于不通过同步来解决时，请提出资源类型方案，并在创建前征求同意。
如果用户提出使用普通变量，也可以使用。

作为步骤输入（静态引用）

使用 $res: 前缀引用特定资源：

{
  "database": {
    "type": "static",
    "value": "$res:f/folder/my_database"
  }
}

OpenFlow 架构

支持 Markdown

登录后评论

基本信息

作者: windmill-labs
仓库: windmill-labs/windmill-cli-docs
分类: 开发
安装次数: 41
GitHub Stars: 5

报告问题

write-flow

关于 write-flow

主要功能

适用场景

安装

详细介绍

Windmill Flow CLI 指南

创建 Flow

第 1 步——询问用户路径和摘要

第 2 步——自行运行命令

第 3 步——填写 flow.yaml

应避免的反模式

CLI 命令 — 运行、预览、部署

预览与运行 — 根据意图选择，不要习惯性操作

单步与全流程预览

编写完成后——主动提出运行，不要被动等待

视觉预览

Windmill 流程构建指南

OpenFlow 架构

保留的模块 ID

严格结构规则

模块 ID 规则

AI Agent 模块

聊天模式流程

工具命名规则

AI 决策模块

根据答案分支

作为 Agent 工具

常见错误

步骤间的数据流

循环结构规则

审批 / 暂停结构

分支结果作用域规则

输入转换

资源引用

重用现有脚本和流程

给 AI 的补充提示词

整理流程：分组与备注

最终结构自检

S3 对象操作

在流程中使用资源

作为流程输入

找不到合适的资源类型时

作为步骤输入（静态引用）

OpenFlow 架构

评论

第 3 步——填写 `flow.yaml`