个人知识库

2026-05-28-woshipm-llm-wiki-qmd-architecture

11分钟阅读

LLM Wiki实战篇：少花token，多沉淀知识

基于 qmd 混合检索引擎的本地知识库四层架构——CLI 封装让 LLM 像调 API 一样操作知识库，CLAUDE.md 管行为规范，search-chunks + WIP 机制让 200 页论文不崩不断，六域分类按”命题”而非”学科”划分知识边界

基本信息

  • 来源类型：文章
  • 原文位置：raw/articles/2026-05-28-171259-tg-9cb4f3.md
  • 原文 URL：https://www.woshipm.com/ai/6399958.html
  • 作者：秋孝隱
  • 发布日期：2026-05-22
  • 字数：约 6934 字
  • 消化日期：2026-05-28

核心观点

  1. qmd 定位为本地知识库的”检索底座”而非全能引擎：qmd 不负责理解知识或设计知识结构，只负责一件事——当知识库变大之后，帮 LLM 找到该看的东西。选择 qmd 的五条具体理由是：知识以 Markdown 文件存在（文件系统式知识库）、需要 BM25 + 向量混合检索（精确词 + 语义）、需要让 LLM 稳定调用（封装成语义命令）、需要处理超长文档（块级检索）、需要本地轻量可迁移（文件夹 + Git + Obsidian）

  2. 四层架构中 CLI 层是最关键的设计：用户层（决定读什么）→ LLM 层（执行 ingest/query/lint）→ wiki CLI 层（bin/wiki 封装 qmd，提供 wiki search / wiki get / wiki find-related / wiki search-chunks 等语义命令）→ 系统层（raw + wiki + shared + qmd 索引）。LLM 不直接操作 qmd 原始命令，因为底层参数组合太多容易出错，封装后 LLM 只需理解几个语义化动作

  3. 目录设计的核心是”原始资料和整理结果分层，单篇文章和跨文章概念分开”：bin/（统一 CLI）→ shared/（跨域 entities、concepts、bridges）→ instances/（按域划分，每个域有自己的 raw、wiki、CLAUDE.md）。每个实例内 raw/ 只读不改，wiki/ 由 LLM 维护，_wip/ 保存长文档 ingest 进度

  4. qmd Collection 应按用途注册而非粗暴一个大集合：source 页面、concept 页面、entity 页面、raw 原文的用途完全不同——查询搜 wiki、ingest 找相关 concept、查证据搜 raw、长文档搜块级索引。每个 Collection 需要加 context description 告诉重排序模型”这个集合里装的是什么”，这直接影响检索质量

  5. CLAUDE.md 是整套系统的”行为规范手册”而非配置文件：它定义六个维度——角色定义（LLM 是维护者，两条红线：不改 raw 不改 log）、知识库定位（域边界明确化）、新会话启动流程（status + log-recent + wip-list）、Ingest 流程（读原文 → find-related → 确认计划 → 写页面 → 验证 → log + save）、Query 流程（search → get → 标注依据）、页面格式（模板化）。维护策略：先写一版能跑的，每次改一条，用下一篇文章测试

  6. 长文档处理的核心机制是”search-chunks + WIP 续传”：超长文档（200 页论文等）不能全文塞给 LLM——分三步：① 读摘要/目录判断主题拆分，创建 WIP 文件记录进度；② 每次只处理一个主题，用 wiki search-chunks "主题" -n 5 按块检索相关片段，处理完立刻更新 WIP 落盘；③ 全部完成后再做汇总写 synthesis。核心解决三件事：上下文爆、处理中断、读了前面忘了后面

  7. Lint 只抓结构问题，不判断内容真伪：YAML frontmatter 缺字段、wikilink 断链、stub 页面、concept 重复、raw 文件被意外修改（SHA-256 校验）、命名不统一——这些用程序检查。内容判断需要来源、证据和人的判断，不要交给 LLM 自己凭感觉看

  8. 六域分类按”命题”分不按”学科”分：形式域（公理推演：数学/逻辑）→ 自然域（可证伪：物理/生物）→ 技术域（人工系统构造：工程/软件）→ 心智域（主体经验：认知/情绪）→ 社会域（多主体互动：经济/政治）→ 哲学人文域（意义创造：哲学/艺术）。这解决跨学科文章的分类纠结——如 AlphaFold 模型架构归技术域、蛋白质折叠机制归自然域、科学发现方式变化归哲学人文域。但六域只是作者方案，核心是”要有一套稳定的分类边界”

实操内容保留

代码/配置

qmd Collection 注册示例：

technical-sources → technical/wiki/sources/*.md
technical-concepts → technical/wiki/concepts/*.md
technical-entities → technical/wiki/entities/*.md
technical-synthesis → technical/wiki/synthesis/*.md
technical-raw → technical/raw/**/*.md
shared-entities → shared/entities/*.md
shared-concepts → shared/concepts/*.md
shared-bridges → shared/bridges/*.md

操作步骤

从零搭建 LLM Wiki 的八步法：

  1. 安装 qmd：npm install -g @tobilu/qmd
  2. 建目录：选一个最常用的领域（如 technical），放 raw、wiki、CLAUDE.md
  3. 写 bin/wiki CLI：先封装 init、reindex、search、get、find-related、search-chunks、log、status
  4. 注册 qmd Collection：raw、sources、concepts、entities、synthesis 分开注册，写 context description
  5. 写 CLAUDE.md：角色 + 禁区 + ingest 流程 + query 流程 + 页面模板 + 新会话启动流程
  6. 找三篇文章试跑：第一篇暴露问题，第二篇调整 CLAUDE.md，第三篇验证流程稳定
  7. 加 lint：先查 frontmatter、broken wikilink、stub、raw hash，再慢慢加重复概念、过期页面
  8. 处长文档：等普通文章流程稳定后再加 search-chunks 和 WIP 机制

普通文章 Ingest 七步流程：

  1. 文章转 Markdown 放 raw/articles/（raw 不改）
  2. LLM 读取原文
  3. 提炼主题 + wiki find-related 找已有相关页面
  4. LLM 给出 ingest 计划，用户确认方向
  5. 写入 source / concept / entity / synthesis
  6. wiki get 验证刚写的页面
  7. wiki log + wiki save 记录日志保存版本

长文档 Ingest 三步流程：

  1. 准备：读摘要/目录判断主题拆分 → 创建 WIP 文件（wiki/_wip/）
  2. 按主题处理：wiki search-chunks "主题" -n 5 → 读片段 → 更新 wiki → 更新 WIP 落盘
  3. 汇总：搜主题间关系 → 写 synthesis → wiki wip-done → wiki log

关键概念

  • qmd — 本地知识库检索底座，支持 BM25 + 向量混合检索 + 重排序
  • 六域分类系统 — 按”命题”划分知识域的分类框架（形式/自然/技术/心智/社会/哲学人文）
  • 上下文工程 — CLAUDE.md 在本文中被定义为上下文工程的核心实践——行为规范手册
  • Claude Code — 本文描述其作为 LLM Wiki 系统中 LLM 层的执行载体
  • WIP 续传机制 — 超长文档 ingest 的断点续传设计

与其他素材的关联

  • 与 2026-05-21-woshipm-ai-knowledge-base-product-design 的关系：同为 AI 知识管理文章，但视角完全不同——本文是个人本地知识库的技术实现方案（qmd + CLI + CLAUDE.md），而那篇是从产品设计角度看知识库从个人到企业级的演进。两篇互补：一个解决”怎么建”，一个解决”做成什么产品”
  • 与 2026-05-13-ai-agent-productivity-20x 的关系：本文的 CLAUDE.md 设计理念与深思圈的”上下文资产”观点高度一致——CLAUDE.md 作为行为规范本质上是上下文工程的一种形态，让 LLM 按规矩干活而不是每次自由发挥
  • 与 2026-05-28-agents-md-coding-standard 的关系：两文都强调”规范文件”对 AI 行为的约束力——AGENTS.md 让代码规范率从 60% 飙到 95%，CLAUDE.md 让 LLM 在知识库维护中行为稳定。本质是同一种机制在不同场景的应用
  • 与 2026-05-27-pm-vibe-coding-5-products 的关系：Vibe Coding 文章提到”CLAUDE.md 入职手册的数据飞轮机制，目标 150 行”，本文则给出了 CLAUDE.md 的完整设计方法论（六维内容 + 渐进式维护策略）

原文精彩摘录

qmd 在这套方案里的定位很清楚：它是本地知识库的检索底座。它不负责替你理解知识，也不负责替你设计知识结构。它只负责一件事：当知识库变大之后，帮 LLM 找到该看的东西

LLM 不直接操作 qmd 原始命令，所有动作都走 bin/wiki。原因很简单：qmd 的能力比较底层，参数组合也多，直接让 LLM 调用容易出错。封装之后，LLM 只需要理解几个语义化动作

总结是一次性输出，ingest 是把文章变成知识库的一部分。后面你再问相关问题，这篇文章会和其他页面一起参与检索和推理

这套流程解决的核心问题是稳定性。长文档最怕三件事：上下文爆、处理中断、读了前面忘了后面。分块检索加 WIP 续传，可以把一个大任务拆成多个小任务，每个小任务都能独立完成、验证、保存

这五个问题都没有被”自动消灭”。更准确地说，这套架构给了它们一个可控的处理方式。知识库系统很难一劳永逸，关键是每个问题出现时，你知道它属于哪一层，该用什么机制处理

相关页面

关系图谱

快速导航

反向链接