llm-wiki

LLM Wiki —— 知识蒸馏模式

你正在维护一个持久且不断积累的知识库。这个 wiki 不是聊天机器人，而是一个编译后的产物：知识只蒸馏一次，并持续保持最新，而不是每次查询时都重新推导。

三层架构

第 1 层：原始来源（不可变）

用户的原始文档——文章、论文、笔记、PDF、对话记录、书签，以及图像（屏幕截图、白板照片、示意图、幻灯片截图）。系统绝不会修改这些内容。它们存放在用户自己的位置（通过 .env 中的 OBSIDIAN_SOURCES_DIR 配置）。图像是一级来源：导入技能会通过 Read 工具的视觉支持读取图像，并将解读出的内容视为推断内容，除非它是逐字转录的文本。导入图像需要支持视觉的模型——不支持视觉的模型应跳过图像来源，并报告跳过了哪些文件。

可以将原始来源视为“源代码”——它们具有权威性，但不便于直接查询。

不要将这与库中的 _raw/ 暂存文件夹混淆：两者不是一回事。_raw/ 是用于快速捕获和草稿的临时收件箱，等待后续提升为正式内容（参见 wiki-capture 和 wiki-ingest）。其中的文件并非第 1 层来源，但 wiki-ingest 在提升内容时仍会移动而非删除这些文件，因为有些文件没有其他副本。

第 2 层：Wiki（由 LLM 维护）

由相互链接的 Obsidian 兼容 Markdown 文件组成的集合，按类别组织。这是编译后的知识——经过综合整理、交叉引用，且便于浏览。每个页面都包含：

• YAML frontmatter（标题、类别、标签、来源、时间戳）
• 用于关联相关概念的 Obsidian [[wikilinks]]
• 清晰的出处信息——每条主张都可追溯到来源

Wiki 位于 .env 中通过 OBSIDIAN_VAULT_PATH 配置的路径。

第 3 层：架构规范（此技能 + 配置）

用于规范 wiki 结构的规则——类别、约定、页面模板和操作工作流。架构规范告诉 LLM 应如何维护 wiki。

Wiki 组织方式

库有两个层级的结构：类别（知识的类型）和项目（知识的来源）。

类别

将页面归入以下默认类别（可在 .env 中自定义）：

类别	用途	示例
concepts/	思想、理论、思维模型	concepts/transformer-architecture.md
entities/	人物、组织、工具、项目	entities/andrej-karpathy.md
skills/	操作知识、流程	skills/fine-tuning-llms.md
references/	特定来源的摘要；学术论文使用下文的论文深度剖析模板	references/attention-is-all-you-need.md
synthesis/	跨来源的综合分析	synthesis/scaling-laws-debate.md
journal/	带时间戳的观察记录、会话日志	journal/2024-03-15.md

项目

知识通常属于特定项目。projects/ 目录也采用相同的结构：

$OBSIDIAN_VAULT_PATH/
├── projects/
│   ├── my-project/
│   │   ├── my-project.md      ← project overview (named after project)
│   │   ├── concepts/          ← project-scoped category pages
│   │   ├── skills/
│   │   └── ...
│   ├── another-project/
│   │   └── ...
│   └── side-project/
│       └── ...
├── concepts/                   ← global (cross-project) knowledge
├── entities/
├── skills/
└── ...

知识仅适用于特定项目时（例如只适用于某个代码库的调试技巧、项目特定的架构决策），将其放在 projects/<project-name>/<category>/ 下。

知识具有通用性时（例如“React Server Components”这类概念、“Andrej Karpathy”这类人物、广泛适用的技能），将其放在全局类别目录中。

**交叉引用：**项目页面应使用 [[wikilink]] 链接到全局页面，反之亦然。项目概览页面应链接到与该项目相关的关键概念、技能和实体页面，无论它们位于项目目录下还是全局目录中。

**命名规则：**项目概览文件必须命名为 <project-name>.md，不能命名为 _project.md。Obsidian 的关系图视图使用文件名作为节点标签；_project.md 会让每个项目在图中都显示为 _project，导致图表难以阅读。因此，文件应命名为 projects/my-project/my-project.md、projects/another-project/another-project.md 等。

每个项目目录都有一个结构如下的概览页面：

---
title: >-
    My Project
category: project
tags: [ai, web, backend]
source_path: ~/.claude/projects/-Users-name-Documents-projects-my-project
created: 2026-03-01T00:00:00Z
updated: 2026-04-06T00:00:00Z
---

# My Project

One-paragraph summary of what this project is.

## Key Concepts
- [[concepts/some-api]] — used for core functionality
- [[projects/my-project/concepts/main-architecture]] — project-specific architecture

## Related
- [[entities/some-service]] — deployment platform

特殊文件

每个 wiki 的根目录都有以下文件：

使用 obsidian-wiki memory 编写这些文件，切勿手动编写。 index.md、 log.md、hot.md 和 _meta/ 表共用一个 advisory lock，并以原子方式 写入；如果并行运行时手动编辑，后写入的内容会覆盖先写入的内容。 obsidian-wiki memory sync <VERB> key=value 可在一次调用中完成这三项操作。 完整流程——包括动词、由你维护的 Key Takeaways 部分、所有者资料和待办事项索引——请参阅 references/MEMORY.md。

index.md

按类别组织的内容目录。每个条目都有一行摘要和标签。每次摄取操作后都要重建此文件。格式如下：

# Wiki Index

## Concepts
- [[transformer-architecture]] — The dominant architecture for sequence modeling ( #ml #architecture)
- [[attention-mechanism]] — Core building block of transformers ( #ml #fundamentals)

## Entities
- [[andrej-karpathy]] — AI researcher, educator, former Tesla AI director ( #person #ml)

格式规则：在左括号后和标签前添加空格。 ❌ 不要这样写：description (#tag) — 会导致标签解析失败 ✅ 应这样写：description ( #tag) — 空格格式正确，标签也能正确解析

log.md

按时间顺序追加的记录，用于追踪每次操作。每个条目都可解析：

## Log

- [2024-03-15T10:30:00Z] INGEST source="papers/attention.pdf" pages_updated=12 pages_created=3
- [2024-03-15T11:00:00Z] QUERY query="How do transformers handle long sequences?" result_pages=4
- [2024-03-16T09:00:00Z] LINT issues_found=2 orphans=1 contradictions=1
- [2024-03-17T10:00:00Z] ARCHIVE reason="rebuild" pages=87 destination="_archives/..."
- [2024-03-17T10:05:00Z] REBUILD archived_to="_archives/..." previous_pages=87

.manifest.json

记录已摄取的每个源文件：路径、时间戳，以及它生成了哪些 Wiki 页面。这是增量系统的基础。完整架构请参阅 wiki-status 技能。

清单支持：

• 增量计算 — 自上次摄取以来新增或修改了哪些内容
• 追加模式 — 只处理增量内容，而非全部内容
• 审计 — 哪个源文件生成了哪个 Wiki 页面
• 过时检测 — 源文件已更改，但 Wiki 页面尚未更新

源键约定（v2）。 源键——.manifest.json 中的 sources 键、页面 frontmatter 中的 sources: 值，以及项目的 source_repo——必须可跨机器使用。知识库会在不同机器之间同步，因此裸绝对路径（/Users/...、/home/...）绝不能作为有效的存储键。这是唯一的规范定义；其他技能会引用此处，而不会重复说明。

源所在位置	规范键格式	示例
知识库内	相对知识库的路径 — 使用 POSIX 分隔符，不带前导 ./，也不含 ..	Raw/database/postgres.pdf、Clippings/article.md
$HOME 下	相对主目录的路径 — 以 ~ 开头	~/.claude/projects/-Users-name-my-app/abc.jsonl
并非文件	伪键 — 任意 scheme:/:// 标识符，视为不透明标识符	url:https://example.com/article、agent:claude/<session-id>

规则：

1. 绝不存储裸绝对路径。 写入前就要转换，而不是事后转换。
2. 比较前先规范化。 展开 ~ 和环境变量，将相对知识库的键解析为相对于知识库根目录的路径，并将 scheme:/:// 伪键视为不透明标识符。未经规范化，绝不直接比较原始字符串。
3. 路径变更后仍保持身份一致。 同一个逻辑源在不同机器上使用相同的键。
4. 伪键使用开放命名空间。 键是否为伪键取决于其格式（scheme: 或 ://，因此不会与文件路径混淆），而非固定名称列表。建议使用以下名称：git 项目使用 repo:<host/owner/name>，网页使用 url:<canonical-url>，Agent 会话使用 agent:<agent>/<id>。不在知识库内也不在 $HOME 下的源仍需要一个伪键——不要让它回退为绝对路径。
5. 项目身份对应仓库，而非检出目录。 在 projects 区块中，使用 source_repo（host/owner/name）标识项目，而非机器路径。特定机器上的检出位置（如果确实有用）应放在可选的 source_cwd_hint（相对 ~）中，绝不能用于标识身份。

读取时保持向后兼容：包含绝对路径键的现有清单仍可正常使用，scripts/manifest.py migrate <vault> --dry-run 会将其转换为约定 v2（合并冲突项，保留最新的 ingested_at）。如果知识库已在不同机器之间迁移，其中的绝对路径以旧知识库路径为根目录，既不匹配新知识库，也不匹配 $HOME——请通过 migrate <vault> --from-root <old-vault-root> 显式传入旧根目录（若知识库曾位于多个位置，请重复使用此标志）。此时命令会报告 nothing portable to write — N key(s) kept non-portable，而不会声称操作成功。新写入的内容会经过同样的规范化，因此技能即使向 obsidian-wiki cache-update 传入绝对路径，写入清单的键仍可跨机器使用。

记录来源信息。 写入清单条目时，请在 pages_created 和 pages_updated 中填入该源文件所贡献内容对应的、相对于知识库的页面路径。这样，源文件更改后重新摄取时，才能找到需要重新处理的页面，而不必猜测。

页面模板

创建新的 Wiki 页面时，请使用以下结构：

---
title: >-
    Page Title
category: concepts
tags: [ml, architecture]
aliases: [alternate name]
relationships:
  - target: "[[concepts/related-concept]]"
    type: extends
sources: [papers/attention.pdf]
summary: >-
    One or two sentences, ≤200 chars, so a reader (or another skill) can preview this page without opening it.
provenance:
  extracted: 0.72
  inferred: 0.25
  ambiguous: 0.03
base_confidence: 0.65
lifecycle: draft
lifecycle_changed: 2024-03-15
tier: supporting
created: 2024-03-15T10:30:00Z   # both from `obsidian-wiki memory now`, which honors the vault's timezone: key
updated: 2024-03-15T10:30:00Z
# Optional. Written only by `obsidian-wiki snapshots set` / `apply` — do not hand-author.
# Quoted wikilinks with |title: Obsidian Properties does not treat Markdown [text](path) as links.
snapshots:
  - "[[_raw/_archived/example-clip|example-clip]]"
---

# Page Title

One-paragraph summary of what this page covers.

## Key Ideas

- The source's central claim, paraphrased directly.
- A generalization the source implies but doesn't state outright. ^[inferred]
- A figure two sources disagree on. ^[ambiguous]

Use [[wikilinks]] to connect to related pages.

## Open Questions

Things that are unresolved or need more sources.

## Sources

- [[_raw/_archived/example-clip.md]] — snapshot this page was distilled from

来源部分（必填，正文最后一节）。 每个 Wiki 页面都以 ## Sources 结尾。条目必须能在 Obsidian 中点击：

• 本地快照（原始摄取内容、放入的 PDF/图片、Web Clipper 文件，以及任何进入 _raw/ 并已归档的内容）：在正文的 Sources 部分中使用 [[_raw/_archived/<filename>]]（正文中的 Wiki 链接可以包含 .md）。YAML sources: 保留来源键（url:、agent:、仓库路径等），不要填写归档路径。YAML snapshots: 是单独的字段：将文件移至 _raw/_archived/ 后，运行 obsidian-wiki snapshots set <page> --archive _raw/_archived/<filename>，然后对该已归档路径运行 obsidian-wiki cache-update。CLI 会写入一个带显示文本的引用链接列表，例如 "[[_raw/_archived/clip|clip]]"（目标中不带 .md；|clip 是 Properties 中显示的内容）。不要在 snapshots: 中放入 Markdown 格式的 [title](path)——Properties 会将其显示为不可点击的文本。snapshots CLI 不会改动正文。不要链接剪辑文件 frontmatter 中记录的网页——该 URL 是可变的来源元数据。
• 已抓取的 URL（使用 /ingest-url 且未保存快照）：使用指向规范 URL 的 Markdown 链接，并在 YAML sources: 中填写 url:<canonical-url>。
• 不要混淆两者。剪辑网页不等于从 URL 摄取内容。

相关 Wiki 页面应放在 Related / relationships: 中，而不是 Sources 中。

解析器安全的标量。 自由文本 frontmatter 值（至少包括 title 和 summary）应采用上文所示的折叠标量语法（>-）：不加引号的标量若包含 : （冒号加空格）、# 或引号，会导致 YAML 解析失败，Obsidian 随后会报告 “Invalid properties” 并隐藏 frontmatter。请将值缩进放在 title: >- / summary: >- 后的行中。

论文深入分析模板

通用模板适用于大多数来源。学术论文是例外。 对于存放在 references/ 中的 ML/AI/LLM/VLM 等领域论文，核心内容在于架构、公式和结果表——而简短的“关键思路”列表会将这些内容一概压平。因此，这类论文应使用下面更丰富的模板。这是唯一一处“编译，而非检索”的原则要让位于全面、自成一体的讲解之处，让读者可以用它替代论文进行学习。

Obsidian 原生支持所需的基本功能，无需额外工具：Mermaid 围栏图表、$$…$$ LaTeX（MathJax）、Markdown 表格，以及 ![[image]] / ![[paper.pdf#page=N]] 嵌入。

仅当来源是含有关键图表或公式的学术论文（arXiv/会议论文）时，才使用此模板。其他所有内容均使用上文的通用页面模板。Frontmatter、来源标记、置信度、生命周期和 relationships: 均保持不变——只有正文各节不同。

---
# ...required frontmatter, same as the generic template; category: references...
---

# Paper Title

> [!tldr] One sentence: what's new, plus the headline result.

## Problem & Motivation

What's broken or missing that this paper addresses.

## Method / Architecture

Prose walkthrough. Embed the paper's real architecture figure as the primary
visual (see *Academic papers* in `wiki-ingest` for the PyMuPDF extraction recipe).
Fall back to a Mermaid flowchart only when no figure can be extracted.

![[attachments/<slug>-fig1.png]]
*Figure N (Author Year): one-line caption.*

## Key Equations

The 1–3 core equations as display math, not backtick code:

$$ \mathcal{L} = \mathbb{E}_{x}\!\left[-\log p_\theta(y \mid z)\right] $$

## Results

Headline numbers as a table, not a comma-separated blob — and embed a key
results/motivating figure (scaling plot, benchmark chart, capability collage)
when the paper has one:

| Method | Benchmark | Metric | Cost |
|---|---|---|---|
| Baseline | … | … | … |
| **This paper** | … | … | … |

![[attachments/<slug>-resultsN.png]]
*Figure N (Author Year): one-line caption.*

## Limitations

What the paper concedes or sidesteps. Mark reading-between-the-lines as ^[inferred].

## Related

Typed `[[wikilinks]]` to neighbouring work.

## Sources

- [[_raw/_archived/paper.pdf]] — snapshot distilled (if a local PDF/clip was ingested)
- <https://arxiv.org/abs/XXXX.XXXXX> — only if this ingest fetched the URL and there is no local snapshot

根据论文文字重构的 Mermaid 图表属于综合归纳，而非原文转录——如果其解读并非显而易见，应将其标记为 ^[inferred]。

来源标记

Wiki 页面上的每条声明都属于三种来源状态之一。请在行内标记，以便读者（以及后续摄取流程）区分信号与综合推断。

这些是框架默认值。知识库的 AGENTS.md 可以添加标记或工作流标志。保留所有者扩展，并将正交的工作流标志与提取／推断／模糊这一真值状态轴分开处理。

状态	标记	含义
已提取	（无标记——默认）	对来源实际内容的转述。
推断	^[inferred] 后缀	大模型综合得出的声明——来源未直接说明的联系、概括或推论。
模糊	^[ambiguous] 后缀	来源之间存在分歧，或来源内容不明确。

示例：

- Transformers parallelize across positions, unlike RNNs.
- This is why they scale better on modern hardware. ^[inferred]
- GPT-4 was trained on roughly 13T tokens. ^[ambiguous]

为什么采用这种语法：

• 在 Obsidian 中，^[...] 与脚注相邻——渲染简洁，且不会与 [[wikilinks]] 冲突。
• 放在行内（作为后缀），这样单条项目符号仍是单条项目符号。
• 默认状态为已提取，意味着没有标记的现有页面仍然有效。

Frontmatter 摘要： 可选择在页面级别展示大致比例，让用户无需通读页面，就能快速识别推测内容较多的页面：

provenance:
  extracted: 0.72   # rough fraction of sentences/bullets with no marker
  inferred: 0.25
  ambiguous: 0.03

这些数字是摄取技能在创建／更新时尽力写入的估算值。wiki-lint 会重新计算并标记偏差。此区块为可选项——按照惯例，没有此区块的页面会被视为内容均已提取。

任何发生变化的内容都要注明日期。 数量和金额会过时：星标数、用户数、客户数、下载量、交易额、MRR。请标注日期，例如 291★ (截至 2026-06-30)，或放在带日期的标题下，也可以链接到实时数据所在位置，而不是直接复制数值。不带日期的“23 星标”会让人以为它永远准确。obsidian-wiki lint 会将未注明日期的条目标记为 undated_claims。

类型化关系

页面正文中的普通 [[wikilinks]] 不带有语义权重——它们表示“相关”，但没有说明如何相关。可选的 relationships: frontmatter 区块可为知识图谱添加带类型和方向的边。

relationships: 区块

relationships:
  - target: "[[Transformer Architecture]]"
    type: extends
  - target: "[[LSTM]]"
    type: contradicts
  - target: "[[Attention Mechanism]]"
    type: implements

每个条目都必须包含两个字段：

• target — 指向相关页面的 wikilink（使用与 OBSIDIAN_LINK_FORMAT 相同的格式）
• type — 以下允许的语义类型之一

允许的关系类型

下表是框架默认的允许列表。知识库的 AGENTS.md 可以扩展此列表；使用者必须采用生效后的允许列表，并保留所有者语义，不得强行转换。

类型	含义	示例
extends	此页面在目标页面的基础上扩展或概括	GPT 扩展了 Transformer Architecture
implements	此页面是目标概念的具体实现	BERT 实现了 Masked Language Modelling
contradicts	此页面的声明与目标页面冲突或对其提出反驳	Evidence A 与 Evidence B 相矛盾
derived_from	此页面基于目标页面编写或改编而来	Fine-tuning 源自 Transfer Learning
uses	此页面依赖或使用目标页面	RAG 使用 Vector Databases
replaces	此页面取代目标页面，或使其不再适用	GPT-4 取代 GPT-3
related_to	通用类型：存在关联，但不适用更明确的方向性类型	Concept A 与 Concept B 相关

规则

• 可选字段 — 如果没有已知的类型化关系，请完全省略整个区块。未标记的维基链接仍然有效，wiki-export 会将其视为 related_to。
• 不要重复 — 如果 [[foo]] 已经以内联维基链接的形式出现，relationships: 条目只是为它补充类型，而不是添加第二个链接。
• 方向很重要 — 声明该条目的页面是源；target 是目标。只从当前页面的角度声明关系。
• 不要臆造 — 只有当源材料明确说明关系的方向和类型时，才添加类型化条目。如有疑问，请使用 related_to 或省略。

读取 relationships: 的技能：wiki-export（输出类型化边）、cross-linker（推断链接时写入类型化条目）、wiki-query（在回答中显示类型，并在多跳“X 如何与 Y 相连”的路径查询中遍历类型化边图 — 对 relationships: 邻接关系进行有界 BFS，仅限 frontmatter）。

置信度与生命周期

每个页面都有两个相互独立的信任信号，以及一个可选的取代链接。

以下必填要求和生命周期值是框架默认值。知识库的 AGENTS.md 可以扩展生命周期值，或将信任字段设为可选。验证器必须应用生效的所有者架构，同时仍验证任何已提供的信任值。

确定性 lint/信任使用方通过 OBSIDIAN_ALLOWED_LIFECYCLES、OBSIDIAN_ALLOWED_RELATIONSHIP_TYPES、OBSIDIAN_REQUIRED_TRUST_FIELDS 和 OBSIDIAN_SCHEMA_SOURCE 接受所有者架构。解析优先级为 CLI > 环境/配置 > 这些框架默认值（生命周期和关系扩展以累加方式应用）。显式为空或仅包含空白字符的值会导致验证失败；省略该变量则使用默认值。wiki-lint/SKILL.md 规定了操作调用规范。

必填字段

base_confidence: 0.65          # [0.0, 1.0] — time-independent quality estimate. Stored once, recomputed on content change.
lifecycle: draft               # draft | reviewed | verified | disputed | archived
lifecycle_changed: 2024-03-15  # ISO date of last state transition
# lifecycle_reason: "..."      # optional free-text — why the state changed; surfaced by wiki-query
# superseded_by: "[[new-page]]" # wikilink; only when lifecycle=archived

lifecycle_reason 和 superseded_by 是可选字段。切勿臆造。

置信度公式

该公式是人工设定的基础评分，并非确定性的 URL 分类器：

base_confidence = lineage_count_score * 0.5 + source_quality_score * 0.5

lineage_count_score  = min(independent_evidence_lineages / 3, 1.0)
source_quality_score = avg(reviewed quality score per independent lineage)

计算原始分数后，评估证据是否涵盖页面的实质性主张。部分覆盖可能足以维持或降低分数；对于缺乏支持的实质性主张，必须先修复来源或主张，然后才能调整置信度。避免在认知层面没有实质变化时小幅调整分数。

来源质量评分（使用匹配度最高的档位）：

档位	分数	示例
paper	1.0	arXiv、会议论文集
official	0.9	*.gov、供应商文档
documentation	0.85	维护良好的第三方文档
book	0.8	书籍、技术参考资料
repository	0.75	内容寻址的代码库／代码证据
blog	0.55	个人博客
session_transcript	0.5	对话历史或已完成的操作
forum	0.4	Stack Overflow、HN、Reddit、问题级报告
unknown	0.4	兜底／当前配置
llm_generated	0.3	大模型合成内容或未经验证的记忆种子

独立证据溯源是指能够独立佐证某项主张的来源。规范来源 ID 仍有助于标识来源，但仅凭标识本身无法证明来源独立。计数前应合并存在依赖关系的证据：

• 同一代码库中的文件、发布版本和提交 → 一个代码库溯源；
• 同一工作流中的重试／审核／修复任务 → 一个任务溯源；
• 父／子 Kanban 记录 → 一个任务溯源；
• 不同配置文件中逐字节相同的记忆 → 一个记忆溯源；
• 快照及其所捕获的可变来源 → 一个溯源；
• 解析到同一来源的别名或元数据引用 → 一个溯源。

确定性的 wiki-lint 路径会验证 _meta/trust-ledger.json；它不会根据来源字符串重新计算置信度。新建或有实质性变更的页面会标记为需要人工审核。只有在获得明确的人工批准后，才能刷新账本。

各技能的默认值（摄取技能会自动计算）：

技能	base_confidence	lifecycle
wiki-ingest（URL）	0.17 + 0.5 × classify(url)	draft
wiki-ingest（单份文档）	按来源分类器计算	draft
wiki-ingest（多份文档）	min(N/3,1)×0.5 + avg_q×0.5	draft
wiki-research	不固定，通常为 0.85+	draft
wiki-capture	0.42	draft
*-history-ingest	0.42	draft
wiki-update	0.59	draft
wiki-synthesize	min(input_pages.base_confidence)	draft

生命周期状态机

共五种状态。stale 不是一种状态，而是一个计算得出的覆盖标记：is_stale = (today − updated) > 90 days。

状态	进入方式	说明
draft	任一摄取技能首次写入	所有新页面的默认状态
reviewed	仅限人工编辑
verified	仅限人工编辑	不会仅因时间推移而降低已验证页面的状态
disputed	仅限手动编辑	在显示时覆盖除 archived 以外的所有状态
archived	手动编辑，或摄取技能设置 superseded_by	终止状态

只有摄取技能可以设置 draft。所有其他状态转换都需要人工编辑者。每当状态发生变化时，都要更新 lifecycle_changed。

因此，以下两类边属于非法状态转换，obsidian-wiki lint 会将其报告为 illegal_lifecycle_transitions：任何回退到 draft 的转换（reviewed|verified|disputed → draft），以及任何退出 archived 的转换（该状态为终止状态——恢复页面需要有意删除并重新创建，而非状态转换）。该检查会将页面当前状态与该页面上次审核时 _meta/trust-ledger.json 中记录的生命周期状态进行比较，因此只会检查至少审核过一次的页面。

重要性分级

系数： 字段用于控制每轮摄取中哪些页面会更新，以及它们在检索中的优先级。随着知识库不断增长，每轮摄取都重新读取所有页面会浪费令牌；分级可以让摄取和查询技能将精力集中在最重要的内容上。

三个层级

层级	含义	摄取行为	查询优先级
core	承载关键内容的页面——许多其他页面依赖它们（入链数量多或处于桥接位置）。始终值得更新。	只要来源哪怕与页面略有关联，就始终更新	在索引和全文读取阶段优先展示
supporting （默认）	连接度适中的标准 Wiki 页面	仅当来源包含明确适用于此页面的新主张时才更新	标准优先级
peripheral	连接度低的页面——很少被链接，主题范围狭窄	除非来源主要讨论此主题，否则跳过	最后考虑；缩减至上下文预算时跳过

分配规则

• **新页面：**默认设为 tier: supporting
• **提升为 core：**当页面累计 ≥5 个入链 Wiki 链接，或被 wiki-status 的 insights 模式标记为桥接页面时
• **降级为 peripheral：**当页面只有 ≤1 个入链链接，且 90 天以上未更新时
• 人工覆盖始终优先——手动编辑 tier:，即可将页面锁定在任意层级
• 未设置 tier: 的现有页面视为 supporting（向后兼容——无需迁移）

谁负责管理层级

• wiki-ingest 读取 tier:，以决定在当前轮次是否更新页面
• wiki-query 使用 tier:，在索引阶段排列候选页面并缩减至上下文预算
• wiki-status 的 insights 模式会计算图指标并建议层级分配——绝不会自动写入
• wiki-lint 会标记新建页面缺少 tier: 的情况（第 2 阶段强制执行，时间安排与 base_confidence 相同）

检索原语

读取知识库是每项读取侧技能的主要成本。请使用能够回答问题的最低成本原语，仅在较低成本的原语不足时才升级。任何需要知识库内容的技能都应遵循此表，而不是直接读取完整页面。

需求	原语	相对成本
页面是否存在？它的标题／类别／标签是什么？	读取 index.md；使用 Grep 搜索 frontmatter 块（通过匹配文件开头 ^--- 块的模式限定范围）	最低
页面 1–2 句预览	读取其 frontmatter 中的 summary: 字段	低
页面中的特定主张或章节	Grep -A <n> -B <n> "<term>" <file> — 仅返回匹配行及其上下文	中
整页内容	Read <file>	高 — 最后手段
跨页面关系	在整个知识库中执行 Grep "\[\[.*?\]\]"，或从已知页面遍历 Wiki 链接	视情况而定

**搜索命令优先级：**对于 shell／文件搜索，若可用，请使用 ripgrep（rg、rg --files）；否则回退到 grep／find。这些技能中首字母大写的 Grep／Glob 名称，是面向提供这些工具的 Agent 的通用工具原语。

**规则：**仅当较低成本的原语无法回答问题时才升级。如果仅凭 summary: 字段就能回答，就不要读取页面正文。如果通过 -A 10 -B 2 检索到的章节已经给出了主张，就不要读取整页。打开一个 500 行的页面却只读 15 行，相当于浪费了 485 行的令牌。

**为何重要：**知识库只有 20 页时，全库扫描尚可应付；有 200 页时则不然。上述原语能让技能框架在没有数据库的情况下扩展到大型知识库。

使用此表的技能：wiki-query、cross-linker、wiki-lint、wiki-status（insights 模式）。任何读取知识库的新技能都应引用本节，而非重新设计这套模式。

QMD 索引新鲜度

QMD 是构建在知识库之上的可选搜索索引。Markdown 知识库才是事实来源。任何会写入 Wiki Markdown 的技能都应在知识库写入完成后刷新 QMD，但仅当已配置 QMD_WIKI_COLLECTION 且本地 QMD 传输可用时才刷新。如果 QMD 刷新失败，应保留知识库更改，并单独报告 QMD 状态。

使用能够证明新内容可见的最简验证路径：运行 qmd update；仅当向量已过期或缺失时运行 qmd embed；然后针对一篇已写入的页面或集合根目录执行定向 qmd get 或 qmd ls 检查。只读技能不应刷新 QMD。

核心原则

1. 编译，而非检索。 Wiki 是预编译的知识。摄取来源时，应更新所有相关页面，而不只是为来源创建摘要。

2. 随时间积累。 每次摄取都应让 Wiki 变得更智能，而不只是更庞大。将新信息合并到现有页面中，解决矛盾，加强交叉引用。

3. 来源追溯很重要。 每项说法都应能追溯到来源。更新页面时，注明是哪项来源促使了此次更新。

4. 标记推断。 默认句子均为摘录内容。使用 ^[inferred] 标记综合得出的说法，使用 ^[ambiguous] 标记有争议的说法。掩盖猜测的 Wiki 会悄然腐朽；明确标记的 Wiki 才能保持可信。

5. 人类负责策展，LLM 负责维护。 人类决定添加哪些来源、提出哪些问题。LLM 负责处理维护工作——更新交叉引用、保持一致性、注明矛盾。

6. Obsidian 是 IDE。 用户在 Obsidian 中浏览和探索 Wiki。所有内容都必须是有效的 Obsidian Markdown，并包含可用的 Wiki 链接。

链接格式

连接 Wiki 页面之间的所有内部链接都由解析后的配置中的 OBSIDIAN_LINK_FORMAT 控制（默认值：wikilink）。

设置	语法	示例
wikilink (默认值)	[[path/to/page]] 或 [[path/to/page|display text]]	[[concepts/foo|foo]]
markdown	[display text](relative/path.md)	[foo](../concepts/foo.md)

生成 Markdown 格式的链接

当 OBSIDIAN_LINK_FORMAT=markdown 时：

1. 从当前文件所在目录计算到目标 .md 文件的相对路径；需要时使用 .. 向上跳转。
2. 使用页面标题或自然短语作为显示文本。
3. 始终包含 .md 扩展名。

当前文件	目标	相对链接
index.md	concepts/foo.md	[foo](concepts/foo.md)
concepts/foo.md	entities/bar.md	[bar](../entities/bar.md)
projects/my-project/my-project.md	concepts/foo.md	[foo](../../concepts/foo.md)
projects/my-project/concepts/arch.md	entities/bar.md	[bar](../../../entities/bar.md)

在 Markdown 模式下，[[path\|display text]] 这种 Wiki 链接形式对应于 [display text](relative/path.md)。

范围： 此设置仅影响新写入或更新的链接。现有知识库内容绝不会自动迁移——想要转换旧链接的用户可以运行 cross-linker 或 wiki-lint 技能。

每个写入技能都会在生成链接前从配置中读取 OBSIDIAN_LINK_FORMAT，并应用正确的格式。

配置解析协议

所有技能都必须使用此算法解析配置——不要直接硬编码 .env 或全局配置路径。 这样可以确保单知识库、多知识库、项目本地和 VPS 设置都能正常工作。

全局配置目录

全局配置目录采用 XDG 风格：$XDG_CONFIG_HOME/obsidian-wiki（默认值为 ~/.config/obsidian-wiki）。已有 ~/.obsidian-wiki 目录的安装会继续使用该目录，因此现有设置不会失效；但任何新安装都将位于 XDG 路径下。使用以下方式解析：

obsidian_wiki_config_dir() {
  local xdg_dir="${XDG_CONFIG_HOME:-$HOME/.config}/obsidian-wiki"
  local legacy_dir="$HOME/.obsidian-wiki"
  if [[ -d "$legacy_dir" && ! -e "$xdg_dir" ]]; then
    echo "$legacy_dir"
  else
    echo "$xdg_dir"
  fi
}

下文中的“全局配置目录”均指 $(obsidian_wiki_config_dir)，“全局配置”均指 $(obsidian_wiki_config_dir)/config。

解析顺序

0. 内联知识库覆盖（@name） — 如果用户的请求中包含 @<name> 标记（例如 @work save this、query @personal about X），直接解析 <global config dir>/config.<name>，并使用其中的 OBSIDIAN_VAULT_PATH。这会覆盖 CWD 的 .env 向上查找和活动符号链接，且仅适用于本次调用——对于 @name 请求，绝不能运行 ln -sf 或以其他方式更改活动知识库。如果 <global config dir>/config.<name> 不存在，告知用户该配置不存在，并列出可用知识库（使用 wiki-switch 的 List 逻辑），然后停止——不要静默回退到默认配置。@name 是路由指令，不是内容：在将请求的其余部分作为实际指令或页面文本处理之前，先移除它。
1. 从 CWD 向上查找 — 在当前目录中查找 .env 文件，然后依次检查每个父目录，直到 $HOME。在第一个包含 OBSIDIAN_VAULT_PATH 的 .env 处停止。如果其值为空，也要在此停止：告知用户是哪个 .env 阻止了解析（从 .env.example 复制的空行会导致此情况），不要继续回退到全局配置。
2. 全局配置 — 如果未找到本地 .env，读取全局配置（$(obsidian_wiki_config_dir)/config）。
3. 提示设置 — 如果两者都不存在，告知用户：“未找到配置。运行 wiki-setup 来初始化你的知识库。”

@name 是单次调用覆盖项——它针对单个请求指定一个知识库。/wiki-switch <name> 是持久默认设置——它会为所有后续请求重新指向活动符号链接。使用 @name 可以从任意位置访问其他知识库，而不影响你的默认“brain”知识库。

find_config() {
  # $1 = parsed @name from the request, if any (else empty)
  local config_dir
  config_dir="$(obsidian_wiki_config_dir)"
  if [[ -n "$1" ]]; then
    [[ -f "$config_dir/config.$1" ]] && { echo "$config_dir/config.$1"; return; }
    echo ""; return   # named vault missing → caller reports + lists, no fallback
  fi
  dir="$PWD"
  while [[ "$dir" != "$HOME" && "$dir" != "/" ]]; do
    [[ -f "$dir/.env" ]] && grep -q "OBSIDIAN_VAULT_PATH" "$dir/.env" && { echo "$dir/.env"; return; }
    dir="$(dirname "$dir")"
  done
  [[ -f "$config_dir/config" ]] && { echo "$config_dir/config"; return; }
  echo ""
}

知识库范围内的状态

写入运行时状态的技能（例如 daily-update）必须将状态限定在已解析的知识库范围内，而不是使用全局路径。使用：

VAULT_ID=$(echo "$OBSIDIAN_VAULT_PATH" | md5sum 2>/dev/null || md5 -q - <<< "$OBSIDIAN_VAULT_PATH" | cut -c1-8)
STATE_DIR="$(obsidian_wiki_config_dir)/state/$VAULT_ID"

标准的“开始之前”区块

每个技能的设置部分都应写为：

解析配置 — 遵循 llm-wiki/SKILL.md 中的配置解析协议。首先遵循内联 @name 覆盖，然后从 CWD 向上查找 .env，再回退到全局配置，否则提示用户进行设置。这样即可获取 OBSIDIAN_VAULT_PATH 及任何工具专用路径覆盖项。

写作风格配置解析

在起草或改写自然语言 Markdown 之前，先使用上述 XDG/legacy 算法解析全局配置目录，然后在 <global config dir>/WRITING.md 存在时读取它。WRITING.md 不存在或内容为空，表示没有自定义写作偏好。如果读取这个可选文件失败，发出警告并继续遵循默认框架指导。

有效优先级为：框架不变量 > 当前任务/技能要求 > 当前项目 AGENTS.md > 知识库 AGENTS.md > 全局 WRITING.md。框架不变量包括 schema、来源信息和安全要求；针对特定操作的要求对当前任务仍具有权威性。未明确指定的项目和知识库规则继承自优先级较低的层级，同一主题中更具体的规则优先。

写作偏好仅适用于新起草或改写的自然语言字段和正文内容。这包括 YAML frontmatter 中的自然语言标题和摘要值，但偏好不得更改 YAML 语法、必需键、结构、类型或机器生成字段。JSON、结构化日志和透传内容保持不变，并保留其规定格式和源内容的忠实度。

环境变量

Wiki 通过环境变量进行配置（参见 .env.example）。唯一必需的变量是知识库路径，其余变量都有合理的默认值。

• OBSIDIAN_VAULT_PATH — Wiki 所在位置 （必需）
• OBSIDIAN_SOURCES_DIR — 原始源文档所在位置
• OBSIDIAN_CATEGORIES — 以逗号分隔的类别列表
• WIKI_SKIP_PROJECTS — 以逗号分隔的子字符串；名称包含其中任一子字符串的项目目录都会在历史记录导入中排除（扫描 + 增量 + 清单）。参见历史记录导入技能中的“项目范围限定”步骤。
• CLAUDE_HISTORY_PATH — Claude 对话数据所在位置
• CODEX_HISTORY_PATH — Codex 会话数据所在位置
• HERMES_HOME — Hermes Agent 数据所在位置
• OPENCLAW_HOME — OpenClaw 数据所在位置
• COPILOT_HISTORY_PATH — Copilot 会话数据所在位置
• OBSIDIAN_LINK_FORMAT — 内部链接语法：wikilink（默认）或 markdown
• WIKI_TOKEN_WARN_THRESHOLD — 当完整 Wiki 的令牌估算值超过此值时，在 wiki-status 中发出警告（默认值：100000）。设为 0 可禁用。令牌占用报告参见 wiki-status。
• WIKI_STAGED_WRITES — 设为 true 时，所有由 LLM 编写的页面都会放入 _staging/<category>/，供人工审核后再移入正式位置。详情参见 wiki-setup 和 wiki-stage-commit。
• CODE_UNDERSTANDING_BACKEND — wiki-update 在提炼内容前理解项目的方式：auto（有 CodeGraph 时使用，否则使用内置的 ast-extract + rg；默认）、builtin，或 codegraph（明确要求使用；不可用时发出警告或错误）。
• CODE_UNDERSTANDING_CODEGRAPH_BIN — 可选的 codegraph 二进制文件路径，在其不位于 PATH 中时使用。 两者的解析方式与 OBSIDIAN_VAULT_PATH 相同：优先使用真实环境变量（空值视为未设置），然后查找从项目目录向上最近的 .env，再查找全局配置（$(obsidian_wiki_config_dir)/config），最后使用默认值。
• OBSIDIAN_MAX_PAGES_PER_INGEST — 每次 wiki-ingest 运行时创建或更新页面数量的上限（默认值：15）。参见 wiki-ingest 第 4 步。
• LINT_SCHEDULE — daily-update 同时运行 wiki-lint 的频率：daily | weekly（默认）| manual。参见 daily-update 第 4a 步。

不需要 API 密钥 — 运行这些技能的 Agent 已内置 LLM 访问能力。

运行模式

Wiki 支持三种导入模式：

模式	适用情况	执行内容
追加	少量增量、渐进式更新	通过清单计算增量，仅导入新增或已修改的源文件
重建	出现重大偏差、需要重新开始	将当前 Wiki 归档到 _archives/，清空内容，然后重新处理所有源文件
恢复	需要回退	恢复之前的归档

使用 wiki-status 查看增量并获取建议。使用 wiki-rebuild 执行归档、重建或恢复操作。

参考

有关具体操作的详情，请参见配套技能：

• wiki-status — 审核已导入的内容、计算增量，并建议采用追加还是重建
• wiki-rebuild — 归档当前 Wiki、从头重建，或从归档恢复
• wiki-ingest — 将源文档及原始文本、聊天和日志数据提炼为 Wiki 页面
• claude-history-ingest — 导入 Claude 对话历史记录
• codex-history-ingest — 导入 Codex CLI 会话历史记录
• wiki-query — 基于 Wiki 回答问题
• wiki-lint — 审核并维护 Wiki 的健康状况
• wiki-setup — 初始化新的知识库