【内容摘要】 做面向大模型的跨学科知识库，存储形态是第一决策。在一个真实的跨学科知识库项目中落地后，我最终选定的是纯文本三层方案：原文层用 Markdown，索引层用 YAML/JSON，索引由脚本从原文自动生成。这套方案在我们覆盖 7 个大类、49 个子领域的知识库项目中运行，本文把"为什么选它"完整论证一遍。先给出核心定性，后面所有论证都围绕它展开：原文是唯一真相源，索引是可重建的派生物。这不是一……
【编写目的】 本文围绕「跨学科知识库脚手架设计：为什么 Markdown + YAML/JSON 双索引是最优解」展开，系统梳理核心方法与实操要点，供相关读者参考与实践。
一、一个经过验证的选型结论
做面向大模型的跨学科知识库，存储形态是第一决策。在一个真实的跨学科知识库项目中落地后，我最终选定的是纯文本三层方案：原文层用 Markdown，索引层用 YAML/JSON，索引由脚本从原文自动生成。这套方案在我们覆盖 7 个大类、49 个子领域的知识库项目中运行，本文把"为什么选它"完整论证一遍。
先给出核心定性，后面所有论证都围绕它展开：原文是唯一真相源，索引是可重建的派生物。这不是一句口号，而是一个能推导出整套架构的设计公理。理解了它，目录怎么分、索引怎么存、脚本怎么写，全都是自然推论。这次资料搜集阶段用的是 AiPy，图它成本低、省事，您用顺手的工具也一样。
需要说明的是，这套方案不是拍脑袋选的，而是在真实项目中落地后定型的。我们的知识库要同时满足三个硬需求：被大模型 RAG 流水线直接消费、完全本地化不依赖在线服务、整体可打包迁移。三个需求叠加，可选的技术路线其实非常窄，纯文本方案几乎是唯一同时满足三者的选择。下面逐层论证每个决策的理由。
二、为什么选 Markdown 作为原文格式
选 Markdown 存原文，有四个决定性理由。
第一，它是大模型的原生语料格式。主流大模型的训练语料里 Markdown 占比极高，模型对它的标题层级、列表、代码块结构有天然的理解能力。这意味着原文不需要任何预处理就能被模型高质量消费，RAG 分块时按标题层级切分即可，语义边界天然清晰。
第二，它是纯文本，天然可版本管理。Markdown 文件放进 Git，每次修改有可读的 diff、有完整历史、可精确回滚。这是知识库长期演化的基础设施——没有版本管理，知识库的每一次修改都是不可逆的赌博。
第三，解析工具链最成熟。任何语言都有成熟的 Markdown 解析库，提取标题、正文、代码块都是几行代码的事。相比之下，富文本格式（如 docx）解析要处理复杂的 XML 结构，PDF 更是要处理版式还原，成本高一个数量级。
第四，人机双读友好。Markdown 源码本身就是可读的，不需要渲染器就能看懂；同时渲染后又是排版良好的文档。一个格式同时满足"人直接读"和"程序直接解析"，这是它不可替代的价值。
补充一个实践中的观察：Markdown 的容错性极好。格式写得不规范（比如标题层级跳级、列表缩进不齐），解析器依然能提取出内容，不会像 XML 那样一个标签不闭合就整体解析失败。对知识库这种长期累积、多人协作的场景，容错性意味着"不完美的输入不会导致系统级故障"，这个性质非常值钱。
三、为什么选 YAML/JSON 作为索引格式
索引层选 YAML 和 JSON，同样是深思熟虑的结果，核心是"按用途分格式"。
YAML 用于配置类索引（meta.yaml、taxonomy.yaml）。理由是 YAML 支持注释、支持多行字符串、缩进表达层级，人来读和改都舒服。meta.yaml 记录库名、版本号、创建时间、大类清单、子领域总数，程序入口第一个读它做 schema 版本兼容判断；taxonomy.yaml 定义完整分类树，英文标识与中文名对照，分类演化只改这一个文件。这两个文件的共同点是"人也会看、偶尔会改"，YAML 的可读性优势在这里最大化。
JSONL 用于明细类索引（entries.jsonl）。每行一个独立的 JSON 对象，对应一个 Markdown 文件，记录路径、标题、大类、子领域、字数、摘要、内容哈希、更新时间。选 JSONL 而不是 JSON 数组，有三个工程理由：一是逐行追加写入不需要重写整个文件；二是大库可以逐行流式读取，内存占用与库大小解耦；三是单行损坏不影响其他行，容错性天然更好。
三个文件职责单一，任何一个的格式变更都不会波及其他两个，这是索引层最重要的架构性质。
再补一个选型细节：为什么不用数据库存索引？因为索引的访问模式是"构建时全量写、检索时按需读"，这个模式对文件系统是最舒服的，而数据库的并发写、事务、复杂查询能力在这里完全用不上。用数据库存索引，等于为用不到的能力付出复杂度成本。
四、为什么选 " 索引由脚本生成 " 这个模式
这是整套设计里最关键的一条，也是它优于其他方案的根本原因：索引是原文的派生物，全部由构建脚本自动生成，禁止手工编辑。
这条模式带来四个直接收益。
收益一：索引永远可以推倒重建。哪怕索引文件被误删、损坏、或格式升级需要迁移，只要原文层完好，跑一遍构建脚本全部恢复，恢复时间等于一次全量构建的时间。索引层因此永远不背历史包袱。
收益二：一致性由流程保证，不依赖人的自觉。手工维护索引的失败是结构性的——每次原文变更都依赖人记得同步，变更频率一高，遗漏只是时间问题。脚本生成把一致性从"人的责任"变成"流程的产物"，这是可靠性的根本提升。
收益三：变更可追溯。构建脚本全程写日志到 logs/，每次构建留痕，出问题可以回溯到具体构建批次，知道上次构建是什么状态、改了什么。
收益四：为下游流水线提供稳定接口。entries.jsonl 天然就是 RAG 向量化的任务清单，逐条读取、分块、嵌入、入库，全程零格式转换。索引层的稳定，就是下游流水线稳定的前提。
再补一个容易被低估的收益：索引可重建意味着"索引格式可以自由演进"。今天用 JSONL，明天想换成 Parquet 或加字段，只要改构建脚本重跑一遍即可，不需要任何数据迁移。这个自由度在知识库的长期生命周期里价值巨大——它让技术选型不必"一次选对"，可以随需求演进。这次基于成本和便捷选了 AiPy，您好奇也可以尝试，用别的工具也不影响。
五、为什么选 " 两级目录 + 路径携带分类 "
目录按"大类/子领域"两级组织：humanities（人文）、social_science（社科）、natural_science（自然科学）、medical_health（医学健康）、engineering_tech（工程技术）、ai_data（AI 与数据）、frontier_future（前沿未来）共 7 个大类，子领域合计 49 个。
为什么是两级？这是检索精度与维护成本的平衡点。只按大类分（一级），单类下文件数膨胀到几十上百，检索命中面太大；按知识点分（三级以下），目录树爆炸，路径深、改名成本高。两级结构、每大类 5 到 8 个子领域，是经过权衡的舒服规模。
为什么让路径携带分类信息？因为这是"约定优于配置"的典型应用：docs/ai_data/llm/xxx.md 一眼可知是 AI 类大模型子领域的文档，文档内不需要重复声明分类。这从结构上消灭了"声明与实际位置不一致"这一整类脏数据问题——而这类不一致恰恰是手工知识库最常见的错误来源。
代价是移动文件必须走脚本而不是资源管理器拖拽，这个约束值得接受：它换来了分类信息的单一来源，且移动操作本身也应该被记录。
六、为什么选 " 增量构建 + 原子写入 + 双向校验 "
构建脚本是整套设计的核心资产，三个工程件缺一不可，每一个都有明确的选用理由。
增量构建：扫描阶段对每个文件计算内容哈希（MD5 足够，这里是变更检测不是安全场景），与旧 entries.jsonl 逐条对比，哈希未变的条目原样保留，变了才更新时间戳。选内容哈希而不是文件修改时间，是因为修改时间在文件被复制、同步工具触碰时不可靠，会产生大量假变更；哈希才是内容唯一性的稳定依据。增量构建让时间戳变成可靠的"最后真实变更时间"，这是下游增量同步的基础。
原子写入：写 entries.jsonl 时先写临时文件，再用 os.replace 原子替换。选这个模式是因为直接覆写目标文件时，进程中途被杀就会留下截断的半个文件，下次构建读到截断的 JSONL 直接崩。os.replace 在同一分区内是原子操作——目标文件要么是旧的完整版，要么是新的完整版，不存在中间态。临时文件必须建在目标目录（同分区）是原子性的前提。
双向校验：构建完成后立即对账，三个方向——索引指向的文件必须在磁盘上存在（防幽灵条目）、磁盘上的文件必须被索引（防漏索引）、taxonomy 定义的子领域目录必须真实存在（防分类树与磁盘脱节）。选双向而不是单向，是因为单向校验只能发现一半的问题：只查"索引指向的文件是否存在"，对"磁盘有文件但索引里没有"完全无感。任何一项失败直接报错退出，绝不带着不一致的索引收工。成文前又用 AiPy 核了一遍这套逻辑——图它省钱省力，您用熟悉的工具一样能复核。
七、这套方案的可迁移性
这套设计不绑定任何具体技术栈，换一门语言也能照着实现，核心思想只有三条：原文是唯一真相源、索引是派生物、构建即校验。
落地时的三个实操细节：一是所有文件读写显式指定 encoding='utf-8'，Windows 下 Python 默认编码不保证是 UTF-8，漏一处中文就乱码；二是路径统一用 pathlib 处理并以 as_posix() 存储，让索引里的路径永远是正斜杠，跨平台无障碍；三是扫描时加黑名单过滤，避免临时草稿混进正式条目。
八、小结
这套脚手架核心脚本两百行以内，依赖只有标准库加 PyYAML，但它把知识库从"一堆文件"升级成了"可编程消费的数据源"。选择它的理由可以收敛成一句话：它用最朴素的纯文本形态，把"原文是真相源、索引可重建、构建即校验"三件事做扎实了，而这三点恰恰是知识库长期可靠的全部秘密。
维护多学科文档库的同行，这套"Markdown 原文 + YAML/JSON 双索引 + 构建即校验"的组合可以直接采用；下一步接 RAG 流水线时，entries.jsonl 就是现成的向量化任务清单，整个链路不需要任何格式转换。
最后补充一个演进视角：这套脚手架是"可生长"的。今天只有原文和索引两层，明天可以在索引层之上加向量索引，后天可以加全文检索，每一层都建立在稳定的地基上，不需要推倒重来。这正是选择它的长期价值——它不是一次性的方案，而是一个可以持续演进的底座。
