creating-flow

Robomotion Flow Builder

Robomotion 是一个 RPA 平台，提供 TypeScript SDK 和可视化节点编辑器。本技能是 ./docs/ 中参考文档的简要索引。遇到相关主题时，请阅读对应文档——不要试图从本文件中记住所有内容。

硬性规则（SDK 会在验证时拒绝违规内容）

SDK 会强制执行以下规则。违反规则时，robomotion validate / build 会抛出详细错误消息，因此 Agent 不会悄悄生成有问题的工作流：

1. 节点 ID 必须是 6 位小写十六进制数——/^[0-9a-f]{6}$/。f.node()、.then()、f.edge() 会在注册时拒绝非十六进制 ID（如 'begin'、'label'、'maps'、大写字符）。随机生成每个 ID（openssl rand -hex 3）；切勿复制这些文档中的示例 ID，也不要使用 a1b2c3 或 aa11bb 这样的模式。参见 ./docs/reference/id-format.md。
2. 子工作流节点 ID 必须与 subflows/<id>.ts 文件名完全一致。 两者都必须是 6 位十六进制数。Designer 的“进入子工作流”交互依赖两者匹配。
3. f.addDependency(namespace, version) 会根据实时软件包索引进行验证。 version 必须是具体版本（不接受 'latest'），并且必须存在于软件包已发布的 versions 列表中。namespace 必须存在于 https://packages.robomotion.io/stable/index.json。调用 addDependency 之前，运行 robomotion get packages <ns> 或 robomotion describe package <ns>，以确认有效版本。切勿编造版本号。
4. 终端节点（Debug、Log、Stop、GoTo、End、WaitGroup.Done）的输出数为 0——使用 f.edge() 将线连到它们，切勿从它们调用 .then()。
5. 每个 Core.Flow.GoTo 都必须引用同一工作流文件中存在的 Core.Flow.Label ID。
6. 工作流文件是 Flow Designer 可以读取的声明，而不是只能由 Bun 运行的程序。 Designer 会逐个静态解析 main.ts 和每个 subflows/*.ts 文件，绘制它能理解的内容，并在每次保存时根据画布重新生成整个文件——它无法读取的内容会在用户第一次保存后从 git 中消失。因此：唯一的导入是 @robomotion/sdk；每个节点都必须是在 create 回调中直接写出的字面量 f.node() / .then() / f.edge()（不能使用辅助函数、循环或 .map()）；每个属性都必须是字面量、由字面量组成的数组/对象、对字面量使用作用域辅助函数，或使用模板、+ 或 [..].join('\n') 由同一文件内的 const 构建的字符串；不能使用展开（{ ...SHARED }）、简写属性或在 func 中导入辅助函数。每个使用共享辅助字符串的文件都要重新声明它。robomotion validate 会以“the Flow Designer cannot read it”拒绝其他写法。完整列表见 ./docs/reference/project-format.md。
7. 程序就是工作流；Function 节点只是连接代码，仅在必要时编写，并且要让人读得懂。 我们确实会编写代码，但只在某个步骤需要时编写：Function 用于为下一个节点整理 msg。工作应放在节点中：SQL 应写在 SQL 节点中，使用 {{{field}}} 占位符，绝不能在 JavaScript 中通过拼接字符串构造 SQL；用户会命名的规则应使用独立的 Function，并设置 outputs: 2；格式化是屏幕的工作；不要创建辅助库，也绝不能把辅助库粘贴到每个节点中。代码应格式清晰：每行一条语句，代码块单独成行并缩进，各部分之间留空行。没有行数限制——只要 Function 只做一件事且从上到下易于阅读，写得长也没问题。robomotion validate 会拒绝拥挤的代码（“several statements on one line”、“a whole block on one line”），以及同一个代码块在三个或更多 Function 中重复的情况。各类代码应放在何处：./docs/reference/function-nodes.md。

必需的首行

每个流程文件（main.ts 和每个 subflows/*.ts）都必须以以下导入语句开头，且内容完全一致——请原样复制，包括当前未使用的辅助函数（Bun 不会提示未使用的导入，但缺少的导入会导致运行时 ReferenceError）：

import { flow, Message, Custom, JS, Global, Flow, Credential, AI } from '@robomotion/sdk';

对于库文件，将 flow 替换为 library / subflow。这条规则适用于每个文件，无论文件多小：不存在更短的“最简”导入语句，本文档中的每个示例也都以此行开头。完整参考：./docs/reference/imports.md。

Builder 语法

• f.node(id, type, name, props) — 参数顺序。只传入非默认属性（Go 运行时会根据 pspec 填充默认值）。
• .then() 用于顺序连接，.edge() 用于多端口连线。
• Message(name) 用于变量 · Custom(value) 用于字面值 · JS(expr) 用于单行 JS · Credential({vaultId, itemId}) 用于密钥。
• 字段使用的作用域辅助函数取决于该节点中的字段类型，而不是它的 in*/opt* 名称——而且同名字段在不同节点中可能不同。 每个 in*/out* 端口都必须使用作用域辅助函数（Custom('…') / Message()）；直接写字面值会被静默丢弃。对于 opt* 字段，不要根据名称猜测——请检查 robomotion describe node <type>：类型为 object 且带有 variableType 的字段（即使是数值类型）需要使用作用域辅助函数；普通的 number/boolean/enum 字段则需要直接写字面值，绝不能用辅助函数包装。同一个属性在不同节点中可能有不同类型： Core.Browser.OpenLink 的 optTimeout 是普通数值 → optTimeout: 32，但 Core.Browser.WaitElement 的 optTimeout 是 variableType:Integer → optTimeout: Custom('30')。无论哪种情况，类型不匹配都能通过校验，但会在机器人上加载失败（flow_error: failed / Config parse error，不会运行任何节点）：包装普通字段会向标量传入对象；未包装由变量支持的字段会向 {scope,name} 槽位传入标量。枚举/布尔值始终是普通值（optBrowser: 'chrome'、optMethod: 'post'、optInsecure: true）；in* 端口和 optUrl/optDownloadDir/optNofBranches 等值字段始终使用 Custom()/Message()。
• func 是字面字符串（不是 JS()）。
• 常见运行时属性也使用原始值：delayBefore: 2、delayAfter: 0.5、continueOnError: true。
• func 内仅支持 ES5：不能使用 =>、模板字符串、const/let 或解构。不能使用 require() / fs / Buffer / process（纯 JS 沙箱）。
• 循环：Label → ForEach → body → GoTo。Stop 独立放置，通过 f.edge() 连接 ForEach 的端口 1。
• GoTo/Label 不只用于循环：长连线应使用 GoTo。 任何需要回连或跨越其他行才能到达共享节点或后置声明节点的边（例如错误处理器、通用的“说明原因”响应节点、分支后的汇合点），都会在所有中间节点上方画出对角线——每个分支都如此，最终画布将难以阅读。在目标旁放置 Core.Flow.Label，并让每个远端分支以放在独立行中的 Core.Flow.GoTo 结束。GoTo 没有出边，因此长边不再存在，也就无需再画一条更短的连线。经验法则：连线需要跨越两行以上时，就使用 GoTo，并根据目标为其命名，这样每一行仍能从左向右阅读。一行放不下的长链条也是同样的情况：以 GoTo 结束该行，并以 Label 开始下一行，绝不要让连线跨画布回连。参见 ./docs/patterns/branches.md；有关换行以及多端口节点的目标位置，请参见 ./docs/patterns/comments-and-layout.md。
• 库项目使用 library.create(id, name, fn) 和 Begin/End 节点（不使用 .start()）。内联子流使用 subflow.create(name, fn)。
• 每个流都以 .start() 结束。每个流都必须包含一个从触发器可到达的 Core.Flow.Stop 节点——有两种流不会停止：应用后端（由 Robomotion.Apps.Action 触发的流是运行在 Robomotion App 屏幕背后的长驻服务；每条路径都以 App Respond 结束；参见 building-app 技能），以及聊天流（由 Robomotion.ChatAssistant.ChatIn 触发的流会逐条回复消息；每轮都以 Chat Out 结束；参见 ./docs/patterns/conversational-chat.md；引导模式请参见 ./docs/patterns/guided-chat.md）。这两种流都没有 Stop 或 End。只有当流中完全没有 Stop 时，robomotion validate 才会发出警告（Chat In 和 App Action 流除外）；如果触发器的路径无法到达 Stop，校验仍会通过——请自行检查连线。
• Core.* 软件包（Core.Trigger、Core.Browser、Core.Programming、Core.CSV、Core.Flow、Core.Vault、Core.Net、Core.Excel 等）已嵌入机器人——绝不要调用 f.addDependency('Core.*', …)。Designer 会自动加载这些软件包。只有非 Core.* 软件包才调用 f.addDependency(ns, ver)。更新现有流时，绝不要升级现有的 addDependency 版本；只添加缺失的软件包。
• 注释与画布布局——Core.Flow.Comment 节点（包含 Markdown 字符串 optText）用于标注流标题并划分逻辑阶段；可视化布局——节点 positions、注释框的颜色/大小以及 Sugiyama 风格的分层——位于 main.designer.ts 中。布局仅影响外观（绝不会影响运行时），但它决定了流是否易于阅读。参见 ./docs/patterns/comments-and-layout.md。 完整语法：./docs/sdk-grammar.md。架构：./docs/architecture.md。

诊断索引

根据错误症状查找对应的修复文档。运行 robomotion validate 失败时，请先在此处查找对应症状，再阅读完整的失败跟踪信息。

症状	可能原因	修复方法
[SDK] Invalid node ID '<x>' in f.node('<x>', …)	语义化 ID／非十六进制 ID	./docs/reference/id-format.md — 选择 6 位十六进制 ID
[SDK] Invalid subflow filename '<x>.ts'	子流程文件名不是十六进制	重命名文件，并更新父 SubFlow 节点 ID，使其与文件名一致
version must be concrete; 'latest' and empty are not allowed	f.addDependency(ns, 'latest')	robomotion describe package <ns> → 固定到一个实际版本
package '<ns>' not found in repository	命名空间是臆造的	robomotion get packages <kw> → 使用真实的命名空间
version '<v>' is not published for <ns>	固定的版本有误	从验证器返回的 available_versions 中选择
Cannot chain from node (outputs=0)	在 Debug／Log／Stop／GoTo／End 后调用了 .then()	使用 f.edge() 连接 TO 端口，绝不要从 FROM 端口连接
the Flow Designer cannot read it（导入、展开运算符、辅助函数，或值“不是在此文件中声明的 const”）	该文件是程序，而非声明（硬性规则 6）	直接内联：只导入一次 @robomotion/sdk，在回调中编写节点，使用同一文件中的 const，不使用展开运算符。./docs/reference/project-format.md
several statements on one line／a whole block on one line／the same block opens N Function nodes	代码不是为人编写的，或把辅助库粘贴到了步骤中（硬性规则 7）	格式化代码（每行一条语句，代码块单独占行）；将 SQL 放入 SQL 节点，并使用 {{{field}}}；每条规则对应一个 Function；在屏幕上进行格式化。./docs/reference/function-nodes.md
Label 上出现 Invalid input port 0. Node has 0 input(s)	连接到了 Core.Flow.Label（在某些 pspecs 中，Label 没有输入端口）	使用 Core.Flow.GoTo，并设置 optNodes.ids: [<labelId>] 跳转到 Label
运行时出现 Vault has to be selected	Core.Vault.GetItem 缺少 optCredentials	./docs/patterns/credentials.md
Property 'optCredentials' requires vault credentials but has empty/placeholder values	一个可选凭据属性（例如用于受密码保护文件的 Core.Excel.Open）被设为 _／空白占位符	除非有真实的 Vault 引用，否则完全省略 optCredentials — ./docs/patterns/credentials.md
inSelectorType 的值 'xpath' 无效（允许的值：xpath:position、css）	写了 inSelectorType: 'xpath' — 这不是有效的枚举值	使用 XPath 时，直接省略 inSelectorType（这是默认值）；XPath 枚举字面值是 xpath:position，而不是 xpath。CSS ⇒ inSelectorType: 'css'。./docs/patterns/browser.md
GoTo 上未找到 inLabel 属性	属性有误	optNodes: { ids: [...], type: 'goto', all: false }
未找到 Core.Programming.If	节点不存在	使用 outputs: 2 的 Core.Programming.Function（./docs/patterns/conditions.md）
节点名称有误（例如 Core.CSV.Read、Browser.Click）	常见命名错误	./docs/reference/node-naming.md
inPath: Custom('$Home$/file') 字面值未解析	系统变量只会在 Function 节点中解析	global.get('$Home$') + '/file'（./docs/reference/system-variables.md）
流程通过验证，但在机器人上加载失败（flow_error: failed／Config parse error，没有节点运行）	opt* 值的形状与其节点类型不匹配：普通 number／bool／enum 字段被包装在 Custom() 中，或 variableType／对象字段被设为裸字面值	对每个节点检查 robomotion describe node <type>。枚举／布尔值直接填写（optBrowser: 'chrome'）。数值字段因节点而异：OpenLink.optTimeout: 32（普通 number），而 WaitElement.optTimeout: Custom('30')（variableType:Integer）。in* 端口以及 optUrl／optDownloadDir／optNofBranches 始终需要使用 Custom()／Message()。
范围内有任何 CSV／Excel／Sheets／SQLite／Pandas／Airtable／DOMParser／DataTable 节点	自定义数据形状有误（例如 {header: [...]}，或行是数组）	必须阅读 ./docs/patterns/data-tables.md — 格式为 {columns: [...], rows: [{key: value}]}，其中行键必须与列名一致
写入后出现空单元格／ErrFilePath／“table not recognized”	使用了 header 而不是 columns，或行是数组而不是对象	./docs/patterns/data-tables.md — 属性必须是 columns，绝不是 header；行必须是以列名为键的对象，绝不能是按位置排列的数组
每次对流程代码执行 Write / Edit 前容易遗忘的提醒：

• 永远不要在聊天中输出 TypeScript——始终使用 Write / Edit。计划和说明留在聊天中。
• 从一开始就使用十六进制 ID。交叉引用（optNodes.ids、Catch.optNodes.ids、子流程文件名）必须使用相同的十六进制值。
• 对于图像流程（Robomotion.ImageAutomation.*——远程桌面 / Citrix 会话，或其他任何东西都无法查看的旧版应用）：先使用 Skill(exploring-image) 探索实时屏幕（通过 ToolSearch 预热后使用 mcp__image__*），并根据其记录的序列构建流程；阅读 ./docs/patterns/image.md。绝不要绘制模板或猜测坐标：记录的模板已验证为屏幕上的唯一模板。image: IMG_X 是由 image_write_templates 写入的 const 的标识符——绝不是字符串，也绝不能粘贴 base64。deltaX/Y、布尔值和枚举值为普通值；in* 端口和 optConfidence / optWaitTimeout 使用 Custom()。
• 对于 Java 桌面流程（Robomotion.JavaAutomation.*，Swing/AWT 应用）：先使用 Skill(exploring-java) 探索实时应用（通过 ToolSearch 预热后使用 mcp__java__*），并根据其记录的序列构建流程；阅读 ./docs/patterns/java.md。绝不要猜测 Window Title 或 Full Path：记录的值已针对正在运行的应用验证。键槽 inMod1..3、枚举值和 optTimeout 为普通值；in* 端口使用 Custom()。
• 对于浏览器流程：先探索实时页面（使用 Skill(exploring-browser)，或通过 ToolSearch 预热后使用 mcp__browser__*）。不要猜测选择器。Core.Browser.* 元素节点（ClickElement / TypeText / GetValue / SetValue / WaitElement / Select）的 inSelector 默认使用 XPath——将找到的 CSS 句柄（#email、input[type="email"]）转换为 XPath（//input[@id='email']），并省略 inSelectorType；只有在 inSelectorType: 'css'（普通字面值——inSelectorType 是枚举值，因此绝不能使用 Custom('css')）时才使用 CSS 字符串。使用默认引擎时，CSS 字符串会在运行时导致“element not found”。绝不要写 inSelectorType: 'xpath'（无效；该值为 xpath:position）。此外：枚举 / 下拉选项（optBrowser、optProxy、optProxyAuth、optClickType）使用普通字符串 / 布尔值——绝不能使用 Custom()；将枚举值包装在 Custom() 中会生成 {name,scope} 对象，机器人会在加载时拒绝该节点，并报 Config parse error（流程无法启动）。Custom() / Message() 仅用于变量值字段（选择器 / URL / 文本 / 路径）。请参阅 ./docs/patterns/browser.md。
• 对于 Windows 桌面应用（记事本、Excel 的 UI、ERP 客户端，以及任何 Robomotion.WindowsAutomation.* 节点）：先探索实时应用（使用 Skill(exploring-windows)，或通过 ToolSearch 预热后使用 mcp__windows__*），并根据记录的序列构建流程——其选择器已针对应用验证。绝不要根据猜测或屏幕截图编写桌面选择器。程序使用 Core.Process.StartProcess 启动，并设置 optBackground: true（不设置时，该节点会等待应用退出）。optWaitTimeout / optTimeout / optIndex 和枚举值为普通值；in* 和 optText 使用 Custom() / Message()。请参阅 ./docs/patterns/windows.md。
• 对于任何读取或写入表格数据（CSV / Excel / Google Sheets / Excel 365 / SQLite / Airtable / Pandas / DataTable / DOMParser）的流程——在添加节点之前，先阅读 ./docs/patterns/data-tables.md，无论是构建表格的 Function，还是读取 / 写入节点都要阅读。该文档列出了准确的节点名称及其属性（例如，写入 CSV = Core.CSV.WriteCSV，使用 inFilePath + inTable；写入 Sheets = Robomotion.GoogleSheets.SetRange；等等），以及 {columns: [...], rows: [{key: value}]} 格式（绝不能使用 {header: ...}，也绝不能将行表示为数组）。**不要使用 robomotion search 搜索数据输出节点——搜索返回的是模板，而非节点，反复搜索只会浪费时间。节点名称已列在 data-tables.md 中；确定节点后，使用 robomotion describe node <type> 查看其准确属性。**如果搜索返回的是模板，而不是你需要的节点，请停止搜索并阅读相关模式文档。
• 对于任何处于对话式模式的 Robomotion.ChatAssistant 流程——编写前先阅读 ./docs/patterns/conversational-chat.md。一条用户消息对应一次 ChatIn → ChatOut 运行，只有 ChatOut 才会解锁编辑框；因此，以其他方式结束的分支（出错或缺少 ChatOut）会冻结聊天，直到重新加载页面——这是此类流程中最常见的错误，而且看起来像是产品故障，而不是流程故障。该文档还介绍了流式传输连线（Callback In stream_delta → Streaming Text，并且不要用 Text 节点重复输出答案）和附件连线（GetAttachments，因为 msg.payload.files 中包含的是名称和版本，而不是磁盘上的文件）。
• 对于处于引导式模式的 Robomotion.ChatAssistant 流程（流程依次提出问题：Textbox、ButtonGroup、Checkbox 等）——编写前先阅读 ./docs/patterns/guided-chat.md。固定选项格式为 [{ scope: 'Custom', name: { label: '…' } }]（describe node 只会将其显示为 array，且 validate 不会检查），每个 outResult 都是一个对象：读取 msg.<x>.value。
• 保存前先验证——先运行 robomotion validate；git push 会将文件夹中的内容原样存储，不管内容是否有问题。

模式参考

编写相应代码前，请先阅读这些文档：

模式	文档
循环（Label → ForEach → 主体 → GoTo）	./docs/patterns/loops.md
条件（带有 outputs: N 的 Function）	./docs/patterns/conditions.md
凭据（保管库 + 类别）	./docs/patterns/credentials.md
浏览器自动化（包括代理）	./docs/patterns/browser.md
远程桌面 / Citrix / 基于像素的屏幕（Robomotion.ImageAutomation）——先使用 exploring-image 探索	./docs/patterns/image.md
Java 桌面应用（Swing / AWT、Robomotion.JavaAutomation）——先使用 exploring-java 探索	./docs/patterns/java.md
Windows 桌面自动化（Robomotion.WindowsAutomation：选择器、节点、转换 exploring-windows 录制）	./docs/patterns/windows.md
异常处理（Catch、continueOnError）	./docs/patterns/exceptions.md
分支与并行（ForkBranch、WaitGroup）	./docs/patterns/branches.md
子流程（Begin/End、多输出）	./docs/patterns/subflows.md
数据表（CSV / Excel / Sheets / SQLite / Pandas / Airtable / DOMParser / DataTable）——编写任何生成或使用 msg.table 的代码前必须阅读	./docs/patterns/data-tables.md
验证码求解	./docs/patterns/captcha.md
将旧版 Robomotion.Assistant 流迁移到 Robomotion.ChatAssistant	./docs/patterns/assistant-migration.md
对话式 Chat Assistant（轮次约定、Stop、流式传输、附件）——编写任何对话模式的聊天流前必须阅读	./docs/patterns/conversational-chat.md
引导式 Chat Assistant（问题组件、固定选项、outResult.value、再次提问、错误路径）——编写任何引导模式的聊天流前必须阅读	./docs/patterns/guided-chat.md
注释、分组与 Sugiyama 布局（标题框、彩色阶段标题 + 描述文本、框尺寸、使用 GoTo/Label 连接长线、多端口扇出、main.designer.ts）	./docs/patterns/comments-and-layout.md

参考资料：

主题	文档
导入（所有作用域辅助工具 + 示例）	./docs/reference/imports.md
节点 ID 格式（十六进制规则）	./docs/reference/id-format.md
Designer 和 CLI 均可读取和保存的项目格式（硬性规则 6）	./docs/reference/project-format.md
Function 节点：仅在必要时编写胶水代码，面向人类排版；各项内容应放置的位置（硬性规则 7）	./docs/reference/function-nodes.md
系统变量（$Home$、$TempDir$）	./docs/reference/system-variables.md
节点命名（错误 → 正确）	./docs/reference/node-naming.md
凭据类别（字段布局）	./docs/reference/credential-categories.md

如需查看架构、示例和包文档，请使用 robomotion CLI（它已在 PATH 中，直接使用命令名调用）：

需求	命令
跨来源模糊 / 语义搜索	robomotion search <query>
查找包	robomotion get packages [query]
查找节点	robomotion get nodes [query] [--in <ns>]
查找模板	robomotion get templates [query] [--category <name>] [--tag <name>]
完整节点架构 + 文档 + 示例	robomotion describe node <type>[,<type>...]
包信息（包括已发布版本）	robomotion describe package <namespace>
模板源代码	robomotion describe template <slug>
包文档（llms.txt）	robomotion docs <namespace> [--grep <pattern>]
列出保管库 / 保管库条目	robomotion get vaults · robomotion get vault-items <vault-id>
列出机器人	robomotion get robots

公共模板仓库： github.com/robomotionio/robomotion-templates 是权威来源。与其从头构建，不如优先克隆或派生匹配的模板。

工作流

完整步骤指南：./docs/workflow.md。概要：

0a. 项目。 一个 flow 是一个文件夹：根目录中有 main.ts，并且是已登录账号的该 flow 自有仓库的 git 检出副本。如果还没有，就在用户希望存放它的文件夹下创建：

robomotion create flow "<short human name>"

该命令会创建文件夹（名称转换成 slug，或使用 --dir <path>），如果尚未登录则会引导登录（生成一段代码和一个链接，用户在浏览器中批准；在后台运行，等待批准；如果用户指定了工作区，则使用 --workspace <host>），在服务端创建 flow 并检出到该文件夹中。然后 cd 进入该文件夹。现有的检出副本（从 flow 的 Home 卡片执行 git clone 得到）无需任何操作；如果 robomotion auth whoami 显示尚未登录，则在其中运行 robomotion auth login --workspace <host>。 0. 收集需求（仅限交互模式）——凭据（从 robomotion get vaults / robomotion get vault-items <vault-id> 返回的结果中选定一个 Vault 条目，不要盘问用户；绝不要询问机密本身——请用户先将其添加到 Vault：./docs/patterns/credentials.md）、URL、文件、迭代方式、错误处理。

1. 发现——使用 robomotion search、robomotion get nodes，并对每个非 Core.* 包使用 robomotion docs <namespace>（当某个包没有 llms.txt 时，使用 robomotion describe package <ns> 和 describe node）。
2. 规划——将计划作为聊天文本输出，然后使用你自己的提问工具（或在普通聊天中）询问“开始构建，还是修改计划？”
3. 编写——阅读 1-2 篇相关的 ./docs/patterns/*.md，使用 robomotion describe node 验证属性名称，然后编写 main.ts（以及任何 subflows/<id>.ts）。对于浏览器工作流：先探索实时页面。
4. 验证——在 flow 文件夹中运行 robomotion validate。该命令会进行 Pspec 检查和依赖项检查。保存前必须通过。
5. 保存——在 flow 目录中运行 git add -A && git commit -m "..." && git push（robomotion create flow 创建的检出副本已配置好推送，无需额外设置；将 main.designer.ts 与 main.ts 一起提交）。除非用户也要求运行，否则此步骤即为任务结束。 报告成功——不要自行接着运行 flow。运行是单独的用户请求，由 running-flow 技能处理；如果运行时发现错误并修复了错误，请再次验证并保存。
6. 如果请求包含运行（“构建、运行，并在成功后保存”）：构建 → 验证 → 运行（running-flow：robomotion run 会按文件夹当前状态运行，无需先保存）→ 修复问题，直到运行成功 → 运行成功后保存。Chat In flow 则由 running-chat-assistant 处理，该技能会在每次聊天前推送（在 flow 检出副本中，推送即为保存）。如果用户没有提出此要求：构建 → 验证 → 保存，然后停止。

如果以直接模式调用（“为 X 编写 main.ts”、“生成一个执行 Y 的 flow”），跳过第 0-2 步，直接进入第 3 步。

在 Designer 的 Build with AI 中，同样的步骤通过工具完成：第 4 步使用 validate_flow，第 5 步使用 save_flow（该环境会拒绝 git 操作），describe node 使用 get_node_schema，提问使用 AskUserQuestion（及其 vault_picker）。在终端中，使用上面的命令。

**浏览器注意事项：**如果初次探索后代码发生了变化（选择器不同、操作新增），保存前必须对照实时页面重新验证选择器。选择器验证属于第 3 步，不是保存后的步骤。探索结束后，立即关闭探索浏览器——无论它是由哪个工具打开的（robomotion-browser-mcp、Playwright MCP）；编写或运行 flow 时绝不要让它保持打开。机器人会自行打开浏览器。

规范示例（简单链）

有关循环／条件／子流程／捕获示例，请参阅对应的模式文档，其中包含更丰富的可运行代码片段。

import { flow, Message, Custom, JS, Global, Flow, Credential, AI } from '@robomotion/sdk';

flow.create('<flow-id>', 'Simple Flow', (f) => {
  f.node('42ec21', 'Core.Trigger.Inject', 'Start', {})
    .then('7dbafc', 'Core.Programming.Function', 'Setup', {
      func: `msg.url = 'https://example.com';

return msg;`
    })
    .then('a06926', 'Core.Browser.Open', 'Open Browser', {
      outBrowserId: Message('browser_id')
    })
    .then('8e1c4b', 'Core.Browser.OpenLink', 'Navigate', {
      inBrowserId: Message('browser_id'),
      inUrl: Message('url'),
      outPageId: Message('page_id')
    })
    .then('d52f73', 'Core.Browser.Close', 'Close', {
      inBrowserId: Message('browser_id')
    })
    .then('b9a841', 'Core.Flow.Stop', 'Stop', {});
}).start();

CLI 和 MCP

• robomotion — 功能完备的 CLI。用于构建、验证、运行、搜索和检查。运行 robomotion help 查看完整的动词列表。
• robomotion-browser-mcp — 用于交互式浏览器探索的 MCP 服务（供 exploring-browser 和 mcp__browser__* 工具使用）。
• robomotion-image-mcp — 用于仅以像素形式呈现的屏幕的 MCP 服务：远程桌面、Citrix、旧版应用（供 exploring-image 和 mcp__image__* 工具使用；仅限 Windows）。
• robomotion-java-mcp — 通过 Java Access Bridge 操作 Java 桌面应用的 MCP 服务（供 exploring-java 和 mcp__java__* 工具使用；仅限 Windows）。
• robomotion-windows-mcp — 仅限 Windows：用于交互式桌面应用探索的 MCP 服务（供 exploring-windows 和 mcp__windows__* 工具使用）。

robomotion CLI 在内部会调用 robomotion-sdk-mcp 来执行基于搜索的命令，并直接调用 api.robomotion.io 来执行运行、停止、保管库和机器人操作。无需其他 MCP 服务。

回归测试套件

对于编辑此技能的人：agent-skills 仓库中包含一个自动化评测套件（github.com/robomotionio/agent-skills，skills/creating-flow/evals/）——Tier A 精准回归测试（手工制作的样例，每个样例对应一条规则）以及 Tier B 集成测试（使用公开 robomotion-templates 仓库中的实时 main.ts）。robomotion skills install 不会安装此套件。在该仓库的检出目录中，提交对本 SKILL.md 或 ./docs/ 文件的修改前，请从根目录运行 bun run skills/creating-flow/evals/run-evals.ts；其 README.md 介绍了如何添加新用例以及断言语法。

相关技能

• validating-flow — 架构验证
• testing-flow — 行为测试
• running-flow — 在机器人上执行
• running-chat-assistant — 在真实聊天页面中以 Agent 身份运行并测试 Chat Assistant 工作流（Chat In）
• searching-packages — 查找包、节点和模板
• exploring-browser — 交互式浏览器自动化
• exploring-image — 根据像素探索远程桌面／Citrix／旧版屏幕，并记录经过验证的 Image Automation 步骤
• exploring-java — 探索 Java（Swing/AWT）桌面应用，并记录经过验证的 Java Automation 步骤
• exploring-windows — 交互式 Windows 桌面应用自动化
• reversing-network — 捕获流量后，将浏览器工作流转换为 HTTP