跳转到主要内容
dictionary:
  # [1] Ingress: 输入准入
  inputs:
    - name: "target_asin"
      type: "string"
      pattern: "^[A-Z0-9]{10}$"
      description: "亚马逊标准识别码"
      required: true
    - name: "callback_url"
      type: "string"
      description: "用户接收异步结果的回调地址"
      required: true
    - name: "api_token"
      type: "string"
      mask: true # 运行日志中自动脱敏

  # [2] Data Pull: 外部数据源实时获取
  external_data:
    - id: "amazon_market_data"
      type: "REST_API"
      config:
        url: "https://api.market-api.com/v1/products/{{inputs.target_asin}}"
        method: "GET"
        headers:
          Authorization: "Bearer {{env.MARKET_API_TOKEN}}"
      cache_policy:
        ttl: 3600 # 缓存 1 小时

  # [3] Actions: 外部服务异步调用
  external_services:
    - action_id: "notify_slack"
      type: "HTTP"
      config:
        method: "POST"
        url: "{{env.SLACK_WEBHOOK}}"
        timeout: 10
        retry_policy:
          max_retries: 3
          interval: "fixed"

  # [4] Egress: 交付资产与结果分发
  outputs:
    # 场景 A: 生成内置的可视化 HTML 报告资产
    - name: "selection_report_html"
      type: "html"
      config:
        title: "选品专家分析报告 - {{inputs.target_asin}}"
        template_ref: "urn:runly:templates:business-report-v1"
        data_mapping:
          market_trend: "{{steps.ai_logic_node.trend}}"
          competitors: "{{data.amazon_market_data.list}}"
      export_as: "artifact"

    # 场景 B: 生成内置的结构化 JSON 数据文件
    - name: "raw_data_json"
      type: "json"
      config:
        export_as_file: true
        filename: "ASIN_{{inputs.target_asin}}.json"

    # 场景 C: 全流程结束后的异步主动推送
    - name: "final_delivery"
      delivery:
        mode: "ASYNC_PUSH"
        target_url: "{{inputs.callback_url}}"
        method: "POST"
        retry_policy:
          max_retries: 5
          interval: "exponential"
        payload_mapping:
          request_id: "{{system.trace_id}}"
          status: "COMPLETED"
          report_url: "{{outputs.selection_report_html.url}}" # 引用生成的资产链接
          data_file: "{{outputs.raw_data_json.url}}"
          summary: "{{steps.ai_logic_node.summary}}"

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 数据与用户业务系统的无缝对接。