依赖说明

使用这个 skill 前，请先让 Agent 跑依赖检查。依赖状态以子仓根目录的 verify_dependencies.py 输出为准；文档只说明它会检查什么。

让 Agent 先做什么

你可以直接这样说：

我要使用 grobid-docling-pdf，请先检查 PDF 解析依赖；如果 Docker、GROBID 镜像或 Python 包没有就绪，请帮我处理到可用。

检查命令

以下命令从工作区根目录（包含 skills/ 和 .tmp/ 的目录）运行，检查默认本地模式的依赖：

# Windows PowerShell：让 Python 和后续子进程使用 UTF-8
$env:PYTHONUTF8 = "1"
python skills/grobid_pdf_skill/verify_dependencies.py

Windows 默认 GBK Python 环境可能因 Docker 输出中的非 GBK 字节触发 UnicodeDecodeError，随后出现 NoneType.splitlines。可先在当前 PowerShell 会话设置 $env:PYTHONUTF8 = "1" 再执行；该设置也会传给后续流水线子进程。仅检查依赖时，也可运行 python -X utf8 skills/grobid_pdf_skill/verify_dependencies.py。这是已复现解码问题的运行规避方式，不能把普通模式的 traceback 当成依赖检查通过。

该脚本不提供命令行选项；不要使用旧资料中的 --skip-services 或 --grobid-url。这两个选项属于旧说明，不能控制当前脚本的检查范围。

它会检查什么

类型	必需性	脚本实际检查
Python 包	必需	分别导入 docling、lxml、torch，导入失败即检查失败；若模块暴露版本号则打印版本。
Docker	默认本地模式必需	检查 docker 命令是否存在，并通过 Docker Server 版本确认引擎可用。Windows 缺失时提示安装 WSL2 和 Docker Desktop；macOS 缺失时提示安装 Docker Desktop for Mac。引擎不可用时返回对应平台的启动提示。
GROBID 镜像	默认本地模式必需	按镜像仓库名中的 grobid 和 GROBID 标签发现候选；候选必须恰好只有一个镜像 ID，并且唯一标签为 grobid/grobid:0.8.2。
GROBID 容器	默认本地模式必需的配置检查	容器可以尚未创建；如果存在，则包括停止实例在内最多只能有一个，并且必须是固定名称 grobid-docling-pdf、标准镜像 ID、固定端口 127.0.0.1:8070 和 unless-stopped 重启策略。
CUDA	可选	通过 torch.cuda.is_available() 检查；不可用只给出警告，可继续使用 --docling-device auto 或 cpu。

外部 GROBID 服务是另一种运行方式：显式传入去除尾部 / 后不等于 http://127.0.0.1:8070 的 --grobid-url，流水线会跳过本地 Docker 管理。因此外部服务模式不要求本机具备 Docker 或 GROBID 镜像，但仍要求可导入这些 Python 包，并能访问目标服务的 /api/isalive 与 /api/processFulltextDocument。verify_dependencies.py 始终检查本地 Docker，不能作为外部服务模式的完整判定器；应分别确认 Python 导入与服务健康，并以实际解析和包校验结果作为完成依据。

不会检查什么

verify_dependencies.py 不会：

• 扫描或验证仓库脚本、SKILL.md、示例 PDF 等代码资产；
• 下载模型、执行真实 PDF 解析，或验证 GROBID 对某份 PDF 的解析质量；
• 启动、停止、创建或删除 GROBID 容器，也不会请求 GROBID HTTP API；
• 检查 Python 包版本兼容矩阵、模型缓存、磁盘空间、网络代理或远端下载权限；
• 检查外部 GROBID 服务，或证明 Docling 首次使用所需模型已缓存；离线环境需要提前准备模型缓存，未缓存时需要能访问模型下载源；
• 验证 CUDA 驱动、CUDA toolkit 与 PyTorch 构建版本是否互相兼容；
• 运行合并器、最终图片索引校验或解析器自测试。

缺失时的修复方向

• docling、lxml 或 torch 导入失败：在运行该工作区的同一 Python 环境中安装或修复对应包，再重新运行依赖检查。安装 torch 时按目标机器的 CPU/CUDA 平台选择官方匹配构建。
• Windows 上 Docker 检查失败：安装 WSL2 和 Docker Desktop；若已经安装，则启动 Docker Desktop 并确认 WSL2 backend 可用。
• macOS 上 Docker 检查失败：安装并启动 Docker Desktop for Mac，等待 Docker engine ready 后重新检查。
• GROBID 镜像缺失：拉取 docker pull grobid/grobid:0.8.2；检测到额外镜像时先报告并获得授权，再精确清理。
• GROBID 容器重复或配置漂移：不要新建任务专属容器，也不要静默清理；先报告异常资源并获得授权。状态符合规范后，运行 python skills/grobid_pdf_skill/scripts/manage_grobid_runtime.py ensure 创建、启动并复用标准容器。
• CUDA 只出现警告：不必阻塞 CPU 流程，使用 --docling-device auto 或 cpu；如果确实需要 GPU，再核对 NVIDIA 驱动、PyTorch CUDA 构建和 torch.cuda.is_available()。

判断标准

只有必需 Python 包、Docker、唯一标准 GROBID 镜像和容器配置检查均通过，才满足默认本地流水线的安装前提。零容器是合法的初始状态；默认流水线会创建或启动唯一标准容器并等待健康检查。status 和本依赖检查均不证明 HTTP 服务已健康；外部服务模式按上一节单独确认。依赖检查通过仍不代表任意 PDF 的最终包必然通过内容与图片索引校验。