docling 子进程安全调用规范：为什么每个外部命令都要显式设置 check

docling（Get your documents ready for gen AI）文档转换引擎在运行时大量依赖外部可执行程序：OCR 阶段调用 Tesseract CLI、视频管线调用 ffmpeg/ffprobe、LaTeX 公式渲染调用 Tectonic、旧版 Office 格式（.doc/.xls/.ppt）转换调用 LibreOffice。如何在 Python 主程序中安全、可预测地驱动这些外部进程，是该项目子进程调用的核心问题。本文基于 docling 仓库内置的编码标准文档 .agents/skills/dignified-python/subprocess.md 展开，完整讲解其"显式设置 check"的核心规则、错误边界包装、超时保护等模式，并结合仓库中 Tesseract、ffmpeg、Tectonic、LibreOffice 四处真实子进程调用源码，展示这套规范在生产级代码中的落地方式。读完本文，你将掌握一套可直接复用的 subprocess 安全调用模板，并能理解 docling 各外部进程调用点的参数选择依据。

核心规则：check 必须显式设置

subprocess.md 给出的第一条、也是唯一一条硬性规则是：subprocess.run() 必须显式设置 check——要么 check=True（非零退出码时抛异常），要么 check=False（由你自己处理返回码）。绝不依赖默认值。

默认值 check=False 的问题在于：调用方是否预期检查退出码的"意图"是模糊的。代码评审时，看到没有 check 参数的 subprocess.run，你无法判断作者是忘了处理失败，还是认为失败无所谓。显式写出 check=True 或 check=False 是把意图固化在代码表面（intent in code）。

文档给出的三种写法对比：

import subprocess
from pathlib import Path

# ✅ CORRECT: check=True to raise on error
result = subprocess.run(
    ["git", "status"],
    check=True,
    capture_output=True,
    text=True
)
print(result.stdout)

# ✅ ALSO CORRECT: check=False when you intend to inspect returncode yourself
result = subprocess.run(["git", "status"], check=False, capture_output=True, text=True)
if result.returncode != 0:
    ...

# ❌ WRONG: check unset - intent is ambiguous
result = subprocess.run(["git", "status"])

注意这里 shell=False 的隐含前提：命令以列表形式传递参数，而不是拼接成一个 shell 字符串。docling 仓库中所有子进程调用（可全局搜索 subprocess.run 确认）均采用列表参数形式，且凡需要显式声明的地方都写出 shell=False，这与 check 规则共同构成了命令注入防护的第一道防线。

完整模式：把外部命令包进函数边界

subprocess.md 中"Complete Subprocess Example"一节的完整模式，是把命令封装成带类型标注的函数，在函数边界处捕获 CalledProcessError 并补充上下文后重新抛出：

def run_git_command(args: list[str], cwd: Path | None = None) -> str:
    """Run a git command and return output."""
    try:
        result = subprocess.run(
            ["git"] + args,
            check=True,          # Raise on non-zero exit
            capture_output=True, # Capture stdout/stderr
            text=True,          # Return strings, not bytes
            cwd=cwd             # Working directory
        )
        return result.stdout.strip()
    except subprocess.CalledProcessError as e:
        # Error boundary - add context
        raise RuntimeError(f"Git command failed: {e.stderr}") from e

这个模式有三个要点：

1. 错误边界（error boundary）：try/except 只包在调用外部进程的最小范围里，不是把整个业务逻辑裹进去。异常在边界处被"翻译"——从通用的 CalledProcessError 变成携带业务含义的 RuntimeError，并用 raise ... from e 保留原始异常链。
2. capture_output=True + text=True：分别保证能拿到 stdout/stderr 且是字符串而非字节，便于日志与异常信息拼接。
3. from e 异常链接：符合 PEP 3134，traceback 中可以看到完整因果链。

文档"Error Handling"一节还给出了直接消费 CalledProcessError 属性的用法，异常对象上 cmd、returncode、stdout、stderr 四个字段都可访问：

try:
    result = subprocess.run(
        ["make", "test"],
        check=True,
        capture_output=True,
        text=True
    )
except subprocess.CalledProcessError as e:
    # Access error details
    print(f"Command: {e.cmd}")
    print(f"Exit code: {e.returncode}")
    print(f"Stdout: {e.stdout}")
    print(f"Stderr: {e.stderr}")
    raise

常用模式速查

subprocess.md 的"Common Patterns"一节覆盖了三种高频场景，全部原样保留如下：

# Silent execution (no output)
subprocess.run(["git", "fetch"], check=True, capture_output=True)

# Stream output in real-time
process = subprocess.Popen(
    ["pytest", "-v"],
    stdout=subprocess.PIPE,
    stderr=subprocess.STDOUT,
    text=True
)
for line in process.stdout:
    print(line, end="")
process.wait()
if process.returncode != 0:
    raise subprocess.CalledProcessError(process.returncode, process.args)

# With timeout
try:
    subprocess.run(["long-command"], check=True, timeout=30)
except subprocess.TimeoutExpired:
    print("Command timed out")

三条模式说明：

• 静默执行：capture_output=True 只是捕获、不会打印；若连捕获都不需要，可以用 stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL 进一步省内存。
• 实时流式输出：subprocess.run 本质是"等进程结束"，无法边执行边读输出；需要实时行输出时必须用 Popen + 迭代 process.stdout，并用 process.wait() 收尾。由于 Popen 没有 check 参数，退出码需要手工检查——文档示例中手动 raise subprocess.CalledProcessError(process.returncode, process.args) 正是"显式表达意图"原则在 Popen 场景的等价物。
• 超时保护：timeout 只作用于 run/call 等阻塞式 API；进程超时会被强制终止并抛 subprocess.TimeoutExpired。对于可能挂死的外部程序（GUI 应用、需要用户交互的转换工具），超时是必选项。

文档最后的 Key Takeaways 汇总为五条：显式设置 check、用 capture_output=True 捕获输出、用 text=True 拿字符串、在边界处 try/except 补上下文、长任务设 timeout。

docling 源码中的落地：四个真实调用点

下面进入仓库源码，看这套规范在 docling 中如何执行。所有示例均取自当前仓库，文件路径可直接跳转。

1. Tesseract CLI：check=True + 输入净化 + 边界日志

OCR 阶段的 CLI 模式实现于 TesseractOcrCliModel。核心执行点 docling/models/stages/ocr/tesseract_ocr_cli_model.py#L197-L199：

output = subprocess.run(
    cmd, stdout=PIPE, stderr=DEVNULL, stdin=DEVNULL, check=True, shell=False
)

对照 subprocess.md 的规范，这里每个参数都有明确动机：

• check=True：OCR 失败必须抛 CalledProcessError，由上层决定降级策略；
• stdin=DEVNULL：外部命令不读标准输入，杜绝挂起等待；
• stderr=DEVNULL：Tesseract 的 stderr 噪音大且上层用 CalledProcessError.stderr 记录，这里直接丢弃节省内存；
• shell=False：显式声明不用 shell 解释。

更值得注意的是它的调用前净化与调用后边界处理，把 subprocess 规范从"怎么调"扩展到了"调之前和调之后"：

• 构造时即验证并缓存所有子进程参数——_sanitize_lang 用白名单正则 ^[a-zA-Z0-9_/][a-zA-Z0-9_/+-]*$ 校验语言标识符，docling/models/stages/ocr/tesseract_ocr_cli_model.py#L108-L136 拒绝含 null 字节的命令名、数据目录和文件名，注释明确写着"防止参数注入（prevent argument injection）"；psm 选项在拼命令行时强制 int() 转换（docling/models/stages/ocr/tesseract_ocr_cli_model.py#L190-L191）。
• 边界处理上，OSD（方向/脚本检测）失败与 OCR 失败分别被捕获并带完整上下文记日志——docling/models/stages/ocr/tesseract_ocr_cli_model.py#L327-L361 中捕获 subprocess.CalledProcessError 后打印"文档、页码、OCR 矩形、临时文件"四元组，auto 模式下 OSD 失败直接 continue 跳到下一块，非 auto 模式则继续尝试 OCR。这正是 subprocess.md 所说"Error context: Wrap in try/except at boundaries"的完整版：异常在业务边界被消化成日志和降级，而不是让整页崩溃。

对应的单测 tests/test_tesseract_ocr_cli_lang.py 通过 patch("...subprocess.run", return_value=...) 伪造 --list-langs 输出，验证 Windows 反斜杠语言包（script\Latin）会被归一化为 script/ 并通过 _sanitize_lang，说明子进程输出解析逻辑本身也是被测试覆盖的一等公民。

2. ffmpeg 帧抽取：check=False + 手工 returncode 检查的正当性

不是所有外部命令失败都该抛异常。视频帧采样 docling/utils/video_frame_sampling.py 中，单帧抽取用 check=False（docling/utils/video_frame_sampling.py#L139-L165）：

proc = subprocess.run(
    ["ffmpeg", "-nostdin", "-ss", f"{timestamp:.3f}", "-i", str(video_path), ...],
    capture_output=True,
    check=False,
)
if proc.returncode != 0 or not proc.stdout:
    _log.debug("Frame extraction at %.3fs produced no output (rc=%s): %s",
               timestamp, proc.returncode,
               proc.stderr.decode("utf-8", "replace")[-200:])
    return None

这是 subprocess.md 中"check=False when you intend to inspect returncode yourself"的典范应用：时间戳超出视频结尾时 ffmpeg 返回非零属于预期内场景，正确行为是记 debug 日志并返回 None，让上层跳过这一帧，而不是让整段视频处理中断。or not proc.stdout 还额外处理了"退出码为 0 但没有数据"的空输出情况。

与之形成对照的是同文件中的 _probe_duration（docling/utils/video_frame_sampling.py#L109-L131）：ffprobe 查时长失败同样属于"环境不完整"的软失败，所以这里用 check=True 抛出，再在 except (subprocess.CalledProcessError, ValueError) 中统一降级为 0.0。同一个视频管线内，"失败是错误还是正常分支"的区分决定了 check 的取值——这正是"显式设置"原则的实质：先想清楚失败的语义，再把它写进参数。

3. Tectonic LaTeX 引擎：check=True + timeout 双保险

LaTeX 图表渲染引擎 docling/backend/latex/engines/tectonic.py 同时使用了 subprocess.md 五条要点中的两条硬措施：

subprocess.run(
    cmd,
    cwd=temp_dir,          # 在临时目录内编译，隔离产物
    capture_output=True,
    check=True,
    timeout=self.timeout,  # 外部编译进程必须限时
)

外层分别捕获 CalledProcessError（编译失败：解码 stderr 记 warning 并返回 None，让管线降级处理）和 subprocess.TimeoutExpired（超时：记 warning 返回 None）。Tectonic 是一个会下载包、可能长时间运行的外部编译器，timeout 在这里不是可选装饰，而是防止渲染阶段无限阻塞的必要手段。这与 subprocess.md "Timeout safety: Set timeout for long-running commands" 直接对应。

4. LibreOffice 旧格式转换：超时 + 独立 profile + 输出丢弃

旧版 .doc/.xls/.ppt 到现代格式的转换在 docling/backend/docx/drawingml/utils.py 中通过 LibreOffice 无头模式完成（docling/backend/docx/drawingml/utils.py#L129-L145）：

subprocess.run(
    [libreoffice_cmd, profile_arg, "--headless", "--convert-to",
     target_suffix, "--outdir", str(tmp_dir), str(input_path)],
    stdout=subprocess.DEVNULL,
    stderr=subprocess.DEVNULL,
    check=True,
    timeout=timeout_s,     # 默认 120 秒
)

这里把 subprocess 安全和进程安全结合起来：_isolated_libreoffice_profile() 为每次转换创建一个一次性 UserInstallation profile 目录（用后即删），避免并行转换抢占同一个 profile 锁；timeout=120 防止 soffice 挂死拖住调用线程；DEVNULL 丢弃输出因为结果只落在输出文件里——转换成功与否以"预期产物文件是否存在"为准（docling/backend/docx/drawingml/utils.py#L147-L151 检查后抛 RuntimeError）。

5. 测试代码里最简模板

仓库测试中的 tests/test_run_pr_fast_checks.py#L38-L46 是 subprocess.md 中 run_git_command 完整模式的最小实现：

def run_git(repo_root: Path, *args: str) -> str:
    completed = subprocess.run(
        ["git", *args],
        cwd=repo_root,
        capture_output=True,
        text=True,
        check=True,
    )
    return completed.stdout.strip()

五个参数一个不少，与规范文档逐条对齐。

关键参数决策表

综合 subprocess.md 与 docling 源码中的实际用法，外部命令调用时各参数的决策逻辑如下：

参数	规范要点	docling 中的实际选择
命令形式	必须列表传参、禁用 shell 字符串拼接	全部列表形式，必要时显式 shell=False（如 Tesseract 三处调用）
check	必须显式。失败=错误→True；失败=正常分支→False 且自行检查 returncode	版本探测/OCR 编译用 True；视频帧抽样用 False + returncode != 0 手工检查
capture_output	需要输出时捕获 stdout/stderr	需要解析输出的场景（ffprobe 时长、Tesseract TSV）用之；产物落文件的场景（LibreOffice 转换）改用 DEVNULL
text	拿字符串便于日志与异常拼接	ffprobe、git 等文本输出用 text=True；二进制输出（ffmpeg 帧数据）不用，取回 bytes 后手工解码
stdin	外部命令不应读标准输入	Tesseract 一律 stdin=DEVNULL 防挂起
timeout	长任务/不可信外部进程必须限时	Tectonic 用 self.timeout，LibreOffice 默认 120s；帧级短命令不设
cwd	限定工作目录隔离产物	Tectonic 在临时目录编译；测试中 git 命令限定 repo_root

自检清单

按 .agents/skills/dignified-python/subprocess.md 的 Key Takeaways，代码评审或自写子进程调用时逐条核对：

1. check 是否显式设置？没写 check 的 subprocess.run 一律视为问题代码；若选 check=False，代码中必须能看到对 returncode 的检查，否则应改为 check=True。
2. 输出是否被捕获？需要输出时加 capture_output=True；完全不需要时用 DEVNULL，不要让它继承父进程文件描述符。
3. 是否 text=True？处理文本命令输出时启用；二进制输出则保持 bytes 并显式选择解码方式（参考 video_frame_sampling.py 中 decode("utf-8", "replace") 的宽容解码）。
4. 异常边界是否补上下文？捕获 CalledProcessError 时至少记录命令、退出码、stderr，并用 raise ... from e 或业务异常重新抛出。
5. 长命令是否设 timeout？任何可能挂死的 GUI/转换/编译类进程都应限时，并显式捕获 subprocess.TimeoutExpired。
6. Popen 场景退出码是否手工处理？Popen 无 check 参数，wait() 后必须检查 returncode（见 subprocess.md 的流式输出模式）。

docling 的实践还补上了规范之外的两条工程经验：一是对进入命令行的一切外部输入先净化（Tesseract 的语言包、数据目录、psm 选项），因为"check 与 shell=False 防的是崩溃，净化防的是注入"；二是对外部命令的环境隔离（LibreOffice 一次性 profile、Tectonic 临时目录 cwd），保证子进程调用在并发场景下互不干扰。把这两条加进自己的 subprocess 使用习惯，就能覆盖文档转换这类"深度依赖外部工具链"场景下绝大多数的进程安全问题。