1. Namespace (变量命名空间) 规范
定义协议内部所有参数的唯一寻址路径。变量命名必须遵循snake_case。
inputs.<key>:全局只读域。由协议启动时外部注入的初始业务参数。steps.<node_id>.<key>:节点局部域。存储特定逻辑节点执行后的中间产物或最终结果。data.<source_id>.<key>:外部拉取域。通过external_data动获取的结构化信息快照。env.<key>:环境私密域。由执行引擎在运行时注入的受保护密钥、API Tokens。system.<key>:系统元数据域。引擎生成的运行状态,如trace_id,timestamp,runtime_version。outputs.<key>:交付资产域。定义最终对外分发的报文、文件或可视化报告。
2. Strong Typing (强类型约束) 规范
所有声明的变量必须强制指定物理类型,执行引擎在节点入栈前进行 Type Assertion (类型断言)。| 类型关键字 | 描述说明 | 核心约束参数 (Constraints) |
|---|---|---|
string | 文本字符串 | pattern (正则), min_len, max_len |
number | 数值(整型/浮点) | min, max, precision (精度控制) |
boolean | 布尔逻辑 | N/A |
enum | 枚举值 | options (合法值白名单列表) |
json | 结构化对象 | schema_ref (JSON Schema), export_as_file (是否转为文件) |
html | 可视化资产 | template_ref (模板 ID), css_theme (样式主题) |
array | 数组列表 | items_type (成员类型), min_items |
file | 原始文件流 | extensions (后缀限制), max_size (单位 MB) |
3. Data Ingress (数据准入与清洗)
定义原始数据从外部进入协议时的校验与保护规则。required(必填性) :若为true且启动时缺失该数据,引擎立即拒绝执行并抛出错误。default(回退值) :非必填项缺失时自动填充的预设值。mask(隐私保护) :标记为true的字段在 Log 日志、HITL 专家审核界面中将以掩码显示(如:**)。transform(预处理) :支持简单的格式规范化,如trim,lowercase,uppercase。
4. External Data Sources (外部数据源拉取 - Pull)
定义协议执行过程中需要从第三方系统主动获取的数据实体。source_id:协议内部唯一的引用 ID。type:支持REST_API,gRPC,MCP(Model Context Protocol)。config:包含url,method,headers,query_params。支持变量注入(如{{env.API_URL}})。cache_policy:定义ttl(Time To Live),避免在长流程 SOP 中产生冗余的网络开销。
5. External Service Actions (外部服务动作调用 - Action/Push)
定义协议需要驱动的外部“副作用”动作,如发送通知、同步 ERP、更新数据库。action_id:动作唯一标识。config:定义请求的详细参数,包含timeout(1s - 300s)。retry_policy(重试策略) :max_retries: 最大重试次数。interval: 支持fixed(固定间隔) 或exponential(指数退避)。retry_on_status: 触发重试的状态码(如[502, 504])。
6. Outputs & Delivery (交付资产与异步输出规范)
定义协议执行完毕后的产出形态。Runly 支持将结果包装成可视化报告或结构化文件,并主动推送到用户侧。6.1. 内置资产生成 (Built-in Artifacts)
export_as: "artifact":标记此输出为需要持久化的资产文件。执行引擎将渲染后的 HTML 或生成的 JSON 上传至受保护的对象存储,并生成访问 URL。template_ref:引用 Runly 标准库中的可视化模板,通过data_mapping将逻辑结果填充至 UI。
6.2. 交付模式 (Delivery Modes)
mode:SYNC:随当前执行 API 请求同步返回结果。ASYNC_PUSH:逻辑执行完毕后,由引擎主动异步推送至target_url(Webhook)。
payload_mapping:允许用户自定义推送的报文结构,实现 Runly 数据与用户业务系统的无缝对接。
