# 知识库契约（宪法）

> 本文件定义本库所有 md 文件的格式约束。`kb.py` 与所有 skill 都以此为准。
> 改本文件 = 改法律：必须同步改 `90-工具/kb.py` 的 `dump_fm` 字段顺序，并在文末「规则变更记录」登记。

---

## 一、四类页面

| 类型 `type` | 目录 | 职责 | 一页装什么 |
|---|---|---|---|
| `source` | `sources/` | **来源页**：一个原材料文件对应一页 | 该文件讲了什么、关键事实、可引用原句、适用场景 |
| `topic` | `topics/` | **主题页**：多源合成的知识块 | 一个业务问题下的整合结论（市场规模、客户画像、方法论体系） |
| `entity` | `entities/` | **实体页**：人/机构/工具/政策/术语 | 该实体的定义、属性、与本业务的关系 |
| `module` | `modules/` | **课程模块**：可直接进课程的最小单元 | 目标、知识点、案例、时长、素材出处、练习 |

**判定规则**
- 有唯一物理源 → `source`
- 由 ≥2 个源综合得出 → `topic`
- 有专有名词、需要被反复引用 → `entity`
- 能直接搬进课表 → `module`

一个源文件通常派生 **1 个 source 页 + 若干个 topic/entity/module 页**。
纯废话的源文件可以只建 source 页，不强行派生。

---

## 二、frontmatter 字段

```yaml
---
id: "src_a1b2c3d4"        # 唯一 id，source=src_*，topic=tp_*，entity=en_*，module=md_*
type: "source"             # source | topic | entity | module   【必填】
title: "2026 AI 培训白皮书"  # 人类可读标题                                【必填】
summary: "一句话说明这页有什么用"  # ≤ 40 字，进索引            【必填】
evidence: "A"              # A|B|C|D 证据等级，见第三节          【必填】
tags:                      # 2–5 个，用于检索
  - "行业"
  - "市场"
sources:                   # 【关键】该页内容来自哪些原材料
  - "01-行业资料/2026-AI培训白皮书.pdf"
related:                   # 相关页面的 stem（不含 .md）
  - "提示词案例集"
status: "active"           # active | draft | archived
stale: false               # true = 上游变了，本页待重建
stale_reason: ""           # 为什么 stale
created: "2026-11-04"
updated: "2026-11-04"
---
```

### sources 字段是回滚机制的全部依据

- 值 = **原材料在 `00-原材料/` 下的相对路径**（POSIX 斜杠），不是 id、不是文件名。
- 必须精确，一字不差。`kb.py retract` 靠它定位要回滚的页面。
- 一个页面可以有多个源（共享页）；只有一个源的叫独占页。二者的删除行为不同。

---

## 三、证据分级（每页必标）

做课最大的风险不是没内容，是**把 C 级经验当成 A 级数据讲给客户听**。学员一追问就穿帮。

| 级别 | 定义 | 典型来源 | 讲课时的约束 |
|---|---|---|---|
| **A** | 可核验的一手数据，有明确口径和出处 | 国家统计局、上市公司财报、客户书面提供的真实数据、已发表的一手研究 | 可直接讲，页脚标出处 |
| **B** | 有研究或报告支撑，但样本小、口径不明、无法复现 | 咨询公司白皮书、行业调研、单一案例报告 | 必须说「某机构测算」，不能说「数据显示」 |
| **C** | 从业者经验、普遍共识，无直接证据 | 讲师判断、同行说法、行业习惯 | 必须说「经验上」，不能当结论用 |
| **D** | 推断、假设、未验证 | 「我推测客户会在意…」、模型生成的分析 | **不许进课件**，只能留在 module 的「待验证」区 |

### 木桶规则

**页面的 `evidence` = 该页所有内容里最弱的那一条。**

- `source` 页：按原文件本身的性质定级。
- `topic` 页：**不得高于**它所有 `sources` 对应 source 页的最低级。合成不会提高证据强度。
- `module` 页：不得高于它引用的素材最低级。
- `entity` 页：无权威来源时一律 `C`。

`kb.py lint` 会查 `EVIDENCE_INFLATED`（声明等级高于来源最低级），这是本库最容易被糊弄过去的一项。

### 做课的硬配比

- 讲授内容里 **A + B 不低于 60%**，否则整门课是"讲师个人经验分享"。
- **D 级一律不上课件。**
- 单个模块如果只有 C 级素材，必须在模块详案里写明「本模块以经验为主，建议补一份 A/B 级材料」，并进 `03-缺口与补料.md`。

---

## 四、溯源规则

正文中任何**具体数字、论断、引语**后面加脚注引用对应 source 页：

```md
2026 年企业 AI 培训市场规模达 380 亿元。[^白皮书]
```

- 脚注标签用 source 页的 stem，LLM 与人都能对上。
- 不确定的说法必须标注「（推测）」或「（待核实）」，不允许把推测写成事实。
- **带 `万 / 亿 / % / 倍 / 元 / 人` 的数字，前后 100 字内必须有出处**（脚注、双链、或 `来源：` 字样）。`check-content.py` 机器查这一条。

---

## 五、写作规则

1. **原子性** — 一页只讲一件事。想写第二件事就开新页。
2. **结论先行** — 每页开头 3 行内给出结论，细节在后。
3. **可独立阅读** — 打开这一个 md 就能看懂，不依赖上下文。
4. **链接用 `[[stem]]`** — 双链，不带 `.md`。指向不存在的页面会被 lint 报 DEAD_LINK。
5. **不写"本文介绍了…"** — 直接写内容。
6. **中文正文，英文专有名词保留原样**。
7. **长度** — source 页 200–800 字；topic 页 300–1500 字；module 页 200–600 字。低于 100 字判为 THIN。

### 反 AI 腔（`check-content.py` 机器查）

下面几种是 AI 写知识库时的固定病，见到就改：

| 病症 | 例子 | 改法 |
|---|---|---|
| **元叙述** | 「本页介绍了…」「这条主要讲…」「以上就是…」 | 删掉这一句，直接写内容 |
| **空转加强词** | 「值得注意的是」「本质上」「总而言之」「不难发现」 | 直接删，不损失信息 |
| **段尾升华** | 「让我们一起拥抱 AI 时代」「未来可期」 | 删 |
| **万能开头** | 「在当今快速发展的…背景下」「随着…的不断发展」 | 直接说事 |
| **要读者翻译的比喻** | 「这套组合拳」「打通最后一公里」「形成护城河」 | 换成具体动作 |
| **电报体** | 一句话一个句号，句句十来个字，读着像念提纲 | 有因果/转折的相邻短句用「因为/所以/但」连起来 |

**句子标准**：一句一件事，30 字上下，最长不超过 60 字。超过 60 字的句子 `check-content.py` 会列出来。

### 写给人看，不是写给模型看

读者是公司里要去做课的同事，不是 AI。所以：

- 专业名词当场用一句日常话解释，名词本身保留（「Agent 编排，也就是让几个 AI 分工干活」）。
- 不写只有同行看得懂的缩写。
- 每句话单独拿出来能读懂。需要回看上文才懂的句子，重写。

---

## 六、stale 的含义

页面被标 `stale: true` 表示**内容可能已过期，读之前先看 stale_reason**。

产生 stale 的三种情形：
| 情形 | 触发者 | 处理方式 |
|---|---|---|
| 源文件被删除，但页面还有其他源 | `kb.py retract` | 用剩余源重新合成，清掉 stale |
| 源文件内容变更 | `kb-sync` | 重读源，更新页面 |
| 引用的下游页面失效 | `kb.py retract` 级联 | 人工确认后决定改写还是解除引用 |

处理完必须清 `stale: false` 并删掉 `stale_reason`，否则下次 lint 还会报。

---

## 七、禁止事项

- ❌ 不在 `10-知识库/` 里放非 md 文件（图片一律引用原文路径）
- ❌ 不手动改 `_index.md`（`kb.py graph` 会覆盖）
- ❌ 不在 `00-原材料/` 里修改或删除已入库的文件而不跑 `kb-sync`（会让 manifest 与磁盘脱节）
- ❌ 不把 `sources:` 写成文件绝对路径或文件名
- ❌ 不建只有标题没有内容的空页
- ❌ 不给页面标高于其来源的 `evidence`
- ❌ 不让两种说法打架还并存 —— 发现冲突必须登记 `_meta/矛盾登记.md` 并裁决

---

## 八、可重建性分级（决定备份什么）

不是所有东西都值得备份，也不是所有东西丢了都能重来。分清这两件事，才知道该保护什么。

| 东西 | 丢了能重建吗 | 怎么重建 |
|---|---|---|
| `00-原材料/` | **不能** | 这是唯一真相源，没有替代品。靠 git 远端和备份 |
| `_meta/矛盾登记.md` | **不能** | 裁决理由是人的判断，无法还原 |
| `_meta/changelog.jsonl`、`CHANGELOG.md` | **不能** | 历史就是历史（但 git 历史里还有一份） |
| `10-知识库/*/` 页面内容 | 勉强能 | 重读源让 LLM 重写，但历次「沉淀」出来的结论会永久丢失 |
| `_meta/manifest.json` | 能 | `kb.py repair` 从磁盘 + 页面反推（不是 scan，scan 会丢派生关系） |
| `_meta/derivations.jsonl` | 能 | `kb.py graph` 从页面 frontmatter 重建 |
| `*/_index.md` | 能 | `kb.py graph` |
| `_meta/rebuild_queue.jsonl` | 能 | 从 `stale: true` 的页面重新推导 |

**一句话**：只要 `00-原材料/` 还在，知识库永远能重建，只是很贵（几十小时 LLM 工时）。原材料没了，整个系统归零。

**备份优先级**：原材料 > 矛盾登记 > changelog > 其余。前三个丢了不可逆，后面几个丢了只是费时间。

**git 是这一整套的第二层保险**：它把每次改动都留了副本，所以「归档」和「回滚」实际上都是可逆的。但 git 只保护被提交过的东西 —— 同步完不提交，等于白做。

---

## 九、规则变更记录

**每条新规则必须登记：什么时候加的、因为什么事加的、谁改的。**
没有起因的规则，三个月后就会被人当成官僚条款删掉，然后同一个坑再踩一次。

| 日期 | 改动 | 起因 |
|---|---|---|
| 2026-11-04 | 初版：四类页面 + frontmatter 契约 + 溯源 + stale | 做课系统搭建 |
| 2026-11-04 | 新增第三节「证据分级」A/B/C/D + 木桶规则 + 做课配比；`evidence` 列为必填字段 | 参照 HowToLiveBetter 的条目证据分级。原设计只有 `sources` 没有可信度，做课时无法判断哪句话能直接讲、哪句要加限定语 |
| 2026-11-04 | 新增第五节「反 AI 腔」与句子标准 | 同上，对应其 `check-plain.mjs`。知识库由 LLM 写，不设文风红线就会积累成"AI 生成的垃圾" |
| 2026-11-04 | 新增第四节「带单位的数字必须有出处」 | 做课翻车都翻在数字上。结构完整的页面里塞一个没有出处的 42%，比缺页更危险 |
| 2026-11-04 | 新增 `_meta/矛盾登记.md`；约定「两份资料说法不一致时不许静默采用新的」；新增第八节可重建性分级 | 参照 Karpathy llm-wiki 把「new data contradicts old claims」列为头号检查项。做课时最怕两份资料打架而无人知晓，引用哪份全凭运气 |
| 2026-11-04 | kb-query 增加「第 6 步 沉淀」；kb-sync 增加「5.6 回声检查」；kb.py 新增 `guide` 命令与人读 CHANGELOG.md | 同上。Karpathy 的核心洞察是 wiki 要「复利」：①答过的分析要归档回库，否则每次从零拼；②一个源平均触及 10–15 页，只建 1 页等于漏了回声检查。`guide` 对应 llmwiki 的自描述入口，省 AI 重建认知的 token |