chore: 接入 git 版本控制，新增 kb.py repair

- GIT.md：提交信息规范、多人分工、三个冲突高发点的处理办法
- kb.py repair：manifest 冲突或丢失时从磁盘+页面反推重建（sha256 与派生关系都能恢复）
- .gitignore 明确标注"刻意不忽略"的项（manifest / 原材料必须进版本控制）
- .gitattributes：changelog.jsonl 用 union merge，二进制不做换行转换
- AGENTS.md / README / 约定.md / 设计说明 四处同步

10-知识库/_meta/约定.md

@@ -169,11 +169,11 @@ updated: "2026-11-04"
 
 | 东西 | 丢了能重建吗 | 怎么重建 |
 |---|---|---|
-| `00-原材料/` | **不能** | 这是唯一真相源，没有替代品 |
+| `00-原材料/` | **不能** | 这是唯一真相源，没有替代品。靠 git 远端和备份 |
 | `_meta/矛盾登记.md` | **不能** | 裁决理由是人的判断，无法还原 |
-| `_meta/changelog.jsonl`、`CHANGELOG.md` | **不能** | 历史就是历史 |
+| `_meta/changelog.jsonl`、`CHANGELOG.md` | **不能** | 历史就是历史（但 git 历史里还有一份） |
 | `10-知识库/*/` 页面内容 | 勉强能 | 重读源让 LLM 重写，但历次「沉淀」出来的结论会永久丢失 |
-| `_meta/manifest.json` | 能 | `kb.py scan` 重算指纹，但「已整理」状态丢失，会当新文件重做一遍 |
+| `_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` 的页面重新推导 |
@@ -182,6 +182,8 @@ updated: "2026-11-04"
 
 **备份优先级**：原材料 > 矛盾登记 > changelog > 其余。前三个丢了不可逆，后面几个丢了只是费时间。
 
+**git 是这一整套的第二层保险**：它把每次改动都留了副本，所以「归档」和「回滚」实际上都是可逆的。但 git 只保护被提交过的东西 —— 同步完不提交，等于白做。
+
 ---
 
 ## 九、规则变更记录

90-工具/kb.py

@@ -683,6 +683,8 @@ def cmd_guide(args):
   要做一门课                  → 30-技能/course-outline → course-slides
   库看着有点乱                → kb.py check           （结构 + 内容一起过）
   改页面格式或加规则          → 10-知识库/_meta/约定.md（改完登记起因）
+  改完要留档                  → GIT.md                （一次同步一个 commit）
+  manifest 被 git 搞冲突了    → kb.py repair          （从磁盘和页面反推）
 
 【格式硬约束】（细节见 约定.md）
   每页 frontmatter 必填：type / title / summary / evidence / sources

AGENTS.md

@@ -22,4 +22,6 @@
 python 90-工具/kb.py status
 ```
 
+**改完记得提交。** 一次同步对应一个 commit，规则与冲突处理见 [`GIT.md`](GIT.md)。不提交的话，下次出错你没法回退到"昨天那个还能用的版本"。
+
 这个文件叫 AGENTS.md 只是因为各家 AI 工具默认读这个名字，内容与工具无关。

GIT.md

@@ -0,0 +1,209 @@
+# Git 工作流
+
+> 这个仓库已经 `git init`，首次提交完成。下面是怎么用，以及为什么这么用。
+
+---
+
+## 为什么这个仓库特别适合 git
+
+不是所有项目都值得上 git。这个仓库有三条天然契合：
+
+| 特性 | 带来的好处 |
+|---|---|
+| **原材料只增不改** | 加文件几乎永远不冲突。这是最关键的——协作时最怕两个人改同一个文件 |
+| **全是 Markdown** | diff 读得懂。改了什么、删了什么，一眼看出来，不用看二进制 |
+| **索引是派生的** | `_index.md`、`derivations.jsonl` 冲突了直接重生成，不用手工合并 |
+
+还有一条隐藏价值：**知识库的 git 历史 = 课程内容的演进史**。半年后你想知道「客户画像这一页是怎么长成现在这样的」，`git log -p` 能看到它被五份资料逐步充实的过程。这比任何笔记都可靠。
+
+---
+
+## 一次性设置（已配好，换机器要重做）
+
+```bash
+git config core.quotepath false     # 中文文件名正常显示，不显示成八进制
+git config user.name  "你的名字"
+git config user.email "你的邮箱"
+```
+
+`core.quotepath false` 这条别漏。不配的话 `git status` 里全是 `\346\212\200\350\203\275` 这种，没法看。
+
+---
+
+## 日常：一次同步，一个提交
+
+```
+丢资料 → 说「同步」→ 跑 kb.py check → git add -A → git commit
+```
+
+**提交前必须跑一次检查**，别把死链和没出处的数字提交进去：
+
+```bash
+python 90-工具/kb.py check
+```
+
+### 提交信息规范
+
+统一前缀加一句话，方便日后 `git log --oneline` 扫读：
+
+| 前缀 | 什么时候用 | 例子 |
+|---|---|---|
+| `sync:` | 增量同步完成 | `sync: 入库 3 份行业报告，派生 9 页` |
+| `retract:` | 源删除后的回滚 | `retract: 删除 2024 旧版大纲，归档 4 页` |
+| `course:` | 课程产出 | `course: 银行 3 天课大纲初稿` |
+| `fix:` | 修复体检问题 | `fix: 清理 12 处死链与 3 个孤儿页` |
+| `rule:` | 改契约或技能 | `rule: 新增证据分级 A/B/C/D` |
+| `chore:` | 工具改动 | `chore: kb.py 增加 repair 命令` |
+
+不要写 "update"、"修改"、"提交一下"。三个月后自己看不懂。
+
+---
+
+## 多人协作：谁改什么
+
+冲突的根源是两个人改同一个文件。按下面的分工，冲突面能压到接近零。
+
+| 角色 | 主要改 | 基本不碰 |
+|---|---|---|
+| 资料策展人 | `00-原材料/` 加文件 | 知识库页面 |
+| 做课的人 | `20-课程产出/`、`10-知识库/modules/` | 别人的 topic 页 |
+| 库维护者 | `10-知识库/topics/`、`entities/`、`_meta/` | 产出目录 |
+
+### 三个冲突高发点
+
+| 文件 | 冲突概率 | 原因 |
+|---|---|---|
+| `_meta/manifest.json` | **极高** | 单一文件，谁同步都会改 |
+| `topics/*.md` | 中 | 两个人可能同时往同一主题页补料 |
+| `*/_index.md` | 中 | 每次 `graph` 都重写 |
+
+---
+
+## 冲突怎么解
+
+### 情况一：`manifest.json` 冲突
+
+**不要手动合并 JSON。** 它本质是磁盘状态的缓存，直接从磁盘重建就行：
+
+```bash
+git checkout --ours 10-知识库/_meta/manifest.json
+python 90-工具/kb.py repair
+```
+
+`repair` 会扫磁盘算指纹、扫页面反推派生关系，把 manifest 重新建出来。恢复不了的只有「整理时间」和「已删除源的记录」，不影响使用。
+
+### 情况二：页面冲突
+
+正常解，但注意 **`sources:` 列表要取并集**，不是二选一。少一个源，将来删那个源时这页就回滚不掉。
+
+```yaml
+sources:
+  - "01-行业资料/报告A.pdf"     # 对方加的
+  - "02-客户与需求/访谈.md"      # 你加的
+```
+
+### 情况三：`_index.md` 冲突
+
+**别解，直接重生成：**
+
+```bash
+git checkout --theirs 10-知识库/topics/_index.md
+python 90-工具/kb.py graph
+```
+
+它是 `kb.py graph` 的产物，手工合并没有任何意义。
+
+---
+
+## 用 git 做四件具体的事
+
+### 1. 撤销一次糟糕的同步
+
+同步完发现喂了错误的资料，整批派生页都脏了：
+
+```bash
+git reset --hard HEAD~1     # 回到上一个提交（会丢未提交的改动，先确认）
+```
+
+比手动删页面安全得多。
+
+### 2. 看某一页是怎么长出来的
+
+```bash
+git log -p -- 10-知识库/topics/客户画像.md
+```
+
+能看到它第一次只是一句话，后来被几份资料逐步补成现在的样子，每次补料是谁、按什么依据。**这是这个仓库最值钱的用法之一。**
+
+### 3. 找回被误删的页
+
+```bash
+git log --diff-filter=D --name-only -- 10-知识库/
+```
+
+列出所有被删过的文件，配合 `git checkout <commit>^ -- <路径>` 恢复。
+
+### 4. 对比两周前的库
+
+```bash
+git diff HEAD~20 --stat
+```
+
+一眼看出这两周库长大了多少、哪些方向在长、哪些页一直没动过。
+
+---
+
+## 要不要推到远端
+
+**不要推到公开 GitHub。** 这个库里有客户名称、报价、内部方法论，属于公司资产。
+
+需要多人协作时的选项：
+
+| 方案 | 适合 |
+|---|---|
+| 公司内网 GitLab / Gitee 私有仓库 | 正式团队协作 |
+| 局域网共享盘 + 各自本地仓库 | 三两个人，临时 |
+| 一人维护，其他人只读 | 最常见，用 `git pull` 拿最新 |
+
+远端地址配好后：
+
+```bash
+git remote add origin <地址>
+git push -u origin main
+```
+
+---
+
+## 大文件
+
+`00-原材料/` 里如果有超过 50MB 的 PDF 或视频，建议用 git-lfs，否则仓库会很快膨胀到几个 GB：
+
+```bash
+git lfs install
+git lfs track "00-原材料/**/*.pdf"
+git lfs track "00-原材料/**/*.mp4"
+git add .gitattributes
+```
+
+**已经提交过的大文件不能再靠 lfs 瘦身**，需要用 `git filter-repo` 重写历史。所以最好现在就决定。
+
+---
+
+## 和 kb.py 的分工
+
+别把两件事搞混：
+
+| | 管什么 |
+|---|---|
+| **git** | 文件的历史版本：谁在什么时候改了什么 |
+| **kb.py** | 当前状态的一致性：哪些源整理过、哪些页该删、索引对不对 |
+
+`git` 回答「上周这页写的什么」，`kb.py` 回答「现在库里有没有过期内容」。两个都要，互相替代不了。
+
+---
+
+## 一条最小纪律
+
+> **每次说「同步」结束后，立刻提交一次。**
+
+不要攒着。攒了三天的改动一起提交，出问题时你分不清是哪一批资料搞坏的。

README.md

@@ -162,6 +162,26 @@ python 90-工具/kb.py check               # 上面两个一起跑，提交前
 
 ---
 
+## 版本控制
+
+仓库已经 `git init` 并完成首次提交。**一次同步对应一个 commit**，提交前跑 `kb.py check`。
+
+```bash
+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`](GIT.md)。
+
+---
+
 ## 四条不变的规定
 
 1. **原材料只进不改。** 要更新资料，放新版本进去，让系统识别为 NEW。

设计说明.html

@@ -520,6 +520,7 @@ footer b{color:var(--ink);font-weight:700}
       <tr><td><code>graph</code></td><td>重建关系图和四个目录索引</td><td>模型</td></tr>
       <tr><td><code>lint</code></td><td>结构体检：死链、孤儿、缺字段、等级虚高</td><td>人 + 模型</td></tr>
       <tr><td><code>check</code></td><td>结构 + 内容一起过（聚合器）</td><td>提交前</td></tr>
+      <tr><td><code>repair</code></td><td>从磁盘和页面反推 manifest，用于 git 冲突后或换机器接手</td><td>救急</td></tr>
     </table>
 
     <h3>两个检查器，各查一件事</h3>