# 做课系统

> 一个用 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% 哪来的"。

---

## 快速开始

### 第一次

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

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

> 同步知识库

### 日常

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

### 命令速查

```bash
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 + 讲师备注 |

---

## 四条不变的规定

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. **检查器宁可漏，不可误报。** 一份没人看的检查报告，比没有检查更糟——它给你一种"有人在管"的错觉。