Weegloo Docs - Script

Script 是前端通过 HTTP 调用的声明式后端端点。无需编写服务器代码，只要用 JSON 声明"要做什么"，WEEGLOO 引擎便会代为执行。目标是用一个 Script 取代支撑前端的典型后端管道（BFF，Backend-for-Frontend）：认证、条件检查(guard)、连锁 CRUD、外部 API 调用、值加工等。

这组文档是 Script 语法的正式参考(reference)。各语法的细节在下方本组文档中分别讲解。

Script 在 CMA 中编写并执行（Weegloo User 身份）。以注册产品的会员（ServiceUser）身份，也可在 ACMA 中以相同方式使用。Script API 只存在于这两个管理 API（CMA、ACMA）中，只读的交付 API（CDA、ACDA）中没有。

心智模型

一个 Script 就是一个 HTTP 端点。 通过调用方法(method)匹配要执行哪个 Script。
主体是 statements 数组。 自上而下顺序执行。与一般编程中的函数主体相同。
它是声明而非代码。 不是放入任意代码(FaaS)，而是组合固定的 statement 类型。其设计更贴合由 AI 代理通过 MCP 生成，而非由人手工编写。
值通过 JSON Pointer 模板流动。 用 { /pointer } 引用前一步的结果、输入 payload、变量，并传给下一步。需要条件或计算时使用 JsonLogic 运算符。详细规则在值表达式中讲解。

顶层结构 (ScriptDefinition)

一个 Script 用下面的 ScriptDefinition 结构来定义。

{
  "method": "Post",               // Get | Post | Put | Patch | Delete. 调用时用于匹配的 HTTP 方法（必填）
  "payloadSchema": { /* ... */ }, // （选填）JSON Schema。存在时会在执行前校验请求 payload
  "executionMode": "Sync",        // "Sync" | "Async"（必填）
  "statements": [ /* Statement[]. 自上而下执行（必填，1 个以上） */ ]
}

字段	必填	说明
`method`	必填	调用此 Script 时使用的 HTTP 方法。调用时以此值进行匹配。
`payloadSchema`	选填	JSON Schema。指定后会在执行前用此 schema 校验请求 body(payload)，校验失败则不执行并拒绝。
`executionMode`	必填	执行位置。`Sync`（在请求路径中立即执行）或 `Async`（后台）。详细规则在下方执行模式：Sync 与 Async中讲解。
`statements`	必填	要执行的语句(statement)的有序数组。至少 1 个。

payload 只接受 JSON。调用 body 通过 /payload 上下文根访问（{ /payload/... }）。调用的请求 HTTP 头通过 /headers 根引用（{ /headers/... }，键为小写）。全部上下文根在值表达式中讲解。

请求与响应

Script 最终将 Return 语句的值返回给调用方。响应（或 Async 轮询结果）的形态如下。

{
  "requestId": "…",     // 执行标识符（Async 用此 id 轮询结果）
  "durationMs": 1234,   // 执行耗时(ms)
  "statusCode": 200,    // 所到达 Return 的 statusCode（默认 200）
  "return": <value>     // 仅当 Return.isError 为 false 时。值为 null 则为 ""
  // "error": <value>   // 仅当 Return.isError 为 true 时（此时无 "return"）。值为 null 则为 ""
}

return 与 error 不会同时出现。由 Return 语句的 isError 决定是哪一个。
如果 Script 在未到达 Return 语句的情况下结束，则 return 与 error 都不存在，statusCode 为默认值(200)。
值为 null 时，该字段以空字符串 "" 呈现。

用 Return 的 value、isError、statusCode 控制响应正文与状态码。详细内容在Statement 目录的 Return中讲解。

执行模式：Sync 与 Async

区分	Sync	Async
执行位置	在处理请求的路径中立即执行	在后台执行
调用响应	立即以下面的形态作为响应正文返回	立即返回 `202 Accepted` 与 `requestId`
结果获取	直接为响应正文	用 `requestId` 轮询，完成时取得响应
时间预算	默认 10 秒	默认 60 秒

存在外部 I/O 时只允许 Async。 只要有任何一个 statement 涉及走网络的操作，例如 Http 外部调用(ExternalIo)或 Media 文件摄取(MediaIngest，url·base64)，executionMode 就必须为 Async；试图以 Sync 保存会在保存时被拒绝。这是为了不让请求线程被外部延迟阻塞。
这只是执行位置的差异，无论哪一种，结果都是 Return 值。

从各项能力衔接到模式的规则与限额，在执行语义、约束、安全中讲解。

最小示例

用请求 payload 的标题与正文创建一条帖子 Content 并立即发布，然后返回所创建的 sys.id。

{
  "method": "Post",
  "executionMode": "Sync",
  "statements": [
    { "type": "ResourceCreate", "resource": "Content",
      "contentType": { "sys": { "id": "ct_post" } },
      "fields": {
        "title": { "en-US": "{ /payload/fields/title }" },
        "body":  { "en-US": "{ /payload/fields/body }" }
      },
      "publish": true,
      "name": "post" },
 
    { "type": "Return", "value": { "id": "{ /post/sys/id }" }, "statusCode": 201 }
  ]
}

用 ResourceCreate 创建 Content 并把结果绑定到名为 post 的名称上。
Return 将 { "id": <新 Content id> } 以 201 返回。
Content 的 fields 值之所以是 locale 映射({ "en-US": ... })，其原因在值表达式的 locale 映射中讲解。

更多样的场景在Cookbook中。

本组文档

值表达式：讲解 { /pointer } 引用、字面量、JsonLogic 运算与条件、上下文根、locale 映射。是语法的核心。
Statement 目录：讲解 17 种语句（资源 CRUD 与读取、Http、SetVar、If、Loop、Parallel、Try、Return）的字段与结果。
执行语义、约束、安全：讲解执行顺序、guard、补偿、乐观锁、错误、静态约束与套餐限额、安全模型。
Cookbook：讲解 upsert、额度 guard、LLM 代理、分页、并行、支付 saga 等完整示例。
Script 资源与端点：讲解 Script 资源的 sys 结构，以及编写、执行(/execute) HTTP 端点的规格。

初次接触的话，建议在本页之后按值表达式、Statement 目录的顺序阅读。Cookbook可以整体通览一遍。