跳转到主要内容
topology:
  # 协议启动的起始点
  start_at: "node_ingress_check"

  nodes:
    # 1. 准入审计
    - id: "node_ingress_check"
      type: "LOGIC_GATE"
      rules:
        - condition: "inputs.target_asin.length == 10"
          next: "node_fetch_market_data"
        - condition: "default"
          next: "terminate_error"

    # 2. 调用外部数据源 (在 Dictionary 中定义的数据源)
    - id: "node_fetch_market_data"
      type: "HTTP"
      config:
        ref: "external_data.amazon_market_data" # 引用字典中的定义
      on_success: "node_ai_analysis"
      on_failure: "node_retry_strategy"

    # 3. AI 专家逻辑执行
    - id: "node_ai_analysis"
      type: "AI_TASK"
      config:
        model: "gemini-2.0-flash"
        prompt: "基于 {{steps.node_fetch_market_data.output}} 分析该产品的市场竞争力..."
      on_success: "node_profit_gate"

    # 4. 商业逻辑门限
    - id: "node_profit_gate"
      type: "LOGIC_GATE"
      rules:
        - condition: "steps.node_ai_analysis.profit_margin > 0.25"
          next: "node_expert_sign_off" # 利润达标，进入人工复核
        - condition: "default"
          next: "node_direct_push"   # 利润一般，跳过人工直接推送结果

    # 5. 人工卡点 (HITL)
    - id: "node_expert_sign_off"
      type: "HITL"
      config:
        # [1] 授权目标：指定谁来审批
        assignee: "{{manifest.creator.me_id}}" 
        
        # [2] 交互策略：如何触达专家
        interaction:
          priority: "HIGH"            # 高优先级，触发手机强提醒
          channel: ["APP", "SLACK"]   # 支持多渠道推送
          auth_level: "SIGNATURE"     # 要求专家使用私钥签名回传，确保不可抵赖
        
        # [3] 界面呈现：专家在 App 里看到的内容
        ui:
          title: "选品风控审核"
          instruction: "请核对 ASIN {{inputs.target_asin}} 的市场毛利是否真实。"
          fields: # 展示给专家看的关键上下文切片
            - "steps.ai_core.summary"
            - "data.market_api.raw_price"
      on_success: "node_direct_push"
      on_failure: "node_ai_analysis" # 若专家打回，回到 AI 重新分析

    # 6. 最终交付
    - id: "node_direct_push"
      type: "TERMINUS"
      config:
        output_ref: "outputs.final_delivery" # 引用字典中的输出定义

​
1. Node (逻辑节点) 生命周期

每个节点在执行引擎（Executor）中必须经历以下四个标准阶段：
  1. Preparation (准备)：从 Dictionary 中提取变量，注入 env 密钥，解析 Prompt 模板或 HTTP URL。
  2. Pre-check (预检)：进行 Strong Typing 校验，确保输入数据符合节点预设的 Schema。
  3. Execution (执行)：调用模型、触发外部 HTTP 请求或进入 HITL 挂起状态。
  4. Post-process (收尾)：捕获输出，更新全局 Context，根据结果决定下一跳路径（Next Hop）。

​
2. Edge & Branching (连线与跳转规则)

Topology 使用有向无环图 (DAG) 或有限状态机 (FSM) 描述逻辑流转。每个节点必须显式定义其跳转逻辑。
跳转指令触发条件执行动作
on_success节点返回状态为 200/OK转向指定的下一个节点 ID。
on_failure节点报错、超时或 AI 输出非法转向错误处理节点（Error Handler）或触发回滚。
on_condition基于表达式的判断结果配合 LOGIC_GATE 类型使用，实现多分支跳转。
terminate流程终结指令立即停止执行，并根据当前状态触发 TERMINUS。

​
3. Node Types (节点类型) 深度规范

在 Topology 中，不同类型的节点具有不同的执行语义：
  • AI_TASK：
    • 核心语义：非确定性语义计算。
    • 约束：必须定义 output_schema。如果 AI 输出不符合 Schema，触发 on_failure。
  • HTTP(External Action) ：
    • 核心语义：外部系统集成。
    • 约束：必须定义 timeout 和 retry_policy。
  • LOGIC_GATE：
    • 核心语义：确定性决策。
    • 约束：不调用任何 AI 或外部服务，纯粹基于当前 Context 变量进行逻辑判定。
  • HITL(Human-in-the-loop) ：
    • 核心语义：人机协同隔离。
    • 约束：引擎必须保存当前 Snapshot，暂停计算，释放资源，等待异步唤醒。

​
4. HITL (人工卡点) 状态机语义

这是 Runly 协议区别于传统工作流的核心。当执行流到达 HITL 节点时：
  1. 挂起 (Suspend)：Executor 将当前所有 steps 变量、inputs 以及执行进度序列化并存入持久化层。
  2. 生成 Ticket：系统生成一个唯一的 Interaction_ID 和授权令牌。
  3. 通知 (Notify)：通过 Dictionary 定义的 external_services（如 Slack/Runly Me）通知专家。
  4. 唤醒 (Resume)：专家通过 API 回传指令及审批意见，Executor 载入 Snapshot，从该节点继续向后执行。

​
5. 容错与并发控制 (Resilience)

  • Max_Depth：防止循环依赖，单个协议执行的节点深度上限（默认 100）。
  • Retry_Backoff：节点失败后的指数级重试机制。
  • Global_Timeout：整个协议生命周期的总时长限制，超时则强制 TERMINATED_TIMEOUT。