我把用了一个多月的 Obsidian LLM Wiki 开源了：5 个 Skill 与 Doctor 设计

我一直在用 Obsidian 记录资料。

文章、技术方案、项目经验、临时想法，以及从不同渠道收集来的知识，都在持续进入同一个 Vault。笔记越来越多之后，我遇到的问题却不是“没有内容”，而是另一种更隐蔽的失控：我知道某个知识大概率写过，却不一定记得它在哪；即使自己能找到，也很难让 AI 稳定地找到。

一个多月前，我开始尝试用 LLM Wiki 的思路重新组织这些知识。第一版完成后，散落的 Obsidian 笔记逐渐变成了互相关联的知识节点，AI 也可以通过 query Skill 沿着这些入口检索资料。

后来，我又把同一套思想放进项目开发场景中进行内部试用。随着使用时间变长，一个新的问题逐渐暴露出来：

Obsidian 还在增长，但 LLM Wiki 停留在了上一次 ingest 的时刻。

我会定期调用 maintain 整理知识库，但对整个知识库的健康程度仍然完全未知。于是，在准备开源这套 Skill 库时，我增加了一个独立的 doctor 层，把原来依赖感觉的维护过程，变成“先诊断、再确认、后修复”的闭环。

这就是 Obsidian LLM Wiki 从个人工具走向开源项目的过程。

起点：从 Karpathy 的 LLM Wiki 得到启发

最初的起点，是我阅读并翻译了 Karpathy 的 LLM Wiki 相关内容。此前的中文翻译可以在这里阅读：

Karpathy LLM Wiki 中文翻译

它给我的启发并不是“再做一个搜索工具”，而是换一种方式理解 LLM 与知识库的关系。

当知识量很小时，我们可以直接把几个文件放进上下文。但随着资料不断增长，这种方式很快会遇到限制：上下文装不下，目录结构对模型没有意义，搜索结果也缺少稳定的导航入口。

与其每次把所有资料交给模型，不如先为模型建设一层 Wiki：用索引、主题、项目、实体、来源代理和链接关系，把知识组织成可以逐步导航的结构。

这也成为我实现 Obsidian LLM Wiki 的出发点。

第一版：把知识碎片变成可导航的 Wiki

我个人 Obsidian 中的资料并不是一套从零规划出来的标准知识库。它更接近真实世界的状态：目录很多，内容持续增长，有些笔记之间有链接，有些则只是写完后被放在某个角落。

第一版 Obsidian LLM Wiki 主要解决三个问题：

• 盘点 Vault 中已经存在的目录和资料类型。
• 将确认过的资料组织成 Wiki 可见的知识节点。
• 为 LLM 提供稳定的检索入口，而不是让它每次从整个 Vault 盲目搜索。

最初的工作流可以概括为：

这里的 ingest 不只是复制文件。它需要记录资料来自哪里、当前处理到什么状态、对应哪个 Wiki 入口，以及它与哪些 topic、project、entity、SOP 或 checklist 有关。

最终形成的并不是一份更大的文件清单，而是一张能够被 Obsidian 展示、也能够被 Agent 导航的知识图谱。

截图：整理前的 Obsidian 目录或关系图谱。

截图：完成 init & ingest 后的 Wiki 目录或关系图谱。

Query 让知识可以被重新调用

知识被组织起来之后，obsidian-wiki-query 开始承担检索入口的角色。

当我询问一个问题时，Agent 不需要一开始就扫描全部笔记，而是可以先读取 Wiki 的主索引，再根据主题、项目、实体或来源代理逐步缩小范围。这样得到的不只是关键词命中的几个文件，而是一组带有来源和关系的上下文。

例如，我可以直接询问：

基于我的 Obsidian LLM Wiki，总结以前记录过的知识库摄入方案，并列出对应来源。

如果查询过程中发现了值得长期保留的新结论，query 还可以建议将它沉淀成新的 Wiki 页面，但真正写入前仍然需要用户确认。

这一步让我验证了一件事：个人 Obsidian 中散落的知识碎片，确实可以经过结构化整理，变成可被 AI 持续调用的长期上下文。

在项目开发场景中内部试用一个多月

个人知识库验证可用后，我把同一套思想放进了项目开发流程中进行内部试用。

项目开发中的上下文比个人笔记变化更快。需求文档、代码、Bug、日志、会议记录和历史会话持续产生。如果 Agent 每次开始开发都重新寻找资料，不仅效率低，也很容易遗漏已经做过的决策。

在这一个多月的内部实践中，LLM Wiki 被用于组织项目上下文，并辅助需求分析、问题定位和开发讨论。这部分 Project Develop 能力目前仍处于内部使用阶段，可能会在后续形成独立的开源计划，不属于这次 Obsidian LLM Wiki 已开源能力的范围。

不过，正是这段真实使用，让我发现了第一版设计中最关键的缺口。

能查询，不代表知识库是健康的

Obsidian 中每天都可能增加新文档，但 Wiki 并不会因为文件出现就自动理解它。

如果新增文档没有进入 ingest 流程，后续链路就不会发生：

笔记没有丢失，文件也没有损坏，但对于只沿着 LLM Wiki 工作的 Agent 来说，这些知识近似于不存在。

我把这种现象理解为一种“数据腐烂”或“摄入覆盖度漂移”：真实 Vault 持续变化，而 Wiki 表达层没有同步更新，两者之间的差距越来越大。

过去，我会每隔一段时间调用 maintain Skill。它可以修复已经看到的问题，例如补充缺失链接、更新索引或调整结构。但这里存在一个根本矛盾：

我一直在维护知识库，却始终不知道它是否健康。

maintain 是维修工具。它适合处理已经确认的问题，却不应该同时承担“发现所有问题”和“直接修改文件”两种职责。否则，诊断和写入混在一起，用户既不知道检查标准，也难以控制修改范围。

为什么要增加独立的 Doctor 层

这次开源版本中，我将诊断能力拆成了独立的 obsidian-wiki-doctor Skill。

Doctor 的边界非常明确：只读检查、输出证据、给出方向性评分，但不修改 Vault。需要修复时，再把已确认的范围交给 maintain。

完整闭环变成了：

这种拆分带来了几个直接收益：

• 检查不会在后台顺手修改原始笔记。
• Findings 是确定性观察，评分只是成熟度摘要，两者不会混为一谈。
• 用户可以看到问题证据，再决定修不修、修哪些。
• 修复后可以重新运行 Doctor，验证结果是否改善。

Doctor 当前会检查这些确定性问题：

• 输入路径能否解析为有效的 LLM Wiki。
• wiki/index.md 与 wiki/log.md 等必要入口是否完整。
• Wiki 索引和内部 Markdown 链接是否指向缺失目标。
• 已处理的 ingest 记录是否缺少对应的 source proxy。
• 初始化后的路线图和知识地图是否缺失。
• 生成的 Wiki 页面中是否出现疑似敏感信息模式。

在评分层，它会从控制中心解析、导航与可发现性、摄入可追溯性、安全卫生和 Query 就绪度几个维度给出方向性结果，并区分 healthy、usable、needs-attention 和 at-risk。

截图：Doctor 中文健康报告，建议包含关键结论、总体评分和 Findings。

截图：修复前后两次 Doctor 报告的对比。

Doctor 不是终点：当前仍有一个重要边界

这里需要明确说明当前版本的能力边界。

现有 Doctor 能检查“已经进入 ingest 的记录是否可追溯”，但还不能主动发现“Vault 中新增、却从未登记到 ingest 的文档”。也就是说，它已经能够检查 Wiki 内部结构，却还没有完整测量真实 Vault 与 Wiki 表达层之间的覆盖差距。

这也是后续最重要的优化方向之一：在不读取笔记正文的前提下，通过元数据级盘点识别新增、修改和待摄入文档，并记录上次盘点时间，形成摄入覆盖度与知识新鲜度指标。

我希望最终的 Doctor 不仅能回答“Wiki 内部有没有坏链接”，还能够回答：

• Vault 最近新增了多少文档？
• 其中多少还没有进入 ingest？
• 哪些 Wiki 页面长时间没有同步来源变化？
• 当前 Query 实际能够覆盖多少知识？

把这个边界写清楚很重要。Doctor 不是一个“已经解决所有问题”的标签，而是让知识库从盲目维护走向可观测、可验证维护的第一步。

现在的 Obsidian LLM Wiki 包含 5 个 Skill

当前开源版本按照用户意图拆分成 5 个 Skill：

Skill	主要职责	是否写入
obsidian-wiki-init	初始化或接管 Vault，盘点结构并建立知识库中控	确认后写入
obsidian-wiki-ingest	将确认过的资料组织成 Wiki 页面和来源代理	确认后写入
obsidian-wiki-doctor	只读诊断、校验、评分并生成报告	否
obsidian-wiki-maintain	根据已确认 Findings 执行窄范围修复	确认后写入
obsidian-wiki-query	基于 Wiki 回答、总结和定位来源	默认只读

这五个 Skill 组成了一条完整工作流：

init → ingest → doctor → maintain → query

实际使用并不要求用户记住命令。用户只需要表达意图，Skill 负责完成路由。例如：

• “初始化我的 Obsidian Vault，先只盘点目录，不读取正文。”
• “把这批确认过的资料摄入我的 LLM Wiki。”
• “检查当前知识库的健康程度，生成中文 Doctor 报告。”
• “根据 Doctor 报告，修复我确认的链接问题。”
• “基于我的 Wiki，回答以前记录过的这个问题。”

安装与首次使用

可以通过 Skills CLI 安装：

npx skills add huajiexiewenfeng/obsidian-llm-wiki

本地开发或测试时，在仓库根目录运行：

npx skills add .

新版还增加了默认 Vault 发现和确认流程。第一次使用时，Skill 会尝试读取 Obsidian 最近使用过的 Vault，展示真实绝对路径，例如：

1. D:/notes/My Vault
2. C:/Users/<user>/Documents/Obsidian Vault

用户选择并确认后，它会保存为默认 Vault。之后运行 Doctor、Query 或 Ingest 时可以自动使用，不需要每次重新输入路径。如果临时指定另一个 Vault，则只覆盖本次操作，不会偷偷修改默认配置。

第一次测试可以直接发送：

检查我的 Obsidian LLM Wiki 健康度，输出中文 Doctor 报告，不要修改任何文件。

如果当前还没有初始化 LLM Wiki，可以先发送：

初始化我的 Obsidian Vault。先盘点目录和文件类型，不读取笔记正文，也不要移动原始文件。

为什么我决定把它开源

这套 Skill 最初只是为了解决我自己的知识管理问题。经过一个多月的个人使用和项目内部试用后，我越来越确定：很多人缺少的不是另一个“帮你写笔记”的 AI，而是一套能让已有知识逐步变得可导航、可追溯和可维护的工作流。

真实的个人知识库不会一直保持整洁。它会增长，会出现重复，会遗漏 ingest，会产生失效链接，也会逐渐偏离最初的目录规划。因此，长期可用的 LLM Wiki 不能只关注“如何把资料放进去”，还需要回答三个问题：

1. 这些资料是否真正进入了知识网络？
2. Agent 能否沿着稳定入口找到它们？
3. 当结构开始腐烂时，用户能否先看见问题，再决定如何修复？

这也是我把 doctor 和 maintain 分开的原因。

开源仓库地址：

huajiexiewenfeng/obsidian-llm-wiki

如果你也有一个已经积累了很久的 Obsidian Vault，欢迎用真实资料测试它。尤其欢迎反馈新增文档发现、摄入覆盖度、Doctor 报告和 Query 质量方面的问题。这些真实使用场景，会继续决定项目下一步应该优化什么。

写在最后

过去我们常把知识库理解成“存放 Markdown 的地方”。但当它开始服务 LLM 和 Agent 后，知识库还需要具备另一组能力：知道入口在哪里，知道知识从哪里来，知道哪些内容没有被覆盖，也知道什么时候需要维护。

一个长期使用的 LLM Wiki，不应该只是越来越大的 Markdown 目录。它应该是一套可组织、可诊断、可维护、可查询的知识系统。

这次开源是第一步。下一步，我会继续补齐摄入覆盖度和知识新鲜度检查，并将内部 Project Develop 实践中验证过的经验逐步整理出来。

---