开发者接入白皮书 - OriginBeat Documents

1. 协议愿景：业务逻辑的“集装箱”

在 AI 时代，业务逻辑正变得碎片化且不可控。Runly Protocol 旨在定义一套工业级的逻辑封装标准。正如 Docker 封装了运行环境，Runly 封装了业务执行的路径。通过 RSS (Runly SOP Standard)，开发者可以将非标的“Prompt 交互”升级为具备强类型准入、异构模型路由、人工卡点（HITL）以及自动分账能力的逻辑资产。

2. 核心架构设计 (The 4-Domain Model)

一份 .runly 协议文件由四个核心域组成，确保了逻辑在全生命周期内的安全性与确定性。 2.1. Manifest (协议名片)

确权与唯一性：通过全局唯一的 URN 标识资产身份。
版本控制：遵循 SemVer 2.0.0 语义化版本规范，确保下游集成的稳定性。
安全签名：集成 Ed25519 数字指纹，任何对逻辑的微小篡改都将导致协议拒绝执行。

2.2. Dictionary (数据字典)

强类型准入：支持 string, json, file, enum 等强类型校验，在数据进入 AI 节点前拦截异常。
外部集成声明：静态定义协议所需的外部数据拉取（Pull）和服务调用（Action）。
交付定义：支持内置生成 HTML 可视化报告或 JSON 资产文件，并支持 Webhook 异步推送（Async Push）。

2.3. Topology (逻辑拓扑)

执行语义：定义 AI_TASK (生成)、LOGIC_GATE (决策)、HTTP (通讯) 的执行顺序。
HITL (人工卡点)：协议原生的状态机挂起机制。支持业务流在关键决策点自动暂停，等待人类专家通过 Runly Me 授权唤醒。
容错机制：内置指数退避重试（Exponential Backoff）与全局超时控制。

2.4. Commerce (商业域)

自动结算：代码化定义单次调用价格（UNIT_PAYMENT）。
版税分账：自动执行创作者（Creator）与平台/渠道之间的收益分成。

3. 开发者集成指南 (Step-by-Step)

第一步：定义逻辑字典 (Defining the Dictionary) 开发者需首先声明协议的“边界”。

dictionary:
  inputs:
    - name: "target_asin"
      type: "string"
      pattern: "^[A-Z0-9]{10}$"
      required: true
  outputs:
    - name: "final_report"
      type: "html"
      delivery: { mode: "ASYNC_PUSH", target_url: "{{inputs.callback}}" }

第二步：编排拓扑结构 (Orchestrating Topology) 使用 DAG 结构串联业务逻辑。

topology:
  nodes:
    - id: "ai_analysis"
      type: "AI_TASK"
      config: { prompt: "分析 ASIN {{inputs.target_asin}}..." }
      on_success: "logic_gate_1"
    - id: "logic_gate_1"
      type: "LOGIC_GATE"
      rules:
        - condition: "steps.ai_analysis.score > 80"
          next: "human_review"

第三步：编译与签名 (Pack & Sign) 使用 Runly CLI 工具对 YAML 源码进行编译签名，生成加密资产。

runly-cli build expert_logic.yaml --key ./my_private.key
# 输出: expert_logic.runly

第四步：部署执行 (Invocation) 通过 SDK 将逻辑资产集成到您的业务系统中。

import "github.com/runly/sdk"

res := sdk.Execute("expert_logic.runly", map[string]interface{}{
    "target_asin": "B08N5KXXXX",
    "callback": "https://api.myapp.com/webhook"
})

4. 报流协议：RSS Message (Packet Standard)

当 SDK 与 Executor 交互时，数据包必须遵循以下结构：

4.1. 请求报文 (Request Packet)

请求报文用于初始化执行、唤醒挂起节点或传递外部输入。

{
  "header": {
    "protocol_version": "v1.0",
    "trace_id": "req-8899-001",
    "timestamp": 1738746029
  },
  "asset": {
    "urn": "urn:runly:ecommerce:launch-v1",
    "signature": "ed25519:sig_data..."
  },
  "payload": {
    "current_node": "ai_task_localization",
    "state_data": { 
        "action": "RESUME", 
        "input_override": { "comment": "Verified by expert" } 
    }, 
    "global_inputs": { 
        "target_asin": "B08N5KXXXX",
        "callback": "https://api.myapp.com/webhook"
    } 
  }
}

{
  "header": {
    "protocol_version": "v1.0",
    "trace_id": "req-8899-001",
    "timestamp": 1738746150
  },
  "asset": {
    "urn": "urn:runly:ecommerce:selection-starter:v1:8892",
    "signature": "ed25519:sig_data..."
  },
  "payload": {
    "current_node": "expert_gate",
    "node_type": "HITL",
    "state_data": {
      "action": "SUSPENDED",
      "instruction": "请确认 ASIN B08N5KXXXX 的市场毛利是否真实。",
      "snapshot_context": {
        "ai_analysis_result": "{{steps.ai_core.output}}",
        "market_raw_data": "{{data.market_api.output}}"
      }
    },
    "global_inputs": {
      "target_asin": "B08N5KXXXX",
      "callback": "https://api.myapp.com/webhook"
    }
  }
}

trace_id: 唯一调用链路标识，用于日志追踪与异步回调匹配。
state_data: 用于传递状态机指令。在初次启动时为空；在 HITL 唤醒时携带专家决策数据。
global_inputs: 严格映射 Dictionary 中定义的必填字段。

4.2. 返回报文 (Response Packet)

返回报文描述了当前的执行进度、产出物或中断原因（如等待人工）。

{
  "header": {
    "protocol_version": "v1.0",
    "trace_id": "req-8899-001",
    "timestamp": 1738746150
  },
  "status": {
    "code": 202,
    "state": "SUSPENDED",
    "node_id": "human_review",
    "message": "Awaiting expert authorization via Runly Me."
  },
  "result": {
    "outputs": {
      "intermediate_analysis": "..." 
    },
    "artifacts": {
      "report_url": "https://cdn.runly.net/a/x8y2.html"
    }
  },
  "error": null
}

{
  "header": {
    "protocol_version": "v1.0",
    "trace_id": "req-8899-001",
    "timestamp": 1738746200
  },
  "asset": {
    "urn": "urn:runly:ecommerce:selection-starter:v1:8892"
  },
  "payload": {
    "current_node": "expert_gate",
    "state_data": {
      "action": "RESUME",
      "output": {
        "audit_result": "APPROVED",
        "expert_comment": "毛利核实无误，准予通过。",
        "authorized_by": "me_dow_001"
      }
    }
  }
}

status.code:
- 200: 流程完全结束（TERMINUS）。
- 202: 接受执行但已挂起（通常指遇到 HITL）。
- 400/500: 字典校验失败或引擎内部错误。
status.state: 可选值为 RUNNING, SUSPENDED, COMPLETED, FAILED。
artifacts: 包含生成的持久化资产下载链接（如 HTML 报告）。

5. 为什么选择 Runly Protocol？

特性	传统 AI 开发	Runly Protocol (RSS)
逻辑稳定性	高度依赖 Prompt，易产生幻觉	逻辑门限与强类型 Schema 强制限制
集成成本	需为每个模型编写大量适配代码	标准化 SDK，资产即插即用
人工核验	需手动开发审批后台与状态机	原生支持 HITL 挂起与断点续传
变现能力	难以对“一段代码”进行定价	协议内置分账逻辑，调用即结算

6. 开发者生态与支持

Runly 提供完整的开发者工具链：

Runly Hub：在线的可视化协议编辑器与资产管理仓库。
Runly Executor：轻量级、高性能的逻辑执行引擎，支持云端部署与边缘部署。
Runly Me：专家的数字身份终端，用于接收 HITL 节点推送并进行决策。

7. 名词解释表 (Glossary)

为了帮助非技术背景的业务专家快速理解 Runly Protocol，我们对核心术语进行了通俗化定义：

术语	全称	通俗解释	业务价值
URN	Uniform Resource Name	协议的“身份证号”。全球唯一的资源标识符。	确保你的逻辑资产在任何地方都不会被混淆。
HITL	Human-in-the-loop	“人工卡点”。在自动化流程中强制加入的专家审核环节。	确保高价值或高风险决策由人最终把关，防止 AI 跑偏。
DSL	Domain Specific Language	领域专用语言。专门为 SOP 逻辑编排设计的脚本语言。	让业务专家能用“逻辑话”直接写协议，无需底层编程。
Executor	Logic Executor	“逻辑执行官”。负责阅读协议并驱动各节点运行的软件引擎。	它是协议的“心脏”，负责处理计算、通讯和支付。
Artifact	Digital Artifact	“数字产物”。协议执行后生成的 PDF、HTML 或 JSON 文件。	它是最终交付给客户的“实物”报告或数据包。
Royalty	Royalty Share	“逻辑版税”。每次调用协议时产生的收益分成。	保护创作者，实现“睡后收入”，每一单调用都实时结算。
Snapshot	Execution Snapshot	“执行快照”。流程挂起时保存的瞬间状态。	允许流程中断几天后，在另一个设备上无缝继续执行。

8. HelloWorld.runly 完整示例

这是一个名为 “选品简析专家” 的完整协议示例。它展示了如何从输入开始，拉取外部数据，经过 AI 分析，并在专家确认后交付 HTML 报告和分账的全过程。

# 1. Manifest: 协议名片
manifest:
  urn: "urn:runly:ecommerce:selection-starter:v1:8892"
  title: "入门级选品简析专家"
  version: "1.0.0"
  status: "stable"
  creator:
    me_id: "me_dow_001"
    pub_key: "ed25519:0x8e5c...a31b"
  min_runtime: "v1.0"

# 2. Dictionary: 数据字典
dictionary:
  inputs:
    - name: "target_asin"
      type: "string"
      pattern: "^[A-Z0-9]{10}$"
      required: true
  
  external_data:
    - id: "market_api"
      type: "REST_API"
      config:
        url: "https://api.market.com/v1/{{inputs.target_asin}}"
        headers: { Authorization: "Bearer {{env.API_TOKEN}}" }

  outputs:
    - name: "final_report"
      type: "html"
      config:
        template_ref: "urn:runly:templates:simple-report"
        data_mapping: { result: "{{steps.ai_core.output}}" }
      export_as: "artifact" # 存储为可下载资产

# 3. Topology: 逻辑拓扑
topology:
  start_at: "fetch_data"
  nodes:
    # 节点 A: 异步获取外部数据
    - id: "fetch_data"
      type: "HTTP"
      config:
        ref: "external_data.market_api"
      on_success: "ai_core"

    # 节点 B: AI 核心处理
    - id: "ai_core"
      type: "AI_TASK"
      config:
        model: "gemini-2.0-flash"
        prompt: "基于数据 {{steps.fetch_data.output}}，给出 3 条选品建议。"
      on_success: "expert_gate"

    # 节点 C: 人工卡点 (HITL)
    - id: "expert_gate"
      type: "HITL"
      config:
        instruction: "请确认 AI 建议是否符合本季市场趋势。"
      on_success: "delivery"

    # 节点 D: 终点交付
    - id: "delivery"
      type: "TERMINUS"
      config:
        output_ref: "outputs.final_report"

# 4. Commerce: 商业分账
commerce:
  pricing:
    mode: "UNIT_PAYMENT"
    amount: 0.50
    currency: "USDT"
  royalty:
    creator_share: 0.80   # 创作者得 0.4 USDT
    platform_share: 0.20  # 平台得 0.1 USDT

入门

标准协议

​1. 协议愿景：业务逻辑的“集装箱”

​2. 核心架构设计 (The 4-Domain Model)

​3. 开发者集成指南 (Step-by-Step)

​4. 报流协议：RSS Message (Packet Standard)

​4.1. 请求报文 (Request Packet)

​4.2. 返回报文 (Response Packet)

​5. 为什么选择 Runly Protocol？

​6. 开发者生态与支持

​7. 名词解释表 (Glossary)

​8. HelloWorld.runly 完整示例