知识基座参考架构与接口契约

研究归档：本篇保留2026年9月30日前后的本地公开资料研究。开源版本、功能、许可和星数属于当时快照；技术决策应复核所列官方来源。架构与交付计划为参考设计。

状态：拟建架构，2026-09-30。底层能力对照 WeKnora v0.8.2 架构、租户鉴权和API 总览；以下自有控制面、BFF、策略网关、接口与数据表尚未开发。

1. 组件和责任

flowchart LR
  U[销售 / 店员 / 管理员] --> UI[自有 Web / 移动 / IM 入口]
  UI --> BFF[自有 BFF 与身份/策略网关]
  BFF --> CP[控制面：租户 / 模板 / 配置 / 审计 / 用量]
  BFF --> KA[KnowledgeAdapter]
  KA --> WK[WeKnora 标准版]
  KA -. 评测后可切换 .-> RF[RAGFlow 适配器]
  WK --> KB[(客户空间与知识库)]
  CP --> ING[同步编排 / 源数据登记 / 对账]
  ING --> WK
  BFF --> TG[受控工具网关]
  TG --> BUS[CRM / ERP / POS / OA]
  WK --> MG[模型网关]
  BFF --> OBS[评估 / Trace / 告警]
  ING --> OBS
  TG --> OBS

控制面存客户、组织映射、模板/配置、来源记录、审计和计量，不直接保存一份重复的全文知识。知识面由 WeKnora 承担文档解析、分块、索引、检索、回答、引用与 Agent 基础能力。业务工具面从 CRM/POS/ERP 等系统取得实时数据，写动作只能从策略网关出去。自有 BFF 是员工和 vibecoding 生成应用唯一可见的后端；不把 WeKnora 管理 Key 暴露给浏览器。

2. 租户、身份与授权

WeKnora 的空间 RBAC 和 API Key 是一层能力，不代替我们的业务层策略。尤其需要测试 WeKnora 文件直链配置：其文档支持 resource_urls=public，面向企业客户默认应保留鉴权代理模式，只有经客户安全评估才能公开资源 URL。模型供应商、联网搜索、MCP 和沙箱的出网范围也按客户政策单独配置。

3. 数据模型与生命周期

自有控制面建议最小实体：

入库状态机：discovered → authorized → fetched → parsed → indexed → verified → published，失败进入 failed/retry，撤回走 revoked → unindexed → verified_deleted。这是自有编排的建议，不声称 WeKnora 原生按同样名称建模。每条记录保留源端 ID 与内容散列；更新创建新版本，旧版本在新索引验证后失效；源端删除或权限撤销必须触发索引删除和引用资源复验。同步延迟、失败率和不可检索队列要在控制台可见。

知识与事实分流：政策、培训、话术、产品说明等适合入库；今日库存、实时价格、订单/商机状态等由工具实时查询，返回系统时间戳。检索答案若涉及有效期，引用的文档版本、生效/过期时间进入响应；存在冲突时提示冲突来源并转人工确认。

4. 给上层应用的稳定接口（拟建）

接口由我们定义并实现，不能误当成 WeKnora 原生路径。公开 API 用租户用户令牌，服务端再转换为范围化内核凭据：

POST /v1/assistants/{assistant_id}/responses
Authorization: Bearer <user-token>
Idempotency-Key: <client-generated-key>
Content-Type: application/json

{"conversation_id":"optional","message":"客户说太贵怎么办？","context":{"store_id":"s-01","opportunity_id":"o-42"}}

{
  "request_id": "...",
  "answer": "...",
  "confidence_policy": "answered|needs_review|no_evidence",
  "citations": [{"source_id":"...","document_version":"...","title":"...","locator":"...","effective_at":"..."}],
  "actions": [{"type":"create_crm_task","status":"requires_confirmation","summary":"..."}],
  "trace_id": "..."
}

另提供 POST /v1/knowledge/search（只返回获授权的证据）、POST /v1/feedback、GET /v1/assistants、POST /v1/tool-actions/{id}/confirm。所有写接口需幂等键、审计和授权。KnowledgeAdapter 最小方法：createCorpus、upsertDocument、deleteDocument、indexStatus、search、answer、getCitation、health；适配器把 WeKnora/RAGFlow 的库、文档、引用与错误映射为自有契约。不要用“最小公分母”抹掉能力差异：高级分块/图谱可放在可选 capability 字段。

5. 回答与业务工具执行链

1. BFF 从令牌取得用户、客户、门店/团队；忽略前端提交的 tenant_id 权威性。加载该助手发布版本和可访问资源策略。
2. 判断问题是否需要实时事实；先由策略网关调用只读业务工具或检索知识。发给内核的 KB 范围取用户授权、模板范围和租户范围的交集。
3. 根据检索证据生成回答；BFF 校验引用仍可读、版本未撤回、生效时间有效。无依据、引用冲突或高风险主题触发拒答/人工转交策略。
4. 对模型建议的写动作只产生 requires_confirmation 计划；用户确认后，工具网关重新鉴权、校验参数与幂等键，再调用业务系统并记录回执。高风险动作进入客户审批链。
5. 记录 trace、延迟、模型消耗、知识版本、工具结果和反馈，用于运营分析；日志内按字段脱敏。

6. 部署、运维与发布

• 共享控制面 + 多空间：面向接受逻辑隔离的低敏客户；需通过租户穿透测试、资源引用测试和运维人员权限审计。空间不是独立数据库。
• 每客户专属实例：面向敏感数据和专属 SLA，独立网络、存储、密钥、模型网关、备份与升级窗口。自有控制面可统一看健康状况，但不得跨实例读取客户正文。
• 客户自有环境：用相同发布包和配置契约交付；明确升级、补丁、备份恢复、模型可用性和连接器支持责任。

版本固定为上游 tag + 我方适配器版本 + 模板版本 + 数据迁移版本。发布前在脱敏数据集验证权限、增量更新、问答评估和工具调用；先灰度一个客户/门店，再扩大。备份需要覆盖控制面库、WeKnora 数据库、对象文件与密钥恢复材料；恢复演练应验证“答案的引用和原文同版本”。监控至少覆盖同步滞后、解析失败、队列、检索/模型延迟、无证据率、越权拒绝、工具失败与单位有效回答成本。具体 RPO/RTO、留存期、SLA 在客户合同中设定，本方案不编造数值。

7. 尚需用 POC 验证的架构问题

WeKnora v0.8.2 的多空间/Principal 模型在所需规模下的边界、文件引用与嵌入渠道的跨租户行为、源端 ACL 能否精准投影、删除后的索引收敛时间、解析高峰资源、沙箱隔离、模型出网策略、升级迁移与成本。每项对应交付验收测试；未验证前不在销售材料中写成保证。