跳转到主要内容
# =============================================================
# 5. TOPOLOGY (拓扑逻辑)
# 引用资源契约，编排 AI Native 业务流转状态机
# =============================================================
topology:
  start_at: "node_validate"
  
  nodes:
    # 节点 1: 逻辑校验门
    - id: "node_validate"
      type: "LOGIC_GATE"
      rules:
        - { condition: "inputs.target_asin.length == 10", next: "call_market_skill" }
        - { condition: "default", next: "terminate_error" }

    # 节点 2: 执行技能（引用 Skills 域）
    - id: "call_market_skill"
      type: "SKILL_CALL"
      config:
        skill_ref: "amazon_realtime_data"
      on_success: "node_ai_reasoning"
      on_failure: "node_retry_logic"

    # 节点 3: AI 推理（挂载 Knowledge 域）
    - id: "node_ai_reasoning"
      type: "AI_TASK"
      config:
        model: "gemini-2.0-flash"
        knowledge_ref: "internal_market_trends"
        prompt: |
          结合知识库背景及实时数据 {{steps.call_market_skill.output}}，
          深度评估 ASIN {{inputs.target_asin}} 的市场机会。
      on_success: "node_expert_hitl"

    # 节点 4: HITL 人工审批（专家确权）
    - id: "node_expert_hitl"
      type: "HITL"
      config:
        assignee: "{{manifest.creator.me_id}}"
        instruction: "AI 已完成逻辑推理，请针对 ROI 预测完成最终业务授权。"
        ui_snapshot:
          - "steps.node_ai_reasoning.output"
          - "steps.call_market_skill.output.price"
      on_success: "node_terminus"

    # 节点 5: 逻辑终点
    - id: "node_terminus"
      type: "TERMINUS"
      config:
        artifact_ref: "selection_report_data"
        data_source: "steps.node_ai_reasoning.output"

​
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. 节点通用字段

所有节点均包含以下基础属性：
  • id: 节点唯一标识，用于跨节点引用数据（如 {{steps.node_id.output}}）。
  • type: 节点类型（详见下文）。
  • config: 节点私有配置，根据类型不同而变化。
  • 流转控制: next (通用下行), on_success (成功下行), on_failure (失败/异常下行)

​
3. 核心节点类型 (Node Types)

​
A. LOGIC_GATE (逻辑校验门)

作为协议的“分流器”，负责基于表达式的条件跳转。
  • rules: 条件列表。
    • condition: 支持 CEL (Common Expression Language) 或类 JS 表达式，可访问 inputs 或 steps 状态。
    • next: 满足条件后跳转的目标节点 ID。

​
B. SKILL_CALL (技能调用)

协议与外部确切世界交互的锚点。
  • config.skill_ref: 引用 Skills 域定义的 ID。
  • 执行逻辑: 引擎根据引用的契约发起请求，并将返回报文存入 steps.ID.output。若报文校验失败，触发 on_failure。

​
C. AI_TASK (AI 推理任务)

AI Native 的核心，将 RAG 与大模型推理封装。
  • config.model: 建议的模型标识。
  • config.knowledge_ref: 引用 Knowledge 域定义的 ID，引擎自动完成语义检索与上下文注入。
  • config.prompt: 推理指令，支持强大的变量渲染模板。

​
D. HITL (Human-in-the-loop 人工卡点)

解决 AI 确定性最后 1% 的关键。
  • config.assignee: 授权人，通常引用 {{manifest.creator.me_id}}。
  • config.ui_snapshot: 数据快照声明。定义哪些上下文数据需要被推送到“专家终端（Runly Me）”供人审核，实现真正的“人机协同”。

​
E. TERMINUS (逻辑终点)

协议执行完成的出口。
  • config.artifact_ref: 引用 Dictionary.artifacts 域定义的 ID。
  • config.data_source: 指定从哪个节点的输出提取数据来填充该 Artifact。

​
4、变量引用规范 (Variable Scoping)

在 Topology 中，节点间通过插值表达式进行数据传递，作用域遵循以下优先级：
  1. {{inputs.xxx}}: 协议全局输入。
  2. {{steps.node_id.output}}: 特定节点的产出结果。
  3. {{manifest.xxx}}: 协议元数据。
  4. {{env.xxx}}: 执行环境注入的敏感变量（仅在 Config 域有效）。