# Topic Knowledge Base

> 当用户想深入了解某个主题/关键词并建立学习型知识库时使用，建库采用"先总后细"的知识谱系结构 （_知识谱系.md 全库总图 + 分层目录 + 每类 _总览.md + 知识点笔记 + _log.md 增量日志 + 写后回读校验）。 支持三种信源模式：①web（纯联网搜索，准确系统，~80K tokens）②social（纯社媒多平台采集，真实考生经验，~120K tokens） ③hybrid（默认，双信源融合：Web建知识骨架+社媒注入备考经验/易错点/分歧辨析，~150K tokens，预压缩优化后）。 典型触发语：'研究/学习/了解/深入/科普 X'、'X 是什么'、'建立/创建 X 的知识库'、'把 X 整理成学习资料'、'我想学 X 帮我规划'、 '采集并建库 关键词=xxx'、'多平台采集并建库 xxx'、'媒体汇总/融合建库 xxx'、'建库 关键词=X 模式=web/social/hybrid'。 工作流：先查 E:\obsidian\rein 已有库防重复 → 选择信源模式（默认hybrid）→ 可选社媒采集清洗+预压缩（harvest_clean.py） → web_search 多路检索（social模式跳过）→ 设计知识谱系树（先总后细）→ 在 E:\obsidian\rein\<关键词>\ 按谱系树建目录 → 生成 _知识谱系.md 与各 _总览.md → 双信源融合生成结构化笔记（Web知识点+社媒多平台视角）与 _MOC 总索引 → 写后回读校验 → 引导用户按学习路径逐步学习。 每个主题为独立 vault，路径固定 E:\obsidian\rein\<主题>\，不统一路径。

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

---


# 主题知识库构建器（Topic Knowledge Base）

把任意关键词（如 "video coding"、"考研控制工程"、"LLM"、"六级英语"）变成 `E:\obsidian\rein\` 下的一套**"先总后细"的知识谱系学习库**（**每个主题 = 独立 vault**），并给出从入门到深入的学习路径。

## 触发条件（When to use）

用户说以下任意一类话时启用本 Skill：

- "研究 / 学习 / 了解 / 深入 / 科普 X"、"X 是什么"、"讲讲 X"
- "建立 / 创建 X 的知识库"、"把 X 整理成学习资料"
- "我想学 X，帮我规划"、"给我讲讲 X 从入门到精通"
- "采集并建库 关键词=X" / "用社媒采集结果建库 X" / "把 MediaCrawler 结果整理成知识库 X"（**社媒采集信源分支**，见第 1.6 步）

注意：X 是任意主题词（英文/中文均可）。本 Skill 不做固定学科假设，每次根据主题动态设计结构。

## 核心原则

1. **文件直写**：Vault 是纯 Markdown 文件夹，直接用文件工具（创建目录 / 写文件 / 追加）操作 `E:\obsidian\rein\`，不依赖 Obsidian App 是否打开、不依赖任何 Obsidian 插件。
2. **关键词即总目录**：每次在 `E:\obsidian\rein\` 根目录新建（或复用）与主题词对应的文件夹，如 `E:\obsidian\rein\video-coding\`、`E:\obsidian\rein\考研控制工程\`。**每个主题为独立 vault**：路径固定 `E:\obsidian\rein\<主题>\`，不与其他主题或 rein 四大库混用路径。
3. **从浅入深**：目录按"学习路径"组织：先总览，再概念，再深入，再实践，再资源。
4. **谱系化（先总后细）**：建库 = 先产出知识谱系树（关键词 → 大类 → 子概念 → 知识点），生成 `_知识谱系.md`（Mermaid mindmap 全库总图）与每个大类的 `_总览.md`（子谱系 + 索引），知识点笔记为最细层。形成"一图览全貌 → 每类一索引 → 每点一笔记"。
5. **带引用**：每篇笔记必须保留来源 URL（web_search 返回的链接），绝不编造。
6. **先查已有库（P0）**：建库前先扫描 `E:\obsidian\rein\` 是否已有相同/相似主题 → 已有则复用目录增量生长，不重复建库。
7. **增量生长**：用户追问子话题时，在对应目录下继续新建笔记，不重写已有内容；同时更新 `_知识谱系.md` 与对应 `_总览.md`，并在 `_log.md` 追加记录。
8. **_log.md 增量日志（P1）**：每主题库维护 append-only `_log.md`，记录每次建库/新增/更新的日期与条目，最新在上；只追加不覆盖。
9. **写后回读校验（P1）**：每批写入后回读抽查：文件存在、frontmatter 闭合、Mermaid/wikilink 语法正确、无乱码；发现问题就地修复。
10. **社媒多平台采集信源（P3，可选分支）**：当用户要求"采集并建库"或提供 MediaCrawler jsonl 时，用 `scripts/harvest_clean.py` 把多平台原始采集清洗成素材包 + 融合数据包（只留硬货：视频清单/课程目录/易错纠错/经验心得/资料链接，丢弃三连打卡等噪音；支持 B站/知乎/抖音/小红书/快手/微博/贴吧）。多平台时执行"重融合"：每篇核心笔记带 `## 🌐 多平台视角` 小节 + 根目录生成 `_媒体融合.md`（共识/分歧/互补总览）。素材内容只本地使用，笔记引用时保留原视频链接。
11. **三种信源模式（P0，默认 hybrid）**：建库前根据主题和用户指令选择信源模式，不同模式走不同流程、消耗不同 token：
    - **`web`（纯联网搜索，~80K tokens）**：只用 web_search 多路检索，建准确系统的知识体系。适合：新领域从零了解、纯技术/学术主题、需要权威定义和公式推导。**不采集社媒、不生成多平台视角**。
    - **`social`（纯社媒采集，~120K tokens）**：只用 MediaCrawler 多平台采集 + harvest_clean 清洗，建真实考生/从业者的经验库。适合：考研/考证/求职/备考方法类主题、需要真实踩坑和分歧辨析。**跳过 web_search，知识点框架从社媒素材的课程目录/经验贴中提取**。
    - **`hybrid`（双信源融合，默认，~150K tokens 优化后）**：Web 搜索建知识骨架（定义/公式/原理）+ 社媒采集注入血肉（备考方法/易错点/真实经验/分歧辨析）。每篇笔记 = Web 知识点 + 社媒 `🌐多平台视角`。适合：既要准确知识体系又要实战经验的主题（考研/考证/技能学习）。**hybrid 模式必须执行社媒素材预压缩（见第1.6.1步），避免 596 条硬货全塞进上下文导致 token 爆炸**。
    - 模式切换：用户说"建库 关键词=X 模式=web/social/hybrid"显式指定；未指定时默认 hybrid；用户说"省 token"或"简单建库"时自动降级为 web。

## 工作流（执行步骤）

### 第 0 步：澄清建库意图（Clarification Gate，P0）
- 收到建库请求后，**先检测关键信息是否充分**，不足则停下反问，不猜、不直接建库。
- 只问影响执行的高价值问题（最多 1-3 个），每个问题附"为什么问"，用白话、不用术语考用户。
- 常问四件套（按需取舍）：
  1. 这个主题你想达到什么目的？（A 入门科普 / B 系统深入 / C 备考应考）
  2. 期望建到多细？（A 概念总览 / B 到知识点 / C 到实践+资源）
  3. 信源模式选哪个？（A web 纯搜索~80K token / B social 纯社媒~120K / C hybrid 双信融合~150K，**默认 C**）——附说明：web 准确系统但缺实战经验，social 真实经验但知识点偏弱，hybrid 两者结合但 token 消耗最高
  4. `E:\obsidian\rein` 下是否已建过相关库？（增量补充 or 新建）
- 用户回答后，把答案整理成 2-3 句"建库意图快照"复述确认；用户说"开始/确认"才进入第 1 步。
- 若用户已给出足够明确的信息（含主题、目的、深度），跳过反问直接执行。
- 安全边界：不把模糊想法当建库授权；不替用户脑补主题范围、深度或分类方式。

### 第 1 步：确认主题、查已有库并制定检索计划
- 从用户话语中提取主题关键词（保留原文用词：英文小写、中文原样）。
- **查已有库**：扫描 `E:\obsidian\rein\` 根目录（列出所有子目录），若已存在同名或明显相似主题：
  - 告知用户"已存在 `<主题>` 库（N 个笔记）"，确认是**增量补充**还是**另建新库**（默认增量）。
  - 增量分支：跳到"第 3.5 步：增量生长"，只补新笔记并更新谱系/总览/_log。
- 设计 4~6 路检索维度（示例）：
  1. 定义与概述（X 是什么 / what is X）
  2. 发展历史与背景
  3. 核心概念与原理
  4. 分类 / 细分方向
  5. 实践、工具与上手路径
  6. 优质资源（教程 / 书籍 / 课程 / 项目）
- 若走"社媒采集信源分支"（第 1.6 步有素材包），检索维度可相应精简：素材包已覆盖"优质资源/实践路径"两路，web_search 侧重补"定义/历史/概念"等素材包给不了的维度。

### 第 1.5 步：信源模式路由（P0，默认 hybrid）
> 根据第0步确认的模式，决定后续流程走向。**未指定模式时默认 hybrid**。

**模式判断逻辑**：
1. 用户显式说"模式=web"或"纯搜索建库"→ `web` 模式
2. 用户显式说"模式=social"或"纯社媒建库"或"采集并建库"→ `social` 模式
3. 用户显式说"模式=hybrid"或"双信源"或"融合建库"→ `hybrid` 模式
4. 用户说"省 token"或"简单建库"或"快速了解"→ 自动降级为 `web` 模式
5. **未指定**→ 默认 `hybrid` 模式

**各模式后续流程差异**（+教材信源为可叠加选项，任意模式都可加）：

| 步骤 | web 模式 | social 模式 | hybrid 模式（默认） |
|---|---|---|---|
| 第1.6步 社媒采集 | ❌ 跳过 | ✅ 执行采集+清洗 | ✅ 执行采集+清洗+预压缩 |
| 第1.7步 教材PDF | ⭕ 可选 | ⭕ 可选 | ⭕ 可选（推荐，知识性最强） |
| 第2步 web_search | ✅ 8路全检索 | ❌ 跳过 | ✅ 8路深度检索 |
| 第3步 谱系设计 | 基于web结果 | 基于社媒课程目录/经验 | web骨架+社媒血肉+教材体系 |
| 第4步 笔记撰写 | 标准模板 | 加🌐多平台视角 | 双信源融合模板 |
| 第4.5步 _媒体融合 | ❌ 不生成 | ✅ 生成 | ✅ 生成 |
| 预估token | ~140K | ~130K | ~175K（+教材另算） |

**模式切换记录**：在 `_log.md` 首条记录"建库模式：web/social/hybrid"，方便后续增量更新时保持一致。

### 第 1.6 步：社媒多平台采集信源（可选分支，P3）
**触发**：用户说"采集并建库 关键词=X"，或提供了 MediaCrawler 采集产物（jsonl 目录路径）。

**平台**：MediaCrawler 支持 7 平台——B站(bili)/知乎(zhihu)/抖音(dy)/小红书(xhs)/快手(ks)/微博(wb)/贴吧(tieba)，各自扫码登录一次即可。

1. **采集**（若用户未提供 jsonl，且本机装了 MediaCrawler）：
   - 引导用户运行 `E:\tools\启动-社媒采集.bat` 逐个平台完成采集（每平台首次需手机扫码），
     或由 Agent 后台运行：`python main.py --platform <平台> --lt qrcode --type search --keywords "<关键词>"`
     （工作目录 `E:\tools\MediaCrawler`，需 `PLAYWRIGHT_BROWSERS_PATH=E:\tools\pw-browsers`，并清掉 HTTP_PROXY/HTTPS_PROXY 让国内站直连）。
   - 采集产物在 `E:\tools\MediaCrawler\data\<平台>\jsonl\`。
2. **清洗（多平台）**：
   ```bash
   # 自动扫描 data 下所有已采集平台
   python "<skill目录>\scripts\harvest_clean.py" --root "E:\tools\MediaCrawler\data"
   # 或指定平台目录（逗号分隔）
   python "...\harvest_clean.py" --dir "<平台1jsonl>,<平台2jsonl>"
   ```
   产出：每平台一个 `harvest_<关键词>_<平台>_<日期>.md` 素材包 + 多平台时自动生成
   **`fuse_<关键词>_<日期>.md` 融合数据包**（跨平台同源内容去重 + 平台覆盖统计 + 按类别跨平台合并）。
3. **读取全部素材包与融合数据包**作为高价值中文信源，告知用户各平台清洗统计。
4. 之后照常进入第 2 步（web_search 补维度）与第 3 步（谱系设计）。
5. **谱系设计优先利用素材包**：评论区高频"课程目录/章节框架"是领域真实知识骨架（如卢京潮 40 讲目录），
   应作谱系树主干参考；"易错纠错/经验心得"转化为对应知识点的"易错点/学习路径"素材。
6. 第 3.6 步确认关卡照常执行，展示信源构成时注明各平台采集数量。

### 第 1.6.1 步：社媒素材预压缩（hybrid 模式必做，social 模式可选，P0）
> **目的**：把 harvest_clean.py 产出的 596 条硬货压缩成 80-120 条精华，按知识点分类，避免全量塞进上下文导致 token 爆炸（596条≈90K输入 → 压缩后≈15K输入，省 80%）。

**触发条件**：
- hybrid 模式：**必须执行**（否则双信源融合输入超 150K）
- social 模式：可选（素材量 < 200 条时可跳过，直接用融合数据包）
- web 模式：不执行（无社媒素材）

**预压缩流程**：
1. **读取融合数据包** `fuse_<关键词>_<日期>.md`（已按类别合并：目录/纠错/经验/资料）
2. **LLM 压缩（用最便宜的模型，如 DeepSeek/通义）**：
   - 输入：融合数据包全文（~90K tokens）
   - 指令："把以下考研数学社媒素材压缩成精华，按知识点分类（如：老师选择/习题集/计算错误/概念误区/复习规划/心态），每类保留 5-15 条最有价值的内容，丢弃重复和低价值内容。输出格式：## 类别名 → 1. 精华内容（来源平台）。总条数控制在 80-120 条。"
   - 输出：`compressed_<关键词>_<日期>.md`（~15K tokens，按知识点分类的精华）
3. **后续建库只读取压缩版**，不再读取原始融合数据包和各平台素材包
4. **原始素材包保留在 `raw_material/` 目录**，供后续回溯和增量更新使用

**Token 成本对比**：
| 方式 | 输入 tokens | 说明 |
|---|---|---|
| 不压缩（全量喂） | ~90K | 596条硬货全塞进上下文 |
| 预压缩（推荐） | ~15K | 80-120条精华，按知识点分类 |
| 节省 | **~75K（83%）** | 压缩步骤本身消耗 ~100K（输入90K+输出10K），但建库时省 75K，**总成本略高但避免单次上下文溢出** |

> **注意**：预压缩是"用一次额外调用换上下文安全"。如果模型上下文窗口 ≥ 128K（如 DeepSeek-V4 1M），可以跳过预压缩直接用融合数据包；如果用 32K/64K 窗口模型，**必须预压缩**。

### 第 1.7 步：教材/讲义 PDF 信源（可选分支，P1）
> 知识性最强的信源：教材/考研讲义提供**系统知识体系**（定义/定理/证明/例题），
> 社媒提供备考经验，web 提供拓展。三者融合 = 真正"能带你学习"的知识库。

**触发**：用户说"用教材建库/把教材加入建库"，或提供了教材/讲义 PDF 路径。

**处理流程（MinerU API，skill: mineru-pdf-extractor）**：
1. **收集教材 PDF 路径**（可多个，如武忠祥高数基础+强化、李永乐线代、汤家凤概率）。
2. **检查页数和大小**（MinerU 单文件限制 **≤200 页**，大文件上传极慢）：
   ```bash
   python -c "import fitz; d=fitz.open(r'<pdf路径>'); print(d.page_count, '页')"
   ```
   - 超 200 页用 `scripts/split_pdf.py` 拆分成 ≤190 页的分卷。
   - **大文件（>50MB）必须先压缩**：用 `scripts/compress_pdf.py`（PyMuPDF + Pillow，200 DPI + JPEG 85，可压 90%+，文字公式清晰度足够）。
     - 341MB → 31MB（节省 91%），上传从 2 小时降到 2 分钟。
     - 压缩命令：`python scripts/compress_pdf.py <输入pdf> <输出pdf> 200`
3. **申请上传 URL**：⚠️ **不要用 curl**（TLS 指纹被 MinerU 风控，返回 -500），用 **Python urllib 或 PowerShell Invoke-RestMethod**：
   - Python：`urllib.request` + `ProxyHandler({})`（清代理直连）
   - 必须清掉 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量（VPN 代理会导致 WinError 10061）
4. **上传**：用 `curl.exe --noproxy "*" -X PUT <url> --upload-file <pdf>` 直传阿里云 OSS（OSS 无 TLS 风控）。
   ⚠️ **签名 URL 有效期约 15 分钟**：每个文件**独立申请 URL + 立即上传**，不要批量申请后排队传大文件（会过期）。
   ⚠️ **大文件超时**：curl `--max-time` 设为 1800（30分钟），subprocess timeout 设为 1900。
5. **轮询结果**：`GET https://mineru.net/api/v4/extract-results/batch/<batch_id>`，返回结构：
   ```json
   {"data": {"extract_result": [{"state": "done", "full_zip_url": "https://..."}]}}
   ```
   state=done 后下载 `full_zip_url`（zip 包含 full.md + images/ + layout.json）。
6. **按章节拆分**：把提取的 full.md 按章拆分为独立文件：
   - 优先按 `## 第X章` 二级标题拆分（很多教材一级标题 # 很少，实际章节在 ## 里）
   - 用 `scripts/resplit_textbook.py <full.md> <输出目录> <书名>` 自动拆分
   - 存到 `E:\obsidian\rein\<主题>\99-教材原文\<书名>\<章节>.md`（保留原始公式 LaTeX、表格、例题）
   - 每本书生成 `_目录.md` 索引（wikilink 指向各章节）

**建库融合方式（教材信源 + 现有模式）**：
- 教材原文放 `99-教材原文\` 目录（原始提取，不加工）
- 知识点笔记正文：**定义/定理/证明/例题优先引用教材原文**（比 web 搜索更准确系统）
- 社媒素材补充：易错点/备考经验/老师对比
- web 搜索补充：拓展应用/前沿进展
- 笔记中标注来源：`教材：《<书名>》第X章` + 原文链接 `[[99-教材原文/...]]`

**教材融合版笔记结构（标准模板，后续建库自动套用）**：

```markdown
---
category: "学科"
tags: ["知识点","教材融合"]
source: ["教材名","社媒建库"]
created: "YYYY-MM-DD"
---

# 知识点名（教材融合版）

> 教材原文全文见 [[99-教材原文/<书名>/<章节>|章节名]]

---

## 📌 一、核心定义（教材原文）
- 每个定义用引用块 > 标注，保留原始公式（LaTeX）
- 定义后加1-2句解释或注记
- 相关概念对比用表格

## 📐 二、定理与重要公式（教材原文）
- 定理用编号列表，条件和结论分开
- 公式用 $$...$$ 独立成行
- 常用公式汇总用表格（公式+适用条件+备注）

## 📝 三、经典例题（教材精选）
- 每道例题：题目→解题步骤→易错标注
- 精选3-5道最典型的例题，不堆砌
- 例题后加 > ⚠️ 常见错误 标注

## 🎯 四、常见题型（社媒归纳）
- 按考试频率排序，标注题型（选择/填空/大题）
- 每题加1句解题要点

## ⚠️ 五、易错点（教材强调 + 社媒纠错）
- 6-10条，每条：错误做法→正确做法→原因
- 教材强调的经典错误优先
- 社媒高频问题补充

## 🔗 六、知识关联（前置/后续/跨学科）
- 前置知识：学习本知识点需要先掌握什么
- 后续知识：本知识点是哪些后续知识的基础
- 跨学科：与其他学科的联系

## ✅ 七、掌握检验（checklist）
- 5-8条可自测的问题，用 - [ ] 格式
- 覆盖定义、计算、应用、易错点

## 🌐 八、多平台视角（社媒）
- B站/知乎/小红书各1句共识或经验
- 标注老师名字和课程名

## 📚 九、参考来源
- 教材：[[99-教材原文/...|书名 章节]]（字符数）
- 例题：[[98-教材例题库/...|知识点例题库]]（N道）
- 社媒：[[知识点]]（社媒建库精简版）
```

**模板使用规则**：
1. **不覆盖现有社媒版笔记**，新建"（教材融合版）"文件，两者通过 wikilink 互链
2. 教材定义/定理精简提取（不全文复制），详细内容通过 wikilink 指向 99-教材原文
3. 例题从 `98-教材例题库/` 引用，精选3-5道，不堆砌
4. 易错点必须同时包含"教材强调"和"社媒纠错"两个来源
5. 掌握检验用 checklist 格式，方便学生自测
6. frontmatter 必须包含 `source` 字段，标注教材名和社媒建库

**教材例题库自动提取**（`scripts/extract_examples.py`）：
- 扫描 `99-教材原文/` 下所有 .md 文件，提取【例X】/例X. 标记的题目
- 按知识点自动分类（文件名优先 + 内容关键词补充）
- 输出到 `98-教材例题库/<学科>/<知识点>.md`，每道题带教材来源 wikilink
- 生成 `_例题库总览.md` 索引

**完整三信源融合笔记结构**：
```markdown
## 📌 核心定义（教材原文，最权威）
## 📐 定理与证明（教材原文）
## 📝 经典例题（教材例题 + 考研真题）
## 🎯 常见题型（web搜索）
## ⚠️ 易错点（社媒纠错素材）
## 🔗 前置知识 / ➡️ 后续知识
## ✅ 掌握检验
## 🌐 多平台视角（社媒）
## 📚 参考来源（教材章节 + web URL + 社媒链接）
```

### 第 2 步：多路搜索（web/hybrid 模式执行，social 模式跳过）
- **模式判断**：
  - `web` 模式：8 路全检索（定义/历史/概念/分类/实践/资源/例题/对比）
  - `hybrid` 模式：**8 路深度检索**（社媒给备考经验，web 必须给足知识点深度，不能只搜3路）
  - `social` 模式：**跳过本步**，直接进入第3步（谱系从社媒课程目录/经验贴提取）
- **8 路检索维度（web/hybrid 通用，按主题动态调整）**：

  | 路数 | 维度 | 搜索词示例 | 产出 |
  |---|---|---|---|
  | 1 | 定义与原理 | "X 的定义 详解"、"X 是什么 原理" | 严格定义、几何/物理意义、本质 |
  | 2 | 公式与推导 | "X 公式 推导过程"、"X 定理 证明" | 公式、适用条件、推导步骤 |
  | 3 | 经典例题 | "X 经典例题 解析"、"X 题型 20道" | 例题+详细解析、解题步骤 |
  | 4 | 易混淆对比 | "X 和 Y 的区别"、"X vs Y 对比" | 对比表格、判断方法、典型误区 |
  | 5 | 解题方法 | "X 的解题方法 总结"、"求 X 的 N 种方法" | 方法清单、适用场景、选择策略 |
  | 6 | 知识框架 | "X 知识框架 思维导图"、"X 知识点体系" | 知识点依赖关系、整体结构 |
  | 7 | 常见题型 | "X 考试题型 归纳"、"X 考研/期末 常考" | 题型分类、分值占比、解题套路 |
  | 8 | 拓展应用 | "X 在 工程/物理/计算机 中的应用" | 跨学科联系、实际应用案例 |

  > **注意**：8 路是上限，简单主题（如"什么是傅里叶变换"）可精简到 5-6 路；复杂主题（如"考研数学"、"自动控制原理"）必须 8 路全搜。**hybrid 模式不再精简到 3 路**——社媒给"怎么学"，web 必须给足"学什么"。

- 用 `web_search` 逐路检索，每路 1 次调用，`count` 取 5~8。
- **逐路串行调用，不要并行**：一次并行发起多路 web_search 会触发 DuckDuckGo 反爬限流（返回 "bot-detection challenge"），随后百度/Bing 也可能联动限流；遇到限流隔几十秒重试一次，仍失败就按下面规则标注"待补充"，不硬编。
- 若某路返回空，调整关键词再试一次；仍空则记录"该维度暂无可靠结果"，不编造。
- **hybrid 模式特殊处理**：web_search 结果和社媒压缩素材（第1.6.1步产出）一起作为第3步谱系设计的输入；web 结果负责"知识骨架+深度讲解"，社媒素材负责"血肉（经验/易错/分歧/老师选择）"。

### 第 3 步：设计知识谱系树并创建目录（先总后细）
- **自适应接入（personal-twin，P2）**：动手设计谱系前先读取用户画像参数（见
  `personal-twin/references/adaptation-guide.md` 的读取命令）：
  目标主题属于已评级领域时，按 `adaptation.<领域>.depth` 决定建库深度（≤2 级多建"概念入门/核心深入"、
  =3 级加大"实践应用"占比）；`example_kind` 决定例子类型（如控制工程用土木机械类比）；
  输出按"结构化分步+可动手清单"优先（用户 VARK: K>R>A>V）。读不到画像就按默认深度，不阻塞。
- 综合搜索结果，先产出**知识谱系树**（缩进树形，先总后细，后续所有产物的统一骨架）。**必须细化到"具体知识点"层，不能停留在"大类"层**：
  ```
  <关键词>
  ├── <大类A>（如：高等数学）
  │   ├── <子类A1>（如：极限与连续）
  │   │   ├── <知识点a>（如：数列极限的定义）← 每篇笔记聚焦一个知识点
  │   │   ├── <知识点b>（如：函数极限的定义）
  │   │   ├── <知识点c>（如：等价无穷小替换）
  │   │   └── ...
  │   ├── <子类A2>（如：导数与微分）
  │   │   ├── <知识点d>（如：导数的定义）
  │   │   └── ...
  │   └── ...
  ├── <大类B>（如：线性代数）
  │   └── ...
  └── <大类C>（如：备考方法论）← 社媒素材主要贡献这部分
      ├── 老师选择
      ├── 习题集选择
      └── ...
  ```
  **粒度要求**：
  - 简单主题（如"什么是傅里叶变换"）：2-3 个大类，每个大类 3-5 个知识点，总计 10-15 篇笔记
  - 中等主题（如"自动控制原理"）：3-4 个大类，每个大类 5-8 个知识点，总计 20-30 篇笔记
  - 复杂主题（如"考研数学"）：4-6 个大类，每个大类 8-15 个知识点，总计 40-60 篇笔记
  - **每篇笔记必须聚焦一个具体知识点**（如"等价无穷小替换"），不能是一个大类（如"极限与连续"）。大类/子类只建 `_总览.md` 索引，不建泛泛而谈的笔记。
- 在 `E:\obsidian\rein\<关键词>\` 下按谱系树创建目录 + 生成"总"层产物（数字前缀保证排序）：
  ```
  E:\obsidian\rein\<关键词>\
  ├── _知识谱系.md             # 全库总谱系图（Mermaid mindmap，先总：一图览全貌）
  ├── _MOC.md                  # 总索引 + 学习路线图（必建）
  ├── _log.md                  # 增量日志（append-only，必建，P1）
  ├── 01-<大类A>\               # 如：01-高等数学
  │   ├── _总览.md             # 该大类子谱系 + 子类索引 + 推荐学习顺序（先总）
  │   ├── 01-<子类A1>\          # 如：01-极限与连续
  │   │   ├── _总览.md         # 该子类知识点索引 + 学习顺序
  │   │   ├── <知识点a>.md      # 如：数列极限的定义.md（每篇聚焦一个知识点）
  │   │   ├── <知识点b>.md
  │   │   └── ...
  │   ├── 02-<子类A2>\          # 如：02-导数与微分
  │   │   └── ...
  │   └── ...
  ├── 02-<大类B>\               # 如：02-线性代数
  │   └── ...
  ├── 03-<大类C>\               # 如：03-概率论（数一/数三）
  │   └── ...
  └── 04-备考方法论\            # 社媒素材主要贡献这部分（老师选择/习题集/时间规划/心态）
      ├── _总览.md
      ├── 老师选择指南.md
      ├── 习题集选择.md
      └── ...
  ```
  > **目录结构说明**：大类用数字前缀（01/02/03），子类也用数字前缀（01/02），知识点笔记不用前缀（按知识点命名）。这样 Obsidian 文件浏览器里按学习顺序排列。
- 生成 `_知识谱系.md`：谱系树转 Mermaid mindmap（Obsidian 原生渲染）；总谱系画到"子类"层，知识点层放在各子类 `_总览.md`。
- 生成每个大类/子类的 `_总览.md`：子谱系（Mermaid mindmap 或树形，细化到知识点）+ 该分类全部笔记 `[[]]` 索引 + **推荐学习顺序**（按知识点依赖关系排序，先学前置知识）+ **该分类学习目标**（学完应该掌握什么）。
- 生成 `_log.md`：记录建库日期、谱系规模（大类数/子类数/知识点笔记数）、待补充维度（格式见 `references/templates.md`）。
- 层级数量与子概念根据主题复杂度**动态增减**，不必每层都建；命名：中文主题用"什么是-XXX"，文件夹用主题词本身；知识点笔记用知识点名称命名（如"等价无穷小替换.md"），不要用"知识点1.md"这种无意义名称。

### 第 3.5 步：增量生长（已有库时，P0 分支）
- 复用已有目录结构，只在对应分类/子分类下**新建缺失的笔记**，不重写已有内容。
- 同步更新 `_知识谱系.md`、对应 `_总览.md`（加入新笔记索引）、`_MOC.md`。
- 在 `_log.md` 追加："YYYY-MM-DD：新增《<笔记>》于 <分类>/<子分类>"。

### 第 3.6 步：建库蓝图确认（Checkpoint，P2）
- **谱系树定稿后、正式写笔记前，强制向用户展示"建库蓝图"并等待确认**（借鉴 ResearStudio 人类可干预思路，防止建完才发现方向不对）：
  1. 知识谱系树总图（Mermaid mindmap / 缩进树）
  2. 每个大类计划创建的**笔记清单**与**预计篇数**
  3. 每个大类的**信源构成**（来自哪些搜索/采集来源，中文/英文占比）
- 展示后询问：`回复【确认】开始写笔记；要调整请直接说明改哪里（如"删掉 XX 类 / 加 YY 主题 / XX 类太浅"）`
- **用户确认后才进入第 4 步；未确认禁止写任何文件**。
- 用户要求调整 → 修改谱系树/笔记清单后再次展示，直到用户确认；调整点记入 `_log.md`。

### 第 3.7 步：多平台融合设计（重融合，P3）
> 仅在用户要求"多平台融合/媒体汇总"或存在 ≥2 个平台素材包时执行。

- 建库前，LLM 通读全部平台素材包 + `fuse_*.md` 融合数据包，产出**融合视图**（写入第 3.6 步蓝图展示）：
  1. **平台覆盖矩阵**：各平台覆盖了主题的哪些维度（如 B站=体系课程、知乎=原理推导、小红书=实操技巧、抖音=直觉碎片）
  2. **共识点**：≥2 平台一致的结论 → 标记为"高可信核心知识"，建库时优先写入正文
  3. **分歧点**：平台间说法/定义/流派不同的 → 单独建"分歧与辨析"笔记或在对应知识点标注
     （典型如教材流派差异、奈奎斯特图定义差异），附各平台原文说法
  4. **互补结构**：各平台擅长维度 → 优化学习路径顺序（先抖音直觉 → B站体系 → 知乎原理 → 小红书技巧）
- 用户确认蓝图后照常建库。

### 第 4 步：撰写笔记（每篇用统一模板，按信源模式选择结构）
- 模板见 `references/templates.md`（先读取，按其结构撰写）。
- 每篇笔记聚焦一个知识点；事实与来源必须来自 web_search 返回结果；拿不准的标注"待核实"。
- **按信源模式选择笔记结构**（**所有模式都必须包含学习闭环：前置知识/后续知识/掌握检验**）：

  **web 模式（标准结构，带学习闭环）**：
  ```
  ---
  frontmatter（topic/tags/category/source/prerequisites/next）
  ---
  # 知识点标题（如：等价无穷小替换）

  ## 📌 核心定义（是什么）
  - 严格定义、几何/物理意义、本质

  ## 📐 公式与推导（为什么）
  - 核心公式、适用条件、推导步骤

  ## 📝 经典例题（3-5道，带详细解析）
  - 例题1：题目 → 解题步骤 → 答案 → 关键技巧
  - 例题2：...
  - 例题3：...

  ## 🎯 常见题型（考研/期末怎么考）
  - 题型1：...（解题套路）
  - 题型2：...

  ## ⚠️ 易错点（哪里容易错）
  - 易错点1：...（错误原因 + 正确做法）

  ## 🔗 前置知识（学这个之前需要掌握什么）
  - [[知识点A]]、[[知识点B]]（wikilink）

  ## ➡️ 后续知识（学完这个可以学什么）
  - [[知识点C]]、[[知识点D]]（wikilink）

  ## ✅ 掌握检验（3道自测题，带答案）
  - 自测1：...（答案：...）
  - 自测2：...（答案：...）
  - 自测3：...（答案：...）

  ## 📚 参考来源（URL列表）
  ```

  **social 模式（加多平台视角，带学习闭环）**：
  ```
  ---
  frontmatter（topic/tags/category/source=社媒采集/prerequisites/next）
  ---
  # 知识点标题

  ## 📌 核心知识点（从社媒课程目录/经验贴提取）
  ## 📝 经典例题（社媒课程中讲到的例题）
  ## 🎯 常见题型/应用场景
  ## ⚠️ 易错点（来自社媒纠错类素材，真实踩坑）
  ## 🔗 前置知识
  ## ➡️ 后续知识
  ## ✅ 掌握检验（3道自测题，带答案）
  ## 🌐 多平台视角（各平台如何讲这个点+共识+分歧）
  ## 📚 参考来源（原视频链接，标注"网友经验供对照参考"）
  ```

  **hybrid 模式（双信源融合，默认，带学习闭环）**：
  ```
  ---
  frontmatter（topic/tags/category/source=web+社媒/prerequisites/next）
  ---
  # 知识点标题

  ## 📌 核心定义（**来自web搜索，准确系统**）
  ## 📐 公式与推导（**来自web搜索，严格推导**）
  ## 📝 经典例题（3-5道，web搜索+社媒课程例题）
  ## 🎯 常见题型（web+社媒课程目录）
  ## ⚠️ 易错点（**来自社媒纠错类素材，真实踩坑**）
  ## 🔗 前置知识（wikilink）
  ## ➡️ 后续知识（wikilink）
  ## ✅ 掌握检验（3道自测题，带答案）
  ## 🌐 多平台视角（**来自社媒压缩素材，各平台说法+共识+分歧**）
  ## 📚 参考来源（web URL + 社媒原视频链接）
  ```
  - **hybrid 模式核心原则**：知识点本身（定义/公式/原理/推导）用 web 搜索结果（准确），备考方法/易错点/真实经验/分歧辨析用社媒素材（接地气）。**不要用社媒内容代替知识点定义**（社媒有错误观点，如"数一要考数学分析"）。
  - **学习闭环强制要求**：每篇知识点笔记必须包含「前置知识」「后续知识」「掌握检验」三个小节。前置/后续用 wikilink 链接到其他笔记，形成知识网络；掌握检验必须有 3 道自测题（带答案），让用户学完能立即检验掌握程度。
  - **经典例题强制要求**：每篇知识点笔记必须包含 3-5 道经典例题（带详细解析），不能只有定义和公式。例题来源：web 搜索到的例题解析、社媒课程中讲到的例题、考研/期末真题。

- **社媒信源引用**：来自素材包的内容，来源标注 `社媒采集：<原视频链接>`（素材包视频清单里有链接）；
  评论区经验/纠错注明"网友经验/弹幕纠错，仅供对照参考"，不当作权威结论。
- **多平台视角小节（重融合，P3）**：若走融合分支（social/hybrid），每篇核心知识点笔记末尾加 `## 🌐 多平台视角` 小节：
  - 各平台如何讲这个点（如 `- B站（课程）：…` / `- 知乎（原理）：…` / `- 小红书（技巧）：…`），标注来源链接
  - 共识（多平台一致）与分歧（说法不同 + 你的判断/待查）
  - 没有该平台内容就写"（该平台暂无此点内容）"，不编造。
- **hybrid 模式笔记数量控制**：知识点笔记按主题复杂度控制（简单 10-15 篇 / 中等 20-30 篇 / 复杂 40-60 篇），备考方法论/易错点/资源类笔记 5-10 篇（社媒血肉）。**知识点细化后，单篇笔记聚焦一个具体知识点（如"等价无穷小替换"），每篇 1500-2500 字，包含 3-5 道例题和 3 道自测题**。总笔记数 15-70 篇，总输出 tokens 50K-150K。

### 第 4.5 步：生成 _媒体融合.md（重融合，P3）
- 建库完成后，在主题根目录生成 `_媒体融合.md` 总览：
  1. 平台覆盖总览表（各平台采集量/擅长维度）
  2. **共识知识清单**（多平台一致的核心结论 → 高可信）
  3. **分歧与辨析表**（分歧点 + 各平台说法 + 建议处理）
  4. **跨平台互补与学习路径建议**（按平台特长排的学习顺序）
  5. 链接到各知识点笔记与素材包；更新 `_MOC.md` 索引加入本文件。

### 第 5 步：生成 _MOC.md（总索引 + 学习路线）
- 主题一句话介绍；学习路线（概念入门 → 核心深入 → 实践应用 → 资源）；链接到 `_知识谱系.md`；按目录列出所有笔记，用 `[[]]` 双向链接；待补充清单（哪些维度还没搜全，后续追问时补）。

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

### 第 7 步：向用户汇报
- 给出知识库路径、全库谱系图（`_知识谱系.md`）与目录结构、推荐学习顺序。
- 若走融合分支：额外给出 `_媒体融合.md` 的共识/分歧/互补摘要。
- 提示：想深入哪个子话题直接说，会在对应目录继续细化补充，并同步更新谱系图与 `_log.md`。

## 红线（必须遵守）

1. 只允许在 `E:\obsidian\rein\` 下创建 / 修改文件；禁止触碰其他磁盘目录；禁止修改 rein 四大库（01-每日日志 / 02-学习库 / 03-项目库 / 04-简历成长库）内的现有文件。
2. 每个主题 = 独立 vault：`E:\obsidian\rein\<主题>\`，不写入、不引用 rein 四大库，不混用路径。
3. 写文件前检查目标是否存在：已存在则按需 append 或在同目录新建带后缀的笔记，禁止覆盖已有笔记。
4. 所有事实与来源必须来自 web_search 返回结果；拿不准的标注"待核实"。
5. 不删除任何已有笔记。
6. 文件操作优先用创建 / 追加接口；涉及大量文件时先列出计划再执行。
7. `_log.md` 只追加、不覆盖；历史条目保留。
8. 社媒素材仅本地建库使用，不重新发布/商用；评论内容引用时保留原视频链接并标注"网友经验，供对照参考"。

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

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

## Token 经济优化（P0，必看）

### 三种模式 Token 消耗对比（v2：8路搜索+知识点细化+学习闭环）

| 模式 | 输入 tokens | 输出 tokens | 合计 | 国内模型成本 | 适用场景 |
|---|---|---|---|---|---|
| web | ~60K（8路搜索） | ~80K（15-30篇×2000字） | **~140K** | ~¥0.4 | 新领域从零了解、纯技术/学术 |
| social | ~70K（社媒素材） | ~60K（10-20篇×2000字） | **~130K** | ~¥0.4 | 备考/经验/求职类 |
| hybrid（默认） | ~75K（8路web+社媒预压缩） | ~100K（20-50篇×2000字） | **~175K** | ~¥0.5 | 既要知识体系又要实战经验 |

> 成本按 DeepSeek-V4 估算（输入¥1/百万，输出¥4/百万）；用阿里云通义更便宜（~¥0.3/次）。**v2 版本因为 8 路搜索+知识点细化+例题+自测题，token 消耗比 v1 增加约 40-60%，但知识性提升 200%+。一次建库不到 1 块钱。**

### hybrid 模式的 Token 优化策略（按优先级）

1. **必做：社媒素材预压缩（第1.6.1步）**
   - 596条硬货（~90K输入）→ 80-120条精华（~15K输入），省 83%
   - 压缩步骤用最便宜的模型（DeepSeek/通义），建库步骤用好模型
   - **不做预压缩，hybrid 模式输入会超 160K，小窗口模型直接溢出**

2. **必做：8 路搜索但逐路串行（避免反爬限流）**
   - v2 版本 hybrid 模式从 3 路增加到 8 路（知识性提升的核心），但必须逐路串行
   - 并行会触发 DuckDuckGo 反爬，导致后续搜索全部失败
   - 遇到限流隔 30 秒重试，仍失败就标注"待补充"，不硬编

3. **推荐：按主题复杂度控制笔记数量**
   - 简单主题（如"什么是傅里叶变换"）：10-15 篇知识点笔记
   - 中等主题（如"自动控制原理"）：20-30 篇
   - 复杂主题（如"考研数学"）：40-60 篇
   - 每篇 1500-2500 字（含 3-5 道例题 + 3 道自测题）
   - 超过 60 篇会导致输出 token 超 150K

4. **推荐：大主题分批建库**
   - 主题过大（如"人工智能"、"考研全科"）时，先建骨架（谱系+总览+核心概念 10 篇）
   - 子主题后续追问时增量补充（第3.5步增量生长）
   - 避免一次建库 70+ 篇笔记

5. **可选：跳过预压缩（大窗口模型）**
   - 如果用 128K+ 窗口模型（DeepSeek-V4 1M、Claude 3.5 Sonnet 200K）
   - 可以跳过预压缩，直接用融合数据包（~90K输入）
   - 省一次调用，但输入 token 增加 ~75K

6. **可选：例题和自测题用 web 搜索结果直接引用**
   - 不要让 LLM 自己编例题（容易出错且耗 token）
   - 8 路搜索中的"经典例题"路会返回带解析的例题，直接引用
   - 自测题可以从例题中简化/改编，不需要 LLM 从零生成

### 什么时候自动降级为 web 模式

- 用户说"省 token"、"简单建库"、"快速了解"、"先看看"
- 主题是纯技术/学术（如"什么是傅里叶变换"），社媒素材价值低
- 用户 token 余额不足或模型窗口 < 64K
- 降级时告知用户："已自动降级为 web 模式（省 token），如需社媒实战经验请说'模式=hybrid'"

### 什么时候推荐升级为 hybrid 模式

- 主题是备考/考证/求职/技能学习（如"考研数学"、"六级英语"、"Python入门"）
- 用户问"怎么学"、"有什么经验"、"避坑"、"选哪个老师"
- web 模式建库后用户反馈"不够实用"、"没有真实经验"
- 升级时告知用户："已切换为 hybrid 双信源模式（~175K tokens，含8路搜索+知识点细化+例题+自测题），将加入真实考生经验和易错点"

## 参考文件

- `references/templates.md`：笔记统一模板（撰写时先读取）