GROBID + Docling PDF 解析

grobid-docling-pdf 用来把论文或技术 PDF 解析成一个下游 Agent 可消费的 XML 包：GROBID 负责学术文本结构，Docling 负责图表图片真值，最终合并成一个干净的 TEI/XML 交付目录。

逻辑视图

这个 skill 接收一份 PDF、GROBID 服务地址和解析选项，输出一份以 TEI/XML 为入口的材料包。它把“文本结构”和“视觉真值”分开处理：GROBID 提供标题、摘要、正文、引用和参考文献结构，Docling 提供图片与表格 PNG；合并阶段以 Docling 为唯一图表索引来源，并清理无法由 Docling 支撑的 GROBID 图表目标。

核心模块及其边界如下：

阶段	脚本	职责
本地运行时	`scripts/manage_grobid_runtime.py`	强制唯一标准镜像与共享容器，幂等创建或启动容器并等待健康检查。
文本结构解析	`scripts/grobid_parse_pdf.py`	调用 GROBID，提取标题、摘要、正文、引用和参考文献结构。
视觉内容导出	`scripts/docling_export.py`	调用 Docling，导出 PDF 中的图片、表格和 Docling JSON。
结果合并	`scripts/merge_docling_into_grobid_tei.py`	将 Docling 图片索引写入 GROBID TEI，移除不可靠的 GROBID 图表记录。
包校验	`scripts/validate_hybrid_outputs.py`	检查 XML 中引用的图片是否存在、最终图片是否全部被索引。
编排与归档	`scripts/run_hybrid_pipeline.py`	串联以上阶段，归档中间结果，只保留最终 XML 包。

最终边界是 final/<paper-name>.xml 与相邻的 final/images/；GROBID 原始结果、Docling JSON、合并清单和校验 JSON 属于可追溯中间结果，不是默认最终目录中的独立交付件。

运行视图

从用户请求到交付物的执行路径是：

text

用户 prompt + PDF 路径
  -> 主 Agent 确认 PDF 类型、输出目录和依赖
  -> run_hybrid_pipeline.py
     -> 默认本地 URL：ensure 唯一共享 GROBID 容器
        外部服务 URL：复用调用者已准备的 GROBID 服务
     -> GROBID TEI
     -> Docling JSON + images
     -> merged TEI/XML + final/images
     -> 校验状态与 validation JSON
  -> intermediate_parse_results.zip
  -> 主 Agent 汇报 XML、图片、归档和校验摘要

默认流水线必须能访问 GROBID 服务；随后才会运行 Docling、合并与校验。任何阶段返回非零状态都会终止编排，校验失败也不能报告为成功交付。校验摘要会打印到命令输出，详细 JSON 会随 work/ 进入中间归档。

本地管理分支只在去除尾部 / 后的 URL 为 http://127.0.0.1:8070 时执行；其他地址即使指向本机也由调用者负责服务生命周期。依赖预检固定检查本地 Docker，不会自动切换为远端连通性检查。运行时 status 只做只读资源检查，ensure 才会创建、启动并等待 HTTP 健康状态。

编排开始时会先清理目标最终目录与松散中间目录；应为每份 PDF 分配独占输出目录。成功后才创建中间归档并清理松散文件；失败时可能留下不完整产物。默认输出契约不适用于显式启用 --keep-intermediate 或指定自定义输出路径的诊断运行。

开发视图

分层	位置	面向开发者的含义
Agent 使用约定	`SKILL.md`	定义默认工作流、最终输出契约和汇报要求，不是面向文档站的正文。
发布文档	`docs/`	提供能力展示、使用方式、依赖与架构说明。
依赖预检	`verify_dependencies.py`	检查 Python 包、可选 CUDA、Docker Desktop、唯一标准 GROBID 镜像及容器唯一性；不改变容器状态。
本地运行时	`scripts/manage_grobid_runtime.py`	复用固定的 `grobid-docling-pdf` 容器，禁止任务级容器，并等待服务健康。
流水线编排	`scripts/run_hybrid_pipeline.py`	负责阶段顺序、路径、归档和中间文件清理。
解析与合并	`scripts/grobid_parse_pdf.py`、`scripts/docling_export.py`、`scripts/merge_docling_into_grobid_tei.py`	分别处理学术文本、视觉导出及统一 XML。
交付校验	`scripts/validate_hybrid_outputs.py`	校验图片引用、索引和残留视觉记录，并以退出码决定流水线成败。

最终目录

text

.tmp/runs/<run-id>/grobid-docling-pdf/<paper-name>/
|-- final/
|   |-- <paper-name>.xml
|   `-- images/
|       |-- picture_*.png
|       `-- table_*.png
`-- <paper-name>.intermediate_parse_results.zip

设计边界

born-digital 论文默认不开 OCR；扫描版 PDF 才启用 --ocr。
本地任务固定复用 grobid/grobid:0.8.2 与 grobid-docling-pdf，解析后保持容器运行以支持并发。
最终 XML 只以 Docling 导出的图表图片作为视觉真值。
中间 GROBID / Docling / merge / validation 文件默认打包进 zip 后移除。
校验失败意味着 XML 包不完整，不能作为成功交付。

Agent 协作边界

当前 skill 的既定流程没有要求启动子 Agent、checker 或 reviewer，也没有定义跨 Agent 交接物。主 Agent 单独完成依赖确认、流水线执行、结果核验和最终汇报；因此使用本 skill 不需要额外申请子 Agent 权限。

如果上游任务自行采用多 Agent 编排，交接边界只应是已经生成并通过校验的最终 XML、images/ 和中间归档路径；下游 Agent 不应绕过校验直接消费松散的 GROBID、Docling 或 work/ 中间文件，也不应把“已建立图片索引”误报为“每张图片都存在准确正文位置引用”。

校验关注点

validate_hybrid_outputs.py 会检查最终 XML 包的图片封装关系，重点包括：

XML 中引用的图片是否都存在。
图片目录中的最终图片是否都被 XML 索引。
统计正文中已标注为 Docling 关联的图片、只有索引而无正文关联的图片，并检查关联图片文件是否存在。
最终 XML 中是否残留不可靠的 GROBID 图表记录。

通过校验后，final/<paper-name>.xml 才应作为下游 Agent 的正式输入。校验器不评估引用的语义、正文位置或 OCR 正确性；valid: true 也允许存在未关联正文的图片和没有 target 的原始图表引用。它使用恢复模式读取 XML，不等于通过 TEI/XSD 严格模式校验。下游如需逐图语义对应或严格 schema 合规，应另行复核。

GROBID + Docling PDF 解析 ​

逻辑视图 ​

运行视图 ​

开发视图 ​

最终目录 ​

设计边界 ​

Agent 协作边界 ​

校验关注点 ​

子仓文档导航 ​