flying3615 Reading Vault Builder
把书籍资料整理成 Obsidian 风格的 ReadingVault/。默认目标是读书笔记库，不是陪读对话，也不是代码工程分析。
默认约定：
- 主输入：
PDF、epub - 次输入：
txt、md、url - 默认输出：中文笔记
- 保留：原文术语、关键引文
- 组织方式：章节笔记为主，主题索引为辅
所有读取和输出都限制在 CWD 内。用户给外部路径时，要求先复制到当前目录。
默认产物
ReadingVault/
00-Overview/
01-Chapters/
02-Themes/
03-Concepts/
04-Quotes/
05-Checks/
00-Overview/：全书总览、章节入口、主题入口01-Chapters/：逐章笔记，主阅读层02-Themes/：跨章节主题或母题03-Concepts/：高频概念、人物、框架04-Quotes/：可追溯引文05-Checks/：轻量理解检查
模板见 references/templates.md。交付前按 references/quality-checklist.md 自检。
提取脚本
处理 epub 时，优先先运行本地脚本：
python3 reading-vault-builder/scripts/extract_epub.py \
--epub "/path/to/book.epub" \
--out-dir "./out/epub-text"
默认输出：
metadata.jsontoc.jsonchapters.jsonchapters/*.txt
后续笔记整理优先基于这些抽取结果，而不是直接在压缩包里逐个猜章节。
工作流
1. Discover
扫描并确认书籍源：
**/*.pdf**/*.epub**/*.txt**/*.md- 用户给出的
url
排除：
.git/node_modules/dist/build/ReadingVault/
如果有多本书、多版本或多卷，先让用户确认当前处理对象。
2. Extract
先拿到可读文本，再分析。
PDF：优先pdftotextepub：优先运行reading-vault-builder/scripts/extract_epub.pytxt/md：直接读取url：只提正文，不把导航、广告、评论区当正文
先确认：
- 书名
- 作者
- 目录或章节列表
- 前言 / 正文 / 附录边界
3. Map Structure
先建结构地图，再写笔记。
至少完成：
- 读封面、目录、开头
- 抽样读中段和末段
- 建立映射：
chapter/section -> source file -> page range or anchor
- 没有稳定页码时，用章节锚点或标题层级
- 材料不完整时，明确标缺失
4. Write Chapter Notes First
先写章节页，再写跨章节页。不要一开始就写一篇全书长总结。
每章至少包含：
- 本章摘要
- 核心观点 / 关键事件
- 关键概念 / 人物 / 场景
- 重要引文
- 与前后章节的联系
- 我的疑问
3-5个理解检查题## Related Notes
5. Build Cross-Chapter Pages
在章节页稳定后再生成：
00-Overview/全书总览.md02-Themes/：只收跨章节主题03-Concepts/：只收值得反复引用的概念、人物、框架04-Quotes/：只收可追溯的重要引文05-Checks/：章节很多时再拆出独立检查页
按书籍类型调整重心
- 非虚构：主张、论证、框架、定义、证据
- 小说/叙事：情节、人物、场景、母题、转折
- 传记/历史：时间线、行动者、因果链、解释框架
无论类型，都保持“章节优先，再做主题整合”。
链接与标签
标签统一用英文、小写、kebab-case，例如：
#book-...#theme-...#concept-...#character-...#note-chapter#note-theme
链接规则：
00-Overview/链到所有章节页和主题入口页- 每个章节页都要链接相关主题页或概念页
- 主题页必须反链回章节页
- 概念页要指出首次出现或主要出现章节
- 引文页必须能回到章节页
可追溯性
始终区分：
- 原书直接信息
- 多章综合归纳
- 书外补充说明
规则：
- 直接引文尽量附页码或章节锚点
- 页码不稳定时明确说明
- 综合归纳写清来源章节
- 书外补充明确标成“补充说明”
- 无法溯源的内容不要写成确定事实
语言
- 默认中文输出
- 保留原文术语、专有名词、关键引文
- 重要术语首次出现建议写成：
中文（Original Term）