Roky Wang 的技术知识库

如何使用 Obsidian 构建一个技术知识库

18分钟阅读

如何使用 Obsidian 构建一个技术知识库

真正有价值的技术知识库，不是把文章、聊天记录和 PDF 堆进一个文件夹，而是把原始资料逐步转化为可验证、可连接、可继续更新的知识。这个项目采用 Obsidian 作为阅读与链接界面，以 Hermes Agent 和 llm-wiki 作为整理助手，再用 SCHEMA、AGENTS、知识库索引 和 log.md 约束知识的生命周期。^[SCHEMA.md] ^[AGENTS.md]

一、先明确知识库要解决什么问题

普通笔记系统经常遇到三个问题：资料不断增加，但无法判断哪些内容可信；同一主题被重复记录，却没有形成统一认识；每次向 AI 提问都像重新开始，过去的研究无法稳定复用。LLM Wiki 的核心思路，是让 AI 不只检索原文，还把资料整理成结构化 Markdown 页面，并通过 [[wikilinks]] 逐步形成知识网络。^[Clippings/Hermes Agent + LLM Wiki + Obsidian 个人知识库.md]

在这套系统中，人和 AI 的职责不同：

  • AI 负责读取资料、提取候选知识、发现已有页面、建立关联并生成草稿。
  • 人负责确认事实、修正判断、处理冲突，以及决定哪些内容值得成为长期知识。
  • Obsidian 负责呈现 Markdown、反向链接和知识图谱。
  • Hermes 负责按照规则执行摄入、查询和检查流程。

因此，这不是“全自动写笔记”，而是一套半自动的知识编译流程。

二、使用三层结构管理知识

1. 原始资料层：保存证据

raw/ 保存文章、论文、转录、视频资料、附件和书籍原件。原始资料一旦摄入就不再修改；如果需要纠错、翻译或总结，应新建知识页面，而不是改写来源。^[SCHEMA.md]

书籍采用独立目录保存原件和元数据。例如，本项目已经将《Clean Code》第一印次 PDF 存放在 raw/books/2008-clean-code-robert-c-martin/，并在 raw/books/README.md 的原始书籍归档规范中定义了文件命名、版本隔离和 SHA-256 完整性校验规则。^[raw/books/2008-clean-code-robert-c-martin/metadata.md]

2. 待审核层：隔离未确认内容

_inbox/ 是正式知识库之前的缓冲区：

  • _inbox/notes/ 保存自己写的随手记录、问题和灵感。
  • _inbox/drafts/ 保存根据 URL、PDF、RSS、公众号转发或其他文章生成的候选知识页。

收件箱内容可以不完整，也不默认参与正式知识查询。只有经过人工审核的内容，才进入正式目录；其具体审核边界见本地 Vault 的 _inbox/README.md。^[_inbox/README.md]

3. 正式知识层：保存经过确认的认识

正式页面按内容职责分类，而不是按资料来源分类。可以先把四个目录理解成四种不同的问题：

目录它回答的问题典型例子
entities/它是谁，或它是什么具体对象Hermes Agent、Obsidian、Andrej Karpathy
concepts/这个技术、原理或方法是什么意思LLM Wiki、RAG、双向链接
comparisons/多个对象有什么区别，应该如何选择RAG 与 LLM Wiki、Obsidian 与 Notion
queries/一个重要问题的完整答案是什么如何构建技术知识库

四种知识类型的下一层统一使用 aigc、architecture、cloud-native、database、golang、middleware 和 tools 七个主领域。每个页面只选择一个主领域；跨领域关系通过标签和 [[wikilinks]] 表达。

entities/ 保存可以被明确指认的人物、组织、产品、工具、模型、框架和项目。例如，2026-07-27-hermes-agent.md 可以记录 Hermes Agent 是什么、主要能力、启动方式、当前版本，以及它与 llm-wiki 的关系。如果页面标题通常是一个专有名词，它往往属于 entities/。

concepts/ 保存抽象概念、技术原理和方法论。例如，2026-07-27-llm-wiki.md 可以解释 LLM Wiki 的定义、原始资料层与知识层、资料如何转化为知识，以及为什么需要保留来源。如果标题适合用“什么是……”来提问，它通常属于 concepts/。

comparisons/ 用于围绕一个实际选择，对两个或多个对象进行结构化比较。例如，2026-07-27-rag-vs-llm-wiki.md 可以从工作方式、知识积累、适用场景和风险等维度比较 RAG 与 LLM Wiki。如果标题自然包含“与”“对比”“区别”或“如何选择”，它通常属于 comparisons/。

最简单的判断方式是：

Hermes Agent 是什么具体工具？       → entities/
LLM Wiki 是什么方法？               → concepts/
RAG 和 LLM Wiki 应该如何选择？       → comparisons/
如何用 Obsidian 构建技术知识库？      → queries/

同一篇外部文章可能同时提供实体、概念和比较知识，但不必为了填满目录而强行创建多个页面。只有某个对象或主题值得长期独立维护时，才单独建页。本页属于 queries/，因为它回答了一个需要综合多个项目规则、且以后会反复参考的问题。^[SCHEMA.md]

三、建立统一的页面规范

正式知识页必须包含 YAML frontmatter，用来描述标题、创建和更新时间、页面类型、标签、来源与置信度。文件名使用首次创建日期加小写英文 kebab-case；日期前缀与 created 保持一致，后续更新时不改变，例如：

queries/tools/2026-07-27-how-to-build-a-technical-knowledge-base-with-obsidian.md

建页前先搜索是否已有同主题页面。一个主题通常只有在两个以上来源中出现，或它是单一来源的核心主题时才值得建页；一笔带过的概念不应立即扩展成新页面。页面超过约 200 行时，应考虑拆分为更清晰的子主题。^[SCHEMA.md]

每个新页面应尽量添加至少两条有意义的 [[wikilinks]]。链接的目的不是增加数量，而是说明知识之间的真实关系。标签也只能使用 既有标签体系；需要新增标签时，应先更新规范并由维护者确认。

四、处理自己写的内容

自己的想法适合采用以下流程：

  1. 先写入 _inbox/notes/，不用为了格式完整而打断思考。
  2. 定期整理笔记，判断它是实体、概念、对比，还是值得长期保留的查询答案。
  3. 搜索正式目录，优先补充已有页面，避免创建同义重复页。
  4. 补全 frontmatter、来源、置信度和相关 wikilinks。
  5. 审核后移动到正式目录。
  6. 更新 index.md，并向 log.md 追加操作记录。

个人经验如果还没有外部证据，可以保留，但应明确它是经验判断，并使用 confidence: medium 或 confidence: low，避免把未经验证的观察写成通用事实。^[SCHEMA.md]

五、处理外部文章和资料

外部资料应遵循“先保存证据，再生成知识”的顺序：

  1. 保存 URL、作者、发布时间、摄入日期和原文；可下载文件还应记录摘要值。
  2. 将原始内容放入 raw/articles/、raw/papers/、raw/transcripts/、raw/video/ 或 raw/books/。
  3. 让 AI 检查正式目录中是否已有相关页面。
  4. 在 _inbox/drafts/ 生成候选总结，区分来源事实、作者观点和 AI 的综合判断。
  5. 人工核对关键结论、来源路径、日期和引用。
  6. 将审核通过的内容发布到正式目录，同时维护索引和日志。

现有 Clippings/ 是原 Vault 的保留内容，不应被自动批量迁移或改写。今后明确摄入的外部资料应优先进入 raw/，再从原始资料生成正式知识页。^[AGENTS.md]

当页面综合三个及以上来源时，应在具体论述后添加来源标记；如果新资料与旧页面冲突，应保留不同观点及其日期和来源，并在 frontmatter 中使用 contested: true 和 contradictions:，而不是直接覆盖旧结论。^[SCHEMA.md]

六、使用 Hermes 查询知识库

在本项目根目录启动 Hermes：

cd /Users/wxy/Documents/GitHub/rokywang-obsidian
WIKI_PATH="$PWD" hermes chat --skills llm-wiki

然后可以直接使用自然语言提问：

查询这个 Wiki：如何使用 Obsidian 构建技术知识库？
先读取 index.md，再读取相关正式知识页；必要时回查 raw/。
请列出引用的 [[wikilinks]] 页面。
只回答，不修改文件。

标准查询过程是：先读 index.md 定位页面，再搜索和阅读相关 Markdown，必要时回查 raw/ 验证来源，最后基于已整理知识综合答案。_inbox/ 默认不参与正式查询，除非明确要求 Hermes 审核或整理草稿。^[本机 /Users/wxy/.hermes/skills/research/llm-wiki/SKILL.md 与 _inbox/README.md，核验于 2026-07-27]

如果答案是一项重要对比、深度分析或重新推导成本很高的结论，可以明确要求 Hermes 把它写入 queries/ 或 comparisons/；普通事实查询不需要归档。

注意：现有剪藏文章中的 hermes init、hermes skill enable llm-wiki 和 /llm-wiki query 示例不能作为本机当前版本的直接操作依据。本项目实际验证的启动方式是上面的 WIKI_PATH="$PWD" hermes chat --skills llm-wiki。

七、维护索引、日志和质量

index.md 是知识库的导航入口。每次创建、修改或归档正式页面，都要同步维护所属分组、页面摘要、页面总数和最后更新日期。log.md 是只追加的变更历史，记录摄入、创建、更新、查询、检查和归档等操作。^[AGENTS.md]

建议定期让 Hermes 或 Codex 执行一次知识库检查，重点关注：

  • 没有其他页面指向的孤立页面；
  • 指向不存在文件的坏链接；
  • 未进入 index.md 的正式页面；
  • 缺少 frontmatter、来源或更新时间的页面；
  • 使用了未定义标签的页面；
  • 超过约 200 行、需要拆分的页面；
  • confidence: low、存在冲突或长期未更新的内容；
  • 原始资料摘要值发生变化的异常情况。

八、当前项目的实际状态

截至 2026 年 7 月 27 日，本项目已经具备：

  • 由 SCHEMA.md 定义的内容格式、标签、建页阈值和冲突处理规则；
  • 由 AGENTS.md 定义的 Codex 维护流程与安全边界；
  • raw/ 原始资料层及书籍归档规范；
  • _inbox/notes/ 与 _inbox/drafts/ 半自动审核缓冲区；
  • entities/、concepts/、comparisons/ 和 queries/ 正式知识目录；
  • index.md 导航与 log.md 追加式维护记录；
  • Hermes Agent + llm-wiki 的本地查询入口。

这篇文章是正式知识层中的第一篇页面。它的价值不只是介绍目录，而是把整个项目的维护原则收敛成一条可执行路径：

自己写作或采集资料
        ↓
保存原始证据或进入收件箱
        ↓
AI 生成候选知识并建立关联
        ↓
人工审核事实、来源和判断
        ↓
发布到正式知识目录
        ↓
更新索引与日志，持续查询和修订

九、将正式知识层构建并托管到 GitHub Pages

Obsidian 是本地写作和知识连接界面；对外阅读则可以由 Quartz 把 Markdown、frontmatter 与 [[wikilinks]] 编译为静态 HTML、搜索索引、反向链接和知识图谱。当前项目采用“先确定公开输入，再静态构建”的流程，而不是让构建器直接遍历整个 Vault：

正式知识页 + index.md + 规范页
        ↓ 白名单暂存（.site-content/）
Quartz 4.5.2
        ↓
public/ 静态站点
        ↓ GitHub Actions
GitHub Pages

发布白名单固定为根目录的 index.md、SCHEMA、AGENTS，以及 entities/、concepts/、comparisons/、queries/ 四类正式知识目录。raw/、Clippings/、_inbox/、_archive/、_meta/、.obsidian/ 和 log.md 不会复制到 .site-content/，因而不会出现在网站产物中。这个边界既保留知识库的可公开阅读层，也避免将原始资料、待审核草稿和本地使用痕迹默认暴露。^[site/README.md]

本地先执行以下命令验证；npm run stage 可单独检查公开输入，npm run build 会先暂存再生成 public/，而 npm test 与 npm run check 分别验证发布白名单和 Quartz 配置的测试、类型及格式。

npm ci
npm test
npm run check
npm run build
find public -type f | sort

Quartz 配置保留 Obsidian wikilink、全文检索、反向链接、图谱、目录、深色模式和代码高亮；页面地址会在 GitHub Actions 中从 GITHUB_REPOSITORY 推导，因此既适用于 owner.github.io 用户站点，也适用于 owner.github.io/repository 项目站点，无须将个人账号名写死在知识库。^[quartz/config.ts]

推送到 main 后，.github/workflows/deploy-pages.yml 会依次安装锁定依赖、运行测试与静态检查、构建 public/，再将该目录作为 Pages artifact 部署。首次接入 GitHub 仓库后，仍需在仓库的 Settings → Pages → Build and deployment 中选择 GitHub Actions；之后每次对正式知识或站点配置的提交都会触发同一流程。GitHub Pages 面向互联网发布，因此任何应保密的内容都必须继续留在发布白名单之外，而不能仅依赖仓库可见性。^[.github/workflows/deploy-pages.yml]

日常维护不变：资料先留在 raw/ 或 _inbox/，经审核后进入正式目录并更新 知识库索引 与 log.md；只有已晋升为长期知识的页面才会在下次构建时发布。这样，本地知识库的证据层与公开知识站点保持清晰、可复查的边界。

结论

使用 Obsidian 构建技术知识库，关键不在于安装更多插件，而在于建立稳定的知识生命周期：原始资料不可变、草稿与正式知识隔离、页面按职责分类、结论可以追溯、冲突不会被悄悄覆盖，并且每次整理都会增强未来的查询能力。

Obsidian 让知识可阅读、可链接，Hermes 让维护流程可执行，llm-wiki 提供从资料到结构化知识的方法，而人的审核决定了知识库最终是否值得信任。

关系图谱

反向链接