course-factory

做课系统

一个用 llm-wiki 思路管理的课程开发知识库。 原料丢进来 → LLM 整理成结构化 md → 从库里取材做课。 库里所有东西都能追回原始文件，源文件删了会自动回滚。

---

它解决什么问题

你的痛点	这个系统的答案
资料散在微信、桌面、网盘，做课时找不到	唯一输入区 00-原材料/，全部分类归档
每次做课都要重新翻一遍全部资料	一次整理成 md 知识库，下次直接检索
不知道哪些资料已经整理过、哪些是新的	manifest.json 记指纹，kb.py scan 精确算出增量
整理过一次就过期了，没人知道	源自带 hash，源变了页面自动标 stale
删了源文件，知识库里留一堆僵尸内容	kb.py retract 三档回滚（归档/降级/级联）
新人接手，不知道从哪看起	三层索引：业务地图 → 目录索引 → 页面摘要
做出来的课是"AI 编的"，经不起追问	每个模块必须标素材出处，缺料就明说
课上被问"这个数据哪来的"答不上	每页标证据等级 A/B/C/D，做课按等级配比，B 级不许说成 A 级
知识库越写越像 AI 生成的垃圾	独立的内容检查器查 AI 腔、长句、没出处的数字

---

结构

做课系统/
├─ 00-原材料/          【唯一输入区】只进不改，不限文件类型
│   ├─ _inbox/         随手丢，同步时再分流
│   ├─ 01-行业资料/
│   ├─ 02-客户与需求/
│   ├─ 03-课程素材/
│   └─ 04-竞品与参考/
│
├─ 10-知识库/          【管理目录】全 md，LLM 维护，人可读
│   ├─ index.md        业务地图（路由入口）
│   ├─ _meta/          manifest / 关系图 / 日志 / 约定
│   ├─ _archive/       因源删除而归档的页（可回溯）
│   ├─ sources/        一源一页
│   ├─ topics/         多源合成的主题结论
│   ├─ entities/       人/机构/工具/政策/术语
│   └─ modules/        可进课表的课程模块
│
├─ 20-课程产出/        【交付区】按课程分目录
├─ 30-技能/            【方法区】8 个 skill
└─ 90-工具/kb.py       【引擎】管结构，不管语义

---

四条核心机制

1. 增量：靠指纹，不靠记忆

00-原材料/ 每个文件在 _meta/manifest.json 里有一条记录（size + mtime + sha256）。

scan → 分类
  NEW       manifest 没有，磁盘有     → 整理成页面
  CHANGED   hash 变了                  → 重读、更新页面
  DELETED   manifest 有，磁盘没了      → 回滚
  MOVED     hash 相同但路径变了        → 只改引用，不重做
  UNCHANGED 都没变                     → 跳过

大文件用 size + mtime 短路，不变就不重算 hash —— 200 页的库扫描一次 1 秒内。

为什么不能靠 LLM 记忆判断增量：上下文会丢、会话会断、多人协作时互相不知道。指纹存在磁盘上，谁来跑结果都一样。

2. 回滚：三种情形，三种处理

页面 frontmatter 里的 sources: 就是回滚依据。删一个源：

页面类型	判据	处理
独占页	sources 只有这一个	移入 _archive/，原位置删除（不物理销毁）
共享页	sources 有多个	移除该源，标 stale，进 rebuild_queue 等重合成
级联页	引用了被归档的页	标 stale，提示人工复核

为什么不直接删：一个 topic 页可能综合了 5 份资料。删其中 1 份就删整页，等于把另外 4 份的成果也扔了。

3. 索引：三层，越往下越贵

L1  index.md 业务地图      按业务问题分区（市场/客户/内容/交付）
L2  */_index.md 目录索引    自动生成，一行一页带摘要
L3  frontmatter.summary    写页时顺手写

查东西从上往下走，命中即停。不许一上来全文 grep。

4. 可信度：每页标证据等级

等级	什么内容	课上怎么讲
A	一手数据，口径明确可核对	直接讲，标出处
B	有报告支撑但口径不明/样本小	说「某机构测算」
C	从业者经验、行业共识	说「我们的经验是」，不当结论
D	推断、假设、未验证	不上课件

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

做课配比：讲授内容 A+B 不低于 60%。低于 40% 就得改定位，别包装成有数据支撑的课。

这条是"课经不经得起追问"的唯一量化保证。学员里总有一个人会问"这个 42% 哪来的"。

---

快速开始

第一次

cd 做课系统
python 90-工具/kb.py status        # 应该显示全 0

把第一批资料丢进 00-原材料/01-行业资料/，然后对 AI 说：

同步知识库

日常

丢文件 → 说"同步"     → 增量整理
删文件 → 说"同步"     → 自动回滚
找东西 → 说"查 XX"    → 路由检索
做课   → 说"做一门 XX 课" → 取材出大纲
体检   → 说"检查知识库"  → lint 修复

命令速查

python 90-工具/kb.py status              # 总览
python 90-工具/kb.py scan                # 差异
python 90-工具/kb.py scan --json         # 差异（给程序用）
python 90-工具/kb.py mark <源> --pages a.md,b.md   # 登记已整理
python 90-工具/kb.py retract <源>        # 回滚
python 90-工具/kb.py move <旧> <新>      # 登记移动
python 90-工具/kb.py graph               # 重建索引与关系图
python 90-工具/kb.py lint [--json]       # 结构检查（死链/孤儿/缺字段/等级虚高）
python 90-工具/check-content.py          # 内容检查（AI 腔/长句/没出处的数字）
python 90-工具/kb.py check               # 上面两个一起跑，提交前用

---

8 个技能

技能	管什么
course-factory	总入口：激活、诊断、分流、维护编排
kb-sync	增量同步编排（新增/变更/删除/移动）
kb-ingest	单源精读与原子化（一文件拆几页、怎么命名）
kb-query	五级检索路由
kb-lint	健康检查与分派修复
kb-index	索引与业务地图维护、合并/拆分
course-outline	需求澄清 → 取材 → 大纲 → 模块详案 → 缺口
course-slides	大纲 → 授课 PPT + 讲师备注

---

版本控制

仓库已经 git init 并完成首次提交。一次同步对应一个 commit，提交前跑 kb.py check。

python 90-工具/kb.py check      # 先过检查
git add -A
git commit -m "sync: 入库 3 份行业报告，派生 9 页"

三条要知道的：

1. 不要推到公开 GitHub。 库里有客户名称、报价、内部方法论。要协作用内网 GitLab 或私有仓库。
2. manifest.json 冲突不要手解，跑 git checkout --ours ... && python 90-工具/kb.py repair。
3. _index.md 冲突直接重生成，git checkout --theirs ... && python 90-工具/kb.py graph。

完整工作流（含提交信息规范、多人分工、冲突处理、用 git 撤销糟糕的同步）见 GIT.md。

---

四条不变的规定

1. 原材料只进不改。 要更新资料，放新版本进去，让系统识别为 NEW。
2. 写完必登记。 kb.py mark 漏一次，下次白干一遍。
3. 脚本管事实，LLM 管语义。 任何"哪些文件是新的""有几页"的判断，一律问脚本。
4. 每页必标证据等级，不许虚高。 补料时随手把 C 级标成 A 级，三个月后做课就会把它当事实讲给客户。这是这套系统里唯一无法靠工具完全兜住的地方——EVIDENCE_INFLATED 只能查"比来源高"，查不出"来源本身标错了"。

---

扩展

• 加新分类：在 00-原材料/ 下建目录即可，kb.py 自动纳入扫描。
• 加新技能：在 30-技能/ 下建目录写 SKILL.md，然后在 course-factory 的分流表里加一行。
• 改页面格式：改 10-知识库/_meta/约定.md，同时改 kb.py 里 dump_fm 的字段顺序，并在约定.md 文末「规则变更记录」登记日期和起因。
• 加检查规则：一个检查器只查一件事。结构问题进 kb.py lint，内容问题进 check-content.py，互不掺和。新规则先想清楚：误报率多高？高的就别进退出码，做成 --xxx 手动开关。误报多了大家就不看报告了，等于没有检查。
• 多人协作：git init 后，原材料目录天然适合并行（只增不删），知识库靠 kb-sync 收敛。冲突时以 manifest 为准。提交前跑 kb.py check。

两条给未来的自己的话

1. 每条规则都登记起因。 约定.md 文末的变更记录不是形式主义。没有起因的规则，三个月后会被当成官僚条款删掉，然后同一个坑再踩一次。
2. 检查器宁可漏，不可误报。 一份没人看的检查报告，比没有检查更糟——它给你一种"有人在管"的错觉。