# 共同字段与流程结构

先查 `GET /node-types?q=关键词&page=1&pageSize=20`，再用返回的节点类型 ID 调用 `GET /node-types/{nodeType}`。`page` 从 1 开始，`pageSize` 为 1–100，默认 20。节点类型 `browser_gotoUrl` 与流程内自定义的节点 ID（如 `visit`）是两个字段。

| 契约字段 | 编排时怎么用 |
|  --- | --- |
| `authorable`、`runtimeSupported`、`externalRunnable`、`documentationComplete` | 分别核对可编排、运行支持、外部运行和文档完整性。 |
| `inputSchema` | 查输入类型、枚举、格式与结构；按实例返回的同源 Schema 地址解析 `$ref`。 |
| `conditionalRules`、`referenceRules` | 查按模式必填或禁止的字段、求值后的范围、允许的引用和可见范围。 |
| `defaults`、`outputVariants`、`fieldPolicies` | 查执行默认值、各模式的输出和字段策略。`x-editor-default` 是 UI 初值。 |


## 流程结构

公开写入使用 `editorVersion: 2`、`editorParametersVersion: 1`。根级 `nodes` 按顺序执行，唯一的 `start` 在首位、唯一的 `end` 在末位。嵌套节点使用节点契约规定的 `blocks`；全树节点 ID 唯一，修改时复用稳定 ID。各节点和分支的 `data.title` 写用途；分组不能再嵌套分组。

动作节点的 `type` 为 `browser_<action>`，`data.browserAction` 为匹配的动作名，输入放在 `data.browserUi.inputs`。动作输入的变量用 `${targetUrl}` 和 `${visit.data.finalUrl}` 等字符串。结束输出和条件操作数可用 `{"type":"ref","content":["visit","data","finalUrl"]}`，其中 `content` 必须是路径段数组。不要引用未来节点或不可见的兄弟分支。自定义变量在 `start.data.customVariables` 声明，通过 `browser_updateCustomVariable` 更新，以 `${custom.<id>}` 读取。保存后以服务端规范化的树继续编辑。

## 支持变量引用

字段表标注“支持变量引用”时，可以用 `${…}` 语法，把省略号换成实际变量名或引用路径。流程运行时会读取该引用的值，并按字段规则校验取值。

例如，`"selectorRadio": "${locatorType}"` 会读取初始化参数 `locatorType`。参数值为 `"XPath"` 时使用 XPath 选择器。该字段只允许 `"CSS"` 或 `"XPath"`，因此参数值为 `"TEXT"` 时无法通过校验。

## 示例字段和边界

| 节点或字段 | 写入规则 |
|  --- | --- |
| `gotoUrl.url` | 必填字符串，支持引用。可移植示例使用完整的绝对 HTTP(S) URL；使用其他协议前，先对当前客户端做预检，并确认浏览器的实际处理结果。 |
| `gotoUrl.postWaitMs` | 数字或支持的数字表达式，按契约求值后为 0–2147483647 毫秒，缺省 1000；零等待显式写 0。请把取值控制在此范围内。 |
| `getUrl.type` / `key` | `type` 为 `href`（默认）、`origin` 或 `search`；`search` 必须提供求值后非空的字符串 `key`。本例使用 `href`，从 `data.value` 读取完整 URL。对搜索模式按实例契约处理缺失值。 |
| `browserUi.exception.timeout` | 毫秒整数 0–2147483647，0 表示节点不限时，仍受运行剩余时间约束。动作默认 30000，控制节点默认 0；控制节点显式设置时覆盖整个子图。 |
| `browserUi.exception.policy` | 显式填写 `interrupt`、`skip` 或 `handle`。跳过失败继续时，下游对该节点 `data` 的引用为 null；还应检查运行的 `hasNodeErrors`。 |
| `retryTimes` / `retryInterval` | 原子动作启用 `retry` 后，额外尝试次数为 1–10 的整数，间隔为 0–2147483 **秒**。可能重复已生效的动作。 |


模板必填 `title`（去掉首尾空白后 1–100 字符）、`description`（最多 1000 字符，可空串）、`workflow`、`dependencies`（没有子流程时为 `[]`）。请求字节数、流程字节数、节点数、嵌套深度及单次编辑数以当前 `capabilities.data.limits` 为准。完整模型见[Workflow、变量与结构节点契约](/zh/browser-rpa/api/workflow)和[公共数据模型](/zh/browser-rpa/api/data-types)。

下一步：[校验并保存示例](/zh/browser-rpa/quickstart)。