自动化
校验定义
校验源码并返回诊断及输入输出契约。
校验源码并返回诊断及输入输出契约。支持动作、脚本和工作流;结果含 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。 |
| source | string | 必填 / 必有;待校验的源码;action 和 script 使用 TypeScript,workflow 使用 YAML。 |
示例
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 '@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
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 步骤的循环信息 {each, in}。 不接受额外字段。 |
| 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
{
"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. |
鉴权错误与通用错误 · 排查时保留响应头 X-Request-Id。