拆解 llm-wiki-compiler 两阶段编译流水线增量编译、快照复用与混合检索的源码级解析【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compilerllm-wiki-compiler 是一个开源知识编译器knowledge compiler把论文、笔记、网页等原始素材编译成带引用溯源、可互相链接的 Markdown wiki。它最硬核的部分是藏在 src/compiler/ 目录里的两阶段编译流水线——先提取概念、再生成页面。配合增量编译、提取快照复用和混合检索三大机制它能在不浪费一次 LLM 调用的前提下让知识库越用越聪明 。这篇文章带你从源码角度用大白话把这条流水线完整拆开。一、两阶段编译先读懂再成文整条流水线的总指挥是 compile()它获取项目锁、恢复崩溃现场后调用 runCompilePipeline() 完成全部工作。它的分工像报社的编辑部阶段对应源码职责类比阶段 1概念提取extraction-phase.ts把每份源文件读给 LLM提取出关键概念记者读完资料列提纲阶段 2页面生成generatePagesPhase()把多份来源的同一概念合并、并行写成 wiki 页面编辑据提纲写出成稿阶段 1 不写任何页面。extractForSource() 会把源文件内容加上当前 wiki 的索引用于去重一起发给模型只产出结构化的概念列表。阶段 2 才动笔。多个来源提到的同一个概念会被mergeExtractions()合并再由 pLimit 控制的并发池并行生成页面——页面越多省下的墙钟时间越明显。两阶段解耦的好处很直观概念提取可以跨来源合并去重而页面生成可以并行、可以被审查策略拦截--review模式互不拖累。二、增量编译SHA-256 哈希决定谁需要重编译每次运行llmwiki compile第一件事不是调用 LLM而是对账。核心在 detectChanges()对sources/下每份文件计算 SHA-256 哈希与.llmwiki/state.json里记录的旧哈希比对把文件分进三个桶new、changed、unchanged消失的则标为deleted见 classifyFile()bucketChanges() 只把new/changed送进 LLM 流水线unchanged的文件一次模型调用都不发生。这意味着给一个已有 200 份资料的 wiki 新增 1 份笔记只有 1 份会过 LLM。同时阶段 1 还会通过迟到影响源循环runExtractionPhases() 中的 while 循环反复检查新提取的概念如果和某些未变化来源旧提取的概念重名会把它们也拉进来一起处理直到没有新增为止——保证跨来源的共享概念始终一致。三、提取快照复用不重问模型也能安全复用如果同一份未变化的来源是某个共享概念页的所有者之一增量机制会跳过它。但阶段 2 生成共享页面时仍然需要知道这份来源当初贡献了哪些概念。重新让模型提取一遍太贵。llm-wiki-compiler 的答案是提取快照代码在 extraction-snapshot.ts快照随状态一起提交snapshotExtraction() 在页面成功写入后把该来源提取出的概念列表、来源哈希和指纹一并记入state.json指纹绑定契约extractionFingerprint() 把提示词版本、提供商、模型 ID、完整提取提示词和工具定义打包哈希。任何一项变了换了模型、升级了提示词旧快照自动作废回退到重新提取——宁可重算不可错用三重校验才复用reusableExtraction() 依次检查快照格式、指纹匹配、来源字节哈希与实时所有权是否完全一致全部通过才返回缓存的概念并把is_new强制置为false避免虚增新概念统计。一句话概括这个设计快照不是提示缓存而是经过校验的已发布元数据——只有字节、契约、所有权三者全对得上才省掉一次 LLM 调用。四、混合检索三级递降永远有答案编译产出的 wiki 如何被问检索入口是 pickSearchRefs()它按精度优先、逐级降级的顺序工作Chunk 级语义检索最高精度对编译期维护的 v3 嵌入库做块级向量匹配命中即返回Page 级语义检索块没命中时用页面级嵌入兜底LLM/索引回退嵌入不可用无 key、无嵌入端点时selectFallbackRefs() 让模型从活的、允许曝光的页面候选里挑选并严格丢弃所有不认识的 token绝不凭空捏造页面。检索命中之后src/context/ 里的上下文构建器见 build.ts 提到的语义检索、图扩展、来源窗口会继续做两件增值的事BM25 重排序把向量初筛的结果按词频信号再排一遍以及wikilink 图扩展——沿页面间的链接关系把直接命中页的邻居页拉进证据包graph.ts。所以混合的完整含义是语义向量 词法重排 链接图三者叠加最后打包成带引用的 evidence pack 交给模型或 MCP 客户端。值得新手注意的健壮性细节嵌入失败不会让整个检索挂掉而是降级为结构化警告embedding-degraded让调用方CLI、MCP、SDK明确知道这次没有语义信号而不是静默地返回空结果。五、速查核心模块地图想了解从哪看编译总编排src/compiler/index.ts变更检测与哈希src/compiler/hasher.ts阶段 1 概念提取src/compiler/extraction-phase.ts提取快照复用src/compiler/extraction-snapshot.ts概念合并src/compiler/extraction-merge.ts混合检索入口src/search/retrieval.ts上下文包构建src/context/build.ts官方概念文档docs/concepts/how-it-works.mdx六、写在最后llm-wiki-compiler 的流水线本质上是把查询时反复读原始文件的成本前置成编译时一次性做对增量哈希让没变的资料零成本快照复用让跨来源共享页不重复提问混合检索让查询始终有三条退路。这套思路对任何想构建可复用知识库的团队都值得借鉴——先读懂再成文省调用别断链 。【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathys LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compiler创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考