read-pdfs

read-pdfs

读取 PDF，避免消耗大量 token。直接将 PDF 放进上下文会很费 token，而且其中往往大部分是图像。此工具只需将 PDF 转换一次，即可生成 Markdown 工作区，其中的文本读取成本低；原本放有图像／图形／图表的位置会留下占位符，并且只会渲染任务实际需要查看视觉内容的页面。

思路

1. 只需导入一次 → pdf_to_markdown.py 会为每个 PDF 创建一个工作区文件夹（原文件 + .md + manifest.json）。
2. 阅读 Markdown → 所有文本、标题和表格都在其中；图像会显示为占位符标记，例如 🖼 [[fig:p4:1]]。
3. 按需渲染 → 只有在确实需要查看图形的实际像素时，才将对应页面渲染为 PNG 并读取。

这样做的好处是：token 成本取决于你查看的内容，而不是 PDF 的大小。

前置条件

这些脚本需要 pymupdf4llm 和 pymupdf。如果运行时提示缺少模块，请安装：

pip install -r requirements.txt

优先使用 pymupdf4llm（它会生成结构化 Markdown，并标记图像位置）。如果未安装，转换器会退回到纯文本提取并说明情况——仍然可用，但结构会较少。

运行脚本。 请使用此工具安装位置的完整路径调用脚本（只有当前目录是工具根目录时，裸路径 scripts/... 才有效）。在 Windows／PowerShell 上，路径中包含空格时请用双引号括起来：

python "<skill-dir>/scripts/pdf_to_markdown.py" "path/to/report.pdf"

转换完成后，包含绝对路径的精确渲染命令会写入转换后文件的前置元数据中；请直接从那里复制，不要自行重新拼写。

工作流

复制此清单并跟踪进度：

- [ ] Step 1: Ingest the PDF  (run pdf_to_markdown.py)
- [ ] Step 2: Read the .md    (text, tables, figure index, placeholders)
- [ ] Step 3: Render a page   (only when a visual must be seen, then Read the PNG)

步骤 1 — 导入 PDF

对 PDF 运行转换器。它会创建一个以文件名命名的干净工作区文件夹：

python "<skill-dir>/scripts/pdf_to_markdown.py" "path/to/report.pdf"

默认情况下，以下内容会生成在 PDF 所在目录旁边：

report/
├── report.pdf        # the original, copied in (workspace is self-contained)
├── report.md         # Markdown + YAML front matter + image placeholders
└── manifest.json     # structured record of what's in the .md vs the original

实用标志：--out-dir DIR（将工作区放到其他位置）、--force（覆盖现有工作区）、--move（移动原文件，而不是复制）、--dpi N（前置元数据中记录的默认渲染 DPI）。脚本会打印一份 JSON 摘要，其中包含工作区路径和精确的渲染命令——请保留它。

如果工作区已在之前的运行中创建，请勿重新转换；只需读取现有的 .md。

步骤 2 — 阅读 Markdown

读取 report/report.md。文件开头是前置元数据（页数、图形／表格数量、渲染命令），以及一个**“图形和图像索引”**表，将每个占位符对应到所在页面及说明文字。后面是页面正文，每页对应一个 ## Page N 小节，表格以 Markdown 格式呈现，视觉内容则显示为行内占位符。

对于大多数问题——摘要、引文、表格数据、“在哪里讨论了 X”——仅凭 Markdown 就足够了。请根据其中内容作答并注明页码。

步骤 3 — 仅在需要查看视觉内容时渲染页面

如果任务确实需要查看图形、图表、示意图、照片或扫描页面（而不只是阅读其说明文字），请在 .md 中找到对应的占位符，从标记中读取页码，渲染该页面，然后读取生成的 PNG：

python "<skill-dir>/scripts/render_page.py" "path/to/report" 4

render_page.py 接受工作区文件夹（或直接的 .pdf 路径）以及从 1 开始计数的页面范围：4、3-5、1,4,7 或 2-3,9。它会写入 report/pages/[email protected]，缓存该文件并打印路径。然后读取该 PNG 以查看页面。

只有标记中的 p<N> 部分表示页码；末尾的 :n 仅用于区分同一页面上的多个视觉内容。对于 [[fig:p4:2]]，请渲染第 4 页。

**反馈循环：**如果小字或密集图表难以辨认，请使用更高分辨率重新渲染，例如 --dpi 220（或 300）。快速浏览时，--dpi 100 成本更低。

占位符一览

• 🖼 [[fig:p4:1]] — image (~300×180) not shown; render page 4 to view. — 第 4 页该位置的一张图片/插图。图注通常紧接在下一行，并显示在插图索引中。
• ⚠ [[fig:p3:1]] — scanned / image-only page; render page 3 to read. — 几乎没有/没有可提取的文本；渲染页面后即可阅读。
• 标记格式为 [[fig:p<page>:<n>]]。要列出所有视觉内容，请在 .md 中搜索 [[fig:，或查看 front-matter 中的插图索引。

完整的占位符规范和解析详情：请参阅 references/placeholders.md。

提示

• **多个 PDF：**将每个文件转换到各自的工作区（每个文件一个文件夹）。按页码交叉引用。
• **大型 PDF（数百页）：**仍然只转换一次；阅读 .md 和插图索引，并按需选择性渲染页面。避免“以防万一”渲染大量页面——这会适得其反。
• **扫描版/仅含图像的 PDF：**文本会很少。渲染相关页面并以图像形式阅读。如需使用自动 OCR 而非视觉识别，请参阅 references/conversion-internals.md。
• **不要重新转储 PDF：**创建工作区后，应基于 .md 和指定页面的渲染结果进行操作，而不是将原始 PDF 加载到上下文中。

参考文件

• references/placeholders.md — 占位符标记格式、插图索引、扫描页标记，以及查找/解析方法。
• references/conversion-internals.md — 转换的工作原理、图注/扫描页启发式规则及其可调常量、DPI 指南、OCR、基于 Playwright 的替代渲染方案，以及故障排除（加密/超大 PDF）。