深潜 4：个人 Wiki 架构篇

三层架构：从信息摄入到知识输出的完整管线

这个个人 Wiki 系统的架构设计体现了清晰的关注点分离：入口层（Entry）负责解析与路由，管线层（Pipeline）负责收集、整理与交付，能力层（Capability）则提供了 6 种 Reader 外加 Organizer 和 Deliver 子模块。这不是一个简单的”扔文档进去、用 LLM 查”的 RAG 系统，而是一条从原始信息到结构化知识的完整加工管线，每一层都有明确的职责边界和输入/输出契约。

入口层的解析与路由解决了”信息从哪里来”的问题。一篇网页、一个 PDF、一段聊天记录——每种格式需要不同的解析策略。路由则决定这些信息应该进入哪条处理管线。管线层是核心，它的”收集-整理-交付”三阶段映射了人类认知的基本流程：先广泛收集相关素材，再整理提炼为结构化的中间表示，最后根据用户需求以合适的格式交付。能力层是管线的执行者，6 种 Reader 分别处理不同类型的输入源，Organizer 负责结构化，Deliver 负责格式化输出。

Web-Reader 案例：多路径探索与聚合策略

以 web-reader 的能力构建为案例，可以看到这个架构在实践中的深度。web-reader 面临的核心问题是”如何可靠地抓取网页内容”——这个问题看似简单，但在实际中充满了边缘情况：SPA 应用需要 JS 渲染、某些网站反爬、内容可能动态加载。架构中的应对策略是多路径探索：同时维护 Lightpanda、Headless Chrome、Puppeteer 和 Playwright 四条路径，根据目标网站的特征自动选择最优方案。

这种冗余不是浪费，而是对网页复杂性的务实回应。聚合策略更加精细：先用 CLI 快速验证页面是否可抓取，再用子 Agent 对抓取结果进行测试和评估，最后通过循环优化不断提升抓取质量。整个过程通过技能封装对外暴露为一个简洁的接口——调用方不需要知道底层有四种渲染引擎在竞争，只需要调用 read_web(url) 就能获得最佳结果。这是好的架构设计的标志：复杂性被封装在内部，对外呈现简单一致的抽象。

软硬分离：LLM 语义理解 + 固定程序 IO 捕获

这个 Wiki 系统最核心的洞察是软部分与硬部分的分离。”软部分”指 LLM 承担的语义理解任务——判断内容是否相关、提取关键信息、生成摘要和组织结构。这些任务依赖模型的理解能力，天然适合 LLM。”硬部分”指用固定程序承担的 IO 和抓取任务——HTML 解析、网络请求、文件读写。这些任务有明确的规则和边界，用固定程序执行更可靠、更快、更便宜。

这种分离很像机器学习中的”训练数据 + 模型训练”分工：硬部分负责高效、准确地获取和预处理数据（相当于训练数据准备），软部分负责从数据中提取语义价值（相当于模型训练）。很多人做 Agent 或 RAG 系统时把所有事情都交给 LLM——包括”帮我把这个网页下载下来”——结果不仅慢、贵，而且不可靠。正确的做法是：让 LLM 做它擅长的事（理解），让程序做程序擅长的事（执行）。这个 Wiki 系统的架构清晰地体现了这一原则，也是它能稳定运行的基础。