知识库契约（宪法）

本文件定义本库所有 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 字段

---
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 页：

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

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

五、写作规则

原子性 — 一页只讲一件事。想写第二件事就开新页。
结论先行 — 每页开头 3 行内给出结论，细节在后。
可独立阅读 — 打开这一个 md 就能看懂，不依赖上下文。
链接用 [[stem]] — 双链，不带 .md。指向不存在的页面会被 lint 报 DEAD_LINK。
不写"本文介绍了…" — 直接写内容。
中文正文，英文专有名词保留原样。
长度 — 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

约定.md 11 KB 히스토리 Raw