10. Markdown 知识库

从第 9 篇的结论出发

第 9 篇的论证收敛于一个可操作的判断标准：如果知识可以浓缩到一个 CLAUDE.md 里，就不要引入向量数据库。RAG 是浓缩不再可行时的退路，而非默认选项。

这一篇正面展开退路之前的正选方案：Markdown 知识库（Markdown Knowledge Base，以下简称 Markdown KB）。它不是 RAG 的简化版，更不是过渡态。它是一套独立的范式，有独立的适用边界和设计哲学。

这个范式并非凭空产生。第 4 篇讨论的 Rules 和 Skills 已经是 Markdown KB 的雏形——Rules 定义 Agent 的行为边界，Skills 定义可复用的操作流程。CLAUDE.md、.cursorrules、OpenClaw 的 rules/ 和 skills/ 目录，都是在同一个模式下的不同命名。

但它们只覆盖了”人写给 Agent 看”的那一部分。一个完整的 Markdown KB 远不止于此——它包含人写的笔记、Agent 在运行中生成的经验总结、以及两者共同维护的交叉引用网络。维护者不是单方面的人力投入，而是人加 Agent 的协作体。CLAUDE.md 在大量项目中正是由 Agent 在运行过程中发现、总结和更新的，而非人逐行维护的产物。

渐进式演进：人类直觉，Agent 整理

如果一个 Markdown 知识库需要人像档案管理员一样每天分类、打标签、维护索引，那它在 AI 时代已经失去了存在的合理性。工具应该适配人的工作方式，而非相反。

现代 Markdown KB 的核心范式是自下而上的渐进式演进。人类负责直觉式的记录——想到什么写什么，不需要预先设计分类体系。Agent 负责探索、链接和上下文的按需注入。这个范式可以描述为三个阶段，它们并非严格的时间先后，而是描述一篇笔记从诞生到成熟的典型轨迹。

阶段一：无负担倾倒

在这个阶段，人的行为没有任何额外的认知负荷。打开编辑器，写下算法心得、会议纪要或重构灵感。文件名可以是随手敲下的日期加关键词——2026-06-13-Angular重构碎碎念.md。不需要判断它属于哪个分类，不需要预先设计标签，甚至不需要写完整的段落。

这篇笔记被丢进知识库目录。此刻它只是一段孤立的文本，等待被连接。

阶段二：Agent 的主动探索与织网

Agent 在后台或按需启动时，对这篇生肉进行语义阅读。它不需要完美的结构化输入——它只需要理解这篇笔记的核心内容是什么。比如一段凌乱的重构记录，Agent 识别出其核心是”RxJS 的流控优化”。

理解内容之后，Agent 开始检索已有知识库。它发现半年前存在一篇相关笔记 RxJS基础算子.md，于是在文末自动注入一行 wikilink。如果 Agent 发现两篇笔记讨论的是同一个问题但结论存在矛盾，它可以标记一条提醒，提示人注意两处信息的不一致。

此时笔记不再是孤立文本。它被接入了知识网络，通过超链接与已有的知识节点建立了显式的关联。

阶段三：动态上下文注入

随着人机持续共同使用知识库，这个系统开始展现出主动行为。

当 Agent 处理一个新任务时，它在开始执行之前主动去知识库中探索，将相关的旧笔记作为上下文注入当前的推理窗口。它可能会在 prompt 中自然地插入一句：“我注意到三个月前记录过这个接口的一个坑，当时的解决方案是……”

当 Agent 解决了一个全新的问题后，它可以主动提出将解决方案写入知识库留档。人只需要确认，不需要亲自动笔。Agent 写下的内容与人的笔记在同一个目录中，使用同一种格式，遵守同一套约定。

在这个阶段，Agent 还发展出了条件注入的能力。它根据当前任务的性质自行判断需要查阅知识库的哪些部分——任务涉及部署，就去翻部署相关的笔记；涉及测试，就去找测试经验。不需要代码预先写死关键词到文件的映射表，Agent 自己决定读什么。

设计原则

以下原则描述的是 Markdown KB 作为一个系统的外在特征，而非对维护者提出的操作规范。它们是 Agent 参与维护后自然呈现的结果。

免维护

人对知识库不需要付出额外的组织劳动。目录结构、wikilink 引用关系、标签的分布——这些是 Agent 在持续使用过程中自然生长的产物。人可以随时手动调整任何内容，但”不调整”不会导致知识库退化。这与传统档案管理形成鲜明对比：后者的检索效率高度依赖管理员的持续投入，而前者的检索效率由 Agent 的探索能力来保障。

确定性

Markdown KB 与 RAG 最本质的区别在于知识获取的路径。RAG 的路径经过了一次语义检索——查询被编码为向量，与文本块的向量做相似度计算，取 top-K 注入 prompt。这条路径上的每一步都引入了不确定性：embedding 模型的精度、相似度阈值的调参、K 值的选择、噪声块的混入。

Markdown KB 没有检索环节。Agent 用 read 直接打开文件读原文。读到了就是读到了，没读到就是没读到。不存在”大概读到了但不确定”的中间状态。确定性来自路径的简洁——一次文件系统调用，一次文本返回，没有中间模型。

人可审计

Agent 写入的所有内容都是纯文本 Markdown。这意味着人可以通过 git diff 精确审查 Agent 对知识库的每一次修改——增删了哪些行、修改了哪个段落、添加了什么引用。Agent 生成的知识与人类书写的知识共享同一个目录、同一种格式、同一套版本控制工具链。如果 Agent 写入了一个错误的结论，人修改它的方式与修改自己笔记的方式完全相同：一次普通的 git commit。

这一特性的工程价值在于：Agent 的知识贡献不会形成一个人无法审查的黑箱。Agent 写得越多，审计机制的必要性越强。Markdown KB 将审计的成本降至近乎为零。

一篇合格的 Markdown KB 笔记

Markdown KB 不需要任何代码。它只需要用好 Markdown 本身的两个机制。

YAML Frontmatter

Markdown 文件顶部的 --- 包裹区域被称为 Frontmatter，是笔记的元数据区。它是一块结构化的 YAML，嵌在纯文本文件的最前端。

---
title: RxJS 流控优化踩坑记
date: 2026-06-13
tags:
  - rxjs
  - 性能
---

Frontmatter 的价值在于它为 Agent 提供了一个无需通读全文即可做出判断的信息层。Agent 在 kb/ 目录中定位到一批候选笔记后，第一步不是进入正文，而是读取 frontmatter。title 告诉它这篇笔记讲什么，date 告诉它信息的时效性——一年前的排查经验可能已被新版本的方案取代，tags 提供初步的语义锚点。

这比全文 grep 高效得多。grep 是模糊的全文匹配，frontmatter 是结构化的元数据查询。前者的精度取决于关键词的选择，后者的精度取决于前置的归纳——在写入时花三秒钟标注标签，为后续所有检索节省三秒乘以检索次数的时间。

正文：一个要点

好的知识库笔记不追求覆盖面的广度。一篇笔记只承载一个要点——一个 bug 的根因和修复路径、一个配置项的推荐值及其理由、一次重构的决策逻辑和权衡考量。

标题需要直接说明内容，避免”关于 XX 的一些思考”这类零信息量的命名。正文中通过 wikilink 连接相关笔记，将单篇笔记嵌入知识网络。对于已解决的问题，写清楚结论。对于未解决的问题，写清楚当前状态和阻塞点。这两类信息对 Agent 具有完全不同的指导意义——结论可以直接复用，状态则需要继续推进。

一个对比：不合格的笔记只有一段模糊叙述，“那天服务器挂了，搞了好久，最后改了个配置好了”——Agent 读完后无法判断发生了什么、是否与当前任务相关、结论是否可复用。合格的笔记在 frontmatter 中标注了标题、日期和标签，正文中拆分为现象、根因、修复、预防四个结构化段落，并通过 wikilink 引用了相关规范文档。Agent 只需读取 frontmatter 的三行结构化信息即可完成筛选。

Agent 的阅读路径

Agent 探索知识库的路径与人类浏览个人笔记的路径高度一致。

第一步，扫 kb/ 目录，通过文件名中的关键词定位候选笔记。第二步，打开候选笔记，先读 frontmatter，通过 title 和 tags 判断是否与当前问题域匹配。第三步，如果匹配，进入正文，跟随 wikilink 跳转到关联笔记。第四步，如果前三步没有找到现成答案，退回到全文 grep 搜索特定关键词。

整个过程只需要 read 和 grep 两个工具——Agent 在第 1 篇就已经具备的能力。不需要向量数据库，不需要 embedding 模型，不需要索引管线。

与 RAG 的分工

两套方案不构成互斥关系。它们在同一个系统中服务于不同的知识形态。

Markdown KB 处理的是精炼后的经验——规则、约定、避坑记录、设计决策。这些知识的共同特点是短、经过人机归纳、需要在每次相关任务中出现。它们的载体是单篇短笔记，一篇一个要点，通过 wikilink 织成网络。

RAG 处理的是原始资料——API 手册、历史 issue 讨论、长文档。这些知识的共同特点是量大、未经精炼、只在特定查询场景下需要按需检索。

在 prompt 的注入顺序上，两者也存在明确的优先级关系。system prompt 占据最外层，随后是 Rules 和 Skills（第 4 篇的加载机制），然后是 Agent 自行从 Markdown KB 中读取的相关笔记，最后才是 RAG 的检索结果。这个顺序并非随意的——Agent 主动找到的精炼知识优先于机器检索的原始资料。LLM 先看到宪法和可信经验，再看到可能的参考文档。

设计哲学

软件工程的一般经验是：方案随需求增长而升级。从单体到微服务，从单机到分布式，从手工到自动化——进阶的方向通常是增加复杂度。

Markdown KB 提供了一个反直觉的案例。它的进阶方向不是增加技术组件，而是减少。不需要向量数据库，不需要 embedding 模型，不需要索引管线。需要的是一个文件系统、一个能读写的 Agent、以及维持笔记质量的纪律。

它的力量不在于技术的复杂度，而在于一个朴素的约束：知识必须精炼到能被人类一眼看懂。这个约束同时作用于人和 Agent——人写下的内容需要清晰，Agent 写下的内容同样需要可理解。精简本身就是最有价值的步骤。它不是为省 token 而采取的妥协，而是迫使模糊直觉转化为清晰表述的机制。

当精炼不再可行时——知识量确实超出了人机协作能维护的边界——RAG 在那边作为退路存在。但在退路之前，Markdown KB 提供了一个代价更低、确定性更高、维护成本近乎为零的方案。这个方案能够覆盖的实践范围，比多数人直觉估计的要大得多。

---

下一篇：11. 总结与展望()