# 概念 (/docs/cloud/services/automation/concepts)



脚本和工作流描述要做什么；运行记录某一次执行；触发器决定何时执行。动作是执行期间调用的可复用能力。

## 定义、版本与标签 [#定义版本与标签]

脚本与工作流共用 `namespace/name`，一个名字只能属于其中一种。草稿可以修改；发布的版本不可变，版本号不能复用。同版本同内容再次发布会返回已有版本。弃用版本保留历史，不等于删除。

版本和 dist-tag 遵循 npm 的引用方式：`docs-samples/hello@1.0.0` 固定版本，`@^1.2.0`、`@~1.2`、`@1.x` 选择范围，`@latest` 跟随标签。省略 `@` 等价于 `@latest`。每次运行记录实际解析的版本。

正式版发布会按版本选择规则更新 `latest`；发布较低版本不会自动把它退回。预发布版本需显式指定标签，例如 `beta`。`stable`、`beta` 等标签可以移动；标签名不能是版本号或版本范围；`latest` 不能删除。移动标签影响之后解析它的运行，不改写已发布版本。

用[发布版本](/docs/api/native/automation/publishScriptVersion)管理不可变内容，用[设置标签](/docs/api/native/automation/setScriptTag)把标签指向已有版本。写标签不需要 `If-Match`。修改草稿则需要最新 ETag，发布草稿需要 `expected_draft_revision`。

动作没有语义版本号：兼容更新立即生效，调用记录保存实际修订。输入输出不兼容时使用新名字，避免破坏既有调用方。工作流发布时锁定脚本和子工作流依赖的精确版本，动作不锁定。

## 运行生命周期 [#运行生命周期]

| 状态          | 含义                 |
| ----------- | ------------------ |
| `pending`   | 已受理，等待开始。          |
| `running`   | 正在执行。              |
| `waiting`   | 工作流正在等待事件、定时器或子运行。 |
| `suspended` | 工作流被暂停。            |
| `completed` | 成功结束，读取 `output`。  |
| `faulted`   | 执行失败，读取 `error`。   |
| `cancelled` | 已取消。               |

脚本没有 `waiting` 和 `suspended`。取消请求尚未结束时，运行可能仍为 `running`，并带 `cancel_requested_at`。超时是 `faulted`，错误类型为 `timeout`，不是另一个状态。终态不会恢复；[重跑](/docs/api/native/automation/rerunRun)创建新的根运行，`rerun_of` 指向原运行。

HTTP 成功表示请求被处理，不代表脚本成功。分别检查 `status`、`output` 和 `error`。脚本可查看[调用](/docs/api/native/automation/listRunCalls)与[日志](/docs/api/native/automation/listRunLogs)，工作流可查看[步骤](/docs/api/native/automation/listRunTasks)与[等待点](/docs/api/native/automation/listRunWaits)。

## 子运行与来源 [#子运行与来源]

脚本可以通过 `praxis.automation.runs.create` 启动子运行。子运行的 `initiator` 始终保留最初发起者（人、API Key 或触发器）；父子关系由 `parent_run_id` 表达。按来源筛选子运行用 `channel=run`，按指定父运行查找用 `parent_run_id` 过滤；公开详情中的 `parent` 提供父运行摘要，`root_run_id` 指向根运行。

父运行被取消时向下级联；父正常结束时子运行可以继续。子运行 deadline 不会超出父运行剩余时间。同一目标在调用链上再次出现会被循环检测拒绝；深度和扇出上限见[限制](/docs/cloud/services/automation/limits-and-errors)。

## 幂等与重试 [#幂等与重试]

[创建运行](/docs/api/native/automation/createRun)接受 `Idempotency-Key`。作用域为同一 owner、HTTP 方法、路径和 key，保留 24 小时；请求指纹不包含 `wait`。网络重试应复用原 key 和请求内容；重放返回当前运行，并带 `Idempotent-Replayed: true`。有意再跑一次时使用新 key。

同 key 不同请求返回 `IDEMPOTENCY_KEY_MISMATCH`；尚在处理时返回 `IDEMPOTENCY_IN_FLIGHT`，详见创建运行的错误表。幂等不提供事务回滚，失败前已经完成的调用可能产生了效果。

## 费用归因 [#费用归因]

运行本身不单独收费。运行中调用模型、搜索等能力产生费用，按这些能力的原价计费，并归因到运行与触发器上显示。没有能力调用的纯计算脚本不会产生模型或搜索费用。

[API 参考 →](/docs/api/native/automation) · [Cookbook →](/docs/cookbook)