Synthadoc：把原始文档编译成本地 Markdown 维基的 AGPL 引擎
Synthadoc：一个开源 LLM 知识编译引擎，可将原始文档转换为结构化的、本地优先的 wiki。传统 RAG 的透明、人类可读的替代方案，无需使用任何工具即可自我管理和自我改进。
秒懂
- 它是什么？
- Synthadoc 在摄取时用 LLM 把 PDF、表格、网页乃至视频转录编译成带交叉引用和矛盾标记的 Markdown 维基，输出可直接放入 Obsidian。它的核心取舍是放弃查询时检索，换取一个不依赖任何工具即可阅读的知识工件。
- 适合谁用？
- 适合需要长期积累、可审计、可人工修正知识库的个人研究者、小型团队以及有本地合规要求的企业。不适合追求实时问答、依赖动态检索增强生成、或无法接受 AGPL-3.0 传染性条款的闭源商业项目。
- 能商用吗？
- 可以，但条件严格。AGPL-3.0 是网络 copyleft 许可证：如果别人通过网络使用你修改过的版本（例如作为托管服务），你必须以同一许可证向他们提供源代码。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月19日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决的是检索之外的另一个问题
传统 RAG 的思路是查询时检索：把文档切块、向量化，用户提问时再拼装上下文。Synthadoc 把这个顺序倒过来。它在摄取时就把原始材料交给 LLM 编译成结构化的维基页面，交叉引用在写入时就建好，矛盾在写入时就标出。README 引用了 Andrej Karpathy 的一句话作为愿景：LLM 应该能替你维护一个维基。这个定位决定了它的适用人群：不是需要即时问答的客服系统，而是需要一份可翻阅、可编辑、可长期演进的知识资产的人。个人研究者、初创团队、有合规要求的部门都在其目标列表里。它的输出是纯 Markdown，不依赖任何运行中的服务就能浏览，这是它与所有在线知识库工具的根本区别。
摄取时编译，而不是查询时拼装
架构上的关键动作发生在 ingest 阶段。新文档进入后，系统不是简单追加一个块，而是用它去丰富和重联整个语料库。README 的原话是 every new source enriches and cross-links the entire corpus。这意味着每次新增材料都可能触发对已有页面的更新，成本与语料规模相关，而不是与单次查询相关。系统会自动构建交叉引用，检测并呈现矛盾，标记孤立页面，每条答案都附来源。这些能力在文档里被描述为自主优化，但自主不等于免费。每次摄取都是一次 LLM 调用，长文档、多格式输入会让 token 消耗显著上升。对于预算敏感的个人用户，README 建议用 Gemini Flash 或本地 Ollama 模型跑零成本方案，这反过来说明默认路径的模型开销并不低。
安装与首次运行：从 PyPI 到你的第一个维基
README 没有给出完整的安装命令块，但仓库结构指向了标准 Python 发布路径。项目以 synthadoc 为包名，源码位于 synthadoc/ 目录，包含 agents 和 skills 子目录，说明编译流程由多个代理角色协作完成。安装大概率是 pip install synthadoc，但这一点需要以实际发布页为准。快速开始指南位于 docs/user-quick-start-guide.md，里面包含通过 MCP 连接 Claude 的附录，以及 agentic workflows 的说明。配置部分在 README 的 Configuration 章节，但具体键值没有在摘要中出现。仓库还带有一个 obsidian-plugin 目录，说明与 Obsidian 的集成不是靠导出，而是有专门的插件代码。hooks 目录的存在意味着用户可以在摄取流程中挂自定义脚本，这对 CI/CD 集成是直接支持的。
四种操作界面：CLI、Obsidian、Web UI 与 MCP
README 的视频列表明确列出了四种交互方式。CLI 适合脚本化和批处理，Obsidian 插件适合日常浏览和手改，Web UI 适合团队共享，MCP 则让 Claude 等外部代理能直接操作维基。这四种界面共享同一套 Markdown 工件，所以不存在数据同步问题。对工程师来说，MCP 接口是最值得注意的设计：它把维基变成了一个可被其他 LLM 代理调用的工具，而不是一个封闭的终点。这意味着你可以让 Claude 在回答问题时自动查阅你编译好的知识库，引用其中的页面。这种设计把编译和检索分离了，编译是离线的、一次性的，检索是外部的、按需的。代价是外部代理只能看到已经编译进维基的内容，原始文档里未被编译的部分对它不可见。
审计日志与钩子系统：企业部署的硬要求
对于中等规模和企业场景，README 强调了审计追踪和钩子系统。每次摄取和每次成本事件都会被记录，这直接服务于合规敏感的本地知识库需求。OpenTelemetry 被列为运维仪表盘的集成选项，说明项目考虑了可观测性。钩子系统允许在流程中插入自定义逻辑，比如摄取完成后自动触发构建或通知。这些特性组合起来，指向一个比个人笔记工具更严肃的定位：它想成为组织内部知识基础设施的一部分。但要注意，审计日志记录的是事件，不是内容正确性。LLM 编译可能产生事实错误，审计能告诉你谁在什么时候加了什么，不能告诉你那个内容是否准确。人工校对仍然是必要的，README 提到的 self-improvement 也暗示了这一点。
AGPL-3.0 许可与维护成本
项目采用 AGPL-3.0 许可证。这意味着如果你修改了源码并以网络服务形式提供给他人使用，你需要开放你的修改版本源码。对于内部部署、不对外提供网络服务的团队，这个限制通常不构成障碍。但如果你计划把 Synthadoc 嵌入到面向客户的 SaaS 产品中，AGPL 的传染性条款会带来实质性的合规负担。维护成本方面，项目更新频率不低，v1.2.1 到 v1.3.1 在两周内连续发布，说明处于活跃开发期。活跃开发意味着 bug 修复快，但也意味着接口可能变动。你的维基是纯 Markdown，不会因为升级而损坏，但你的配置文件和自定义钩子可能需要跟随新版本调整。升级前阅读 changelog 是必须的，而不是可选的。
与 RAG 的对比：这不是替代品，而是另一种工具
README 自称是传统 RAG 的透明、可读的替代方案。这个说法需要限定。RAG 的优势在于查询时灵活性，你可以问任意问题，系统从原始文档中即时检索。Synthadoc 的优势在于编译后的结构，交叉引用和矛盾检测是 RAG 难以直接提供的。但如果你需要频繁查询那些尚未被编译进维基的新文档，Synthadoc 会让你先等一次摄取周期。正确的理解是：RAG 适合动态语料和开放问答，Synthadoc 适合稳定语料和知识沉淀。一个团队完全可以两者并用，用 Synthadoc 做长期知识库，用 RAG 处理临时查询。README 没有讨论这种混合部署，但从架构上看没有冲突。
边界条件：什么时候它明显是错误的选择
如果你的文档集合每天都在剧烈变化，每次摄取都要重联整个语料库，token 成本会快速失控。如果你的使用场景是实时对话式问答，编译延迟会让体验变得笨重。如果你的团队没有版本控制习惯，一个不断被 LLM 改写的 Markdown 仓库会变成混乱之源。README 建议用 git 备份维基，这实际上是一个隐含的前提条件，不是可选项。另外，输入格式虽然覆盖了 PDF、表格、网页、图片、视频等，但视频和图片的解析质量取决于底层模型能力，README 没有给出任何准确率数据。在投入生产前，你应该用自己的样本文档跑一遍，检查编译结果里的事实错误率。这个验证步骤无法跳过。
编辑结论
适合需要长期积累、可审计、可人工修正知识库的个人研究者、小型团队以及有本地合规要求的企业。不适合追求实时问答、依赖动态检索增强生成、或无法接受 AGPL-3.0 传染性条款的闭源商业项目。采用前先验证三件事：你常用的文档格式在 v1.3.1 的解析器里是否稳定，你选用的 LLM 在长文档编译时的成本是否符合预算，以及你的团队是否愿意维护一个不断增长的 Markdown 仓库而不是一个黑盒索引。Synthadoc 的承诺是知识工件本身可读，但这份可读性需要你用版本控制和人工校对去换。
社区笔记