使用方式

这个 skill 适合在“论文阅读、技术 PDF 解析、后续 PPT 或报告生成”之前调用。你可以直接把 PDF 路径交给 Agent，让它生成结构化 XML 包，而不是让 Agent 直接从 PDF 页面里硬读内容。

典型 Prompt

• 请解析这篇论文 PDF，输出结构化 XML 和图表图片索引，用于后续分析。
• 请把这篇论文 PDF 的正文、引用、参考文献、图和表整理成 agent 可消费的结构化结果。
• 请先把这个技术 PDF 转成 XML 包，保留最终 XML 路径、图片目录和校验结果。

推荐流程

1. 确认 PDF 是 born-digital 还是扫描版。
2. 确认唯一的共享 GROBID 运行时符合规范；默认流水线会自动检查、创建或启动它。
3. 将输出目录放在主工作区 .tmp/runs/<run-id>/grobid-docling-pdf/<paper-name>/ 下。
4. 运行混合解析流水线。
5. 检查最终 XML、图片目录、归档 zip 和校验状态。

每份 PDF 使用独立输出目录。同一路径重跑会先清理 final/、grobid/、docling/、work/ 以及旧 comparison/、merged/，然后才检查或启动运行时；需要保留既有结果时，应使用新的论文子目录。--final-out 指定的目录也会被整体清理，只能指向本次工作的独占产物目录。

脚本入口

以下命令从工作区根目录（即包含 skills/ 和 .tmp/ 的目录）运行：

Windows 的默认 GBK Python 环境中，Docker JSON 输出可能触发当前运行时脚本的解码错误。先在当前 PowerShell 会话启用 Python UTF-8 模式，使设置同时传给流水线子进程；此设置不更改 Windows 系统编码：

$env:PYTHONUTF8 = "1"

python skills/grobid_pdf_skill/scripts/run_hybrid_pipeline.py `
  --pdf path/to/paper.pdf `
  --out .tmp/runs/<run-id>/grobid-docling-pdf/<paper-name> `
  --grobid-url http://127.0.0.1:8070 `
  --docling-device auto

本地默认模式固定复用 grobid-docling-pdf 容器，不要为论文、任务或 Agent 创建独立容器。容器不存在时流水线会创建并启动，已停止时会重新启动，解析完成后保持运行以支持并发任务。也可以单独检查或确保运行时：

python skills/grobid_pdf_skill/scripts/manage_grobid_runtime.py status
python skills/grobid_pdf_skill/scripts/manage_grobid_runtime.py ensure

本地自动管理按 URL 字符串判断：去除末尾 / 后恰好为 http://127.0.0.1:8070 才会调用 ensure。使用远端或独立维护的服务时传入其实际 --grobid-url；例如 http://localhost:8070 虽指向本机，也会跳过 Docker 管理，必须由调用者提前保证服务可用。不要通过更换本地别名规避共享容器规范。

status 只读检查镜像与容器配置，不启动容器，也不请求 /api/isalive；ensure 会创建或启动共享容器，并等待该健康接口。流水线对外部服务不会启动 Docker，但 GROBID 解析步骤仍会请求其 /api/isalive 和 /api/processFulltextDocument。服务地址是根 URL，不要追加 /api。

扫描版 PDF 才加：

--ocr

确认 CUDA PyTorch 可用后才指定：

--docling-device cuda

交付汇报

Agent 完成后应汇报：

• 最终 XML 路径。
• 最终图片目录和图片数量。
• 中间结果归档路径。
• 校验状态，包括缺失图片引用、未索引图片、body-linked 图片数量。

完成标准是命令成功退出、XML 和图片存在、中间归档生成，并且校验输出 valid: true。缺失图片引用、未索引图片、正文关联图片缺失、残留 GROBID 图表和悬空视觉目标均应为 0。indexed_without_body_ref 可以大于 0，必须如实汇报，不能据此宣称每张图都有准确正文位置引用。单独看见 final/ 目录不足以证明成功；失败可能留下不完整目录，且尚未生成中间归档。

默认成功后删除松散中间文件；诊断时可加 --keep-intermediate，在归档之外保留它们。--final-out 和 --intermediate-archive 可以更改最终目录与归档位置；没有显式指定时，按上述默认目录交付。

依赖检查

以下命令同样从工作区根目录运行。它检查 Python 包、Docker Desktop、唯一标准 GROBID 镜像以及本地容器唯一性；不会启动容器或请求 GROBID API：

python skills/grobid_pdf_skill/verify_dependencies.py

依赖检查允许标准容器尚未创建；默认流水线会调用运行时管理脚本，将唯一标准容器处理到可用状态。

依赖检查脚本没有 --skip-services、--grobid-url 等选项，也不会根据外部服务地址自动跳过本地 Docker。使用独立服务时，按依赖说明区分 Python 包、本地运行时预检和远端服务连通性。