跳转到主要内容
# =============================================================
# 3. SKILLS (技能契约)
# 定义外部数据调用与动作执行的报文契约(Skill Packet Standard)
# =============================================================
skills:
  - id: "amazon_realtime_data"
    type: "ACTION_HTTP"
    description: "获取亚马逊实时核心竞争数据"
    config:
      endpoint: "https://api.acme.com/v1/market/fetch"
      method: "POST"
      timeout: 15
	  max_retries: 3
      cache_ttl: 3600
      headers:
        Authorization: "Bearer {{env.MARKET_API_TOKEN}}"
    # 报文契约:确保执行层与技能层的数据对齐
    contract:
      request:
        payload:
          asin: "{{inputs.target_asin}}"
          region: "US"
      response:
        strict_mode: true
        schema:
          type: "object"
          properties:
            price: { "type": "number" }
            bsr_rank: { "type": "integer" }
            stock_level: { "type": "string" }

1、参数字段

字段名必填类型说明
idString技能唯一标识。用于在拓扑节点中通过 skill_ref 进行寻址。
typeEnum执行类型。ACTION_HTTP 为标准 RESTful 动作。
descriptionString功能描述。辅助 AI 或专家理解该技能的业务用途。
configObject物理执行配置。定义如何连接、重试及缓存数据。
contractObject报文契约标准。定义请求 Payload 和返回 Schema 的强约束。

2、Config 详解

这一部分定义了执行引擎在“物理层”的行为准则:

  • endpoint: 动态终点地址。支持 {{inputs.xxx}} 变量注入,实现参数化寻址。
  • method: 动作谓词(POST/GET/PUT)。
  • timeout: 最大阻塞时间(秒)。AI 场景下建议略长(15-30s),以应对复杂计算。
  • max_retries: 失败重试次数。针对网络抖动或 API 频率限制的自动化容错。
  • cache_ttl: 缓存有效期(秒)
    • 作用:如果同一个 ASIN 在一小时内被多次分析,引擎直接从缓存读取结果,节省 API 成本并提升相应速度。
  • headers: 鉴权声明。使用 {{env.xxx}} 模式,确保敏感 Token 永不存入 .runly 文件。

3、Contract 详解

这是协议最核心的“过滤器”,确保进入 AI 节点的永远是结构化、干净的数据。

Request (请求载荷)

  • payload: 定义发送给 API 的 JSON 结构。允许将 Dictionary 域的输入 (inputs) 映射到 API 的参数中。

Response (返回契约)

  • strict_mode:
    • true: 若 API 返回的数据不符合 Schema,引擎会立即抛出契约异常(ContractViolation),不传给 AI,防止 AI 基于错误数据进行错误推理。
  • schema: 采用 JSON Schema 标准。
    • 定义返回值的类型(number, integer, string)。
    • 此处定义的 price, bsr_rank 等字段,将成为后续 AI_TASK 节点 Prompt 中可引用的变量。