LLM Wiki：代码 vs. Markdown

AI模型价格对比 | AI工具导航 | ONNX模型库 | Vibe Coding教程 | Tripo 3D | Meshy AI | ElevenLabs | KlingAI | ArtSpace | Phot.AI | InVideo

2026年4月，Andrej Karpathy发布了一个名为llm-wiki.md的GitHub gist。它不是代码，也不是一个产品。它是一个他称之为想法文件的东西——一个用普通散文写成的模式，设计为粘贴到LLM智能体中，让智能体为其用户构建一个定制的wiki。

这个框架很优雅。我们今天对文档所做的大部分操作看起来像RAG：你上传文件，模型检索片段，生成答案，然后遗忘。Karpathy的转折点：不要每次查询都重新阅读原始资料。将它们一次性编译成一个结构化的、互联的wiki。然后查询wiki。像编译器对待源代码一样对待知识——预处理一次，永远快速运行。

我在一个周六读了这个gist。到周日晚上我已经有了一个Python包。一个月后，我将同样的想法重写为一个单独的AGENTS.md文件。两个都能用。两个都是开源的。它们并不冗余——它们是对同一个问题的两种答案，而这个问题是：多少实现应该在代码中固化，多少应该在运行时与智能体协商？

这是对两者的 walkthrough，每个优化了什么，以及如何选择。

1、什么我先选择了程序化方案

我的第一直觉是让它可复现。我处理的是包含数百到数千个文档的语料库——企业手册、法规文本、内部程序——在这些场景下，每次更改时都对每一页运行LLM的成本不是学术性的。Token会累积。幻觉会叠加。当同样的内容需要每次产生相同的wiki页面时，"让智能体好好做"不是一个规范。

所以我写了wiki-llm（可在Github获取）。

架构是Karpathy概述的八个阶段，加固成一个流水线：

几个值得提及的决定，因为它们是将想法转化为团队可以无人值守运行的东西的关键：

• 阶段之间使用Pydantic v2合约。 每个阶段接受类型化输入并返回类型化输出。当Writer将草稿交给Evaluator时，schema是被强制执行的，而不是寄托于希望。
• 确定性的内容可寻址ID。 每个页面的UUID是从其去掉frontmatter的body的SHA-256派生的。相同内容，相同ID——无论文件名、frontmatter或格式如何。重命名源文件，下游不会出问题。
• 通过instructor实现多后端LLM。 OpenRouter、OpenAI、Bedrock、Ollama——相同的代码路径，带有自动重试的结构化输出。
• 使用LangGraph构建的修复智能体。 不是整个流水线——只是lint发现需要通过扇出和审查来解决的那个角落。在智能体能发挥价值的地方使用智能体。
• BM25聊天，无向量存储。 对于个人或团队知识库大小的wiki，词法检索快速、透明且足够好。把嵌入基础设施留给实际需要的时候。
• 一个认真对待结构的Markdown处理层。 这是我稍后会回过头来谈的部分。

该流水线可以在生产环境中作为Kubernetes CronJob运行。聊天UI是一个独立的Deployment。整个东西打包在一个Docker镜像中，通过一个暴露WikiConfig对象的Python模块进行配置。用户只需编写一次配置，流水线会处理剩下的所有事情。

这是对想法文件的程序化回答：每一个操作关注点都被明确化，每一个提示词都被版本化，每一个输出在确定性可能的地方都是确定性的。

2、然后我将其重写为.md

几周后，在帮助一个朋友在几百篇文章上建立个人wiki时，我意识到我在过度工程化。他不需要Pydantic、Kubernetes或修复智能体。他需要的是Claude Code指向一个文件夹，并有足够的结构来像一个wiki维护者而不是聊天机器人。

所以我把同样的八个阶段浓缩到一个文件中：AGENTS.md，加上一个薄的CLAUDE.md垫片指向它。整个东西在同一个仓库中。它可以在任何读取项目根指令文件的智能体上运行——Claude Code、Codex、Cursor、VS Code Agent Mode。

其形式刻意与Python版本接近。相同的阶段，相同的名称，相同的约定：

与程序化版本相比，消失的是：

• Python导入、Pydantic模型、Dockerfile、CI工作流。
• LangGraph修复智能体——被"对于每个断开的链接，通过模糊/语义相似性找到最接近的匹配；如果置信度>80%，替换；否则用TODO标记"取代。
• 确定性UUID。智能体使用slugified标题。
• 聊天UI。如果用户想要聊天，智能体直接从wiki回答。

保留的是：

• 相同顺序的八个阶段。
• Writer → Evaluator → Editor三重循环。
• [[wikilink]] 约定。
• Lint规则和修复行为。
• 在删除之前询问的合并步骤。
• 文件顶部的CONFIG块，智能体在首次运行向导期间填充并用其文件编辑工具编辑。

它实际上是将想法文件用程序化版本的操作形态 stamped上去。

诚实的总结是：对于大型语料库和 recurring pipeline，程序化版本在token、可预测性和可审查性方面物超所值。对于较小的基础或wiki形式仍在探索中的项目， .md 版本启动更快、更容易更改。 两种方式的输出质量相当——Karpathy的模式足够稳健，Writer → Evaluator → Editor → Lint → Repair循环无论作为Python运行还是作为智能体指令都能产出好的页面。区别在于循环周围的一切，而不是循环本身。

3、Markdown问题，以及为什么它不是可选的

我想特别指出程序化版本中的一个部分，因为这是大多数LLM生成的wiki悄悄失败的地方。

当智能体写Markdown时，它产生的是看似合理的Markdown。大部分嵌套正确的标题。通常能解析的表格。看起来正确但实际上无法解析的链接。形状像YAML但当一个冒号出现在未引用的值中时会中断的frontmatter。同一文件中有两个H1，因为智能体忘记了已经写过一个。同一来源的不同重新生成之间章节顺序会漂移。

在一个复合的流水线中——每个页面都成为topics、groups、index、chat retriever的输入——那种结构噪声不是表面问题。它会破坏每个下游阶段。分块器会错误地在sections之间产生重叠。去重器会合并错误的页面。lint pass会报告repair pass无法安全修复的问题，因为它无法判断哪个标题是"真正的"那个。

我写了markdown-hero来专门解决这一层——类型检查、section感知、多语言，带有一个重叠窗口保持在同一heading内的分块器。在wiki-llm中，每个离开Generate阶段的页面都通过lint()。Consolidate中的每次合并都通过markdown_merge(dedupe_headings=True)。每个输送到聊天索引的chunk都来自extract_chunks(purpose="rag")。流水线不会产生结构性垃圾，因为markdown-hero层会拒绝。

agentic版本无法提供这种保证。它要求智能体遵循约定，然后信任智能体。对于大多数用例，这种信任是成立的。但对于wiki是另一个自动化阶段的输入的流水线，并非如此。

这是为数不多的几个程序化版本不是更重的替代方案的地方——它是一种不同的能力。

你可以在这里阅读所有关于markdown-hero的内容，并通过pypi获取：

pip install markdown-hero

3、何时选择哪个

如果你符合以下任何条件，从.md版本开始：

• 个人或小团队wiki，大约200篇文档以下。
• 你仍在弄清楚wiki应该是什么样子。
• 你已经在每天使用Claude Code、Codex或Cursor，并希望wiki存在于你已经在工作的地方。
• 你想迭代提示词和结构而无需重新部署任何东西。

如果你符合以下任何条件，从package开始：

• 语料库足够大，重新生成未更改的页面所花费的token是真实成本。
• 团队需要相同的wiki从相同的输入中每次产生相同的结果。
• 流水线为下游自动化提供输入（搜索、聊天、导出、仪表板）。
• 生产环境按计划运行——夜间、每周、提交时。
• 每次LLM调用的审计追踪是一项要求。

两种实现都尊重原始想法。Karpathy的直觉——在智能体时代应该分享的是模式而不是代码——以一种我直到编写了两个版本后才充分理解的方式被证明是负载承载的。.md版本的存在因为模式是清晰的。Python版本的存在因为模式很好地转化为工程决策。

两种今天就可以开始的方式：

• 原始想法文件： Karpathy的 llm-wiki.md gist——粘贴到你的智能体中，让它围绕你构建一个wiki。
• 我的agentic实现： wiki_llm 中的AGENTS.md——放到任何项目中，让你的智能体指向一个文档文件夹，让它构建wiki。
• 我的程序化实现： GitHub上的wiki-llm —— pip install，写一个配置，运行流水线。构建在markdown-hero之上以提供结构性基础。

选择适合你语料库的那个。如果不合适，以后再切换。

原文链接：I Built Karpathy's LLM Wiki Twice: Once as Code, Once as a .md — Here's What Each One Gives Up

汇智网翻译整理，转载请标明出处