最近想找一个工程完成度足够高、又能拿来学 RAG 全链路的开源项目，翻了一圈最后停在腾讯开源的 WeKnora 上。它是 MIT 协议、当前版本 v0.8.2，把「文档理解 + 语义检索 + 自主推理」做成了一套可自托管的框架，代码结构比大多数 demo 级的 RAG 仓库认真得多。
我打算用一个系列把它拆开讲。这是第一篇，先建立整体认知：它分成哪几层、为什么主后端用 Go 而文档解析单独拎出一个 Python 服务、一条文档从上传到能被检索中间到底发生了什么。后面三篇分别深入分片机制、检索管线和 Agent 能力。
做 RAG 的人迟早会撞到一堵墙：检索命中率上不去，答案总是缺上下文，或者命中的块跟问题根本不相关。排查到最后，问题往往不在模型、不在向量库，而在最前面那一步——分片（chunking）。
大多数项目的分片逻辑简单粗暴：按固定字符数切，加个 overlap 完事。这在一篇结构规整的文章上凑合能用，但真实世界的文档千奇百怪——有带规范标题的技术手册，有 OCR 出来的、连标题都没有的扫描件，有 FAQ 那样的原子条目，也有长篇叙事报告。用同一把尺子去量所有文档，注定顾此失彼。
WeKnora 的分片器（Go 侧 internal/infrastructure/chunker 包）给出的答案是一套自适应架构。这是系列第二篇，我按源码把它逐层拆开。
分片切好了、向量也建好了，接下来的问题是：用户提一个问题，系统怎么从成千上万个块里捞出最相关的那几个，排好序，再拼成 prompt 喂给模型？
很多人以为这一步就是「算个 query 向量、查一次向量库、取 Top-K」。真做过就知道，这条链路里藏着一堆工程细节：多轮对话的历史怎么带、查询要不要改写、向量和关键词怎么融合、召回一堆重复的怎么办、怎么保证结果既有相关性又有多样性。WeKnora 把这些环节抽象成了一条事件驱动、按需装配的 Pipeline。这是系列第三篇。
前三篇我们一路沿着数据流走下来：架构分层、文档怎么被解析分片、检索管线怎么把内容捞出来排序。但这些都还停留在「RAG」的范畴——用户问一句，系统检索一次、答一句，是被动的。
WeKnora 真正想做的不止于此。它在检索之上搭了一个 ReAct Agent，让系统能自己规划多步任务、调用工具、写代码、开浏览器、还能把一堆原始文档蒸馏成一个自维护的 Wiki。这是系列收官篇，我们看看问答之上的这层「自主推理」是怎么组织的，也顺便给整个 RAG 全链路收个口。
第一篇讲架构全景时提到，WeKnora 横向用「接口 + 注册表」让向量库、模型、存储都可插拔；第三篇讲检索管线时又带过混合召回。这篇番外把镜头对准「可插拔」这三个字本身：它到底怎么做到换一个向量库像改一行配置一样简单。
先说清楚这件事的分量。一个生产级 RAG 系统，向量库选型经常会变：起步用 Postgres 加 pgvector 图省事，数据量上来了想换 Milvus 或 Qdrant，要做全文检索想上 Elasticsearch，部署在腾讯云又想用腾讯云向量库。如果每换一次都要把索引、检索、删除的代码重写一遍，迁移成本会高到没人敢动。WeKnora 用一套分层抽象，把这件事变成了「加一个后端实现 + 改一个环境变量」。
很多人刚开始做大模型应用时，会把上下文理解成“聊天记录”。用户说过的话越多，全部拼接给模型，似乎模型就越了解用户。
但实际情况往往相反。历史消息越长，越容易混入过期信息、无关闲聊和互相冲突的指令。模型还可能因为上下文太长而超出限制，或者忽略真正重要的内容。
科学的上下文管理不是尽可能多地塞内容，而是：
每次只给模型完成当前任务所必需、可靠、最新的信息。
大模型很擅长理解人话，也很擅长把结果组织成看起来完整的句子。但在真正的业务系统里，“看起来合理”远远不够。
比如用户让 AI 查询订单，大模型可能返回这样一段内容：
{
"order_id": "12345",
"include_items": true
}
这段内容看上去没有问题，可它只说明模型提出了两个参数。它没有证明订单 12345 真的存在，也没有证明当前用户有权查看这个订单。
因此，大模型应用通常需要连续做三层校验：先确认内容能不能读，再确认格式是否符合约定，最后确认它是否符合真实业务规则。
最近看 Ornith 1.5 时，一个说法很容易让人兴奋：它能自己生成训练任务，所以 Agent 是不是会在日常使用中“越用越聪明”？
我的答案是：**可以形成越用越贴近真实工作的改进闭环，但它不是聊天时自动学习，更不是不需要数据。**真正发生的事情是，系统把已授权的使用信号转成可验证任务，在隔离环境里训练候选版本，再由独立评测决定是否发布。
AI 编程 Agent 的能力在过去一年里突飞猛进。Codex 能重构整个模块，Claude Code 能自主修复 bug，Cursor 能理解整个代码库。但如果你真的让它们跑一个跨越数天的长任务，大概率会收获这样的结果：目标悄悄漂移、同一个错误重试几十次、中断后从头开始、烧了一堆 Token 却看不到有效进展。
LoopX 就是为了解决这个问题而生的。它不教 Agent 变得更聪明，而是给 Agent 装了一套"制度"——让长期任务可控、可追踪、可恢复。