# Material To Knowledge Base

> 当用户提供一个资料包/文件夹路径，希望把其中的 PDF、Word、Markdown 等资料阅读分析后，按"先总后细"的知识谱系 整理成 Obsidian 知识库（含知识谱系图、复习闭环、知识关联、增量日志与写后回读校验）时使用。 典型触发语：'帮我整理这个文件夹里的资料'、'把这些 PDF/Word 整理成知识库'、'分析这个资料包并建学习笔记'、 '把 D:\\xxx 整理成 Obsidian 笔记'。 工作流：确认资料路径 → 查已有库/资料指纹去重 → 扫描预检 → 逐份提取文本（含 OCR 管线）→ LLM 识别主题、 多级分类与知识谱系树（先总后细）→ 按谱系树建目录并生成 _知识谱系.md 与各 _总览.md → 生成结构化笔记 （来源/前置知识/关联知识点/自我检测/复习排期）→ 生成 _MOC 与 _复习清单 → 写后回读校验 → 汇报。 每个主题为独立 vault（E:\obsidian\rein\<主题>\），不统一路径；只读资料包，不修改原文件。

- Skill: `reinforce52/material-to-knowledge-base` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add reinforce52/material-to-knowledge-base`
- Raw SKILL.md: https://api.skillmd.com/api/skills/reinforce52/material-to-knowledge-base/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: reinforce52 (https://skillmd.com/u/reinforce52)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/reinforce52/material-to-knowledge-base

---


# 资料包知识库构建器（Material to Knowledge Base）

把用户提供的资料包（PDF / Word / Markdown 混合文件夹）阅读分析后，自动识别主题、按知识点层次分类，在 `E:\obsidian\rein\` 下生成一套**分层学习知识库 + 复习闭环 + 知识关联图**（**每个主题 = 独立 vault**）。

## 触发条件（When to use）

用户同时满足以下两点时启用本 Skill：

1. **提供了资料包路径**（文件夹路径，或多个文件路径）
2. **表达了整理/建库意图**，例如：
   - "帮我整理这个文件夹里的资料"、"把这些资料整理成知识库"
   - "分析这个资料包"、"把这些 PDF/Word 整理成学习笔记"
   - "把 D:\\xxx 整理成 Obsidian 笔记"、"读取这个文件夹并建库"

注意：路径由用户每次提供，不预设固定路径。主题和分类方式由 LLM 根据资料内容自动分析，不预设学科。

## 核心原则

1. **文件直写**：Vault 是纯 Markdown 文件夹，直接用文件工具操作 `E:\obsidian\rein\`，不依赖 Obsidian App。
2. **主题自动识别**：LLM 阅读资料后自动判断主题（如"六级英语"、"结构力学"、"机器学习"），用主题名建总目录。
3. **分类自动设计（多级）**：根据资料内容自动设计知识点层次：大类 → 子类 → 知识点，不预设固定分类。
4. **来源可追溯**：每篇笔记必须标注来源资料（文件名，尽量精确到章节/页码），方便回查。
5. **只读资料包**：只读取用户资料包，不修改、不移动、不删除原文件。
6. **增量生长**：同一主题后续追加资料时，在已有目录下补充笔记，不重写已有内容。
7. **复习闭环**：每篇笔记带 `review_status` + `next_review`，并生成 `_复习清单.md`，按间隔重复（1/3/7/15 天）驱动复习（规则见 `references/spaced-repetition.md`）。
8. **知识关联**：每篇笔记标注 `前置知识` 与 `关联知识点`，`_MOC` 用 Mermaid 画知识关系图，形成可导航的知识网络。
9. **谱系化（先总后细）**：建库 = 先产出全库**知识谱系树**（主题 → 大类 → 子类 → 知识点），生成 `_知识谱系.md`（Mermaid mindmap 全库总图）与每个大类的 `_总览.md`（子谱系 + 索引），知识点笔记为最细层。形成"**一图览全貌 → 每类一索引 → 每点一笔记**"的三层总-细结构。
10. **多来源合并去重**：多份资料讲同一知识点时，合并到一篇笔记并标注多来源，不重复建笔记。
11. **先查已有库 + 资料指纹去重（P0）**：建库前先扫描 `E:\obsidian\rein\` 是否已有同主题目录；识别资料包唯一性（路径 + 文件名 + 大小/指纹），避免同一资料重复建库。
12. **_log.md 增量日志（P1）**：每主题库维护 append-only `_log.md`，记录建库/新增/更新的日期与条目，最新在上；只追加不覆盖。
13. **写后回读校验（P1）**：每批写入后回读抽查：文件存在、frontmatter 闭合、Mermaid/wikilink 语法正确、来源字段完整、无乱码。

## 工作流（执行步骤）

### 第 0 步：澄清整理意图（Clarification Gate，P0）
- 收到资料包路径后，**先检测关键信息是否充分**，不足则停下反问，不猜、不直接开始解析建库。
- 只问影响执行的高价值问题（最多 1-3 个），用白话，每个问题附"为什么问"。
- 常问三件套（按需取舍）：
  1. 这批资料的用途？（A 备考 / B 系统学习 / C 工作参考 / D 纯整理归档）
  2. 期望深度？（A 总览索引 / B 到知识点笔记 / C 含复习闭环+自我检测）
  3. `E:\obsidian\rein` 下是否已建过同类库？（增量补充 or 新建）
- 用户回答后，整理成 2-3 句"整理意图快照"复述确认；用户确认后才进入第 1 步扫描。
- 若用户信息已明确（用途、深度、是否增量都清楚），跳过反问直接执行。
- 安全边界：不把模糊想法当建库授权；不替用户脑补主题、分类或深度。

### 第 1 步：确认资料包路径、查重、预检并扫描
- 从用户消息中提取资料包路径（文件夹或文件列表）。
- **查已有库**：扫描 `E:\obsidian\rein\` 根目录，若已存在同主题目录：
  - 提示用户"已存在 `<主题>` 库"，确认是**增量补充**还是**另建**（默认增量）。
- **指纹去重**：记录本次资料包的关键文件（名 + 大小），与已有库 `99-原始资料索引\资料清单.md` 比对，重复文件标注"已处理"，避免重复解析。
- **预检**：扫描该路径，按类型分组并统计：
  - PDF（`.pdf`）、Word（`.doc` / `.docx`）、Markdown（`.md`）、TXT（`.txt`）
  - 图片/其它（`.png` `.jpg` 等，标注"待 OCR"）
  - 记录每份文件的**大小**，识别超大文件（>50MB 需分段）。
  - 根据文件名/命名规律做**角色预判**（如 `讲义`、`真题`、`词汇表`、`练习`、`课件`），写入预检清单，供第 3 步参考。
- 向用户确认文件清单（数量、总大小、角色分布）。文件过多（>30 个或 >200MB）时建议分批处理：先做骨架（知识谱系 + MOC + 目录 + 资料索引），再按批填充知识点。

### 第 2 步：逐份提取文本
- **PDF / Word**：使用 `document-extract` 工具提取文本（该插件已启用，支持 PDF 和 docx）。
- **Markdown / TXT**：直接用文件读取工具读取全文。
- **扫描版 PDF / 图片（P1·OCR 管线）**：文本层为 0 时，走本 skill 自带 OCR 脚本（`scripts/` 目录，运行时 = 用户系统 Python，依赖 pymupdf/pypdf）：
  1. 探测文本层：`python scripts/probe_pdf.py <pdf>` → 判定是否扫描版。
  2. 渲染页面：`python scripts/render_pdf.py <pdf> <临时目录> --pages <页码,如 0,20,40>` → 输出 PNG。
  3. Windows 自带 OCR（zh-Hans-CN）：`powershell -ExecutionPolicy Bypass -File scripts/ocr_windows.ps1 -ImagePath <png>` → 输出识别文本。
  - OCR 产物先存临时文本，再进第 3 步分析；识别质量差的段落标注"OCR 待校对"。
  - 解析类内容（如答案在公众号/附录）标注"初稿仅供参考"，不编造。
- 提取失败的文件：记录文件名和失败原因，标注"待处理"，不中断整体流程。
- 大文件（>50MB 或超长文本）：分段提取或先取摘要，避免上下文溢出。
- 提取时尽量记录**章节标题与页码**（如可分页），供笔记 source 引用。

### 第 3 步：LLM 分析主题、多级分类与关联
- **自适应接入（personal-twin，P2）**：分类设计前先读取用户画像参数（见
  `personal-twin/references/adaptation-guide.md` 的读取命令）：
  资料主题命中已评级领域时，笔记讲解深度按 `adaptation.<领域>.depth`（≤2 级重概念+复习闭环，
  =3 级重应用/练习）；`example_kind` 决定例子类型；涉及该用户硬约束（如"不走现场"）的岗位/职业内容必须遵守；
  用户该领域 level≤2 时，笔记不得写成"已掌握"。读不到画像按默认执行，不阻塞。
汇总所有资料的文本内容（或摘要），LLM 分析并产出**建库蓝图**：

1. **主题识别**：这批资料的核心主题是什么？（用简洁中文/英文主题词）
2. **多级分类设计**：按知识点从浅入深设计 3-5 个大类，每类下再细分 **2-4 个子类**（资料简单时可扁平，只到子类一层）。同时在分类设计时产出**知识谱系树**（缩进树形：主题 → 大类 → 子类 → 知识点），它是后续目录、`_知识谱系.md`、各 `_总览.md` 与笔记的统一骨架。
3. **知识点映射**：每份资料的核心知识点对应到哪个分类/子分类下的哪篇笔记。
4. **知识点关联识别**：找出知识点之间的**前置/依赖关系**（A 是 B 的前提）与**并列关联**（A 与 B 相关），供笔记 `前置知识`/`关联知识点` 字段与 `_MOC` 关系图使用。
5. **重复知识点合并**：识别多份资料覆盖的同一知识点，规划合并到一篇笔记。
6. **知识谱系树产出**：把主题/分类/子类/知识点组织成一棵缩进树形谱系（**先总后细**），供第 4 步建目录、生成 `_知识谱系.md` 与各 `_总览.md`。

向用户简要汇报识别出的主题、多级分类方案和预计笔记数（1-2 句话 + 结构草图），如无异议则继续。

### 第 4 步：按谱系树创建目录并生成"总"层产物（先总）
在 `E:\obsidian\rein\<主题>\` 下按第 3 步的谱系树创建多级目录，并同步生成"总"层文件（数字前缀保证排序）：

```
E:\obsidian\rein\<主题>\
├── _知识谱系.md             # 全库总谱系图（Mermaid mindmap，先总：一图览全貌）
├── _MOC.md                  # 总索引 + 知识关系图 + 学习路线（必建）
├── _复习清单.md             # 间隔重复复习清单（必建）
├── _log.md                  # 增量日志（append-only，必建，P1）
├── 01-<分类A>\
│   ├── _总览.md             # 该大类子谱系（Mermaid mindmap）+ 知识点索引 + 学习顺序（先总）
│   ├── 01-<子分类A1>\
│   │   ├── <知识点1>.md     # 详细知识点（最细）
│   │   └── <知识点2>.md
│   └── 02-<子分类A2>\
│       └── ...
├── 02-<分类B>\
│   ├── _总览.md
│   └── ...
└── 99-原始资料索引\           # 资料包文件清单与提取状态
    └── 资料清单.md
```

**生成 `_知识谱系.md`（全库总谱系，先总）**：把谱系树转成 Mermaid mindmap（Obsidian 原生渲染、零插件）；总谱系画到"子类/知识点"层即可，知识点特别多时可只到"子类"层避免图过密；细到每个知识点放在该大类 `_总览.md`。

**生成每个大类的 `_总览.md`（分类层先总）**：该大类子谱系（Mermaid mindmap 或树形列表，细化到知识点）+ 全部知识点笔记 `[[]]` 索引 + 推荐学习顺序。

**生成 `_log.md`**：记录建库日期、谱系规模、处理资料数、待处理项（格式见 `references/templates.md`）。

- 分类/子分类/知识点三级：子分类目录按需创建，知识点少时可只建分类一层。
- 每个知识点**独立一篇笔记**（路径定位到最终子分类目录）。
- 如该主题目录已存在，复用已有目录结构，只追加新分类或新笔记。

### 第 5 步：撰写笔记（统一模板，含复习与关联）
- 每篇笔记模板见 `references/templates.md`（先读取，按其结构撰写）。
- 每篇笔记聚焦一个知识点，内容来自资料原文的提炼，不编造资料中没有的信息。
- `source` 字段标注该知识点来自哪些资料文件（尽量带章节/页码）；多份资料合并时全部列出。
- 资料中的公式、图表描述、关键定义尽量保留。
- `自我检测` 写 2-3 条考点式问答（后续可转成闪卡复习）。
- `review_status` 初始为 `new`，`next_review` 初始为 `created + 1 天`（间隔规则见 `references/spaced-repetition.md`）。

### 第 6 步：生成 _MOC.md 与 _复习清单.md
**\_MOC.md 内容：**
- 主题一句话介绍
- 资料包概况（共多少份资料、哪些格式、覆盖范围、处理状态）
- **知识关系图**（Mermaid，Obsidian 原生渲染；用知识点节点 + 前置/关联连线，体现学习路径）
- 学习路线（推荐阅读顺序，按前置依赖排）
- 按目录列出所有笔记，用 `[[]]` 双向链接
- 待处理清单（提取失败的文件、需要 OCR 的图片、待补充的知识点）

**\_复习清单.md 内容：**
- 复习规则说明（间隔：new→1天 / learning→3天 / review→7天 / mastered→15天，见 `references/spaced-repetition.md`）
- 按 `next_review` 日期排序的待复习清单，每条含：知识点标题、当前状态、下次复习日期、双链
- 复习操作指引：学完点开笔记 → 过"自我检测"→ 更新 `review_status` 与 `next_review`

### 第 7 步：写后回读校验（P1）
- 每批写入后，回读抽查：文件存在、frontmatter 闭合、Mermaid/wikilink 语法正确、`source` 字段完整、中文无乱码、`[[]]` 目标存在。
- 发现问题就地修复，修复后重读确认。

### 第 8 步：向用户汇报
- 给出知识库路径、全库谱系图（`_知识谱系.md`）与目录结构（多级）
- 说明识别出的主题、多级分类和知识关联图概要
- 列出成功处理的资料数 + 待处理的资料
- 给出推荐学习顺序与复习节奏（何时复习第一批）
- 提示：后续追加资料、深入某个知识点、更新复习状态，直接说

## 红线（必须遵守）

1. 只允许在 `E:\obsidian\rein\` 下创建/修改笔记；禁止触碰其他磁盘目录。
2. 每个主题 = 独立 vault：`E:\obsidian\rein\<主题>\`，不写入、不引用 rein 四大库，不混用路径。
3. **只读用户资料包**：不修改、不移动、不删除、不重命名原文件。
4. 写笔记前检查目标是否存在：已存在则 append 或新建带后缀的笔记，禁止覆盖已有笔记。
5. 所有内容必须来自资料原文提取；资料中没有的信息标注"待补充"，不编造。
6. 不删除任何已有笔记。
7. 文件操作优先用创建/追加接口；涉及大量文件时先列出计划再执行。
8. 处理用户资料时注意隐私：不将资料内容输出到无关渠道，只用于生成笔记。
9. `review_status` / `next_review` 只能由用户反馈或复习动作更新，不随意改写。
10. 多份资料同一知识点必须合并去重，不得因"每份资料一篇"产生重复笔记。
11. `_log.md` 只追加、不覆盖；历史条目保留。

## Git 版本管理（P2，可选）

- 建库/增量追加资料后，可对 vault 目录执行本地版本管理：`git init`（仅首次）+ 写入 `.gitignore`（排除 `.obsidian/workspace*`、`.trash/`、系统文件）+ `git add -A` + `git commit -m "<YYYY-MM-DD> 建库/更新 <主题>"`。
- 每个主题 vault 独立 git 仓库；不 push 远程，除非用户明确要求。
- 绝不改写/删除历史提交。

## 参考文件

- `references/templates.md`：笔记模板（撰写时先读取）
- `references/spaced-repetition.md`：间隔重复规则（复习排期用）
- `scripts/probe_pdf.py` / `scripts/render_pdf.py` / `scripts/ocr_windows.ps1`：扫描版 PDF 的 OCR 管线（详见第 2 步）