Deep Reading Skill

交互式PDF逐行阅读器，支持块级/行级翻页、跳转、搜索、书签等功能。

触发方式

当用户想要阅读PDF文档、通过指令控制阅读进度时使用此skill。

功能

• 📖 打开PDF: 加载PDF文件并开始阅读
• ➡️ 下一句: 读取下一块/行内容
• ⬅️ 上一句: 返回上一块/行
• 🔄 重读: 重新读取当前内容
• 📑 跳转: 支持页码跳转、块跳转
• 🔍 搜索: 关键词全文搜索
• 🔖 书签: 添加和管理书签
• 📊 进度: 显示阅读进度

指令列表

使用示例

用户: 列出PDF
助手: 📚 当前 Workspace 可读 PDF 索引
     路径: /path/to/workspace-e
     ━━━━━━━━━━━━━━━━━━━━━━━━
     共 3 个 PDF：
      1. docs/report.pdf
      2. papers/paper.pdf
     💡 使用「开始读 1」或「开始读 report.pdf」打开

用户: 开始读 /home/docs/report.pdf
助手: 📄 第1页 · 块1/50 · [██░░░░░░░] 4%
     ━━━━━━━━━━━━━━━━━━━━━━━━
     第一章 项目概述
     
     本报告主要介绍...

用户: 下一句
助手: 📄 第1页 · 块2/50 · [██░░░░░░░] 6%
     ━━━━━━━━━━━━━━━━━━━━━━━━
     
     1.1 项目背景...

用户: 去第5页
助手: 📄 第5页 · 块20/50 · [████░░░░░] 40%
     ━━━━━━━━━━━━━━━━━━━━━━━━
     第二章 技术方案...

实现细节

核心模块

pdf-reader/
├── __init__.py         # 主入口
├── reader/
│   ├── types.py        # 类型定义
│   ├── exceptions.py   # 异常类
│   ├── blocks.py       # 数据类
│   ├── parser.py       # PDF解析引擎
│   ├── state.py        # 状态管理
│   └── cache.py        # 缓存管理
├── commands/
│   └── navigation.py   # 导航指令
└── ui/
    └── formatter.py   # 输出格式化

MVP 范围

• ✅ 可搜索PDF（非扫描件）
• ✅ 单栏布局
• ✅ 无页数限制（按需解析+落盘）
• ✅ 块级翻页
• ✅ 页码跳转
• ✅ 进度显示
• ✅ 书签（按 PDF 持久化）

技术依赖

• pdfplumber: 文本/表格提取
• PyMuPDF: 图片提取

模板与 Agent LLM 加工

• 块级导航：下一句 按块（paragraph）推进
• 模板：用户可 模板 定义、模板 使用，skill 不调用 LLM
• Structured Payload：当使用非默认模板时，skill 在输出末尾附加 [PDF_READER_TEMPLATE_PAYLOAD] 块，内含 template_prompt、original、page、block_id
• Agent 职责：解析该 payload 后，由 Agent 调用 LLM 按 template_prompt 对 original 加工（如 原文/翻译/解读），将 LLM 输出呈现给用户

存储结构

每个 PDF 有独立目录（~/.cache/pdf-reader/{hash}/），包含：

• index.json - 索引（total_pages, page_offsets）
• p1.json, p2.json ... - 各页块数据
• state.json - 阅读进度
• bookmarks.json - 书签

注意事项

1. MVP版本不支持扫描件PDF（需要OCR）
2. MVP版本不支持多栏布局
3. 大文件可能需要较长的初始加载时间
4. 书签与解析结果、进度均按 PDF 分目录保存，切换 PDF 即切换目录

PDF 文本提取说明

提取模式

PDF Reader 支持两种文本提取模式：

文本模式

• 适用于：大多数正常 PDF
• 优点：速度快
• 问题：部分 PDF（老版本 LaTeX 生成）文本流没有空格

OCR 模式

• 适用于：扫描件PDF、文本提取有问题的 PDF
• 优点：识别准确
• 缺点：速度较慢
• 需要安装 tesseract：

  # macOS
  brew install tesseract
  
  # Ubuntu
  sudo apt install tesseract-ocr
  

使用示例

用户: 模式 ocr
助手: ✅ 已切换到 ocr 模式

用户: 开始读 xxx.pdf
助手: (使用 OCR 提取文本...)

技术实现

• text_enhance.py：文本后处理模块
  • enhance_text() - 智能添加空格
  • is_scanned_pdf() - 检测是否为扫描件
• parser.py：
  • _extract_blocks() - 文本提取
  • _extract_blocks_ocr() - OCR 提取