使用文档

安装、配置、掌握 LLM Wiki 的全部功能。

快速开始

# 方式一：Obsidian 插件
1. 安装插件到 Obsidian
2. 打开 Chat 面板（Cmd+Shift+C）
3. 输入 /init

# 方式二：Claude Code Skill
1. 将 llm-wiki skill 添加到 Claude Code
2. 打开任意目录
3. 说"在这里初始化 wiki"

/init 命令创建所有目录、CLAUDE.md、index.md 和 log.md — wiki 骨架即刻就绪。把文章丢进 raw/，然后输入 /ingest raw/你的文章.md 见证魔法。

安装

Obsidian 插件

  1. 从 最新 Release 下载 main.js、manifest.json 和 styles.css
  2. 放入 Vault 的 .obsidian/plugins/obsidian-llm-wiki/ 目录
  3. 在 Obsidian 设置 → 第三方插件中启用 "LLM Wiki"
  4. 安装 Claude Code 或 Cursor
  5. 安装 ACP 桥接：npm install -g @agentclientprotocol/claude-agent-acp
  6. 在插件设置中配置 ACP 可执行文件路径

Claude Code Skill

  1. 将 skills/llm-wiki/ 目录复制到 Claude Code 的 skills 文件夹
  2. 重启 Claude Code（或重新加载 skills）
  3. 进入任意目录，说 "在这里初始化 wiki"

Skill 创建同样的 wiki 结构 — 不需要 Obsidian。与任意文本编辑器配合使用。

建议： 如果你是 Obsidian 用户，用插件更顺滑（有文件选择器）。如果偏好终端或使用其他编辑器，用 Skill。

插件 vs Skill

Obsidian 插件Claude Code Skill
界面 Obsidian 内置图形界面 终端 / Claude Code 聊天
文件选择 图形化文件选择器 手动输入路径
Wiki 状态 内置状态面板 询问 LLM
快捷键 Cmd+Shift+C/E/S 标准 Claude Code
配置 插件安装 + ACP 桥接 放入 skill 文件夹
脱离 Obsidian 使用 否 是
批量操作 一次一个 可脚本化

核心操作

五个斜杠命令驱动整个知识编译管线。没有复杂的 UI。

/init — 初始化 Wiki 结构

第一个要运行的命令。创建完整的 wiki 骨架 — 所有目录、CLAUDE.md 规范、index.md 和 log.md。插件原生执行，通过 Obsidian 的 Vault API 本地执行，零 LLM 依赖，毫秒级完成。

Vault/
├── raw/          (tech/, work/, reading/, general/)
├── wiki/         (summaries/, concepts/, entities/, methods/, comparisons/, analysis/)
├── drafts/
├── legacy/
├── CLAUDE.md     ← LLM 操作规范
├── index.md      ← Wiki 主索引
└── log.md        ← 操作时间线

/ingest — 将文章编译为 Wiki

核心操作。喂入文章，LLM 将其编译为 wiki 条目。Ingest 工作流：

  1. 完整阅读源文件，浏览已有 wiki 索引
  2. 给出明确的处理方案（不是提问）— 建议的 summary 名称、要建/改的 concept/entity、风险提示 — 控制在 10 行以内
  3. 等待你一句话回复（"同意" / "改成 X" / "不要 Y"）
  4. 一气呵成完成所有文件操作：创建摘要页、更新概念页、更新实体页、提取方法论（如满足条件）、添加交叉引用、检查矛盾、更新索引和日志
/ingest raw/tech/transformer-paper.md

一次 ingest 可能触达 10–15 个 wiki 页面。来源标注是自动的 — 每段内容都标注了 (source: [[摘要文件名]])。

/query — 基于 Wiki 的问答

提出问题，LLM 查阅 wiki 索引，读取相关页面，综合回答并附上 wikilink 引用。如果回答有价值且可复用，可归档为 wiki/analysis/ 下的新页面。只有归档的查询记录到日志，未归档的不留痕。

/query self-attention 和 cross-attention 有什么区别？

/lint — Wiki 健康检查

全面审计，检查矛盾、孤立页面、过时内容、缺失页面、来源缺失、知识空白和方法论质量。LLM 能修的自动修（合并重复页面、重命名文件、补链接），其余的写入 wiki/lint-report.md。建议每周运行一次。

  • 页面矛盾 — 用 [!warning] 标注冲突声明
  • 孤立页面 — 没有其他页面链接到它
  • 过时内容 — 被新源取代的信息
  • 缺失页面 — 被反复提及但缺乏独立页面的概念
  • 来源缺失 — 没有标注来源的内容段落
  • 知识空白 — 附建议搜索方向的主题
  • 方法论质量 — 对照准入条件和骨架标准验证 method 页面

/scan — 历史库扫描

针对已有的几百篇旧笔记。轻量扫描 — 每个文件只读标题和前 10 行 — 生成索引地图到 legacy-index.md。后续按需精选迁移到 raw/ 做正式 ingest。

不要全量 ingest 历史内容。 推荐策略：先扫描，新内容走正常 ingest，按主题需要时再精选迁移历史内容。

标签审计

让 LLM 审计 wiki 的标签。扫描所有 frontmatter 标签，识别重复和近义标签，提出合并建议。你确认后它自动应用到所有页面。

审计 wiki/ 中的标签

CLAUDE.md 规范

CLAUDE.md 是整个系统最重要的文件。它不是 README — 它是 LLM 操作规范，Claude Code 启动时自动读取。它定义了目录结构、所有权规则、wiki 页面格式、操作流程和质量标准。把它想象成编译器的配置文件 — 编辑它，LLM 的行为就跟着变，不需要改任何代码。

CLAUDE.md 定义了：

  • 目录结构和所有权规则 — 谁能写哪里（raw/ 不可变，wiki/ 是 LLM 领地，drafts/ 人类专属）
  • Wiki 页面格式 — 必需的 YAML frontmatter：title、tags、sources、created、updated
  • 文件命名规范 — wiki/ 下所有文件用英文小写 kebab-case
  • 操作流程 — ingest、query、lint、scan 的逐步流程
  • 方法论质量标准 — 三条准入条件、五个自检问题、强制页面骨架
  • Wikilink 规则 — 只用文件名，绝不包含目录路径
  • 十条铁律 — 绝不修改 raw/、每次操作后更新 index、一次只 ingest 一篇等

规范中内置的关键设计原则：

  • raw/ 不可变 — LLM 读取源文件但绝不修改、移动或删除
  • wiki/ 是 LLM 的领地 — 人类阅读但不直接编辑 wiki 页面
  • 知识必须可追溯 — 每条声明通过 wikilink 链接回其原始来源
  • 矛盾标记，不静默覆盖 — 冲突信息用 [!warning] 标注
  • 日志仅追加 — 操作被记录供审计；用 tail 读取最近条目

Wiki 页面类型

LLM 在 wiki/ 中维护六种页面：

  • 摘要 Summary（wiki/summaries/）— 每个摄入源一个。一对一映射 raw 文件。文件名用英文 kebab-case 根据内容主题命名（禁止与 raw 源文件同名）。
  • 概念 Concept（wiki/concepts/）— 跨源综合。每个重要概念或主题一个页面。正文每段标注来源。
  • 实体 Entity（wiki/entities/）— 知名人物、工具、框架、组织。只建公众知名人物 — 非公众人物的文章作者在 summary frontmatter 记录 author 字段即可。
  • 方法论 Method（wiki/methods/）— 可复用的操作指南。必须满足三条准入：可照做、可迁移、非平凡。与 concept 严格分家（method 回答"怎么做"，concept 回答"是什么"）。
  • 对比 Comparison（wiki/comparisons/）— 相关事物的并排分析。
  • 分析 Analysis（wiki/analysis/）— 深度探索，通常由优质问答结果归档而来。

方法论质量标准

Method 页面有 wiki 中最严格的质量门槛。创建 method 页前，内容必须通过三条准入条件：

  1. 可照做 — 读者不需要理解背景就能按字面执行。"做 X；如果 Y，做 Z"，而不是"X 很重要"。
  2. 可迁移 — 步骤在源文之外的场景也站得住。只适用于特定产品/项目的操作手册不算方法论。
  3. 非平凡 — 至少有一条步骤、规则或反模式是非显然的。"先测试再上线"这种常识不算方法论。

三条必须同时满足，缺一不可。不满足的，一律不建 method 页 — 宁可一个 method 页都不建，也不要把 concept 复制一份塞到 methods 下。

来源追溯

Wiki 的核心价值是知识可追溯。每段信息都必须能追回到原始来源：

  • 摘要页面 — frontmatter sources 指向 raw 源文件
  • 概念 / 实体 /方法论页面 — frontmatter sources 列出所有贡献过内容的 raw 文件；正文用行内引用：(source: [[摘要文件名]])
  • 引用文件名必须使用实际存在的文件名 — 不要编造或推测

设计决策

为什么不用 RAG？

对于一万条以内笔记的个人知识库，简单的 index.md 比向量搜索更好用。零基础设施 — 不需要 embedding 管线或向量数据库。确定性 — 索引文件是人类可读的，可调试。上下文丰富 — LLM 读取完整页面，不是检索片段。交叉引用 — wikilink 创建可浏览的图谱，不是孤立块。当 wiki 增长到超过上下文窗口时，RAG 可以补充 — 但先用简单方案跑通。

为什么用 CLAUDE.md 而不是硬编码逻辑？

因为每个人的知识需求不同。有人要加 wiki/tutorials/，有人不需要 legacy/，有人用英文，有人用中文。CLAUDE.md 是一个可编辑的配置文件 — 改了它，LLM 的行为就跟着变。不需要重新编译插件。它也可复用：同一份 CLAUDE.md 适用于 Claude Code、Cursor 或任何遵循该格式的 LLM Agent。

为什么严格的目录所有权？

职责不清是笔记库腐烂的根本原因。当人和 AI 都编辑同一文件时，信任被侵蚀 — 你分不清哪些是 AI 生成的、哪些是人类整理的。明确边界：wiki/ 永远由 LLM 维护，你可以信任它的结构和来源标注。drafts/ 永远是人类专属，你有一个安全的草稿空间。

为什么 ingest 时不讨论？

早期版本让 LLM 在 ingest 前"讨论关键要点"。结果：LLM 写了一堆漂亮的分析但一个文件都没创建。解决办法：去掉所有讨论步骤。LLM 先给简短方案（10 行以内），你一句话批准或调整，然后它自动执行所有操作。就像 make build — 应该直接出编译产物，而不是打印一份"我打算怎么编译"的计划书。

日常使用循环

Wiki 搭好后，日常节奏很简单：

  1. 新文章 → 丢进 raw/ → /ingest → wiki 自动更新
  2. 有问题 → /query → 好回答 → 沉淀为 wiki 页面
  3. 定期 → /lint → 维护 wiki 健康
  4. 旧笔记 → legacy/ → /scan → 生成索引 → 按需迁移到 raw/

技巧与最佳实践

  • 一次只 ingest 一篇文章。 LLM 专注单个来源时产出更好。
  • 参与 ingest 过程。 LLM 先提方案，用一句话回复来引导侧重点。
  • 归档好答案。 只在聊天记录里的好答案等于丢失了。归档它。
  • 每周运行 lint。 定期维护防止积累混乱 — 就像给代码跑测试。
  • 用 Git 版本管理。 Wiki 就是 Markdown 文件目录，Git 给你历史、diff 和安全感。
  • 让 LLM 重命名文件。 不要手动整理 wiki 页面，lint 会发现命名问题并修复所有引用。
  • 不要在 prompt 里重复注入 CLAUDE.md。 Claude Code 启动时自动读取。重复注入浪费 token 且增加混淆。
  • 用 XML 标签隔离 prompt。 把原始源内容包在 <raw_input role="data"> 标签里，防止 LLM 把文章内容当成指令执行。

配套工具

与 LLM Wiki 配合使用的工具：

  • Obsidian — 用 Graph view 浏览 wiki，Dataview 做动态查询
  • Obsidian Web Clipper — 浏览器插件，把网页文章转为 Markdown 直接存入 raw/
  • qmd — 本地 Markdown 搜索引擎（BM25 + 向量搜索），wiki 变大后配合 index.md 使用
  • Marp — Markdown 转幻灯片，从 wiki 内容直接生成演示文稿
  • Git — Markdown 文件目录天然带版本历史