pdfaudit

pdfaudit

有些 PDF 在屏幕上看起来没问题，但屏幕阅读器却无法使用：文本虽然存在，却没有任何信息说明阅读顺序；图像没有描述；文件甚至可能禁止提取辅助技术所依赖的内容。pdfaudit 会根据 PDF/UA 无障碍性的机器可检基本要求检查本地 PDF，并在 JSON 报告中准确列出检查结果，供调用方采取后续行动。文档绝不会上传——审计会读取磁盘上的文件，完全在本地运行，不会访问网络。

每份文档都会运行七项检查。文档必须带有标签（目录中包含 /MarkInfo 字典，且其中有 /Marked true），并且必须包含结构树（/StructTreeRoot）。必须设置语言（非空的 /Lang 条目），并且必须提供标题（信息字典中非空的 /Title；不会检查 XMP 元数据）。每张图像都必须能从带有替代文本的结构元素访问。必须能够确定阅读顺序，这需要结构树和至少一个结构元素。此外，文档不得禁止辅助功能访问：未加密的文档通过检查；加密文档只有在权限位允许为无障碍功能提取内容时才通过。

每项检查都会报告固定的 ID、名称、通过或失败状态，以及详细信息字符串。报告会统计失败数量，并选择下一步处理方案：没有失败时为 already-compliant；扫描文档（没有可提取的文本，但至少有一张图像）为 ocr；包含可提取文本但未加标签的数字 PDF 为 guaranteed；其他情况均为 repair——包括需要针对性修复的部分加标签或混合文档。一行判定结果会概述通过的检查数量、处理方案，以及任何失败检查的 ID。

审计采用刻意精简的 PDF 读取方式：扫描普通对象块以查找目录、信息字典、结构元素、图像对象和加密字典，并从 Tj 和 TJ 运算符中恢复文本，以辅助确定处理方案。对于无法通过这种方式读取的文件，程序会如实报告——文件不存在、没有 PDF 文件头，以及没有可用对象结构的文件，都会分别产生各自的错误，而不是给出误导性报告。

CLI

npx @reneturcios/pdfaudit check_pdf_accessibility '{"file_path": "/path/to/document.pdf"}'
npx @reneturcios/pdfaudit --version

报告以 JSON 格式打印：

{
  "filePath": "/path/to/document.pdf",
  "checks": [
    {
      "id": "tagged",
      "name": "Document is tagged",
      "passed": true,
      "detail": "MarkInfo/Marked is true"
    }
  ],
  "failed": 0,
  "route": "already-compliant",
  "verdict": "7/7 checks passed. Route: already-compliant."
}

（上面的示例缩写了 checks 列表；实际报告始终包含全部七项。）

退出代码：成功时为 0；运行时错误时为 1（包括无法解析 JSON 参数、文件不存在，或文件不是可审计的 PDF）；用法错误时为 2。

MCP 服务

npx -y @reneturcios/pdfaudit mcp

MCP 客户端配置：

{
  "mcpServers": {
    "pdfaudit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/pdfaudit", "mcp"]
    }
  }
}

工具

• check_pdf_accessibility — 根据 PDF/UA 无障碍性的机器可检基本要求审计本地 PDF，并返回 JSON 报告。文档绝不会上传。

  • file_path（字符串，必填）— 本地 PDF 的路径

  返回一项文本内容，其中包含 JSON 报告；报告采用 2 个空格缩进美化打印，键按 filePath、checks、failed、route、verdict 的顺序排列。 checks 中的每个条目都按 id、name、passed、detail 的顺序包含这些字段。

Docker

docker run -i ghcr.io/cloudcorprecords/pdfaudit
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/pdfaudit check_pdf_accessibility '{"file_path": "/w/document.pdf"}'

开发

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

许可证

MIT — 版权所有 (c) 2026 Rene Turcios