# book-deep-reader **Repository Path**: gzalex78/book-deep-reader ## Basic Information - **Project Name**: book-deep-reader - **Description**: 通读整本 PDF 图书并产出带页码引文的读书报告/书评(支持扫描版 OCR) - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-07 - **Last Updated**: 2026-10-07 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # book-deep-reader · 整本书深度通读 > 把一本几十万字的书拆成若干**互不干扰的小块**分别精读,再**只根据笔记**汇总。 > 全过程任何一步都不把整本书塞进同一个上下文——这是保证忠实度、防止长篇总结中细节编造的核心设计。 一个 WorkBuddy / Claude Code 技能(Skill)。通读整本 PDF 图书,产出**带页码引文的读书报告或书评**,并附可检索的全书文本。支持文字版 PDF 与扫描版 PDF(离线中文 OCR)。 ## 它解决什么问题 直接把整本书丢进上下文,会同时触发长上下文的「中间遗忘」与整体退化,典型症状是: - 细节编造、页码错配、观点张冠李戴 - 结论趋于笼统("全书都在讲××") 本技能用 **Map → Reduce → Verify** 三层结构规避该问题:原始全文只出现在单块精读的子代理上下文里(每次一块),汇总阶段只读结构化笔记(digest),最后用脚本回查引文。 ## 安装 把整个目录克隆/拷贝到所用 Agent 的 skills 目录即可(目录名保持 `book-deep-reader`): | 平台 | skills 目录 | |---|---| | WorkBuddy | `~/.workbuddy/skills/` | | Claude Code | `~/.claude/skills/` | | OpenClaw | `~/.openclaw/skills/` | ```bash git clone https://gitee.com/gzalex78/book-deep-reader.git \ ~/.workbuddy/skills/book-deep-reader ``` ## 用法 在对话里直接提需求即可触发,例如: - "读完整本《××》" - "总结这本书的亮点和不足" - "这本书对我做财务工作有什么帮助" - "帮我写一篇读书分享 / 书评 / 读书笔记" **视角(lens)是参数**:默认通用读者视角;也可以指定领域视角(财务、管理、投资、历史、写作、育儿……),此时只替换「可迁移要点」一节的提炼维度,取证纪律不变。书与视角不匹配时不硬凑,改用通用视角并在报告开头说明。 **两种深度**:通读(默认,覆盖全书)与速读(抽 2–3 个关键章,交付时明确标注未覆盖全书)。 ## 工作流 | 步骤 | 做什么 | 脚本 | |---|---|---| | 0 | 探测页数 / 文字层 / 是否双页合扫 | `scripts/probe_pdf.py` | | 1 | (仅扫描版)全书 OCR,断点续跑 | `scripts/ocr_range.py` | | 2 | 建骨架:目录、章节、页码映射 → `bookmap.json` | — | | 3 | 按 `bookmap.json` 切章,每页带 `[书页 x]` 标记,自动章头对齐检查 | `scripts/split_by_toc.py` | | 4 | 按预算分块(单块 ≤ 3 万字) | `scripts/chunk_check.py plan` | | 5 | 并行子代理精读,每块产出一份 digest | — | | 6 | 只读 digest 汇总成报告 | — | | 7 | 覆盖率 + digest 结构校验 + 引文回查 | `scripts/chunk_check.py` | | 附 | 巨型书(>1000 页)抽样 OCR 定位部卷边界 | `scripts/locate_sections.py` | ``` python scripts/probe_pdf.py python scripts/ocr_range.py --start 1 --end 60 python scripts/split_by_toc.py bookmap.json python scripts/chunk_check.py plan --max-chars 30000 python scripts/chunk_check.py coverage python scripts/chunk_check.py verify-quotes ``` 完整流程、防幻觉设计与实测踩坑见 [`SKILL.md`](SKILL.md)。 ## 依赖与自测 - `chunk_check.py` / `split_by_toc.py` / `selftest.py` 为**纯标准库**,无需安装依赖; - `probe_pdf.py` / `ocr_range.py` 需 `pymupdf`;OCR 另需 `rapidocr-onnxruntime` 与 `Pillow`: ```bash pip install pymupdf rapidocr-onnxruntime ``` 依赖缺失时脚本以受控错误码退出并提示安装命令,不会裸露 traceback。**无 OCR 依赖的扫描版会明确告知无法完成,不会假装读过。** ```bash python scripts/selftest.py # 一键自检(纯标准库、无副作用),改动脚本后必跑 ``` ## 目录结构 ``` book-deep-reader/ ├── SKILL.md 技能主文档(完整流程与设计说明) ├── README.md ├── LICENSE ├── .gitignore ├── scripts/ │ ├── probe_pdf.py PDF 探测 │ ├── ocr_range.py 参数化 OCR,断点续跑 │ ├── locate_sections.py 抽样 OCR 书眉,定位巨书部卷边界 │ ├── split_by_toc.py 按 bookmap.json 切章 + 页码映射 │ ├── chunk_check.py 分块规划 / 覆盖率校验 / 引文回查 │ └── selftest.py 脚本自检(纯标准库、无副作用) ├── references/ │ ├── digest-template.md 子代理精读 prompt 与笔记模板 │ └── report-template.md 最终报告模板 ``` ## 已知坑(摘录) 1. 沙箱内 `multiprocessing` 会被拦(表现为无声停滞)→ OCR 单进程。 2. 长 OCR 先前台测速 20 页,正常再放后台,明显限流退回前台分批。 3. 中间文件放本地盘,不要放 OneDrive / 同步目录。 4. 切章后脚本自动做章头对齐检查,WARN 项必须人工复核页码映射。 5. `verify-quotes` 未命中 ≠ 编造,OCR 字形差异需用宽松关键词逐条复核。 6. digest 文件名必须与 chunk 文件名严格对应,且五小节结构齐全,中途重切块会造成成批误报。 更多见 [`SKILL.md`](SKILL.md) 的「坑」一节。 ## License MIT © 2026 gzalex