write-flow

Name: write-flow
Author: windmill-labs

github.com/windmill-labs開発541 回インストール1 日前に更新

リポジトリ

write-flow について

write-flowは、Windmill CLIでWindmillのワークフローを作成・テストするAIエージェント向けガイドです。正しい初期化と構造ルールを示し、ユーザーの意図に応じてローカルプレビューとデプロイを使い分けます。

主な機能

01`wmill flow new`による初期化
02OpenFlowルールに沿ったモジュール定義
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 エージェントであるあなた自身が、適切なフラグを付けて wmill flow new <path> を実行し、フローのひな形を作成します。フォルダーと flow.yaml を手動で作成してはいけません。また、ユーザーに「wmill flow new を実行して、プロンプトに従ってください」と伝えてはいけません。

wmill flow new は、正しいサフィックス（ワークスペースの nonDottedPaths 設定に応じて __flow または .flow）を付けてフォルダーを作成し、最小限の flow.yaml のひな形を書き込み、Claude 固有の次の手順に関するヒントを表示します。手動でひな形を作成すると、これらがすべて省略され、サフィックスも誤りがちです。

Step 1 — ユーザーに尋ねてパスと概要を確認する

必要な情報は次の 2 つです。

path — windmill のパスです。例：f/folder/my_flow または u/username/my_flow。
summary — フローの簡単な説明です。

ユーザーの依頼に両方の情報が含まれていない場合は、1 回のやり取りで両方を尋ねます。実行環境で利用できる対話型の質問機能（利用可能であれば構造化された複数選択ツール、そうでなければ通常のチャット）を使い、それぞれに 1 つまたは 2 つの入力例と、「その他」／自由入力の選択肢を用意します。パスや概要を推測してはいけません。

Step 2 — 自分でコマンドを実行する

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

概要とは別に残す価値のある詳しい説明をユーザーから受け取っている場合は、--description "..." を追加します。

Step 3 — `flow.yaml` を記入する

生成された flow.yaml（コマンドが作成したフォルダー内）を開き、空の value.modules と schema を実際のフロー定義に置き換えます。

rawscript モジュールでは、コンテンツキーに !inline path/to/script.ts を使用します。インラインスクリプトファイルの名前に .inline_script. を含めてはいけません（例：a.inline_script.ts ではなく a.ts を使用します）。

フローに実際の内容が入ったら、次の手順としてビジュアルプレビューを開くことを一文で提案します（例：「ビジュアルプレビューを開きますか？」）。自動的に開いてはいけません。開発ページを開くと、ブラウザーウィンドウや 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 をローカルのインラインスクリプトに対して実行します。PathScript ステップでローカルファイルの代わりにデプロイ済みのワークスペーススクリプトを使用するには、--remote を追加します。モジュールを1つだけ単独で実行するには、--step <step_id> を追加します（以下の「単一ステップのプレビューとフロー全体のプレビュー」を参照）。
wmill flow run <path> — ワークスペースにすでにデプロイされているフローを実行します。デプロイ済みバージョンのテストをユーザーが明示的に希望している場合に限って使用してください。ローカルの編集内容には使用しないでください。
wmill generate-metadata — フローとそのインラインスクリプトの古くなったローカル .lock ファイルを再生成し、wmill-lock.yaml 内のコンテンツハッシュを更新します。ローカルファイルのみを書き換えます（デプロイではありません）。インポートまたは引数を変更するインラインスクリプトを編集した後に実行し、wmill-lock.yaml がずれて git-sync／CI に不要なノイズが追加されないようにしてください。デフォルトではワークスペース全体のスクリプト、フロー、アプリをスキャンしますが、古くなったものだけを再生成します。対象を編集したフローに絞るには、そのフローのフォルダーを引数として渡すか、そのサブディレクトリから実行してください。変更された共有スクリプトをインポートするフロー（またはスクリプト）も対象になることに注意してください。適用前に何が古くなっているか、その理由（content changed か depends on <path> か）を正確に確認するには、wmill generate-metadata --dry-run を実行してください。
ローカルの変更をワークスペースにデプロイします — リポジトリの設定に応じて、git push または wmill sync push を使用します（AGENTS.wmill.md のデプロイセクションを参照）。ユーザーがデプロイ／公開／プッシュを明示的に希望した場合に限って、デプロイを提案または実行してください。「実行」「試す」「テストする」と言われただけの場合は、デプロイしないでください。

プレビューと実行 — 習慣ではなく、意図に応じて選ぶ

ユーザーが「フローを実行して」「試して」「テストして」「動くか確認して」と言い、flow.yaml にローカルの編集内容がある場合は、flow preview を使用してください。フローをプッシュしてから flow run を実行してはいけません。プッシュはデプロイであり、テストのためだけにデプロイすると、未テストの変更でワークスペースのバージョンが上書きされます。

flow run を使用するのは、次の場合に限ります。

ユーザーが「デプロイ済みのバージョンを実行して」／「サーバー上のものを実行して」と明示的に指示した場合。
編集中のローカル flow.yaml がなく、既存のフローを呼び出すだけの場合。

sync push を使用するのは、次の場合に限ります。

ユーザーがデプロイ、公開、プッシュ、またはリリースを明示的に希望した場合。
プレビューで変更がすでに検証されていて、ユーザーがそれをワークスペースに反映したい場合。

単一ステップのプレビューとフロー全体のプレビュー

ユーザーが1つのモジュールを反復編集しており、検証対象にフローの上流ステップが含まれない場合は、flow preview <flow_path> --step <step_id> を使用してください。そのステップの実行可能なもの（rawscript の場合はインラインスクリプト、script の場合は PathScript〔利用可能であればローカルのもの〕、flow の場合はパスで指定するサブフロー）だけを実行するため、前のステップに時間や費用がかかる場合、フロー全体を実行するより大幅に速くなります。ステップ ID は、入れ子になった branchone／branchall／forloopflow／whileloopflow モジュールをたどって解決されます。また、特別な preprocessor モジュールと failure モジュールも含まれます。

各ステップが互いの出力に依存する場合、ユーザーが全体の制御フローを検証している場合、または --step を適用できない場合は、flow preview <flow_path>（--step なし）を使用してください。branchone、branchall、forloopflow、whileloopflow、identity、および AI エージェントの各ステップは、それ自体を単独でテストできません。ただし、branchone／branchall／forloopflow／whileloopflow の場合は、内部のステップ ID を渡せば、その中に含まれるステップをテストできます。

作成後 — 実行を提案し、受け身で待たない

これはプログラムによる実行（wmill flow preview -d '<args>'）についての説明です。実際にフローを実行するため、副作用が発生します。ビジュアルプレビュー（preview スキル）は別途提案します。下の「ビジュアルプレビュー」を参照してください。

ユーザーがまだフローの実行やテストを依頼していない場合は、次のステップとして1文で提案してください（例：「サンプル引数を使って 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 スキルを使用してください。自動で開くのではなく、次のステップとして必ず1文で提案してください（例：「ビジュアルプレビューを開きますか？」）。開発ページを開くと副作用（ブラウザーウィンドウの表示や、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 のエントリーではありません
フローでプリプロセッサーが必要な場合は、id: preprocessor を指定して value.preprocessor_module を作成します
フローで失敗ハンドラーが必要な場合は、id: failure を指定して value.failure_module を作成します
preprocessor または failure という名前の通常モジュールを value.modules 内に作成してはいけません
preprocessor_module と failure_module で使用できるのは script または rawscript のみです
preprocessor_module は通常のモジュールより先に実行され、results.* を参照できません
failure_module では、error.message、error.step_id、error.name、error.stack を含む error オブジェクトを使用できます
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 エージェントモジュール

aiagent モジュールは、ツールを呼び出せる LLM を実行します。value.tools の各エントリは、追加の value.tool_type を持つモジュール形式のオブジェクトです。script／flow ツールには flowmodule、MCP サーバーツールには mcp、ウェブ検索には websearch、組み込みの ask_question ツールには question を指定します（エージェントは停止し、実行ページまたはチャットから誰かが回答するまでワーカーを占有しません。秒単位の任意の 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 を通じて保存済みエージェントにリンクされている場合を除き、必須です。フォームからフローを実行する場合は静的な設定が適しています。チャットフローでは、代わりにフィールドをフロー入力に接続します。詳細は以下を参照してください。

チャットモードのフロー

value.chat_input_enabled: true のフローは、フォームではなくチャットから実行されます。入力欄からターンごとに 1 つのメッセージが送信され、会話が表示されます。エージェントが読み取る、必須の文字列入力 user_message が必要です。入力欄で編集されないその他のフロー入力は、［入力の設定］で質問されます。

静的な provider では、モデルを変更できないチャットになります。 代わりにフロー入力から値を渡してください。方法は 2 つあります。オブジェクト全体を保持する 1 つの入力（"expr": "flow_input.model_config"）を使うと、すべてのフィールドを編集できます。または、フィールドごとに接続して、一部を固定し、その他を公開します。チャットから書き込めるフィールドは、入力欄にプロバイダー選択、モデル一覧、思考の制御などのコントロールとして表示されます。静的なままのフィールドは固定され、コントロールは表示されません。例外は kind です。プロバイダーは resource と組み合わせて選択されるため、入力欄から kind を書き込むのは resource と一緒の場合のみです。そのため、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 参照である、1 つのオブジェクトリテラルを使います。スプレッド、呼び出し、計算されたキーを使うと、入力欄はどの入力がどのフィールドに渡されるかを判別できないため、コントロールは一切表示されません。オブジェクト全体に対するそのままの flow_input.x は、すべてのフィールドを保持する 1 つの入力として読み取られます
保存済みエージェントにリンクされたステップ（agent が設定済み）には、独自の provider はありません。model と reasoning_effort の入力を通じて、同じ 2 つのコントロールを公開し、エージェントに保存された設定を置き換えます。"model": { "type": "javascript", "expr": "flow_input.model" } のように指定します。モデルが空なら保存済みのモデルが維持され、思考の強度が空なら何も送信されません。プロバイダーのリソースは常にエージェントのものが使われます
エージェントが前のターンを参照できるようにするには、memory が必要です。これがないと、メッセージごとに何もない状態から始まります
streaming をオンにすると、回答と思考が一度にすべてではなく、トークンごとに表示されます
user_attachments は、S3 オブジェクトの配列として型指定されたフロー入力を参照します（{ "type": "array", "items": { "type": "object", "resourceType": "s3object" } }）。これにより、メッセージに添付されたファイルがエージェントに届きます
実行には、ターンが属する会話を指定する memory_id クエリパラメーター（フロー引数ではありません）が必要です。新しい UUID を使うと会話が開始され、同じ UUID を再利用すると会話が続きます。チャットではこの値が自動的に渡されます。その他の方法で実行する場合は、値を渡す必要があります。渡さないと、サーバーはジョブを拒否します

ツールの命名規則

これらの規則は、エージェントが名前で呼び出す flowmodule ツールを対象とします。websearch ツールや question ツールの summary は単なるラベル（Web Search）であり、mcp ツールは MCP サーバー独自のツール名を公開するため、いずれも名前のチェック対象にはなりません。これらの summary はそのままにしてください。

flowmodule ツールの summary は、人間向けのラベルではなく、エージェントが呼び出す名前です。人間向けの説明は description に記載してください
summary は ^[a-zA-Z0-9_]+$ に一致する必要があります。使用できるのは英字、数字、アンダースコアのみです。スペース、ハイフン、ピリオド、アクセント記号は使用できません。Search documentation ではなく、search_documentation にしてください
必ず summary を設定してください。エージェントのツール間で一意である必要があり、予約済み ID（do、bg、ctx、state、if、else、for、delete、while、new、in、failure、preprocessor、as、Input、Result、Trigger）は使用できません
使用可能な文字以外を含むツール名をエージェントに提供すると、そのツールを提供する実行はすべて Invalid tool name で失敗します。wmill lint <flow folder> を実行すると、実行開始前に報告されます
ツールの id にも、モジュール ID と同じ規則が適用されます。フロー全体で一意である必要があり、スペースではなくアンダースコアを使用してください
description は任意の自由記述で、ツールをいつ、どのように呼び出すかをエージェントに伝えます。名前だけでは明らかでない場合は設定してください。基になるスクリプトから導出される説明よりも優先されます

AI Decision モジュール

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。チャットモデルは使用しません）です。リソースも同じ種類のものを指定してください
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 } のリスト（スコアの場合は label も含む）であり、スコアに legend はありません。OpenAI が回答を拒否した質問があると、ステップは失敗します。ユーザーメッセージの配列である state（[{ role: "user", content: [{ type: "input_text", text }, { type: "input_image", image_url: "data:image/png;base64,..." }] }]）はそのまま送信され、画像を評価する場合はこの形式を使用します。それ以外のオブジェクトや配列は JSON テキストとして送信されます

回答に基づく分岐

回答に応じて処理を振り分けるには、判定の直後に branchone を配置し、各選択肢に1つずつ分岐を設け、それぞれの 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" を指定した分岐を1つ用意し（しきい値は必要に応じて調整してください）、default を「いいえ」の経路にします。

エージェントツールとして

aidecision は、aiagent の flowmodule ツール（"tool_type": "flowmodule", "type": "aidecision"）として使用できます。state を { "type": "ai" } に設定すると、呼び出し元のモデルが値を指定し、output のみがモデルに返されます。summary にはツールの命名規則が適用されます。これを呼び出せるのは、フロー自身のエージェントステップのみであり、ツールとして使用されているエージェントからは呼び出せません。

よくある間違いとその回避方法

input_transforms がない：指定しないと、Rawscript のパラメーターに値が渡されません
後続のステップを参照する：results.step_id が機能するのは、現在のステップより前に実行されるステップのみです
モジュール ID の重複：フロー内の各モジュール ID は一意である必要があります
AI エージェントの 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）内の現在のループインデックスです
suspend ステップ（承認）の後、次のステップの JavaScript 式では以下も使用できます：
- resume - 直近の再開ペイロード（再開フォームの値）です。continue_on_disapprove_timeout を指定した場合、拒否またはタイムアウト時には代わりに { error: { name: "SuspendedDisapproved" | "SuspendedTimedOut", message } } が返されます
- resumes - 到着順に並んだ、すべての再開ペイロードです
- approvers - 再開ごとに1つの文字列を含む通常の配列です。getResumeUrls(approver) の resume／cancel URL を介して再開した場合は、そこで渡された approver（指定されている場合）が含まれます。それ以外（approvalPage リンクを含む）の場合は、再開したユーザーのユーザー名が含まれます。ユーザー名がない場合は "anonymous" となります。例：approvers[0]。フローのステータスに保存される { resume_id, approver } オブジェクトではないため、approvers[0].approver は常に undefined です

ループ構造のルール

forloopflow は、配列を返す JavaScript 式（例：results.get_items）である iterator の各要素に対して、modules を 1 回ずつ実行します。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> は常に未定義であり、これに依存する終了条件を持つループは終了しません
反復間で状態を保持するには、ステップで自身の前回の反復結果を results.<its_own_id> から読み取り、初回の反復用のフォールバックを指定します（例：results.b ?? flow_input.start）。ただし、この場合、ループの stop_after_if はループモジュールではなく、必ずその内側のステップに指定します。終了条件をループモジュールに置いた、通常のステップが 1 つだけの本体は、results.<step_id> がすべての反復で null になる高速パスで実行され、ループが終了しません（ステップが 2 つ以上ある本体、または 1 つだけのステップに独自の stop_after_if、リトライなどがある本体では、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 を生成し、承認者（Slack、メールなど）に送信するか、実行ページから承認できるように、それらの URL を返します。

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 にコピーせず、パスを指定して再利用します。

ワークスペースのスクリプト：path を持つ type: script（例：f/folder/send_email）
ワークスペースのフロー：サブフローとして実行する、path を持つ type: flow
Hub スクリプト：hub/<version>/<app>/<name> パスを持つ type: script

再利用するアイテムの入力を input_transforms で網羅する必要があるため、まず入力スキーマを確認します。ローカルツリー（各スクリプトの隣にある .script.yaml に入力スキーマが記載され、各フローフォルダーには flow.yaml があります）とワークスペースで、wmill script list ／ wmill flow list を使って候補を探します。wmill script get <path> と wmill flow get <path> でアイテムの詳細を確認できます。

AI 向けの追加プロンプト

フローの入力スキーマには、スクリプトと同様に、入力を選ぶ AI に対する作成者の指示として、トップレベルの prompt_for_ai 文字列を含めることができます。そのフローを実行する引数を選ぶときはこの指示に従い、スキーマを書き換える場合も保持してください。

フローの整理：グループとノート

グループとノートは、エディターでのフローの見え方を整えるものであり、フローの動作には影響しません。

特に指示されなくても、重要なフローはすべてグループに分割してください。 フローに数ステップを超える手順がある場合や、連続するステップが「取得」「変換」「通知」などの段階を構成する場合は、グループにまとめ、意味のあるステップがすべていずれかのグループに属するようにしてください。ノートは、フロー全体に関する情報で、ステップの範囲に属さないものに限って控えめに使用してください。たとえば、フローの目的、重要な前提、警告、TODO などです。通常はノートが 1 つあれば十分です。ステップのまとまりにノートを付けるのは避けてください。その用途にはグループを使います。

value.groups にはグループが列挙され、それぞれが start_id から end_id までのステップを含みます。

start_id、end_id（必須）：グループの最初と最後のステップの ID。同じ ID を指定すると、1 ステップだけのグループになります
summary：グループのタイトル
note：タイトルの下に表示される Markdown
color：yellow、blue、green、purple、pink、orange、red、cyan、lime、gray のいずれか。16 進数コードや CSS の色は指定できません。省略すると、エディターが色を選びます
autocollapse：true にすると、グループはデフォルトで折りたたまれた状態で表示されます

グループが以下のルールに違反しているフローは、エディターで描画できません。

start_id と end_id は同じリスト内のステップである必要があります。両方とも最上位にあるか、同じループ本体または分岐内にある必要があります。グループにループまたは分岐のステップ全体を含めることはできますが、その外側から始めて内側で終えることはできません
そのリスト内で、start_id は end_id より後に配置できません
グループは入れ子にできますが（片方がもう片方の中に完全に含まれる状態）、部分的に重なってはいけません。また、2 つのグループが start_id と end_id の両方を共有してはいけません
グループに含められるのは通常のステップだけです。preprocessor、failure、Input、Result、Trigger、AI エージェントのツールは含められません

value.notes には付箋が列挙されます。それぞれに、一意の id、Markdown の text、同じリストから選んだ color、および type: free が必要です。group のノートタイプは非推奨です。代わりに value.groups を使用してください。各ノートには position（{ x, y }）と size（{ width, height }）を設定してください。設定しない場合、エディターはノートを原点に描画し、サイズを変更できません。x: -400 と width: 275 を指定すると、グラフの横に配置できます。

最終的な構造のセルフチェック

フローを完成させる前に、以下を確認してください。

preprocessor が value.preprocessor_module にある
failure handler が value.failure_module にある
approval ステップにモジュールレベルの suspend がある
分岐の外側にある下流のステップが、分岐内のステップ ID を参照していない
すべての AI エージェントの 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 やトークン）やステップ内で読み取る変数ではなく、1 つのリソース入力として渡します。入力の型を 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 スター: 5

問題を報告

write-flow

write-flow について

主な機能

活用シーン

インストール

詳細

Windmill Flow CLI ガイド

Flow の作成

Step 1 — ユーザーに尋ねてパスと概要を確認する

Step 2 — 自分でコマンドを実行する

Step 3 — flow.yaml を記入する

避けるべきアンチパターン

CLI コマンド — 実行、プレビュー、デプロイ

プレビューと実行 — 習慣ではなく、意図に応じて選ぶ

単一ステップのプレビューとフロー全体のプレビュー

作成後 — 実行を提案し、受け身で待たない

ビジュアルプレビュー

Windmill フロー構築ガイド

OpenFlow スキーマ

予約済みモジュール ID

構造上の厳格なルール

モジュール ID のルール

AI エージェントモジュール

チャットモードのフロー

ツールの命名規則

AI Decision モジュール

回答に基づく分岐

エージェントツールとして

よくある間違いとその回避方法

ステップ間のデータフロー

ループ構造のルール

承認／一時停止の構造

ブランチ結果のスコープルール

入力変換

リソース参照

既存のスクリプトとフローの再利用

AI 向けの追加プロンプト

フローの整理：グループとノート

最終的な構造のセルフチェック

S3 オブジェクト操作

フローでのリソースの使用

フロー入力として使用する場合

適合するリソースタイプがない場合

ステップ入力として使用する場合（静的参照）

OpenFlow スキーマ

コメント

Step 3 — `flow.yaml` を記入する