做课系统
一个会自己保鲜的
课程知识库

维护知识库最烦的不是读和想，是记账 —— 更新交叉引用、保持摘要新鲜、标记新数据推翻了旧结论。 人在放弃，因为维护成本增长快于价值增长。而模型不会烦，也不会忘记改一处引用。 — Karpathy, llm-wiki（2026）· 本系统的方法论来源

所以这套系统的分工是：人负责选料、判断、提问；模型负责摘录、交叉引用、归档、记账。人不写页面，一页都不写。

层	目录	职责	谁写
原材料	00-原材料/	唯一输入区。不限文件类型。只增不改 —— 要更新就放新版本进去，让系统识别为新文件	人
知识库	10-知识库/	全 Markdown。四个子目录：sources / topics / entities / modules，外加索引与元数据	模型
契约	_meta/约定.md	页面格式、证据分级、溯源规则、写作红线。改它等于改法律，必须登记起因	人 + 模型共演化
产出	20-课程产出/	按课程分目录：需求确认 → 大纲 → 模块详案 → 课件 → 讲师手册	模型起草，人审

磁盘上真正有什么 结构

# 原材料目录，永不修改
00-原材料/
  _inbox/             随手丢，同步时再分流
  01-行业资料/  02-客户与需求/  03-课程素材/  04-竞品与参考/

# 知识库，模型全权维护
10-知识库/
  index.md            业务地图 —— 按业务问题分区，不是按文件
  _meta/
    manifest.json     每个源文件的 size + mtime + sha256 + 派生了哪些页
    derivations.jsonl 关系图：哪个源派生了哪页，哪页引用了哪页
    CHANGELOG.md      人读日志，统一前缀可 grep
    矛盾登记.md        两份资料打架时的裁决记录
    约定.md            宪法
  _archive/           因源删除而归档的页，可回溯
  sources/  topics/  entities/  modules/

关键约束：文件系统是唯一真相源。索引、关系图、业务地图全部可以从 Markdown 文件重新算出。这意味着即使元数据全丢了，只要有原材料和页面，库还能重建 —— 只是会丢掉历史。哪些丢了能重建、哪些不能，写在契约第八节。

3.1 增量靠指纹，不靠记忆 解决：重复劳动

每个源文件在 manifest.json 里有一条记录。扫描时按指纹算出五类差异，而不是问模型"哪些是新的"。

分类	判据	动作
NEW	manifest 无，磁盘有	整理成页面，登记派生关系
CHANGED	sha256 变了	重读、更新页面、刷新派生页
DELETED	manifest 有，磁盘没了	回滚（见 3.2）
MOVED	sha256 相同但路径变了	只改引用，不重做内容
UNCHANGED	size 与 mtime 都没变	跳过，连 hash 都不算

为什么不能让模型记：上下文会丢、会话会断、三个人同时用会互相不知道。指纹存在磁盘上，谁跑都是同一个结果。这是整套系统和"直接跟模型聊天"的分界线。

3.2 回滚分三档，而不是一刀切删 解决：误删连带毁掉成果

一个主题页可能综合了 5 份资料。删其中 1 份就把整页删掉，等于把另外 4 份的成果一起扔了。所以按依赖关系分三档：

情形	判据	处理
独占页	来源列表只有这一个	移入 _archive/，原位置删除。不物理销毁
共享页	来源有多个	摘掉该源 → 标 stale → 进重建队列，等用剩余源重合成
级联页	引用了被归档的页	标 stale，提示人工复核：改写引用还是删掉那句话

回滚的依据是页面 frontmatter 里的 sources: —— 填的是原材料相对路径，一字不差。这个字段写错一个字，回滚就找不到该删的页。所以它是契约里的头号硬约束。

3.3 索引三层，越往下越贵 解决：库大了查不动

层	文件	回答什么	成本
L1	index.md	我该从哪个方向找（按业务问题分区，不按文件）	读一屏
L2	*/_index.md	这个方向下有哪些页，每页一句话	自动生成
L3	页面 frontmatter	这页具体讲什么、什么等级、来自哪些源	读十行

检索遵守「命中即停」：L1 能定位就不翻 L2，L2 能定位就不全文 grep。300 份源、上千个页面时，这套索引仍然不需要向量数据库。

3.4 每页必标证据等级 解决：课上被问倒

做课最大的风险不是没内容，是把 C 级经验当成 A 级数据讲给客户听。学员里总有一个人会问"这个 42% 哪来的"。

木桶规则：页面的等级取它所有内容里最弱的那一条。topic 页不得高于它来源的最低级 —— 合成不会提高证据强度，只会稀释。

做课配比：讲授内容里 A+B 不低于 60%。低于 40% 就得改定位，别包装成"有数据支撑的课"。这条由 kb.py lint 监控（EVIDENCE_INFLATED），也是这套系统里唯一能自动拦住"吹牛"的地方。

维度	补料 · 往库里加	取材 · 从库里拿
典型说法	丢了资料、同步、删了源、整理	做一门课、查一下、出大纲、要课件
能否补充原文件没有的	不能。只允许搬，不允许造	能。可以组合、提炼、编排
出处要求	指回原文件的具体段落	每个数字标脚注或双链
缺东西时	标「待核实」，不许猜	明说「库里没有」，不许编
证据等级	按原文件性质如实定	不得高于所用素材的最低级
做完必须	登记派生关系（kb.py mark）	把缺口写进补料清单

补料在给库里攒信用，取材在花信用。
补料时随手编一句，三个月后做课就会把它当事实讲给客户。

这个划分来自另一类项目：一个由 AI 维护的公开知识库，用同一个文件名把"改内容"和"用内容回答"拆成两套规则，因为两者的容错空间完全相反。改内容时错一个字会污染整库，回答时保守一点最多是少说一句。

命令行 · 90-工具/kb.py

命令	做什么	谁用
guide	自描述入口：这是什么、铁律、当前状态、下一步。新会话第一件事	模型
status	一行看全库：源数、页数、待处理、陈旧页	人 + 模型
scan	五类差异，--json 给程序用	模型
mark	登记"这个源已整理成哪几页"	模型
retract	源删除后回滚：归档 / 降级 / 级联	模型
move	源移动：只改引用，不重做内容	模型
graph	重建关系图和四个目录索引	模型
lint	结构体检：死链、孤儿、缺字段、等级虚高	人 + 模型
check	结构 + 内容一起过（聚合器）	提交前

两个检查器，各查一件事

把它们分开不是洁癖。结构对了不等于内容能用，而一个查七件事的脚本，改其中一条规则时会牵连其他六条，最后没人敢动。

检查器	只管	典型问题
kb.py lint	结构：链接、字段、来源、等级一致性	死链、孤儿页、等级虚高、D 级进课件
check-content.py	内容：文风与出处	AI 腔、超 60 字长句、带单位的数字没出处

内容检查器有一条设计原则值得单独说：宁可漏，不可误报。词表只收确实反复出现过的毛病，因为一份没人看的检查报告比没有检查更糟 —— 它给你一种"有人在管"的错觉。

八个技能

技能	职责
course-factory	总入口：诊断、分流、维护编排
kb-sync	增量同步编排：五类差异逐个处理
kb-ingest	单源精读：一个文件该拆几页、怎么命名、定什么等级
kb-query	五级检索路由，外带"把好答案写回库"
kb-lint	体检与分派修复
kb-index	索引维护、合并拆页、业务地图重组
course-outline	澄清需求 → 取材 → 大纲 → 模块详案 → 缺口报告
course-slides	大纲 → 授课 PPT + 讲师备注

日常三个动作

• 有新材料 → 丢进去，说「同步」。不用说细节，模型自己扫描。
• 想问点什么 → 直接问。它会按索引路由，答完还会判断这个答案值不值得写回库。
• 删了源文件 → 也要说一声「同步」。这是最容易忘的一步，也是唯一会让库慢慢失真的地方。

维护节奏

频率	做什么
每次同步后	自动跑一次体检，只看有没有新增问题
每周	kb.py check 全量过一遍，清空重建队列
每月	抽 5 个主题页对比数字，看有没有互相打架；找同一件事拆成好几页的，合并
每季度	看业务地图是否还反映真实业务；删掉已经不做的方向

三句话记住这个系统

1. 原材料只进不改。
2. 写完必登记，否则下次白干一遍。
3. 任何"有几个文件是新的""库里有多少页"的判断，问脚本，别问记忆。

它真正保证的只有一件事：库里的每个数字都能追到某个原文件的某一段，追不到的地方会被标出来。这在课程开发这个场景里，比多整理出二十个页面值钱得多。

共同的洞察只有一句：知识库烂掉的原因从来不是内容不够，是没人做记账。交叉引用要更新、摘要要保鲜、新数据推翻了旧结论要标出来 —— 这些事人做不完也做不久。把记账交给机器，把判断留给人，这套东西才转得起来。