# 库结构约定

这个插件不猜你的笔记怎么组织，它按下面这套约定读。**你可以只满足第一层，其余全是加分项**——
越往上满足，检索越准。

> **这套约定的出处**：三层结构（不可变的原始资料 / LLM 维护的 wiki / 描述规矩的 schema 文件）与
> `index.md` 内容目录 + `log.md` 时间线的做法，来自 Andrej Karpathy 的
> [`llm-wiki.md`](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)。
> 那份 gist 讲的是模式与理由，本文档把它落成了**插件能读的具体字段与文件名**。

---

## 第 0 层：最小可用（只要这一条就能用）

> 一个目录，里面放着 `.md` 文件。

满足这条，`wiki_recall` 就能按「文件名 + 正文关键词」检索。别的什么都不需要。

插件会跳过：`.` 开头的目录（如 `.obsidian`、`.git`）、`_` 开头的目录、`index.md`、`log.md`。
单页超过 512 KB 只记元数据，不读正文（防止某个巨型资料页把上下文吃穿）。

---

## 第 1 层：frontmatter 字段（决定「搜得准不准」）

页面开头的 YAML 属性块，七个字段。**缺失不报错，只是那一路加分失效。**

```markdown
---
类型: 概念
状态: 演进中
标签: [AI, 上下文]
别名: [Context Engineering, 上下文工程学]
来源数量: 3
创建: 2026-10-01
更新: 2026-10-20
---
```

| 字段 | 取值 | 用途 | 缺失后果 |
| --- | --- | --- | --- |
| `类型` | 概念 / 实体 / 对比 / 综合 / 资料 | 类型筛选；同分时排序（综合 > 概念/实体/对比 > 资料） | 类型筛选失效，排序退化为默认档 |
| `状态` | 草稿 / 演进中 / 已提纯 | 状态筛选；「这页成熟到什么程度」 | 状态筛选失效 |
| `标签` | `[a, b]` 或 `[a，b]`（中英文逗号都认） | 标签筛选；命中 +25 分 | 标签通道失效 |
| `别名` | `[a, b]` | **别名命中 +50 分**——中英文/缩写/旧称都能搜到 | 只能靠页名和正文，缩写查不到 |
| `来源数量` | 数字 | **证据强度的唯一可靠代理**（库里没有「可信档」字段，按它推） | 不显示证据强度 |
| `创建` / `更新` | `YYYY-MM-DD` | 同分时新的排前面；显示新鲜度 | 排序退化为名字序 |

资料页（`类型: 资料`）额外建议三个字段：`标题`、`作者`、`来源`，以及可选的
`覆盖文件`（例：`原始资料-raw/某课程/（9 篇）`），用来做「哪些页来自同一批原料」的聚集。

> 别自己发明「可信档」这种字段——它不会被读。证据强度就用 `来源数量` + `状态` 两个字段推。

---

## 第 2 层：`index.md`（决定「一次调用能不能直接回答」）

人工提炼的一句话摘要。**它比正文片段值钱**，因为摘要本身就是「这页讲了什么」的答案。

```markdown
# 索引

**当前规模**：213 份资料 · 72 个页面 · 最后更新 2026-11-02

## 概念

- [[上下文工程]] — 不是写更好的提示词，而是决定每一步把什么放进模型的视野（3 份资料，更新于 2026-10-20）
- [[记忆系统]] — 把「这次说过的话」变成「下次还能拿出来用的东西」的那层机制（1 份资料，更新于 2026-10-12）
```

行格式：

```
- [[页名]] — 一句话摘要（N 份资料，更新于 YYYY-MM-DD）
```

括号里的元数据三种写法都认：`（2 份资料，2026-11-01）`、`（2 份，2026-11-01）`、
`（2 份资料，更新于 2026-11-01）`。没有括号也行，整行都当摘要。

`**当前规模**：…` 这行会被 `overview` 模式原样显示，写什么就是什么。

**注意**：摘要分只在「其它通道全为 0」时才给（8 分）——只补漏、不抢位。
否则摘要里提过某个词的资料页会顶掉真正相关的笔记页。

---

## 第 3 层：`log.md`（时间线）

只追加，不修改。每条一个二级标题：

```markdown
## [2026-10-15] ingest | 某课程第三讲（3 篇原始资料）
## [2026-10-20] query | 上下文预算怎么分配
## [2026-11-01] lint | 全库红链检查
```

类型（竖线前那一段）随便写，惯例是 `init` / `ingest` / `query` / `archive` / `lint` / `schema` / `fix`。
`overview` 模式会显示最近 5 条。

---

## 第 4 层：`总览-overview.md`（全库当前认知状态）

`overview` 模式会把这一页的正文整段返回。文件名认 `总览-overview.md` 或 `总览.md`。

建议写四块：这个库在讲什么 / 各页成熟度 / 未裁决的分歧 / 待补缺口。
它是「新会话开场先读什么」的答案——省掉模型自己拼全貌的成本。

---

## 双链与红链

正文里 `[[页名]]` 或 `[[页名|显示名]]` 会被解析：

- 指向存在的页（或存在页的别名）→ 正常关系
- 指向不存在的页 → **红链**，工具会在结果里标出来

红链不是错误，是信号：**「这里引用了一个库里没有的判断」**。模型看到红链就知道
这段话缺页级支撑，转述时该降级表述。`overview` 会汇总全库红链。

---

## 为什么这么设计

1. **原始资料与知识分离**：`原始资料-raw/` 只读，`知识层-wiki/` 由人（或 LLM）维护。
   压缩稿可以重写，原文不能动——否则「追源」就断了。
2. **索引由人写**：`index.md` 的一句话摘要必须是人（或至少是一次有判断的提炼）写的。
   自动生成的摘要没有判断，检索时反而制造噪音。
3. **只追加的日志**：`log.md` 记的是「什么时候发生了什么」，改它等于篡改历史。

---

## 五分鐘起步

```bash
mkdir my-wiki && cd my-wiki
mkdir 概念-concepts
cat > 概念-concepts/示例页.md <<'EOF'
---
类型: 概念
状态: 草稿
标签: [示例]
别名: []
来源数量: 1
创建: 2026-11-02
更新: 2026-11-02
---

# 示例页

## 它是什么

一句话说清这个概念。
EOF
```

然后在设置 →「知识库」里填这个目录，或者：

```bash
WIKI_ROOT="$PWD" node bin/cli.mjs search 概念
```

更完整的可跑样例见 `examples/sample-wiki/`（6 页，含 index、log、总览、红链、别名）。