自动化
创建脚本
创建脚本及可编辑草稿,不会发布或启动运行。
创建脚本及可编辑草稿,不会发布或启动运行;脚本与工作流共用名称空间,同租户重名返回 NAME_TAKEN。
POST /automation/v1/scripts
鉴权
Authorization: Bearer $PRAXIS_API_KEY
请求字段
| 参数 | 类型 | 说明 |
|---|---|---|
| header: Idempotency-Key | string | 可选;可选;1–256 字符。24 小时内同一 key 重放首个响应并带 Idempotent-Replayed: true;同 key 不同请求体返回 422;处理中返回 409。 minLength: 1;maxLength: 256 |
application/json
不接受额外字段。
| 字段 | 类型 | 说明 |
|---|---|---|
| namespace | string | 必填 / 必有;命名空间,存储前转为小写,格式 [a-z0-9][a-z0-9.-]{0,63};praxis 只读。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| name | string | 必填 / 必有;名称,存储前转为小写,格式 [a-z0-9][a-z0-9.-]{0,63}。 pattern: "^[a-zA-Z0-9][a-zA-Z0-9.-]{0,63}$" |
| description | string | 可选;说明,最多 1000 个字符。 maxLength: 1000 |
| draft | string | 可选;可编辑源码;脚本为 TypeScript,工作流为 YAML。创建时省略为空字符串。 |
| labels | object | 可选;最多 50 个标签;键为 1–40 个字符,值最多 500 个字符。 |
示例
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 '@deepractice-ai/praxis-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-Replayed | boolean | Present and true when replaying the first response for this key. |
application/json
| 字段 | 类型 | 说明 |
|---|---|---|
| draft | object | 必填 / 必有;脚本或工作流的可编辑草稿;发布版本时以草稿或某次运行的源码为准。 不接受额外字段。 |
| draft.source | string | 必填 / 必有;草稿源码:脚本为 TypeScript,工作流为 YAML。 |
| draft.revision | string | 必填 / 必有;草稿修订标识(ETag),发布时作为 expected_draft_revision,更新草稿时作为 If-Match;与当前不一致返回 412。 |
| draft.updated_at | string | 必填 / 必有;草稿最近一次修改的时间(RFC 3339 UTC)。 |
| draft.updated_by | object | 必填 / 必有;网关注入的主体 {type, id},表示谁发起或操作;本服务不解析名字,名字由控制台批量解析。 不接受额外字段。 |
| draft.updated_by.type | "user" / "api_key" / "agent" / "run" / "trigger" | 必填 / 必有;主体类型。user 为登录用户;api_key 为平台 API Key;agent 为智能体;run 为由运行本身(例如父运行)执行的操作;trigger 为触发器。 |
| draft.updated_by.id | string | 必填 / 必有;主体标识,含义随 type 而定:用户 ID、API Key ID、智能体 ID、运行 ID 或触发器 ID;按不透明字符串处理。 |
| id | string | 必填 / 必有;编排 ID,脚本前缀 scr_,工作流前缀 wf_;日常使用 namespace 与 name。 |
| kind | "script" / "workflow" | 必填 / 必有;编排类型。script 为 TypeScript 脚本,一次执行;workflow 为 YAML 工作流,由步骤组成,可等待事件、定时器或子运行并可暂停。 |
| namespace | string | 必填 / 必有;命名空间,引用形如 namespace/name@版本。 |
| name | string | 必填 / 必有;名字,与 namespace 一起在租户内唯一,脚本与工作流共用命名空间,重名返回 409 NAME_TAKEN。 |
| description | string | 必填 / 必有;说明文字,最多 1000 字符。 |
| labels | object | 必填 / 必有;用户自定义标签:字符串键值对,用于分类与列表过滤(labels[key]=value);键不能以 praxis. 开头。 |
| owner | string | 必填 / 必有;所属租户,由网关注入;按不透明字符串处理。 |
| latest_version | null / object | 必填 / 必有;latest 标签指向的已发布版本 {version, published_at};尚未发布为 null。 |
| latest_version(分支2).version | string | 必填 / 必有;最新发布版本的版本号(semver)。 |
| latest_version(分支2).published_at | string | 必填 / 必有;该版本的发布时间(RFC 3339 UTC)。 |
| dist_tags | object | 必填 / 必有;标签到精确版本号的映射,例如 latest 指向 1.2.0;用 ns/name@标签 运行时按此解析。 |
| draft_changed | boolean | 必填 / 必有;true 表示草稿内容(摘要)不同于 latest 版本,即有未发布的改动。 |
| latest_run | null / object | 必填 / 必有;该编排最近一次运行的摘要;还没有运行为 null。 |
| latest_run(分支2).id | string | 必填 / 必有;运行 ID(run_ 前缀),可用于 runs.retrieve。 |
| latest_run(分支2).number | null / number | 必填 / 必有;运行在该脚本或工作流内的递增序号。 |
| latest_run(分支2).status | "running" / "completed" / "faulted" / "cancelled" / "pending" / "waiting" / "suspended" | 必填 / 必有;运行状态。pending 已创建尚未开始;running 执行中;waiting 工作流在等待事件、定时器或子运行;suspended 工作流被暂停;cancelled 已取消;faulted 失败;completed 成功完成。 |
| latest_run(分支2).created_at | string | 必填 / 必有;运行创建时间(RFC 3339 UTC)。 |
| latest_run(分支2).current_wait | null / object | 必填 / 必有;当前未完成的等待点;没有等待为 null。 |
| latest_run(分支2).current_wait(分支2).id | string | 必填 / 必有;等待点 ID,前缀 wait_;完成事件等待点时作为路径中的 wait_id。 |
| latest_run(分支2).current_wait(分支2).run_id | string | 必填 / 必有;所属运行 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).task | null / object | 必填 / 必有;产生该等待的工作流步骤 {reference, name};没有对应步骤为 null。 |
| latest_run(分支2).current_wait(分支2).task(分支2).reference | string | 必填 / 必有;步骤的 JSON Pointer,例如 /do/2/wait_payment。 |
| latest_run(分支2).current_wait(分支2).task(分支2).name | string | 必填 / 必有;步骤名,即工作流 YAML 中的键。 |
| latest_run(分支2).current_wait(分支2).resume_at | null / string | 必填 / 必有;kind=timer 时恢复运行的时刻(RFC 3339 UTC);其它类型为 null。 |
| latest_run(分支2).current_wait(分支2).event_type | null / string | 必填 / 必有;kind=event 时等待的事件类型;其它类型为 null。 |
| latest_run(分支2).current_wait(分支2).child_run_id | null / string | 必填 / 必有;kind=child 时被等待的子运行 ID;其它类型为 null。 |
| latest_run(分支2).current_wait(分支2).created_at | string | 必填 / 必有;等待点创建时间(RFC 3339 UTC)。 |
| latest_run(分支2).current_wait(分支2).expires_at | null / string | 必填 / 必有;等待点到期时间(RFC 3339 UTC);没有期限为 null。 |
| latest_run(分支2).current_wait(分支2).resolved_at | null / string | 必填 / 必有;等待点被满足的时间(RFC 3339 UTC);尚未满足为 null。 |
| stats_7d | object | 必填 / 必有;近七天的运行统计:按运行结束日期累计,在运行结束时更新,读取时不扫描运行。 不接受额外字段。 |
| stats_7d.runs | number | 必填 / 必有;近七天内结束的运行总数(任意终态)。 |
| stats_7d.failures | number | 必填 / 必有;其中以 faulted 结束的运行数。 |
| archived_at | null / string | 必填 / 必有;归档时间;未归档为 null。归档后名字保留,不可复用。 |
| created_at | string | 必填 / 必有;创建时间(RFC 3339 UTC)。 |
| updated_at | string | 必填 / 必有;最近一次更新的时间(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 | 错误码与说明 |
|---|---|
| 400 | INVALID_PARAMS:请求参数、路径、游标或请求体格式无效。 |
| 403 | NAMESPACE_FORBIDDEN:命名空间只读或运行令牌不允许此调用。 |
| 409 | IDEMPOTENCY_IN_FLIGHT:同一幂等键的请求仍在处理中。 NAME_TAKEN:名称已被同一租户占用。 |
| 422 | IDEMPOTENCY_KEY_MISMATCH:同一幂等键已用于不同请求内容。 |
| default | RFC 9457 automation problem. 429 includes Retry-After. |
鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。