1. 为什么需要把 Markdown 知识库和 AI Agent 连起来
我自己的知识库大概从三年前开始全面转向 Markdown，原因很简单：纯文本、可版本控制、跨平台、不绑定任何一家笔记软件。但真正让我头疼的问题，是最近一年 AI Agent 爆发之后出现的——我的知识库和我的 Agent 完全是两个世界。
Markdown 文件躺在 Git 仓库里，Agent 在另一个终端窗口里跑，每次我想让 Agent 参考某篇笔记，要么手动复制粘贴，要么写一堆胶水脚本去读文件。更麻烦的是，Agent 每次对话都是无状态的，它不知道我上周写了什么、改了哪些文档、哪些结论已经过时了。这种割裂感，用过 AI Agent 做知识工作的人应该都懂。
OpenKnowledge 这个项目要解决的就是这个问题：把 Markdown 知识库变成 AI Agent 可以直接读写、可以感知变化、可以持续积累的活的知识层。它不是又一个笔记软件，也不是又一个 Agent 框架，而是两者之间的连接层。适合谁看？如果你手上有几百篇 Markdown 笔记，同时在用 Claude Code、Codex 或者其他支持 Skills 的 Agent 工具，这篇文章就是写给你的。
核心关键词先摆出来：OpenKnowledge、Markdown、AI Agent、Git、Skills。这五个词基本概括了整个项目的技术栈和设计哲学。下面我会从设计思路、核心机制、实操步骤、踩坑经验四个维度，把这个连接层拆开讲清楚。
2. 整体设计思路：为什么是 Markdown + Git + Skills 这个组合
2.1 知识库格式选型：Markdown 的不可替代性
先说为什么知识库必须是 Markdown，而不是数据库或者向量库。我试过把笔记导入向量数据库做 RAG，效果确实有，但问题也很明显：向量检索是黑盒。你没法精确知道 Agent 到底读了哪一段、为什么读这一段、检索结果对不对。调试的时候非常痛苦。
Markdown 的好处在于它是人类可读、机器可解析、Git 可追踪的三位一体格式。Agent 读 Markdown 不需要任何转换层，直接读文本就行。而且 Markdown 的语法足够简单，标题层级天然就是知识的结构树，列表和表格天然就是结构化数据。你写的时候是人话，Agent 读的时候也是人话，中间没有信息损耗。
这里有个细节值得说：Markdown 的标题层级（H1/H2/H3）实际上就是知识库的目录结构。OpenKnowledge 的设计里，Agent 定位知识不是靠全文检索，而是先读目录、再按标题层级下钻。这比向量检索精确得多，也更符合人类查资料的习惯。
2.2 版本控制选型：Git 作为知识的时间轴
Git 在这个项目里的角色不只是备份，而是知识的时间维度。Agent 需要知道"这个结论是什么时候写的""上周改了什么""哪些内容被删掉了"。这些信息只有 Git 能提供。
我实测下来，Git 的 commit history 对 Agent 特别有用。比如你问 Agent"我关于 RAG 的笔记最近有什么更新"，它可以直接读git log的输出，然后定位到具体文件的 diff。这种能力是任何笔记软件都给不了的。而且 Git 的分支机制让知识库可以有多条演进线，比如main是稳定结论，draft是实验性想法，Agent 可以根据任务类型选择读哪个分支。
注意：知识库的 Git 仓库建议单独建，不要和代码仓库混在一起。代码的 commit 频率和知识库完全不同，混在一起会让 history 变得很乱，Agent 读起来也费劲。
2.3 连接层选型：Skills 作为 Agent 的能力扩展
Skills 是最近 Agent 生态里最值得关注的概念。简单说，Skill 就是一段给 Agent 看的说明书 + 可执行脚本。Agent 遇到特定任务时，会先读 Skill 的描述，然后决定要不要调用。
OpenKnowledge 用 Skills 做连接层，好处是解耦。知识库本身不需要知道 Agent 的存在，Agent 也不需要内置知识库的逻辑。中间靠 Skill 做翻译：Skill 告诉 Agent"知识库在哪、怎么读、怎么写、怎么查历史"。换 Agent 工具的时候，只需要换 Skill，知识库本身不动。
这个设计思路我特别认同。我见过太多项目把知识库和 Agent 硬编码在一起，结果 Agent 框架一升级，整个知识库就得重构。Skills 这种松耦合的方式，长期维护成本低得多。
2.4 方案对比：为什么不用现成的 RAG 方案
| 方案 | 精确性 | 可调试性 | 版本追踪 | 维护成本 |
|---|---|---|---|---|
| 向量库 RAG | 中 | 差 | 无 | 中 |
| 全文检索 | 中 | 中 | 无 | 低 |
| OpenKnowledge（Markdown+Git+Skills） | 高 | 高 | 完整 | 低 |
向量库 RAG 的问题前面说了，黑盒。全文检索的问题是没有结构感知，它不知道 H2 和 H3 的从属关系。OpenKnowledge 的方案是结构优先：先按标题层级定位，再在段落内做匹配。实测下来，对于个人知识库这种规模（几百到几千篇），结构优先的准确率明显更高。
3. 核心机制拆解：Agent 到底怎么读写知识库
3.1 知识库的目录约定与索引文件
OpenKnowledge 对知识库的目录结构有约定，但不是强制的。核心约定是：每个知识领域一个顶层目录，目录下必须有一个index.md作为入口。这个index.md里列出该领域的所有文档链接和一句话摘要。
为什么要有index.md？因为 Agent 读知识库的第一步不是全文扫描，而是读索引。索引文件相当于知识库的"目录页"，Agent 先读它，知道有哪些内容，再决定深入读哪一篇。这比让 Agent 遍历所有文件高效得多，token 消耗也低得多。
索引文件的格式建议这样写：
# RAG 知识索引 - [RAG 基础原理](./rag-basics.md) - 检索增强生成的核心流程和数学推导 - [向量检索实践](./vector-search.md) - 主流向量库的选型和调参经验 - [RAG 评估方法](./rag-eval.md) - 如何量化 RAG 系统的效果Agent 读这个文件，就能在几百个 token 内掌握整个领域的全貌。这个设计我称之为索引先行，是 OpenKnowledge 效率的关键。
3.2 Skill 的编写规范：让 Agent 知道怎么用
Skill 文件通常是一个 Markdown 文件，放在 Agent 工具的 skills 目录下。它的结构一般包含三部分：描述、触发条件、执行步骤。
描述部分告诉 Agent 这个 Skill 是干什么的。触发条件告诉 Agent 什么时候用。执行步骤是具体的操作指令，可以是自然语言，也可以是脚本调用。
一个典型的 OpenKnowledge Skill 长这样：
--- name: openknowledge-read description: 从本地 Markdown 知识库读取内容 --- ## 何时使用 当用户询问需要参考个人笔记、知识库内容时使用。 ## 执行步骤 1. 读取知识库根目录的 index.md 2. 根据用户问题定位相关领域目录 3. 读取该目录的 index.md，找到具体文档 4. 读取目标文档，提取相关内容 5. 如果内容涉及历史变更，执行 git log 查看这个 Skill 的关键在于步骤足够具体。Agent 不需要猜，照着做就行。我踩过的坑是：Skill 写得太抽象，Agent 会自由发挥，结果读了一堆无关文件，token 烧得飞快。
3.3 读写分离：Agent 写知识库的安全机制
Agent 读知识库是安全的，但写知识库必须谨慎。OpenKnowledge 的设计里，Agent 的写操作走的是"提议-确认"流程，而不是直接改文件。
具体做法是：Agent 把要写的内容先输出到一个pending/目录，文件名带时间戳。然后由人（或者一个专门的 review Skill）确认后，再移动到正式目录并 commit。这个机制防止了 Agent 乱改知识库，也保留了人工审核的环节。
提示：
pending/目录建议加到.gitignore里，避免未确认的内容污染 commit history。
我实测下来，这个机制非常必要。有一次 Agent 理解错了我的意图，差点把一篇重要笔记的核心结论改掉。有了 pending 机制，我一眼就能看出它想改什么，直接拒绝就行。
3.4 Git 集成：让 Agent 感知知识的时间维度
Git 集成是 OpenKnowledge 区别于普通文件读取的核心。Agent 通过几个 Git 命令就能获得时间维度的信息：
git log --oneline -20：最近 20 次变更概览git log --follow <file>：某个文件的完整变更历史git diff HEAD~5 HEAD -- <file>：最近 5 次提交对该文件的改动git blame <file>：每一行是谁什么时候写的
这些命令的输出对 Agent 来说就是结构化的时间数据。比如你问"我关于向量检索的结论变过吗"，Agent 可以git log --follow vector-search.md，看到这个文件被改过三次，然后git diff看每次改了什么，最后给你一个准确的回答。
这个能力在知识管理里价值极高。人的认知是演进的，知识库应该反映这种演进，而不是只保留最终结论。Git 让 Agent 能读懂你的思考过程。
4. 实操过程：从零搭建 OpenKnowledge 连接层
4.1 环境准备：Git 安装与基础配置
第一步是确保 Git 可用。Linux 下sudo apt install git或者sudo yum install git，macOS 下brew install git，Windows 下直接下载安装包。安装完执行git --version确认。
然后是基础配置，这两条命令必须做：
git config --global user.name "你的名字" git config --global user.email "你的邮箱"为什么必须配置？因为 Agent 读git log的时候，作者信息是它判断"这段内容是谁写的、可信度如何"的依据之一。如果作者信息是空的，Agent 的推理会缺一块。
还有一个容易被忽略的配置：换行符处理。Markdown 文件在不同系统下的换行符不一样，会导致 Git diff 出现大量无意义的变更。建议配置：
git config --global core.autocrlf input这个配置在 Linux 和 macOS 下保持原样，在 Windows 下提交时转成 LF。这样跨平台协作时 diff 才干净。
4.2 知识库初始化：目录结构与索引文件
新建知识库目录，初始化 Git：
mkdir my-knowledge && cd my-knowledge git init然后建立目录结构。我的建议是按领域分顶层目录，而不是按时间或者类型。比如：
my-knowledge/ ├── index.md ├── ai/ │ ├── index.md │ ├── rag-basics.md │ └── vector-search.md ├── frontend/ │ ├── index.md │ └── react-patterns.md └── tools/ ├── index.md └── git-workflow.md根目录的index.md列出所有领域，每个领域的index.md列出该领域的所有文档。这个两层索引结构，是 Agent 高效定位知识的基础。
注意：文档命名建议用英文小写加连字符，比如
rag-basics.md。中文文件名在某些 Git 配置下会出现乱码，Agent 读取时也可能出问题。文档标题写在文件内的 H1 里，用中文没问题。
4.3 Skill 部署：把连接层装到 Agent 里
Skill 的部署位置取决于你用的 Agent 工具。以 Claude Code 为例，Skill 放在~/.claude/skills/目录下。Codex 的话放在对应的 skills 目录。具体路径查你所用工具的文档。
部署步骤：
- 在 skills 目录下新建
openknowledge/文件夹 - 在里面创建
SKILL.md，写入前面说的 Skill 内容 - 如果 Skill 需要执行脚本，在同目录放脚本文件
- 重启 Agent 工具，让它重新加载 Skills
验证 Skill 是否生效：直接问 Agent"你能读取我的知识库吗"，如果它回答时提到了你的知识库路径和索引文件，说明 Skill 加载成功了。
我踩过的坑：Skill 文件里的路径写成了绝对路径，换电脑之后就失效了。建议用相对于知识库根目录的路径，然后在 Skill 里说明"知识库根目录是 XXX"，让 Agent 自己拼接。
4.4 读写流程实测：一次完整的知识查询
假设我的知识库在~/my-knowledge，我问 Agent："我关于 RAG 评估的笔记里，有没有提到过评估指标的选择标准？"
Agent 的执行流程（通过 Skill 引导）：
- 读
~/my-knowledge/index.md，看到有ai/领域 - 读
~/my-knowledge/ai/index.md，看到有rag-eval.md - 读
rag-eval.md，定位到"评估指标"章节 - 提取相关内容，回答我的问题
- 如果内容里有"待确认"标记，Agent 会提示我这部分结论可能不完整
整个过程 Agent 只读了三个文件，token 消耗很小，但定位非常精确。这就是索引先行 + 结构下钻的威力。
写流程实测：我让 Agent"把刚才讨论的评估指标补充到知识库"。Agent 会把内容写到pending/20250101-rag-eval-update.md，然后提示我确认。我 review 之后，手动移动到ai/rag-eval.md并 commit。这个流程虽然多了一步，但安全感强很多。
5. 常见问题与排查技巧实录
5.1 Skill 不生效：Agent 读不到知识库
最常见的症状是 Agent 说"我没有访问知识库的能力"。排查顺序：
| 排查项 | 检查方法 | 常见原因 |
|---|---|---|
| Skill 目录位置 | 确认路径和工具文档一致 | 放错目录 |
| SKILL.md 格式 | 检查 frontmatter 是否完整 | 缺 name 或 description |
| 工具是否重启 | 重启后重试 | Skill 未重新加载 |
| 路径权限 | ls -la确认可读 | 权限不足 |
我遇到最多的是 frontmatter 格式问题。name和description之间的---必须成对出现，少一个 Agent 就解析不了。
5.2 Git 认证失败：Agent 执行 git 命令报错
Agent 执行git log一般不需要认证，但如果是git push或者访问远程仓库，可能会遇到认证问题。典型报错是Permission denied (publickey)或者Authentication failed。
解决思路：Agent 不应该直接执行需要认证的 Git 操作。读操作（log、diff、blame）不需要认证，写操作应该由人来做。如果确实需要 Agent 推送，建议配置 SSH key 并确保 Agent 运行环境的 SSH agent 已加载。
提示：知识库的远程仓库建议设为私有。Agent 读的是本地文件，不需要远程访问权限，这样最安全。
5.3 索引文件过期：Agent 定位到不存在的文档
知识库用久了，index.md容易和实际文件不同步。Agent 按索引找文档，结果文件已经改名或者删了，就会报错。
解决办法有两个：一是养成习惯，每次增删文档都更新索引；二是写一个校验 Skill，让 Agent 定期扫描目录和索引的差异。我用的校验脚本逻辑很简单：列出目录下所有.md文件，和index.md里的链接对比，输出差异。
# 简化的索引校验逻辑 find . -name "*.md" -not -name "index.md" | while read f; do grep -q "$f" index.md || echo "索引缺失: $f" done这个脚本跑一遍，就知道哪些文件没进索引了。
5.4 Token 消耗过大：Agent 读了太多无关内容
如果发现 Agent 回答一个问题消耗了大量 token，通常是索引没起作用，Agent 在全文扫描。排查方法：看 Agent 的执行日志，如果它读了超过 5 个文件，基本就是索引失效了。
优化方向：确保每个领域的index.md足够详细，每篇文档的一句话摘要要准确。摘要越准，Agent 越容易判断"这篇要不要读"。另外，文档内部建议用清晰的 H2/H3 标题，Agent 可以只读相关章节，而不是整篇读。
5.5 多 Agent 协作时的冲突
如果你同时用多个 Agent 工具（比如 Claude Code 和 Codex），它们可能同时读写知识库，导致冲突。OpenKnowledge 的解法是用 Git 分支隔离：每个 Agent 在独立分支上工作，定期合并到 main。
具体做法：Agent 写操作前先git checkout -b agent-xxx，写完 commit 到该分支，人 review 后合并。这样即使两个 Agent 同时改，也不会互相覆盖。
6. 进阶玩法：让知识库真正活起来
6.1 自动归档：把网页内容保存成 Markdown
热词里有个"agent 将网页保存成 markdown 的 skill"，这其实是 OpenKnowledge 的一个自然扩展。写一个 Skill，让 Agent 读取网页内容，转成 Markdown，按领域归档到知识库。
关键点是归档时的元数据。建议在文件头部加 frontmatter：
--- source: https://example.com/article archived: 2025-01-01 tags: [rag, evaluation] ---这些元数据让 Agent 后续检索时能按来源、时间、标签过滤。我实测下来，加了元数据的归档文档，Agent 的引用准确率明显更高。
6.2 知识图谱：用双向链接构建关联
Markdown 的双向链接（[[文档名]]）是构建知识图谱的天然工具。OpenKnowledge 可以让 Agent 在写文档时自动建议关联链接：读一篇文档时，Agent 扫描知识库里其他文档，找出内容相关的，建议加上双向链接。
这个玩法的价值在于发现隐性关联。我自己写笔记时经常忘记某两个概念是相关的，Agent 帮我找出来，知识库的连通性就上去了。
6.3 定期回顾：让 Agent 做知识库的"体检"
写一个回顾 Skill，让 Agent 定期扫描知识库，输出：
- 超过 6 个月没更新的文档
- 被引用次数最多的文档（通过反向链接统计）
- 内容重复或矛盾的文档
- 索引缺失的文档
这个"体检"报告对知识库的长期健康非常有用。我每月跑一次，能发现不少问题，比如某篇文档的结论已经被新文档推翻了，但旧文档没更新。
6.4 与代码仓库联动：知识库和项目同步
如果你的知识库和代码仓库有关联（比如技术笔记对应某个项目），可以让 Agent 在 commit 代码时，自动检查知识库是否有相关文档需要更新。这个联动通过 Git hook 实现：commit 时触发一个脚本，让 Agent 分析 diff，提示"这次改动可能影响知识库的 XX 文档"。
这个玩法我还在实验阶段，但初步效果不错。它解决了"代码改了但笔记没更新"这个老大难问题。
7. 我个人的一些实操体会
搭这套东西大概花了我两个周末，中间踩了不少坑，但用起来之后确实回不去了。最大的感受是：知识库的价值不在于存了多少，而在于 Agent 能不能用上。以前我存了几百篇笔记，但真正查的时候还是靠记忆和搜索，Agent 帮不上忙。现在 Agent 能精确地读、能感知变化、能帮我写，知识库才真正变成了"第二大脑"。
几个具体的建议：第一，索引文件一定要认真维护，这是整个系统效率的命脉，索引烂了 Agent 就瞎了。第二，Skill 的步骤要写得像给新人看的操作手册，越具体越好，Agent 不会嫌你啰嗦。第三，写操作一定要走 pending 流程，别让 Agent 直接改正式文档，血的教训。第四，Git commit message 写清楚，Agent 读 log 的时候全靠这个判断变更意图。
最后分享一个小技巧：在知识库根目录放一个AGENTS.md，里面写清楚这个知识库的组织方式、命名规范、索引维护规则。Agent 读这个文件就能快速理解你的知识库结构，比在 Skill 里写一堆说明更直接。这个文件相当于给 Agent 的"入职指南"，实测下来效果很好。
