PDF Accessibility Audit

pdf-a11y-audit

面向用户和 AI Agent 的本地优先 PDF 无障碍审计工具。

无需上传，无需账户，无需 API 密钥，也不会调用模型。它会读取本地 PDF，检查实际对象模型和文本层，并返回结构化报告、Markdown 审计结果，或可直接发送给同事的独立 HTML 报告。

为什么要开发这个工具

大多数 PDF 无障碍检查工具要么是 Windows 图形界面，要么是付费服务，要么只给出黑箱评分。本工具则恰恰相反：

• 本地运行 — 文档不会离开你的设备。
• 结果确定 — 同一份 PDF 始终会生成相同的检查结果。
• 基于证据 — 每条检查结果都会注明规则、页码、标准参考和修复步骤。
• 如实报告 — 需要屏幕阅读器或人工检查的项目会标为手动检查，绝不会报告为已通过。
• 免费 — 无需服务器、无需按文档付费，也没有推理成本。

本工具由 Remediate 为发布公共部门文档的团队开发和维护。

安装

# Run without installing
npx -y pdf-a11y-audit ./document.pdf

# Or install the CLI
npm install -g pdf-a11y-audit
pdf-a11y-audit ./document.pdf --format html --out report.html

本工具已发布到 npm，名称为 pdf-a11y-audit，并已列入官方 MCP Registry，标识为 io.github.Veduis/pdf-a11y-audit。

如果你更喜欢从本地克隆的仓库开始，请克隆仓库、运行 npm install，然后使用 node bin/cli.js。

CLI

# Markdown to the terminal
pdf-a11y-audit budget.pdf

# A self-contained HTML report
pdf-a11y-audit budget.pdf --format html --out budget-a11y.html

# JSON for a pipeline
pdf-a11y-audit budget.pdf --format json --out budget-a11y.json

# Fail a build on serious or critical findings
pdf-a11y-audit budget.pdf --fail-on serious

# Audit every PDF in a folder
pdf-a11y-audit ./public-docs --format csv

选项	默认值	含义
--format json|markdown|html|csv	markdown	输出格式
--out <path>	标准输出，或 HTML 格式下的 <name>-a11y-report.html	写入文件
--fail-on <severity|none>	serious	达到或超过此严重性时以状态码 1 退出
--max-findings <n>	500	限制每份文档的检查结果数量
--quiet	关闭	仅打印最终摘要

MCP 服务

此软件包提供基于 stdio 的 MCP 服务。它不会建立网络连接。

Claude Desktop / Cursor / 任意 MCP 客户端

{
  "mcpServers": {
    "pdf-a11y-audit": {
      "command": "npx",
      "args": ["-y", "pdf-a11y-audit", "--mcp"]
    }
  }
}

对于本地克隆的仓库：

{
  "mcpServers": {
    "pdf-a11y-audit": {
      "command": "node",
      "args": ["/absolute/path/to/pdf-a11y-audit/bin/mcp.js"]
    }
  }
}

其中包含一个最精简的客户端。它会启动服务、调用 audit_pdf，并按服务返回的原样打印结果：

node examples/mcp-client.mjs ./document.pdf
MCP_TRACE=1 node examples/mcp-client.mjs ./document.pdf | head -n 30

也可以通过 CLI 入口使用 --mcp 启动同一服务；Registry 清单和上述 npx 配置都采用这种方式。

工具

工具	功能
audit_pdf	审计一份本地 PDF。返回 JSON、Markdown 或独立 HTML 报告；output 可将结果写入文件。
audit_batch	审计一个或多个文件夹中的所有 PDF，并返回比较表。
explain_finding	说明一条规则、其标准映射及修复方法。
list_checks	列出规则目录，包括手动检查项。
compare_reports	比较两份 JSON 报告，并列出新增、已修复和仍存在的检查结果。
render_report	将现有 JSON 报告重新渲染为 HTML 并写入文件。

资源和提示词

• remediate://rules — 完整的规则目录。
• remediate://methodology — 说明审计能够和不能判定的事项。
• audit_and_plan — 一个提示词，可将检查结果转化为优先级明确的修复计划，且不会声称文档符合标准。

检查内容

自动化引擎涵盖：

• **文档：**标签、/MarkInfo、父树、疑似内容、角色映射、语言、显示标题、文档标题、XMP 标题、PDF/UA 声明。
• **标题：**是否存在、第一个标题级别、跳过的级别、空标题、多个 H1。
• **表格：**表头单元格、空表头、Scope/Headers、行、不规则行。
• **图形：**缺少替代文本、替代文本为空、替代文本类似文件名。
• **表单：**字段名称、工具提示、重复名称、控件结构、Tab 顺序。
• **列表：**空列表项。
• **链接：**结构父项和可访问名称。
• **字体：**嵌入字体和 ToUnicode 映射。
• **页面：**扫描页面、空白页面、文本稀疏的页面。
• **阅读顺序：**孤立或缺失的 MCID，以及顺序不匹配。
• **导航：**长文档缺少书签、空书签条目。

报告还列出了有关颜色对比度、替代文本质量、屏幕阅读器顺序、复杂表格、链接用途、OCR 准确度、表单错误以及完整辅助技术检查的人工检查。自动化检查通过不等于获得符合性证书。

HTML 报告

HTML 报告是一个独立文件，不包含外部字体、图像、脚本或跟踪功能。报告包括：

• 无障碍评分和严重性计数；
• 按影响程度从高到低排列的问题；
• 每个问题的证据和修复建议；
• 标准映射；
• 完整的自动化检查登记表，包括跳过的检查；
• 人工审查清单和局限性；
• <script type="application/json"> 块中以机器可读 JSON 格式呈现的报告副本。

报告支持响应式布局，适合打印，并支持浅色和深色配色方案。

设计原则

• **无持续费用。**无需托管服务、推理、存储或账户。
• **不搞 AI 噱头。**没有紫色渐变、发光色块或“AI 驱动”文案。报告是一份编辑文档，而不是仪表板玩具。
• **证据优先于评分。**评分只是摘要；问题才是产品本身。
• **明确报告失败，不静默处理。**不受支持的检查会标记为已跳过或需人工检查，绝不会被静默视为通过。

开发

cd pdf-a11y-audit
npm install
npm test

测试套件会生成自己的带标签和不带标签的 PDF 测试文件，测试 CLI 和 MCP 服务，并验证 HTML 报告是否为独立文件。

局限性

• 审计针对 PDF，而非客户的网站或第三方嵌入内容。
• 颜色对比度、替代文本质量以及阅读顺序的含义需要由人工借助屏幕阅读器检查。
• 格式错误或已加密的 PDF 可能会导致任何解析器都无法读取其结构。
• 本工具不提供法律建议，也不构成符合性证书。

许可证

MIT © Veduis。由 Remediate 构建。