running-flow

运行 Robomotion Flow

在机器人上运行 Flow，观察 Agent 模式事件流，并处理故障。涉及四个部分：

1. 运行前检查 — robomotion validate <flow-dir> 会在提交前于本地检查 pspec/schema 错误，耗时不到 1 秒。成本低；始终先执行。
2. 机器人 — 用户自己的机器人，已连接到这台电脑（通过 Robomotion 的 Desktop App，或在用户同意后运行 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 为起点的 Flow 不在此处运行。 没有任何东西会向它发送消息；它会一直等待，直到 --timeout 超时。请使用 running-chat-assistant skill，在真实聊天页面中将其作为 Agent 进行测试（robomotion agent）。

没有浏览器：日志是判断 Flow 的唯一依据。 Flow 没有屏幕，因此只有机器人的事件能显示它是否正常工作。请阅读这些事件；如果没有 flow_end status=success，绝不要说运行成功。

步骤 1 — 验证（强制运行前检查）

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

在机器人执行任何操作前，检查出所有“属性名称错误”“节点类型不存在”“端口无效”等问题。CLI 会重新构建并验证，不会输出 JSON。不要跳过此步骤——从运行日志中的 node_error 事件诊断 pspec 错误，远比阅读 validate 输出慢。

如果验证失败：阅读 stderr，修复 main.ts，然后重新运行 validate。重复此过程，直到退出码为 0，再继续。

robomotion run 也会在构建步骤中进行验证，因此错误的 Flow 不会到达机器人——但你要等到网络往返结束、Submitting flow for execution... 转圈提示出现后才会发现。请先验证。

步骤 2 — 使用用户自己的机器人

Flow 会在用户自己的某台机器人上运行。robomotion run 会读取机器人在其本机上写入的日志来跟踪运行，因此机器人必须连接到这台电脑。通常，Desktop App 已经连接好机器人。

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 会读取该日志。

如果用户没有机器人连接到此处（Desktop App 未运行，或当前环境是服务器），请询问用户一次，然后以用户身份在此处连接一台机器人：

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

它会像 Desktop App 一样使用用户的登录信息连接机器人；不会创建新机器人或新令牌，并且会拒绝连接 Agent 或应用的机器人（这些机器人通过 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 接受 Flow 目录（会解析到其中的 main.ts）或 .ts 文件。它会：

1. 构建 Flow（根据 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 步 — 查看 Agent 事件流

robomotion run 默认会持续跟踪事件流——它会持续读取 deskbot 写入的会话日志文件，文件位于：

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

事件以紧凑的单行 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 表示启动者（对于 robomotion run，值为 "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

第 5 步 — 验证 → 运行 → 观察 → 修复循环

目标是自主迭代（重试次数有限；收到用户请求时停止）：

1. 在本地验证：robomotion validate <flow-dir> — 提交前必须以 0 退出。如果退出码非 0，根据 stderr 报告修复 main.ts，然后重复此步骤（不要提交已知有问题的流程）。
2. 提交：robomotion run <flow-dir> --robot <name>（仅首次使用此标志）— 记录 Session id。
3. 流式查看：run 会自动持续读取 Agent 日志，直到出现 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 上运行，因此应根据平台选择打开方式，而不是想当然地只使用一种：

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

规则：

• 只询问，绝不自行打开。 步骤结束后文件突然出现在用户屏幕上，会让人意外，而不是带来结果。这只需问一个问题。
• 只处理本次运行实际生成的内容，且只有在知道路径时才处理 — 流程写入了该文件，因此你知道路径。绝不猜测路径，也不要改为打开文件夹。
• 仅限对话场景。 用户正在观看的运行可以询问；定时运行或无头运行没有人在场，不得打开任何内容。
• 无法询问时，就展示内容。 非交互式运行（一次性 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（退出码 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（退出码 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 启动的流程：运行并在聊天页面中将其作为 Agent 进行测试
• validating-flow — 架构检查（本地执行，无需机器人）
• testing-flow — 使用模拟对象进行行为测试（无需机器人）