running-flow

Robomotion Flow の実行

ロボット上でフローを実行し、エージェントモードのイベントストリームを監視して、失敗に対応します。必要な要素は次の4つです。

1. 事前チェック — robomotion validate <flow-dir> を実行すると、送信前に pspec／スキーマのエラーをローカルで1秒未満で検出できます。手軽なので、必ず最初に実行してください。
2. ロボット — このコンピューターに接続された、ユーザー自身のロボットです（Robomotion のデスクトップアプリ、またはユーザーの同意を得て robomotion robot connect を実行）。robomotion get robots で接続済みのロボットを確認できます。
3. トリガー — robomotion run <flow-dir> --robot <name> を実行すると、ローカルでビルドして送信し、イベントログをストリーミングします。
4. 監視 — run は JSONL セッションログを末尾まで追跡します。robomotion logs --last で再度読み取れます。実行は flow_end（または flow_error）イベントで完了します。agent_mode の開始／終了イベントが実行を囲む場合もありますが、それを待つ必要はありません。

Robomotion.ChatAssistant.ChatIn から始まるフローは、ここでは実行しないでください。 メッセージを送信するものがないため、--timeout まで待機することになります。実際のチャットページで running-chat-assistant スキル（robomotion agent）を使って、エージェントとしてテストしてください。

ブラウザーはありません。フローの判断材料はログだけです。 フローには画面がないため、正常に動作したかどうかを示すのはロボットのイベントだけです。イベントを確認し、flow_end status=success が記録されていない限り、実行が成功したと言わないでください。

手順1 — 検証（必須の事前チェック）

robomotion validate <flow-dir>           # exit 0 = pspec-clean, 1 = errors on stderr

ロボット側での作業を始める前に、「プロパティ名が間違っている」「存在しないノードタイプ」「無効なポート」といったエラーをすべて検出します。CLI は JSON を出力せずに、フローを再ビルドして検証します。省略しないでください — 実行ログの node_error イベントから pspec エラーを診断するより、validate の出力を読むほうがはるかに速いです。

validate に失敗した場合は、stderr を読み、main.ts を修正して、validate を再実行してください。終了コードが 0 になるまで繰り返してから、次に進みます。

robomotion run もビルド手順の一環として検証するため、不正なフローがロボットに到達することはありません。ただし、ネットワークの往復と Submitting flow for execution... のスピナーが終わった後に問題がわかります。最初に検証してください。

手順2 — ロボットはユーザー自身のものを使う

フローは、ユーザー自身のロボットのいずれかで実行します。robomotion run は、ロボットが自身のマシンに書き込むログを読み取って実行を追跡するため、ロボットはこのコンピューターに接続されている必要があります。通常は、デスクトップアプリですでに接続されています。

robomotion get robots        # which robots exist, and which are connected right now

プロジェクトで初めて実行するときは、ユーザーがすでに指定していない限り、どのロボットを使うかを一度だけ、短く尋ねてから --robot <name> に渡してください。CLI は選択内容をプロジェクトの .robomotion/run.json に記憶するため、そのフォルダーで以降 robomotion run を実行するときにフラグは不要です。使用するロボットがわからず、質問できるターミナルもない場合、run はロボットを表示して終了コード 3 で終了します。これは推測するのではなく、ユーザーに尋ねる合図です。（終了コード 3 には、下記のとおり、別のマシン上のロボットで実行された場合という意味もあります。）

ロボットは自身のマシンにイベントログを書き込みます（~/.config/robomotion/agent/logs/sessions/<studio_id>.jsonl）。ロボットがこのコンピューターにある場合、robomotion run はそのログを追跡します。

ユーザーのロボットがここに接続されていない場合（デスクトップアプリが実行されていない、またはここがサーバーである場合）は、ユーザーに一度尋ねてから、ユーザーとしてここに接続してください。

robomotion robot connect --robot "<name>"   # one of their Development/Production robots; remembered for this folder
robomotion robot status                     # what `robot connect` has running here
robomotion robot disconnect                 # when they are done

ユーザーのログイン情報を使い、デスクトップアプリと同じ方法でロボットを接続します。新しいロボットや新しいトークンが作成されることはなく、エージェントまたはアプリのロボット（robomotion agent start／robomotion app start で起動するロボット）への接続は拒否されます。robomotion 26.9.8 以降が必要です。

手順3 — 実行をトリガーする

robomotion run <flow-dir> --robot <name|id>        # the choice is remembered in .robomotion/run.json
robomotion run <flow-dir>                          # next time: the remembered robot (a picker when there is a terminal)
robomotion run                                     # defaults to main.ts in cwd

CLI には、フローディレクトリ（その中の main.ts に解決されます）または .ts ファイルを指定できます。実行内容は次のとおりです。

1. フローをビルドします（pspec に照らして検証し、エラーがあればすぐに失敗します）。
2. ロボットを解決します（--robot、次に .robomotion/run.json の順）。
3. 新しい studio_id を使って POST /v1/flows.agent.run を実行します（成功すると Session として表示されます）。

前提条件： 手順1（検証）がクリーンであること、プロジェクトでサインイン済みであること（robomotion auth whoami。robomotion create flow でサインイン済みになるため、そうでない場合は robomotion auth login --workspace <host> を実行）、ロボットが接続されていること（手順2）。

ステップ 4 — エージェントのイベントストリームを監視する

robomotion run はデフォルトでストリームを追跡します。deskbot が次の場所に書き込むセッションログファイルを追跡します。

~/.config/robomotion/agent/logs/sessions/<studio_id>.jsonl           (Linux/macOS)
%LOCALAPPDATA%\Robomotion\agent\logs\sessions\<studio_id>.jsonl      (Windows)

イベントは、1 行に 1 つの簡潔な JSON です。flow_end（または flow_error）で実行は終了します。その直後にストリームが停止し、その後に agent_mode end の行が出力されない場合があります。例：

{"event":"agent_mode","status":"start"}
{"event":"flow_start","flow":"Imported Write To Clipboard","version":"local","origin":"agent"}
{"event":"node_start","node":"Start"}
{"event":"node_end","node":"Start"}
{"event":"node_start","node":"Get Clipboard Data"}
{"event":"node_end","node":"Get Clipboard Data","duration_ms":4780}
{"event":"flow_end","status":"success","duration_ms":8852}
{"event":"agent_mode","status":"end"}

robomotion run の終了コード：

コード	意味
0	flow_end status=success
1	flow_end status=error または flow_error
2	追跡のタイムアウト（セッションはまだ実行中）— --timeout を増やすか、ログファイルを再読み込みしてください
3	ロボットが選択されていない（--robot がなく、記憶されたロボットもなく、質問できるターミナルもないため、ロボットの一覧が表示されます。使用するロボットを相手に尋ねてください）、または 実行は送信されたものの、ログがここに現れなかった — ロボットが別のマシンにあるため、ログはそのマシンにあります。後者の場合、ロボット上では実行が進行しています。進捗は Flow Designer で確認してください。出力を読んで、どちらの状況かを判断してください。

フラグ：--no-follow（実行のみ、ストリームなし）、--log-wait <s>（ファイルの出現を待つ時間。デフォルトは 5）、--timeout <s>（追跡の全体的な制限時間。デフォルトは 300）。

イベントリファレンス

イベント	フィールド	意味
agent_mode	status: "start" | "end"	実行を囲むように出力される場合があります。常に書き込まれるわけではなく、robomotion logs にも表示されません。決して出力を待たないでください。
flow_start	flow、version、origin	Flow が開始しました。robomotion run の場合、version は local、実行を開始した人を示す origin は "agent" です。
flow_end	status: "success" | "error"、duration_ms、error?	Flow が終了しました。実行は完了です。
flow_error	error、node?、node_id?、duration_ms	未処理の Flow レベルのエラーです。実行は完了です。
node_start	node	ノードに入りました。
node_end	node、duration_ms?	ノードが完了しました。一部のノード（トリガーなど）では duration_ms がありません。これに依存しないでください。
node_error	node、error、duration_ms	ノードで例外が発生しました。修正が必要であることを示します。
log	node?、level、msg	Core.Flow.Log の出力です。
debug	node、msg	Core.Programming.Debug のペイロードです（各フィールドは 255 バイトに切り詰められます）。
connected	msg	ロボットがワークスペースに登録されました。
ready	—	ロボットがコマンドを受け付ける準備ができました。

実行後に再読み込みする

robomotion run はストリーミング中にログを読み取ります。ファイルはその後も保持されます。robomotion logs は、ユーザーが読むイベント（flow_start、node_*、log、debug、flow_error、flow_end。agent_mode の行は含まれません）に絞って、ログを再読み込みします。最初の行には、読み取ったファイルを示す log: <path> ヘッダーが出力されます。

robomotion logs --last               # the newest run's events
robomotion logs --studio <id>        # one run, by the Session id `run` printed
robomotion logs --last -f            # follow a run still going
robomotion logs --last --raw         # every line, for jq

Step 5 — 検証 → 実行 → 状況確認 → 修正のループ

目標は自律的に反復することです（再試行回数に上限を設け、ユーザーから依頼があれば停止します）。

1. ローカルで検証する：robomotion validate <flow-dir> — 送信前に終了コードが 0 である必要があります。0 以外の場合は、stderr のレポートをもとに main.ts を修正し、このステップを繰り返します（既知の不具合があるフローを送信してはいけません）。
2. 送信する：robomotion run <flow-dir> --robot <name>（フラグを指定するのは初回のみ）— Session ID を記録します。
3. ログをストリーミングする：run は flow_end / flow_error までエージェントのログを自動的に追跡します。robomotion logs --last でログを再度読み取れます。
4. 分類する：
   • flow_end status=success（CLI 終了コード 0）→ 結果を報告し、生成されたファイルを開くか尋ねて（以下を参照）、停止します。
   • node_error または flow_error（CLI 終了コード 1）→ error と node を調べ、main.ts を修正して、ステップ 1 に戻ります。ユーザーに尋ねずに再試行できるのは最大 3 回です。
   • タイムアウト（CLI 終了コード 2）→ フローはロボット上で実行中の可能性があります。その旨を報告して尋ねます。
   • CLI 終了コード 3 → 出力を確認します。ロボットが選択されていない場合は、ロボットの一覧が表示されます。どれを使うか尋ねてから、--robot <name> を指定します。ログにアクセスできない場合は、ロボットが別のマシン上にあり、そのログもそこにあることを伝え、ロボットに何が表示されたかユーザーに尋ねるか、Flow Designer で進捗を確認するよう案内します。
5. 再試行の間、モック／テスト用フィクスチャは同じ状態に保ち、成功した実行が実際に修正を検証できるようにします。
6. 保存する：修正が成功したら、フローフォルダーで git add -A && git commit -m "..." && git push を実行します（commit -am では、新しい subflows/<id>.ts などのファイルは追加されません）。Designer にはプッシュされた内容が表示されます。実行すると main.designer.ts（キャンバスのレイアウト）が書き換えられるため、main.ts と一緒にコミットします。フローが実行前にすでに保存されていて、変更なしで成功した場合は、保存する必要はありません。まだ保存されておらず、ユーザーが作成、実行、正常動作の確認後の保存を依頼していた場合は、成功を示す実行の後に保存します。それが作業の最後のステップです。

実行が成功した後：生成されたファイルを開くか尋ねる

ファイルを書き出す実行は、ユーザーがそのファイルを確認するまで完了ではありません。ファイル名を伝えて、あとは自分で見つけてもらうだけでは不十分です。スプレッドシートを依頼し、作成されるのを見届けたなら、次にすることは当然、その中身を確認することです。

実行に成功して何か（スプレッドシート、CSV、PDF、ダウンロードしたドキュメント）が生成された場合は、保存場所を伝え、開くかどうか尋ねます。

Downloads フォルダーに web_table.xlsx を作成しました。6 行すべてが含まれています。開きますか？

「はい」と言われた場合は、ユーザーのコンピューターで開きます。Robomotion は Linux、macOS、Windows で動作するため、プラットフォームを確認して適切なアプリケーションを選び、1 つに決めつけないでください。

# Linux
xdg-open "<path>"
# macOS
open "<path>"
# Windows
start "" "<path>"        # cmd;  PowerShell: Start-Process "<path>"

ルール：

• 必ず開くかどうか尋ねてください。自分の判断で開いてはいけません。 ステップの完了と同時にファイルが画面に表示されるのは、結果ではなく予期しない出来事です。尋ねるのは 1 つだけです。
• 今回の実行で実際に生成され、パスがわかっているファイルに限ります。フローが書き出したファイルならパスがわかります。パスを推測したり、代わりにフォルダーを開いたりしてはいけません。
• 会話中に限ります。 実行を見ているユーザーがいる場合は、開くかどうか尋ねます。スケジュール実行やヘッドレス実行にはその場にユーザーがいないため、何も開いてはいけません。
• 尋ねられない場合は、代わりに内容を表示します。 非対話的に実行する場合（単発の claude -p、CI ジョブ、質問ツールが使えない場合など）は、開くかどうか尋ねても答える人がいません。そのため、質問で終わらせず、実行のレポートに生成物を表示します。テキストファイルや CSV ファイルを出力し（cat、長いファイルの場合は head -n 20）、読み戻したスプレッドシートの行を表示し、完全なパスも伝えます。それでもウィンドウは開いてはいけません。
• 開くことに失敗しても、実行の失敗にはなりません。 ファイルを開くアプリケーションがない場合や、デスクトップが利用できない場合（サーバーや SSH セッションなど）は、実行に成功したことと完全なパスを伝えます。成功した実行を失敗扱いにしてはいけません。

よくある node_error のパターン

error の断片	考えられる原因	修正方法
Cannot read property 'X' of undefined	上流ノードで msg.X が設定されていません	書き込みノードの out* プロパティを確認し、上流で Message('X') が設定されていることを確認します。
Network timeout / ETIMEDOUT	ロボットから URL に到達できません	URL を確認し、タイムアウトを延長して、プロキシを確認します。
element not found / selector failure	セレクターが古くなっています	exploring-browser を再実行し、inSelector を更新します。
property not found in pspec	プロパティ名が無効です	robomotion describe node <type> を実行してスキーマを確認します。
Vault has to be selected	Core.Vault.GetItem の optCredentials がありません	optCredentials: Credential({vaultId, itemId}) を追加します。

その他の便利な CLI コマンド

• robomotion get robots — 利用可能なロボットを一覧表示します（対話型ピッカーで使用されるものと同じデータです）。
• robomotion logs [--last | --studio <id>] [-f] — 実行のイベントを再表示します。
• robomotion stop --robot <robot-id> — ロボット上で実行中のフローを停止します。
• robomotion get vaults / robomotion get vault-items <vault-id> — ワークスペースで利用可能な認証情報を表示します。

よくあるエラーと修正方法

メッセージ	原因	修正方法
Not logged in to Robomotion in this project	このフォルダーではログインしていません	プロジェクトフォルダーで robomotion auth login --workspace <host> を実行します（バックグラウンドで実行し、ブラウザーで本人に承認してもらいます）。
No main.ts found in directory: <path>	ディレクトリが間違っているか、main.ts がありません	main.ts を含むディレクトリを指定します。
Flow validation failed	ビルド時に pspec 違反が発生しました	エラーを修正して（詳細なレポートには validating-flow を使用）、再実行します。
No robot named "<x>" / No robot chosen (exit 3)	名前が間違っているか、ターミナルなしで名前が指定されていません	robomotion get robots を実行し、本人にどのロボットを使うか尋ねて、--robot <name> を指定します。
No robots in this workspace	ロボットが登録されていません	Robomotion でロボットを作成し、コンピューターで起動するよう本人に依頼します。
実行を送信しても flow_start が表示されません	ロボットがオフラインか、別のワークスペースにいます	robomotion get robots を実行し、本人にロボットを起動してもらうか、（本人の許可を得て）robomotion robot connect --robot "<name>" を実行します。
Couldn't follow the flow here — no log appeared (exit 3)	ロボットが別のコンピューターにあります	実行はそのコンピューター上で行われています。このコンピューターで実行を追跡するには、robomotion robot connect --robot "<name>" を実行します。

フローで使用するパッケージの開発

修正がフローで使用するパッケージに関するもので、そのソースがこのコンピューターにある場合は、公開する代わりに、ソースツリーからパッケージを実行します。

robomotion package dev <package source folder> [--version <the version main.ts depends on>]
robomotion run                       # the robot now starts the package from source
robomotion package off <package source folder>   # back to the installed build
robomotion package status

Python パッケージは <source>/.venv から実行されるため（初回の dev で作成されます）、編集内容は次回の実行に反映されます。フローがパッケージを実行したままの場合は、編集後に package dev を再実行します。その他の言語は、package dev の実行ごとにパッケージ独自のビルドコマンドで再ビルドされます。パッケージの完全なトレースバックはロボットの出力にあり、実行のイベントストリームには表示されません。修正を完了とする前に、パッケージ独自のテストを実行してください。リリース時には、f.addDependency(...) を公開済みのバージョンに更新し、package off を実行します。robomotion 26.9.8 以降が必要です。

関連スキル

• creating-flow — フローを生成します
• running-chat-assistant — Chat In から開始するフローです。チャットページでエージェントとして実行・テストします
• validating-flow — スキーマチェックです（ローカルで実行でき、ロボットは不要です）
• testing-flow — モックを使った動作テストです（ロボットは不要です）