WeKnora：把文档变成"活知识"的三层引擎

如果只看一眼 README，WeKnora 像是又一个 RAG（Retrieval-Augmented Generation，检索增强生成）问答系统。但放进"企业知识库"这条赛道里对比，它真正想解决的问题比问答更进一层：文档入库之后，如何让它持续保持可用、可推理、可治理。大多数轻量 RAG 方案在团队规模越过十人之后开始失灵，失灵点不在检索精度，而在没人维护。

WeKnora 是腾讯开源的 LLM 知识平台，后端主体用 Go 编写，当前 31,762 Stars（2026-10-03 实测），最新正式版 v0.8.2（2026-09-24 发布），README 标注 MIT 协议，可完全私有化部署，2025 年 7 月建仓。它的定位可以压缩成一句话：把原始文档变成可查询的 RAG、能自主推理的 Agent，以及一份自动维护的 Wiki。它也是微信对话开放平台背后的知识框架，经历过一轮真实的企业级部署。

目录

• 1. 核心判断：三层能力的垂直整合
• 2. 系统地图：一条从文档到 Wiki 的回路
• 3. 检索层：RAG 回答有据可查
• 4. 推理层：ReAct Agent 与沙箱边界
• 5. 沉淀层：Auto-Wiki 让知识反哺文档
• 6. 一次任务如何流过三层
• 7. 长期记忆与知识治理
• 8. 工程侧的企业化配置
• 9. 上手路径与最小闭环验收
• 10. 常见问题与排查
• 11. 适用边界与采用顺序
• 12. 参考来源与口径说明

1. 核心判断：三层能力的垂直整合

WeKnora 的差异化不在单点能力，而在三层能力的垂直整合。多数开源项目只做第一层；做到第二层的通常会引入安全隐患——Agent 直接操作宿主机；第三层——让 Agent 把原始文档蒸馏成互相链接的 Markdown 知识库，带知识图谱、手工编辑、修订历史和一键回滚——是目前这条赛道里少见的完整实现。

三层共享同一套知识库和检索基础设施，不是三个独立产品拼装。这一点决定了选型时的判断标准：评估 WeKnora 应该用"整合与治理"当标尺，把某一层单独拉出来和专职产品比算法，测不出它的价值。

2. 系统地图：一条从文档到 Wiki 的回路

读这套系统前先分清一条数据回路：文档从入库到变成知识资产，经过解析、切片、索引，然后被 RAG 和 Agent 消费，最后以 Wiki 的形态回流成新的文档。

 文档（PDF / Office / 网页 / 飞书 / GitLab / RSS…）
   │
   ▼
 入库管线：解析 → 切块(chunk) → 向量化 → 写入索引
   │                        │
   │                        ▼
   │                RAG 检索（关键词 + 语义 + 原文引用）
   │                        │
   │                        ▼
   │                ReAct Agent（检索 + MCP 工具 + 沙箱执行）
   │                        │
   │                        ▼
   │                回答 / 生成文件（Artifact）
   │                        │
   ▼                        ▼
 Auto-Wiki：蒸馏成互相链接的 Markdown 页面 + 知识图谱
   │                        │
   └────── 修订历史 / 版本回滚 ──────┘

两个组件决定了这条回路的边界。解析在 0.6.0 时代全部由独立的 Python 服务 docreader 承担，通过 gRPC 与主进程通信；v0.8.0 起 Office 文档改由内置的 anydoc 解析器在 Go 主进程内处理，不再绕道 gRPC，PDF、图片、Excel 等仍走解析服务，转成 chunk 与图片引用。Agent 的执行则被关进沙箱，与宿主机隔开。主进程负责编排，解析与执行都是外挂能力，可以单独替换。

3. 检索层：RAG 回答有据可查

检索层解决的是日常查文档。查询走语义与关键词混合检索，回答附带来源引用，可打开原文核对，多模态文档（扫描件、图片、表格）在入库阶段被解析成可检索的内容。

Agent 侧的检索工具在 v0.8.2 做过一轮收敛：原先分散的 knowledge_search、grep_chunks 等工具合并为 search_knowledge（支持 hybrid / semantic / keyword 三种模式）与 read_document，关键词模式由真正的关键词索引（BM25）服务，取代了旧的全文正则扫描。检索模式不可用时自动回退——向量库答不了关键词请求就转语义，反之亦然，并在结果里注明实际使用的模式。对使用者的含义是：混合检索的口径在不同类型的知识库之间表现一致，不必为每个库手动挑检索方式。

它不追求单点检索算法的极致——框架价值在整合，这一层满足"查得到、有出处"即可。真正影响检索质量的，是入库侧的切片与治理，第 7 节展开。

4. 推理层：ReAct Agent 与沙箱边界

推理层解决多步任务。Agent 采用 ReAct（Reasoning + Acting）模式自主编排检索、MCP（Model Context Protocol）工具、租户技能目录和网络搜索，在沙箱中处理文件、运行脚本。

沙箱的边界画在哪里，v0.8.0 和 v0.8.2 给出了两个不同版本的答案，这条演变路线值得单独看：

• v0.8.0 重建了执行环境，把"Agent 能干什么"从权限问题变成隔离问题：技能沙箱提供 Docker / E2B / Cube 三种会话持久化后端，按租户配置网络策略；本地宿主进程后端被移除（BREAKING）；Docker 后端默认关闭，需显式开启（System Settings → Network Security，或设 WEKNORA_SANDBOX_DOCKER_ENABLED=true）——挂载 docker.sock 等于交出宿主机 root，这种能力不能默认打开。
• v0.8.0 曾在容器内降权：所有 Docker exec（脚本、shell_exec、文件操作）以沙箱用户（uid 1000）运行而非 root，并封堵跟随符号链接的 chown 操作，防止逃出工作区。
• v0.8.2 反转了容器内策略（BREAKING）：沙箱命令默认以 root 运行。理由是每个会话独占一个沙箱容器，隔离责任收回到容器边界，不再依赖容器内降权。

同一会话中的多轮任务共用一个沙箱工作区，沙箱里生成的文件会收进消息抽屉（Artifact）供预览与下载。两个版本的取舍方向一致：安全不靠给 Agent 精细授权，靠把执行环境整体关进可丢弃的容器。部署时真正要审的是网络策略与沙箱后端选型，容器内的 uid 反而不是重点。

5. 沉淀层：Auto-Wiki 让知识反哺文档

沉淀层是 WeKnora 区别于大多数 RAG 方案的地方。开启 Wiki 后，Agent 从知识库文档中提取人物、产品和概念，生成互相链接、带来源引用的 Markdown 页面，按主题组织成可浏览的 Wiki，同时构建知识图谱——顺着链接可以查看相关知识。

治理手段同样给在 Wiki 上：页面可直接修订，也可让 Agent 协助维护；版本历史保留每次差异，必要时一键回滚到历史内容。也就是说，知识库不是一次入库就静止的堆料，它自己会演化和被修正。

6. 一次任务如何流过三层

把三层串起来的场景最有代表性：团队有 50 页的产品白皮书与若干会议纪要，想让新同事能查、能对比、还能沉淀出 FAQ。一次"对比这三份方案并给出结论"的任务是这样流过的：

1. 入库：白皮书与纪要上传，或绑定飞书 / GitLab 自动同步。解析服务把 PDF 与 Office 转成 chunk 和图片引用，向量化后写入索引；树形文件夹视图保留上传时的目录结构。
2. 快速问答：新同事先问"方案 A 的部署要求是什么"，走检索层，即时返回并附原文引用，可以点开核对。
3. 多步任务：问题变成"对比三份方案的部署要求、成本与适用场景，给出结论"时，Agent 接棒——先检索三份材料，再调用 MCP 工具查公开价格，必要时在沙箱里跑一段脚本算总账，最后合成带引用的结论。
4. 知识反哺：把这次对比中的结论编辑进 Wiki，或者让 Wiki 模式自动把它吸收成新页面。下次有人问同样的问题，直接命中沉淀层的结果，不再重复检索。

这一趟走完，文档从"躺在库里"变成"有人读、有人改、有人引用"。

7. 长期记忆与知识治理

v0.8.0 引入的跨会话长期记忆分为 profile / preference / fact / task / interest 五类（已在官方 API 文档 website-docs/04-api/02-api-memory.md 核实），采用"自动抽取 + 用户确认"的模式：后台抽取的记忆条目先进入 pending 状态，用户确认后才生效；工作区可整体开关，个人也能单独关闭，另提供 search_memory 工具供 Agent 按需检索。设计上刻意避免全自动写入——记忆条目需要确认才生效，这在"记忆污染"（Agent 记错并强化错误）普遍存在的当下是务实的选择。

检索质量最终取决于 chunk 质量。WeKnora 给了两个少见的治理手段：树形文件夹视图保留上传目录结构，以及 chunk 级编辑带修订历史——检索块可以像文档一样编辑、diff、回滚。检索错误可以在数据侧修正，而不必重跑整个入库管线。

8. 工程侧的企业化配置

• 多源接入：飞书 Wiki / 飞书云盘 / Confluence / GitLab / 腾讯 IMA / Notion / 语雀 / 钉钉文档 / RSS 自动同步；GitLab 与腾讯 IMA 为 v0.8.0 新增，Confluence 与钉钉文档为 v0.8.2 新增。
• 模型无关：v0.8.2 重建模型目录后内置 27 家供应商，含 OpenAI、DeepSeek、Qwen、混元、Gemini、Ollama、LiteLLM 等；Office 文档由内置解析器进程内处理。
• 可观测性：Langfuse 全链路追踪，沙箱操作也产出产品级追踪片段，附运行时任务队列面板与 worker 池治理。
• 权限与安全：多工作区 RBAC，四层角色矩阵 + 资源级所有权 + 工作区级审计日志，v0.8.0 增加 OIDC JWKS 验证，v0.8.2 增加白名单出站模式（SSRF_DNS_WHITELIST_ONLY=true，DNS 解析前拒绝白名单外主机）。
• 技能目录（v0.8.0）：从 ClawHub、SkillHub、Git、ZIP 安装技能并统一管理；长会话上下文压缩与 prompt-cache 标记（压缩工具历史而非截断或重写文件，稳定前缀提升 Anthropic / OpenAI 兼容后端的缓存命中率）。
• 对外集成（v0.8.2）：内置 MCP Server，每个工作区可从 Settings 发布带独立令牌、知识库范围与限速的 MCP 端点，官方生成 Cursor / Claude 等工具的接入配置（旧的 Python mcp-server/ 随之弃用）；Local Browser 模式经 BrowserSkill 扩展驱动用户本机 Chrome / Edge，登录与验证码交回用户处理。
• 客户端：IM 问答覆盖企业微信、飞书、Lark、QQBot、Slack、Telegram、钉钉、Mattermost、微信、云之家，另有网站 Embed 挂件、Chrome 插件、MCP API、CLI 与 DeepSeek Harness 集成。

9. 上手路径与最小闭环验收

WeKnora 支持本地和私有云部署。README 给出的 Docker Compose 路径是四步：克隆仓库、cp .env.example .env 按注释编辑配置、docker compose pull 拉取镜像、docker compose up -d 启动，随后打开 http://localhost 走完引导流程。部署后典型流程：

1. 配置 LLM 供应商（任意 OpenAI 兼容接口或 Ollama 本地模型）。
2. 从数据源接入文档（上传或绑定飞书 / GitLab 等自动同步）。
3. 先用快速问答验证检索质量，再按需开启 Agent 与 Wiki 模式。
4. 通过 IM 渠道把问答接入日常沟通。

从 v0.8.0 之前的版本升级到 v0.8.2 时，先读官方升级说明再动手：.env.example 不再自带默认的 JWT_SECRET / SYSTEM_AES_KEY，已有部署必须保留现有 SYSTEM_AES_KEY，否则已存储的凭据无法解密（详见第 10 节）。

选型阶段建议先跑通一个最小闭环，再逐项验证：“单个数据源 + 快速问答"能拿到带引用、可点开的答案是第一道验收线；通过后再开 Agent 沙箱跑一个多步任务，确认沙箱后端可用（Docker 记得显式开启）；最后开 Wiki 模式，看蒸馏出的页面是否带来源、能否回滚。README 的 feature 列表非常长，企业级特性堆叠的完整度，永远要用自己的数据验证。

10. 常见问题与排查

• Agent 报沙箱不可用：v0.8.0 起 Docker 后端默认关闭。先在 System Settings → Network Security 开启，或设 WEKNORA_SANDBOX_DOCKER_ENABLED=true；仍不行就换 E2B / Cube 后端。本地宿主进程后端已在 v0.8.0 移除，旧配置需要重建。
• 从 v0.8.0 升到 v0.8.2 后凭据解不开、重启后全员掉登录：v0.8.2 的 .env.example 不再带默认 JWT_SECRET / SYSTEM_AES_KEY，并新增 SYSTEM_SIGNING_KEY。已有部署必须保留原 SYSTEM_AES_KEY，丢了它已存储的凭据无法解密；JWT_SECRET 未设置时退化为进程内随机值，重启后登录态失效，多副本部署必须共享同一值。钉钉渠道自 v0.8.2 起仅支持 Stream 模式，旧 webhook 渠道会被迁移。
• 长会话回复越来越慢或内容错乱：检查是否命中上下文压缩。v0.8.0 会把过长的工具历史压缩而不是截断文件；配合 prompt-cache 标记观察缓存命中率。
• 检索结果不准确：先在数据侧修正。chunk 级编辑带修订历史，改完可 diff、可回滚，不需要重跑入库管线。
• 记忆条目不对劲：长期记忆是"自动抽取 + 用户确认”，未经确认的条目不生效；可以在记忆管理界面查看、关闭或清理已保存的偏好与事实。推断所依据的内容已被修改时，确认接口会返回 409，刷新列表后再处理。
• 多数据源同步中断：树形文件夹视图保留目录结构，先在数据源侧确认同步状态，再检查该源的凭据与网络策略。

11. 适用边界与采用顺序

适合：需要私有化部署、多数据源汇聚、对权限和审计有要求的团队知识库场景；希望知识不止于问答还能反哺文档的组织；已经在微信生态里做对话产品、想复用同一套知识底座的团队。

不适合：个人单机轻量笔记（Docker 全家桶偏重）；以英文 SaaS 为主的团队——它的数据源与 IM 渠道围绕飞书、企微、钉钉、语雀、腾讯 IMA 这些中文办公生态建设，Notion 加托管 RAG 的组合对这类团队更省事；需要深度二次开发检索算法的团队（WeKnora 的价值在整合而非单点算法）。

采用顺序：先跑通"单数据源 + 快速问答"最小闭环，验证自己的文档解析与检索质量；确认有价值后，开 Agent 沙箱跑一个真实的多步任务，同时让安全团队过一遍沙箱与网络策略；最后才上 Wiki 模式，把问答沉淀成文档。三步对应三层能力，每一步都有独立的验收线，不需要一次全量铺开。

12. 参考来源与口径说明

• 仓库：https://github.com/Tencent/WeKnora。Stars / Forks（31,762 / 4,242）、语言（Go）、最近推送（2026-10-01）为 2026-10-03 经 GitHub API 实测的瞬时值；建仓时间 2025-07-22。许可证以 README 标注的 MIT 为准（GitHub API 的 license 字段未申报，显示 NOASSERTION）。
• 官方站点与文档：https://weknora.weixin.qq.com/（产品介绍、RAG / Agent / Wiki 三能力说明、沙箱与记忆文档均以此处为准）。v0.8.2 起官方文档统一迁入仓库 website-docs/ 目录，旧 docs/ 路径已删除，引用仓库内文档时注意用新路径。
• 版本变更：https://github.com/Tencent/WeKnora/blob/main/CHANGELOG.md。v0.8.0（2026-09-03）的沙箱重建（移除本地宿主进程后端、Docker 后端默认关闭、容器内 uid 1000 降权）、Artifact、上下文压缩、长期记忆、技能目录、OIDC JWKS，以及 v0.8.2（2026-09-24）的沙箱默认 root、内置 MCP Server、Local Browser、Confluence / 钉钉文档数据源、模型目录（27 家供应商）、.env 密钥变量变更、钉钉 Stream-only，均核对自该文件（releases 列表中 v0.8.0 的下一个版本就是 v0.8.2，无 v0.8.1）。
• 长期记忆五类分类（profile / preference / fact / task / interest）与 pending 确认机制，已在 website-docs/04-api/02-api-memory.md（2026-10-03 版本）核实；空间配置、确认接口 409 行为等细节以该文档为准。
• 第三方架构分析（0.6.0，2026-05-30）：https://martianlee.github.io/kb/2026-05-30-weknora-architecture。docreader gRPC 解析服务、多向量库支持等技术细节转述自该文；其中"解析全走 docreader"反映 0.6.0 时点，v0.8.0 起 Office 解析已转入进程内 anydoc。
• 微信对话开放平台背景、MCP 工具与部署方式转述自官方 README 与第三方项目解读（dev.to，2026-09-17）；“已投入真实企业部署"的表述以此为依据。

结语

检索负责查、Agent 推理负责用、Wiki 负责沉淀，三层之间再用沙箱、记忆确认和 chunk 治理把安全与质量问题做进架构——这是 WeKnora 给知识库品类带来的增量：知识库从检索工具走向知识资产的运营平台。也要留意它的迭代节奏：v0.8.0 到 v0.8.2 相隔三周，两次都带破坏性变更，评估时应锁定版本，把 CHANGELOG 列进验收材料。如果你的团队正在选可私有化的知识库方案，按第 9 节的最小闭环先跑一轮，再决定它进不进候选清单头部。