7. 知识库体系

Knowledge System 描述 FlowNex 如何接入、授权、检索、绑定和观测组织知识。

知识库授权与 Skill 绑定框架

7.1 知识库接入目标

知识库接入的目标是让 Agent 回答和执行任务时具备组织依据。

第一阶段目标：

  1. 管理侧可以维护 OpenViking 知识库与本地业务资产的映射。
  2. 管理侧可以维护知识库可见范围。
  3. 用户可以选择本轮知识库范围。
  4. Agent 可以通过 knowledge_search 和 knowledge_qa 检索授权知识。
  5. 检索结果可以作为引用证据进入回答。
  6. 知识命中可以被记录和分析。

非目标：

  1. 不在 FlowNex 内自研组织知识向量检索底座。
  2. 不在本地长期保存知识正文。
  3. 不让运行时文件进入 OpenViking 管理。
  4. 不把用户个人文件无差别入库。

7.2 OpenViking 知识库集成

OpenViking 负责组织知识的检索底座。

在第一阶段，知识库创建、飞书云文档接入、解析、分段、索引构建都在 OpenViking 后台完成。FlowNex 只维护本地映射和权限。

本地系统需要保存：

  1. 知识资产 ID。
  2. 知识资产编码。
  3. 知识资产名称。
  4. OpenViking providerResourceId。
  5. Provider 类型。
  6. 所属租户。
  7. 可见范围。
  8. 本地启停状态。
  9. 检索配置摘要。

这样可以避免知识正文双真相。

7.3 本地知识资产模型

推荐本地知识资产模型包括：

  1. KnowledgeAsset。
  2. KnowledgeMapping。
  3. KnowledgeAcl。
  4. KnowledgeUsageTrace。

KnowledgeAsset

表示本地业务知识资产。

字段建议：

  1. assetId。
  2. tenantCode。
  3. assetCode。
  4. assetName。
  5. description。
  6. assetType。
  7. status。
  8. tags。

KnowledgeMapping

表示本地知识资产与外部知识库资源的映射。

字段建议：

  1. mappingId。
  2. assetId。
  3. providerCode。
  4. providerResourceId。
  5. externalObjectId。
  6. endpointConfig。
  7. retrievalConfig。
  8. scopeVersion。

KnowledgeAcl

表示知识可见范围。

字段建议：

  1. assetId。
  2. tenantCode。
  3. scopeType。
  4. scopeRef。
  5. enabled。

scopeType 可以包括：

  1. TENANT。
  2. DEPARTMENT。
  3. ROLE。
  4. PROJECT。
  5. USER。

7.4 知识授权范围计算

知识授权范围计算必须发生在本地业务系统。

计算输入：

  1. tenantCode。
  2. userId。
  3. 用户角色。
  4. 用户部门。
  5. 用户项目。
  6. 知识资产状态。
  7. 知识映射状态。
  8. 用户本轮手选范围。
  9. Skill 绑定范围。

计算输出：

{
  "tenantCode": "xingyun",
  "userId": 10001,
  "scopes": [
    {
      "assetId": 1,
      "assetCode": "project-sop",
      "providerCode": "OPEN_VIKING",
      "providerResourceId": "kb_project_sop",
      "scopeVersion": 3
    }
  ]
}

授权范围必须在检索前完成裁剪，而不是检索后再过滤。这样可以避免越权知识被召回到中间结果。

7.5 Runtime Knowledge Access

RuntimeKnowledgeAccess 是 control-center 下发给 runtime 的本轮知识访问快照。

它用于告诉 share-harness：

  1. 本轮是否允许知识检索。
  2. 本轮可检索哪些知识库。
  3. 本轮知识范围来自用户手选、Skill 绑定还是默认授权。
  4. 是否存在必需知识缺失。
  5. 是否存在被禁用或被权限裁剪的知识范围。

示例：

{
  "enabled": true,
  "mode": "SKILL_BOUND",
  "providerResourceIds": ["kb_contract", "kb_policy"],
  "requiredMissing": [],
  "trace": {
    "authorizedCount": 5,
    "selectedCount": 2,
    "skillBoundCount": 2,
    "forbiddenDroppedCount": 0
  }
}

运行时不应接收 Provider 凭证、内部 endpoint 配置和未经裁剪的权限信息。

7.6 knowledge_search 与 knowledge_qa

FlowNex 建议在 runtime 中提供两个知识工具：

knowledge_search

用于复杂任务中的资料检索。

适合场景：

  1. 研究。
  2. 分析。
  3. 写作。
  4. 方案生成。
  5. 多段证据引用。

返回内容通常包括：

  1. 文档标题。
  2. 片段内容。
  3. 来源知识库。
  4. 相似度或排序分。
  5. 引用标识。

knowledge_qa

用于直接问答。

适合场景：

  1. FAQ。
  2. 制度查询。
  3. 明确问题。
  4. 简短答案。

如果 knowledge_qa 置信度不足，可以降级调用 knowledge_search 获取更多证据。

7.7 Skill-Knowledge Binding

Skill 与知识库绑定用于把业务能力和业务依据关联起来。

实现分工：

  1. agent-domain-service 保存绑定关系。
  2. control-center 管理绑定并计算本轮最终知识范围。
  3. agent-runtime-gateway 透传 knowledgeAccess。
  4. share-harness 基于 knowledgeAccess 调用知识工具。

绑定类型：

类型 运行时语义
REQUIRED 必需知识范围，无权限或缺失时需要降级或提示
PREFERRED 优先检索范围，召回不足时可以扩展
OPTIONAL 补充检索范围
FORBIDDEN 禁止当前 Skill 使用

最终范围计算：

最终知识范围 =
    用户授权范围
  ∩ Skill REQUIRED/PREFERRED 绑定范围
  ∩ 用户本轮手选范围，如果存在
  - Skill FORBIDDEN 范围

如果 Skill 没有绑定知识，应回退到用户手选范围或用户默认授权范围。

7.8 知识命中观测与引用追踪

每次知识检索都应记录命中轨迹。

建议记录：

  1. tenantCode。
  2. userId。
  3. conversationId。
  4. taskId。
  5. messageId。
  6. skillCodes。
  7. 检索 query。
  8. 检索知识库范围。
  9. 命中文档。
  10. 命中片段。
  11. 最终使用证据。
  12. 被裁剪原因。
  13. token 成本。
  14. 检索耗时。

这些数据用于：

  1. 展示引用来源。
  2. 排查回答依据。
  3. 分析低命中知识库。
  4. 分析 Skill 绑定是否合理。
  5. 识别知识缺口。

7.8.1 业务线能力接入后的知识上下文关系

业务线 AI 能力接入 FlowNex 后，知识库不只服务 Agent 问答，也会成为业务线能力调用时的重要上下文资产。

典型关系包括：

关系 说明
Skill 绑定知识 Skill 执行时默认使用某些制度、模板、案例和 SOP
Capability 绑定知识 原子能力调用前需要特定知识作为参数补充或规则依据
Provider 绑定知识 某个业务线 Provider 只允许访问其业务域内知识资产
Agent 能力包绑定知识 一个业务场景应用默认携带一组知识范围
租户能力开通绑定知识 租户开通某能力时，同步开通与该能力配套的知识资产

例如，差旅报销 AI 应用可能包含：

  1. 报销单识别原子能力。
  2. 发票验真原子能力。
  3. 差旅制度知识库。
  4. 报销流程 Skill。
  5. 财务审批查询 Tool。

运行时需要同时计算能力授权和知识授权：

用户权限
  ∩ Agent 能力包授权
  ∩ Skill 绑定知识
  ∩ Capability 绑定知识
  ∩ 租户可见知识范围
  -> Runtime KnowledgeAccess

原则上，Capability 绑定知识不能绕过用户和租户 ACL。即使某个业务线能力声明需要某知识库，如果当前用户无权访问，该知识也不能被注入模型上下文或传给外部 Provider。

7.9 降级策略与安全边界

知识库系统必须有明确降级策略。

典型降级场景：

  1. OpenViking 不可用。
  2. 知识库超时。
  3. 用户无可用知识。
  4. Skill 必需知识缺失。
  5. 检索结果置信度不足。
  6. 返回结果超出上下文预算。

处理策略：

  1. 普通问答可降级为不使用知识库，但需避免声称有组织依据。
  2. REQUIRED 知识缺失时，业务型 Skill 应提示无法完整执行。
  3. 检索超时时，主链路应尽量继续运行。
  4. 越权知识不得进入 runtime。
  5. 检索结果进入模型前必须经过 token 预算裁剪。

安全边界：

  1. Provider 凭证不下发给模型。
  2. endpoint 配置不暴露给前端。
  3. 未授权知识不进入检索请求。
  4. 被 FORBIDDEN 绑定排除的知识不进入本轮范围。