跳转到主要内容
# =============================================================
# 2. KNOWLEDGE (知识契约)
# 定义 AI 节点所需的背景知识挂载标准
# =============================================================
knowledge:
  - id: "market_trends_kb"
    description: "亚马逊全球市场趋势知识库"
    
    # [模式声明] 
    # VDB_DIRECT: 引擎负责向量化及物理检索
    # SEMANTIC_API: 引擎发送文本，服务商返回聚合后的文本
    provider_type: "SEMANTIC_API" 

    # [连接与认证配置]
    config:
      endpoint: "https://api.acme.com/v1/knowledge/search" # 接口 URL 或 VDB 物理地址
      method: "POST"
      timeout: 15
      # 鉴权定义 (秘密注入)
      headers:
        Authorization: "Bearer {{env.KB_SERVICE_TOKEN}}"
      
      # [模式特定参数] - 仅在 VDB_DIRECT 时生效
      vdb_params:
        index_name: "global-trends-idx"
        top_k: 5
        threshold: 0.85
        embedding_model: "text-embedding-3-small"

    # [注入契约]
    injection:
      target_variable: "context_knowledge" # Prompt 中引用的变量名
      max_tokens: 1500                    # 强制截断，防止 Token 溢出
      format: "markdown"                  # 注入格式: text | markdown | json

​
1、参数字段

字段名必填类型说明
id是String资源唯一标识。用于被 Topology 节点通过 knowledge_ref 引用。
provider_type是Enum接入模式。可选值：SEMANTIC_API (语义接口) 或 VDB_DIRECT (向量库直连)。
description否String业务描述。简述该知识库的内容，方便专家编排时理解。
config是Object连接配置容器。包含物理连接、鉴权及模式特有参数。
injection是Object注入契约容器。定义检索结果如何注入 AI 上下文。

​
2、Config 检索策略

参数名必填类型说明
endpoint是String访问地址。API URL 或向量库物理 Endpoint。支持 {{env.XXX}} 注入。
method是Enum请求动词。通常为 POST（用于发送 Query 报文）。
timeout是Integer超时限制(秒)。建议范围 10-30 秒。
headers否Map鉴权与自定义头。【安全核心】 必须配合 {{env.KEY_NAME}} 使用，实现秘密注入。
vdb_params条件Object**当 **provider_type: VDB_DIRECT时必填 。定义物理检索策略。
vdb_params.index_name是String物理索引名称（如 Pinecone 的 Collection 名）。
vdb_params.top_k是Integer检索返回的片段（Chunks）数量。
vdb_params.threshold是Float相似度过滤阈值 (0.0 - 1.0)。低于此值的噪声将被过滤。
vdb_params.embedding_model否String指定执行引擎应使用的向量化模型（如 text-embedding-3-small）。

​
3、Injection 注入模式

参数名必填类型说明
target_variable是StringPrompt 引用变量。在 Prompt 模板中通过 {{target_variable}} 引用检索到的背景知识。
max_tokens否Integer【工业护栏】。强制限制注入内容的 Token 长度，防止成本失控或上下文溢出。
format否Enum注入格式。可选值：text (纯文本), markdown (结构化), json (对象)。

​
4、执行流行为 (Execution Logic)

当一个 AI_TASK 节点通过 knowledge_ref 挂载了该资源时，执行引擎的动作流如下：
  1. 动态向量化: 引擎提取当前节点的输入或 Prompt 中的关键词，生成 Query Vector。
  2. 契约检索: 引擎根据 index_name 连接物理库，并应用 top_k 和 threshold 过滤规则。
  3. 上下文注入: 引擎将检索到的结果填充至 target_variable 声明的变量中。
  4. 模型调用: 将完整的、增强后的上下文发送给大模型（RAG 过程完成）。