# 创建脚本 (/docs/api/native/automation/createScript)





创建脚本及可编辑草稿，不会发布或启动运行；脚本与工作流共用名称空间，同租户重名返回 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 [#applicationjson]

不接受额外字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| 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 个字符。 |

## 示例 [#示例]

[SDK 安装与示例环境](/docs/api/native/automation)

```bash
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 });"
}'
```

```typescript
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 [#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

```json
{
  "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. |

[鉴权错误与通用错误](/docs/api/errors) · 排查时保留响应头 `X-Request-Id`。