跳转到主要内容

​
1、统一鉴权框架：RSS-Auth

为了确保协议资产在公开流转时不泄露私钥，同时在运行时具备工业级安全性，Runly 采用以下方案：
  • 秘密占位符 (Secret Placeholder)：在 YAML 中严禁出现明文 Key。使用 {{env.KEY_NAME}} 语法。
  • 运行时注入 (Runtime Injection)：执行引擎在加载协议时，从安全环境（.env 文件、KMS 或 Vault）中提取对应的真实值进行动态替换。
  • 链路追踪 (Trace ID)：所有外发请求必须在 Header 中携带 X-Runly-Trace-ID，用于跨系统审计。

​
2、KNOWLEDGE (知识契约) 集成规范

Knowledge 模块旨在为 AI 节点提供执行背景。支持“底层直连”与“高层 API”两种模式。

​
2.1 、配置规范 (YAML Definition)

knowledge:
  - id: "market_kb"
    provider_type: "SEMANTIC_API" # 模式选择: SEMANTIC_API | VDB_DIRECT
    description: "市场分析知识库"
    config:
      endpoint: "https://api.acme.com/v1/knowledge/search"
      method: "POST"
      timeout: 10
      # [鉴权定义]：通过 env 注入，支持多种 Header 格式
      headers:
        Authorization: "Bearer {{env.KB_API_TOKEN}}"
        X-Provider-Key: "{{env.PROVIDER_SECRET}}"
      # VDB_DIRECT 模式特有参数
      index_params:
        index_name: "global-v1"
        threshold: 0.85
    injection:
      target_variable: "context_knowledge"
      max_tokens: 1500 # 强制截断，保护上下文窗口

​
2.2 、报文规范 (Message Standard)

  • 请求 (Executor → Provider): 发送自然语言查询及上下文过滤器。 
    {
  "header": { "trace_id": "tx-8899", "timestamp": 1738980000 },
  "query": { "text": "ASIN B08N5KXXXX 的竞争情况", "namespace": "us-market" },
  "limit": { "max_tokens": 1500 }
}
  • 响应 (Provider → Executor): 返回清洗后的文本段落。 
    {
  "status": "SUCCESS",
  "data": { "content": "根据检索结果...", "source": ["report_v1.pdf"] }
}

​
3、SKILLS (技能契约) 集成规范

Skills 模块赋予 SOP 改变世界或获取实时结构化数据的能力。

​
3.1、配置规范 (YAML Definition)

skills:
  - id: "amazon_api"
    type: "ACTION_HTTP"
    config:
      endpoint: "https://api.acme.com/v1/market/fetch"
      method: "POST"
      timeout: 15
      max_retries: 3
      # [鉴权定义]
      headers:
        X-Api-Key: "{{env.AMZ_SKILL_KEY}}"
    contract:
      request:
        payload: { "asin": "{{inputs.target_asin}}" }
      response:
        strict_mode: true # 强校验开关
        schema:
          type: "object"
          required: ["price"]
          properties:
            price: { "type": "number" }
            stock: { "type": "string" }

​
3.2 、报文规范 (Message Standard)

  • 请求 (Executor → Skill Service): 包含标准的调用上下文。 
    {
  "auth": { "token": "rk_live_8822..." },
  "context": { "caller_urn": "urn:runly:expert:sop", "trace_id": "tx-8899" },
  "params": { "asin": "B08N5KXXXX" }
}
  • 响应 (Skill Service → Executor): 必须包含状态码与结构化输出。 
    {
  "status": { "code": 200, "message": "OK" },
  "output": { "price": 29.99, "stock": "IN_STOCK" },
  "usage": { "latency_ms": 420 }
}

​
4、 接入开发者 CheckList

为了确保第三方服务能被 Runly 顺利挂载，开发者需满足以下要求：
  1. 鉴权兼容性：支持通过标准 HTTP Header（如 Authorization）接收 Token。
  2. 错误回传：当服务不可用时，必须返回标准的 JSON 错误报文（含 status.code），以便 Runly 执行引擎触发 on_failure 逻辑。
  3. 幂等性：Skill 接口需支持幂等调用，以应对执行引擎的重试机制。
  4. 超时控制：必须在协议定义的 timeout 时间内完成响应，否则将被引擎强行挂断。