# 快速开始：创建模板

本例保存一个模板：访问运行时传入的网址，并返回导航后的最终地址（包含重定向结果）。请在 macOS 或 Linux 的同一个 Bash 会话中按顺序执行；Windows 请使用 WSL。需要 MoreLogin 桌面客户端 V2.73.0 或更高版本，以及 curl 7.76 或更高版本、jq 和 uuidgen。请保留生成的文件，[运行示例](/zh/browser-rpa/run-api-example)和[请求恢复](/zh/browser-rpa/local-api#%E6%81%A2%E5%A4%8D)都会用到。

## 1. 查询能力与节点契约

将端口改为 MoreLogin 客户端中 Local API 的端口。实际的模板和运行响应可能含有敏感值，因此命令在私有的临时目录中执行。

```bash
umask 077
RPA_BASE_URL='http://127.0.0.1:40000/api/rpa/browser/v1'
RPA_DIR="$(mktemp -d)" && cd "$RPA_DIR"
rpa_curl() {
  curl --fail-with-body -sS --max-time 30 "$@"
}
```

如果启用了 Local API 认证，请按[认证](/zh/api-reference/getting-started/authentication)的说明，在 `rpa_curl` 的 `curl` 命令中加上 `Authorization` 请求头。

确认客户端支持本例用到的操作，并记录目录版本。写请求需要在 `X-RPA-Catalog-Revision` 请求头中带回该值。

```bash
rpa_curl "$RPA_BASE_URL/capabilities" -o capabilities.json &&
jq '.data | {operations, limits, docs}' capabilities.json &&
jq -e '.data.operations as $ops | ["listNodeTypes","getNodeType","validateWorkflow","createTemplate"] - $ops | length == 0' capabilities.json &&
RPA_CATALOG_REVISION="$(jq -er '.data.catalogRevision' capabilities.json)"
```

读取本例用到的四种节点类型的契约。只有每份契约都可编排、运行时支持、可通过 API 运行且文档完整时，最后一条命令才会成功。各契约字段的含义见[共同字段与流程结构](/zh/browser-rpa/node-contract-guide)。

```bash
rpa_curl --get "$RPA_BASE_URL/node-types" --data-urlencode 'q=gotoUrl' -o node-types.json &&
rpa_curl "$RPA_BASE_URL/node-types/start" -o start.contract.json &&
rpa_curl "$RPA_BASE_URL/node-types/end" -o end.contract.json &&
rpa_curl "$RPA_BASE_URL/node-types/browser_gotoUrl" -o browser_gotoUrl.contract.json &&
rpa_curl "$RPA_BASE_URL/node-types/browser_getUrl" -o browser_getUrl.contract.json &&
jq -s -e 'all(.[]; .data | .authorable and .runtimeSupported and .externalRunnable and .documentationComplete)' *.contract.json
```

AI 代理可以先读取本机指南：`rpa_curl "$RPA_BASE_URL/llms.txt"` 会列出 Skill（`/docs/SKILL.md`）和 API 指南。以 `/` 开头的路径按 `http://127.0.0.1:<port>` 解析。

## 2. 校验完整候选

将下面的正文保存为 `create.json`。每个节点的标题都写清楚它做什么。`end` 节点会把 `message` 作为运行的 `outputs.result` 返回；本例的 message 是 `url_result` 节点输出的 `data.value`。

```json
{
  "title": "浏览器 RPA 示例：返回网页地址",
  "description": "访问指定网页并返回地址",
  "workflow": {
    "editorVersion": 2,
    "editorParametersVersion": 1,
    "variables": {
      "type": "object",
      "properties": {
        "targetUrl": {
          "type": "string",
          "description": "要访问的 HTTP(S) 地址"
        }
      },
      "required": [
        "targetUrl"
      ]
    },
    "nodes": [
      {
        "id": "start",
        "type": "start",
        "data": {
          "title": "读取目标网址参数"
        }
      },
      {
        "id": "visit",
        "type": "browser_gotoUrl",
        "data": {
          "browserAction": "gotoUrl",
          "browserUi": {
            "inputs": {
              "url": "${targetUrl}",
              "postWaitMs": 0
            },
            "exception": {
              "timeout": 30000,
              "policy": "interrupt"
            }
          },
          "title": "访问指定的网页"
        }
      },
      {
        "id": "url_result",
        "type": "browser_getUrl",
        "data": {
          "browserAction": "getUrl",
          "browserUi": {
            "inputs": {
              "type": "href"
            },
            "exception": {
              "timeout": 30000,
              "policy": "interrupt"
            }
          },
          "title": "读取导航后的完整网址"
        }
      },
      {
        "id": "end",
        "type": "end",
        "data": {
          "inputsValues": {
            "status": {
              "type": "constant",
              "content": "success"
            },
            "message": {
              "type": "ref",
              "content": [
                "url_result",
                "data",
                "value"
              ]
            }
          },
          "title": "返回最终网页地址"
        }
      }
    ]
  },
  "dependencies": []
}
```

```bash
jq '{purpose:"save",source:{kind:"inline",template:.}}' create.json > validate-save.json &&
rpa_curl "$RPA_BASE_URL/validations" -H 'Content-Type: application/json' \
  --data-binary @validate-save.json -o validation-save.json &&
jq '.data | {valid,issues,truncated,runtimeChecks}' validation-save.json &&
jq -e '.data.valid == true and .data.truncated == false' validation-save.json
```

阅读校验报告中的错误、警告和运行时检查项。仅当 `valid` 为 `true` 且报告未截断时继续。校验不会打开浏览器。

## 3. 保存模板并记录版本

```bash
([ -s create.key ] || uuidgen > create.key) &&
rpa_curl "$RPA_BASE_URL/templates" -H 'Content-Type: application/json' \
  -H "X-RPA-Catalog-Revision: $RPA_CATALOG_REVISION" \
  -H "Idempotency-Key: $(cat create.key)" \
  --data-binary @create.json -D created.headers -o created.json &&
head -n 1 created.headers &&
jq '.data | {id,version,revisionId,warnings}' created.json
```

HTTP 201 表示模板已保存。保留规范化后的响应（包含 workflow、ID、version 和 revisionId），以及 `created.headers` 中的 `ETag`。`create.key` 中的 key 标识这次写入意图：只在重试同一请求时复用，新的写入请生成新 key。请求超时后，先按[请求恢复](/zh/browser-rpa/local-api#%E6%81%A2%E5%A4%8D)确认结果，再发送新的写请求。

模板列表刷新后，客户端的「自定义模板」中也会显示该模板。以后要修改时，先读取最新版本，用 `source.base` 校验完整候选，再携当前 `If-Match` 提交，见[修改既有模板](/zh/browser-rpa/local-api#%E4%BF%AE%E6%94%B9%E6%97%A2%E6%9C%89%E6%A8%A1%E6%9D%BF)。

下一步：[通过 API 运行已保存的模板](/zh/browser-rpa/run-api-example)。