WeKnora 二次开发与集成指南

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

目标是把 WeKnora 用作可升级的知识内核，同时让行业助手和客户差异保持在自有产品层。此文基于 v0.8.2 的官方扩展点指南及本地源码静态核查；命令是将来实施参考，本轮未执行服务启动。

1. 先选最小改动路径

这样安排的依据是官方已提供 REST、Go SDK、内置 MCP Server 和多种可注册扩展点。API 总览、MCP 集成、Go SDK。

2. 自有服务对接顺序

1. 版本：按发布 tag 固定源码和镜像；记录 WeKnora 版本、迁移版本、模型/向量库版本。不要用 latest 作为客户环境的长期升级策略。
2. 身份：每客户映射一个工作空间；每个用途发独立 API Key。只读问答用 retrieve/chat，内容导入用 ingest，管理能力单独发放。受限 Key 加 knowledge_base_ids 白名单。平台 Key 只留在控制面，不给助手前端。API 认证和能力。
3. 知识生命周期：自有 source_record 保存源系统 ID、版本、校验和、权限标签和最后同步时间；通过 WeKnora API 建库、导入、查询解析状态；删除/撤权要有对账任务。不要把“上传成功”当作“可检索”。知识 API。
4. 问答：自有 BFF 接收用户身份与场景参数，确定允许的 KB 列表，再调用 knowledge-search 或会话问答；向前端返回答案、引用、版本、延迟和请求 ID。所有工具调用在 BFF 再鉴权。聊天 API。
5. 发布：网站嵌入与 IM 渠道可用于内部试点；对客户可见的统一品牌、多租户菜单、计费和交付门户由自有层负责。嵌入渠道。

3. 九类源码扩展点

表中“入口”与注册机制来自官方扩展点速查表。加一类实现时，同时核对 API、配置、UI、权限、迁移及回归路径。

两个最可能的源码二开

数据源连接器。 实现 Validate、ListResources、FetchAll、FetchIncremental；大数据量额外实现 StreamingConnector 与 checkpoint。保存源端 ID 和游标，区分源端删除、暂时无权限、请求失败；URL 必须经过项目的 SSRF 校验，凭据按原项目加密约定存储。注册 ConnectorMetadataRegistry 后再补 UI 元数据和同步测试。详见连接器实现指南。

Agent 工具。 types.Tool 要提供名称、描述、JSON Schema 参数和 Execute；还需更新可选工具定义，并在 Agent 初始化时注册。对“写 CRM、改价格、发消息”先做外部工具，经自有策略网关校验用户、资源、参数及审批；只有确有必要才内置到 WeKnora。官方实现说明和源码定义可作为起点。

4. 分支与升级纪律

• 保留 upstream 指向 Tencent/WeKnora，客户差异用自有仓库和配置管理；若必须 fork，按 feature/connector-*、feature/parser-* 划小改动，不在同一提交重写 API 和数据库。
• 每次升级先读目标版本 CHANGELOG，再检查数据库迁移、API 字段、Agent 工具名、嵌入 token 与镜像标签。v0.8.2 的对话/嵌入和工具改动提示了这一必要性。更新记录。
• 对外保持自有 KnowledgeAdapter 接口，隔离 WeKnora API 变更。记录上游 SHA、内部补丁、对应客户、合并状态和回退方案。
• 不把测试密钥、客户文档、.env 和导出的会话数据提交到 fork；生产前复核 LICENSE 与第三方通知。

5. 最小回归集

官方开发指南描述构建和测试命令；本轮没有执行它们。