pdf-text-extractor

PDF 文本提取器

触发条件与路由

• 触发条件：PDF 下载、全文、提取文本、论文/PDF、全文抽取、下载 PDF。
• 适用场景：queries.md 设置了 evidence_mode: fulltext（或你明确需要全文证据），并希望为论文笔记/主张提供更有力的证据。

也可以收集全文片段，以获取比摘要更深入的证据。

此技能有意保持保守：在许多综述任务中，摘要/片段模式就已足够，还能避免大量下载。

输入

• papers/core_set.csv（需要包含 paper_id、title，最好还包含 pdf_url/arxiv_id/url）
• 可选：outline/mapping.tsv（用于优先处理已映射的论文）

输出

• papers/fulltext_index.jsonl（每篇尝试处理的论文对应一条记录）
• 附带产物：
  • papers/pdfs/<paper_id>.pdf（缓存的下载文件）
  • papers/fulltext/<paper_id>.txt（提取出的文本）

决策：证据模式

• queries.md 可以设置 evidence_mode: "abstract" | "fulltext"。
  • abstract（默认模板）：不要下载；生成索引，并清楚记录跳过原因。
  • fulltext：下载 PDF（如果可行），并将文本提取到 papers/fulltext/。

本地 PDF 模式

无法或不应下载 PDF 时（网络受限、触发速率限制或没有权限），请手动提供 PDF，并以“仅本地 PDF”模式运行。

• PDF 命名约定：papers/pdfs/<paper_id>.pdf，其中 <paper_id> 与 papers/core_set.csv 中的值一致。
• 在 queries.md 中设置 - evidence_mode: "fulltext"。
• 运行：uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace> --local-pdfs-only

如果缺少 PDF，脚本会生成待办清单：

• output/MISSING_PDFS.md（人类可读的摘要）
• papers/missing_pdfs.csv（机器可读的列表）

工作流（启发式）

1. 读取 papers/core_set.csv。
2. 如果存在 outline/mapping.tsv，优先处理已映射的论文。
3. 对每篇选定的论文（全文模式）：
   • 确定 pdf_url（优先使用 pdf_url；否则尽可能根据 arxiv_id/url 推导）
   • 如果缺少文件，则下载到 papers/pdfs/<paper_id>.pdf
   • 提取适量的文本前缀到 papers/fulltext/<paper_id>.txt
   • 在 papers/fulltext_index.jsonl 中追加/更新一条 JSONL 记录，包含状态和统计信息
4. 除非明确要求，否则不要覆盖已提取的文本（删除 .txt 文件即可重新提取）。

质量检查清单

• papers/fulltext_index.jsonl 存在且非空。
• 如果 evidence_mode: "fulltext"：至少有一小部分论文提取到了文本（严格模式下，提取覆盖率接近零会导致任务受阻）。
• 如果 evidence_mode: "abstract"：索引涵盖 papers/core_set.csv 中的每篇论文，并且每条记录都明确标记为 skip_mode_abstract（未尝试下载）。fulltext_max_papers 不会截断这个零下载索引。

脚本

快速开始

• uv run python .codex/skills/pdf-text-extractor/scripts/run.py --help
• uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace>

所有选项

• --max-papers <n>：限制处理的论文数量（可由 queries.md 覆盖）
• --max-pages <n>：每个 PDF 最多提取 N 页
• --min-chars <n>：计为正常所需的最少提取字符数
• --sleep <sec>：下载间隔时间
• --local-pdfs-only：不下载；仅使用已存在的 papers/pdfs/<paper_id>.pdf
• queries.md 支持：evidence_mode、fulltext_max_papers、fulltext_max_pages、fulltext_min_chars

示例

• 摘要模式（不下载文件）：
  • 在 queries.md 中设置 - evidence_mode: "abstract"，然后运行脚本（脚本会生成包含跳过状态的 papers/fulltext_index.jsonl）
• 仅使用本地 PDF 的全文模式：
  • 在 queries.md 中设置 - evidence_mode: "fulltext"，将 PDF 放在 papers/pdfs/ 下，然后运行：uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace> --local-pdfs-only
• 使用较小预算的全文模式：
  • uv run python .codex/skills/pdf-text-extractor/scripts/run.py --workspace <workspace> --max-papers 20 --max-pages 4 --min-chars 1200

注意事项

• 下载的文件会缓存在 papers/pdfs/ 下；提取的文本会缓存在 papers/fulltext/ 下。
• 除非删除 .txt 文件，否则脚本不会覆盖现有的提取文本。

故障排除

问题：没有可供下载的 PDF

解决方法：

• 使用 evidence_mode: abstract（默认值），或将本地 PDF 放在 papers/pdfs/ 下，并使用 --local-pdfs-only 重新运行。

问题：提取的文本为空或乱码

解决方法：

• 如果支持，尝试更换提取后端；否则将论文的证据级别标记为 abstract，避免提出有力的全文主张。