用途
digest-pdf 用于将 PDF 消化为磁盘上的结构化单元树，每个单元是一对（图像，转写文本）。它面向教材类 PDF（生成章节/小节树）与试卷类 PDF（按题目切分）等场景。工具负责全部识别与切分，不消耗 LLM token；MinerU 是唯一的转写器（ADR-0010）。使用者的职责是理解调用的仓库、确认其 Layout Spec、运行批量处理并做校验，而不应自行 OCR 或阅读图片转写页面。
主要能力
- 支持一次处理一个或多个 PDF 文件及/或目录（对目录递归查找 *.pdf）。
- 三种切分策略：
auto（默认）、page、outline、question。 page：输出<out>/<stem>/page-NNNN.{png,md}（扁平结构）。outline：输出<out>/<stem>/第N章/<section>/page-NNNN.{png,md}，章节树在转写后解析。question：输出<out>/<stem>/qNN.{png,md}（完整题目，含题干、选项、解答），以及<out>/<stem>/qNN-stem.{png,md}（不含解答的题目，切断于【答案】/【解析】/【分析】/【详解】之前）；若 PDF 无解答标记，则只有 qNN，属正常情况。- 每个 .md 带来源头信息（model@revision、dpi、strategy、源页码）。
- 通过 Layout Spec（
<repo>/.digest/layout.yaml，ADR-0008）决定落盘位置：一张有序规则表，每条规则将文件名模式（regex 加命名捕获，如 year/region/subject）映射到一个切分策略和一个目标路径模板（如真题/{region}/{year}/{subject}/q{qno}），从仓库根解析。 - 单进程内跨 PDF（规划与 MinerU 提交）和跨页面（渲染/写入）并行，一次调用即可占满机器；重跑会从 manifest 续传。
- MinerU 服务器可预热（
--serve-mineru），在整个批次中保持模型加载，避免逐 PDF 冷加载。
使用方式
工具是已发布的 Python CLI，可直接从 Git 仓库用 uvx 运行：
DIGEST="uvx --from git+https://github.com/sunfmin/digest-pdf digest"
所有命令在调用仓库的工作目录下运行。工具自行管理其 venv 与模型缓存。
典型工作流：
- 理解仓库并确认 Layout Spec（门禁）。从 cwd 向上查找
.digest/定位调用仓库；若存在 CONTEXT.md 可读取命名约定。用$DIGEST --inspect <targets...>探测匹配情况（不涉及 MinerU/VLM），每行含layout: {status, rule, strategy, dest}，status 取值matched | unmatched | no-spec。全部 matched 且策略无歧义时可直接展示计划表并运行；no-spec、存在 unmatched、策略有歧义或计划与已存 spec 背离时需停下确认，提出 Layout Spec 供用户批准后写入并重新 inspect。对未匹配的 stem 应提议新增规则，不得静默回退到原生<stem>/布局。 - 确保就绪（一次性）。若 --inspect 行中任一
needs_mineru: true，先检查并安装 MinerU（约 2 GB 模型，经 ModelScope）：$DIGEST --mineru-status || $DIGEST --install-mineru。 - --inspect 每行结构：
{path, pages, strategy, needs_mineru, out_subdir, estimate, layout}。estimate 在 question 策略下为文本层 PDF 检测到的题目数，或在无文本层时为 "unknown (scanned)"；outline 策略下为章节树在转写后解析的说明；page 策略下为页数。 - 预热 MinerU 服务器（仅当有行需要 MinerU）：后台运行
--serve-mineru并等待健康检查，导出MINERU_API_URL；若启动失败则告警并在无 URL 情况下继续（会回退到逐 PDF CLI，较慢但可用）。 - 运行批次（单进程，内部并行）。已确认 Layout Spec 时省略
--out与--strategy；重跑从 manifest 续传。不要并行启动多个 digest 进程（会在共享 manifest 上竞争）。 - 校验：读取
<out>/manifest.json，统计每个 PDF 的完成与失败页数，并在磁盘上交叉核验每个单元目录中 *.md 与同名 *.png 成对存在。 - 收尾：若步骤 3 启动了服务器，则 kill 对应 PID。
适用场景
- 教材类 PDF 的章节化拆解（outline）。
- 试卷类 PDF 的逐题拆解（question），可对扫描版试卷强制使用
--strategy question。 - 一般 PDF 的逐页拆解（page）。
- 需要将 PDF 内容按仓库约定的路径模板批量落盘的场景。
限制与注意事项
auto策略在无可用结构的扫描 PDF 上会回退为page。- 扫描 PDF 的题目数在运行前可能未知（estimate 为 "unknown (scanned)"），属正常情况，由 MinerU 在运行时解析。
- 题目无解答标记时不会生成 -stem 图像，属预期而非错误。
- 本技能允许写入的唯一文件是调用仓库的
<repo>/.digest/layout.yaml（Layout Spec 引导）；不应 push，也不应编辑工具的 lockfile。 - 关于收费、价格、具体平台支持范围等信息，资料中暂未提供。