paper-prep

# paper-prep — 学术文献预处理流水线 > **核心理念**: 你（AI）是调度器，不是执行者。所有批量逻辑都在 `scripts/doi_pipeline.py` 与 `scripts/paper_prep/` 包里，你只负责：把用户需求翻译成 CLI 命令 → 跑命令 → 读报告 → 解读结果。 > **位置**: 本 skill 位于 `paper-tools/paper-prep/`（与 `pdf-doi-toolkit`、`litrev-extract`、`DeepSeek-OCR` 同级），不属 skill-forge。所有论文工具集中在此。 ## 前置条件检查（每次使用前 MUST） 1. **pdf-doi-toolkit 可 import**（自动定位：`scripts/paper_prep/__init__.py` 向上找 `pdf-doi-toolkit`）： ```bash uv run python -c "import pdf_doi_toolkit; print(pdf_doi_toolkit.__version__)" ``` 2. **DeepSeek-OCR 可用**（仅 --step ocr 时需要）： ```bash ls <paper-tools>/DeepSeek-OCR/ocr_cli.py ``` 3. **目标目录有 PDF**：`ls <article_dir>/*.pdf` 4. **junction 已建立**：本 skill 通过 junction 链接到 `~/.claude/skills/paper-prep`，指向 `paper-tools/paper-prep`。若 scripts/ 下文件不存在说明链接断了，重跑安装命令。 --- ## 目录约定 ``` <article_dir>/ ├── *.pdf # 输入 PDF ├── ocr_output/ # OCR 输出（脚本自动创建） │ ├── {pdf_stem}/ │ │ └── {pdf_stem}.md ├── bib/ # BibTeX 输出 │ ├── {doi_safe}.bib ├── doi_map.json # 匹配结果（机器可读,含 verified/canonical_title/title_sim 字段） ├── doi_match_report.md # 可读报告 ├── verify_report.md # 内容校验报告（verify 阶段产出） └── pipeline_state.json # 阶段状态（断点续跑） ``` **skill 自身结构**（拆分后）： ``` paper-tools/paper-prep/ ├── SKILL.md └── scripts/ ├── doi_pipeline.py # 薄入口:argparse + 编排 └── paper_prep/ # 包 ├── __init__.py # 路径解析 + Windows SSL ├── config.py # 常量 + resolve_llm_config() ├── llm.ini # LLM 默认配置(base/model/timeout,无密钥) ├── llm_verifier.py # LLMVerifier(双通道) ├── title_extractor.py / verify.py / bibtex_fetcher.py / state.py └── steps/ # 每 step 一个模块 ├── step_ocr.py / step_match.py / step_report.py ├── step_verify.py / step_bibtex.py / step_rename.py ``` --- ## LLM 配置（双通道验证用） 双通道验证（`--llm-verify`）需要一个能用的 LLM 端点。配置按优先级链解析（高 → 低），密钥不落版本库： | 优先级 | 来源 | 用途 | |---|---|---| | 1 | `--llm-model` CLI | 只覆盖 model | | 2 | `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL_NAME` 环境变量 | 专名,与 litrev-extract 同名 | | 3 | `scripts/paper_prep/llm.ini` | 默认 base/model/timeout(随版本库) | | 4 | `OPENAI_API_KEY` / `OPENAI_BASE_URL` | 兼容兜底(仅非 Claude 会话) | | 5 | 全无 | WARN 并禁用 LLM 通道,降级为仅余弦 | **为何不用 `OPENAI_*`**: `.claude/settings.json` 全局注入 `OPENAI_API_KEY=PROXY_MANAGED` + 一个对 deepseek/glm 返回 403 的 proxy。在 Claude 会话里,子进程继承这两个值,任何依赖 `OPENAI_*` 的配置默认就连错端点,且静默降级不报错。`LLM_*` 名字干净、与 litrev 的 `LLM_API_KEY` 同名,正好对齐"同一接口"。 **最小可用配置**（只设一个变量即可，base/model 从 ini 取）： ```jsonc // .claude/settings.json 的 env 块 "LLM_API_KEY": "sk-..." ``` ini 默认指向 litrev 用的本地代理 `http://localhost:37183/v1` + `deepseek-v4-flash`。要换端点/模型，改 `llm.ini` 或设 `LLM_BASE_URL`/`LLM_MODEL_NAME` 环境变量覆盖。 --- ## 工作流（CLI 驱动） ### 单一命令 用户说"帮我处理这些 PDF"时： ```bash uv run python <skill>/scripts/doi_pipeline.py --article-dir <dir> --step all ``` `all` 的阶段顺序为 `ocr → match → verify → report → bibtex → rename`。 ### 分段执行 用户说"只跑 OCR" / "只校验" 等时： ```bash uv run python <skill>/scripts/doi_pipeline.py --article-dir <dir> --step ocr|match|verify|report|bibtex|rename ``` ### 带双通道验证的 match（推荐） 启用 LLM 对 OCR 标题与 Crossref 标题做语义比对（余弦相似度 + LLM 双通道，两者都否定才判 `no_confidence`）： ```bash uv run python <skill>/scripts/doi_pipeline.py --article-dir <dir> --step match --llm-verify ``` 约 100 tokens/次（输入两标题 + 1 token 输出 YES/NO），极轻量。配置见上面「LLM 配置」章节，最小只需在 settings.json 设 `LLM_API_KEY`。缺配置时自动降级为仅余弦验证,不报错。 ### 带 bib 与 litrev 的三方校验（强烈推荐） 若用户已有 `references.bib`,跑 verify 时传 `--bib` 让 bib 标题参与比对；若已跑过 `litrev-extract`,把其 `derived/` 目录传给 `--verify-with-litrev` 复用已有 metadata JSON,无需额外 LLM 调用: ```bash uv run python <skill>/scripts/doi_pipeline.py --article-dir <dir> --step verify \ --bib <dir>/references.bib \ --verify-with-litrev <dir>/litrev_project/output/derived ``` ### 断点续跑 `pipeline_state.json` 记录了已完成阶段。脚本启动时会跳过已完成的 stage,只跑未完成的。如果用户要求重跑已完成的 stage,需要手动删除 `pipeline_state.json` 中对应条目。 ### dry-run 重命名前预览: ```bash uv run python <skill>/scripts/doi_pipeline.py --article-dir <dir> --step rename --dry-run ``` ### --force 放行未验证条目 verify 阶段判定为 `mismatch`(内容与 DOI 不符)的条目在 rename 时会被门禁跳过。人工核对后确认无误,可用 `--force` 放行: ```bash uv run python <skill>/scripts/doi_pipeline.py --article-dir <dir> --step rename --force ``` --- ## 每阶段结果解读 命令跑完后,你(AI)负责做以下解读,不要只把输出丢给用户: | 阶段 | 你要做的事 | |------|-----------| | match | 读 `doi_match_report.md`,汇报:匹配 X 篇,未匹配 Y 篇,疑似未注册论文 Z 篇。对未匹配的列出标题,问用户是否需要人工处理。**对 `no_confidence` 条目**（疑似博士论文/预印本,在 Crossref 上无独立 DOI）说明:该论文可能不在 Crossref 上,建议归档到独立目录或重下正确论文,不要用 `--force` 强行匹配。同时留意 `verified:false` 的条目(标题与 CrossRef canonical 不符),一并向用户说明 | | verify | 读 `verify_report.md`,汇报:一致 X 篇,内容不符 Y 篇。**对内容不符项必须逐条列出**（OCR 标题 vs Crossref 期望标题 vs 相似度),告诉用户这通常是 PDF 下错/OCR 装错目录,需要重新下载正确论文或修正 OCR | | bibtex | 汇报拉取成功/失败数。失败的 DOI 可让用户重新跑一次 bibtex stage | | rename | **必须 dry-run 先预览**,列出将改名的文件让用户确认,确认后才执行。被门禁跳过的条目要向用户说明,建议先跑 verify 解决 | | ocr | 汇报成功/失败数。失败的 PDF 可能是扫描件或加密,告诉用户 | --- ## 已知问题 | 问题 | 处理 | |------|------| | Windows OpenSSL | BibTeX 拉取已用局部 `_create_unverified_context()`,无需用户干预 | | 已通过 pipeline_state.json 标记完成的 stage 重跑 | 手动删 state 文件或编辑 json | | CrossRef 命中率 | 非英文论文/预印本可能匹配失败,属预期;报告会列出 | | 重命名冲突 | 脚本跳过冲突项并记录,用户可手动处理 | | **内容与 DOI 错配** | 文件夹名是正确 DOI,但 OCR md 装的是另一篇论文(如下错博士论文)。verify 阶段会标 `mismatch` 并在 rename 时门禁跳过。处理路径:人工核对 → 重下正确 PDF/重跑 OCR → 删 pipeline_state.json 的 verify 条目重跑 | | **Crossref 未注册论文被误配 DOI** | 博士论文/预印本/技术报告在 Crossref 上无独立 DOI,`search_by_title` 会返回最相近的已注册论文(如 Mohammadian 博士论文→Rahman, Vasios 博士论文→Qi)。match 阶段双通道验证会判为 `no_confidence`(doi=None),不拉 bib 不 rename。处理:归档为 `@phdthesis` 或重下正确论文 | | LLM 通道不可用 | `--llm-verify` 缺 `LLM_API_KEY` 时自动降级为仅余弦验证,不报错;启动时会打印 WARN | | verify 误报 | OCR 标题启发式本身有噪声,相似度阈值默认 0.5 偏低以减少漏报。误报的条目人工确认后用 `--force` 放行 | | bib month 字段小写警告 | IEEEtran.bst 不认 `sept`/`june`,改 `Sept`/`June` 消 warning(不影响 PDF) | --- ## 范围外(本 skill 不做) - DeepSeek-OCR 并行化或并发调用(付费 API,settings.json 限制) - venv 合并或依赖管理 - CrossRef 以外数据源(Semantic Scholar / OpenAlex) - 一次性脚本版 `ocr_doi_matcher.py` 的后续维护 - LLM 并行化或并发调用(双通道验证为逐篇串行,单次极轻量) --- ## 校验机制说明(为何加这些) **信任链方向(重要)**:本 skill 的输入是乱码命名的 PDF。OCR 内容是最强的可用真值,Crossref 是外部权威登记,`references.bib` 是**流水线的输出**,不是输入。校验的目的是验证「这个 DOI 是否真的是这篇 PDF」,而不是假设 DOI 对了反过来怪内容。 本 skill 的核心风险是**单点信任**:流水线只信 OCR 文本,一旦 PDF 下错或 OCR 装错目录,错误会一路传到 rename 被固化。1.2.0 的双通道验证 + 1.1.0 的校验体系,按成本从低到高依次: 1. **[match] DOI 反查 + 双通道验证**:`search_by_title` 得到 DOI 后,回查 CrossRef canonical 标题,同时跑余弦相似度与 LLM 语义比对两条独立通道。两通道都过 → verified;只有余弦过 → 需人工;双通道都否 → `no_confidence`(该论文可能不在 Crossref 上,博士论文/预印本)。命中:搜错 DOI(M4)、内容错导致标题不一致、Crossref 未注册论文被误配。 2. **[verify] 文件夹内容校验**:按文件夹名推断 DOI,反查 CrossRef 期望标题与 OCR 标题比对。命中"PDF/OCR 装错目录"。 3. **`--bib` 第三方真值**:references.bib 标题参与三方比对。命中"bib 登记错"也能被比出来。 4. **`--verify-with-litrev` 深度内容**:复用 litrev-extract 已产出的 metadata JSON(从正文提取的 citation.title),抓"标题相似但内容不同"的刁钻案例。 为什么用 LLM 双通道而不是只调阈值:余弦相似度只看词重叠,读不出语义。它有两个盲区——不同论文共享关键词(假阳性)、OCR 噪声导致低分(假阴性)。LLM 直接读两个标题做语义判断,恰好补上这两个盲区。两条通道同时否定才判 `no_confidence`,避免单通道误杀。 所有校验只标记不删除,`no_confidence` 条目不进 rename 不拉 bib,错误内容仍以原名存在,可人工处理,零破坏。 --- ## 安装方式(管理端) 本 skill 位于 `paper-tools/paper-prep/`。junction 链接： ```bash # 管理员终端 mklink /J %USERPROFILE%\.claude\skills\paper-prep C:\Users\VerNe\Downloads\Documents\paper-tools\paper-prep ```