# 校验定义 (/docs/api/native/automation/validateDefinition)





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

`POST /automation/v1/validate`

## 鉴权 [#鉴权]

`Authorization: Bearer $PRAXIS_API_KEY`

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

### application/json [#applicationjson]

不接受额外字段。

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

## 示例 [#示例]

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

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

```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.validate.create({
  "body": {
    "kind": "script",
    "source": "export default async (input: { n: number }) => ({ answer: input.n + 1 });"
  }
});
console.log(result);
```

## 响应 [#响应]

### HTTP 200 [#http-200]

Success

`application/json`

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| valid | `boolean` | 必填 / 必有；源码是否通过校验：true 可发布或运行，false 见 errors。 |
| errors | `object[]` | 必填 / 必有；校验错误列表，每项含 pointer 与中文 detail；为空数组时 valid 为 true。 |
| errors[].pointer | `string` | 必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。 |
| errors[].detail | `string` | 必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。 |
| errors[].hint | `string` | 可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。 |
| errors[].line | `integer` | 可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| errors[].column | `integer` | 可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| input_schema | `null` / `object` | 必填 / 必有；从源码推导出的输入 JSON Schema；无法解析源码时为 null。 |
| input_schema（分支2).*（分支5) | `object` | 递归 JSON 值。 |
| input_schema（分支2).*（分支6)[] | `null` / `string` / `number` / `boolean` / `object` / `JSON[]` | 递归 JSON 值。 |
| output_schema | `null` / `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 值。 |
| references | `object[]` | 必填 / 必有；源码依赖的动作、平台 API、脚本与工作流。 |
| references[].kind | `"action"` / `"script"` / `"workflow"` / `"platform_api"` / `"run"` | 必填 / 必有；依赖类型。action 为动作；platform_api 为平台 API 操作；script 为脚本；workflow 为工作流；run 为脚本中 invoke("ns/name") 调用的子运行目标（脚本或工作流，发布时解析）。 |
| references[].name | `string` | 必填 / 必有；被依赖对象：动作为 ns/name，平台 API 为操作名，脚本与工作流为 ns/name。 |
| references[].range | `string` | 可选；引用时写的版本范围或标签（npm 规则）；未写时为空。 |
| references[].locked_version | `string` | 可选；发布时锁定的精确版本；仅脚本与工作流依赖有，动作与平台 API 不锁定。 |
| outline | `null` / `object[]` | 必填 / 必有；工作流步骤大纲；脚本和动作为 null。 |
| outline（分支2)[].name | `string` | 必填 / 必有；步骤名，即工作流 YAML 中该步骤的键。 |
| outline（分支2)[].reference | `string` | 必填 / 必有；该步骤在工作流文档中的 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)[].target | `string` | 可选；步骤调用的目标：call 步骤为动作 ns/name，run 步骤为 ns/name@范围；其它类型没有。 |
| outline（分支2)[].wait | `object` | 可选；等待步骤的摘要：时长（seconds 或 duration）或等待的事件类型（event）。 不接受额外字段。 |
| outline（分支2)[].wait.until | `string` | 可选；等待结束的绝对时刻，仅在可静态确定时给出；目前大纲不填充该字段。 |
| outline（分支2)[].wait.seconds | `number` | 可选；可静态换算的等待秒数；时长对象与可换算的 ISO 时长均投影到此字段。 |
| outline（分支2)[].wait.event | `string` | 可选；listen 步骤等待的事件类型。 |
| outline（分支2)[].wait.duration | `string` | 可选；无法静态换算成秒的原始时长或运行时表达式；不与 seconds 强行换算。 |
| outline（分支2)[].loop | `object` | 可选；for 步骤的循环信息 &#123;each, in&#125;。 不接受额外字段。 |
| outline（分支2)[].loop.each | `string` | 必填 / 必有；循环变量名；未指定时为 item。 |
| outline（分支2)[].loop.in | `string` | 必填 / 必有；被遍历的集合表达式原文。 |
| outline（分支2)[].children | `object[]` | 可选；嵌套的子步骤（do、fork 分支、try 与 catch 内的步骤）。 |
| outline（分支2)[].children[] | `object` | 递归 JSON 值。 |
| warnings | `object[]` | 可选；脚本/动作静态分析的非阻断诊断；无法推导类型时使用空 schema 并给 warning。工作流分析可省略。 |
| warnings[].pointer | `string` | 必填 / 必有；RFC 6901 字段指针。TypeScript 源码诊断为 /source（脚本）或 /implementation/source（动作）；行列另见 line/column，不拼在指针后。 |
| warnings[].detail | `string` | 必填 / 必有；中文修正说明，指出该位置出了什么问题以及怎样改。 |
| warnings[].hint | `string` | 可选；可选的补充提示，给出下一步可执行的动作（例如改用另一个接口）。 |
| warnings[].line | `integer` | 可选；行号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| warnings[].column | `integer` | 可选；列号，从 1 起；仅有源码位置时返回。 minimum: 1 |
| platform_apis | `string[]` | 可选；脚本/动作引用的平台 API 集合（字符串数组）；工作流分析可省略。 |

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

HTTP 200

```json
{
  "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 | 错误码与说明 |
| --- | --- |
| 400 | INVALID_PARAMS：请求参数、路径、游标或请求体格式无效。 |
| default | RFC 9457 automation problem. 429 includes Retry-After. |

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