tech-book-extractor-skills 1.0.6 → 1.0.8

package/README.md

@@ -2,30 +2,61 @@
 
 Claude Code 技能：技术书深度萃取——两阶段流水线。
 
-## 结构
+## 安装
 
-| 阶段 | 文件 | 职责 |
-|------|------|------|
-| Stage 1 | [stage1/skill-stage1-structure-parser.md](stage1/skill-stage1-structure-parser.md) | 全书骨架解析：标注 type/weight/complexity/keyQuestions/outdatedRisks/阅读路线 |
-| Stage 2 | [stage2/skill-stage2-chapter-extractor.md](stage2/skill-stage2-chapter-extractor.md) | 单章深度萃取：六层结构 + 复杂热点深度脚手架 |
+```bash
+npx tech-book-extractor-skills
+```
 
-## 安装（Agent Skill）
+**更新：**
 
 ```bash
-npx tech-book-extractor-skills
+npx tech-book-extractor-skills@latest
 ```
 
-安装完成后即可使用 `/tech-book-stage1` 和 `/tech-book-stage2`。
+## 使用
+
+### 日常工作流：只用 `/chapter-drill`
+
+```
+/chapter-drill 书文件路径.epub 第三章
+```
+
+一步完成。首次使用时会自动在后台生成知识骨架（透明），后续章节直接复用。不需要手动跑 `/book-map`。
+
+### 可选：`/book-map` — 单独校对骨架
 
-**更新到最新版本：**
+如果想要调整某章的权重、过时标注或阅读路线后再萃取：
+
+```
+/book-map 书文件路径.epub
+```
+
+骨架生成后可手动编辑 `stage1-skeleton.json`，然后 `/chapter-drill` 会读取你的改动。
+
+### 示例
 
 ```bash
-npx tech-book-extractor-skills@latest
+# 直接钻，骨架第一次自动建
+/chapter-drill ~/books/jvm.epub 第二章
+
+# 钻完继续钻，骨架复用
+/chapter-drill ~/books/jvm.epub 第三章
+
+# 偶尔跑一下，校对骨架内容
+/book-map ~/books/jvm.epub
 ```
 
+## 命令
+
+| 命令 | 日常使用频率 | 职责 |
+|------|------------|------|
+| `/chapter-drill` | ⭐⭐⭐ 每次都跑 | 单章萃取 + 自动建骨架。complexity=high 的小节深度脚手架 |
+| `/book-map` | ⭐ 校对时跑 | 显式重建全书骨架，方便手动调整元数据后提升萃取质量 |
+
 ## 设计思路
 
-- **Stage 1 画地图**——读整本书之前，先标注知识价值分布，聚焦高权重章节
+- **Stage 1 画地图**——标注知识价值分布，聚焦高权重章节
 - **Stage 2 搭脚手架**——复杂小节（如 ZGC 染色指针）不精炼提纯，而是分步拆解：做了什么 → 为什么需要 → 不这样做会怎样
-- **复杂度客观检测**——用小节长度、脚注密度、跨章引用数自动判定 complexity，不依赖 LLM 主观判断
-- **一套模板 + 增量**——六层输出格式统一，complexity=high 的小节在心智模型层追加分步拆解，不断开新模板
+- **复杂度客观检测**——小节长度、脚注密度、跨章引用数 → 自动判定 complexity，不靠 LLM 主观判断
+- **一套模板 + 增量**——六层格式统一，complexity=high 仅在心智模型层追加分步拆解

package/bin/install.js

@@ -39,4 +39,12 @@ const scannerDest = path.join(scriptsDest, "complexity_scanner.py");
 fs.copyFileSync(scriptsSrc, scannerDest);
 console.log(`✓ script: complexity_scanner.py → ${scannerDest}`);
 
+// 复制 PDF 文本提取脚本
+const scriptsDir = path.join(__dirname, "..", "scripts");
+for (const pyScript of ["pdf_extract_utils.py", "extract_book.py", "extract_chapter.py"]) {
+  const dest = path.join(scriptsDest, pyScript);
+  fs.copyFileSync(path.join(scriptsDir, pyScript), dest);
+  console.log(`✓ script: ${pyScript} → ${dest}`);
+}
+
 console.log(`\n${skills.length} skill(s) installed.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tech-book-extractor-skills",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Claude Code skills for deep technical book reading — structure parsing (Stage 1) and chapter extraction (Stage 2).",
   "bin": {
     "tech-book-extractor-skills": "bin/install.js"
@@ -8,7 +8,10 @@
   "files": [
     "skills/",
     "bin/",
-    "stage1/complexity_scanner.py"
+    "stage1/complexity_scanner.py",
+    "scripts/pdf_extract_utils.py",
+    "scripts/extract_book.py",
+    "scripts/extract_chapter.py"
   ],
   "scripts": {
     "install-skills": "node bin/install.js",

package/scripts/extract_book.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env python3
+"""
+extract_book.py — 整本书文本提取脚本
+=======================================
+直接从 PDF 文字层提取全书文本（不需要 OCR/GPU），输出 Markdown 文件，
+可直接喂给 book-map skill（Mode B）。
+
+原理：PyMuPDF 直接读取 PDF 内嵌的文本层，和 PDF 阅读器里 Ctrl+C 一样。
+      对扫描件 PDF（文字层为空），脚本会检测并提示。
+
+用法：
+  python extract_book.py ./深入理解Java虚拟机.pdf
+  python extract_book.py ./book.pdf --output ./note/book/
+  python extract_book.py ./book.pdf --max-pages 20   # 测试用
+  python extract_book.py ./book.pdf --export-images    # 同时导出嵌入图片
+
+输出：
+  {output_dir}/{书名}/{书名}-fulltext.md
+  {output_dir}/{书名}/images/          # 仅 --export-images 时
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from pdf_extract_utils import (
+    pdf_page_count,
+    extract_pages,
+    save_results,
+    extract_book_name,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="整本书文本提取 — 从 PDF 文字层直接提取，对接 book-map skill",
+        epilog="注意：仅适用于文字版 PDF（排版导出的），扫描件 PDF 请用 OCR 工具。",
+    )
+    parser.add_argument("pdf", help="PDF 文件路径")
+    parser.add_argument(
+        "--output", "-o", default="./note/book/",
+        help="输出根目录（默认: ./note/book/）",
+    )
+    parser.add_argument(
+        "--max-pages", type=int, default=0,
+        help="最多处理多少页（0=全部，用于测试）",
+    )
+    parser.add_argument(
+        "--start-page", type=int, default=1,
+        help="起始页码（1-based，默认: 1）",
+    )
+    parser.add_argument(
+        "--export-images", action="store_true",
+        help="同时导出 PDF 中的嵌入图片到 images/ 目录",
+    )
+    args = parser.parse_args()
+
+    pdf_path = Path(args.pdf)
+    if not pdf_path.exists():
+        sys.exit(f"❌ PDF 文件不存在: {pdf_path}")
+
+    # 书名 & 输出路径
+    book_name = extract_book_name(pdf_path.name)
+    output_dir = Path(args.output) / book_name
+    output_path = output_dir / f"{book_name}-fulltext.md"
+    image_dir = str(output_dir / "images") if args.export_images else ""
+
+    # 页码范围
+    total_pages = pdf_page_count(pdf_path)
+    end_page = total_pages
+    if args.max_pages > 0:
+        end_page = min(args.start_page + args.max_pages - 1, total_pages)
+
+    print(f"📖 {book_name}")
+    print(f"   总页数: {total_pages}")
+    print(f"   处理范围: 第 {args.start_page}-{end_page} 页")
+    print(f"   输出: {output_path}")
+    if args.export_images:
+        print(f"   图片: {image_dir}/")
+    print()
+
+    # 提取
+    print(f"🔍 提取文本 ({end_page - args.start_page + 1} 页) ...")
+    results = extract_pages(
+        pdf_path,
+        page_range=(args.start_page, end_page),
+        export_images=args.export_images,
+        image_dir=image_dir,
+    )
+
+    # 保存
+    save_results(results, output_path, title=book_name)
+
+    # 下一步提示
+    print(f"""
+📎 下一步 — 生成知识骨架:
+   用 book-map skill，选择 Mode B（全书全文），把以下文件内容贴进去：
+   {output_path.resolve()}
+""")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/extract_chapter.py

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""
+extract_chapter.py — 单章文本提取脚本
+========================================
+从 PDF 中提取指定页码范围的文本，输出 Markdown 文件，
+可直接喂给 chapter-drill skill。
+
+用法：
+  # 提取第 45-78 页（第 3 章）
+  python extract_chapter.py ./book.pdf --pages 45-78 --chapter "ch03"
+
+  # 指定输出目录
+  python extract_chapter.py ./book.pdf --pages 45-78 --chapter "ch03" --output ./note/book/
+
+  # 同时导出嵌入图片
+  python extract_chapter.py ./book.pdf --pages 45-78 --chapter "ch03" --export-images
+
+输出：
+  {output_dir}/{书名}/chapters/{chapter_id}-raw.md
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from pdf_extract_utils import (
+    pdf_page_count,
+    extract_pages,
+    save_results,
+    extract_book_name,
+    parse_page_range,
+)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="单章文本提取 — 从 PDF 提取指定页码范围，对接 chapter-drill skill",
+    )
+    parser.add_argument("pdf", help="PDF 文件路径")
+    parser.add_argument(
+        "--pages", required=True,
+        help="页码范围，如 '45-78' 或 '45'（单页）",
+    )
+    parser.add_argument(
+        "--chapter", "-c", default="",
+        help="章节标识，如 'ch03'。输出文件名: ch03-raw.md",
+    )
+    parser.add_argument(
+        "--output", "-o", default="./note/book/",
+        help="输出根目录（默认: ./note/book/）",
+    )
+    parser.add_argument(
+        "--export-images", action="store_true",
+        help="同时导出 PDF 中的嵌入图片到 images/ 目录",
+    )
+    args = parser.parse_args()
+
+    pdf_path = Path(args.pdf)
+    if not pdf_path.exists():
+        sys.exit(f"❌ PDF 文件不存在: {pdf_path}")
+
+    # 页码范围
+    page_start, page_end = parse_page_range(args.pages)
+    if page_start > page_end:
+        page_start, page_end = page_end, page_start
+
+    total_pages = pdf_page_count(pdf_path)
+    if page_end > total_pages:
+        print(f"⚠️  页码范围超出（PDF 共 {total_pages} 页），自动截断")
+        page_end = total_pages
+
+    # 章节标识
+    chapter_id = args.chapter if args.chapter else f"p{page_start}-{page_end}"
+
+    # 书名 & 输出路径
+    book_name = extract_book_name(pdf_path.name)
+    output_dir = Path(args.output) / book_name / "chapters"
+    output_path = output_dir / f"{chapter_id}-raw.md"
+    image_dir = str(Path(args.output) / book_name / "images") if args.export_images else ""
+
+    page_count = page_end - page_start + 1
+    print(f"📖 {book_name}")
+    print(f"   章节: {chapter_id}  (第 {page_start}-{page_end} 页, 共 {page_count} 页)")
+    print(f"   输出: {output_path}")
+    print()
+
+    # 提取
+    print(f"🔍 提取文本 ({page_count} 页) ...")
+    results = extract_pages(
+        pdf_path,
+        page_range=(page_start, page_end),
+        export_images=args.export_images,
+        image_dir=image_dir,
+    )
+
+    # 保存
+    chapter_title = f"{book_name} · {chapter_id}"
+    save_results(results, output_path, title=chapter_title)
+
+    # 下一步提示
+    print(f"""
+📎 下一步 — 深度萃取:
+   用 chapter-drill skill，将以下文件内容作为章节全文输入：
+   {output_path.resolve()}
+
+   同时提供 Stage 1 骨架片段（type, weight, keyQuestions 等）。
+""")
+
+
+if __name__ == "__main__":
+    main()

package/scripts/pdf_extract_utils.py

@@ -0,0 +1,540 @@
+"""
+PDF 文本提取工具库 — 直接读取 PDF 文本层，不依赖 OCR/GPU
+==========================================================
+为 extract_book.py 和 extract_chapter.py 提供共享能力：
+  - 文本提取（PyMuPDF fitz.get_text，CPU 毫秒级）
+  - 表格区域检测（基于文字坐标的网格分析）
+  - 嵌入图片导出（标记不可读内容）
+  - 结果汇总与输出格式化
+
+原理：大多数技术书 PDF 是排版软件导出的，内嵌文字层。
+      PyMuPDF 直接读取这层文字，和 Ctrl+C 一个原理。
+      对扫描件 PDF（全图片），文字层为空，脚本会检测并提示。
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import sys
+import time
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+# ═══════════════════════════════════════════════════════════════════
+# 数据结构
+# ═══════════════════════════════════════════════════════════════════
+
+@dataclass
+class TextBlock:
+    """PDF 中的一个文本块（段落/标题/单元格）"""
+    text: str
+    x0: float
+    y0: float
+    x1: float
+    y1: float
+    block_type: str = ""   # "text" | "image"
+    font_size: float = 0.0
+    font_name: str = ""
+
+
+@dataclass
+class PageResult:
+    """单页提取结果"""
+    page_num: int                         # 页码（1-based）
+    text: str                             # 提取的文本
+    tables: list[TableRegion] = field(default_factory=list)   # 检测到的表格
+    image_count: int = 0                  # 嵌入图片数
+    has_text_layer: bool = True           # 是否有文字层
+    elapsed: float = 0.0                  # 耗时（秒）
+
+
+@dataclass
+class TableRegion:
+    """检测到的表格区域"""
+    y_start: float
+    y_end: float
+    rows: int              # 估计行数
+    cols: int              # 估计列数
+    raw_text: str = ""     # 从该区域提取的原始文本
+    page_num: int = 0
+
+
+# ═══════════════════════════════════════════════════════════════════
+# PDF 工具
+# ═══════════════════════════════════════════════════════════════════
+
+def pdf_page_count(pdf_path: str | Path) -> int:
+    """返回 PDF 总页数"""
+    import fitz
+    doc = fitz.open(str(pdf_path))
+    count = len(doc)
+    doc.close()
+    return count
+
+
+def _group_blocks_by_line(blocks: list[TextBlock], y_tolerance: float = 4.0) -> list[list[TextBlock]]:
+    """
+    将文本块按 y 坐标分组为"行"。
+    同一行内 block 按 x 坐标从左到右排序。
+    """
+    if not blocks:
+        return []
+
+    # 按 y 排序
+    sorted_blocks = sorted(blocks, key=lambda b: (b.y0, b.x0))
+
+    lines: list[list[TextBlock]] = []
+    current_line: list[TextBlock] = [sorted_blocks[0]]
+
+    for block in sorted_blocks[1:]:
+        # 如果 y0 和上一行的平均 y0 接近，属于同一行
+        avg_y = sum(b.y0 for b in current_line) / len(current_line)
+        if abs(block.y0 - avg_y) < y_tolerance:
+            current_line.append(block)
+        else:
+            lines.append(sorted(current_line, key=lambda b: b.x0))
+            current_line = [block]
+
+    lines.append(sorted(current_line, key=lambda b: b.x0))
+    return lines
+
+
+def _detect_tables(blocks: list[TextBlock]) -> list[TableRegion]:
+    """
+    基于文本块坐标检测表格区域。
+
+    表格特征：
+    1. 多行文本的 x 坐标在列方向上对齐（形成网格）
+    2. 行间距均匀（和正文段落的分隔模式不同）
+    3. 单行内多个独立 block（多列）
+
+    返回检测到的表格区域列表。
+    """
+    if len(blocks) < 4:  # 至少 2 行 × 2 列才有表格意义
+        return []
+
+    # 过滤掉太小的块（可能是页码、页眉）
+    text_blocks = [b for b in blocks if len(b.text.strip()) > 1]
+    if len(text_blocks) < 4:
+        return []
+
+    lines = _group_blocks_by_line(text_blocks, y_tolerance=5.0)
+
+    tables: list[TableRegion] = []
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+        # 单行有 ≥2 个对齐的 block → 可能是表格行
+        if len(line) >= 2:
+            # 向后扫描，看有多少连续行有相同数量的 block（列数一致）
+            table_lines = [line]
+            col_count = len(line)
+            j = i + 1
+            while j < len(lines) and len(lines[j]) >= 2:
+                # 检查列宽是否大致对齐
+                if _columns_aligned(table_lines[-1], lines[j], tolerance=10.0):
+                    table_lines.append(lines[j])
+                    j += 1
+                else:
+                    break
+
+            if len(table_lines) >= 2:  # 至少 2 行才算表格
+                y0 = min(b.y0 for line in table_lines for b in line)
+                y1 = max(b.y1 for line in table_lines for b in line)
+                # 聚合表格内所有文本（按行组织）
+                raw = ""
+                for tl in table_lines:
+                    cells = [b.text.strip() for b in tl]
+                    raw += " | ".join(cells) + "\n"
+                tables.append(TableRegion(
+                    y_start=y0,
+                    y_end=y1,
+                    rows=len(table_lines),
+                    cols=col_count,
+                    raw_text=raw.strip(),
+                ))
+                i = j
+                continue
+        i += 1
+
+    # 去重：合并重叠的表格区域
+    return _merge_overlapping_tables(tables)
+
+
+def _columns_aligned(line_a: list[TextBlock], line_b: list[TextBlock], tolerance: float = 10.0) -> bool:
+    """
+    检查两行文本的列是否对齐。
+    比较每列的 x0 坐标是否在容差范围内。
+    """
+    if len(line_a) != len(line_b):
+        return False
+    for ba, bb in zip(line_a, line_b):
+        if abs(ba.x0 - bb.x0) > tolerance:
+            return False
+    return True
+
+
+def _merge_overlapping_tables(tables: list[TableRegion]) -> list[TableRegion]:
+    """合并 y 范围有重叠的表格检测结果"""
+    if len(tables) <= 1:
+        return tables
+    sorted_tables = sorted(tables, key=lambda t: t.y_start)
+    merged = [sorted_tables[0]]
+    for t in sorted_tables[1:]:
+        last = merged[-1]
+        if t.y_start <= last.y_end + 10:  # 允许小间隙
+            last.y_end = max(last.y_end, t.y_end)
+            last.rows = max(last.rows, t.rows)
+            last.cols = max(last.cols, t.cols)
+            last.raw_text += "\n" + t.raw_text
+        else:
+            merged.append(t)
+    return merged
+
+
+# ═══════════════════════════════════════════════════════════════════
+# 核心：单页提取
+# ═══════════════════════════════════════════════════════════════════
+
+def extract_page(
+    page,
+    page_num: int,
+    export_images: bool = False,
+    image_dir: str = "",
+) -> PageResult:
+    """
+    提取单个 PDF 页面的文本、表格和图片信息。
+
+    Args:
+        page: PyMuPDF Page 对象
+        page_num: 页码（1-based）
+        export_images: 是否导出嵌入图片
+        image_dir: 图片导出目录
+
+    Returns:
+        PageResult
+    """
+    import fitz
+
+    t0 = time.time()
+
+    # 1. 提取文本（dict 模式，保留坐标）
+    text_dict = page.get_text("dict")
+    blocks_raw = text_dict.get("blocks", [])
+
+    # 2. 提取嵌入图片
+    image_count = 0
+    image_refs: list[str] = []
+    try:
+        image_list = page.get_images(full=True)
+        for img_idx, img_info in enumerate(image_list):
+            image_count += 1
+            if export_images and image_dir:
+                xref = img_info[0]
+                base_image = page.parent.extract_image(xref)
+                if base_image:
+                    ext = base_image["ext"]
+                    img_path = os.path.join(image_dir, f"p{page_num:04d}_img{img_idx+1}.{ext}")
+                    os.makedirs(os.path.dirname(img_path), exist_ok=True)
+                    with open(img_path, "wb") as f:
+                        f.write(base_image["image"])
+                    image_refs.append(img_path)
+    except Exception:
+        pass  # 某些 PDF 图片提取可能失败，不阻塞流程
+
+    # 3. 分离文本块和图片块
+    text_blocks: list[TextBlock] = []
+    for block in blocks_raw:
+        if block.get("type") == 0:  # 文本块
+            for line in block.get("lines", []):
+                line_text = ""
+                x0, y0, x1, y1 = float("inf"), float("inf"), 0, 0
+                font_size = 0.0
+                font_name = ""
+                for span in line.get("spans", []):
+                    line_text += span.get("text", "")
+                    bbox = span.get("bbox", (0, 0, 0, 0))
+                    x0 = min(x0, bbox[0])
+                    y0 = min(y0, bbox[1])
+                    x1 = max(x1, bbox[2])
+                    y1 = max(y1, bbox[3])
+                    if span.get("size", 0) > font_size:
+                        font_size = span.get("size", 0)
+                    font_name = span.get("font", "")
+                if line_text.strip():
+                    text_blocks.append(TextBlock(
+                        text=line_text.strip(),
+                        x0=x0, y0=y0, x1=x1, y1=y1,
+                        block_type="text",
+                        font_size=font_size,
+                        font_name=font_name,
+                    ))
+
+    # 4. 检测表格
+    tables = _detect_tables(text_blocks)
+
+    # 5. 构建输出文本
+    # 策略：按 y 坐标从上到下排列文本块，表格区域插入特殊标记
+    has_text = len(text_blocks) > 0
+
+    if not has_text:
+        # 可能是扫描件 PDF — 没有文字层
+        elapsed = time.time() - t0
+        return PageResult(
+            page_num=page_num,
+            text=f"> ⚠️ 本页无文字层，可能是扫描件图片。需要 OCR 才能提取文字。\n",
+            tables=[],
+            image_count=image_count,
+            has_text_layer=False,
+            elapsed=elapsed,
+        )
+
+    # 按 y 坐标排序所有文本块
+    sorted_blocks = sorted(text_blocks, key=lambda b: (b.y0, b.x0))
+
+    # 标记哪些 block 属于表格区域
+    table_block_indices: set[int] = set()
+    for table in tables:
+        for idx, block in enumerate(sorted_blocks):
+            if table.y_start - 5 <= block.y0 <= table.y_end + 5:
+                table_block_indices.add(idx)
+
+    # 生成文本输出
+    output_lines: list[str] = []
+    output_lines.append(f"\n<!-- 第 {page_num} 页 -->\n")
+
+    prev_y = -100
+    prev_was_table = False
+    inside_table = False
+
+    for idx, block in enumerate(sorted_blocks):
+        in_table = idx in table_block_indices
+
+        # 表格区域开始
+        if in_table and not inside_table:
+            inside_table = True
+            # 找到对应的 TableRegion
+            for table in tables:
+                if table.y_start - 5 <= block.y0 <= table.y_end + 5:
+                    output_lines.append(f"\n> 📊 **表格区域**（{table.rows}行 × {table.cols}列）— 建议查阅原书第 {page_num} 页确认结构\n>\n")
+                    # 输出提取的原始文本
+                    for line in table.raw_text.split("\n"):
+                        output_lines.append(f"> | {line}\n")
+                    output_lines.append(f">\n> ⚠️ 上方表格的单元格内容已提取，但行列关系可能不准确\n")
+                    break
+            prev_was_table = True
+            continue
+
+        # 表格区域内的后续行跳过（已在 header 中输出）
+        if in_table and inside_table:
+            prev_y = block.y0
+            continue
+
+        # 离开表格区域
+        if not in_table and inside_table:
+            inside_table = False
+            output_lines.append("\n")
+
+        # 判断是否为标题（字号较大）
+        is_heading = block.font_size >= 14.0 and len(block.text) < 80
+
+        # 段落间距判断
+        if prev_y > 0 and block.y0 - prev_y > 20:
+            output_lines.append("")
+
+        if is_heading and len(block.text) > 2:
+            output_lines.append(f"## {block.text}")
+        else:
+            output_lines.append(block.text)
+
+        prev_y = block.y0
+        prev_was_table = False
+
+    # 6. 图片引用
+    if image_count > 0:
+        output_lines.append(f"\n> 🖼️ 本页含 {image_count} 张嵌入图片，建议查原书\n")
+
+    elapsed = time.time() - t0
+    return PageResult(
+        page_num=page_num,
+        text="".join(output_lines) if output_lines else "",
+        tables=tables,
+        image_count=image_count,
+        has_text_layer=True,
+        elapsed=elapsed,
+    )
+
+
+# ═══════════════════════════════════════════════════════════════════
+# 批量提取
+# ═══════════════════════════════════════════════════════════════════
+
+def extract_pages(
+    pdf_path: str | Path,
+    page_range: Optional[tuple[int, int]] = None,
+    export_images: bool = False,
+    image_dir: str = "",
+    progress_callback=None,
+) -> list[PageResult]:
+    """
+    从 PDF 批量提取页面文本。
+
+    Args:
+        pdf_path: PDF 文件路径
+        page_range: (start, end) 1-based，None 表示全部
+        export_images: 是否导出嵌入图片
+        image_dir: 图片导出目录
+        progress_callback: fn(page_num, status)
+
+    Returns:
+        [PageResult, ...]
+    """
+    import fitz
+
+    doc = fitz.open(str(pdf_path))
+    total = len(doc)
+
+    start = 1
+    end = total
+    if page_range:
+        start, end = page_range
+        start = max(1, start)
+        end = min(total, end)
+
+    results: list[PageResult] = []
+    scan_pages = 0
+
+    for i in range(start - 1, end):
+        page_num = i + 1
+        page = doc[i]
+        result = extract_page(page, page_num, export_images, image_dir)
+        results.append(result)
+
+        if not result.has_text_layer:
+            scan_pages += 1
+
+        if progress_callback:
+            status = "scan" if not result.has_text_layer else "ok"
+            progress_callback(page_num, status)
+        else:
+            flag = " ⚠️ 扫描件" if not result.has_text_layer else ""
+            print(f"  ✓ 第 {page_num} 页 ({result.elapsed:.3f}s){flag}")
+
+    doc.close()
+
+    # 汇总报告
+    if scan_pages > 0:
+        print(f"\n⚠️  {scan_pages}/{len(results)} 页无文字层（可能是扫描件），需要 OCR。")
+        if scan_pages == len(results):
+            print("   这本书似乎是纯扫描件 PDF，建议使用 OCR 工具（如 Unlimited-OCR）处理。")
+
+    return results
+
+
+# ═══════════════════════════════════════════════════════════════════
+# 输出格式化
+# ═══════════════════════════════════════════════════════════════════
+
+def merge_to_markdown(
+    results: list[PageResult],
+    title: str = "",
+) -> str:
+    """
+    将多页提取结果合并为一个 Markdown 文档。
+
+    Args:
+        results: 按页码排序的结果列表
+        title: 文档标题
+
+    Returns:
+        完整的 Markdown 文本
+    """
+    lines = []
+    if title:
+        lines.append(f"# {title}\n")
+
+    # 报告统计
+    total_tables = sum(len(r.tables) for r in results)
+    total_images = sum(r.image_count for r in results)
+    scan_pages = sum(1 for r in results if not r.has_text_layer)
+
+    if total_tables > 0 or total_images > 0 or scan_pages > 0:
+        lines.append("> 📋 **提取报告**\n")
+        if total_tables > 0:
+            lines.append(f"> - 检测到 {total_tables} 个表格区域，建议查原书验证结构\n")
+        if total_images > 0:
+            lines.append(f"> - {total_images} 张嵌入图片无法提取文字\n")
+        if scan_pages > 0:
+            lines.append(f"> - {scan_pages} 页无文字层（扫描件），内容缺失\n")
+        lines.append(">\n")
+
+    for r in results:
+        lines.append(r.text)
+        lines.append("")
+
+    return "\n".join(lines)
+
+
+def save_results(
+    results: list[PageResult],
+    output_path: str | Path,
+    title: str = "",
+) -> str:
+    """
+    保存提取结果为 Markdown 文件。
+
+    Args:
+        results: 提取结果列表
+        output_path: 输出文件路径
+        title: 文档标题
+
+    Returns:
+        实际写入的文件路径
+    """
+    output_path = Path(output_path)
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+
+    markdown = merge_to_markdown(results, title)
+    output_path.write_text(markdown, encoding="utf-8")
+
+    total_ok = sum(1 for r in results if r.has_text_layer)
+    total_time = sum(r.elapsed for r in results)
+    total_tables = sum(len(r.tables) for r in results)
+    total_images = sum(r.image_count for r in results)
+
+    print(f"\n✅ 保存到: {output_path}")
+    print(f"   文字页: {total_ok}/{len(results)}, "
+          f"表格: {total_tables}, 图片: {total_images}, "
+          f"耗时: {total_time:.2f}s")
+
+    return str(output_path)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# 辅助函数
+# ═══════════════════════════════════════════════════════════════════
+
+def extract_book_name(pdf_path: str | Path) -> str:
+    """从 PDF 文件名提取书名（去后缀、去特殊字符）"""
+    name = Path(pdf_path).stem
+    name = re.sub(r"[（(]第?\d+版[）)]", "", name)
+    name = re.sub(r"[:：].*", "", name)
+    return name.strip()
+
+
+def parse_page_range(range_str: str) -> tuple[int, int]:
+    """
+    解析页码范围字符串。
+
+    Examples:
+        "45-78" → (45, 78)
+        "45"    → (45, 45)
+    """
+    parts = range_str.split("-")
+    if len(parts) == 2:
+        return int(parts[0].strip()), int(parts[1].strip())
+    return int(parts[0].strip()), int(parts[0].strip())

package/skills/{tech-book-stage1 → book-map}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: tech-book-stage1
-description: "技术书精读前的知识骨架生成器。当用户想在读书前先画地图、分析章节价值分布、标注权重和阅读路线时激活。触发词：/tech-book-stage1、精读准备、生成骨架、分析这本书的结构。先运行 complexity_scanner.py，再生成 stage1-skeleton.json。"
+name: book-map
+description: "技术书结构解析——生成知识骨架地图。触发词：/book-map、画地图、分析结构。"
 ---
 # 阶段一 Skill：技术书结构解析器
 
@@ -10,6 +10,21 @@ description: "技术书精读前的知识骨架生成器。当用户想在读书
 
 ---
 
+## Step -1：从 PDF 提取文本（如有 PDF）
+
+如果手头是 PDF 而非纯文本，先用提取脚本拿到全书原文：
+
+```bash
+# 全书提取 → 输出 {书名}-fulltext.md
+python ~/.claude/scripts/extract_book.py ./你的书.pdf --output ./
+
+# 测试：只看前 20 页
+python ~/.claude/scripts/extract_book.py ./你的书.pdf --max-pages 20
+```
+
+> 原理：PyMuPDF 直接读取 PDF 文字层（和 Ctrl+C 一样），不需要 GPU/OCR。
+> 扫描件 PDF 无文字层，脚本会检测并提示。
+
 ## Step 0：运行预处理脚本（必须先做）
 
 ```bash

package/skills/{tech-book-stage2 → chapter-drill}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: tech-book-stage2
-description: "技术书章节深度萃取器。当用户想精读某章节、把内容读薄提炼为可用知识时激活。需要 Stage 1 骨架作为输入。触发词：/tech-book-stage2、萃取这章、精读这章、深度提炼。输出六层结构的 Markdown 笔记。"
+name: chapter-drill
+description: "技术书章节深度萃取——把一章钻透。自动生成骨架（如需要）。触发词：/chapter-drill、钻读、萃取。"
 ---
 # 阶段二 Skill：技术书章节深度萃取器
 
@@ -8,11 +8,24 @@ description: "技术书章节深度萃取器。当用户想精读某章节、把
 
 ---
 
+## 前置步骤：从 PDF 提取单章文本
+
+如果章节原文在 PDF 里，先用提取脚本拿到文字：
+
+```bash
+# 提取第 45-78 页（如第 3 章）
+python ~/.claude/scripts/extract_chapter.py ./你的书.pdf --pages 45-78 --chapter "ch03" --output ./
+```
+
+输出 `{书名}/chapters/ch03-raw.md`，可直接作为下方「章节全文」输入。
+
+---
+
 ## 输入
 
 | 字段 | 来源 | 说明 |
 |------|------|------|
-| 章节全文 | 用户提供 | 单章完整原文 |
+| 章节全文 | 用户提供（或 `extract_chapter.py` 产出） | 单章完整原文 |
 | 章节骨架 | Stage 1 产出 | 本章的 type、weight、keyQuestions、outdatedRisks、prerequisites、subsections.skipIf、subsections.complexity |
 | complexityHotspots | Stage 1 产出 | 全书中 complexity=high 的小节列表，Stage 2 对此类小节启用深度脚手架而非精炼提纯 |
 | 前置章节萃取 | Stage 2 先前产出（可选） | 已处理章节的"关键问答"，用于检测术语引用一致性 |