# 设置脚本标签 (/docs/api/native/automation/setScriptTag)





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

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

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

## 请求字段 [#请求字段]

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| path: ns | `string` | 必填；命名空间，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}；praxis 只读。 |
| path: name | `string` | 必填；名称，存储前转为小写，格式 [a-z0-9][a-z0-9._-]{0,63}。 |
| path: tag | `string` | 必填；发布标签。预发布版本（如 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 [#applicationjson]

不接受额外字段。

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

## 示例 [#示例]

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

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

| 变量 | 来源 |
| --- | --- |
| SCRIPT_NAME | [创建脚本返回的 name](/docs/api/native/automation/createScript) |

```bash
: "${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"
}'
```

```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.distTags.set({
  "path": {
    "ns": "docs-samples",
    "name": env("SCRIPT_NAME"),
    "tag": "sample"
  },
  "body": {
    "version": "1.0.0"
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 200 [#http-200]

Success

`application/json`

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

### 实测响应 [#实测响应]

HTTP 200

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

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