> 把散落的文档，养成一座「会自己整理书架、还会写百科」的图书馆
>
> 研究对象：Tencent/WeKnora（腾讯开源 LLM 知识平台 —— RAG 问答 · ReAct Agent · AI Wiki 三模一体）
> 研究时间：2026-08-16 ｜ 方法：浅克隆仓库（3067 文件）一手代码取证 ＋ README/CHANGELOG/ROADMAP/技术文档静态深读 ＋ 外源检索（官网、微信公众号首发文、第三方横向评测、GitHub API 真值）。凡推断处标「【推断】」，代码/文档明示标「【代码证实】」「【文档证实】」
> 一手材料：weknora-research/（克隆副本）；取证要点散见 internal/、docs/、mcp-server/、CHANGELOG.md
—
〇、费曼视角 · 一句话讲清
设想你接手一座巨大的图书馆，书堆得满地都是。传统 RAG 工具像个只会按关键词找书的学徒——你问一句，它翻出几页递给你，书还是乱的。
WeKnora 想做的，是一座「活图书馆」：
1. RAG 问答＝你问「某合同第几条第几款」，它不光翻出书页，还用黄笔把出处标好（答案自动溯源）； 2. ReAct Agent＝它雇了个图书管理员，你丢一句「帮我写份竞品分析」，管理员自己规划：先查三个书库、再上网搜最新数据、再调个算表工具、最后写成带引用的报告——全程自主，关键动作还可设人工审批； 3. Wiki 模式＝最妙的一招：管理员读完原始书，会自动改写成一本本互相链接的百科词条，且新书入库时，这本百科自己更新、自己维护，还带修订历史与一键回滚。
一句话：WeKnora 不是「问答机」，而是把文档吃进去、吐出「可检索、可推理、可自演化」知识资产的流水线工厂。 其野心，是用一套模块化内核，把 Dify 的「应用编排」与 RAGFlow 的「深度解析」之间的空档，连成「检索—推理—沉淀」的闭环。
—
一、它到底是什么（基本档案 ＋ 三大核心模式）
1.1 基本档案
| 项 | 内容 |
|---|---|
| 定位 | 开源 LLM 知识平台（知识引擎/框架）：将原始文档转化为「可查询 RAG ＋ 自主推理 Agent ＋ 自维护 Wiki」三位一体 |
| 出身 | 腾讯 · 微信对话开放平台核心文档理解与检索框架，2025-08 开源（仓建于 2025-07-22） |
| 官名 | WeKnora（维娜拉）；官网 weknora.weixin.qq.com |
| 当前版本 | v0.7.2（2026-08-07） |
| 许可 | MIT（腾讯前言 ＋ MIT 条款；外源多误记为 Apache，以 LICENSE 为准）【代码证实】 |
| 语言/栈 | 后端 Go 1.26；前端 Vue/TypeScript；文档解析 Rust(anydoc) 经 cgo 链接；MCP 服务 Python；另有微信小程序（miniprogram） |
| 体量 | 3067 文件；GitHub ★19,911 / fork 2,863 / open issues 546 / 订阅 95（2026-08-16 真值）【GitHub API】 |
| 形态 | Docker Compose（profiles）、K8s(Helm)、Lite 版、离线支持；界面 Web UI / REST API / CLI / Chrome 扩展 / 小程序 |
| 协议友好度 | MIT，商业可自由嵌入并商业化，无附加条款（对比 RAGFlow 之 SSPL） |
1.2 三大核心模式【文档证实】
1. RAG 快速问答（Quick Q&A）——基于知识库的检索增强生成，BM25 ＋ 稠密 ＋ 知识图谱（GraphRAG）混合检索，答案自动标注来源、规避幻觉。 2. ReAct Agent 自主推理——渐进式多步推理，自主编排「知识库检索 → Web 搜索 → MCP 工具 → 代码沙箱」；MCP 工具调用可设人机审批工作流；支持自定义智能体配置。 3. Wiki 模式（v0.5.0 GA）——Agent 将原始文档蒸馏为自维护、互链的 Markdown 知识库，带交互式知识图谱、手动编辑、修订历史与一键回滚；支持万级文档体量，持续自动更新演进。
> 三者并非孤岛：Agent 既能检索 RAG，也能读写 Wiki（17 个 Wiki 工具），Wiki 又反哺 RAG 检索——「检索—推理—沉淀」自洽闭环，乃其差异化骨架。
—
二、架构深读（分层 ＋ 模块证据 ＋ 技术栈矩阵）
2.1 分层架构（由 internal/ 目录与 docs/architecture.png 还原）【代码证实】
WeKnora 采用整洁分层（clean-ish architecture），依赖方向清晰：
接入层 cmd/(server,desktop,download) · router/ · handler/ · im/(9 路 IM) │ 应用层 application/(repository, service) · container/(DI) · runtime/(server,startup) │ 能力层 agent/(engine,tools,memory,skills,approval) · mcp/ · sandbox/ models/(chat,embedding,rerank,vlm,asr,provider,limiter) │ 基础设施 infrastructure/(chunker, docparser, web_fetch, web_search) datasource/connector · searchutil · retriever/(10 路后端) │ 横切 tracing/langfuse · middleware/asynqdl(异步队列) · event/ · redislock storageurl · storageallowlist(SSRF) · ratelimit · config · logger
关键观察：
– internal/agent 是真正的「心脏」：engine.go（executeLoop 主循环 ＋ runReActIteration 单步 think → analyze → act → observe）、think.go/act.go/observe.go/finalize.go 构成标准 ReAct 四段式【代码证实】。引擎跨轮无状态（每轮从 DB 重建历史），配 tokenEstimator 管理上下文窗、memoryConsolidator 做 LLM 摘要式「强制合并」记忆、modelcontext.Registry 做请求级模型句柄边界、ImageDescriberFunc（VLM）描述工具结果中的图片、skills.Manager 做技能「渐进式披露」（Progressive Disclosure）、event.EventBus 发事件、tracing/langfuse 埋 span。
– internal/sandbox 是第二颗复杂心脏：cube_remote_client.go（腾讯 Cube）、e2b_remote_client.go（E2B）、docker.go、local_unix.go/local_windows.go 多后端；session_binding_redis.go 用 Redis 做多实例会话绑定；orphan_reaper.go 回收孤儿沙箱；url_guard.go 做 SSRF 防护；envd_compat_transport.go 兼容 E2B envd 协议。这是生产级沙箱子系统，非玩具。
– internal/infrastructure/chunker ＋ docparser：分块与解析解耦，解析器可插拔（内置/MinerU/anydoc）。
– internal/datasource/connector：飞书/Notion/语雀/RSS 等数据源同步。
– internal/im：9 路 IM 渠道接入（企微、飞书、Slack、Telegram、QQ、钉钉、云之家、Mattermost、微信＋Lark）。
2.2 技术栈矩阵（由 go.mod ＋ docs/ ＋ CHANGELOG 取证）【代码证实】
| 维度 | 选型（广度罕见） |
|---|---|
| 文档解析 | firecrawl/anydoc/go（Rust，cgo 链接，musl/gnu 预编译库）＋ MinerU ＋ DocReader(OCR/扫描件回落) |
| 向量/检索后端（10 路） | postgres(pgvector)、elasticsearch(v7/v8)、opensearch、milvus(v2.6)、qdrant(v1.18)、weaviate(v1.37)、tencentvectordb、doris、neo4j(知识图谱)、sqlite(Lite) |
| 对象存储（每工作区多实例） | local / MinIO / S3 / COS / TOS / OSS / KS3 / OBS |
| LLM（20+） | OpenAI、Azure、Anthropic、DeepSeek、Qwen、智谱、混元、Gemini、MiniMax、Ollama…（走 OpenAI 兼容协议） |
| 嵌入 / 重排 | BGE/GTE/OpenAI 兼容；重排 BGE/Cohere/Volcengine/vLLM |
| 沙箱 | 腾讯 Cube ＋ E2B ＋ Docker ＋ local，Redis 会话绑定 |
| 异步任务 | asynq（Redis 支撑）＋ 分级 worker 池治理 |
| 观测 | Langfuse（v0.7.1 起迁 OTel/OTLP，W3C traceparent 跨服务传播） |
| 安全 | AES-256-GCM 加密、SSRF 防护（统一 SSRF-safe HTTP transport）、gRPC TLS、Redis TLS、RBAC 4 级角色 ＋ 审计日志、OIDC |
| 部署 | Docker Compose（profiles: default/full/neo4j/minio/langfuse）、Helm/K8s、Lite 版、离线 |
> 最硬的一手证据：检索后端竟达 10 路（retriever 目录实测列出 doris/elasticsearch/milvus/neo4j/opensearch/postgres/qdrant/sqlite/tencentvectordb/weaviate）。此广度在开源 RAG 界属第一梯队，远超多数竞品「绑定 1–2 个向量库」的现状——是其「模块化知识引擎」定位的实体兑现。
—
三、三大能力取证
3.1 RAG 与「自适应三级分块」【文档证实 · docs/CHUNKING.md】
分块是 RAG 召回的命门。WeKnora 的分块子系统有独到之处，值得单表：
– 自适应三级策略：auto（文档画像器先数结构信号——Markdown 标题、换页符、章节标记、全大写行、视觉分隔——再选最强档）、heading（按 #/##/### 切，嵌入时前置「面包屑」上下文头）、heuristic（按换页/编号/多语种章节标记切）、legacy（递归分隔符切分，兜底）。
– 父子分块（Parent-Child）：子块小（384 字符）用于向量匹配，父块大（4096 字符）回灌 LLM 上下文。
– 实证基准驱动：文档自陈基于 Vecta Feb-2026 基准（50 篇论文），递归切分 ~512 token/15% 重叠 = 69% 端到端准确率，优于语义切分；故以之为基、上叠结构感知策略。
– UI 预览：KB 编辑器内「分块预览」对示例文本只读跑切分（5s 超时、不写库不调 API），展示所选档位、被拒档位及理由、文档画像、分块尺寸统计——把分块变成可调试的一等公民。
> 【推断】这套「文档画像 → 策略链 → 验证回退 → UI 可视化」的分块工程，正是其相对「丢给 LlamaIndex 默认切分」类方案的可感知差异点；也是其自诩「模块化文档处理」的核心抓手。
3.2 ReAct Agent：从「问答」到「办事」【代码证实】
agent/engine.go 明示 AgentEngine is the core engine for running ReAct agents，runReActIteration 单步即 think → analyze → act → observe。工具集之丰，是其「自主推理」的实体支撑：
| 工具族 | 代表工具（部分） |
|---|---|
| 知识检索 | knowledge_search、grep_chunks、list_knowledge_chunks、query_knowledge_graph、get_document_info、faq_snippet |
| 网页 | web_fetch、web_search |
| Wiki 编辑（17 个） | wiki_write_page、wiki_read_page、wiki_replace_text、wiki_link_mutation、wiki_rename_page、wiki_flag_issue… |
| 记忆 | search_memory、search_conversations |
| 沙箱执行 | shell_exec、sandbox_ls、sandbox_read |
| 数据分析 | data_analysis(DuckDB)、database_query、data_schema |
| 技能/MCP | skill_execute/skill_read、mcp_tool/mcp_oauth |
| 规划/思考 | sequentialthinking、todo_write、think_stream |
> 注意：Agent 能直接读写 Wiki——这意味着「Wiki 模式」不是离线的批处理蒸馏，而是 Agent 在对话中持续维护知识库的能力闭环。再配以 approval/gate.go 的人机审批、memory.Consolidator 的强制合并记忆、VLM 图像描述，已是一套接近「知识工作智能体」的成形系统，而非简单问答 bot。
3.3 Wiki 模式：文档自动蒸馏为「活百科」【文档证实】
– 官方文档站 docs/wiki/ 本身即一部双向链接互链知识网（MOC 结构，所有页面通过双向链接关联）【文档证实】。
– 由 Agent 将原始文档蒸馏为结构化、互链的 Markdown Wiki，支持万级文档、持续自动更新；带修订历史、行级 diff、一键回滚、手动编辑【CHANGELOG v0.7.2】。
– 知识图谱：上传文档后自动抽取实体与关系写入 Neo4j（需 NEO4J_ENABLE=true ＋ docker compose --profile neo4j），对话时自动查图谱取相关知识【docs/KnowledgeGraph.md】。
—
四、差异化子系统（为何「不止是又一个 RAG」）
1. 检索后端广度（10 路）：见 §2.2，业界罕见。
2. 多后端沙箱 ＋ 孤儿回收：Cube/E2B/Docker/local 可切换，Redis 绑定多实例会话，orphan_reaper 兜底清理——把「代码执行安全」做成生产级子系统。
3. MCP 双向打通：既是 MCP 消费方（Agent 调外部 MCP 服务、mcp_tool/mcp_oauth，支持对话中 OAuth），也是 MCP 提供方——官方 PyPI 包 tencent-weknora-mcp（v1.1.x，29 个工具），把「建库/检索/问答/管理」暴露给任意 MCP 客户端（Claude/Cursor/n8n…）。
4. 上下文与记忆工程：modelcontext.Registry 做请求级 res:// 稳定别名压缩（v0.7.0），memory.Consolidator 做 LLM 摘要式强制合并记忆，tokenEstimator 管窗口——把「长上下文管理」拆成可观测、可治理的部件。
5. 分级异步治理：v0.7.0 引入 Runtime Queues 仪表盘 ＋ 分级 worker 池（core/post-process/enrichment/maintenance ＋ 弹性池），每模型并发 governor 包裹 chat/embedding/rerank/VLM，Wiki 生成独占池【docs/worker-pool-governance.md】——把「 ingestion pipeline 背压」当一等公民治理。
6. 平台级治理：RBAC 4 级角色 ＋ 审计、平台级作用域 API Key（能力授权 principal 模型）、多实例存储后端、OIDC、共享空间——已具「企业平台」骨架。
—
五、生态与横向定位
5.1 与主流开源 RAG/知识库对照
| 维度 | WeKnora | Dify | RAGFlow | FastGPT |
|---|---|---|---|---|
| 官方定位 | 知识引擎/框架 | 全栈 AI 应用编排 | 企业级深度文档理解 RAG | 轻量知识库问答 |
| 协议 | MIT | Apache-2.0 | SSPL（SaaS 商用需授权） | Apache-2.0 |
| 文档解析 | anydoc/MinerU/OCR，模块化 | 依赖第三方预处理 | DeepDoc 深度解析（表格/版面顶级） | 基础，复杂表格弱 |
| 检索后端 | 10 路 | 有限 | 内置为主 | 有限 |
| Agent | ReAct ＋ Wiki 自维护 ＋ 沙箱 | 工作流编排 | 弱 | 图形编排 |
| 应用层 | 需自研权限/运营 | 开箱即用 | 内置完善（权限/审计） | 开箱即用 |
| 学习曲线 | 中高（技术向） | 低 | 中 | 低 |
| 知识图谱 | Neo4j GraphRAG | 需外接 | 有 | 无 |
5.2 定位判断【推断】
– WeKnora 是「知识引擎内核」，不是「成品平台」：它的强项是把「文档如何被吃进去、切成什么、存在哪、怎么检索、Agent 怎么用」全部模块化、可替换、可二开；弱项是「开箱即用的应用层」（权限/运营需自建，文档较 Dify/FastGPT 少）。这与微信对话开放平台「把内核输出给开发者自搭」的诉求一致。 – vs RAGFlow：RAGFlow 在「复杂版面/表格深度解析」上仍领先（自研 DeepDoc ＋ 视觉布局分析），且 SSPL 对纯内部使用无碍；WeKnora 胜在一体三模（RAG+Agent+Wiki）、10 路向量库、MIT、Agent 工具丰度。 – vs Dify：Dify 是「应用编排全家桶」，RAG 仅是其中一环；WeKnora 是「RAG/Agent 内核」，可嵌进 Dify 工作流做知识库召回（社区常见组合建议）。 – 与腾讯系关系：WeKnora 即微信对话开放平台核心框架的开源形态，亦有「腾讯云一键部署」——是腾讯在知识引擎赛道的开源支点。
—
六、成熟度与治理（真实数据 ＋ 批判）
6.1 真实 GitHub 健康度【GitHub API 2026-08-16】
| 指标 | 数值 |
|---|---|
| 星标 / fork / open issues | 19,911 / 2,863 / 546 |
| 订阅（watchers） | 95 |
| 创建 | 2025-07-22（开源约 2025-08） |
| 主语言 | Go |
| 许可 | MIT |
| 贡献者（Top） | lyingbug 1803、voidkey 128、begoniezhao 112、dependabot 50、ochanism 38、claude 28、langcaiye 24… |
6.2 迭代节奏（极快）【CHANGELOG】
– v0.7.0（2026-07-17）→ v0.7.1（2026-07-24）→ v0.7.2（2026-08-07）：三周连发三版，每版数十项特性＋缺陷修复。
– 79+ 数据库迁移（000079_*）；文档站 VitePress ~50 页、~360 个 API 端点、~150 环境变量——配置与接口面已具「企业级」体量。
6.3 风险与短板（献疑）
1. ⚠️ bus factor ≈ 1（单核驱动）：lyingbug 一人 1803 次提交居绝对主导（Top2 仅 128），呈典型「大厂单主力 ＋ 协作者零散」格局。虽有大厂背书，长期可持续性仍系于少数核心。
2. ⚠️ 文档主权/滞后：in-repo mcp-server/PROJECT_SUMMARY.md 仍写「21 个工具、最后更新 2025-10、v1.0.0」，与 CHANGELOG 之「29 工具、v1.1.x、PyPI tencent-weknora-mcp」明显不符【代码证实】；ROADMAP 大量条目仍为 [ ]（语义分块、音视频格式、自研模型、官方云端服务、社区组件鼓励等均未勾选）——路线图尚在早期。
3. ⚠️ 协议误传需正名：多篇文章称其 Apache-2.0，实为 MIT（LICENSE 明示），商用最友好——此点当为加分项而非减分项，勿被旧文误导。
4. ⚠️ 旧评测失真：有 2026-06 第三方实测文指「v0.6.2 不支持 Excel/PPT、复杂表格压扁为纯文本」；然 v0.7.2 已明确支持 PDF/Word/Txt/MD/HTML/EPUB/MHTML/图片/CSV/Excel/PPT/JSON 共 10+ 格式【README】。该评测结论对当前版本已过时，需打折。但「复杂表格语义保留依赖解析器（anydoc/MinerU）而非 WeKnora 独有能力」这一点仍成立——表格精度最终由底层解析决定，WeKnora 与同行同此长尾。
5. ⚠️ 重依赖与工具链门槛：需 Go 1.26 新工具链；DuckDB/Neo4j/ES 等重组件；anydoc 走 cgo ＋ Rust 预编译库（musl/gnu），离线/ARM 部署需留意。知识图谱依赖 Neo4j 独立部署（非默认开启，需 profile neo4j）。
6. ℹ️ 学习曲线陡峭：属「框架/内核」而非「成品」，权限、应用运营需自行搭建；i18n 仅界面层，术语曾重构（tenant→workspace 界面改、内部标识不变）。
7. ℹ️ 记忆取舍：v0.7.1 移除了 Neo4j 会话/情景记忆（简化部署、降低基础设施 footprint），但保留 Neo4j 知识图谱；Long-term memory 改由 LLM 摘要式 consolidator 承担。说明团队在「能力」与「部署轻量」间主动取舍。
—
七、本研究之局限
1. 浅克隆（—depth 1）仅见 1 提交：真实提交历史以 GitHub API ＋ CHANGELOG 还原；bus factor 数字来自 API 贡献榜（lyingbug 1803 为榜首，真实总提交数或更高，集中度判断不变）。
2. 未全量构建运行：受限于无完整向量库/Neo4j/DuckDB 运行环境与离线约束，取证基于源码静态阅读 ＋ 技术文档 ＋ 外源，未独立跑端到端基准（检索精度/吞吐依赖官方与第三方评测）。
3. 外源偏差：横向对比多引第三方 2026 年评测，部分基于 v0.6.x 旧版，已就版本落差作校正；Dify/RAGFlow/FastGPT 之结论取其公开定位，未逐一复测。
4. 未读全 3067 文件：聚焦 internal/、docs/、mcp-server/、CHANGELOG/ROADMAP 与 go.mod，关键论断均锚定具体文件/行号。
—
八、结论
WeKnora 是腾讯以「知识引擎」定位开源的一体化平台：RAG 问答、ReAct 自主 Agent、AI 自维护 Wiki 三模合一，工程完成度高、模块化深、检索后端广度（10 路）罕见、Agent 工具集（含 17 个 Wiki 编辑工具、沙箱、DuckDB 数据分析）丰富、协议最友好（MIT）。其真正的新意不在某单项技术，而在把「检索—推理—沉淀」做成可治理闭环——Agent 既能查知识库，也能写 Wiki，Wiki 又反哺检索。
然天下无免费之宴：当前 bus factor≈1（单核驱动）、文档与 ROADMAP 尚在早期（多处滞后/未勾选）、应用层需自研、重依赖与 Go 1.26/anydoc-cgo 门槛仍是不小的采用成本。它更像一座「可深度定制、MIT 友好的知识平台内核」，而非开箱即用的成品——若要立刻上手的成品，Dify/RAGFlow 更直接；若要完全掌控文档入库与推理流程、做自有知识平台内核，WeKnora 值得认真评估。
一句话定评：WeKnora 是腾讯递出的一把「知识工厂钥匙」——三模一体、MIT 开门、后端任挑；只是开门之后，厂房的装修（应用层）还得自己来，且这厂房目前主要听命于一位主力工程师。取法宜取其架构思想与模块化内核，而非期待开箱即满员的生产线。
—
九、引用
– 仓库：https://github.com/Tencent/WeKnora ｜ 官网：https://weknora.weixin.qq.com
– README（多语）：README.md / README_CN.md / README_JA.md / README_KO.md
– 首发文（微信对话开放平台）：https://fuwu.weixin.qq.com/community/develop/article/doc/0002e077cf8da8c1bfb36bff663c13
– CHANGELOG：仓库 CHANGELOG.md（v0.7.0/0.7.1/0.7.2）
– ROADMAP：docs/ROADMAP.md
– 分块指南：docs/CHUNKING.md ｜ 知识图谱：docs/KnowledgeGraph.md ｜ 异步治理：docs/worker-pool-governance.md ｜ 沙箱：docs/sandbox-protocol.md/sandbox-cluster.md
– MCP 服务：PyPI tencent-weknora-mcp（仓库 mcp-server/）
– 第三方横向评测（注意版本落差）：CSDN《开源知识库的「战国时代」》、RAG 开源项目排行榜(2026-05)、dev.to《Tencent just released a RAG framework…》
– GitHub API 真值（2026-08-16）：stargazers 19,911 / forks 2,863 / open_issues 546 / 主语言 Go / 许可 MIT / 创建 2025-07-22
—