自动化 API

2026-10-20

自动化 API

（待译）

Praxis Automation runs TypeScript scripts and YAML workflows with reusable Actions, triggers and inspectable run results. This is a Praxis-native API. Differences: choose your own namespace without registration, while praxis is read-only; Actions use ns/name at their current revision, while published scripts and workflows use ns/name@version or @tag; drafts can run directly as source without publishing; schedule and webhook triggers require a published target. Start with praxis.automation.runs.create to test source or execute a published target.

管理动作、发布脚本与工作流、查看运行并接收入站 webhook。

https://api.deepraxis.ai/automation/v1

鉴权

使用 Authorization: Bearer $PRAXIS_API_KEY。入站 webhook 使用创建或轮换时返回的 secret URL，无需 API Key。

TypeScript SDK

SDK 尚未发布到 npm。从本地源码安装，再用 Bun 运行示例；将命令中的路径替换为本地 SDK 目录。

bun add /absolute/path/to/packages/sdk/typescript
bun example.ts

示例使用 develop。curl 请求体带变量时需安装 jq。资源示例名称以 sample- 开头；创建前换成尚未占用的名称。动作、脚本和工作流使用 docs-samples 命名空间，完成后归档；触发器完成后删除。

动作

脚本

工作流

定义工具

运行

触发器与入站 webhook

列出动作

筛选可见动作并读取修订摘要。可按名称或说明筛选，包含近七天统计；不含实现源码，默认排除已归档动作。

GET /automation/v1/actions

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
query: limitinteger可选；每页条数，整数 1–100，默认 20。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: qstring可选；不区分大小写，按名称或说明的字面子串匹配；% 与 _ 无通配含义。
query: namespacestring[]可选；仅返回指定命名空间的定义，名称按小写匹配。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: scope"platform" / "own"[]可选；platform 仅平台定义，own 仅租户自建定义；省略返回两者。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: archivedboolean可选；true 仅已归档，false 仅未归档；默认 false。
query: implementation"code" / "container" / "shell"[]可选；按实现类型筛选：code、container 或 shell；省略不过滤。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: labelsobject可选；按标签过滤，使用 labels[k]=v；同键逗号多值取任一，不同键同时满足。
query: created_at[gte]string可选；创建时间下界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"
query: created_at[lte]string可选；创建时间上界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"

示例

SDK 安装与示例环境

curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "namespace=docs-samples" \
  --data-urlencode "limit=1"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.list({
  "query": {
    "namespace": [
      "docs-samples"
    ],
    "limit": 1
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的动作（含当前修订摘要与近七天统计），按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。
data[].namespacestring必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。
data[].namestring必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。
data[].descriptionstring必填 / 必有；动作说明，最多 1000 字符。
data[].labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
data[].ownerstring必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。
data[].builtinboolean必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。
data[].stats_7dobject必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。
data[].stats_7d.callsnumber必填 / 必有；近七天内对该动作的调用次数，按小时汇总。
data[].stats_7d.failuresnumber必填 / 必有；近七天内失败的调用次数。
data[].stats_7d.p50_msnull / number必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。
data[].dependentsobject必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。
data[].dependents.scriptsnumber必填 / 必有；引用该动作的脚本数量。
data[].dependents.workflowsnumber必填 / 必有；引用该动作的工作流数量。
data[].archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。
data[].created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
data[].updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。
data[].current_revisionobject必填 / 必有；列表使用的修订摘要：只含契约与运行位置，不含实现源码。 不接受额外字段。
data[].current_revision.idstring必填 / 必有；修订 ID，前缀 actr_。
data[].current_revision.implementationobject必填 / 必有；动作列表只返回 {kind, host}，不含源码；动作详情返回完整 implementation。 不接受额外字段。
data[].current_revision.implementation.kind"code" / "container" / "shell"必填 / 必有；动作实现方式。code 为源码实现（目前仅 language=ts 可用）；container 为容器镜像加命令，暂未开放；shell 为 shell 脚本，暂未开放。
data[].current_revision.implementation.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
data[].current_revision.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
data[].current_revision.input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
data[].current_revision.input_schema.*（分支5)object递归 JSON 值。
data[].current_revision.input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].current_revision.output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
data[].current_revision.output_schema.*（分支5)object递归 JSON 值。
data[].current_revision.output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].current_revision.created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
      "owner": "tnt_3a9759864ccb4e00",
      "namespace": "docs-samples",
      "name": "sample-action-1791867412840-b05e8a",
      "description": "",
      "labels": {},
      "builtin": false,
      "archived_at": null,
      "created_at": "2026-10-13T04:57:09.039Z",
      "updated_at": "2026-10-13T04:57:09.039Z",
      "current_revision": {
        "id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
        "implementation": {
          "kind": "code",
          "host": "isolate"
        },
        "host": "isolate",
        "input_schema": {
          "type": "object",
          "properties": {
            "n": {
              "type": "number"
            }
          },
          "required": [
            "n"
          ],
          "additionalProperties": false
        },
        "output_schema": {
          "type": "object",
          "properties": {
            "answer": {
              "type": "number"
            }
          },
          "required": [
            "answer"
          ],
          "additionalProperties": false
        },
        "created_at": "2026-10-13T04:57:09.039Z"
      },
      "stats_7d": {
        "calls": 0,
        "failures": 0,
        "p50_ms": null
      },
      "dependents": {
        "scripts": 0,
        "workflows": 0
      }
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

创建动作

创建动作定义和首个修订，名称折叠为小写；同租户重名返回 NAME_TAKEN，praxis 命名空间只读。

POST /automation/v1/actions

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

不接受额外字段。

字段类型说明
namespacestring必填 / 必有；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9.-]{0,63}；praxis 只读。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$"
namestring必填 / 必有；名称，存储前转为小写，格式 [a-z0-9][a-z0-9.-]{0,63}。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$"
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
input_schemaobject必填 / 必有；输入 JSON Schema；更新时只能放宽已接受的输入。
input_schema.（分支5).null / string / number / boolean / object / JSON[]递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；输出 JSON Schema；更新时只能收紧输出约束。
output_schema.（分支5).null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errorsobject[]可选；声明的错误类型与说明；更新时不能删除已有错误。
errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
annotationsobject可选；read_only 与 idempotent 为布尔值，缺省均为 false。 不接受额外字段。
annotations.read_onlyboolean可选；true 表示动作不修改外部状态，只读取数据。默认 false。
annotations.idempotentboolean可选；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。默认 false。
timeout_msnumber可选；正整数毫秒；当前 code 默认且最多 30000，container/shell 暂未开放。
implementationobject / object / object必填 / 必有；实现：code 使用 language=ts 与 source；container（image、command）和 shell（script）暂未开放，创建或更新时返回 OPERATION_NOT_SUPPORTED。
implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码。
implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放，返回 OPERATION_NOT_SUPPORTED）。
implementation（分支2).imagestring必填 / 必有；容器镜像引用。
implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放，返回 OPERATION_NOT_SUPPORTED）。
implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。
messagestring可选；本次修订的说明。

示例

SDK 安装与示例环境

curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "namespace": "docs-samples",
  "name": "sample-action",
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ],
    "additionalProperties": false
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ],
    "additionalProperties": false
  },
  "implementation": {
    "kind": "code",
    "language": "ts",
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  }
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.create({
  "body": {
    "namespace": "docs-samples",
    "name": "sample-action",
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    }
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
idstring必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。
namespacestring必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。
namestring必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。
descriptionstring必填 / 必有；动作说明，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。
builtinboolean必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。
current_revisionobject必填 / 必有；动作的一个不可变修订：契约、实现和运行参数的快照。每次更新兼容的内容变化都会产生新修订。 不接受额外字段。
current_revision.idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
current_revision.digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
current_revision.input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.input_schema.*（分支5)object递归 JSON 值。
current_revision.input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.output_schema.*（分支5)object递归 JSON 值。
current_revision.output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
current_revision.errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
current_revision.errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
current_revision.errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
current_revision.annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
current_revision.annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
current_revision.annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
current_revision.timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
current_revision.implementationobject / object / object必填 / 必有；code 使用 language=ts 与 source。container 和 shell 暂未开放，创建时返回 OPERATION_NOT_SUPPORTED。
current_revision.implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
current_revision.implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
current_revision.implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
current_revision.implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
current_revision.implementation（分支2).imagestring必填 / 必有；容器镜像引用。
current_revision.implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
current_revision.implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
current_revision.implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
current_revision.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
current_revision.platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
current_revision.created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
current_revision.created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
current_revision.created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
current_revision.messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
current_revision.created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
stats_7dobject必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。
stats_7d.callsnumber必填 / 必有；近七天内对该动作的调用次数，按小时汇总。
stats_7d.failuresnumber必填 / 必有；近七天内失败的调用次数。
stats_7d.p50_msnull / number必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。
dependentsobject必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。
dependents.scriptsnumber必填 / 必有；引用该动作的脚本数量。
dependents.workflowsnumber必填 / 必有；引用该动作的工作流数量。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
  "owner": "tnt_3a9759864ccb4e00",
  "namespace": "docs-samples",
  "name": "sample-action-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "builtin": false,
  "current_revision": {
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "errors": [],
    "annotations": {
      "read_only": false,
      "idempotent": false
    },
    "timeout_ms": 30000,
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    },
    "host": "isolate",
    "platform_apis": [],
    "id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
    "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
    "created_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    },
    "message": null,
    "created_at": "2026-10-13T04:57:09.039Z"
  },
  "stats_7d": {
    "calls": 0,
    "failures": 0,
    "p50_ms": null
  },
  "dependents": {
    "scripts": 0,
    "workflows": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:09.039Z",
  "updated_at": "2026-10-13T04:57:09.039Z"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 INPUT_INVALID：输入不满足目标契约或业务校验。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 NAME_TAKEN：名称已被同一租户占用。
413PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取动作

读取动作及当前修订的完整实现；响应 ETag 是当前修订 ID，可用于更新时的 If-Match。

GET /automation/v1/actions/{ns}/{name}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.retrieve({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent resource revision for conditional updates.

application/json

字段类型说明
idstring必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。
namespacestring必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。
namestring必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。
descriptionstring必填 / 必有；动作说明，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。
builtinboolean必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。
current_revisionobject必填 / 必有；动作的一个不可变修订：契约、实现和运行参数的快照。每次更新兼容的内容变化都会产生新修订。 不接受额外字段。
current_revision.idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
current_revision.digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
current_revision.input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.input_schema.*（分支5)object递归 JSON 值。
current_revision.input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.output_schema.*（分支5)object递归 JSON 值。
current_revision.output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
current_revision.errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
current_revision.errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
current_revision.errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
current_revision.annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
current_revision.annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
current_revision.annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
current_revision.timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
current_revision.implementationobject / object / object必填 / 必有；code 使用 language=ts 与 source。container 和 shell 暂未开放，创建时返回 OPERATION_NOT_SUPPORTED。
current_revision.implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
current_revision.implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
current_revision.implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
current_revision.implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
current_revision.implementation（分支2).imagestring必填 / 必有；容器镜像引用。
current_revision.implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
current_revision.implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
current_revision.implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
current_revision.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
current_revision.platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
current_revision.created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
current_revision.created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
current_revision.created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
current_revision.messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
current_revision.created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
stats_7dobject必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。
stats_7d.callsnumber必填 / 必有；近七天内对该动作的调用次数，按小时汇总。
stats_7d.failuresnumber必填 / 必有；近七天内失败的调用次数。
stats_7d.p50_msnull / number必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。
dependentsobject必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。
dependents.scriptsnumber必填 / 必有；引用该动作的脚本数量。
dependents.workflowsnumber必填 / 必有；引用该动作的工作流数量。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
  "owner": "tnt_3a9759864ccb4e00",
  "namespace": "docs-samples",
  "name": "sample-action-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "builtin": false,
  "archived_at": null,
  "created_at": "2026-10-13T04:57:09.039Z",
  "updated_at": "2026-10-13T04:57:09.039Z",
  "current_revision": {
    "id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
    "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "errors": [],
    "annotations": {
      "read_only": false,
      "idempotent": false
    },
    "timeout_ms": 30000,
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    },
    "host": "isolate",
    "platform_apis": [],
    "created_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    },
    "message": null,
    "created_at": "2026-10-13T04:57:09.039Z"
  },
  "stats_7d": {
    "calls": 0,
    "failures": 0,
    "p50_ms": null
  },
  "dependents": {
    "scripts": 0,
    "workflows": 0
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

更新动作

检查当前和最近五个历史修订的兼容性后更新。输入放宽、输出收紧为兼容，包括长度、条目数、属性数、type（integer/number）与 multipleOf（输入新因子可整除旧因子，输出相反）。dry_run=true 仅返回 CompatResult，可不带 If-Match；带了仍校验，* 匹配任何当前存在的表示。正常更新必须带 If-Match，返回 ActionDef 与 ETag；预检不返回 ETag。省略的可选字段保持原值仅适用于 description、labels；errors 默认 []，annotations 未提供的键默认 false，timeout_ms 默认 30000，message 默认 null。 正常更新不兼容时返回 422 SCHEMA_INCOMPATIBLE 与 issues；内容未变则保留现有修订。

PUT /automation/v1/actions/{ns}/{name}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
query: dry_runboolean可选；true 仅检查兼容性，不落库，可省略 If-Match；省略或 false 正常更新。
header: If-Matchstring可选；正常更新必填；dry_run=true 可省略，提供时仍校验。* 匹配任何当前存在的表示；也可提供当前修订 ETag。

application/json

不接受额外字段。

字段类型说明
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。
input_schemaobject必填 / 必有；输入 JSON Schema；更新时只能放宽已接受的输入。
input_schema.（分支5).null / string / number / boolean / object / JSON[]递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；输出 JSON Schema；更新时只能收紧输出约束。
output_schema.（分支5).null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errorsobject[]可选；声明的错误类型与说明；更新时不能删除已有错误。
errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
annotationsobject可选；read_only 与 idempotent 为布尔值，缺省均为 false。 不接受额外字段。
annotations.read_onlyboolean可选；true 表示动作不修改外部状态，只读取数据。默认 false。
annotations.idempotentboolean可选；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。默认 false。
timeout_msnumber可选；正整数毫秒；当前 code 默认且最多 30000，container/shell 暂未开放。
implementationobject / object / object必填 / 必有；实现：code 使用 language=ts 与 source；container（image、command）和 shell（script）暂未开放，创建或更新时返回 OPERATION_NOT_SUPPORTED。
implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码。
implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放，返回 OPERATION_NOT_SUPPORTED）。
implementation（分支2).imagestring必填 / 必有；容器镜像引用。
implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放，返回 OPERATION_NOT_SUPPORTED）。
implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
messagestring可选；本次修订的说明。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
ETAG最新 GET 响应头 ETag（保留引号）
: "${ACTION_NAME:?Set ACTION_NAME}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PUT "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "If-Match: ${ETAG}" \
  -H "Content-Type: application/json" \
  --data '{
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ],
    "additionalProperties": false
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ],
    "additionalProperties": false
  },
  "implementation": {
    "kind": "code",
    "language": "ts",
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  },
  "message": "Sample revision"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.update({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  },
  "headers": {
    "If-Match": env("ETAG")
  },
  "body": {
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    },
    "message": "Sample revision"
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent revision returned only for normal updates; absent for dry_run=true.

application/json

字段类型说明
（分支1).idstring必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。
（分支1).namespacestring必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。
（分支1).namestring必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。
（分支1).descriptionstring必填 / 必有；动作说明，最多 1000 字符。
（分支1).labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
（分支1).ownerstring必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。
（分支1).builtinboolean必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。
（分支1).current_revisionobject必填 / 必有；动作的一个不可变修订：契约、实现和运行参数的快照。每次更新兼容的内容变化都会产生新修订。 不接受额外字段。
（分支1).current_revision.idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
（分支1).current_revision.digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
（分支1).current_revision.input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
（分支1).current_revision.input_schema.*（分支5)object递归 JSON 值。
（分支1).current_revision.input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).current_revision.output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
（分支1).current_revision.output_schema.*（分支5)object递归 JSON 值。
（分支1).current_revision.output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).current_revision.errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
（分支1).current_revision.errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
（分支1).current_revision.errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
（分支1).current_revision.errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
（分支1).current_revision.annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
（分支1).current_revision.annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
（分支1).current_revision.annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
（分支1).current_revision.timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
（分支1).current_revision.implementationobject / object / object必填 / 必有；code 使用 language=ts 与 source。container 和 shell 暂未开放，创建时返回 OPERATION_NOT_SUPPORTED。
（分支1).current_revision.implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
（分支1).current_revision.implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
（分支1).current_revision.implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
（分支1).current_revision.implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
（分支1).current_revision.implementation（分支2).imagestring必填 / 必有；容器镜像引用。
（分支1).current_revision.implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
（分支1).current_revision.implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
（分支1).current_revision.implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
（分支1).current_revision.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
（分支1).current_revision.platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
（分支1).current_revision.created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
（分支1).current_revision.created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
（分支1).current_revision.created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
（分支1).current_revision.messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
（分支1).current_revision.created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
（分支1).stats_7dobject必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。
（分支1).stats_7d.callsnumber必填 / 必有；近七天内对该动作的调用次数，按小时汇总。
（分支1).stats_7d.failuresnumber必填 / 必有；近七天内失败的调用次数。
（分支1).stats_7d.p50_msnull / number必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。
（分支1).dependentsobject必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。
（分支1).dependents.scriptsnumber必填 / 必有；引用该动作的脚本数量。
（分支1).dependents.workflowsnumber必填 / 必有；引用该动作的工作流数量。
（分支1).archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。
（分支1).created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
（分支1).updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。
（分支2)（分支1).compatibletrue必填 / 必有；固定为 true：新契约与当前及最近五个历史修订兼容。
（分支2)（分支2).compatiblefalse必填 / 必有；固定为 false：新契约至少在一处与历史修订不兼容。
（分支2)（分支2).issuesobject[]必填 / 必有；全部不兼容之处，每项含 pointer 与 reason。
（分支2)（分支2).issues[].pointerstring必填 / 必有；不兼容位置的 JSON Pointer（RFC 6901），相对于动作的 input_schema 或 output_schema。
（分支2)（分支2).issues[].reasonstring必填 / 必有；该位置为何与历史修订不兼容（输入应放宽、输出应收紧）。

实测响应

HTTP 200

{
  "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
  "owner": "tnt_3a9759864ccb4e00",
  "namespace": "docs-samples",
  "name": "sample-action-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "builtin": false,
  "archived_at": null,
  "created_at": "2026-10-13T04:57:09.039Z",
  "updated_at": "2026-10-13T04:57:12.709Z",
  "current_revision": {
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "errors": [],
    "annotations": {
      "read_only": false,
      "idempotent": false
    },
    "timeout_ms": 30000,
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    },
    "host": "isolate",
    "platform_apis": [],
    "id": "actr_00mv67lrt1370820a9daaa4fd3882332e4899a4c9e",
    "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
    "created_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    },
    "message": "Sample revision",
    "created_at": "2026-10-13T04:57:12.709Z"
  },
  "stats_7d": {
    "calls": 0,
    "failures": 0,
    "p50_ms": null
  },
  "dependents": {
    "scripts": 0,
    "workflows": 0
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 INPUT_INVALID：输入不满足目标契约或业务校验。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
413PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。
422SCHEMA_INCOMPATIBLE：新动作契约与历史修订不兼容。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出动作修订

按创建时间倒序列出修订。结果包含当前标记及通过兼容门回滚的可行性和原因。 默认不带源码；仅 expand=source 带完整源码，其它值返回 400。详情接口保持全文。

GET /automation/v1/actions/{ns}/{name}/revisions

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
query: limitinteger可选；每页条数，整数 1–100，默认 20。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: expand"source"可选；仅接受 source；默认不带源码，其它值返回 400。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/revisions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.revisions.list({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的动作修订（默认不含实现源码，expand=source 才带），按 created_at 倒序、id 倒序排列。
data[].currentboolean必填 / 必有；true 表示这是动作当前生效的修订。
data[].rollbackobject必填 / 必有；回滚到该修订是否可行，由服务端对当前修订做兼容判定。 不接受额外字段。
data[].rollback.allowedboolean必填 / 必有；true 表示可以回滚到此修订；false 时 issues 说明原因。
data[].rollback.issuesobject[]必填 / 必有；回滚会产生的不兼容项，每项含 pointer 与 reason；allowed 为 true 时为空数组。
data[].rollback.issues[].pointerstring必填 / 必有；不兼容位置的 JSON Pointer（RFC 6901），相对于动作的 input_schema 或 output_schema。
data[].rollback.issues[].reasonstring必填 / 必有；该位置为何与历史修订不兼容（输入应放宽、输出应收紧）。
data[].idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
data[].digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
data[].input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
data[].input_schema.*（分支5)object递归 JSON 值。
data[].input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
data[].output_schema.*（分支5)object递归 JSON 值。
data[].output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
data[].errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
data[].errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
data[].errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
data[].annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
data[].annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
data[].annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
data[].timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
data[].implementationobject / object / object / object必填 / 必有；实现信息：完整实现，或仅含 kind；列表不返回源码，需源码用 expand=source 或读取单个修订。
data[].implementation（分支1)（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
data[].implementation（分支1)（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
data[].implementation（分支1)（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
data[].implementation（分支1)（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
data[].implementation（分支1)（分支2).imagestring必填 / 必有；容器镜像引用。
data[].implementation（分支1)（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
data[].implementation（分支1)（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
data[].implementation（分支1)（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
data[].implementation（分支2).kind"code" / "container" / "shell"必填 / 必有；动作实现方式。code 为源码实现（目前仅 language=ts 可用）；container 为容器镜像加命令，暂未开放；shell 为 shell 脚本，暂未开放。
data[].host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
data[].platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
data[].created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
data[].created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[].messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
data[].created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "actr_00mv67lrt1370820a9daaa4fd3882332e4899a4c9e",
      "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
      "input_schema": {
        "type": "object",
        "properties": {
          "n": {
            "type": "number"
          }
        },
        "required": [
          "n"
        ],
        "additionalProperties": false
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "number"
          }
        },
        "required": [
          "answer"
        ],
        "additionalProperties": false
      },
      "errors": [],
      "annotations": {
        "read_only": false,
        "idempotent": false
      },
      "timeout_ms": 30000,
      "host": "isolate",
      "platform_apis": [],
      "created_by": {
        "type": "api_key",
        "id": "key_3e00b8984967"
      },
      "message": "Sample revision",
      "created_at": "2026-10-13T04:57:12.709Z",
      "current": true,
      "rollback": {
        "allowed": true,
        "issues": []
      },
      "implementation": {
        "kind": "code"
      }
    },
    {
      "id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
      "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
      "input_schema": {
        "type": "object",
        "properties": {
          "n": {
            "type": "number"
          }
        },
        "required": [
          "n"
        ],
        "additionalProperties": false
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "number"
          }
        },
        "required": [
          "answer"
        ],
        "additionalProperties": false
      },
      "errors": [],
      "annotations": {
        "read_only": false,
        "idempotent": false
      },
      "timeout_ms": 30000,
      "host": "isolate",
      "platform_apis": [],
      "created_by": {
        "type": "api_key",
        "id": "key_3e00b8984967"
      },
      "message": null,
      "created_at": "2026-10-13T04:57:09.039Z",
      "current": false,
      "rollback": {
        "allowed": true,
        "issues": []
      },
      "implementation": {
        "kind": "code"
      }
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取动作修订

读取指定修订的完整实现及回滚兼容判定；修订不存在时返回 VERSION_NOT_FOUND。 详情始终返回完整源码。

GET /automation/v1/actions/{ns}/{name}/revisions/{revision}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: revisionstring必填；动作修订 ID（actr_）；查询参数用于筛选调用记录。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
REVISION_ID已有动作修订 id
: "${ACTION_NAME:?Set ACTION_NAME}"
: "${REVISION_ID:?Set REVISION_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/revisions/${REVISION_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.revisions.retrieve({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME"),
    "revision": env("REVISION_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
currentboolean必填 / 必有；true 表示这是动作当前生效的修订。
rollbackobject必填 / 必有；回滚到该修订是否可行，由服务端对当前修订做兼容判定。 不接受额外字段。
rollback.allowedboolean必填 / 必有；true 表示可以回滚到此修订；false 时 issues 说明原因。
rollback.issuesobject[]必填 / 必有；回滚会产生的不兼容项，每项含 pointer 与 reason；allowed 为 true 时为空数组。
rollback.issues[].pointerstring必填 / 必有；不兼容位置的 JSON Pointer（RFC 6901），相对于动作的 input_schema 或 output_schema。
rollback.issues[].reasonstring必填 / 必有；该位置为何与历史修订不兼容（输入应放宽、输出应收紧）。
idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
input_schema.*（分支5)object递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
output_schema.*（分支5)object递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
implementationobject / object / object必填 / 必有；code 使用 language=ts 与 source。container 和 shell 暂未开放，创建时返回 OPERATION_NOT_SUPPORTED。
implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
implementation（分支2).imagestring必填 / 必有；容器镜像引用。
implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
  "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ],
    "additionalProperties": false
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ],
    "additionalProperties": false
  },
  "errors": [],
  "annotations": {
    "read_only": false,
    "idempotent": false
  },
  "timeout_ms": 30000,
  "implementation": {
    "kind": "code",
    "language": "ts",
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  },
  "host": "isolate",
  "platform_apis": [],
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "message": null,
  "created_at": "2026-10-13T04:57:09.039Z",
  "current": false,
  "rollback": {
    "allowed": true,
    "issues": []
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。 VERSION_NOT_FOUND：指定版本或修订不存在。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

回滚动作

用历史内容创建通过兼容检查的新修订。检查覆盖当前及最近五个历史修订；不会把当前指针直接退回旧 ID。可选 If-Match 可指定当前修订或 ； 匹配任何当前存在的表示。

POST /automation/v1/actions/{ns}/{name}/rollback

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
header: If-Matchstring可选；可选当前修订或 ；提供时执行条件校验， 匹配任何当前存在的表示。
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

不接受额外字段。

字段类型说明
revisionstring必填 / 必有；要回滚到的历史修订 ID（actr_）；回滚会创建新修订。
messagestring可选；本次修订的说明。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
REVISION_ID已有动作修订 id
: "${ACTION_NAME:?Set ACTION_NAME}"
: "${REVISION_ID:?Set REVISION_ID}"
BODY=$(jq -n --arg REVISION_ID "$REVISION_ID" '{
  "revision": $REVISION_ID
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/rollback" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$BODY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.rollback({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  },
  "body": {
    "revision": env("REVISION_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.
ETagstringCurrent revision ID after rollback.

application/json

字段类型说明
idstring必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。
namespacestring必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。
namestring必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。
descriptionstring必填 / 必有；动作说明，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。
builtinboolean必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。
current_revisionobject必填 / 必有；动作的一个不可变修订：契约、实现和运行参数的快照。每次更新兼容的内容变化都会产生新修订。 不接受额外字段。
current_revision.idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
current_revision.digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
current_revision.input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.input_schema.*（分支5)object递归 JSON 值。
current_revision.input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.output_schema.*（分支5)object递归 JSON 值。
current_revision.output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
current_revision.errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
current_revision.errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
current_revision.errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
current_revision.annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
current_revision.annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
current_revision.annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
current_revision.timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
current_revision.implementationobject / object / object必填 / 必有；code 使用 language=ts 与 source。container 和 shell 暂未开放，创建时返回 OPERATION_NOT_SUPPORTED。
current_revision.implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
current_revision.implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
current_revision.implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
current_revision.implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
current_revision.implementation（分支2).imagestring必填 / 必有；容器镜像引用。
current_revision.implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
current_revision.implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
current_revision.implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
current_revision.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
current_revision.platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
current_revision.created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
current_revision.created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
current_revision.created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
current_revision.messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
current_revision.created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
stats_7dobject必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。
stats_7d.callsnumber必填 / 必有；近七天内对该动作的调用次数，按小时汇总。
stats_7d.failuresnumber必填 / 必有；近七天内失败的调用次数。
stats_7d.p50_msnull / number必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。
dependentsobject必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。
dependents.scriptsnumber必填 / 必有；引用该动作的脚本数量。
dependents.workflowsnumber必填 / 必有；引用该动作的工作流数量。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
  "owner": "tnt_3a9759864ccb4e00",
  "namespace": "docs-samples",
  "name": "sample-action-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "builtin": false,
  "archived_at": null,
  "created_at": "2026-10-13T04:57:09.039Z",
  "updated_at": "2026-10-13T04:57:15.629Z",
  "current_revision": {
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "errors": [],
    "annotations": {
      "read_only": false,
      "idempotent": false
    },
    "timeout_ms": 30000,
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    },
    "host": "isolate",
    "platform_apis": [],
    "id": "actr_00mv67lu25f7f28dd81a924c698b9d2557056a7b62",
    "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
    "created_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    },
    "message": "回滚到 actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
    "created_at": "2026-10-13T04:57:15.629Z"
  },
  "stats_7d": {
    "calls": 0,
    "failures": 0,
    "p50_ms": null
  },
  "dependents": {
    "scripts": 0,
    "workflows": 0
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 INPUT_INVALID：输入不满足目标契约或业务校验。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。 VERSION_NOT_FOUND：指定版本或修订不存在。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
413PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。 SCHEMA_INCOMPATIBLE：新动作契约与历史修订不兼容。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出动作调用

列出该动作的调用记录，可按状态、修订、调用方编排和时间筛选；结果包含所属运行与调用位置。

GET /automation/v1/actions/{ns}/{name}/invocations

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
query: limitinteger可选；每页条数，整数 1–100，默认 20。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: status"running" / "completed" / "faulted" / "cancelled"[]可选；逗号分隔的状态，可选 running、completed、faulted、cancelled；省略不过滤。
query: revisionstring可选；动作修订 ID（actr_）；查询参数用于筛选调用记录。
query: callerstring可选；调用方脚本或工作流的精确名称，格式 ns/name。
query: run_kind"script" / "workflow"可选；调用方运行类型：script 或 workflow。
query: created_at[gte]string可选；创建时间下界（包含），RFC 3339 且带时区，如 2026-10-01T00:00:00Z。 format: "date-time"

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/invocations" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.invocations.list({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的动作调用记录，按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；调用标识，无独立 inv_ 前缀：脚本为 run_id:seq（运行 ID 与调用序号）；工作流为任务执行键加尝试次数。请按不透明字符串保存。
data[].created_atstring必填 / 必有；调用记录的创建时间（RFC 3339 UTC）。
data[].started_atnull / string必填 / 必有；动作开始执行的时间；尚未开始为 null。
data[].ended_atnull / string必填 / 必有；动作结束的时间；仍在执行为 null。
data[].status"running" / "completed" / "faulted" / "cancelled"必填 / 必有；调用状态。running 执行中；completed 已正常返回；faulted 失败，error 给出原因；cancelled 因运行被取消而中止。
data[].duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
data[].revisionstring必填 / 必有；本次执行使用的动作修订 ID（actr_ 前缀）。
data[].runobject必填 / 必有；发起这次调用的运行：{id, kind, definition, number, source_digest}。 不接受额外字段。
data[].run.idstring必填 / 必有；发起调用的运行 ID（run_ 前缀），可用于读取该运行。
data[].run.kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[].run.definitionnull / object必填 / 必有；该运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
data[].run.definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
data[].run.definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
data[].run.numbernull / number必填 / 必有；运行在其脚本或工作流内的序号；临时运行为 null。
data[].run.source_digestnull / string必填 / 必有；临时运行的源码摘要；由已发布定义启动的运行为 null。
data[].siteobject / object必填 / 必有；调用发生的位置：脚本中的一次调用（kind=call，带 seq），或工作流的一个步骤（kind=task，带 reference 与 iteration）。
data[].site（分支1).kind"call"必填 / 必有；固定为 call：来自脚本中的调用。
data[].site（分支1).seqnumber必填 / 必有；该调用在脚本运行中的序号，与 Call.seq 对应。
data[].site（分支2).kind"task"必填 / 必有；固定为 task：来自工作流步骤。
data[].site（分支2).referencestring必填 / 必有；工作流文档内该步骤的 JSON Pointer，与 Task.reference 对应。
data[].site（分支2).iterationnumber[]必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。
data[].errornull / object必填 / 必有；失败时的 {code, message}；成功或仍在执行为 null。
data[].error（分支2).codestring必填 / 必有；错误码，例如动作声明的 code 或平台错误码。
data[].error（分支2).messagestring必填 / 必有；错误说明文字。
data[].result_previewnull / string必填 / 必有；返回值的单行预览，由服务端截断；未结束或失败为 null。
data[].request_idstring / null必填 / 必有；下游响应的 X-Request-Id；响应未提供该头时为 null，可用于追查失败调用。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出动作引用方

列出引用该动作的编排。检查范围为脚本和工作流的草稿及最新版本。

GET /automation/v1/actions/{ns}/{name}/dependents

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
query: limitinteger可选；每页条数，整数 1–100，默认 20。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/dependents" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.dependents.list({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的引用方（脚本与工作流，口径为最新版本加草稿），按 created_at 倒序、id 倒序排列。
data[].kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[].namespacestring必填 / 必有；引用方的命名空间。
data[].namestring必填 / 必有；引用方的名字。
data[].atstring必填 / 必有；引用所在的草稿或最新版本号：draft 表示草稿，其余值为该编排最新发布的版本号。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

归档动作

归档后保留名称和历史，默认列表不再显示；响应包含 dependents_count，便于判断对引用方的影响。

POST /automation/v1/actions/{ns}/{name}/archive

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.archive({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。
namespacestring必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。
namestring必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。
descriptionstring必填 / 必有；动作说明，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。
builtinboolean必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。
current_revisionobject必填 / 必有；动作的一个不可变修订：契约、实现和运行参数的快照。每次更新兼容的内容变化都会产生新修订。 不接受额外字段。
current_revision.idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
current_revision.digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
current_revision.input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.input_schema.*（分支5)object递归 JSON 值。
current_revision.input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.output_schema.*（分支5)object递归 JSON 值。
current_revision.output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
current_revision.errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
current_revision.errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
current_revision.errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
current_revision.annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
current_revision.annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
current_revision.annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
current_revision.timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
current_revision.implementationobject / object / object必填 / 必有；code 使用 language=ts 与 source。container 和 shell 暂未开放，创建时返回 OPERATION_NOT_SUPPORTED。
current_revision.implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
current_revision.implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
current_revision.implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
current_revision.implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
current_revision.implementation（分支2).imagestring必填 / 必有；容器镜像引用。
current_revision.implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
current_revision.implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
current_revision.implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
current_revision.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
current_revision.platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
current_revision.created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
current_revision.created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
current_revision.created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
current_revision.messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
current_revision.created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
stats_7dobject必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。
stats_7d.callsnumber必填 / 必有；近七天内对该动作的调用次数，按小时汇总。
stats_7d.failuresnumber必填 / 必有；近七天内失败的调用次数。
stats_7d.p50_msnull / number必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。
dependentsobject必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。
dependents.scriptsnumber必填 / 必有；引用该动作的脚本数量。
dependents.workflowsnumber必填 / 必有；引用该动作的工作流数量。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。
dependents_countinteger必填 / 必有；归档时仍引用该动作的脚本与工作流数量之和（dependents.scripts 加 dependents.workflows）。 minimum: 0

实测响应

HTTP 200

{
  "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
  "owner": "tnt_3a9759864ccb4e00",
  "namespace": "docs-samples",
  "name": "sample-action-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "builtin": false,
  "archived_at": "2026-10-13T04:57:17.830Z",
  "created_at": "2026-10-13T04:57:09.039Z",
  "updated_at": "2026-10-13T04:57:17.830Z",
  "current_revision": {
    "id": "actr_00mv67lu25f7f28dd81a924c698b9d2557056a7b62",
    "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "errors": [],
    "annotations": {
      "read_only": false,
      "idempotent": false
    },
    "timeout_ms": 30000,
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    },
    "host": "isolate",
    "platform_apis": [],
    "created_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    },
    "message": "回滚到 actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
    "created_at": "2026-10-13T04:57:15.629Z"
  },
  "stats_7d": {
    "calls": 0,
    "failures": 0,
    "p50_ms": null
  },
  "dependents": {
    "scripts": 0,
    "workflows": 0
  },
  "dependents_count": 0
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

恢复动作

恢复已归档动作，保留当前修订。恢复后重新出现在默认列表。

POST /automation/v1/actions/{ns}/{name}/restore

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
ACTION_NAME创建动作返回的 name
: "${ACTION_NAME:?Set ACTION_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/actions/docs-samples/${ACTION_NAME}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.actions.restore({
  "path": {
    "ns": "docs-samples",
    "name": env("ACTION_NAME")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；动作 ID，前缀 act_；日常调用使用 namespace 与 name，而不是 id。
namespacestring必填 / 必有；动作命名空间；平台动作为 praxis，裸名引用解析到 praxis。
namestring必填 / 必有；动作名，与 namespace 一起唯一标识动作；小写字母、数字、点、下划线、连字符，最长 64 字符。
descriptionstring必填 / 必有；动作说明，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；动作所属租户，由网关注入；按不透明字符串处理。
builtinboolean必填 / 必有；true 表示平台内置动作（命名空间 praxis）；用户创建的动作为 false。
current_revisionobject必填 / 必有；动作的一个不可变修订：契约、实现和运行参数的快照。每次更新兼容的内容变化都会产生新修订。 不接受额外字段。
current_revision.idstring必填 / 必有；修订 ID，前缀 actr_；仅用于展示与回滚（rollback 的 revision），不能被脚本直接引用。
current_revision.digeststring必填 / 必有；契约与实现的内容摘要；内容相同的更新不会产生新修订。
current_revision.input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.input_schema.*（分支5)object递归 JSON 值。
current_revision.input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.output_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
current_revision.output_schema.*（分支5)object递归 JSON 值。
current_revision.output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
current_revision.errorsobject[]必填 / 必有；动作声明的可能错误列表，每项含 type、code、description。
current_revision.errors[].typestring必填 / 必有；错误类型：稳定的 URI，或 Open Workflow 标准类型（如 validation、timeout、communication、runtime）。
current_revision.errors[].codestring可选；可选的稳定错误码，供调用方按码分支处理。
current_revision.errors[].descriptionstring必填 / 必有；该错误的含义与触发条件，面向调用方阅读。
current_revision.annotationsobject必填 / 必有；动作行为声明 {read_only, idempotent}；创建时未给出的键默认为 false。 不接受额外字段。
current_revision.annotations.read_onlyboolean必填 / 必有；true 表示动作不修改外部状态，只读取数据。
current_revision.annotations.idempotentboolean必填 / 必有；true 表示同一输入重复调用与调用一次效果相同；此类动作的重试使用同一幂等键（run_id 加步骤路径，不含尝试次数）。
current_revision.timeout_msnumber必填 / 必有；单次执行的超时毫秒数；创建时未给出，code 实现默认 30000，容器或 shell 实现默认 600000。
current_revision.implementationobject / object / object必填 / 必有；code 使用 language=ts 与 source。container 和 shell 暂未开放，创建时返回 OPERATION_NOT_SUPPORTED。
current_revision.implementation（分支1).kind"code"必填 / 必有；固定为 code：以源码实现。
current_revision.implementation（分支1).language"ts"必填 / 必有；源码语言，目前只支持 ts（TypeScript）。
current_revision.implementation（分支1).sourcestring必填 / 必有；动作的完整 TypeScript 源码；内置动作为空。
current_revision.implementation（分支2).kind"container"必填 / 必有；固定为 container：以容器镜像实现（暂未开放）。
current_revision.implementation（分支2).imagestring必填 / 必有；容器镜像引用。
current_revision.implementation（分支2).commandstring[]必填 / 必有；在容器中执行的命令及参数列表。
current_revision.implementation（分支3).kind"shell"必填 / 必有；固定为 shell：以 shell 脚本实现（暂未开放）。
current_revision.implementation（分支3).scriptstring必填 / 必有；要执行的 shell 脚本全文。
current_revision.host"builtin" / "isolate" / "sandbox"必填 / 必有；动作运行位置，发布时计算。builtin 为平台内置动作；isolate 为在隔离的 Worker isolate 中运行用户代码；sandbox 为在沙箱中运行（container 与 shell 实现）。
current_revision.platform_apisstring[]必填 / 必有；从代码推导出的平台 API 集合，同时是该动作运行令牌的权限范围（最小权限）。
current_revision.created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
current_revision.created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
current_revision.created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
current_revision.messagenull / string必填 / 必有；创建该修订时附带的说明；未提供为 null。
current_revision.created_atstring必填 / 必有；该修订的创建时间（RFC 3339 UTC）。
stats_7dobject必填 / 必有；近七天统计；平台动作按调用方租户隔离，只反映当前调用方的调用，不是平台全局统计。 不接受额外字段。
stats_7d.callsnumber必填 / 必有；近七天内对该动作的调用次数，按小时汇总。
stats_7d.failuresnumber必填 / 必有；近七天内失败的调用次数。
stats_7d.p50_msnull / number必填 / 必有；耗时中位数的近似上界，单位毫秒；正耗时向上归入 2 的幂分桶（9 ms → 16 ms），0 独立一桶；无有效耗时样本时为 null。
dependentsobject必填 / 必有；引用该动作的脚本与工作流数量，口径为最新版本加草稿。 不接受额外字段。
dependents.scriptsnumber必填 / 必有；引用该动作的脚本数量。
dependents.workflowsnumber必填 / 必有；引用该动作的工作流数量。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不能复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "act_00mv67loz4fe4f27bdf89346c885b3a28b2038c091",
  "owner": "tnt_3a9759864ccb4e00",
  "namespace": "docs-samples",
  "name": "sample-action-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "builtin": false,
  "archived_at": null,
  "created_at": "2026-10-13T04:57:09.039Z",
  "updated_at": "2026-10-13T04:57:18.573Z",
  "current_revision": {
    "id": "actr_00mv67lu25f7f28dd81a924c698b9d2557056a7b62",
    "digest": "e35c209873c60486ca8da455878062cb7ea572a6147ce3ca03e0693b4769fa45",
    "input_schema": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number"
        }
      },
      "required": [
        "n"
      ],
      "additionalProperties": false
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "answer": {
          "type": "number"
        }
      },
      "required": [
        "answer"
      ],
      "additionalProperties": false
    },
    "errors": [],
    "annotations": {
      "read_only": false,
      "idempotent": false
    },
    "timeout_ms": 30000,
    "implementation": {
      "kind": "code",
      "language": "ts",
      "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
    },
    "host": "isolate",
    "platform_apis": [],
    "created_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    },
    "message": "回滚到 actr_00mv67loz3e46938b8ecf54e57b8f31297df016a1c",
    "created_at": "2026-10-13T04:57:15.629Z"
  },
  "stats_7d": {
    "calls": 0,
    "failures": 0,
    "p50_ms": null
  },
  "dependents": {
    "scripts": 0,
    "workflows": 0
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404ACTION_NOT_FOUND：动作不存在或当前租户不可见；同名脚本/工作流存在时，hint 指向相应接口。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出脚本

列出可见脚本的摘要、最新版本、标签及近七天统计；默认排除已归档条目。

GET /automation/v1/scripts

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
query: limitinteger可选；每页条数，整数 1–100，默认 25。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: qstring可选；不区分大小写，按名称或说明的字面子串匹配；% 与 _ 无通配含义。
query: namespacestring[]可选；仅返回指定命名空间的定义，名称按小写匹配。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: scope"platform" / "own"[]可选；platform 仅平台定义，own 仅租户自建定义；省略返回两者。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: archivedboolean可选；true 仅已归档，false 仅未归档；默认 false。
query: labelsobject可选；按标签过滤，使用 labels[k]=v；同键逗号多值取任一，不同键同时满足。
query: created_at[gte]string可选；创建时间下界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"
query: created_at[lte]string可选；创建时间上界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"

示例

SDK 安装与示例环境

curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "namespace=docs-samples" \
  --data-urlencode "limit=1"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.list({
  "query": {
    "namespace": [
      "docs-samples"
    ],
    "limit": 1
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的脚本摘要，按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
data[].kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[].namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
data[].namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
data[].descriptionstring必填 / 必有；说明文字，最多 1000 字符。
data[].labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
data[].ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
data[].latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
data[].latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
data[].latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
data[].dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
data[].draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
data[].latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
data[].latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
data[].latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
data[].latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
data[].latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
data[].latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
data[].latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data[].latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data[].latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data[].latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data[].latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data[].latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data[].latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data[].latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data[].latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data[].latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data[].latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data[].latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data[].latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
data[].stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
data[].stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
data[].stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
data[].archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
data[].created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
data[].updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
      "owner": "tnt_3a9759864ccb4e00",
      "kind": "script",
      "namespace": "docs-samples",
      "name": "sample-scripts-1791867412840-b05e8a",
      "description": "",
      "labels": {},
      "latest_version": null,
      "dist_tags": {},
      "draft_changed": true,
      "latest_run": null,
      "stats_7d": {
        "runs": 0,
        "failures": 0
      },
      "archived_at": null,
      "created_at": "2026-10-13T04:57:19.277Z",
      "updated_at": "2026-10-13T04:57:19.277Z"
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

创建脚本

创建脚本及可编辑草稿，不会发布或启动运行；脚本与工作流共用名称空间，同租户重名返回 NAME_TAKEN。

POST /automation/v1/scripts

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

不接受额外字段。

字段类型说明
namespacestring必填 / 必有；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9.-]{0,63}；praxis 只读。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$"
namestring必填 / 必有；名称，存储前转为小写，格式 [a-z0-9][a-z0-9.-]{0,63}。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$"
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
draftstring可选；可编辑源码；脚本为 TypeScript，工作流为 YAML。创建时省略为空字符串。
labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。

示例

SDK 安装与示例环境

curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "namespace": "docs-samples",
  "name": "sample-scripts",
  "draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.create({
  "body": {
    "namespace": "docs-samples",
    "name": "sample-scripts",
    "draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
draftobject必填 / 必有；脚本或工作流的可编辑草稿；发布版本时以草稿或某次运行的源码为准。 不接受额外字段。
draft.sourcestring必填 / 必有；草稿源码：脚本为 TypeScript，工作流为 YAML。
draft.revisionstring必填 / 必有；草稿修订标识（ETag），发布时作为 expected_draft_revision，更新草稿时作为 If-Match；与当前不一致返回 412。
draft.updated_atstring必填 / 必有；草稿最近一次修改的时间（RFC 3339 UTC）。
draft.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
draft.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
draft.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "script",
  "namespace": "docs-samples",
  "name": "sample-scripts-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "latest_version": null,
  "dist_tags": {},
  "draft_changed": true,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:19.277Z",
  "updated_at": "2026-10-13T04:57:19.277Z",
  "draft": {
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
    "revision": "draft_00mv67lwvh333793ba7d9e47cb89b5fd8b43fb4fa3",
    "updated_at": "2026-10-13T04:57:19.277Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 NAME_TAKEN：名称已被同一租户占用。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取脚本

读取脚本详情及草稿源码；ETag 是草稿修订，可作为修改请求的 If-Match。

GET /automation/v1/scripts/{ns}/{name}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.retrieve({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent resource revision for conditional updates.

application/json

字段类型说明
draftobject必填 / 必有；脚本或工作流的可编辑草稿；发布版本时以草稿或某次运行的源码为准。 不接受额外字段。
draft.sourcestring必填 / 必有；草稿源码：脚本为 TypeScript，工作流为 YAML。
draft.revisionstring必填 / 必有；草稿修订标识（ETag），发布时作为 expected_draft_revision，更新草稿时作为 If-Match；与当前不一致返回 412。
draft.updated_atstring必填 / 必有；草稿最近一次修改的时间（RFC 3339 UTC）。
draft.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
draft.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
draft.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "script",
  "namespace": "docs-samples",
  "name": "sample-scripts-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "latest_version": null,
  "dist_tags": {},
  "draft_changed": true,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:19.277Z",
  "updated_at": "2026-10-13T04:57:19.277Z",
  "draft": {
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
    "revision": "draft_00mv67lwvh333793ba7d9e47cb89b5fd8b43fb4fa3",
    "updated_at": "2026-10-13T04:57:19.277Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

更新脚本草稿

修改说明、标签或草稿，必须携带与当前草稿匹配的 If-Match；即使只改元数据也会生成新的草稿修订。

PATCH /automation/v1/scripts/{ns}/{name}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
header: If-Matchstring必填；当前资源的 ETag，可直接使用对象里的 draft.revision 或 etag 字段值：裸值、带双引号或弱校验写法 W/"…" 均接受（RFC 7232 弱比较）；缺失返回 400，修订不匹配返回 412。

application/json

不接受额外字段。

字段类型说明
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。
draftstring可选；可编辑源码；脚本为 TypeScript，工作流为 YAML。创建时省略为空字符串。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
ETAG最新 GET 响应头 ETag（保留引号）
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PATCH "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "If-Match: ${ETAG}" \
  -H "Content-Type: application/json" \
  --data '{
  "description": "Sample definition",
  "draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.update({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME")
  },
  "headers": {
    "If-Match": env("ETAG")
  },
  "body": {
    "description": "Sample definition",
    "draft": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
draftobject必填 / 必有；脚本或工作流的可编辑草稿；发布版本时以草稿或某次运行的源码为准。 不接受额外字段。
draft.sourcestring必填 / 必有；草稿源码：脚本为 TypeScript，工作流为 YAML。
draft.revisionstring必填 / 必有；草稿修订标识（ETag），发布时作为 expected_draft_revision，更新草稿时作为 If-Match；与当前不一致返回 412。
draft.updated_atstring必填 / 必有；草稿最近一次修改的时间（RFC 3339 UTC）。
draft.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
draft.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
draft.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "script",
  "namespace": "docs-samples",
  "name": "sample-scripts-1791867412840-b05e8a",
  "description": "Sample definition",
  "labels": {},
  "latest_version": null,
  "dist_tags": {},
  "draft_changed": true,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:19.277Z",
  "updated_at": "2026-10-13T04:57:21.691Z",
  "draft": {
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
    "revision": "draft_00mv67lwvh333793ba7d9e47cb89b5fd8b43fb4fa3",
    "updated_at": "2026-10-13T04:57:19.277Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

归档脚本

归档后保留名称、版本和草稿；默认列表隐藏该条目，新的目标解析和运行请求拒绝已归档目标。

POST /automation/v1/scripts/{ns}/{name}/archive

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.archive({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "script",
  "namespace": "docs-samples",
  "name": "sample-scripts-1791867412840-b05e8a",
  "description": "Sample definition",
  "labels": {},
  "latest_version": {
    "version": "1.0.0",
    "published_at": "2026-10-13T04:57:22.398Z"
  },
  "dist_tags": {
    "latest": "1.0.0"
  },
  "draft_changed": false,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": "2026-10-13T04:57:27.639Z",
  "created_at": "2026-10-13T04:57:19.277Z",
  "updated_at": "2026-10-13T04:57:27.639Z"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

恢复脚本

恢复已归档定义，保留版本和标签。名称无需重新分配。

POST /automation/v1/scripts/{ns}/{name}/restore

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.restore({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "scr_00mv67lwvh08624c70ef824a0d8b14b0315c88452e",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "script",
  "namespace": "docs-samples",
  "name": "sample-scripts-1791867412840-b05e8a",
  "description": "Sample definition",
  "labels": {},
  "latest_version": {
    "version": "1.0.0",
    "published_at": "2026-10-13T04:57:22.398Z"
  },
  "dist_tags": {
    "latest": "1.0.0"
  },
  "draft_changed": false,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:19.277Z",
  "updated_at": "2026-10-13T04:57:28.559Z"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

发布脚本版本

从草稿或临时运行源码发布版本，校验定义并锁定依赖。草稿须匹配 expected_draft_revision；临时运行由 from_run 与 expected_source_sha256 指定。版本相同且内容相同返回已有版本，内容不同返回 VERSION_EXISTS；预发布版本必须显式带 tag（不能是 latest，tag 只能含 URL 安全字符且不能是版本号或范围，违规返回 TAG_REQUIRED 或 TAG_INVALID，hint 给出完整规则），校验不通过返回 DEFINITION_INVALID。稳定版本仅高于已有最高稳定版本时自动移动 latest；工作流成为 latest 时同步定义中的定时触发器。 发布会去掉版本号的 +build 元数据。

POST /automation/v1/scripts/{ns}/{name}/versions

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

字段类型说明
（分支1).versionstring必填 / 必有；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。
（分支1).expected_draft_revisionstring必填 / 必有；发布的草稿修订，必须匹配当前草稿；与 from_run 发布方式二选一。
（分支1).tagstring可选；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。
（分支2).versionstring必填 / 必有；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。
（分支2).from_runstring必填 / 必有；提供源码快照的临时运行 ID；已发布目标的运行当前没有可用于此入口的快照。须同时给出 expected_source_sha256，不能同时给 expected_draft_revision。
（分支2).expected_source_sha256string必填 / 必有；运行源码的 SHA-256 摘要，必须与快照匹配。
（分支2).tagstring可选；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
DRAFT_REVISION当前 draft.revision
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
: "${DRAFT_REVISION:?Set DRAFT_REVISION}"
BODY=$(jq -n --arg DRAFT_REVISION "$DRAFT_REVISION" '{
  "version": "1.0.0",
  "expected_draft_revision": $DRAFT_REVISION
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$BODY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.versions.publish({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME")
  },
  "body": {
    "version": "1.0.0",
    "expected_draft_revision": env("DRAFT_REVISION")
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
digeststring必填 / 必有；源码与契约的内容摘要。
sourcestring必填 / 必有；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
input_schema.*（分支5)object递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
output_schema.*（分支5)object递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
outline（分支2)[].children[]object递归 JSON 值。
sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
  "kind": "script",
  "version": "1.0.0",
  "digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ]
  },
  "references": [],
  "outline": null,
  "sdk_version": "0.1.0",
  "published_at": "2026-10-13T04:57:22.398Z",
  "published_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "deprecated": null,
  "deprecated_at": null,
  "deprecated_by": null,
  "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 TAG_REQUIRED：预发布版本必须显式指定发布标签（例如 beta，不能是 latest）；响应 hint 列出完整规则。 TAG_INVALID：标签无效：预发布版本不能打 latest；tag 只能含 URL 安全字符（不含空格和 / ? #）；不能是版本号或范围；latest 不能删除。响应 hint 列出完整规则。 DEFINITION_INVALID：源码未通过定义校验。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 RUN_NOT_FOUND：运行不存在或当前租户不可见。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。 VERSION_EXISTS：版本号已存在且源码内容不同。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。 DEFINITION_IDENTITY_MISMATCH：源码声明或运行语言与发布目标不一致。 NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。 CYCLE_DETECTED：发布后依赖会形成环（A 依赖 B、B 又依赖 A）；detail 给出环路径。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出脚本版本

按语义版本倒序分页列出不可变的 schema 和锁定依赖。默认不带源码；仅 expand=source 带完整源码，其它值返回 400。详情接口保持全文。

GET /automation/v1/scripts/{ns}/{name}/versions

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
query: limitinteger可选；每页条数，整数 1–100，默认 25。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: expand"source"可选；仅接受 source；默认不带源码，其它值返回 400。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.versions.list({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的脚本版本（默认不含源码，expand=source 才带），按 semver 降序排列。
data[].idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
data[].kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[].versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
data[].digeststring必填 / 必有；源码与契约的内容摘要。
data[].sourcestring可选；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
data[].input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
data[].input_schema.*（分支5)object递归 JSON 值。
data[].input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
data[].output_schema.*（分支5)object递归 JSON 值。
data[].output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
data[].references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
data[].references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
data[].references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
data[].references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
data[].outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
data[].outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
data[].outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
data[].outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
data[].outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
data[].outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
data[].outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
data[].outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
data[].outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
data[].outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
data[].outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
data[].outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
data[].outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
data[].outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
data[].outline（分支2)[].children[]object递归 JSON 值。
data[].sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
data[].published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
data[].published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
data[].published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[].deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
data[].deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
data[].deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
data[].deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
      "kind": "script",
      "version": "1.0.0",
      "digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
      "input_schema": {
        "type": "object",
        "properties": {
          "n": {
            "type": "number"
          }
        },
        "required": [
          "n"
        ]
      },
      "output_schema": {
        "type": "object",
        "properties": {
          "answer": {
            "type": "number"
          }
        },
        "required": [
          "answer"
        ]
      },
      "references": [],
      "outline": null,
      "sdk_version": "0.1.0",
      "published_at": "2026-10-13T04:57:22.398Z",
      "published_by": {
        "type": "api_key",
        "id": "key_3e00b8984967"
      },
      "deprecated": null,
      "deprecated_at": null,
      "deprecated_by": null
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取脚本版本

读取精确版本的源码、输入输出契约及弃用说明；版本缺失返回 VERSION_NOT_FOUND。 详情始终返回完整源码。 version 接受精确版本或 dist-tag；range 返回 400，hint 提示改用 /resolve。

GET /automation/v1/scripts/{ns}/{name}/versions/{version}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: versionstring必填；精确版本或 dist-tag；不接受 range（400，带 hint）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions/1.0.0" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.versions.retrieve({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME"),
    "version": "1.0.0"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
digeststring必填 / 必有；源码与契约的内容摘要。
sourcestring必填 / 必有；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
input_schema.*（分支5)object递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
output_schema.*（分支5)object递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
outline（分支2)[].children[]object递归 JSON 值。
sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
  "kind": "script",
  "version": "1.0.0",
  "digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ]
  },
  "references": [],
  "outline": null,
  "sdk_version": "0.1.0",
  "published_at": "2026-10-13T04:57:22.398Z",
  "published_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "deprecated": null,
  "deprecated_at": null,
  "deprecated_by": null,
  "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

弃用脚本版本

记录版本弃用说明；message 为空字符串时取消弃用，版本源码不变。

POST /automation/v1/scripts/{ns}/{name}/versions/{version}/deprecate

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: versionstring必填；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。

application/json

不接受额外字段。

字段类型说明
messagestring必填 / 必有；弃用说明；空字符串取消弃用。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/versions/1.0.0/deprecate" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "message": ""
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.versions.deprecate({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME"),
    "version": "1.0.0"
  },
  "body": {
    "message": ""
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
digeststring必填 / 必有；源码与契约的内容摘要。
sourcestring必填 / 必有；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
input_schema.*（分支5)object递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
output_schema.*（分支5)object递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
outline（分支2)[].children[]object递归 JSON 值。
sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
  "kind": "script",
  "version": "1.0.0",
  "digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ]
  },
  "references": [],
  "outline": null,
  "sdk_version": "0.1.0",
  "published_at": "2026-10-13T04:57:22.398Z",
  "published_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "deprecated": null,
  "deprecated_at": null,
  "deprecated_by": null,
  "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出脚本标签

读取发布标签指向的精确版本。同时返回更新时间和更新者。

GET /automation/v1/scripts/{ns}/{name}/dist-tags

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/dist-tags" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.distTags.list({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
.*.versionstring必填 / 必有；标签当前指向的精确版本号。
.*.updated_atstring必填 / 必有；标签最近一次移动的时间（RFC 3339 UTC）。
.*.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
.*.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
.*.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "latest": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:22.398Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

设置脚本标签

将发布标签指向已有精确版本，标签不能是版本号或版本范围；移动 latest 可用于回滚，工作流会同步定时触发器。

PUT /automation/v1/scripts/{ns}/{name}/dist-tags/{tag}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: tagstring必填；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。

application/json

不接受额外字段。

字段类型说明
versionstring必填 / 必有；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X PUT "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/dist-tags/sample" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "version": "1.0.0"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.distTags.set({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME"),
    "tag": "sample"
  },
  "body": {
    "version": "1.0.0"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
.*.versionstring必填 / 必有；标签当前指向的精确版本号。
.*.updated_atstring必填 / 必有；标签最近一次移动的时间（RFC 3339 UTC）。
.*.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
.*.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
.*.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "latest": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:22.398Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  },
  "sample": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:26.232Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 TAG_INVALID：标签无效：预发布版本不能打 latest；tag 只能含 URL 安全字符（不含空格和 / ? #）；不能是版本号或范围；latest 不能删除。响应 hint 列出完整规则。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

删除脚本标签

删除发布标签但保留版本；latest 不可删除，标签不能是版本号或范围，不存在的合法标签可重复删除。

DELETE /automation/v1/scripts/{ns}/{name}/dist-tags/{tag}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: tagstring必填；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
SCRIPT_NAME创建脚本返回的 name
: "${SCRIPT_NAME:?Set SCRIPT_NAME}"
curl --fail-with-body -X DELETE "https://api.deepraxis.ai/automation/v1/scripts/docs-samples/${SCRIPT_NAME}/dist-tags/sample" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.scripts.distTags.delete({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME"),
    "tag": "sample"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
.*.versionstring必填 / 必有；标签当前指向的精确版本号。
.*.updated_atstring必填 / 必有；标签最近一次移动的时间（RFC 3339 UTC）。
.*.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
.*.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
.*.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "latest": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:22.398Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 TAG_INVALID：标签无效：预发布版本不能打 latest；tag 只能含 URL 安全字符（不含空格和 / ? #）；不能是版本号或范围；latest 不能删除。响应 hint 列出完整规则。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出工作流

列出可见工作流的摘要、最新版本、标签及近七天统计；默认排除已归档条目。

GET /automation/v1/workflows

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
query: limitinteger可选；每页条数，整数 1–100，默认 25。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: qstring可选；不区分大小写，按名称或说明的字面子串匹配；% 与 _ 无通配含义。
query: namespacestring[]可选；仅返回指定命名空间的定义，名称按小写匹配。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: scope"platform" / "own"[]可选；platform 仅平台定义，own 仅租户自建定义；省略返回两者。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: archivedboolean可选；true 仅已归档，false 仅未归档；默认 false。
query: labelsobject可选；按标签过滤，使用 labels[k]=v；同键逗号多值取任一，不同键同时满足。
query: created_at[gte]string可选；创建时间下界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"
query: created_at[lte]string可选；创建时间上界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"

示例

SDK 安装与示例环境

curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "namespace=docs-samples" \
  --data-urlencode "limit=1"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.list({
  "query": {
    "namespace": [
      "docs-samples"
    ],
    "limit": 1
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的工作流摘要，按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
data[].kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[].namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
data[].namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
data[].descriptionstring必填 / 必有；说明文字，最多 1000 字符。
data[].labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
data[].ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
data[].latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
data[].latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
data[].latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
data[].dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
data[].draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
data[].latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
data[].latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
data[].latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
data[].latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
data[].latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
data[].latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
data[].latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data[].latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data[].latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data[].latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data[].latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data[].latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data[].latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data[].latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data[].latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data[].latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data[].latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data[].latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data[].latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
data[].stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
data[].stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
data[].stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
data[].archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
data[].created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
data[].updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
      "owner": "tnt_3a9759864ccb4e00",
      "kind": "workflow",
      "namespace": "docs-samples",
      "name": "sample-workflows-1791867412840-b05e8a",
      "description": "",
      "labels": {},
      "latest_version": null,
      "dist_tags": {},
      "draft_changed": true,
      "latest_run": null,
      "stats_7d": {
        "runs": 0,
        "failures": 0
      },
      "archived_at": null,
      "created_at": "2026-10-13T04:57:29.206Z",
      "updated_at": "2026-10-13T04:57:29.206Z"
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

创建工作流

创建工作流及可编辑草稿，不会发布或启动运行；脚本与工作流共用名称空间，同租户重名返回 NAME_TAKEN。 run.workflow 支持 ns/name@range 或 {namespace, name, version, input}；run.script 使用相同引用形状（平台扩展）。 对象的 namespace、name、version 必填；version 支持精确版本、dist-tag 或范围，发布时锁定依赖。 对象 input 默认为 {}，支持表达式；字符串引用继续使用任务级 with。run.await 默认 true，等待子运行输出； false 以 detach 创建子运行，任务立即输出 {run_id}，父取消不级联。内联 script.code 返回 DEFINITION_INVALID， detail 提示「请先保存为脚本再引用」。raise.error 的 type URI、status、title、detail 保留到运行错误。

POST /automation/v1/workflows

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

不接受额外字段。

字段类型说明
namespacestring必填 / 必有；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9.-]{0,63}；praxis 只读。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$"
namestring必填 / 必有；名称，存储前转为小写，格式 [a-z0-9][a-z0-9.-]{0,63}。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$"
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
draftstring可选；可编辑源码；脚本为 TypeScript，工作流为 YAML。创建时省略为空字符串。
labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。

示例

SDK 安装与示例环境

curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "namespace": "docs-samples",
  "name": "sample-workflows",
  "draft": "document:\n  dsl: '\''1.0.3'\''\n  namespace: docs-samples\n  name: sample-workflows\n  version: '\''1.0.0'\''\ndo:\n  - answer:\n      set:\n        answer: 42\n"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.create({
  "body": {
    "namespace": "docs-samples",
    "name": "sample-workflows",
    "draft": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n"
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
draftobject必填 / 必有；脚本或工作流的可编辑草稿；发布版本时以草稿或某次运行的源码为准。 不接受额外字段。
draft.sourcestring必填 / 必有；草稿源码：脚本为 TypeScript，工作流为 YAML。
draft.revisionstring必填 / 必有；草稿修订标识（ETag），发布时作为 expected_draft_revision，更新草稿时作为 If-Match；与当前不一致返回 412。
draft.updated_atstring必填 / 必有；草稿最近一次修改的时间（RFC 3339 UTC）。
draft.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
draft.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
draft.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "workflow",
  "namespace": "docs-samples",
  "name": "sample-workflows-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "latest_version": null,
  "dist_tags": {},
  "draft_changed": true,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:29.206Z",
  "updated_at": "2026-10-13T04:57:29.206Z",
  "draft": {
    "source": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n",
    "revision": "draft_00mv67m4ja0e38625d463646e3a526bb774bf453ee",
    "updated_at": "2026-10-13T04:57:29.206Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 NAME_TAKEN：名称已被同一租户占用。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取工作流

读取工作流详情及草稿源码；ETag 是草稿修订，可作为修改请求的 If-Match。

GET /automation/v1/workflows/{ns}/{name}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.retrieve({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent resource revision for conditional updates.

application/json

字段类型说明
draftobject必填 / 必有；脚本或工作流的可编辑草稿；发布版本时以草稿或某次运行的源码为准。 不接受额外字段。
draft.sourcestring必填 / 必有；草稿源码：脚本为 TypeScript，工作流为 YAML。
draft.revisionstring必填 / 必有；草稿修订标识（ETag），发布时作为 expected_draft_revision，更新草稿时作为 If-Match；与当前不一致返回 412。
draft.updated_atstring必填 / 必有；草稿最近一次修改的时间（RFC 3339 UTC）。
draft.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
draft.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
draft.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "workflow",
  "namespace": "docs-samples",
  "name": "sample-workflows-1791867412840-b05e8a",
  "description": "",
  "labels": {},
  "latest_version": null,
  "dist_tags": {},
  "draft_changed": true,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:29.206Z",
  "updated_at": "2026-10-13T04:57:29.206Z",
  "draft": {
    "source": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n",
    "revision": "draft_00mv67m4ja0e38625d463646e3a526bb774bf453ee",
    "updated_at": "2026-10-13T04:57:29.206Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

更新工作流草稿

修改说明、标签或草稿，必须携带与当前草稿匹配的 If-Match；即使只改元数据也会生成新的草稿修订。

PATCH /automation/v1/workflows/{ns}/{name}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
header: If-Matchstring必填；当前资源的 ETag，可直接使用对象里的 draft.revision 或 etag 字段值：裸值、带双引号或弱校验写法 W/"…" 均接受（RFC 7232 弱比较）；缺失返回 400，修订不匹配返回 412。

application/json

不接受额外字段。

字段类型说明
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。
draftstring可选；可编辑源码；脚本为 TypeScript，工作流为 YAML。创建时省略为空字符串。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
ETAG最新 GET 响应头 ETag（保留引号）
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PATCH "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "If-Match: ${ETAG}" \
  -H "Content-Type: application/json" \
  --data '{
  "description": "Sample definition",
  "draft": "document:\n  dsl: '\''1.0.3'\''\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '\''1.0.0'\''\ndo:\n  - answer:\n      set:\n        answer: 42\n"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.update({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME")
  },
  "headers": {
    "If-Match": env("ETAG")
  },
  "body": {
    "description": "Sample definition",
    "draft": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
draftobject必填 / 必有；脚本或工作流的可编辑草稿；发布版本时以草稿或某次运行的源码为准。 不接受额外字段。
draft.sourcestring必填 / 必有；草稿源码：脚本为 TypeScript，工作流为 YAML。
draft.revisionstring必填 / 必有；草稿修订标识（ETag），发布时作为 expected_draft_revision，更新草稿时作为 If-Match；与当前不一致返回 412。
draft.updated_atstring必填 / 必有；草稿最近一次修改的时间（RFC 3339 UTC）。
draft.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
draft.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
draft.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "workflow",
  "namespace": "docs-samples",
  "name": "sample-workflows-1791867412840-b05e8a",
  "description": "Sample definition",
  "labels": {},
  "latest_version": null,
  "dist_tags": {},
  "draft_changed": true,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:29.206Z",
  "updated_at": "2026-10-13T04:57:31.570Z",
  "draft": {
    "source": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n",
    "revision": "draft_00mv67m4ja0e38625d463646e3a526bb774bf453ee",
    "updated_at": "2026-10-13T04:57:29.206Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

归档工作流

归档后保留名称、版本和草稿；默认列表隐藏该条目，新的目标解析和运行请求拒绝已归档目标。

POST /automation/v1/workflows/{ns}/{name}/archive

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/archive" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.archive({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "workflow",
  "namespace": "docs-samples",
  "name": "sample-workflows-1791867412840-b05e8a",
  "description": "Sample definition",
  "labels": {},
  "latest_version": {
    "version": "1.0.0",
    "published_at": "2026-10-13T04:57:32.297Z"
  },
  "dist_tags": {
    "latest": "1.0.0"
  },
  "draft_changed": false,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": "2026-10-13T04:57:37.671Z",
  "created_at": "2026-10-13T04:57:29.206Z",
  "updated_at": "2026-10-13T04:57:37.671Z"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

恢复工作流

恢复已归档定义，保留版本和标签。名称无需重新分配。

POST /automation/v1/workflows/{ns}/{name}/restore

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/restore" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.restore({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；编排 ID，脚本前缀 scr_，工作流前缀 wf_；日常使用 namespace 与 name。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；命名空间，引用形如 namespace/name@版本。
namestring必填 / 必有；名字，与 namespace 一起在租户内唯一，脚本与工作流共用命名空间，重名返回 409 NAME_TAKEN。
descriptionstring必填 / 必有；说明文字，最多 1000 字符。
labelsobject必填 / 必有；用户自定义标签：字符串键值对，用于分类与列表过滤（labels[key]=value）；键不能以 praxis. 开头。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
latest_versionnull / object必填 / 必有；latest 标签指向的已发布版本 {version, published_at}；尚未发布为 null。
latest_version（分支2).versionstring必填 / 必有；最新发布版本的版本号（semver）。
latest_version（分支2).published_atstring必填 / 必有；该版本的发布时间（RFC 3339 UTC）。
dist_tagsobject必填 / 必有；标签到精确版本号的映射，例如 latest 指向 1.2.0；用 ns/name@标签 运行时按此解析。
draft_changedboolean必填 / 必有；true 表示草稿内容（摘要）不同于 latest 版本，即有未发布的改动。
latest_runnull / object必填 / 必有；该编排最近一次运行的摘要；还没有运行为 null。
latest_run（分支2).idstring必填 / 必有；运行 ID（run_ 前缀），可用于 runs.retrieve。
latest_run（分支2).numbernull / number必填 / 必有；运行在该脚本或工作流内的递增序号。
latest_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
latest_run（分支2).created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
latest_run（分支2).current_waitnull / object必填 / 必有；当前未完成的等待点；没有等待为 null。
latest_run（分支2).current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
latest_run（分支2).current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
latest_run（分支2).current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
latest_run（分支2).current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
latest_run（分支2).current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
latest_run（分支2).current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
latest_run（分支2).current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
latest_run（分支2).current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
latest_run（分支2).current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
latest_run（分支2).current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
latest_run（分支2).current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
latest_run（分支2).current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
latest_run（分支2).current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
stats_7dobject必填 / 必有；近七天的运行统计：按运行结束日期累计，在运行结束时更新，读取时不扫描运行。 不接受额外字段。
stats_7d.runsnumber必填 / 必有；近七天内结束的运行总数（任意终态）。
stats_7d.failuresnumber必填 / 必有；其中以 faulted 结束的运行数。
archived_atnull / string必填 / 必有；归档时间；未归档为 null。归档后名字保留，不可复用。
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。

实测响应

HTTP 200

{
  "id": "wf_00mv67m4jad0d5c2a3d1e04dc9ac4c18cff616eca7",
  "owner": "tnt_3a9759864ccb4e00",
  "kind": "workflow",
  "namespace": "docs-samples",
  "name": "sample-workflows-1791867412840-b05e8a",
  "description": "Sample definition",
  "labels": {},
  "latest_version": {
    "version": "1.0.0",
    "published_at": "2026-10-13T04:57:32.297Z"
  },
  "dist_tags": {
    "latest": "1.0.0"
  },
  "draft_changed": false,
  "latest_run": null,
  "stats_7d": {
    "runs": 0,
    "failures": 0
  },
  "archived_at": null,
  "created_at": "2026-10-13T04:57:29.206Z",
  "updated_at": "2026-10-13T04:57:38.354Z"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

发布工作流版本

从草稿或临时运行源码发布版本，校验定义并锁定依赖。草稿须匹配 expected_draft_revision；临时运行由 from_run 与 expected_source_sha256 指定。版本相同且内容相同返回已有版本，内容不同返回 VERSION_EXISTS；预发布版本必须显式带 tag（不能是 latest，tag 只能含 URL 安全字符且不能是版本号或范围，违规返回 TAG_REQUIRED 或 TAG_INVALID，hint 给出完整规则），校验不通过返回 DEFINITION_INVALID。稳定版本仅高于已有最高稳定版本时自动移动 latest；工作流成为 latest 时同步定义中的定时触发器。run.workflow/run.script 的字符串与对象引用使用相同版本解析和依赖锁定规则。 发布会去掉版本号的 +build 元数据。

POST /automation/v1/workflows/{ns}/{name}/versions

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

字段类型说明
（分支1).versionstring必填 / 必有；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。
（分支1).expected_draft_revisionstring必填 / 必有；发布的草稿修订，必须匹配当前草稿；与 from_run 发布方式二选一。
（分支1).tagstring可选；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。
（分支2).versionstring必填 / 必有；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。
（分支2).from_runstring必填 / 必有；提供源码快照的临时运行 ID；已发布目标的运行当前没有可用于此入口的快照。须同时给出 expected_source_sha256，不能同时给 expected_draft_revision。
（分支2).expected_source_sha256string必填 / 必有；运行源码的 SHA-256 摘要，必须与快照匹配。
（分支2).tagstring可选；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
DRAFT_REVISION当前 draft.revision
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
: "${DRAFT_REVISION:?Set DRAFT_REVISION}"
BODY=$(jq -n --arg DRAFT_REVISION "$DRAFT_REVISION" '{
  "version": "1.0.0",
  "expected_draft_revision": $DRAFT_REVISION
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$BODY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.versions.publish({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME")
  },
  "body": {
    "version": "1.0.0",
    "expected_draft_revision": env("DRAFT_REVISION")
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
digeststring必填 / 必有；源码与契约的内容摘要。
sourcestring必填 / 必有；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
input_schema.*（分支5)object递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
output_schema.*（分支5)object递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
outline（分支2)[].children[]object递归 JSON 值。
sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
  "kind": "workflow",
  "version": "1.0.0",
  "digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
  "input_schema": {},
  "output_schema": {},
  "references": [],
  "outline": [
    {
      "name": "answer",
      "reference": "/do/0/answer",
      "kind": "set"
    }
  ],
  "sdk_version": null,
  "published_at": "2026-10-13T04:57:32.297Z",
  "published_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "deprecated": null,
  "deprecated_at": null,
  "deprecated_by": null,
  "source": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 TAG_REQUIRED：预发布版本必须显式指定发布标签（例如 beta，不能是 latest）；响应 hint 列出完整规则。 TAG_INVALID：标签无效：预发布版本不能打 latest；tag 只能含 URL 安全字符（不含空格和 / ? #）；不能是版本号或范围；latest 不能删除。响应 hint 列出完整规则。 DEFINITION_INVALID：源码未通过定义校验。 INPUT_INVALID：输入不满足目标契约或业务校验。 SCHEDULE_INVALID：定时规则或时间边界无效。 TIMEZONE_INVALID：时区不是有效的 IANA 时区。 INTERVAL_TOO_SHORT：定时间隔短于一分钟。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 RUN_NOT_FOUND：运行不存在或当前租户不可见。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。 VERSION_EXISTS：版本号已存在且源码内容不同。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。 DEFINITION_IDENTITY_MISMATCH：源码声明或运行语言与发布目标不一致。 NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。 CYCLE_DETECTED：发布后依赖会形成环（A 依赖 B、B 又依赖 A）；detail 给出环路径。
429TRIGGER_LIMIT：租户已达到 100 个启用触发器的上限。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出工作流版本

按语义版本倒序分页列出不可变的 schema 和锁定依赖。默认不带源码；仅 expand=source 带完整源码，其它值返回 400。详情接口保持全文。

GET /automation/v1/workflows/{ns}/{name}/versions

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
query: limitinteger可选；每页条数，整数 1–100，默认 25。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: expand"source"可选；仅接受 source；默认不带源码，其它值返回 400。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.versions.list({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的工作流版本（默认不含源码，expand=source 才带），按 semver 降序排列。
data[].idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
data[].kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[].versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
data[].digeststring必填 / 必有；源码与契约的内容摘要。
data[].sourcestring可选；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
data[].input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
data[].input_schema.*（分支5)object递归 JSON 值。
data[].input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
data[].output_schema.*（分支5)object递归 JSON 值。
data[].output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
data[].references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
data[].references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
data[].references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
data[].references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
data[].outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
data[].outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
data[].outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
data[].outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
data[].outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
data[].outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
data[].outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
data[].outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
data[].outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
data[].outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
data[].outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
data[].outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
data[].outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
data[].outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
data[].outline（分支2)[].children[]object递归 JSON 值。
data[].sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
data[].published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
data[].published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
data[].published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[].deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
data[].deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
data[].deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
data[].deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
      "kind": "workflow",
      "version": "1.0.0",
      "digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
      "input_schema": {},
      "output_schema": {},
      "references": [],
      "outline": [
        {
          "name": "answer",
          "reference": "/do/0/answer",
          "kind": "set"
        }
      ],
      "sdk_version": null,
      "published_at": "2026-10-13T04:57:32.297Z",
      "published_by": {
        "type": "api_key",
        "id": "key_3e00b8984967"
      },
      "deprecated": null,
      "deprecated_at": null,
      "deprecated_by": null
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取工作流版本

读取精确版本的源码、输入输出契约及弃用说明；版本缺失返回 VERSION_NOT_FOUND。 详情始终返回完整源码。 version 接受精确版本或 dist-tag；range 返回 400，hint 提示改用 /resolve。

GET /automation/v1/workflows/{ns}/{name}/versions/{version}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: versionstring必填；精确版本或 dist-tag；不接受 range（400，带 hint）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions/1.0.0" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.versions.retrieve({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME"),
    "version": "1.0.0"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
digeststring必填 / 必有；源码与契约的内容摘要。
sourcestring必填 / 必有；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
input_schema.*（分支5)object递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
output_schema.*（分支5)object递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
outline（分支2)[].children[]object递归 JSON 值。
sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
  "kind": "workflow",
  "version": "1.0.0",
  "digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
  "input_schema": {},
  "output_schema": {},
  "references": [],
  "outline": [
    {
      "name": "answer",
      "reference": "/do/0/answer",
      "kind": "set"
    }
  ],
  "sdk_version": null,
  "published_at": "2026-10-13T04:57:32.297Z",
  "published_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "deprecated": null,
  "deprecated_at": null,
  "deprecated_by": null,
  "source": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

弃用工作流版本

记录版本弃用说明；message 为空字符串时取消弃用，版本源码不变。

POST /automation/v1/workflows/{ns}/{name}/versions/{version}/deprecate

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: versionstring必填；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。

application/json

不接受额外字段。

字段类型说明
messagestring必填 / 必有；弃用说明；空字符串取消弃用。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/versions/1.0.0/deprecate" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "message": ""
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.versions.deprecate({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME"),
    "version": "1.0.0"
  },
  "body": {
    "message": ""
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；版本 ID，脚本前缀 scv_，工作流前缀 wfv_。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
versionstring必填 / 必有；版本号（semver，已去掉 +build 元数据）。
digeststring必填 / 必有；源码与契约的内容摘要。
sourcestring必填 / 必有；该版本的完整源码。版本列表默认不返回，需要时加 expand=source。
input_schemaobject必填 / 必有；任意 JSON 对象（键为字符串，值为任意 JSON 值）。
input_schema.*（分支5)object递归 JSON 值。
input_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemaobject必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
output_schema.*（分支5)object递归 JSON 值。
output_schema.*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
referencesobject[]必填 / 必有；该版本依赖的动作、平台 API、脚本与工作流。脚本和工作流依赖在发布时锁定到精确版本。
references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
outlinenull / object[]必填 / 必有；工作流的步骤大纲（OutlineNode 数组），由解析器静态生成；脚本为 null。
outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
outline（分支2)[].children[]object递归 JSON 值。
sdk_versionnull / string必填 / 必有；发布脚本所用的 SDK 版本；工作流为 null。
published_atstring必填 / 必有；发布时间（RFC 3339 UTC）。
published_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
published_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
published_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
deprecatednull / string必填 / 必有；弃用说明；未弃用为 null。弃用的版本仍可运行，但按范围或标签解析时优先选用未弃用的版本。
deprecated_atnull / string必填 / 必有；弃用时间（RFC 3339 UTC）；未弃用为 null。
deprecated_bynull / object必填 / 必有；执行弃用的主体；未弃用为 null。
deprecated_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
deprecated_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "id": "wfv_00mv67m6x5409408c354944fa8a960d207eb33c297",
  "kind": "workflow",
  "version": "1.0.0",
  "digest": "ea7352d51087eca0113ee82230848ce1506fd97d27aad4c7b1911e5c4ef9b5fb",
  "input_schema": {},
  "output_schema": {},
  "references": [],
  "outline": [
    {
      "name": "answer",
      "reference": "/do/0/answer",
      "kind": "set"
    }
  ],
  "sdk_version": null,
  "published_at": "2026-10-13T04:57:32.297Z",
  "published_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "deprecated": null,
  "deprecated_at": null,
  "deprecated_by": null,
  "source": "document:\n  dsl: '1.0.3'\n  namespace: docs-samples\n  name: sample-workflows-1791867412840-b05e8a\n  version: '1.0.0'\ndo:\n  - answer:\n      set:\n        answer: 42\n"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出工作流标签

读取发布标签指向的精确版本。同时返回更新时间和更新者。

GET /automation/v1/workflows/{ns}/{name}/dist-tags

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/dist-tags" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.distTags.list({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
.*.versionstring必填 / 必有；标签当前指向的精确版本号。
.*.updated_atstring必填 / 必有；标签最近一次移动的时间（RFC 3339 UTC）。
.*.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
.*.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
.*.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "latest": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:32.297Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

设置工作流标签

将发布标签指向已有精确版本，标签不能是版本号或版本范围；移动 latest 可用于回滚，工作流会同步定时触发器。

PUT /automation/v1/workflows/{ns}/{name}/dist-tags/{tag}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: tagstring必填；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。

application/json

不接受额外字段。

字段类型说明
versionstring必填 / 必有；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X PUT "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/dist-tags/sample" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "version": "1.0.0"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.distTags.set({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME"),
    "tag": "sample"
  },
  "body": {
    "version": "1.0.0"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
.*.versionstring必填 / 必有；标签当前指向的精确版本号。
.*.updated_atstring必填 / 必有；标签最近一次移动的时间（RFC 3339 UTC）。
.*.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
.*.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
.*.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "latest": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:32.297Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  },
  "sample": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:36.329Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 TAG_INVALID：标签无效：预发布版本不能打 latest；tag 只能含 URL 安全字符（不含空格和 / ? #）；不能是版本号或范围；latest 不能删除。响应 hint 列出完整规则。 INPUT_INVALID：输入不满足目标契约或业务校验。 SCHEDULE_INVALID：定时规则或时间边界无效。 TIMEZONE_INVALID：时区不是有效的 IANA 时区。 INTERVAL_TOO_SHORT：定时间隔短于一分钟。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
429TRIGGER_LIMIT：租户已达到 100 个启用触发器的上限。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

删除工作流标签

删除发布标签但保留版本；latest 不可删除，标签不能是版本号或范围，不存在的合法标签可重复删除。

DELETE /automation/v1/workflows/{ns}/{name}/dist-tags/{tag}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: nsstring必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。
path: namestring必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。
path: tagstring必填；发布标签。预发布版本（如 1.3.0-beta.1）必须带 tag 且不能是 latest；tag 只能由 URL 安全字符组成（字母、数字及 - _ . ! ~ * ' ( )），不含空格和 / ? #，首尾无空白；不能是版本号或版本范围（如 1.2.3、^1、1.x、*）；beta、next、debug 等其余名称均可。违规返回 TAG_INVALID 或 TAG_REQUIRED，hint 给出完整规则。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
WORKFLOW_NAME创建工作流返回的 name
: "${WORKFLOW_NAME:?Set WORKFLOW_NAME}"
curl --fail-with-body -X DELETE "https://api.deepraxis.ai/automation/v1/workflows/docs-samples/${WORKFLOW_NAME}/dist-tags/sample" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.workflows.distTags.delete({
  "path": {
    "ns": "docs-samples",
    "name": env("WORKFLOW_NAME"),
    "tag": "sample"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
.*.versionstring必填 / 必有；标签当前指向的精确版本号。
.*.updated_atstring必填 / 必有；标签最近一次移动的时间（RFC 3339 UTC）。
.*.updated_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
.*.updated_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
.*.updated_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。

实测响应

HTTP 200

{
  "latest": {
    "version": "1.0.0",
    "updated_at": "2026-10-13T04:57:32.297Z",
    "updated_by": {
      "type": "api_key",
      "id": "key_3e00b8984967"
    }
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 TAG_INVALID：标签无效：预发布版本不能打 latest；tag 只能含 URL 安全字符（不含空格和 / ? #）；不能是版本号或范围；latest 不能删除。响应 hint 列出完整规则。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

校验定义

校验源码并返回诊断及输入输出契约。支持动作、脚本和工作流；结果含 valid 及引用，不会保存定义，源码不合法通过 valid=false 返回。 脚本/动作输出 schema 支持返回类型推断：Promise 解包、Record、交叉类型、Date；推不出时使用空 schema 并给 warning（warnings）。源码诊断使用 /source 或 /implementation/source，line/column 从 1 起。kind=action 与创建动作使用同一套准入检查（禁止导入外部模块、平台操作必须写成 call(praxis/., 输入) 直接调用、不能调用 agent 或 automation 接口），校验通过的动作源码创建时不会再被拒绝。

POST /automation/v1/validate

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

application/json

不接受额外字段。

字段类型说明
kind"action" / "script" / "workflow"必填 / 必有；源码类型：action、script 或 workflow。
sourcestring必填 / 必有；待校验的源码；action 和 script 使用 TypeScript，workflow 使用 YAML。

示例

SDK 安装与示例环境

curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/validate" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "kind": "script",
  "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.validate.create({
  "body": {
    "kind": "script",
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
validboolean必填 / 必有；源码是否通过校验：true 可发布或运行，false 见 errors。
errorsobject[]必填 / 必有；校验错误列表，每项含 pointer 与中文 detail；为空数组时 valid 为 true。
errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
input_schemanull / object必填 / 必有；从源码推导出的输入 JSON Schema；无法解析源码时为 null。
input_schema（分支2).*（分支5)object递归 JSON 值。
input_schema（分支2).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
output_schemanull / object必填 / 必有；脚本从返回类型推导，支持 Promise 解包、Record、交叉类型和 Date（date-time）；推不出时为空 schema，并在 /validate 的 warnings 给出 warning。
output_schema（分支2).*（分支5)object递归 JSON 值。
output_schema（分支2).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
referencesobject[]必填 / 必有；源码依赖的动作、平台 API、脚本与工作流。
references[].kind"action" / "script" / "workflow" / "platform_api" / "run"必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。
references[].namestring必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
references[].rangestring可选；引用时写的版本范围或标签（npm 规则）；未写时为空。
references[].locked_versionstring可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。
outlinenull / object[]必填 / 必有；工作流步骤大纲；脚本和动作为 null。
outline（分支2)[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
outline（分支2)[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start；与运行时 Task.reference 一致。
outline（分支2)[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
outline（分支2)[].targetstring可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。
outline（分支2)[].waitobject可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。
outline（分支2)[].wait.untilstring可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。
outline（分支2)[].wait.secondsnumber可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。
outline（分支2)[].wait.eventstring可选；listen 步骤等待的事件类型。
outline（分支2)[].wait.durationstring可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。
outline（分支2)[].loopobject可选；for 步骤的循环信息 {each, in}。 不接受额外字段。
outline（分支2)[].loop.eachstring必填 / 必有；循环变量名；未指定时为 item。
outline（分支2)[].loop.instring必填 / 必有；被遍历的集合表达式原文。
outline（分支2)[].childrenobject[]可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。
outline（分支2)[].children[]object递归 JSON 值。
warningsobject[]可选；脚本/动作静态分析的非阻断诊断；无法推导类型时使用空 schema 并给 warning。工作流分析可省略。
warnings[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
warnings[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
warnings[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
warnings[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
warnings[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
platform_apisstring[]可选；脚本/动作引用的平台 API 集合（字符串数组）；工作流分析可省略。

实测响应

HTTP 200

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "input_schema": {
    "type": "object",
    "properties": {
      "n": {
        "type": "number"
      }
    },
    "required": [
      "n"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "answer": {
        "type": "number"
      }
    },
    "required": [
      "answer"
    ]
  },
  "references": [],
  "outline": null,
  "platform_apis": []
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

解析运行目标

将 ns/name@tag、精确版本或版本范围解析为可运行的精确版本；省略 @ 时使用 latest，归档目标拒绝解析，无匹配返回 NO_MATCHING_VERSION。

GET /automation/v1/resolve

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
query: targetstring必填；ns/name@tag、ns/name@version 或 ns/name@range；省略 @ 时使用 latest。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TARGET已发布的 docs-samples/name@1.0.0
: "${TARGET:?Set TARGET}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/resolve" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "target=${TARGET}"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.resolve.retrieve({
  "query": {
    "target": env("TARGET")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
namespacestring必填 / 必有；编排命名空间。
namestring必填 / 必有；编排名字。
versionstring必填 / 必有；target 解析到的精确版本号。
version_idstring必填 / 必有；该版本的 ID（scv_ 或 wfv_ 前缀）。
deprecatednull / string必填 / 必有；解析到的版本被弃用时的弃用说明；未弃用为 null。

实测响应

HTTP 200

{
  "kind": "script",
  "namespace": "docs-samples",
  "name": "sample-scripts-1791867412840-b05e8a",
  "version": "1.0.0",
  "version_id": "scv_00mv67lza679fc5498438040079f0c5684208c4915",
  "deprecated": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
422NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

搜索自动化定义

按名称搜索可见目标，按名称升序分页；默认排除归档目标，可筛选已发布的脚本和工作流。

GET /automation/v1/targets

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
query: qstring可选；不区分大小写，按 ns/name 或说明的字面子串匹配。
query: kind"action" / "script" / "workflow"[]可选；action、script 或 workflow；省略返回全部。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: limitinteger可选；每页条数，整数 1–100，默认 25。 minimum: 1；maximum: 100
query: labelsobject可选；按标签过滤，使用 labels[k]=v；同键逗号多值取任一，不同键同时满足。
query: created_at[gte]string可选；创建时间下界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"
query: created_at[lte]string可选；创建时间上界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"
query: cursorstring可选；上一页的 next_cursor；翻页时保留原筛选条件。
query: archivedboolean可选；默认 false，仅返回未归档目标；true 仅返回已归档目标。 default: false
query: publishedboolean可选；true 仅返回有已发布版本的编排；动作始终可用。

示例

SDK 安装与示例环境

curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/targets" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "q=sample-" \
  --data-urlencode "limit=1"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.targets.list({
  "query": {
    "q": "sample-",
    "limit": 1
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的目标搜索结果（动作、脚本、工作流），按相关度和创建时间排列。
data[].kind"action" / "script" / "workflow"必填 / 必有；目标类型。action 为动作；script 为脚本；workflow 为工作流。
data[].namespacestring必填 / 必有；目标命名空间。
data[].namestring必填 / 必有；目标名字。
data[].descriptionstring必填 / 必有；目标的说明文字。
data[].latest_versionnull / string必填 / 必有；latest 标签指向的版本号；动作或尚未发布时为 null。
data[].archivedboolean必填 / 必有；true 表示目标已归档，不能再被运行。
next_cursorstring / null必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "kind": "action",
      "namespace": "docs-samples",
      "name": "sample-action-1791867412840-b05e8a",
      "description": "",
      "latest_version": null,
      "archived": false
    }
  ],
  "next_cursor": "WyJbXCJ0YXJnZXRzXCIsXCJ0bnRfM2E5NzU5ODY0Y2NiNGUwMFwiLHtcInFcIjpcInNhbXBsZS1cIn1dIiwiZG9jcy1zYW1wbGVzL3NhbXBsZS1hY3Rpb24tMTc5MTg2NzQxMjg0MC1iMDVlOGEiLCJmdW5jdGlvbjphY3RfMDBtdjY3bG96NGZlNGYyN2JkZjg5MzQ2Yzg4NWIzYTI4YjIwMzhjMDkxIl0="
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

创建运行

target 与 source 二选一；source 还须提供 language，输入与源码先校验再创建运行。wait 为 0–60 秒（默认 0），返回时已到终态为 200，否则 202；Idempotency-Key 在租户、方法、路径内保留 24 小时，请求指纹不含 wait。重放返回当前运行并带 Idempotent-Replayed: true，同键不同内容返回 422，处理中返回 409。新建非确定性运行 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位十六进制 DO ID，共 78 字符；旧随机 ID 为 46 字符，历史与确定性 ID 仍有效。同毫秒内不保证顺序。

POST /automation/v1/runs

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
header: Idempotency-Keystring可选；1–256 字符；租户、方法、路径内去重 24 小时，请求指纹不含 wait。

application/json

字段类型说明
（分支1).targetstring必填 / 必有；脚本或工作流引用 ns/name@tag、ns/name@version 或 ns/name@range，省略 @ 时使用 latest；与 source 互斥。
（分支1).inputnull / string / number / boolean / object / null / string / number / boolean / object / JSON[][]可选；传给运行的 JSON 输入，缺省为 {}；必须符合目标输入契约，最多 1 MiB。
（分支1).input（分支5).*（分支5)object递归 JSON 值。
（分支1).input（分支5).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).input（分支6)[]（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).input（分支6)[]（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).waitnumber可选；等待终态的秒数，0–60，默认 0；不计入幂等请求指纹。 minimum: 0；maximum: 60
（分支1).labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。
（分支1).deadline_secondsinteger可选；正整数秒，最多 604800；脚本默认且最多 300 秒，工作流默认 86400 秒、最多 7 天。 minimum: 1
（分支2).sourcestring必填 / 必有；源码；创建临时运行时与 target 互斥，且必须同时提供 language，最多 1 MiB。
（分支2).language"ts" / "yaml"必填 / 必有；源码语言：ts 表示脚本，yaml 表示工作流。
（分支2).inputnull / string / number / boolean / object / null / string / number / boolean / object / JSON[][]可选；传给运行的 JSON 输入，缺省为 {}；必须符合目标输入契约，最多 1 MiB。
（分支2).input（分支5).*（分支5)object递归 JSON 值。
（分支2).input（分支5).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支2).input（分支6)[]（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支2).input（分支6)[]（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支2).waitnumber可选；等待终态的秒数，0–60，默认 0；不计入幂等请求指纹。 minimum: 0；maximum: 60
（分支2).labelsobject可选；最多 50 个标签；键为 1–40 个字符，值最多 500 个字符。
（分支2).deadline_secondsinteger可选；正整数秒，最多 604800；脚本默认且最多 300 秒，工作流默认 86400 秒、最多 7 天。 minimum: 1

示例

SDK 安装与示例环境

curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
  "language": "ts",
  "input": {
    "n": 41
  },
  "wait": 60,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run"
  }
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.create({
  "body": {
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
    "language": "ts",
    "input": {
      "n": 41
    },
    "wait": 60,
    "labels": {
      "namespace": "docs-samples",
      "name": "sample-run"
    }
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-Replayedbooleantrue when returning a replayed run.

application/json

字段类型说明
idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有；脚本发出的调用总数。
counters.action_callsnumber必填 / 必有；其中调用动作的次数。
counters.child_runsnumber必填 / 必有；启动的子运行数。
counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
error（分支2).titlestring必填 / 必有；错误的简短标题。
error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。

HTTP 202

Run accepted; still pending or executing when wait expires.

响应头类型说明
Idempotent-Replayedbooleantrue when returning a replayed run.

application/json

字段类型说明
idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有；脚本发出的调用总数。
counters.action_callsnumber必填 / 必有；其中调用动作的次数。
counters.child_runsnumber必填 / 必有；启动的子运行数。
counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
error（分支2).titlestring必填 / 必有；错误的简短标题。
error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。

实测响应

HTTP 200

{
  "id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
  "kind": "script",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
  "language": "ts",
  "status": "completed",
  "progress": null,
  "current_wait": null,
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": null
  },
  "input": {
    "n": 41
  },
  "output": {
    "answer": 42
  },
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-13T05:02:40.954Z",
  "created_at": "2026-10-13T04:57:40.954Z",
  "started_at": "2026-10-13T04:57:42.283Z",
  "ended_at": "2026-10-13T04:57:42.367Z",
  "updated_at": "2026-10-13T04:57:42.367Z",
  "heartbeat_at": "2026-10-13T04:57:42.283Z",
  "cancel_requested_at": null,
  "cancelled_by": null,
  "cancel_reason": null,
  "cancel_message": null,
  "suspend_requested_at": null,
  "suspended_by": null,
  "queued_ms": 1329,
  "run_ms": 84,
  "wait_ms": null,
  "usage": null,
  "rerun_of": null,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 DEFINITION_INVALID：源码未通过定义校验。 INPUT_INVALID：输入不满足目标契约或业务校验。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。 RUN_NOT_FOUND：运行不存在或当前租户不可见。
409TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。 IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。
413PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。
422NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。 IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出运行

按创建时间倒序筛选租户内运行。支持状态多选、目标、来源、labels[k] 和创建时间下界筛选。q 以 run_ 开头时精确匹配运行 ID，否则按编排名称前缀匹配。大 input/output 在列表中为 null，对应 input_truncated/output_truncated 为 true；详情返回全文。

GET /automation/v1/runs

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
query: limitinteger可选；每页条数，整数 1–100，默认 50。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: kind"script" / "workflow"[]可选；script 或 workflow；省略返回两者。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: definitionstring[]可选；精确编排名，格式 ns/name。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: versionstring[]可选；规范的精确语义版本，例如 1.2.0 或 1.3.0-beta.1；不能是范围。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: status"pending" / "running" / "waiting" / "suspended" / "cancelled" / "faulted" / "completed"[]可选；逗号分隔的状态，可选 pending、running、waiting、suspended、cancelled、faulted、completed；省略不过滤。 多个值以逗号分隔，匹配任一值。
query: channel"console" / "api" / "internal" / "run" / "trigger"[]可选；来源渠道：run 仅子运行；console、api、internal、trigger 为根运行。多个值以逗号分隔，匹配任一值。 minItems: 1
query: initiator_type"user" / "api_key" / "agent" / "trigger"[]可选；根发起方类型：user、api_key、agent 或 trigger，子运行继承根发起方。run 返回 INPUT_INVALID；按来源筛选用 channel=run 或 parent_run_id。多个值以逗号分隔，匹配任一值。 minItems: 1
query: initiator"me"可选；仅支持 me，匹配当前凭证的主体类型和 ID，包含由我的运行派生出的子运行；省略不限制。
query: adhocboolean可选；true 仅临时运行，false 仅已发布定义的运行；省略返回两者。
query: language"ts" / "yaml"[]可选；源码语言：ts 或 yaml。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: parent_run_idstring[]可选；按直接父运行 ID 精确匹配；用它列出某个运行的子运行（由工作流 run 步骤或脚本 invoke() 启动），每项含 ID、目标、状态与耗时。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: root_run_idstring[]可选；按根运行 ID 精确匹配，读取同一运行树。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: qstring可选；run_ 开头时精确匹配运行 ID，否则按编排名称前缀匹配；% 与 _ 作为普通字符。
query: labelsobject可选；按标签过滤，使用 labels[k]=v；同键逗号多值取任一，不同键同时满足。
query: created_at[gte]string可选；创建时间下界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"
query: created_at[lte]string可选；创建时间上界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"

示例

SDK 安装与示例环境

curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "labels[name]=sample-run-1791867412840-b05e8a" \
  --data-urlencode "limit=1"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.list({
  "query": {
    "labels": {
      "name": "sample-run-1791867412840-b05e8a"
    },
    "limit": 1
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的运行摘要，按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
data[].kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[].numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
data[].definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
data[].definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
data[].definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
data[].targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
data[].resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
data[].source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
data[].language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
data[].status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
data[].progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
data[].progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
data[].progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
data[].progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
data[].progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
data[].current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
data[].current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data[].current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data[].current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data[].current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data[].current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data[].current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data[].current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data[].current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data[].current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data[].current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data[].current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data[].current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data[].current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
data[].countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
data[].counters.callsnumber必填 / 必有；脚本发出的调用总数。
data[].counters.action_callsnumber必填 / 必有；其中调用动作的次数。
data[].counters.child_runsnumber必填 / 必有；启动的子运行数。
data[].counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
data[].counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
data[].inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[].input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[].output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
data[].error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data[].error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data[].error（分支2).titlestring必填 / 必有；错误的简短标题。
data[].error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data[].error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data[].error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data[].error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data[].error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data[].error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data[].error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data[].error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[].error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data[].error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data[].error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data[].error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data[].error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data[].error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data[].error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data[].error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data[].initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
data[].initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[].channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
data[].ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
data[].parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
data[].parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
data[].parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
data[].parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
data[].parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
data[].parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
data[].parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
data[].root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
data[].depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
data[].attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
data[].deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
data[].created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
data[].started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
data[].ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
data[].updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
data[].heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
data[].cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
data[].cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
data[].cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[].cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
data[].suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
data[].suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
data[].suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[].queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
data[].run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
data[].wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
data[].usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
data[].usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
data[].usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
data[].usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
data[].usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
data[].usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
data[].usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
data[].usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
data[].rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
data[].labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
data[].triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
data[].trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
data[].trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
data[].cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
data[].input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
data[].output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
      "kind": "script",
      "number": null,
      "definition": null,
      "target": null,
      "resolved_version": null,
      "source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
      "language": "ts",
      "status": "completed",
      "progress": null,
      "current_wait": null,
      "counters": {
        "calls": 0,
        "action_calls": 0,
        "child_runs": 0,
        "tasks_completed": 0,
        "tasks_total": null
      },
      "input": {
        "n": 41
      },
      "output": {
        "answer": 42
      },
      "error": null,
      "initiator": {
        "type": "api_key",
        "id": "key_3e00b8984967"
      },
      "channel": "api",
      "owner": "tnt_3a9759864ccb4e00",
      "trigger": null,
      "parent": null,
      "parent_run_id": null,
      "root_run_id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
      "depth": 0,
      "attach": null,
      "deadline_at": "2026-10-13T05:02:40.954Z",
      "created_at": "2026-10-13T04:57:40.954Z",
      "started_at": "2026-10-13T04:57:42.283Z",
      "ended_at": "2026-10-13T04:57:42.367Z",
      "updated_at": "2026-10-13T04:57:42.367Z",
      "heartbeat_at": "2026-10-13T04:57:42.283Z",
      "cancel_requested_at": null,
      "cancelled_by": null,
      "cancel_reason": null,
      "cancel_message": null,
      "suspend_requested_at": null,
      "suspended_by": null,
      "queued_ms": 1329,
      "run_ms": 84,
      "wait_ms": null,
      "usage": null,
      "rerun_of": null,
      "labels": {
        "namespace": "docs-samples",
        "name": "sample-run-1791867412840-b05e8a"
      }
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 INPUT_INVALID：输入不满足目标契约或业务校验。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取运行

读取运行详情，可用 expand 一次带回调用、步骤、步骤聚合、日志或源码；传 wait（秒，0–60）可挂起请求直到运行到达终态或超时，不必轮询；展开页最多 200 条，后续通过各账本端点的游标读取。 工作流 raise 错误保留完整 type URI、status、title、detail；只有平台内部异常归为 runtime。

GET /automation/v1/runs/{id}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
query: expand"calls" / "tasks" / "task_groups" / "logs" / "source"[]可选；逗号分隔且不能重复：calls、tasks、task_groups、logs、source，这是全部合法取值（output 不是展开项，运行输出在 output 字段里）；省略不展开，展开页最多 200 条。无效取值返回 INVALID_PARAMS 并列出合法取值。 minItems: 1
query: waitinteger可选；等待运行到达终态的秒数，0–60 的整数，默认 0（立即返回）。超时后运行仍未结束则返回当前运行（状态码仍为 200），请检查 status；超过 60 或不是整数返回 INVALID_PARAMS。含义与 runs.create 的 wait 相同。 minimum: 0；maximum: 60

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.retrieve({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有；脚本发出的调用总数。
counters.action_callsnumber必填 / 必有；其中调用动作的次数。
counters.child_runsnumber必填 / 必有；启动的子运行数。
counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
error（分支2).titlestring必填 / 必有；错误的简短标题。
error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
callsobject可选；expand=calls 时返回的调用记录分页：{data, next_cursor}。 不接受额外字段。
calls.dataobject[]必填 / 必有；本页的调用记录（Call）。 maxItems: 200
calls.data[].idstring必填 / 必有；调用 ID，前缀 call_。
calls.data[].run_idstring必填 / 必有；发出该调用的脚本运行 ID（run_ 前缀）。
calls.data[].seqnumber必填 / 必有；调用在该运行中的序号，随调用顺序递增；与 run_id 一起定位这次调用。
calls.data[].targetobject必填 / 必有；被调用的目标 {kind, name, revision?, version?}。 不接受额外字段。
calls.data[].target.kind"action" / "script" / "workflow" / "platform_api"必填 / 必有；目标类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流。
calls.data[].target.namestring必填 / 必有；目标名称：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
calls.data[].target.revisionstring可选；实际执行的动作修订 ID（actr_ 前缀）；仅动作调用有。
calls.data[].target.versionstring可选；实际运行的精确版本号；仅脚本与工作流调用有。
calls.data[].args_previewstring必填 / 必有；调用参数的单行预览，由服务端截断；超过 32 KB 的原文存放在对象存储而不内联。
calls.data[].result_previewnull / string必填 / 必有；返回值的单行预览，由服务端截断；调用结束前为 null。
calls.data[].status"running" / "completed" / "faulted" / "cancelled"必填 / 必有；调用状态。running 执行中；completed 已正常返回；faulted 失败，error 给出原因；cancelled 因运行被取消而中止。
calls.data[].started_atstring必填 / 必有；调用开始的时间（RFC 3339 UTC）。
calls.data[].ended_atnull / string必填 / 必有；调用结束的时间（RFC 3339 UTC）；仍在执行为 null。
calls.data[].duration_msnull / number必填 / 必有；从开始到结束的毫秒数；未结束为 null。
calls.data[].errornull / object必填 / 必有；调用失败时的错误详情；成功或仍在执行为 null。
calls.data[].error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
calls.data[].error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
calls.data[].error（分支2).titlestring必填 / 必有；错误的简短标题。
calls.data[].error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
calls.data[].error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
calls.data[].error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
calls.data[].error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
calls.data[].error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
calls.data[].error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
calls.data[].error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
calls.data[].error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
calls.data[].error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
calls.data[].error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
calls.data[].error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
calls.data[].error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
calls.data[].error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
calls.data[].error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
calls.data[].error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
calls.data[].error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
calls.data[].child_run_idnull / string必填 / 必有；目标是脚本或工作流时，由本次调用启动的子运行 ID；动作与平台 API 调用为 null。
calls.data[].invocation_keystring必填 / 必有；标识这一次逻辑调用的键，随调用发往下游，使至少一次语义下的重试可被去重。
calls.data[].request_idstring / null必填 / 必有；下游响应的 X-Request-Id；尚未收到响应或响应未提供该头时为 null。
calls.next_cursornull / string必填 / 必有；下一页游标；没有更多为 null。
tasksobject可选；expand=tasks 时返回的工作流步骤分页：{data, next_cursor}。 不接受额外字段。
tasks.dataobject[]必填 / 必有；本页的步骤（Task）。 maxItems: 200
tasks.data[].idstring必填 / 必有；步骤执行记录的标识，按不透明字符串处理。
tasks.data[].run_idstring必填 / 必有；所属运行 ID。
tasks.data[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。
tasks.data[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
tasks.data[].kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
tasks.data[].iterationnumber[]必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。
tasks.data[].attemptnumber必填 / 必有；第几次尝试；步骤因重试而重新执行时递增。
tasks.data[].status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
tasks.data[].skippedboolean必填 / 必有；true 表示该步骤被跳过而没有实际执行。
tasks.data[].started_atnull / string必填 / 必有；步骤开始的时间（RFC 3339 UTC）；未开始为 null。
tasks.data[].ended_atnull / string必填 / 必有；步骤结束的时间（RFC 3339 UTC）；未结束为 null。
tasks.data[].duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
tasks.data[].inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
tasks.data[].input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
tasks.data[].input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
tasks.data[].input_truncatedboolean必填 / 必有；true 表示 input 超过 32 KB 已被截断。
tasks.data[].outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
tasks.data[].output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
tasks.data[].output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
tasks.data[].output_truncatedboolean必填 / 必有；输出超过内联限制而被省略时为 true。
tasks.data[].errornull / object必填 / 必有；步骤失败时的错误详情；未失败为 null。
tasks.data[].error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
tasks.data[].error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
tasks.data[].error（分支2).titlestring必填 / 必有；错误的简短标题。
tasks.data[].error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
tasks.data[].error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
tasks.data[].error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
tasks.data[].error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
tasks.data[].error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
tasks.data[].error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
tasks.data[].error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
tasks.data[].error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
tasks.data[].error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
tasks.data[].error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
tasks.data[].error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
tasks.data[].error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
tasks.data[].error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
tasks.data[].error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
tasks.data[].error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
tasks.data[].error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
tasks.data[].actionnull / object必填 / 必有；call 步骤执行的动作 {name, revision}；其它步骤为 null。
tasks.data[].action（分支2).namestring必填 / 必有；动作全名 ns/name。
tasks.data[].action（分支2).revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
tasks.data[].child_runnull / object必填 / 必有；run 步骤启动的子运行摘要 {id, number, status, resolved_version}；其它步骤为 null。
tasks.data[].child_run（分支2).idstring必填 / 必有；子运行 ID（run_ 前缀），创建后即可读取。
tasks.data[].child_run（分支2).numbernull / number必填 / 必有；子运行在其定义内的序号；临时运行为 null。
tasks.data[].child_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；子运行的状态。pending 尚未开始；running 执行中；waiting 在等待；suspended 已暂停；cancelled 已取消；faulted 失败；completed 成功完成。等待型子运行在结束时补全终态，detach 的子运行只记录启动时的状态。
tasks.data[].child_run（分支2).resolved_versionnull / string必填 / 必有；子运行解析到的精确版本号；临时运行为 null。
tasks.next_cursornull / string必填 / 必有；下一页游标；没有更多为 null。
task_groupsobject可选；expand=task_groups 时返回、按 reference 聚合的步骤分页 {data, next_cursor}（循环的多次迭代合并为一行）；脚本运行为空页。 不接受额外字段。
task_groups.dataobject[]必填 / 必有；本页的聚合行（TaskGroup）。 maxItems: 200
task_groups.data[].referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。
task_groups.data[].namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
task_groups.data[].countnumber必填 / 必有；该 reference 下合并的执行记录条数（循环的迭代数）。
task_groups.data[].status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
task_groups.data[].duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
task_groups.next_cursornull / string必填 / 必有；下一页游标；没有更多为 null。
logsobject可选；expand=logs 时返回的日志分页：{data, next_cursor}。 不接受额外字段。
logs.dataobject[]必填 / 必有；本页的日志行（LogLine）。 maxItems: 200
logs.data[].cursorstring必填 / 必有；该行的游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
logs.data[].tsstring必填 / 必有；日志产生的时间（RFC 3339 UTC）。
logs.data[].level"debug" / "info" / "warn" / "error"必填 / 必有；日志级别。debug 调试信息；info 一般信息；warn 警告；error 错误。
logs.data[].messagestring必填 / 必有；日志文本。
logs.next_cursornull / string必填 / 必有；下一页游标；没有更多为 null。
sourceobject可选；临时运行的源码快照 {language, source, sha256}。 不接受额外字段。
source.language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
source.sourcestring必填 / 必有；运行时使用的完整源码（ts 或 yaml）。
source.sha256string必填 / 必有；源码的 SHA-256 摘要，可作为发布时的 expected_source_sha256。
cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。

实测响应

HTTP 200

{
  "id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
  "kind": "script",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
  "language": "ts",
  "status": "completed",
  "progress": null,
  "current_wait": null,
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": null
  },
  "input": {
    "n": 41
  },
  "output": {
    "answer": 42
  },
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-13T05:02:40.954Z",
  "created_at": "2026-10-13T04:57:40.954Z",
  "started_at": "2026-10-13T04:57:42.283Z",
  "ended_at": "2026-10-13T04:57:42.367Z",
  "updated_at": "2026-10-13T04:57:42.367Z",
  "heartbeat_at": "2026-10-13T04:57:42.283Z",
  "cancel_requested_at": null,
  "cancelled_by": null,
  "cancel_reason": null,
  "cancel_message": null,
  "suspend_requested_at": null,
  "suspended_by": null,
  "queued_ms": 1329,
  "run_ms": 84,
  "wait_ms": null,
  "usage": {
    "currency": "USD",
    "cost": "0.000000",
    "pending_events": 0,
    "by_service": [],
    "tree_cost": "0.000000"
  },
  "rerun_of": null,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

取消运行

请求取消运行。返回 202：工作流直接终止，脚本先请求中止并在宽限期后强制结束；已终态运行返回 409 RUN_INVALID_STATE。取消传播到附着子运行，不影响 detach 子运行；可选 reason 为 1–500 字符，保存为 Run.cancel_message；用户取消的 cancel_reason 仍为 user。

POST /automation/v1/runs/{id}/cancel

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。

application/json

不接受额外字段。

字段类型说明
reasonstring可选；可选取消备注，1–500 字符；保存为 Run.cancel_message，cancel_reason 仍为 user。 minLength: 1；maxLength: 500

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/cancel" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "reason": "Sample completed"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.cancel({
  "path": {
    "id": env("RUN_ID")
  },
  "body": {
    "reason": "Sample completed"
  }
});
console.log(result);

响应

HTTP 202

Cancellation accepted; updated Run.

application/json

字段类型说明
idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有；脚本发出的调用总数。
counters.action_callsnumber必填 / 必有；其中调用动作的次数。
counters.child_runsnumber必填 / 必有；启动的子运行数。
counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
error（分支2).titlestring必填 / 必有；错误的简短标题。
error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。

实测响应

HTTP 202

{
  "id": "run_00mv67mwcj0f099fa839644b384742cdfbbbff67226e46f1eed8a36c5226f15a3cf730a221",
  "kind": "workflow",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "fa40016c6458f18ae4e5b418247cdccccfc4d5dfabe2bdec76f3103842ea15ad",
  "language": "yaml",
  "status": "cancelled",
  "progress": null,
  "current_wait": null,
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": 1
  },
  "input": {},
  "output": null,
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mwcj0f099fa839644b384742cdfbbbff67226e46f1eed8a36c5226f15a3cf730a221",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-14T04:58:05.251Z",
  "created_at": "2026-10-13T04:58:05.251Z",
  "started_at": null,
  "ended_at": "2026-10-13T04:58:07.803Z",
  "updated_at": "2026-10-13T04:58:07.803Z",
  "heartbeat_at": null,
  "cancel_requested_at": "2026-10-13T04:58:07.754Z",
  "cancelled_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "cancel_reason": "user",
  "cancel_message": "Sample completed",
  "suspend_requested_at": null,
  "suspended_by": null,
  "queued_ms": 2552,
  "run_ms": 0,
  "wait_ms": null,
  "usage": null,
  "rerun_of": null,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
409RUN_INVALID_STATE：当前状态不允许执行该动作。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

重新运行

用原精确版本或原临时源码创建新的根运行，保留标签并记录 rerun_of；可覆盖 input，未提供则沿用原输入。原目标已归档会拒绝重新运行，运行令牌不能使用此入口。

POST /automation/v1/runs/{id}/rerun

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

不接受额外字段。

字段类型说明
inputnull / string / number / boolean / object / null / string / number / boolean / object / JSON[][]可选；可选的新输入；省略沿用原运行输入，必须符合目标契约。
input（分支5).*（分支5)object递归 JSON 值。
input（分支5).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/rerun" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "input": {
    "n": 42
  }
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.rerun({
  "path": {
    "id": env("RUN_ID")
  },
  "body": {
    "input": {
      "n": 42
    }
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有；脚本发出的调用总数。
counters.action_callsnumber必填 / 必有；其中调用动作的次数。
counters.child_runsnumber必填 / 必有；启动的子运行数。
counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
error（分支2).titlestring必填 / 必有；错误的简短标题。
error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。

实测响应

HTTP 200

{
  "id": "run_00mv67mj3s5141d7514d6e0c18cd71ba7e821b89faadad8897cc6bedb103209efe6de40b4d",
  "kind": "script",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d",
  "language": "ts",
  "status": "running",
  "progress": null,
  "current_wait": null,
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": null
  },
  "input": {
    "n": 42
  },
  "output": null,
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mj3s5141d7514d6e0c18cd71ba7e821b89faadad8897cc6bedb103209efe6de40b4d",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-13T05:02:48.088Z",
  "created_at": "2026-10-13T04:57:48.088Z",
  "started_at": "2026-10-13T04:57:49.075Z",
  "ended_at": null,
  "updated_at": "2026-10-13T04:57:49.075Z",
  "heartbeat_at": "2026-10-13T04:57:49.075Z",
  "cancel_requested_at": null,
  "cancelled_by": null,
  "cancel_reason": null,
  "cancel_message": null,
  "suspend_requested_at": null,
  "suspended_by": null,
  "queued_ms": 987,
  "run_ms": null,
  "wait_ms": null,
  "usage": null,
  "rerun_of": "run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1",
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 DEFINITION_INVALID：源码未通过定义校验。 INPUT_INVALID：输入不满足目标契约或业务校验。
403NAMESPACE_FORBIDDEN：命名空间只读或运行令牌不允许此调用。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。 RUN_NOT_FOUND：运行不存在或当前租户不可见。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
413PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。 NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

暂停运行

仅可暂停正在运行或等待中的工作流；脚本返回 OPERATION_NOT_SUPPORTED，其他状态返回 RUN_INVALID_STATE。

POST /automation/v1/runs/{id}/suspend

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/suspend" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.suspend({
  "path": {
    "id": env("RUN_ID")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有；脚本发出的调用总数。
counters.action_callsnumber必填 / 必有；其中调用动作的次数。
counters.child_runsnumber必填 / 必有；启动的子运行数。
counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
error（分支2).titlestring必填 / 必有；错误的简短标题。
error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。

实测响应

HTTP 200

{
  "id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
  "kind": "workflow",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "1f559f7323adda4865d889639a4d878eab97e1ce3e542c68ea4022af4cd0f7fa",
  "language": "yaml",
  "status": "suspended",
  "progress": null,
  "current_wait": {
    "id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
    "run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
    "kind": "event",
    "state": "open",
    "task": {
      "reference": "/do/0/ready",
      "name": "ready"
    },
    "resume_at": null,
    "event_type": "ready",
    "child_run_id": null,
    "created_at": "2026-10-13T04:57:56.982Z",
    "expires_at": "2026-10-14T04:57:50.405Z",
    "resolved_at": null
  },
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": 1
  },
  "input": {},
  "output": null,
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-14T04:57:50.405Z",
  "created_at": "2026-10-13T04:57:50.405Z",
  "started_at": "2026-10-13T04:57:56.933Z",
  "ended_at": null,
  "updated_at": "2026-10-13T04:57:58.173Z",
  "heartbeat_at": null,
  "cancel_requested_at": null,
  "cancelled_by": null,
  "cancel_reason": null,
  "cancel_message": null,
  "suspend_requested_at": "2026-10-13T04:57:58.173Z",
  "suspended_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "queued_ms": 6528,
  "run_ms": null,
  "wait_ms": null,
  "usage": null,
  "rerun_of": null,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
409OPERATION_NOT_SUPPORTED：该资源类型不支持此操作。 RUN_INVALID_STATE：当前状态不允许执行该动作。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

恢复运行

仅恢复 suspended 状态的工作流，回到暂停前的运行或等待状态；并发名额不足时仍保持暂停，脚本不支持此操作。

POST /automation/v1/runs/{id}/resume

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。

application/json

不接受额外字段。 object

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/resume" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.resume({
  "path": {
    "id": env("RUN_ID")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
counters.callsnumber必填 / 必有；脚本发出的调用总数。
counters.action_callsnumber必填 / 必有；其中调用动作的次数。
counters.child_runsnumber必填 / 必有；启动的子运行数。
counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
error（分支2).titlestring必填 / 必有；错误的简短标题。
error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。

实测响应

HTTP 200

{
  "id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
  "kind": "workflow",
  "number": null,
  "definition": null,
  "target": null,
  "resolved_version": null,
  "source_digest": "1f559f7323adda4865d889639a4d878eab97e1ce3e542c68ea4022af4cd0f7fa",
  "language": "yaml",
  "status": "waiting",
  "progress": null,
  "current_wait": {
    "id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
    "run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
    "kind": "event",
    "state": "open",
    "task": {
      "reference": "/do/0/ready",
      "name": "ready"
    },
    "resume_at": null,
    "event_type": "ready",
    "child_run_id": null,
    "created_at": "2026-10-13T04:57:56.982Z",
    "expires_at": "2026-10-14T04:57:50.405Z",
    "resolved_at": null
  },
  "counters": {
    "calls": 0,
    "action_calls": 0,
    "child_runs": 0,
    "tasks_completed": 0,
    "tasks_total": 1
  },
  "input": {},
  "output": null,
  "error": null,
  "initiator": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "channel": "api",
  "owner": "tnt_3a9759864ccb4e00",
  "trigger": null,
  "parent": null,
  "parent_run_id": null,
  "root_run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
  "depth": 0,
  "attach": null,
  "deadline_at": "2026-10-14T04:57:50.405Z",
  "created_at": "2026-10-13T04:57:50.405Z",
  "started_at": "2026-10-13T04:57:56.933Z",
  "ended_at": null,
  "updated_at": "2026-10-13T04:58:02.193Z",
  "heartbeat_at": null,
  "cancel_requested_at": null,
  "cancelled_by": null,
  "cancel_reason": null,
  "cancel_message": null,
  "suspend_requested_at": null,
  "suspended_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "queued_ms": 6528,
  "run_ms": null,
  "wait_ms": null,
  "usage": null,
  "rerun_of": null,
  "labels": {
    "namespace": "docs-samples",
    "name": "sample-run-1791867412840-b05e8a"
  }
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
409OPERATION_NOT_SUPPORTED：该资源类型不支持此操作。 RUN_INVALID_STATE：当前状态不允许执行该动作。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出等待点

按账本顺序列出运行的等待点。包括当前及历史的 event、timer 与 child 等待点。

GET /automation/v1/runs/{id}/waits

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
query: limitinteger可选；每页条数，整数 1–100，默认 50。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/waits" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.waits.list({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的等待点（当前与历史），按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data[].run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data[].kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data[].state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data[].tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data[].task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data[].task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data[].resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data[].event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data[].child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data[].created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data[].expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data[].resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
      "run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
      "kind": "event",
      "state": "open",
      "task": {
        "reference": "/do/0/ready",
        "name": "ready"
      },
      "resume_at": null,
      "event_type": "ready",
      "child_run_id": null,
      "created_at": "2026-10-13T04:57:56.982Z",
      "expires_at": "2026-10-14T04:57:50.405Z",
      "resolved_at": null
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出运行调用

分页读取调用账本及执行结果。结果按账本顺序列出目标、参数与结果预览、状态和耗时。脚本运行读调用账本；工作流运行的动作调用记在步骤上，这里列出带动作的步骤（不含被跳过的），与 counters.action_calls 一致。

GET /automation/v1/runs/{id}/calls

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
query: limitinteger可选；运行台账每页条数，整数 1–200，默认 50；其它集合上限为 100。 minimum: 1；maximum: 200
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/calls" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.calls.list({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的脚本调用记录，按 seq 顺序排列。
data[].idstring必填 / 必有；调用 ID，前缀 call_。
data[].run_idstring必填 / 必有；发出该调用的脚本运行 ID（run_ 前缀）。
data[].seqnumber必填 / 必有；调用在该运行中的序号，随调用顺序递增；与 run_id 一起定位这次调用。
data[].targetobject必填 / 必有；被调用的目标 {kind, name, revision?, version?}。 不接受额外字段。
data[].target.kind"action" / "script" / "workflow" / "platform_api"必填 / 必有；目标类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流。
data[].target.namestring必填 / 必有；目标名称：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
data[].target.revisionstring可选；实际执行的动作修订 ID（actr_ 前缀）；仅动作调用有。
data[].target.versionstring可选；实际运行的精确版本号；仅脚本与工作流调用有。
data[].args_previewstring必填 / 必有；调用参数的单行预览，由服务端截断；超过 32 KB 的原文存放在对象存储而不内联。
data[].result_previewnull / string必填 / 必有；返回值的单行预览，由服务端截断；调用结束前为 null。
data[].status"running" / "completed" / "faulted" / "cancelled"必填 / 必有；调用状态。running 执行中；completed 已正常返回；faulted 失败，error 给出原因；cancelled 因运行被取消而中止。
data[].started_atstring必填 / 必有；调用开始的时间（RFC 3339 UTC）。
data[].ended_atnull / string必填 / 必有；调用结束的时间（RFC 3339 UTC）；仍在执行为 null。
data[].duration_msnull / number必填 / 必有；从开始到结束的毫秒数；未结束为 null。
data[].errornull / object必填 / 必有；调用失败时的错误详情；成功或仍在执行为 null。
data[].error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data[].error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data[].error（分支2).titlestring必填 / 必有；错误的简短标题。
data[].error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data[].error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data[].error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data[].error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data[].error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data[].error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data[].error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data[].error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[].error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data[].error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data[].error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data[].error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data[].error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data[].error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data[].error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data[].error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data[].child_run_idnull / string必填 / 必有；目标是脚本或工作流时，由本次调用启动的子运行 ID；动作与平台 API 调用为 null。
data[].invocation_keystring必填 / 必有；标识这一次逻辑调用的键，随调用发往下游，使至少一次语义下的重试可被去重。
data[].request_idstring / null必填 / 必有；下游响应的 X-Request-Id；尚未收到响应或响应未提供该头时为 null。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出运行产物

读取运行产物及其文件引用。按账本顺序返回类型、大小及所属步骤。

GET /automation/v1/runs/{id}/artifacts

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
query: limitinteger可选；每页条数，整数 1–100，默认 50。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/artifacts" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.artifacts.list({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的运行产物，按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；产物 ID，按不透明字符串处理。
data[].file_idstring必填 / 必有；产物在文件服务中的文件 ID，用文件接口下载内容。
data[].namestring必填 / 必有；产物文件名。
data[].content_typestring必填 / 必有；产物的 MIME 类型。
data[].size_in_bytesnumber必填 / 必有；产物大小，单位字节。
data[].tasknull / string必填 / 必有；产生该产物的工作流步骤的 JSON Pointer；不属于某个步骤为 null。
data[].created_atstring必填 / 必有；产物创建时间（RFC 3339 UTC）。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

完成等待点

仅完成 event 等待点，payload 上限 32 KiB 且须满足等待条件；timer 与 child 不支持手动完成。相同 id 与相同 payload 重放返回 replayed=true，其他重复提交返回 WAIT_ALREADY_RESOLVED，超时返回 WAIT_EXPIRED。

POST /automation/v1/runs/{id}/waits/{wait_id}/complete

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
path: wait_idstring必填；该运行下的等待点 ID（wait_）。

application/json

不接受额外字段。

字段类型说明
idstring可选；可选事件去重 ID；同一等待点重复提交相同 ID 和 payload 返回 replayed=true。
payloadnull / string / number / boolean / object / null / string / number / boolean / object / JSON[][]必填 / 必有；事件数据，JSON 编码最多 32 KiB；必须满足等待点的过滤条件。
payload（分支5).*（分支5)object递归 JSON 值。
payload（分支5).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
payload（分支6)[]（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
payload（分支6)[]（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
WAIT_ID同一运行中 kind=event、state=open 的等待点 id
: "${RUN_ID:?Set RUN_ID}"
: "${WAIT_ID:?Set WAIT_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/waits/${WAIT_ID}/complete" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "payload": {
    "answer": 42
  }
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.waits.complete({
  "path": {
    "id": env("RUN_ID"),
    "wait_id": env("WAIT_ID")
  },
  "body": {
    "payload": {
      "answer": 42
    }
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
idstring必填 / 必有；等待点 ID，前缀 wait_。
run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件；timer 等待到点；child 等待子运行；本接口只对 event 有效。
state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；完成后的等待点状态。open 仍在等待；resolved 已被满足；expired 已到期；cancelled 已取消。成功提交的事件使其变为 resolved。
tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer。
task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）。
replayedboolean必填 / 必有；true 表示这是对同一 id 且相同 payload 的重复提交，返回的是原结果而不是再次处理。

实测响应

HTTP 200

{
  "id": "wait_wf-eebc9ef34869206fa1bcc1e2ae6375990a7ab34c5ad485ac98a4f189c4b37346",
  "run_id": "run_00mv67mkw52c7fa90cc9649b1053e66fd836b071f289acb667ff8ca853e65bc4608e9a45bd",
  "kind": "event",
  "state": "resolved",
  "task": {
    "reference": "/do/0/ready",
    "name": "ready"
  },
  "resume_at": null,
  "event_type": "ready",
  "child_run_id": null,
  "created_at": "2026-10-13T04:57:56.982Z",
  "expires_at": "2026-10-14T04:57:50.405Z",
  "resolved_at": "2026-10-13T04:58:03.972Z",
  "replayed": false
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 INPUT_INVALID：输入不满足目标契约或业务校验。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。 WAIT_NOT_FOUND：运行中不存在该等待点。
409OPERATION_NOT_SUPPORTED：该资源类型不支持此操作。 WAIT_ALREADY_RESOLVED：等待点已关闭，或重复事件与原提交不同。
410WAIT_EXPIRED：等待点已超过到期时间。
413PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出运行步骤

分页读取步骤账本；include=planned 附带尚未执行的顶层步骤，group_by=reference 按步骤引用聚合次数、状态和耗时。

GET /automation/v1/runs/{id}/tasks

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
query: limitinteger可选；运行台账每页条数，整数 1–200，默认 50；其它集合上限为 100。 minimum: 1；maximum: 200
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: include"planned"可选；仅支持 planned，附带尚未执行的顶层步骤；省略只读已有步骤。
query: group_by"reference"可选；仅支持 reference，按步骤引用聚合循环执行；省略返回逐次步骤。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/tasks" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.tasks.list({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject / object[]必填 / 必有；本页的工作流步骤记录；group_by=reference 时为按 reference 聚合的 TaskGroup 行，按执行顺序排列。
data[]（分支1).idstring必填 / 必有；步骤执行记录的标识，按不透明字符串处理。
data[]（分支1).run_idstring必填 / 必有；所属运行 ID。
data[]（分支1).referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。
data[]（分支1).namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
data[]（分支1).kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
data[]（分支1).iterationnumber[]必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。
data[]（分支1).attemptnumber必填 / 必有；第几次尝试；步骤因重试而重新执行时递增。
data[]（分支1).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
data[]（分支1).skippedboolean必填 / 必有；true 表示该步骤被跳过而没有实际执行。
data[]（分支1).started_atnull / string必填 / 必有；步骤开始的时间（RFC 3339 UTC）；未开始为 null。
data[]（分支1).ended_atnull / string必填 / 必有；步骤结束的时间（RFC 3339 UTC）；未结束为 null。
data[]（分支1).duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
data[]（分支1).inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[]（分支1).input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).input_truncatedboolean必填 / 必有；true 表示 input 超过 32 KB 已被截断。
data[]（分支1).outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[]（分支1).output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).output_truncatedboolean必填 / 必有；输出超过内联限制而被省略时为 true。
data[]（分支1).errornull / object必填 / 必有；步骤失败时的错误详情；未失败为 null。
data[]（分支1).error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data[]（分支1).error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data[]（分支1).error（分支2).titlestring必填 / 必有；错误的简短标题。
data[]（分支1).error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data[]（分支1).error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data[]（分支1).error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data[]（分支1).error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data[]（分支1).error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data[]（分支1).error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data[]（分支1).error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data[]（分支1).error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[]（分支1).error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data[]（分支1).error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data[]（分支1).error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data[]（分支1).error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data[]（分支1).error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data[]（分支1).error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支1).error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支1).error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data[]（分支1).actionnull / object必填 / 必有；call 步骤执行的动作 {name, revision}；其它步骤为 null。
data[]（分支1).action（分支2).namestring必填 / 必有；动作全名 ns/name。
data[]（分支1).action（分支2).revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[]（分支1).child_runnull / object必填 / 必有；run 步骤启动的子运行摘要 {id, number, status, resolved_version}；其它步骤为 null。
data[]（分支1).child_run（分支2).idstring必填 / 必有；子运行 ID（run_ 前缀），创建后即可读取。
data[]（分支1).child_run（分支2).numbernull / number必填 / 必有；子运行在其定义内的序号；临时运行为 null。
data[]（分支1).child_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；子运行的状态。pending 尚未开始；running 执行中；waiting 在等待；suspended 已暂停；cancelled 已取消；faulted 失败；completed 成功完成。等待型子运行在结束时补全终态，detach 的子运行只记录启动时的状态。
data[]（分支1).child_run（分支2).resolved_versionnull / string必填 / 必有；子运行解析到的精确版本号；临时运行为 null。
data[]（分支2).referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。
data[]（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
data[]（分支2).countnumber必填 / 必有；该 reference 下合并的执行记录条数（循环的迭代数）。
data[]（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
data[]（分支2).duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取运行事件

读取 CloudEvents 账本或订阅实时事件流。默认返回 CloudEvents 账本页，Accept: text/event-stream 开启实时流，事件名为 ai.praxis.automation.run.status、ai.praxis.automation.run.progress、ai.praxis.automation.call.started、ai.praxis.automation.call.completed、ai.praxis.automation.task.started、ai.praxis.automation.task.completed、ai.praxis.automation.wait.created、ai.praxis.automation.wait.resolved。id 为续传游标，Last-Event-ID 优先于 cursor；每 20 秒发送 : ping，运行终态后以 event: end 收尾。

GET /automation/v1/runs/{id}/events

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
query: limitinteger可选；每页条数，整数 1–100，默认 50。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
header: Accept"application/json" / "text/event-stream"可选；application/json（默认）读取账本页；text/event-stream 订阅实时流。
header: Last-Event-IDstring可选；SSE 续传游标，读取该事件之后的记录；优先于 cursor，仅用于实时流。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/events" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Accept: text/event-stream"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
for await (const event of automation.runs.events({
  "path": {
    "id": env("RUN_ID")
  }
})) {
  console.log(event);
}

响应

HTTP 200

Success

application/json

字段类型说明
dataobject / object / object / object / object[]必填 / 必有；本页的账本事件（RunEvent），按事件顺序排列。
data[]（分支1).type"ai.praxis.automation.run.status"必填 / 必有；事件类型：固定为 ai.praxis.automation.run.status，运行状态发生变化，data 为完整的运行。
data[]（分支1).dataobject必填 / 必有；一次运行的完整状态：目标、状态、输入输出、错误、发起方、运行树位置和各类时间。 不接受额外字段。
data[]（分支1).data.idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
data[]（分支1).data.kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data[]（分支1).data.numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
data[]（分支1).data.definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
data[]（分支1).data.definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
data[]（分支1).data.definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
data[]（分支1).data.targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
data[]（分支1).data.resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
data[]（分支1).data.source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
data[]（分支1).data.language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
data[]（分支1).data.status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
data[]（分支1).data.progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
data[]（分支1).data.progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
data[]（分支1).data.progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
data[]（分支1).data.progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
data[]（分支1).data.progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
data[]（分支1).data.current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
data[]（分支1).data.current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data[]（分支1).data.current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data[]（分支1).data.current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data[]（分支1).data.current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data[]（分支1).data.current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data[]（分支1).data.current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data[]（分支1).data.current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data[]（分支1).data.current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data[]（分支1).data.current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data[]（分支1).data.current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data[]（分支1).data.current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data[]（分支1).data.current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data[]（分支1).data.current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
data[]（分支1).data.countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
data[]（分支1).data.counters.callsnumber必填 / 必有；脚本发出的调用总数。
data[]（分支1).data.counters.action_callsnumber必填 / 必有；其中调用动作的次数。
data[]（分支1).data.counters.child_runsnumber必填 / 必有；启动的子运行数。
data[]（分支1).data.counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
data[]（分支1).data.counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
data[]（分支1).data.inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[]（分支1).data.input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).data.input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).data.outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[]（分支1).data.output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).data.output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支1).data.errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
data[]（分支1).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data[]（分支1).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data[]（分支1).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
data[]（分支1).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data[]（分支1).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data[]（分支1).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data[]（分支1).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data[]（分支1).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data[]（分支1).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data[]（分支1).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data[]（分支1).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[]（分支1).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data[]（分支1).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data[]（分支1).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data[]（分支1).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data[]（分支1).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data[]（分支1).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支1).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支1).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data[]（分支1).data.initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
data[]（分支1).data.initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[]（分支1).data.initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[]（分支1).data.channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
data[]（分支1).data.ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
data[]（分支1).data.parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
data[]（分支1).data.parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
data[]（分支1).data.parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
data[]（分支1).data.parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
data[]（分支1).data.parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
data[]（分支1).data.parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
data[]（分支1).data.parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
data[]（分支1).data.root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
data[]（分支1).data.depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
data[]（分支1).data.attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
data[]（分支1).data.deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
data[]（分支1).data.created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
data[]（分支1).data.started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
data[]（分支1).data.ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
data[]（分支1).data.updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
data[]（分支1).data.heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
data[]（分支1).data.cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
data[]（分支1).data.cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
data[]（分支1).data.cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[]（分支1).data.cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[]（分支1).data.cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
data[]（分支1).data.suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
data[]（分支1).data.suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
data[]（分支1).data.suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[]（分支1).data.suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[]（分支1).data.queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
data[]（分支1).data.run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
data[]（分支1).data.wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
data[]（分支1).data.usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
data[]（分支1).data.usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
data[]（分支1).data.usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
data[]（分支1).data.usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
data[]（分支1).data.usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
data[]（分支1).data.usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
data[]（分支1).data.usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
data[]（分支1).data.usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
data[]（分支1).data.rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
data[]（分支1).data.labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
data[]（分支1).data.triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
data[]（分支1).data.trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
data[]（分支1).data.trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
data[]（分支1).data.cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
data[]（分支1).data.input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
data[]（分支1).data.output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。
data[]（分支1).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data[]（分支1).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data[]（分支1).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data[]（分支1).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data[]（分支1).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data[]（分支1).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data[]（分支2).type"ai.praxis.automation.run.progress"必填 / 必有；事件类型：固定为 ai.praxis.automation.run.progress，运行上报了新进度，data 为进度。
data[]（分支2).dataobject必填 / 必有；运行报告的进度，包含说明、已完成量与总量。 不接受额外字段。
data[]（分支2).data.labelstring必填 / 必有；进度说明文字，例如当前阶段。
data[]（分支2).data.currentnull / number必填 / 必有；已完成的数量；未报告为 null。
data[]（分支2).data.totalnull / number必填 / 必有；总量；未知为 null。
data[]（分支2).data.updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
data[]（分支2).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data[]（分支2).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data[]（分支2).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data[]（分支2).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data[]（分支2).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data[]（分支2).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data[]（分支3).type"ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed"必填 / 必有；事件类型。ai.praxis.automation.call.started 调用开始；ai.praxis.automation.call.completed 调用结束（成功或失败）；data 为调用记录。
data[]（分支3).dataobject必填 / 必有；脚本运行中的一次调用记录（动作、平台 API、脚本或工作流），按 seq 顺序排列。 不接受额外字段。
data[]（分支3).data.idstring必填 / 必有；调用 ID，前缀 call_。
data[]（分支3).data.run_idstring必填 / 必有；发出该调用的脚本运行 ID（run_ 前缀）。
data[]（分支3).data.seqnumber必填 / 必有；调用在该运行中的序号，随调用顺序递增；与 run_id 一起定位这次调用。
data[]（分支3).data.targetobject必填 / 必有；被调用的目标 {kind, name, revision?, version?}。 不接受额外字段。
data[]（分支3).data.target.kind"action" / "script" / "workflow" / "platform_api"必填 / 必有；目标类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流。
data[]（分支3).data.target.namestring必填 / 必有；目标名称：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
data[]（分支3).data.target.revisionstring可选；实际执行的动作修订 ID（actr_ 前缀）；仅动作调用有。
data[]（分支3).data.target.versionstring可选；实际运行的精确版本号；仅脚本与工作流调用有。
data[]（分支3).data.args_previewstring必填 / 必有；调用参数的单行预览，由服务端截断；超过 32 KB 的原文存放在对象存储而不内联。
data[]（分支3).data.result_previewnull / string必填 / 必有；返回值的单行预览，由服务端截断；调用结束前为 null。
data[]（分支3).data.status"running" / "completed" / "faulted" / "cancelled"必填 / 必有；调用状态。running 执行中；completed 已正常返回；faulted 失败，error 给出原因；cancelled 因运行被取消而中止。
data[]（分支3).data.started_atstring必填 / 必有；调用开始的时间（RFC 3339 UTC）。
data[]（分支3).data.ended_atnull / string必填 / 必有；调用结束的时间（RFC 3339 UTC）；仍在执行为 null。
data[]（分支3).data.duration_msnull / number必填 / 必有；从开始到结束的毫秒数；未结束为 null。
data[]（分支3).data.errornull / object必填 / 必有；调用失败时的错误详情；成功或仍在执行为 null。
data[]（分支3).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data[]（分支3).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data[]（分支3).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
data[]（分支3).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data[]（分支3).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data[]（分支3).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data[]（分支3).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data[]（分支3).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data[]（分支3).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data[]（分支3).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data[]（分支3).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[]（分支3).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data[]（分支3).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data[]（分支3).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data[]（分支3).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data[]（分支3).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data[]（分支3).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支3).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支3).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data[]（分支3).data.child_run_idnull / string必填 / 必有；目标是脚本或工作流时，由本次调用启动的子运行 ID；动作与平台 API 调用为 null。
data[]（分支3).data.invocation_keystring必填 / 必有；标识这一次逻辑调用的键，随调用发往下游，使至少一次语义下的重试可被去重。
data[]（分支3).data.request_idstring / null必填 / 必有；下游响应的 X-Request-Id；尚未收到响应或响应未提供该头时为 null。
data[]（分支3).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data[]（分支3).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data[]（分支3).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data[]（分支3).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data[]（分支3).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data[]（分支3).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data[]（分支4).type"ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed"必填 / 必有；事件类型。ai.praxis.automation.task.started 步骤开始；ai.praxis.automation.task.completed 步骤结束；data 为步骤记录。
data[]（分支4).dataobject必填 / 必有；工作流中一个步骤的一次执行记录。循环会让同一步骤产生多条记录（iteration 不同），重试会让 attempt 递增。 不接受额外字段。
data[]（分支4).data.idstring必填 / 必有；步骤执行记录的标识，按不透明字符串处理。
data[]（分支4).data.run_idstring必填 / 必有；所属运行 ID。
data[]（分支4).data.referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。
data[]（分支4).data.namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
data[]（分支4).data.kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
data[]（分支4).data.iterationnumber[]必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。
data[]（分支4).data.attemptnumber必填 / 必有；第几次尝试；步骤因重试而重新执行时递增。
data[]（分支4).data.status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
data[]（分支4).data.skippedboolean必填 / 必有；true 表示该步骤被跳过而没有实际执行。
data[]（分支4).data.started_atnull / string必填 / 必有；步骤开始的时间（RFC 3339 UTC）；未开始为 null。
data[]（分支4).data.ended_atnull / string必填 / 必有；步骤结束的时间（RFC 3339 UTC）；未结束为 null。
data[]（分支4).data.duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
data[]（分支4).data.inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[]（分支4).data.input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支4).data.input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支4).data.input_truncatedboolean必填 / 必有；true 表示 input 超过 32 KB 已被截断。
data[]（分支4).data.outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[]（分支4).data.output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支4).data.output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[]（分支4).data.output_truncatedboolean必填 / 必有；输出超过内联限制而被省略时为 true。
data[]（分支4).data.errornull / object必填 / 必有；步骤失败时的错误详情；未失败为 null。
data[]（分支4).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data[]（分支4).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data[]（分支4).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
data[]（分支4).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data[]（分支4).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data[]（分支4).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data[]（分支4).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data[]（分支4).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data[]（分支4).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data[]（分支4).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data[]（分支4).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[]（分支4).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data[]（分支4).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data[]（分支4).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data[]（分支4).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data[]（分支4).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data[]（分支4).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支4).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data[]（分支4).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data[]（分支4).data.actionnull / object必填 / 必有；call 步骤执行的动作 {name, revision}；其它步骤为 null。
data[]（分支4).data.action（分支2).namestring必填 / 必有；动作全名 ns/name。
data[]（分支4).data.action（分支2).revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data[]（分支4).data.child_runnull / object必填 / 必有；run 步骤启动的子运行摘要 {id, number, status, resolved_version}；其它步骤为 null。
data[]（分支4).data.child_run（分支2).idstring必填 / 必有；子运行 ID（run_ 前缀），创建后即可读取。
data[]（分支4).data.child_run（分支2).numbernull / number必填 / 必有；子运行在其定义内的序号；临时运行为 null。
data[]（分支4).data.child_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；子运行的状态。pending 尚未开始；running 执行中；waiting 在等待；suspended 已暂停；cancelled 已取消；faulted 失败；completed 成功完成。等待型子运行在结束时补全终态，detach 的子运行只记录启动时的状态。
data[]（分支4).data.child_run（分支2).resolved_versionnull / string必填 / 必有；子运行解析到的精确版本号；临时运行为 null。
data[]（分支4).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data[]（分支4).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data[]（分支4).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data[]（分支4).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data[]（分支4).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data[]（分支4).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data[]（分支5).type"ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved"必填 / 必有；事件类型。ai.praxis.automation.wait.created 等待点创建；ai.praxis.automation.wait.resolved 等待点被满足、到期或取消；data 为等待点。
data[]（分支5).dataobject必填 / 必有；运行上的一个等待点，工作流在它被满足、到期或取消之前不会继续。 不接受额外字段。
data[]（分支5).data.idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data[]（分支5).data.run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data[]（分支5).data.kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data[]（分支5).data.state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data[]（分支5).data.tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data[]（分支5).data.task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data[]（分支5).data.task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data[]（分支5).data.resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data[]（分支5).data.event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data[]（分支5).data.child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data[]（分支5).data.created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data[]（分支5).data.expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data[]（分支5).data.resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
data[]（分支5).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data[]（分支5).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data[]（分支5).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data[]（分支5).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data[]（分支5).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data[]（分支5).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

text/event-stream

字段类型说明
idstring可选；Resume cursor of this entry; send it back as Last-Event-ID, or as cursor on the JSON form, to continue after it. Absent on the end event.
event"ai.praxis.automation.run.status" / "ai.praxis.automation.run.progress" / "ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed" / "ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed" / "ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved" / "end"必填 / 必有；SSE event name: one of ai.praxis.automation.run.status, ai.praxis.automation.run.progress, ai.praxis.automation.call.started, ai.praxis.automation.call.completed, ai.praxis.automation.task.started, ai.praxis.automation.task.completed, ai.praxis.automation.wait.created, ai.praxis.automation.wait.resolved, naming the RunEvent type carried in data; end is sent once when the run has reached a terminal status and closes the stream.
dataobject / object / object / object / object / object必填 / 必有；Decoded JSON of one run event, whose shape is selected by its type; for the end event, an empty object.
data（分支1)（分支1).type"ai.praxis.automation.run.status"必填 / 必有；事件类型：固定为 ai.praxis.automation.run.status，运行状态发生变化，data 为完整的运行。
data（分支1)（分支1).dataobject必填 / 必有；一次运行的完整状态：目标、状态、输入输出、错误、发起方、运行树位置和各类时间。 不接受额外字段。
data（分支1)（分支1).data.idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
data（分支1)（分支1).data.kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
data（分支1)（分支1).data.numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
data（分支1)（分支1).data.definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
data（分支1)（分支1).data.definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
data（分支1)（分支1).data.definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
data（分支1)（分支1).data.targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
data（分支1)（分支1).data.resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
data（分支1)（分支1).data.source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
data（分支1)（分支1).data.language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
data（分支1)（分支1).data.status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
data（分支1)（分支1).data.progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
data（分支1)（分支1).data.progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
data（分支1)（分支1).data.progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
data（分支1)（分支1).data.progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
data（分支1)（分支1).data.progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
data（分支1)（分支1).data.current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
data（分支1)（分支1).data.current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data（分支1)（分支1).data.current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data（分支1)（分支1).data.current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data（分支1)（分支1).data.current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data（分支1)（分支1).data.current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data（分支1)（分支1).data.current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data（分支1)（分支1).data.current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data（分支1)（分支1).data.current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data（分支1)（分支1).data.current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data（分支1)（分支1).data.current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data（分支1)（分支1).data.current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data（分支1)（分支1).data.current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data（分支1)（分支1).data.current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
data（分支1)（分支1).data.countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
data（分支1)（分支1).data.counters.callsnumber必填 / 必有；脚本发出的调用总数。
data（分支1)（分支1).data.counters.action_callsnumber必填 / 必有；其中调用动作的次数。
data（分支1)（分支1).data.counters.child_runsnumber必填 / 必有；启动的子运行数。
data（分支1)（分支1).data.counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
data（分支1)（分支1).data.counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
data（分支1)（分支1).data.inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data（分支1)（分支1).data.input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支1).data.input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支1).data.outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data（分支1)（分支1).data.output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支1).data.output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支1).data.errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
data（分支1)（分支1).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data（分支1)（分支1).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data（分支1)（分支1).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
data（分支1)（分支1).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data（分支1)（分支1).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data（分支1)（分支1).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data（分支1)（分支1).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data（分支1)（分支1).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data（分支1)（分支1).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data（分支1)（分支1).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data（分支1)（分支1).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data（分支1)（分支1).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data（分支1)（分支1).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data（分支1)（分支1).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data（分支1)（分支1).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data（分支1)（分支1).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data（分支1)（分支1).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data（分支1)（分支1).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data（分支1)（分支1).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data（分支1)（分支1).data.initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
data（分支1)（分支1).data.initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data（分支1)（分支1).data.initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data（分支1)（分支1).data.channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
data（分支1)（分支1).data.ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
data（分支1)（分支1).data.parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
data（分支1)（分支1).data.parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
data（分支1)（分支1).data.parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
data（分支1)（分支1).data.parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
data（分支1)（分支1).data.parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
data（分支1)（分支1).data.parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
data（分支1)（分支1).data.parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
data（分支1)（分支1).data.root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
data（分支1)（分支1).data.depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
data（分支1)（分支1).data.attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
data（分支1)（分支1).data.deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
data（分支1)（分支1).data.created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
data（分支1)（分支1).data.started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
data（分支1)（分支1).data.ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
data（分支1)（分支1).data.updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
data（分支1)（分支1).data.heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
data（分支1)（分支1).data.cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
data（分支1)（分支1).data.cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
data（分支1)（分支1).data.cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data（分支1)（分支1).data.cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data（分支1)（分支1).data.cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
data（分支1)（分支1).data.suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
data（分支1)（分支1).data.suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
data（分支1)（分支1).data.suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data（分支1)（分支1).data.suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data（分支1)（分支1).data.queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
data（分支1)（分支1).data.run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
data（分支1)（分支1).data.wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
data（分支1)（分支1).data.usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
data（分支1)（分支1).data.usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
data（分支1)（分支1).data.usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
data（分支1)（分支1).data.usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
data（分支1)（分支1).data.usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
data（分支1)（分支1).data.usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
data（分支1)（分支1).data.usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
data（分支1)（分支1).data.usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
data（分支1)（分支1).data.rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
data（分支1)（分支1).data.labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
data（分支1)（分支1).data.triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
data（分支1)（分支1).data.trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
data（分支1)（分支1).data.trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
data（分支1)（分支1).data.cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
data（分支1)（分支1).data.input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
data（分支1)（分支1).data.output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。
data（分支1)（分支1).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data（分支1)（分支1).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data（分支1)（分支1).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data（分支1)（分支1).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data（分支1)（分支1).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data（分支1)（分支1).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data（分支1)（分支2).type"ai.praxis.automation.run.progress"必填 / 必有；事件类型：固定为 ai.praxis.automation.run.progress，运行上报了新进度，data 为进度。
data（分支1)（分支2).dataobject必填 / 必有；运行报告的进度，包含说明、已完成量与总量。 不接受额外字段。
data（分支1)（分支2).data.labelstring必填 / 必有；进度说明文字，例如当前阶段。
data（分支1)（分支2).data.currentnull / number必填 / 必有；已完成的数量；未报告为 null。
data（分支1)（分支2).data.totalnull / number必填 / 必有；总量；未知为 null。
data（分支1)（分支2).data.updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
data（分支1)（分支2).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data（分支1)（分支2).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data（分支1)（分支2).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data（分支1)（分支2).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data（分支1)（分支2).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data（分支1)（分支2).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data（分支1)（分支3).type"ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed"必填 / 必有；事件类型。ai.praxis.automation.call.started 调用开始；ai.praxis.automation.call.completed 调用结束（成功或失败）；data 为调用记录。
data（分支1)（分支3).dataobject必填 / 必有；脚本运行中的一次调用记录（动作、平台 API、脚本或工作流），按 seq 顺序排列。 不接受额外字段。
data（分支1)（分支3).data.idstring必填 / 必有；调用 ID，前缀 call_。
data（分支1)（分支3).data.run_idstring必填 / 必有；发出该调用的脚本运行 ID（run_ 前缀）。
data（分支1)（分支3).data.seqnumber必填 / 必有；调用在该运行中的序号，随调用顺序递增；与 run_id 一起定位这次调用。
data（分支1)（分支3).data.targetobject必填 / 必有；被调用的目标 {kind, name, revision?, version?}。 不接受额外字段。
data（分支1)（分支3).data.target.kind"action" / "script" / "workflow" / "platform_api"必填 / 必有；目标类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流。
data（分支1)（分支3).data.target.namestring必填 / 必有；目标名称：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
data（分支1)（分支3).data.target.revisionstring可选；实际执行的动作修订 ID（actr_ 前缀）；仅动作调用有。
data（分支1)（分支3).data.target.versionstring可选；实际运行的精确版本号；仅脚本与工作流调用有。
data（分支1)（分支3).data.args_previewstring必填 / 必有；调用参数的单行预览，由服务端截断；超过 32 KB 的原文存放在对象存储而不内联。
data（分支1)（分支3).data.result_previewnull / string必填 / 必有；返回值的单行预览，由服务端截断；调用结束前为 null。
data（分支1)（分支3).data.status"running" / "completed" / "faulted" / "cancelled"必填 / 必有；调用状态。running 执行中；completed 已正常返回；faulted 失败，error 给出原因；cancelled 因运行被取消而中止。
data（分支1)（分支3).data.started_atstring必填 / 必有；调用开始的时间（RFC 3339 UTC）。
data（分支1)（分支3).data.ended_atnull / string必填 / 必有；调用结束的时间（RFC 3339 UTC）；仍在执行为 null。
data（分支1)（分支3).data.duration_msnull / number必填 / 必有；从开始到结束的毫秒数；未结束为 null。
data（分支1)（分支3).data.errornull / object必填 / 必有；调用失败时的错误详情；成功或仍在执行为 null。
data（分支1)（分支3).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data（分支1)（分支3).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data（分支1)（分支3).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
data（分支1)（分支3).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data（分支1)（分支3).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data（分支1)（分支3).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data（分支1)（分支3).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data（分支1)（分支3).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data（分支1)（分支3).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data（分支1)（分支3).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data（分支1)（分支3).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data（分支1)（分支3).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data（分支1)（分支3).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data（分支1)（分支3).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data（分支1)（分支3).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data（分支1)（分支3).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data（分支1)（分支3).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data（分支1)（分支3).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data（分支1)（分支3).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data（分支1)（分支3).data.child_run_idnull / string必填 / 必有；目标是脚本或工作流时，由本次调用启动的子运行 ID；动作与平台 API 调用为 null。
data（分支1)（分支3).data.invocation_keystring必填 / 必有；标识这一次逻辑调用的键，随调用发往下游，使至少一次语义下的重试可被去重。
data（分支1)（分支3).data.request_idstring / null必填 / 必有；下游响应的 X-Request-Id；尚未收到响应或响应未提供该头时为 null。
data（分支1)（分支3).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data（分支1)（分支3).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data（分支1)（分支3).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data（分支1)（分支3).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data（分支1)（分支3).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data（分支1)（分支3).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data（分支1)（分支4).type"ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed"必填 / 必有；事件类型。ai.praxis.automation.task.started 步骤开始；ai.praxis.automation.task.completed 步骤结束；data 为步骤记录。
data（分支1)（分支4).dataobject必填 / 必有；工作流中一个步骤的一次执行记录。循环会让同一步骤产生多条记录（iteration 不同），重试会让 attempt 递增。 不接受额外字段。
data（分支1)（分支4).data.idstring必填 / 必有；步骤执行记录的标识，按不透明字符串处理。
data（分支1)（分支4).data.run_idstring必填 / 必有；所属运行 ID。
data（分支1)（分支4).data.referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。
data（分支1)（分支4).data.namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
data（分支1)（分支4).data.kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
data（分支1)（分支4).data.iterationnumber[]必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。
data（分支1)（分支4).data.attemptnumber必填 / 必有；第几次尝试；步骤因重试而重新执行时递增。
data（分支1)（分支4).data.status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
data（分支1)（分支4).data.skippedboolean必填 / 必有；true 表示该步骤被跳过而没有实际执行。
data（分支1)（分支4).data.started_atnull / string必填 / 必有；步骤开始的时间（RFC 3339 UTC）；未开始为 null。
data（分支1)（分支4).data.ended_atnull / string必填 / 必有；步骤结束的时间（RFC 3339 UTC）；未结束为 null。
data（分支1)（分支4).data.duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
data（分支1)（分支4).data.inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data（分支1)（分支4).data.input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支4).data.input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支4).data.input_truncatedboolean必填 / 必有；true 表示 input 超过 32 KB 已被截断。
data（分支1)（分支4).data.outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data（分支1)（分支4).data.output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支4).data.output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data（分支1)（分支4).data.output_truncatedboolean必填 / 必有；输出超过内联限制而被省略时为 true。
data（分支1)（分支4).data.errornull / object必填 / 必有；步骤失败时的错误详情；未失败为 null。
data（分支1)（分支4).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
data（分支1)（分支4).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
data（分支1)（分支4).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
data（分支1)（分支4).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
data（分支1)（分支4).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
data（分支1)（分支4).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
data（分支1)（分支4).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
data（分支1)（分支4).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
data（分支1)（分支4).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
data（分支1)（分支4).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
data（分支1)（分支4).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data（分支1)（分支4).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
data（分支1)（分支4).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
data（分支1)（分支4).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
data（分支1)（分支4).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
data（分支1)（分支4).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
data（分支1)（分支4).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
data（分支1)（分支4).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
data（分支1)（分支4).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
data（分支1)（分支4).data.actionnull / object必填 / 必有；call 步骤执行的动作 {name, revision}；其它步骤为 null。
data（分支1)（分支4).data.action（分支2).namestring必填 / 必有；动作全名 ns/name。
data（分支1)（分支4).data.action（分支2).revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
data（分支1)（分支4).data.child_runnull / object必填 / 必有；run 步骤启动的子运行摘要 {id, number, status, resolved_version}；其它步骤为 null。
data（分支1)（分支4).data.child_run（分支2).idstring必填 / 必有；子运行 ID（run_ 前缀），创建后即可读取。
data（分支1)（分支4).data.child_run（分支2).numbernull / number必填 / 必有；子运行在其定义内的序号；临时运行为 null。
data（分支1)（分支4).data.child_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；子运行的状态。pending 尚未开始；running 执行中；waiting 在等待；suspended 已暂停；cancelled 已取消；faulted 失败；completed 成功完成。等待型子运行在结束时补全终态，detach 的子运行只记录启动时的状态。
data（分支1)（分支4).data.child_run（分支2).resolved_versionnull / string必填 / 必有；子运行解析到的精确版本号；临时运行为 null。
data（分支1)（分支4).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data（分支1)（分支4).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data（分支1)（分支4).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data（分支1)（分支4).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data（分支1)（分支4).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data（分支1)（分支4).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
data（分支1)（分支5).type"ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved"必填 / 必有；事件类型。ai.praxis.automation.wait.created 等待点创建；ai.praxis.automation.wait.resolved 等待点被满足、到期或取消；data 为等待点。
data（分支1)（分支5).dataobject必填 / 必有；运行上的一个等待点，工作流在它被满足、到期或取消之前不会继续。 不接受额外字段。
data（分支1)（分支5).data.idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
data（分支1)（分支5).data.run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
data（分支1)（分支5).data.kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
data（分支1)（分支5).data.state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
data（分支1)（分支5).data.tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
data（分支1)（分支5).data.task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
data（分支1)（分支5).data.task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
data（分支1)（分支5).data.resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
data（分支1)（分支5).data.event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
data（分支1)（分支5).data.child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
data（分支1)（分支5).data.created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
data（分支1)（分支5).data.expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
data（分支1)（分支5).data.resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
data（分支1)（分支5).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
data（分支1)（分支5).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
data（分支1)（分支5).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
data（分支1)（分支5).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
data（分支1)（分支5).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data（分支1)（分支5).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
（分支1).event"ai.praxis.automation.run.status" / "ai.praxis.automation.run.progress" / "ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed" / "ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed" / "ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved"可选；SSE event name: one of ai.praxis.automation.run.status, ai.praxis.automation.run.progress, ai.praxis.automation.call.started, ai.praxis.automation.call.completed, ai.praxis.automation.task.started, ai.praxis.automation.task.completed, ai.praxis.automation.wait.created, ai.praxis.automation.wait.resolved, naming the RunEvent type carried in data.
（分支1).dataobject / object / object / object / object可选；运行账本中的一条 CloudEvents 事件，载荷带完整投影，收到后不必回拉。type 决定 data 的类型：run.status 为运行，run.progress 为进度，call.* 为调用，task.* 为步骤，wait.* 为等待点。
（分支1).data（分支1).type"ai.praxis.automation.run.status"必填 / 必有；事件类型：固定为 ai.praxis.automation.run.status，运行状态发生变化，data 为完整的运行。
（分支1).data（分支1).dataobject必填 / 必有；一次运行的完整状态：目标、状态、输入输出、错误、发起方、运行树位置和各类时间。 不接受额外字段。
（分支1).data（分支1).data.idstring必填 / 必有；不透明运行 ID。新建非确定性 ID 为 run_ + 10 位 base36 毫秒时间前缀 + 64 位 hex DO ID，共 78 字符；旧随机 ID 为 46 字符，历史及确定性 ID 仍有效。同毫秒内不保证创建顺序。
（分支1).data（分支1).data.kind"script" / "workflow"必填 / 必有；编排类型。script 为 TypeScript 脚本，一次执行；workflow 为 YAML 工作流，由步骤组成，可等待事件、定时器或子运行并可暂停。
（分支1).data（分支1).data.numbernull / number必填 / 必有；运行在其脚本或工作流内的递增序号；临时运行为 null。
（分支1).data（分支1).data.definitionnull / object必填 / 必有；运行所属的脚本或工作流 {namespace, name}；临时运行（直接传 source）为 null。
（分支1).data（分支1).data.definition（分支2).namespacestring必填 / 必有；脚本或工作流的命名空间。
（分支1).data（分支1).data.definition（分支2).namestring必填 / 必有；脚本或工作流的名字。
（分支1).data（分支1).data.targetnull / string必填 / 必有；创建时 target 参数的原文（如 acme/report@latest）；临时运行为 null。
（分支1).data（分支1).data.resolved_versionnull / string必填 / 必有；target 解析到的精确版本号；临时运行为 null。
（分支1).data（分支1).data.source_digestnull / string必填 / 必有；临时运行的源码摘要，可用于读取源码；由已发布定义启动的运行为 null。
（分支1).data（分支1).data.language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
（分支1).data（分支1).data.status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；运行状态。pending 已创建尚未开始；running 执行中；waiting 工作流在等待事件、定时器或子运行；suspended 工作流被暂停；cancelled 已取消；faulted 失败，error 给出原因；completed 成功完成，output 为结果。后三种是终态。
（分支1).data（分支1).data.progressnull / object必填 / 必有；运行报告的最新进度 {label, current, total, updated_at}；未报告为 null。
（分支1).data（分支1).data.progress（分支2).labelstring必填 / 必有；进度说明文字，例如当前阶段。
（分支1).data（分支1).data.progress（分支2).currentnull / number必填 / 必有；已完成的数量；未报告为 null。
（分支1).data（分支1).data.progress（分支2).totalnull / number必填 / 必有；总量；未知为 null。
（分支1).data（分支1).data.progress（分支2).updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
（分支1).data（分支1).data.current_waitnull / object必填 / 必有；运行当前未完成的等待点；不在等待为 null。
（分支1).data（分支1).data.current_wait（分支2).idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
（分支1).data（分支1).data.current_wait（分支2).run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
（分支1).data（分支1).data.current_wait（分支2).kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
（分支1).data（分支1).data.current_wait（分支2).state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
（分支1).data（分支1).data.current_wait（分支2).tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
（分支1).data（分支1).data.current_wait（分支2).task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
（分支1).data（分支1).data.current_wait（分支2).task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
（分支1).data（分支1).data.current_wait（分支2).resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
（分支1).data（分支1).data.current_wait（分支2).event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
（分支1).data（分支1).data.current_wait（分支2).child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
（分支1).data（分支1).data.current_wait（分支2).created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
（分支1).data（分支1).data.current_wait（分支2).expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
（分支1).data（分支1).data.current_wait（分支2).resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
（分支1).data（分支1).data.countersobject必填 / 必有；运行的累计计数。 不接受额外字段。
（分支1).data（分支1).data.counters.callsnumber必填 / 必有；脚本发出的调用总数。
（分支1).data（分支1).data.counters.action_callsnumber必填 / 必有；其中调用动作的次数。
（分支1).data（分支1).data.counters.child_runsnumber必填 / 必有；启动的子运行数。
（分支1).data（分支1).data.counters.tasks_completednumber必填 / 必有；工作流已完成的步骤数。
（分支1).data（分支1).data.counters.tasks_totalnull / number必填 / 必有；工作流顶层步骤总数；脚本运行为 null。
（分支1).data（分支1).data.inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
（分支1).data（分支1).data.input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支1).data.input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支1).data.outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
（分支1).data（分支1).data.output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支1).data.output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支1).data.errornull / object必填 / 必有；运行失败（faulted）时的错误详情；未失败为 null。
（分支1).data（分支1).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
（分支1).data（分支1).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
（分支1).data（分支1).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
（分支1).data（分支1).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
（分支1).data（分支1).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
（分支1).data（分支1).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
（分支1).data（分支1).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
（分支1).data（分支1).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
（分支1).data（分支1).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
（分支1).data（分支1).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
（分支1).data（分支1).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
（分支1).data（分支1).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
（分支1).data（分支1).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
（分支1).data（分支1).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
（分支1).data（分支1).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
（分支1).data（分支1).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
（分支1).data（分支1).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
（分支1).data（分支1).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
（分支1).data（分支1).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
（分支1).data（分支1).data.initiatorobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
（分支1).data（分支1).data.initiator.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
（分支1).data（分支1).data.initiator.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
（分支1).data（分支1).data.channel"run" / "console" / "api" / "internal" / "trigger"必填 / 必有；请求进入平台的渠道。console 为控制台（经 BFF）；api 为公开 API 调用；internal 为平台内部服务调用；run 为由另一个运行创建的子运行；trigger 为触发器启动。
（分支1).data（分支1).data.ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
（分支1).data（分支1).data.parentnull / object必填 / 必有；派生本运行的父运行 {id, number, definition}；根运行为 null。
（分支1).data（分支1).data.parent（分支2).idstring必填 / 必有；父运行 ID（run_ 前缀）。
（分支1).data（分支1).data.parent（分支2).numbernull / number必填 / 必有；父运行在其定义内的序号；父运行是临时运行时为 null。
（分支1).data（分支1).data.parent（分支2).definitionnull / object必填 / 必有；父运行所属的脚本或工作流 {namespace, name}；临时运行为 null。
（分支1).data（分支1).data.parent（分支2).definition（分支2).namespacestring必填 / 必有；父运行所属定义的命名空间。
（分支1).data（分支1).data.parent（分支2).definition（分支2).namestring必填 / 必有；父运行所属定义的名字。
（分支1).data（分支1).data.parent_run_idstring / null必填 / 必有；派生出本运行的父运行 id；根运行为 null
（分支1).data（分支1).data.root_run_idstring必填 / 必有；运行树根运行的 ID；根运行自身指向自己。
（分支1).data（分支1).data.depthnumber必填 / 必有；运行树中的深度：根运行为 0，每一层子运行加 1，最大 10。
（分支1).data（分支1).data.attachnull / "wait" / "detach"必填 / 必有；子运行与父运行的关系。wait 表示父运行等待子运行结束，且子运行的截止时间不晚于父运行；detach 表示父运行不等待，也不会因父运行取消而被取消；根运行为 null。
（分支1).data（分支1).data.deadline_atstring必填 / 必有；运行的截止时间（RFC 3339 UTC）：创建时间加 deadline_seconds（脚本默认且最多 300 秒，工作流默认 86400 秒、最多 604800 秒），等待型子运行不晚于父运行截止前 1 秒。
（分支1).data（分支1).data.created_atstring必填 / 必有；运行创建时间（RFC 3339 UTC）。
（分支1).data（分支1).data.started_atnull / string必填 / 必有；开始执行的时间（RFC 3339 UTC）；仍在排队为 null。
（分支1).data（分支1).data.ended_atnull / string必填 / 必有；进入终态的时间（RFC 3339 UTC）；尚未结束为 null。
（分支1).data（分支1).data.updated_atstring必填 / 必有；运行记录最近一次更新的时间（RFC 3339 UTC）。
（分支1).data（分支1).data.heartbeat_atnull / string必填 / 必有；执行器最近一次存活信号的时间（RFC 3339 UTC）；尚未开始为 null。
（分支1).data（分支1).data.cancel_requested_atnull / string必填 / 必有；收到取消请求的时间（RFC 3339 UTC）；未取消为 null。
（分支1).data（分支1).data.cancelled_bynull / object必填 / 必有；请求取消的主体；未取消或非人为取消为 null。
（分支1).data（分支1).data.cancelled_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
（分支1).data（分支1).data.cancelled_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
（分支1).data（分支1).data.cancel_reasonnull / "user" / "parent_cancelled" / "deadline" / "executor_lost"必填 / 必有；取消原因。user 为用户取消；parent_cancelled 为父运行被取消而级联取消；deadline 为超过截止时间；executor_lost 为执行器丢失；未取消为 null。
（分支1).data（分支1).data.suspend_requested_atnull / string必填 / 必有；请求暂停工作流的时间（RFC 3339 UTC）；未暂停为 null。
（分支1).data（分支1).data.suspended_bynull / object必填 / 必有；请求暂停的主体；未暂停为 null。
（分支1).data（分支1).data.suspended_by（分支2).type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
（分支1).data（分支1).data.suspended_by（分支2).idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
（分支1).data（分支1).data.queued_msnull / number必填 / 必有；从创建到开始执行的排队毫秒数；尚未开始为 null。
（分支1).data（分支1).data.run_msnull / number必填 / 必有；实际执行毫秒数，不含等待点上的等待时间；结束后固定。
（分支1).data（分支1).data.wait_msnull / number必填 / 必有；在等待点上累计等待的毫秒数；尚无等待为 null。
（分支1).data（分支1).data.usageobject / null必填 / 必有；仅单个运行详情（含 expand）返回；列表为 null。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
（分支1).data（分支1).data.usage（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
（分支1).data（分支1).data.usage（分支1).coststring必填 / 必有；仅本运行自身的已评级实扣（不含子运行），美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
（分支1).data（分支1).data.usage（分支1).pending_eventsinteger必填 / 必有；本运行自身尚未评级的用量事件数，金额稍后才计入。 minimum: 0
（分支1).data（分支1).data.usage（分支1).by_serviceobject[]必填 / 必有；本运行按服务拆分的实扣，每项为 service 与 cost（6 位小数美元字符串）；没有用量时为空数组。
（分支1).data（分支1).data.usage（分支1).by_service[].servicestring必填 / 必有；产生用量的服务名，例如 router 或 search。
（分支1).data（分支1).data.usage（分支1).by_service[].coststring必填 / 必有；该服务已评级实扣的美元十进制字符串，精确到 6 位小数。 pattern: "^[0-9]+\.[0-9]{6}$"
（分支1).data（分支1).data.usage（分支1).tree_coststring / null必填 / 必有；仅根运行返回整棵运行树的已评级实扣（含自身），6 位小数美元字符串；子运行为 null。
（分支1).data（分支1).data.rerun_ofnull / string必填 / 必有；重跑来源：本运行是对哪个运行（run_ ID）的重跑；否则为 null。
（分支1).data（分支1).data.labelsobject必填 / 必有；用户标签与系统标签；触发器运行支持 64 个用户标签，系统标签不占用名额。
（分支1).data（分支1).data.triggerobject / null必填 / 必有；启动本运行的触发器 {id, name}；不是触发器启动时为 null。
（分支1).data（分支1).data.trigger（分支1).idstring必填 / 必有；启动本运行的触发器 ID（trg_ 前缀）。
（分支1).data（分支1).data.trigger（分支1).namestring必填 / 必有；启动本运行的触发器名称。
（分支1).data（分支1).data.cancel_messagestring / null必填 / 必有；用户提供的取消备注（1–500 字符）；未提供时为 null，cancel_reason 枚举不变。
（分支1).data（分支1).data.input_truncatedboolean可选；列表省略外置 input 时为 true，此时 input 为 null；内联值不变，运行详情返回完整值。
（分支1).data（分支1).data.output_truncatedboolean可选；列表省略外置 output 时为 true，此时 output 为 null；内联值不变，运行详情返回完整值。
（分支1).data（分支1).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
（分支1).data（分支1).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
（分支1).data（分支1).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
（分支1).data（分支1).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
（分支1).data（分支1).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
（分支1).data（分支1).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
（分支1).data（分支2).type"ai.praxis.automation.run.progress"必填 / 必有；事件类型：固定为 ai.praxis.automation.run.progress，运行上报了新进度，data 为进度。
（分支1).data（分支2).dataobject必填 / 必有；运行报告的进度，包含说明、已完成量与总量。 不接受额外字段。
（分支1).data（分支2).data.labelstring必填 / 必有；进度说明文字，例如当前阶段。
（分支1).data（分支2).data.currentnull / number必填 / 必有；已完成的数量；未报告为 null。
（分支1).data（分支2).data.totalnull / number必填 / 必有；总量；未知为 null。
（分支1).data（分支2).data.updated_atstring必填 / 必有；进度最近一次更新的时间（RFC 3339 UTC）。
（分支1).data（分支2).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
（分支1).data（分支2).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
（分支1).data（分支2).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
（分支1).data（分支2).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
（分支1).data（分支2).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
（分支1).data（分支2).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
（分支1).data（分支3).type"ai.praxis.automation.call.started" / "ai.praxis.automation.call.completed"必填 / 必有；事件类型。ai.praxis.automation.call.started 调用开始；ai.praxis.automation.call.completed 调用结束（成功或失败）；data 为调用记录。
（分支1).data（分支3).dataobject必填 / 必有；脚本运行中的一次调用记录（动作、平台 API、脚本或工作流），按 seq 顺序排列。 不接受额外字段。
（分支1).data（分支3).data.idstring必填 / 必有；调用 ID，前缀 call_。
（分支1).data（分支3).data.run_idstring必填 / 必有；发出该调用的脚本运行 ID（run_ 前缀）。
（分支1).data（分支3).data.seqnumber必填 / 必有；调用在该运行中的序号，随调用顺序递增；与 run_id 一起定位这次调用。
（分支1).data（分支3).data.targetobject必填 / 必有；被调用的目标 {kind, name, revision?, version?}。 不接受额外字段。
（分支1).data（分支3).data.target.kind"action" / "script" / "workflow" / "platform_api"必填 / 必有；目标类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流。
（分支1).data（分支3).data.target.namestring必填 / 必有；目标名称：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。
（分支1).data（分支3).data.target.revisionstring可选；实际执行的动作修订 ID（actr_ 前缀）；仅动作调用有。
（分支1).data（分支3).data.target.versionstring可选；实际运行的精确版本号；仅脚本与工作流调用有。
（分支1).data（分支3).data.args_previewstring必填 / 必有；调用参数的单行预览，由服务端截断；超过 32 KB 的原文存放在对象存储而不内联。
（分支1).data（分支3).data.result_previewnull / string必填 / 必有；返回值的单行预览，由服务端截断；调用结束前为 null。
（分支1).data（分支3).data.status"running" / "completed" / "faulted" / "cancelled"必填 / 必有；调用状态。running 执行中；completed 已正常返回；faulted 失败，error 给出原因；cancelled 因运行被取消而中止。
（分支1).data（分支3).data.started_atstring必填 / 必有；调用开始的时间（RFC 3339 UTC）。
（分支1).data（分支3).data.ended_atnull / string必填 / 必有；调用结束的时间（RFC 3339 UTC）；仍在执行为 null。
（分支1).data（分支3).data.duration_msnull / number必填 / 必有；从开始到结束的毫秒数；未结束为 null。
（分支1).data（分支3).data.errornull / object必填 / 必有；调用失败时的错误详情；成功或仍在执行为 null。
（分支1).data（分支3).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
（分支1).data（分支3).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
（分支1).data（分支3).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
（分支1).data（分支3).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
（分支1).data（分支3).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
（分支1).data（分支3).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
（分支1).data（分支3).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
（分支1).data（分支3).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
（分支1).data（分支3).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
（分支1).data（分支3).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
（分支1).data（分支3).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
（分支1).data（分支3).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
（分支1).data（分支3).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
（分支1).data（分支3).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
（分支1).data（分支3).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
（分支1).data（分支3).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
（分支1).data（分支3).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
（分支1).data（分支3).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
（分支1).data（分支3).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
（分支1).data（分支3).data.child_run_idnull / string必填 / 必有；目标是脚本或工作流时，由本次调用启动的子运行 ID；动作与平台 API 调用为 null。
（分支1).data（分支3).data.invocation_keystring必填 / 必有；标识这一次逻辑调用的键，随调用发往下游，使至少一次语义下的重试可被去重。
（分支1).data（分支3).data.request_idstring / null必填 / 必有；下游响应的 X-Request-Id；尚未收到响应或响应未提供该头时为 null。
（分支1).data（分支3).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
（分支1).data（分支3).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
（分支1).data（分支3).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
（分支1).data（分支3).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
（分支1).data（分支3).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
（分支1).data（分支3).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
（分支1).data（分支4).type"ai.praxis.automation.task.started" / "ai.praxis.automation.task.completed"必填 / 必有；事件类型。ai.praxis.automation.task.started 步骤开始；ai.praxis.automation.task.completed 步骤结束；data 为步骤记录。
（分支1).data（分支4).dataobject必填 / 必有；工作流中一个步骤的一次执行记录。循环会让同一步骤产生多条记录（iteration 不同），重试会让 attempt 递增。 不接受额外字段。
（分支1).data（分支4).data.idstring必填 / 必有；步骤执行记录的标识，按不透明字符串处理。
（分支1).data（分支4).data.run_idstring必填 / 必有；所属运行 ID。
（分支1).data（分支4).data.referencestring必填 / 必有；该步骤在工作流文档中的 JSON Pointer，例如 /do/0/start。
（分支1).data（分支4).data.namestring必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。
（分支1).data（分支4).data.kind"run" / "call" / "wait" / "set" / "for" / "fork" / "try" / "switch" / "emit" / "raise" / "listen" / "do"必填 / 必有；工作流步骤类型。call 调用动作；run 运行子脚本或子工作流；wait 等待时长；set 设置变量；for 循环；fork 并行分支；try 带捕获的块；switch 条件分支；emit 发出事件；raise 抛出错误；listen 等待事件；do 顺序执行的步骤块。
（分支1).data（分支4).data.iterationnumber[]必填 / 必有；外层 for 循环的当前迭代下标，由外到内；不在循环中为空数组。
（分支1).data（分支4).data.attemptnumber必填 / 必有；第几次尝试；步骤因重试而重新执行时递增。
（分支1).data（分支4).data.status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；步骤状态，取值与运行状态相同。pending 尚未开始；running 执行中；waiting 在等待事件、定时器或子运行；suspended 因运行被暂停；cancelled 已取消；faulted 失败；completed 成功完成。
（分支1).data（分支4).data.skippedboolean必填 / 必有；true 表示该步骤被跳过而没有实际执行。
（分支1).data（分支4).data.started_atnull / string必填 / 必有；步骤开始的时间（RFC 3339 UTC）；未开始为 null。
（分支1).data（分支4).data.ended_atnull / string必填 / 必有；步骤结束的时间（RFC 3339 UTC）；未结束为 null。
（分支1).data（分支4).data.duration_msnull / number必填 / 必有；执行耗时毫秒数；未结束为 null。
（分支1).data（分支4).data.inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
（分支1).data（分支4).data.input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支4).data.input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支4).data.input_truncatedboolean必填 / 必有；true 表示 input 超过 32 KB 已被截断。
（分支1).data（分支4).data.outputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
（分支1).data（分支4).data.output（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支4).data.output（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支1).data（分支4).data.output_truncatedboolean必填 / 必有；输出超过内联限制而被省略时为 true。
（分支1).data（分支4).data.errornull / object必填 / 必有；步骤失败时的错误详情；未失败为 null。
（分支1).data（分支4).data.error（分支2).typestring必填 / 必有；平台错误类别，或工作流 raise 定义的完整 URI，原样保留。
（分支1).data（分支4).data.error（分支2).codenull / string必填 / 必有；稳定错误码，可按码分支处理；没有为 null。
（分支1).data（分支4).data.error（分支2).titlestring必填 / 必有；错误的简短标题。
（分支1).data（分支4).data.error（分支2).detailnull / string必填 / 必有；错误的详细说明；没有为 null。
（分支1).data（分支4).data.error（分支2).sourcenull / object必填 / 必有；错误发生的位置：工作流步骤或脚本调用；未知为 null。
（分支1).data（分支4).data.error（分支2).source（分支2).kind"call" / "task"必填 / 必有；位置类型。task 表示工作流步骤；call 表示脚本中的调用。
（分支1).data（分支4).data.error（分支2).source（分支2).referencestring可选；task 类型时：出错步骤的 JSON Pointer。
（分支1).data（分支4).data.error（分支2).source（分支2).seqnumber可选；call 类型时：出错调用的序号（与 Call.seq 对应）。
（分支1).data（分支4).data.error（分支2).source（分支2).actionobject可选；出错的动作 {name, revision}；错误来自动作时才有。 不接受额外字段。
（分支1).data（分支4).data.error（分支2).source（分支2).action.namestring必填 / 必有；动作全名 ns/name。
（分支1).data（分支4).data.error（分支2).source（分支2).action.revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
（分支1).data（分支4).data.error（分支2).request_idstring / null可选；导致失败的下游响应 X-Request-Id；没有下游响应标识时为 null 或省略。
（分支1).data（分支4).data.error（分支2).errorsobject[]可选；逐字段校验错误；pointer 使用 RFC 6901 指向字段，detail 为中文修正说明。
（分支1).data（分支4).data.error（分支2).errors[].pointerstring必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。
（分支1).data（分支4).data.error（分支2).errors[].detailstring必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。
（分支1).data（分支4).data.error（分支2).errors[].hintstring可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。
（分支1).data（分支4).data.error（分支2).errors[].lineinteger可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1
（分支1).data（分支4).data.error（分支2).errors[].columninteger可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1
（分支1).data（分支4).data.error（分支2).statusnumber可选；工作流 raise 声明的 HTTP 风格状态；可省略，平台错误可能不提供。
（分支1).data（分支4).data.actionnull / object必填 / 必有；call 步骤执行的动作 {name, revision}；其它步骤为 null。
（分支1).data（分支4).data.action（分支2).namestring必填 / 必有；动作全名 ns/name。
（分支1).data（分支4).data.action（分支2).revisionstring必填 / 必有；执行的动作修订 ID（actr_ 前缀）。
（分支1).data（分支4).data.child_runnull / object必填 / 必有；run 步骤启动的子运行摘要 {id, number, status, resolved_version}；其它步骤为 null。
（分支1).data（分支4).data.child_run（分支2).idstring必填 / 必有；子运行 ID（run_ 前缀），创建后即可读取。
（分支1).data（分支4).data.child_run（分支2).numbernull / number必填 / 必有；子运行在其定义内的序号；临时运行为 null。
（分支1).data（分支4).data.child_run（分支2).status"running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended"必填 / 必有；子运行的状态。pending 尚未开始；running 执行中；waiting 在等待；suspended 已暂停；cancelled 已取消；faulted 失败；completed 成功完成。等待型子运行在结束时补全终态，detach 的子运行只记录启动时的状态。
（分支1).data（分支4).data.child_run（分支2).resolved_versionnull / string必填 / 必有；子运行解析到的精确版本号；临时运行为 null。
（分支1).data（分支4).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
（分支1).data（分支4).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
（分支1).data（分支4).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
（分支1).data（分支4).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
（分支1).data（分支4).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
（分支1).data（分支4).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
（分支1).data（分支5).type"ai.praxis.automation.wait.created" / "ai.praxis.automation.wait.resolved"必填 / 必有；事件类型。ai.praxis.automation.wait.created 等待点创建；ai.praxis.automation.wait.resolved 等待点被满足、到期或取消；data 为等待点。
（分支1).data（分支5).dataobject必填 / 必有；运行上的一个等待点，工作流在它被满足、到期或取消之前不会继续。 不接受额外字段。
（分支1).data（分支5).data.idstring必填 / 必有；等待点 ID，前缀 wait_；完成事件等待点时作为路径中的 wait_id。
（分支1).data（分支5).data.run_idstring必填 / 必有；所属运行 ID（run_ 前缀）。
（分支1).data（分支5).data.kind"event" / "timer" / "child"必填 / 必有；等待类型。event 等待外部事件，可通过 runs.completeWait 提交；timer 等待到达 resume_at；child 等待子运行结束。
（分支1).data（分支5).data.state"cancelled" / "open" / "resolved" / "expired"必填 / 必有；等待点状态。open 仍在等待；resolved 已被满足；expired 已超过 expires_at；cancelled 已被取消，不会再被满足。
（分支1).data（分支5).data.tasknull / object必填 / 必有；产生该等待的工作流步骤 {reference, name}；没有对应步骤为 null。
（分支1).data（分支5).data.task（分支2).referencestring必填 / 必有；步骤的 JSON Pointer，例如 /do/2/wait_payment。
（分支1).data（分支5).data.task（分支2).namestring必填 / 必有；步骤名，即工作流 YAML 中的键。
（分支1).data（分支5).data.resume_atnull / string必填 / 必有；kind=timer 时恢复运行的时刻（RFC 3339 UTC）；其它类型为 null。
（分支1).data（分支5).data.event_typenull / string必填 / 必有；kind=event 时等待的事件类型；其它类型为 null。
（分支1).data（分支5).data.child_run_idnull / string必填 / 必有；kind=child 时被等待的子运行 ID；其它类型为 null。
（分支1).data（分支5).data.created_atstring必填 / 必有；等待点创建时间（RFC 3339 UTC）。
（分支1).data（分支5).data.expires_atnull / string必填 / 必有；等待点到期时间（RFC 3339 UTC）；没有期限为 null。
（分支1).data（分支5).data.resolved_atnull / string必填 / 必有；等待点被满足的时间（RFC 3339 UTC）；尚未满足为 null。
（分支1).data（分支5).specversion"1.0"必填 / 必有；CloudEvents 规范版本，固定为 1.0。
（分支1).data（分支5).idstring必填 / 必有；事件 ID，在该运行的账本内唯一。
（分支1).data（分支5).sourcestring必填 / 必有；事件来源，形如 /automation/v1/runs/{id}。
（分支1).data（分支5).timestring必填 / 必有；事件发生的时间（RFC 3339 UTC）。
（分支1).data（分支5).cursorstring必填 / 必有；事件游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
（分支1).data（分支5).seqnumber必填 / 必有；事件在运行账本中的序号，严格递增。
（分支2).event"end"可选；SSE event name end: sent once when the run has reached a terminal status, and the stream then closes.
（分支2).dataobject可选；Always an empty object for the end event.

实测响应

HTTP 200

id: WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwxXQ==
event: ai.praxis.automation.run.status
data: {"type":"ai.praxis.automation.run.status","data":{"id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","kind":"script","number":null,"definition":null,"target":null,"resolved_version":null,"source_digest":"7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d","language":"ts","status":"pending","progress":null,"current_wait":null,"counters":{"calls":0,"action_calls":0,"child_runs":0,"tasks_completed":0,"tasks_total":null},"input":{"n":41},"output":null,"error":null,"initiator":{"type":"api_key","id":"key_3e00b8984967"},"channel":"api","owner":"tnt_3a9759864ccb4e00","trigger":null,"parent":null,"parent_run_id":null,"root_run_id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","depth":0,"attach":null,"deadline_at":"2026-10-13T05:02:40.954Z","created_at":"2026-10-13T04:57:40.954Z","started_at":null,"ended_at":null,"updated_at":"2026-10-13T04:57:40.954Z","heartbeat_at":null,"cancel_requested_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_message":null,"suspend_requested_at":null,"suspended_by":null,"queued_ms":null,"run_ms":null,"wait_ms":null,"usage":null,"rerun_of":null,"labels":{"namespace":"docs-samples","name":"sample-run-1791867412840-b05e8a"}},"specversion":"1.0","id":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwxXQ==","cursor":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwxXQ==","seq":1,"source":"/automation/v1/runs/run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","time":"2026-10-13T04:57:40.954Z"}

id: WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwyXQ==
event: ai.praxis.automation.run.status
data: {"type":"ai.praxis.automation.run.status","data":{"id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","kind":"script","number":null,"definition":null,"target":null,"resolved_version":null,"source_digest":"7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d","language":"ts","status":"running","progress":null,"current_wait":null,"counters":{"calls":0,"action_calls":0,"child_runs":0,"tasks_completed":0,"tasks_total":null},"input":{"n":41},"output":null,"error":null,"initiator":{"type":"api_key","id":"key_3e00b8984967"},"channel":"api","owner":"tnt_3a9759864ccb4e00","trigger":null,"parent":null,"parent_run_id":null,"root_run_id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","depth":0,"attach":null,"deadline_at":"2026-10-13T05:02:40.954Z","created_at":"2026-10-13T04:57:40.954Z","started_at":"2026-10-13T04:57:42.283Z","ended_at":null,"updated_at":"2026-10-13T04:57:42.283Z","heartbeat_at":"2026-10-13T04:57:42.283Z","cancel_requested_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_message":null,"suspend_requested_at":null,"suspended_by":null,"queued_ms":1329,"run_ms":null,"wait_ms":null,"usage":null,"rerun_of":null,"labels":{"namespace":"docs-samples","name":"sample-run-1791867412840-b05e8a"}},"specversion":"1.0","id":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwyXQ==","cursor":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwyXQ==","seq":2,"source":"/automation/v1/runs/run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","time":"2026-10-13T04:57:42.283Z"}

id: WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwzXQ==
event: ai.praxis.automation.run.status
data: {"type":"ai.praxis.automation.run.status","data":{"id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","kind":"script","number":null,"definition":null,"target":null,"resolved_version":null,"source_digest":"7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d","language":"ts","status":"completed","progress":null,"current_wait":null,"counters":{"calls":0,"action_calls":0,"child_runs":0,"tasks_completed":0,"tasks_total":null},"input":{"n":41},"output":{"answer":42},"error":null,"initiator":{"type":"api_key","id":"key_3e00b8984967"},"channel":"api","owner":"tnt_3a9759864ccb4e00","trigger":null,"parent":null,"parent_run_id":null,"root_run_id":"run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","depth":0,"attach":null,"deadline_at":"2026-10-13T05:02:40.954Z","created_at":"2026-10-13T04:57:40.954Z","started_at":"2026-10-13T04:57:42.283Z","ended_at":"2026-10-13T04:57:42.367Z","updated_at":"2026-10-13T04:57:42.367Z","heartbeat_at":"2026-10-13T04:57:42.283Z","cancel_requested_at":null,"cancelled_by":null,"cancel_reason":null,"cancel_message":null,"suspend_requested_at":null,"suspended_by":null,"queued_ms":1329,"run_ms":84,"wait_ms":null,"usage":null,"rerun_of":null,"labels":{"namespace":"docs-samples","name":"sample-run-1791867412840-b05e8a"}},"specversion":"1.0","id":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwzXQ==","cursor":"WyJydW5fMDBtdjY3bWRsbTVkNWQ3MDdjZDAzMTc0NGU4NDM3ZjY3ZjZhY2YwMmFmYWFiZDE4ZTc2YmY4ZGI5ZDY3NDMzM2RlNmYxZmIyZjE6ZXZlbnRzIiwzXQ==","seq":3,"source":"/automation/v1/runs/run_00mv67mdlm5d5d707cd031744e8437f67f6acf02afaabd18e76bf8db9d674333de6f1fb2f1","time":"2026-10-13T04:57:42.367Z"}

event: end
data: {}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取运行日志

默认返回保留期内的日志页，保留期为 30 天；Accept: text/event-stream 开启实时流，日志帧为 event: log。id 为续传游标，Last-Event-ID 优先于 cursor；每 20 秒发送 : ping，运行终态后以 event: end 收尾。

GET /automation/v1/runs/{id}/logs

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。
query: limitinteger可选；运行台账每页条数，整数 1–200，默认 50；其它集合上限为 100。 minimum: 1；maximum: 200
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
header: Accept"application/json" / "text/event-stream"可选；application/json（默认）读取账本页；text/event-stream 订阅实时流。
header: Last-Event-IDstring可选；SSE 续传游标，读取该事件之后的记录；优先于 cursor，仅用于实时流。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/logs" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Accept: text/event-stream"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
for await (const event of automation.runs.logs({
  "path": {
    "id": env("RUN_ID")
  }
})) {
  console.log(event);
}

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的日志行（LogLine），按时间顺序排列。
data[].cursorstring必填 / 必有；该行的游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data[].tsstring必填 / 必有；日志产生的时间（RFC 3339 UTC）。
data[].level"debug" / "info" / "warn" / "error"必填 / 必有；日志级别。debug 调试信息；info 一般信息；warn 警告；error 错误。
data[].messagestring必填 / 必有；日志文本。
next_cursornull / string必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

text/event-stream

字段类型说明
idstring可选；Resume cursor of this entry; send it back as Last-Event-ID, or as cursor on the JSON form, to continue after it. Absent on the end event.
event"log" / "end"必填 / 必有；SSE event name: log carries one log line in data; end is sent once when the run has reached a terminal status and closes the stream.
dataobject / object必填 / 必有；Decoded JSON of one log line; for the end event, an empty object.
data（分支1).cursorstring必填 / 必有；该行的游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
data（分支1).tsstring必填 / 必有；日志产生的时间（RFC 3339 UTC）。
data（分支1).level"debug" / "info" / "warn" / "error"必填 / 必有；日志级别。debug 调试信息；info 一般信息；warn 警告；error 错误。
data（分支1).messagestring必填 / 必有；日志文本。
（分支1).event"log"可选；SSE event name: log, one log line is carried in data.
（分支1).dataobject可选；运行产生的一行日志，保留 30 天。 不接受额外字段。
（分支1).data.cursorstring必填 / 必有；该行的游标；用作 cursor 翻页，或在 SSE 中作为 Last-Event-ID 续传。
（分支1).data.tsstring必填 / 必有；日志产生的时间（RFC 3339 UTC）。
（分支1).data.level"debug" / "info" / "warn" / "error"必填 / 必有；日志级别。debug 调试信息；info 一般信息；warn 警告；error 错误。
（分支1).data.messagestring必填 / 必有；日志文本。
（分支2).event"end"可选；SSE event name end: sent once when the run has reached a terminal status, and the stream then closes.
（分支2).dataobject可选；Always an empty object for the end event.

实测响应

HTTP 200

event: end
data: {}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取运行源码

读取运行实际使用的源码及摘要。结果包括语言与 SHA-256 摘要，适用于临时运行及已发布定义的运行。

GET /automation/v1/runs/{id}/source

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；运行 ID（run_）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
RUN_ID运行 id；暂停和恢复仅工作流；取消需非终态运行
: "${RUN_ID:?Set RUN_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/runs/${RUN_ID}/source" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.runs.retrieveSource({
  "path": {
    "id": env("RUN_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
language"ts" / "yaml"必填 / 必有；源码语言。ts 表示 TypeScript 脚本；yaml 表示工作流 YAML。
sourcestring必填 / 必有；运行时使用的完整源码（ts 或 yaml）。
sha256string必填 / 必有；源码的 SHA-256 摘要，可作为发布时的 expected_source_sha256。

实测响应

HTTP 200

{
  "language": "ts",
  "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });",
  "sha256": "7ae6678882a4ef2ea96e401c105d5c6ef512917cd72a9235289d2a3bf1f1b49d"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404RUN_NOT_FOUND：运行不存在或当前租户不可见。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出触发器

分页列出租户触发器，可按目标、类型和状态筛选；ns/name 匹配该目标的所有标签或版本，ns/name@spec 精确匹配。

GET /automation/v1/triggers

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
query: limitinteger可选；每页条数，整数 1–100，默认 25。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: targetstring[]可选；ns/name 匹配该目标的所有版本或标签；ns/name@spec 精确匹配已存的引用。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: kind"schedule" / "webhook"[]可选；schedule 或 webhook；省略返回两者。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: state"enabled" / "paused" / "expired"[]可选；触发器状态：enabled、paused 或 expired；省略不过滤。 多个值以逗号分隔，匹配任一值。 minItems: 1
query: labelsobject可选；按标签过滤，使用 labels[k]=v；同键逗号多值取任一，不同键同时满足。
query: created_at[gte]string可选；创建时间下界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"
query: created_at[lte]string可选；创建时间上界，包含边界；使用带时区的 ISO 8601 时间。 format: "date-time"

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TARGET已发布的 docs-samples/name@1.0.0
: "${TARGET:?Set TARGET}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/triggers" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  --get \
  --data-urlencode "target=${TARGET}"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.list({
  "query": {
    "target": [
      env("TARGET")
    ]
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的触发器，按 created_at 倒序、id 倒序排列。
data[].namestring必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100
data[].descriptionstring必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000
data[].labelsobject必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。
data[].targetstring必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。
data[].inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
data[].input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
data[].kind"schedule" / "webhook"必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。
data[].scheduleobject / object / object / null必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。
data[].schedule（分支1)（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
data[].schedule（分支1)（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
data[].schedule（分支1)（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
data[].schedule（分支1)（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
data[].schedule（分支1)（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
data[].schedule（分支1)（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
data[].schedule（分支1)（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
data[].schedule（分支1)（分支3).atstring必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time"
data[].timezonestring必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC"
data[].start_atstring / null必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。
data[].end_atstring / null必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。
data[].overlap"skip" / "allow"必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip"
data[].catchup_window_secondsinteger必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0
data[].webhookobject / null必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。
data[].webhook（分支1).input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。
data[].webhook（分支1).url_hintstring必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。
data[].idstring必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。
data[].ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
data[].state"enabled" / "paused" / "expired"必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。
data[].source"api" / "definition"必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。
data[].created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
data[].created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
data[].created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
data[].created_by_user_idstring必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。
data[].next_fire_timesstring[]必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5
data[].last_firingobject / null必填 / 必有；最近一次触发记录；从未触发为 null。
data[].last_firing（分支1).idstring必填 / 必有；触发记录 ID；记录保留 30 天。
data[].last_firing（分支1).trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
data[].last_firing（分支1).scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
data[].last_firing（分支1).fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
data[].last_firing（分支1).outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
data[].last_firing（分支1).run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
data[].last_firing（分支1).resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
data[].last_firing（分支1).errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
data[].last_firing（分支1).error（分支1).codestring必填 / 必有；失败的错误码。
data[].last_firing（分支1).error（分支1).messagestring必填 / 必有；失败的说明文字。
data[].countsobject必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。
data[].counts.startedinteger必填 / 必有；成功启动运行的次数。 minimum: 0
data[].counts.skippedinteger必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0
data[].counts.missedinteger必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0
data[].counts.failedinteger必填 / 必有；创建运行失败的次数。 minimum: 0
data[].created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time"
data[].updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time"
data[].etagstring必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。
data[].usage_30dobject / null可选；仅 GET /triggers/{id} 返回，列表省略。最近 30 天由此触发器启动的运行及子运行的归因实扣。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
data[].usage_30d（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
data[].usage_30d（分支1).coststring必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
data[].usage_30d（分支1).pending_eventsinteger必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0
next_cursorstring / null必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
      "owner": "tnt_3a9759864ccb4e00",
      "name": "sample-webhook-1791867412840-b05e8a",
      "description": "",
      "labels": {
        "namespace": "docs-samples"
      },
      "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
      "input": {},
      "kind": "webhook",
      "schedule": null,
      "timezone": "UTC",
      "start_at": null,
      "end_at": null,
      "overlap": "skip",
      "catchup_window_seconds": 300,
      "webhook": {
        "input_mode": "body",
        "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
      },
      "state": "paused",
      "source": "api",
      "created_by": {
        "type": "api_key",
        "id": "key_3e00b8984967"
      },
      "created_by_user_id": "usr_49d4fcb99517",
      "next_fire_times": [],
      "last_firing": null,
      "counts": {
        "started": 0,
        "skipped": 0,
        "missed": 0,
        "failed": 0
      },
      "created_at": "2026-10-13T04:58:09.974Z",
      "updated_at": "2026-10-13T04:58:12.519Z",
      "etag": "etag_00mv67n1yf40e7b8d39ce5459d9ce835bfb1083701"
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

创建触发器

为已发布脚本或工作流创建定时或 webhook 触发器，每租户最多 100 个启用中的触发器。目标只接受精确版本或标签，webhook_url 仅在创建 webhook 或轮换时返回，须妥善保存。

POST /automation/v1/triggers

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

application/json

不接受额外字段。

字段类型说明
namestring必填 / 必有；触发器显示名，1–100 字符且不能全为空白；不要求唯一。 minLength: 1；maxLength: 100
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
labelsobject可选；最多 64 个用户标签，禁止 praxis. 前缀；内部标签不占用名额。键 1–40 字符、值最多 500 字符。
targetstring必填 / 必有；ns/name@tag 或 ns/name@version，省略 @ 时用 latest；触发器不接受版本范围。
inputnull / string / number / boolean / object / null / string / number / boolean / object / JSON[][]可选；定时触发的静态 JSON 输入，默认 {}；创建与修改时校验目标契约。webhook 未显式提供时不在创建阶段校验回调输入。
input（分支5).*（分支5)object递归 JSON 值。
input（分支5).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；schedule 按计划触发，webhook 由 HTTP 回调触发；创建后不可更改。
scheduleobject / object / object可选；三选一：cron 为五段表达式（支持 L/W/#）；every 为 ISO 8601 时长或时长对象，须为正整数毫秒且在 1 分钟至 366 天之间；at 为未来一年内的一次性 RFC 3339 时间。
schedule（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支3).atstring必填 / 必有；一次性触发时刻，需带 Z 或 ±HH:MM 时区；必须在请求时刻至一年后之间。调用时将示例替换为该范围内的未来时间。 pattern: "(Z|[+-]\d\d:\d\d)$"；format: "date-time"
timezonestring可选；IANA 时区，默认 UTC；夏令时跳过不存在的时刻，重复时刻只触发一次。 default: "UTC"
start_atstring / null可选；可选开始时间，RFC 3339 且带时区；null 表示不设下界。
end_atstring / null可选；可选结束时间，RFC 3339 且带时区；不能早于 start_at，null 表示不设上界。
overlap"skip" / "allow"可选；skip（默认）在前次运行未结束时跳过，allow 允许并行触发。 default: "skip"
catchup_window_secondsinteger可选；非负整数秒，默认 300；仅对定时触发器生效；延迟超过窗口时记为 missed，不补跑，webhook 不受此窗口影响。 default: 300；minimum: 0
webhookobject可选；input_mode 为 body（默认）或 envelope；后者包含 body、raw_body、raw_body_encoding、白名单 headers、webhook_id、received_at，完整 URL 仅创建或轮换时返回。 不接受额外字段。
webhook.input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。 default: "body"

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TARGET已发布的 docs-samples/name@1.0.0
: "${TARGET:?Set TARGET}"
BODY=$(jq -n --arg TARGET "$TARGET" '{
  "name": "sample-webhook",
  "target": $TARGET,
  "kind": "webhook",
  "labels": {
    "namespace": "docs-samples"
  },
  "webhook": {
    "input_mode": "body"
  }
}')
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data "$BODY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.create({
  "body": {
    "name": "sample-webhook",
    "target": env("TARGET"),
    "kind": "webhook",
    "labels": {
      "namespace": "docs-samples"
    },
    "webhook": {
      "input_mode": "body"
    }
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent resource revision for conditional updates.
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
namestring必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100
descriptionstring必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000
labelsobject必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。
targetstring必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。
scheduleobject / object / object / null必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。
schedule（分支1)（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支1)（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支1)（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支1)（分支3).atstring必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time"
timezonestring必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC"
start_atstring / null必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。
end_atstring / null必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。
overlap"skip" / "allow"必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip"
catchup_window_secondsinteger必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0
webhookobject / null必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。
webhook（分支1).input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。
webhook（分支1).url_hintstring必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。
idstring必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
state"enabled" / "paused" / "expired"必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。
source"api" / "definition"必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。
created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
created_by_user_idstring必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。
next_fire_timesstring[]必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5
last_firingobject / null必填 / 必有；最近一次触发记录；从未触发为 null。
last_firing（分支1).idstring必填 / 必有；触发记录 ID；记录保留 30 天。
last_firing（分支1).trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
last_firing（分支1).scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
last_firing（分支1).fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
last_firing（分支1).outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
last_firing（分支1).run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
last_firing（分支1).resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
last_firing（分支1).errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
last_firing（分支1).error（分支1).codestring必填 / 必有；失败的错误码。
last_firing（分支1).error（分支1).messagestring必填 / 必有；失败的说明文字。
countsobject必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。
counts.startedinteger必填 / 必有；成功启动运行的次数。 minimum: 0
counts.skippedinteger必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0
counts.missedinteger必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0
counts.failedinteger必填 / 必有；创建运行失败的次数。 minimum: 0
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time"
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time"
etagstring必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。
usage_30dobject / null可选；创建响应中恒为 null；近 30 天用量只在 GET /triggers/{id} 返回。
usage_30d（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage_30d（分支1).coststring必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage_30d（分支1).pending_eventsinteger必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0
webhook_urlstring可选；Returned only on webhook creation or rotation. format: "uri"

实测响应

HTTP 200

{
  "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "owner": "tnt_3a9759864ccb4e00",
  "name": "sample-webhook-1791867412840-b05e8a",
  "description": "",
  "labels": {
    "namespace": "docs-samples"
  },
  "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
  "input": {},
  "kind": "webhook",
  "schedule": null,
  "timezone": "UTC",
  "start_at": null,
  "end_at": null,
  "overlap": "skip",
  "catchup_window_seconds": 300,
  "webhook": {
    "input_mode": "body",
    "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
  },
  "state": "enabled",
  "source": "api",
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "created_by_user_id": "usr_49d4fcb99517",
  "next_fire_times": [],
  "last_firing": null,
  "counts": {
    "started": 0,
    "skipped": 0,
    "missed": 0,
    "failed": 0
  },
  "created_at": "2026-10-13T04:58:09.974Z",
  "updated_at": "2026-10-13T04:58:09.974Z",
  "etag": "etag_00mv67mzzqc6ef5487c69f4857b65b91dab497104c",
  "webhook_url": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/${WEBHOOK_TOKEN}"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 SCHEDULE_INVALID：定时规则或时间边界无效。 TIMEZONE_INVALID：时区不是有效的 IANA 时区。 INTERVAL_TOO_SHORT：定时间隔短于一分钟。 INPUT_INVALID：输入不满足目标契约或业务校验。
404TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。 NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。
429TRIGGER_LIMIT：租户已达到 100 个启用触发器的上限。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

读取触发器

读取规则、状态、未来触发时间与最近触发结果；ETag 可用于修改，完整 webhook URL 不会再次返回。

GET /automation/v1/triggers/{id}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.retrieve({
  "path": {
    "id": env("TRIGGER_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent resource revision for conditional updates.

application/json

字段类型说明
namestring必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100
descriptionstring必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000
labelsobject必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。
targetstring必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。
scheduleobject / object / object / null必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。
schedule（分支1)（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支1)（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支1)（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支1)（分支3).atstring必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time"
timezonestring必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC"
start_atstring / null必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。
end_atstring / null必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。
overlap"skip" / "allow"必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip"
catchup_window_secondsinteger必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0
webhookobject / null必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。
webhook（分支1).input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。
webhook（分支1).url_hintstring必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。
idstring必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
state"enabled" / "paused" / "expired"必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。
source"api" / "definition"必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。
created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
created_by_user_idstring必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。
next_fire_timesstring[]必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5
last_firingobject / null必填 / 必有；最近一次触发记录；从未触发为 null。
last_firing（分支1).idstring必填 / 必有；触发记录 ID；记录保留 30 天。
last_firing（分支1).trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
last_firing（分支1).scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
last_firing（分支1).fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
last_firing（分支1).outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
last_firing（分支1).run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
last_firing（分支1).resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
last_firing（分支1).errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
last_firing（分支1).error（分支1).codestring必填 / 必有；失败的错误码。
last_firing（分支1).error（分支1).messagestring必填 / 必有；失败的说明文字。
countsobject必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。
counts.startedinteger必填 / 必有；成功启动运行的次数。 minimum: 0
counts.skippedinteger必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0
counts.missedinteger必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0
counts.failedinteger必填 / 必有；创建运行失败的次数。 minimum: 0
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time"
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time"
etagstring必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。
usage_30dobject / null可选；仅 GET /triggers/{id} 返回，列表省略。最近 30 天由此触发器启动的运行及子运行的归因实扣。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage_30d（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage_30d（分支1).coststring必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage_30d（分支1).pending_eventsinteger必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0

实测响应

HTTP 200

{
  "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "owner": "tnt_3a9759864ccb4e00",
  "name": "sample-webhook-1791867412840-b05e8a",
  "description": "",
  "labels": {
    "namespace": "docs-samples"
  },
  "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
  "input": {},
  "kind": "webhook",
  "schedule": null,
  "timezone": "UTC",
  "start_at": null,
  "end_at": null,
  "overlap": "skip",
  "catchup_window_seconds": 300,
  "webhook": {
    "input_mode": "body",
    "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
  },
  "state": "paused",
  "source": "api",
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "created_by_user_id": "usr_49d4fcb99517",
  "next_fire_times": [],
  "last_firing": null,
  "counts": {
    "started": 0,
    "skipped": 0,
    "missed": 0,
    "failed": 0
  },
  "created_at": "2026-10-13T04:58:09.974Z",
  "updated_at": "2026-10-13T04:58:12.519Z",
  "etag": "etag_00mv67n1yf40e7b8d39ce5459d9ce835bfb1083701",
  "usage_30d": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

更新触发器

使用匹配当前 ETag 的 If-Match 修改配置，并重新校验目标输入与规则；kind 不可更改，由定义管理的触发器拒绝修改并返回 TRIGGER_MANAGED。

PATCH /automation/v1/triggers/{id}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。
header: If-Matchstring必填；当前资源的 ETag，可直接使用对象里的 draft.revision 或 etag 字段值：裸值、带双引号或弱校验写法 W/"…" 均接受（RFC 7232 弱比较）；缺失返回 400，修订不匹配返回 412。

application/json

不接受额外字段。

字段类型说明
namestring可选；触发器显示名，1–100 字符且不能全为空白；不要求唯一。 minLength: 1；maxLength: 100
descriptionstring可选；说明，最多 1000 个字符。 maxLength: 1000
labelsobject可选；最多 64 个用户标签，禁止 praxis. 前缀；内部标签不占用名额。键 1–40 字符、值最多 500 字符。
targetstring可选；ns/name@tag 或 ns/name@version，省略 @ 时用 latest；触发器不接受版本范围。
inputnull / string / number / boolean / object / null / string / number / boolean / object / JSON[][]可选；定时触发的静态 JSON 输入，默认 {}；创建与修改时校验目标契约。webhook 未显式提供时不在创建阶段校验回调输入。
input（分支5).*（分支5)object递归 JSON 值。
input（分支5).*（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"可选；schedule 按计划触发，webhook 由 HTTP 回调触发；创建后不可更改。
scheduleobject / object / object可选；三选一：cron 为五段表达式（支持 L/W/#）；every 为 ISO 8601 时长或时长对象，须为正整数毫秒且在 1 分钟至 366 天之间；at 为未来一年内的一次性 RFC 3339 时间。
schedule（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支3).atstring必填 / 必有；一次性触发时刻，需带 Z 或 ±HH:MM 时区；必须在请求时刻至一年后之间。调用时将示例替换为该范围内的未来时间。 pattern: "(Z|[+-]\d\d:\d\d)$"；format: "date-time"
timezonestring可选；IANA 时区，默认 UTC；夏令时跳过不存在的时刻，重复时刻只触发一次。 default: "UTC"
start_atstring / null可选；可选开始时间，RFC 3339 且带时区；null 表示不设下界。
end_atstring / null可选；可选结束时间，RFC 3339 且带时区；不能早于 start_at，null 表示不设上界。
overlap"skip" / "allow"可选；skip（默认）在前次运行未结束时跳过，allow 允许并行触发。 default: "skip"
catchup_window_secondsinteger可选；非负整数秒，默认 300；仅对定时触发器生效；延迟超过窗口时记为 missed，不补跑，webhook 不受此窗口影响。 default: 300；minimum: 0
webhookobject可选；input_mode 为 body（默认）或 envelope；后者包含 body、raw_body、raw_body_encoding、白名单 headers、webhook_id、received_at，完整 URL 仅创建或轮换时返回。 不接受额外字段。
webhook.input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。 default: "body"

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
ETAG最新 GET 响应头 ETag（保留引号）
: "${TRIGGER_ID:?Set TRIGGER_ID}"
: "${ETAG:?Set ETAG}"
curl --fail-with-body -X PATCH "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "If-Match: ${ETAG}" \
  -H "Content-Type: application/json" \
  --data '{
  "description": "Sample webhook",
  "input": {
    "n": 41
  }
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.update({
  "path": {
    "id": env("TRIGGER_ID")
  },
  "headers": {
    "If-Match": env("ETAG")
  },
  "body": {
    "description": "Sample webhook",
    "input": {
      "n": 41
    }
  }
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
ETagstringCurrent resource revision for conditional updates.

application/json

字段类型说明
namestring必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100
descriptionstring必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000
labelsobject必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。
targetstring必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。
scheduleobject / object / object / null必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。
schedule（分支1)（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支1)（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支1)（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支1)（分支3).atstring必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time"
timezonestring必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC"
start_atstring / null必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。
end_atstring / null必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。
overlap"skip" / "allow"必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip"
catchup_window_secondsinteger必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0
webhookobject / null必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。
webhook（分支1).input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。
webhook（分支1).url_hintstring必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。
idstring必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
state"enabled" / "paused" / "expired"必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。
source"api" / "definition"必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。
created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
created_by_user_idstring必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。
next_fire_timesstring[]必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5
last_firingobject / null必填 / 必有；最近一次触发记录；从未触发为 null。
last_firing（分支1).idstring必填 / 必有；触发记录 ID；记录保留 30 天。
last_firing（分支1).trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
last_firing（分支1).scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
last_firing（分支1).fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
last_firing（分支1).outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
last_firing（分支1).run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
last_firing（分支1).resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
last_firing（分支1).errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
last_firing（分支1).error（分支1).codestring必填 / 必有；失败的错误码。
last_firing（分支1).error（分支1).messagestring必填 / 必有；失败的说明文字。
countsobject必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。
counts.startedinteger必填 / 必有；成功启动运行的次数。 minimum: 0
counts.skippedinteger必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0
counts.missedinteger必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0
counts.failedinteger必填 / 必有；创建运行失败的次数。 minimum: 0
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time"
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time"
etagstring必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。
usage_30dobject / null可选；仅 GET /triggers/{id} 返回，列表省略。最近 30 天由此触发器启动的运行及子运行的归因实扣。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage_30d（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage_30d（分支1).coststring必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage_30d（分支1).pending_eventsinteger必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0

实测响应

HTTP 200

{
  "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "owner": "tnt_3a9759864ccb4e00",
  "name": "sample-webhook-1791867412840-b05e8a",
  "description": "Sample webhook",
  "labels": {
    "namespace": "docs-samples"
  },
  "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
  "input": {
    "n": 41
  },
  "kind": "webhook",
  "schedule": null,
  "timezone": "UTC",
  "start_at": null,
  "end_at": null,
  "overlap": "skip",
  "catchup_window_seconds": 300,
  "webhook": {
    "input_mode": "body",
    "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
  },
  "state": "paused",
  "source": "api",
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "created_by_user_id": "usr_49d4fcb99517",
  "next_fire_times": [],
  "last_firing": null,
  "counts": {
    "started": 0,
    "skipped": 0,
    "missed": 0,
    "failed": 0
  },
  "created_at": "2026-10-13T04:58:09.974Z",
  "updated_at": "2026-10-13T04:58:14.661Z",
  "etag": "etag_00mv67n3ib18c0371214b84064b86e9375320685fa"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 SCHEDULE_INVALID：定时规则或时间边界无效。 TIMEZONE_INVALID：时区不是有效的 IANA 时区。 INTERVAL_TOO_SHORT：定时间隔短于一分钟。 INPUT_INVALID：输入不满足目标契约或业务校验。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。 TARGET_NOT_FOUND：编排目标不存在或类型不匹配。 VERSION_NOT_FOUND：指定版本或修订不存在。
409TRIGGER_MANAGED：触发器由定义管理，不能直接修改。 TARGET_ARCHIVED：目标已归档，不能用于本操作；动作执行错误的 detail 包含 ns/name。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
422NO_MATCHING_VERSION：没有满足标签、版本或范围的已发布版本。
429TRIGGER_LIMIT：租户已达到 100 个启用触发器的上限。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

删除触发器

删除触发器及其触发历史，返回 204；已经启动的运行不受影响。由定义管理的触发器返回 409 TRIGGER_MANAGED，需在工作流定义里删除 schedule 后重新发布。

DELETE /automation/v1/triggers/{id}

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X DELETE "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.delete({
  "path": {
    "id": env("TRIGGER_ID")
  }
});
console.log(result);

响应

HTTP 204

Deleted

实测响应

HTTP 204

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
409TRIGGER_MANAGED：触发器由定义管理，不能直接修改。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

暂停触发器

暂停后停止新触发，不终止已经启动的运行；由定义管理的触发器也可以暂停。

POST /automation/v1/triggers/{id}/pause

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/pause" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.pause({
  "path": {
    "id": env("TRIGGER_ID")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
namestring必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100
descriptionstring必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000
labelsobject必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。
targetstring必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。
scheduleobject / object / object / null必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。
schedule（分支1)（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支1)（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支1)（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支1)（分支3).atstring必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time"
timezonestring必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC"
start_atstring / null必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。
end_atstring / null必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。
overlap"skip" / "allow"必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip"
catchup_window_secondsinteger必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0
webhookobject / null必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。
webhook（分支1).input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。
webhook（分支1).url_hintstring必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。
idstring必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
state"enabled" / "paused" / "expired"必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。
source"api" / "definition"必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。
created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
created_by_user_idstring必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。
next_fire_timesstring[]必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5
last_firingobject / null必填 / 必有；最近一次触发记录；从未触发为 null。
last_firing（分支1).idstring必填 / 必有；触发记录 ID；记录保留 30 天。
last_firing（分支1).trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
last_firing（分支1).scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
last_firing（分支1).fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
last_firing（分支1).outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
last_firing（分支1).run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
last_firing（分支1).resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
last_firing（分支1).errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
last_firing（分支1).error（分支1).codestring必填 / 必有；失败的错误码。
last_firing（分支1).error（分支1).messagestring必填 / 必有；失败的说明文字。
countsobject必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。
counts.startedinteger必填 / 必有；成功启动运行的次数。 minimum: 0
counts.skippedinteger必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0
counts.missedinteger必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0
counts.failedinteger必填 / 必有；创建运行失败的次数。 minimum: 0
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time"
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time"
etagstring必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。
usage_30dobject / null可选；仅 GET /triggers/{id} 返回，列表省略。最近 30 天由此触发器启动的运行及子运行的归因实扣。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage_30d（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage_30d（分支1).coststring必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage_30d（分支1).pending_eventsinteger必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0

实测响应

HTTP 200

{
  "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "owner": "tnt_3a9759864ccb4e00",
  "name": "sample-webhook-1791867412840-b05e8a",
  "description": "",
  "labels": {
    "namespace": "docs-samples"
  },
  "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
  "input": {},
  "kind": "webhook",
  "schedule": null,
  "timezone": "UTC",
  "start_at": null,
  "end_at": null,
  "overlap": "skip",
  "catchup_window_seconds": 300,
  "webhook": {
    "input_mode": "body",
    "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
  },
  "state": "paused",
  "source": "api",
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "created_by_user_id": "usr_49d4fcb99517",
  "next_fire_times": [],
  "last_firing": null,
  "counts": {
    "started": 0,
    "skipped": 0,
    "missed": 0,
    "failed": 0
  },
  "created_at": "2026-10-13T04:58:09.974Z",
  "updated_at": "2026-10-13T04:58:12.519Z",
  "etag": "etag_00mv67n1yf40e7b8d39ce5459d9ce835bfb1083701"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

恢复触发器

恢复触发并清空连续失败计数；已过结束时间或已执行完的一次性触发器保持 expired，启用配额已满时返回 TRIGGER_LIMIT。

POST /automation/v1/triggers/{id}/resume

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/resume" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.resume({
  "path": {
    "id": env("TRIGGER_ID")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
namestring必填 / 必有；触发器名称，1–100 字符。 minLength: 1；maxLength: 100
descriptionstring必填 / 必有；触发器说明，最多 1000 字符。 maxLength: 1000
labelsobject必填 / 必有；触发器标签：字符串键值对，最多 64 个；键不能以保留前缀 praxis. 开头，违反返回 400 INPUT_INVALID。
targetstring必填 / 必有；要运行的脚本或工作流引用，形如 ns/name@标签或版本；默认跟随 latest，写成 @1.2.0 则钉死版本。
inputnull / string / number / boolean / object / JSON[]必填 / 必有；任意 JSON 值：null、布尔、数字、字符串、数组或对象。
input（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
input（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。
kind"schedule" / "webhook"必填 / 必有；触发器类型。schedule 按计划（cron、every 或 at）触发；webhook 由入站 HTTP 请求触发。
scheduleobject / object / object / null必填 / 必有；定时规则，kind=schedule 时有值（cron、every 或 at 三选一）；webhook 为 null。
schedule（分支1)（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支1)（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支1)（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支1)（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支1)（分支3).atstring必填 / 必有；一次性触发的时刻（RFC 3339 UTC）；不能早于当前时间，也不能晚于一年后。执行后触发器进入 expired。 format: "date-time"
timezonestring必填 / 必有；IANA 时区名，定时规则按它解释；API 缺省为 UTC。 default: "UTC"
start_atstring / null必填 / 必有；定时触发器的开始时间（RFC 3339 UTC）；此前不触发。没有限制为 null。
end_atstring / null必填 / 必有；定时触发器的结束时间（RFC 3339 UTC）；超过后进入 expired。没有期限为 null。
overlap"skip" / "allow"必填 / 必有；重叠策略：上一次运行未结束时又到点，skip（默认）跳过，allow 照常启动。 default: "skip"
catchup_window_secondsinteger必填 / 必有；补跑窗口（秒），默认 300，仅定时触发器适用：到点时若已延迟超过该值（宕机、暂停期间），记为 missed 且不补跑。 default: 300；minimum: 0
webhookobject / null必填 / 必有；webhook 设置，kind=webhook 时有值；schedule 触发器为 null。
webhook（分支1).input_mode"body" / "envelope"必填 / 必有；webhook 触发时传给目标的输入形态。body（默认）只传请求体；envelope 传含 body、raw_body、raw_body_encoding、headers、webhook_id、received_at 的信封对象。
webhook（分支1).url_hintstring必填 / 必有；webhook 地址的掩码提示，省略号代替私密 token，不能用于调用。新建触发器为公开完整 URL；历史记录可能为 /automation/v1/hooks/{id}/… 相对路径。
idstring必填 / 必有；触发器 ID，前缀 trg_；用于 webhook 地址以及触发器的所有接口。
ownerstring必填 / 必有；所属租户，由网关注入；按不透明字符串处理。
state"enabled" / "paused" / "expired"必填 / 必有；触发器状态。enabled 启用，会按计划或请求触发；paused 已暂停，不触发；expired 已到期，一次性触发器执行完或超过 end_at 后进入，不再触发。
source"api" / "definition"必填 / 必有；触发器来源。api 为通过 API 创建，可修改和删除；definition 为由工作流 YAML 的 schedule 生成，只能暂停或恢复，修改返回 409 TRIGGER_MANAGED。
created_byobject必填 / 必有；网关注入的主体 {type, id}，表示谁发起或操作；本服务不解析名字，名字由控制台批量解析。 不接受额外字段。
created_by.type"user" / "api_key" / "agent" / "run" / "trigger"必填 / 必有；主体类型。user 为登录用户；api_key 为平台 API Key；agent 为智能体；run 为由运行本身（例如父运行）执行的操作；trigger 为触发器。
created_by.idstring必填 / 必有；主体标识，含义随 type 而定：用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID；按不透明字符串处理。
created_by_user_idstring必填 / 必有；创建者的真实用户 ID，由网关转发；触发器启动的运行以该用户身份取令牌，用于审计与用量归属。
next_fire_timesstring[]必填 / 必有；接下来最多 5 次的触发时间（RFC 3339 UTC）；webhook、已暂停或已到期的触发器为空数组。 maxItems: 5
last_firingobject / null必填 / 必有；最近一次触发记录；从未触发为 null。
last_firing（分支1).idstring必填 / 必有；触发记录 ID；记录保留 30 天。
last_firing（分支1).trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
last_firing（分支1).scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
last_firing（分支1).fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
last_firing（分支1).outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
last_firing（分支1).run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
last_firing（分支1).resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
last_firing（分支1).errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
last_firing（分支1).error（分支1).codestring必填 / 必有；失败的错误码。
last_firing（分支1).error（分支1).messagestring必填 / 必有；失败的说明文字。
countsobject必填 / 必有；触发结果累计次数 {started, skipped, missed, failed}。 不接受额外字段。
counts.startedinteger必填 / 必有；成功启动运行的次数。 minimum: 0
counts.skippedinteger必填 / 必有；因重叠策略为 skip 且上一次运行未结束而跳过的次数。 minimum: 0
counts.missedinteger必填 / 必有；因延迟超过补跑窗口而错过的次数。 minimum: 0
counts.failedinteger必填 / 必有；创建运行失败的次数。 minimum: 0
created_atstring必填 / 必有；创建时间（RFC 3339 UTC）。 format: "date-time"
updated_atstring必填 / 必有；最近一次更新的时间（RFC 3339 UTC）。 format: "date-time"
etagstring必填 / 必有；触发器当前修订标识，更新时作为 If-Match；不匹配返回 412。
usage_30dobject / null可选；仅 GET /triggers/{id} 返回，列表省略。最近 30 天由此触发器启动的运行及子运行的归因实扣。运行本身不收费；这里是运行中调用模型、搜索等能力产生的实扣，按调用归因；未评级的用量稍后计入。汇总超时（1.5 秒）或失败时为 null，详情仍返回 200。
usage_30d（分支1).currency"USD"必填 / 必有；金额币种，固定为 USD。
usage_30d（分支1).coststring必填 / 必有；已评级实扣的美元十进制字符串，精确到 6 位小数；没有用量时为 0.000000。 pattern: "^[0-9]+\.[0-9]{6}$"
usage_30d（分支1).pending_eventsinteger必填 / 必有；尚未评级的用量事件数，金额稍后才计入。 minimum: 0

实测响应

HTTP 200

{
  "id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "owner": "tnt_3a9759864ccb4e00",
  "name": "sample-webhook-1791867412840-b05e8a",
  "description": "Sample webhook",
  "labels": {
    "namespace": "docs-samples"
  },
  "target": "docs-samples/sample-scripts-1791867412840-b05e8a@1.0.0",
  "input": {
    "n": 41
  },
  "kind": "webhook",
  "schedule": null,
  "timezone": "UTC",
  "start_at": null,
  "end_at": null,
  "overlap": "skip",
  "catchup_window_seconds": 300,
  "webhook": {
    "input_mode": "body",
    "url_hint": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/…"
  },
  "state": "enabled",
  "source": "api",
  "created_by": {
    "type": "api_key",
    "id": "key_3e00b8984967"
  },
  "created_by_user_id": "usr_49d4fcb99517",
  "next_fire_times": [],
  "last_firing": null,
  "counts": {
    "started": 0,
    "skipped": 0,
    "missed": 0,
    "failed": 0
  },
  "created_at": "2026-10-13T04:58:09.974Z",
  "updated_at": "2026-10-13T04:58:17.058Z",
  "etag": "etag_00mv67n5gidea13751125d4ad292fb95b07fac032e"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
429TRIGGER_LIMIT：租户已达到 100 个启用触发器的上限。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

立即触发

立即触发一次并返回 Firing，仍受当前状态、补跑窗口和 overlap 约束；启动失败记在触发结果的 error 中。

POST /automation/v1/triggers/{id}/fire

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。
header: Idempotency-Keystring可选；可选；1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true；同 key 不同请求体返回 422；处理中返回 409。 minLength: 1；maxLength: 256

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/fire" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.fire({
  "path": {
    "id": env("TRIGGER_ID")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

响应头类型说明
Idempotent-ReplayedbooleanPresent and true when replaying the first response for this key.

application/json

字段类型说明
idstring必填 / 必有；触发记录 ID；记录保留 30 天。
trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
error（分支1).codestring必填 / 必有；失败的错误码。
error（分支1).messagestring必填 / 必有；失败的说明文字。

实测响应

HTTP 200

{
  "id": "frg_00mv67n833fec8a47a90904782ac1a8f1fef264379",
  "trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "scheduled_at": "2026-10-13T04:58:20.215Z",
  "fired_at": "2026-10-13T04:58:20.215Z",
  "outcome": "started",
  "run_id": "run_00mv67n8ao7de994212f453fdfe7def756b57ec5cdeb562a1222f554c6f3d9f428ec25480e",
  "resolved_version": "1.0.0",
  "error": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
409IDEMPOTENCY_IN_FLIGHT：同一幂等键的请求仍在处理中。 RUN_INVALID_STATE：当前状态不允许执行该动作。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
422IDEMPOTENCY_KEY_MISMATCH：同一幂等键已用于不同请求内容。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

轮换回调地址

仅适用于 webhook 触发器：立即作废旧 token，返回新的完整 webhook_url；之后的详情读取不会再次显示完整地址。

POST /automation/v1/triggers/{id}/rotate-webhook

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/rotate-webhook" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.rotateWebhook({
  "path": {
    "id": env("TRIGGER_ID")
  },
  "body": {}
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
webhook_urlstring必填 / 必有；新的完整 webhook 地址，含私密 token；只返回这一次，请妥善保存，丢失后需再次轮换。旧地址立即失效。 format: "uri"

实测响应

HTTP 200

{
  "webhook_url": "https://api-develop.deepraxis.ai/automation/v1/hooks/trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e/${WEBHOOK_TOKEN}"
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

列出触发历史

按时间倒序读取最近 30 天的触发记录。结果包括实际版本、运行 ID 与失败原因。

GET /automation/v1/triggers/{id}/firings

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
path: idstring必填；触发器 ID（trg_）。
query: limitinteger可选；每页条数，整数 1–100，默认 25。 minimum: 1；maximum: 100
query: cursorstring可选；上一页返回的 next_cursor，不透明字符串；保持原查询条件继续翻页。
query: outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"[]可选；按结果筛选，多个值用逗号分隔（OR）；与 run_id 同时提供时取交集。
query: run_idstring可选；仅返回关联此运行 ID 的记录。

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
: "${TRIGGER_ID:?Set TRIGGER_ID}"
curl --fail-with-body -X GET "https://api.deepraxis.ai/automation/v1/triggers/${TRIGGER_ID}/firings" \
  -H "Authorization: Bearer $PRAXIS_API_KEY"
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.firings.list({
  "path": {
    "id": env("TRIGGER_ID")
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
dataobject[]必填 / 必有；本页的最近 30 天的触发记录，按 created_at 倒序、id 倒序排列。
data[].idstring必填 / 必有；触发记录 ID；记录保留 30 天。
data[].trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
data[].scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
data[].fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
data[].outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
data[].run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
data[].resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
data[].errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
data[].error（分支1).codestring必填 / 必有；失败的错误码。
data[].error（分支1).messagestring必填 / 必有；失败的说明文字。
next_cursorstring / null必填 / 必有；下一页游标，原样传给 cursor 参数并保持原查询条件；没有更多页为 null。接口不返回总数。

实测响应

HTTP 200

{
  "data": [
    {
      "id": "frg_00mv67n833fec8a47a90904782ac1a8f1fef264379",
      "trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
      "scheduled_at": "2026-10-13T04:58:20.215Z",
      "fired_at": "2026-10-13T04:58:20.215Z",
      "outcome": "started",
      "run_id": "run_00mv67n8ao7de994212f453fdfe7def756b57ec5cdeb562a1222f554c6f3d9f428ec25480e",
      "resolved_version": "1.0.0",
      "error": null
    },
    {
      "id": "frg_00mv67n6in516077a64cfc4102a4da939476a3fa78",
      "trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
      "scheduled_at": "2026-10-13T04:58:18.384Z",
      "fired_at": "2026-10-13T04:58:18.384Z",
      "outcome": "started",
      "run_id": "run_00mv67n6vvebb47a96bf4b54630d8a07786ec923a68d3b722c2f7ffca4e0a553053c4a5421",
      "resolved_version": "1.0.0",
      "error": null
    }
  ],
  "next_cursor": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

预览触发时间

校验规则与时区并预览未来触发时间。返回人读说明及最多五个未来时间，不会创建触发器或运行。

POST /automation/v1/triggers/preview

鉴权

Authorization: Bearer $PRAXIS_API_KEY

请求字段

参数类型说明
header: Accept-Languagestring可选；人读描述的语言，支持中文（默认）与英文，按语言权重选择。

application/json

不接受额外字段。

字段类型说明
scheduleobject / object / object必填 / 必有；三选一：cron 为五段表达式（支持 L/W/#）；every 至少一分钟；at 为带时区的一次性时间。与创建使用相同校验：at 须在当前时间至一年后之间；every 须为正整数毫秒且不超过 366 天。
schedule（分支1).cronstring必填 / 必有；Five fields; supports L, W, #. DST gaps skip the day and overlaps run once.
schedule（分支2).everystring / object必填 / 必有；时长：ISO 8601 字符串（如 PT5M），或 {days, hours, minutes, seconds, milliseconds} 对象；折算后必须是 60000 至 31622400000 毫秒（1 分钟至 366 天）的整数毫秒。
schedule（分支2).every（分支2).daysinteger可选；天数，非负整数。 minimum: 0
schedule（分支2).every（分支2).hoursinteger可选；小时数，非负整数。 minimum: 0
schedule（分支2).every（分支2).minutesinteger可选；分钟数，非负整数。 minimum: 0
schedule（分支2).every（分支2).secondsinteger可选；秒数，非负整数。 minimum: 0
schedule（分支2).every（分支2).millisecondsinteger可选；毫秒数，非负整数。 minimum: 0
schedule（分支3).atstring必填 / 必有；一次性触发时刻，需带 Z 或 ±HH:MM 时区；必须在请求时刻至一年后之间。调用时将示例替换为该范围内的未来时间。 pattern: "(Z|[+-]\d\d:\d\d)$"；format: "date-time"
timezonestring可选；IANA 时区，默认 UTC；夏令时跳过不存在的时刻，重复时刻只触发一次。

示例

SDK 安装与示例环境

curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/triggers/preview" \
  -H "Authorization: Bearer $PRAXIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "schedule": {
    "cron": "0 9 * * *"
  },
  "timezone": "UTC"
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: env('PRAXIS_API_KEY'),
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.triggers.preview({
  "body": {
    "schedule": {
      "cron": "0 9 * * *"
    },
    "timezone": "UTC"
  }
});
console.log(result);

响应

HTTP 200

Success

application/json

字段类型说明
descriptionstring必填 / 必有；规则的人读描述；常见 cron 为自然语言，其余回显表达式。语言由 Accept-Language 决定，默认中文。
next_fire_timesstring[]必填 / 必有；按该规则和时区计算的接下来最多 5 次触发时间（RFC 3339 UTC）。 maxItems: 5

实测响应

HTTP 200

{
  "description": "每天 09:00 · UTC",
  "next_fire_times": [
    "2026-10-13T09:00:00.000Z",
    "2026-10-14T09:00:00.000Z",
    "2026-10-15T09:00:00.000Z",
    "2026-10-16T09:00:00.000Z",
    "2026-10-17T09:00:00.000Z"
  ]
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 SCHEDULE_INVALID：定时规则或时间边界无效。 TIMEZONE_INVALID：时区不是有效的 IANA 时区。 INTERVAL_TOO_SHORT：定时间隔短于一分钟。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。

接收入站回调

无需 API Key，以 URL 中 token 鉴权；token 错误、触发器不存在、类型不符或不在时间窗口内均返回 404；触发器处于暂停状态（连续 5 次失败熔断或人工暂停）返回 409 TRIGGER_PAUSED，message 说明原因，hint 给出恢复办法 POST /automation/v1/triggers/{id}/resume。原始请求体上限 512 KiB；组装后的运行输入（含原文与解析后的副本）序列化后最多 1 MiB，超限同步返回 413，不创建触发记录；webhook-id 去重 24 小时。202 的 outcome=accepted 表示已受理，最终结果随后更新，重复请求为 deduped。JSON 解析失败时 body 为 null；其它 UTF-8 为原文，非 UTF-8 为 base64。envelope 包含 body、raw_body、raw_body_encoding、白名单 headers、webhook_id 和 received_at；raw_body 保留原始字节，raw_body_encoding 为 utf8 或 base64，可用于自行验签。

POST /automation/v1/hooks/{trigger_id}/{token}

鉴权

使用创建或轮换时返回的 webhook URL；路径中的 token 是凭据，无需 Bearer Key。

请求字段

参数类型说明
path: trigger_idstring必填；触发器 ID（trg_）。
path: tokenstring必填；创建或轮换时返回的私密 URL token；请勿公开。
header: webhook-idstring可选；可选去重标识，同一触发器内保留 24 小时。

application/json

任意 JSON 值：null、布尔、数字、字符串、数组或对象。

字段类型说明
（分支5).*null / string / number / boolean / object / JSON[]递归 JSON 值。
（分支6)[]null / string / number / boolean / object / JSON[]递归 JSON 值。

text/plain

string

application/octet-stream

string

示例

SDK 安装与示例环境

先设置以下环境变量，使用你自己的资源：

变量来源
TRIGGER_ID触发器 id；webhook 调用前需恢复启用
WEBHOOK_TOKEN新 webhook_url 的最后一段；不要公开
: "${TRIGGER_ID:?Set TRIGGER_ID}"
: "${WEBHOOK_TOKEN:?Set WEBHOOK_TOKEN}"
curl --fail-with-body -X POST "https://api.deepraxis.ai/automation/v1/hooks/${TRIGGER_ID}/${WEBHOOK_TOKEN}" \
  -H "Content-Type: application/json" \
  --data '{
  "n": 41
}'
import { createAutomationClient } from '@deepraxis/sdk/automation';

function env(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name}`);
  return value;
}
const automation = createAutomationClient({
  apiKey: '',
  baseUrl: 'https://api.deepraxis.ai',
  maxRetries: 0,
  timeoutMs: 90_000,
});
const result = await automation.hooks.send({
  "path": {
    "trigger_id": env("TRIGGER_ID"),
    "token": env("WEBHOOK_TOKEN")
  },
  "body": {
    "n": 41
  }
});
console.log(result);

响应

HTTP 202

Success

application/json

字段类型说明
idstring必填 / 必有；触发记录 ID；记录保留 30 天。
trigger_idstring必填 / 必有；所属触发器 ID（trg_ 前缀）。
scheduled_atstring必填 / 必有；计划触发的时间（RFC 3339 UTC）；webhook 取请求到达时间。 format: "date-time"
fired_atstring必填 / 必有；实际触发的时间（RFC 3339 UTC）。 format: "date-time"
outcome"accepted" / "started" / "skipped_overlap" / "missed" / "failed" / "deduped"必填 / 必有；触发结果。accepted 已持久化等待处理；started 已创建运行；skipped_overlap 因上一次运行未结束而跳过；missed 到点时延迟超过补跑窗口，不补跑；failed 创建运行失败；deduped 与 24 小时内相同 webhook-id 的请求重复，已去重。
run_idstring / null必填 / 必有；本次触发创建的运行 ID（run_ 前缀）；未创建运行为 null。
resolved_versionstring / null必填 / 必有；本次触发实际解析到的精确版本号；尚未解析或失败时为 null。
errorobject / null必填 / 必有；触发失败时的原因 {code, message}；没有失败为 null。
error（分支1).codestring必填 / 必有；失败的错误码。
error（分支1).messagestring必填 / 必有；失败的说明文字。

实测响应

HTTP 202

{
  "id": "frg_00mv67n6in516077a64cfc4102a4da939476a3fa78",
  "trigger_id": "trg_00mv67mzzqa0d63b98d72446dd9d1331051a3e100e",
  "scheduled_at": "2026-10-13T04:58:18.384Z",
  "fired_at": "2026-10-13T04:58:18.384Z",
  "outcome": "accepted",
  "run_id": null,
  "resolved_version": null,
  "error": null
}

错误码

HTTP错误码与说明
400INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。
404TRIGGER_NOT_FOUND：触发器不存在或不可访问，回调鉴权失败也使用此错误。
405METHOD_NOT_ALLOWED：仅支持 POST；其它方法无需鉴权即返回 405，Allow 为 POST。
409TRIGGER_PAUSED：触发器处于暂停状态：连续 5 次触发失败触发熔断自动暂停，或被人工暂停；响应 message 说明原因，hint 给出恢复办法：恢复该触发器（triggers.resume）。
412PRECONDITION_FAILED：修订、源码摘要或并发写入条件不匹配。
413PAYLOAD_TOO_LARGE：请求内容超过本操作允许的大小。
defaultRFC 9457 automation problem. 429 includes Retry-After.

鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。