remediate-pdf

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Nutrient Remediate PDF

Nutrient PDF无障碍修复

Remediate an existing PDF by auto-tagging it with PDF/UA semantic structure — headings (H1–H6), lists, tables (TR/TD/TH), reading order, and artifact marking — via the dedicated Nutrient DWS Accessibility API. The script uploads a PDF and writes back the remediated, tagged PDF.

This skill ships auto-tag only. The DWS Accessibility API does not currently expose a separate accessibility conformance validation endpoint (confirmed by live probe — see
references/accessibility-api-reference.md
). To check tagged output today, use the bundled standalone verifier —
uv run scripts/verify-pdf.py --input doc-tagged.pdf --profile pdfua
— which checks structural PDF/UA-1 signals and escalates to a full veraPDF audit when veraPDF is installed. It is not a certification. (The same verifier ships with the
make-pdf
skill.)

通过专用的Nutrient DWS Accessibility API，为现有PDF自动添加PDF/UA语义结构标签（标题H1–H6、列表、表格TR/TD/TH、阅读顺序以及 artifact 标记），完成PDF的无障碍修复。该脚本会上传PDF并将修复后的带标签PDF写回本地。

此技能仅支持自动标记功能。目前DWS Accessibility API未开放独立的无障碍合规验证端点（已通过实时探测确认——详见
references/accessibility-api-reference.md
）。目前如需检查标记后的输出结果，请使用附带的独立验证工具：
uv run scripts/verify-pdf.py --input doc-tagged.pdf --profile pdfua
，该工具会检查PDF/UA-1的结构信号，若已安装veraPDF则会升级为完整的veraPDF审计。但这并非官方认证。（
make-pdf
技能也附带了相同的验证工具。）

When to use

使用场景

"Make this PDF accessible" / "auto-tag for screen readers"
"Tag this PDF for PDF/UA" / "remediate accessibility"
"Prepare this document for Section 508" (the tagging step)

"让此PDF具备无障碍特性" / "为屏幕阅读器自动添加标签"
"为PDF添加PDF/UA标签" / "修复无障碍问题"
"为Section 508合规准备此文档"（标记步骤）

Disambiguation from sibling skills

与同类技能的区分

Existing PDF vs. new PDF is the first fork:

Use this skill (
remediate-pdf
) to fix a PDF that already exists — auto-tag it for accessibility.
Use
make-pdf
(its own plugin:
```
/plugin install make-pdf@nutrient-skills
```
) to generate a NEW compliant PDF from Markdown or HTML (PDF/UA or PDF/A output with built-in verification). This plugin bundles the same
```
verify-pdf.py
```
for checking tagged output.

Both

document-processor-api

and this skill perform PDF/UA auto-tagging using the same underlying engine (the

pdf_to_pdfua

capability — confirmed from the live response's build stats). The distinction is product and account surface, not capability:

Use this skill (
remediate-pdf
) when the user wants the dedicated DWS Accessibility product: its own API key (
```
NUTRIENT_ACCESSIBILITY_API_KEY
```
), its own monthly auto-tagged-pages quota and dashboard.
Use
document-processor-api
when the user is already doing
```
/build
```
work and wants PDF/UA as one of several output targets with their Processor key, or wants
```
convert to PDF/A
```
,
```
produce PDF/UA
```
via
```
/build
```
,
```
merge
```
, or
```
sign
```
.

Do not claim the Processor "cannot auto-tag" — it can. Route on which product/key/quota the user wants, not on a capability difference. Cross-link the Processor's

pdfua

output target.

首要区分点是处理现有PDF还是生成新PDF：

**使用本技能（
```
remediate-pdf
```
）**修复已存在的PDF——为其自动添加无障碍标签。
使用
make-pdf
（独立插件：
```
/plugin install make-pdf@nutrient-skills
```
）从Markdown或HTML生成新的合规PDF（支持PDF/UA或PDF/A输出，并内置验证功能）。该插件同样附带
```
verify-pdf.py
```
用于检查标记后的输出结果。

document-processor-api

与本技能均使用相同的底层引擎执行PDF/UA自动标记（即

pdf_to_pdfua

功能——已从实时响应的构建统计信息中确认）。两者的区别在于产品及账户层面，而非功能差异：

**使用本技能（
```
remediate-pdf
```
）**适用于用户需要专用DWS 无障碍产品的场景：拥有独立的API密钥（
```
NUTRIENT_ACCESSIBILITY_API_KEY
```
）、独立的月度自动标记页面配额及控制面板。
**使用
```
document-processor-api
```
**适用于用户已在进行
```
/build
```
相关工作，希望将PDF/UA作为多个输出目标之一（使用其Processor密钥），或需要
```
转换为PDF/A
```
、
```
通过/build生成PDF/UA
```
、
```
合并
```
或
```
签名
```
等功能的场景。

请勿声称Processor「无法自动标记」——它具备该功能。应根据用户所需的产品/密钥/配额进行路由，而非功能差异。可交叉关联Processor的

pdfua

输出目标。

Setup

配置步骤

The DWS Accessibility API is a separate product with its own API key (distinct from the Processor key

NUTRIENT_API_KEY

and the Extraction key

NUTRIENT_EXTRACT_API_KEY

). Calling the Accessibility endpoint with the wrong product key returns

(malformed/unknown key) or

(valid key for a different DWS product — observed live).

Get a DWS Accessibility API key at https://dashboard.nutrient.io/.

Export it as

NUTRIENT_ACCESSIBILITY_API_KEY

(the key uses the

pdf_live_

prefix):

bash

export NUTRIENT_ACCESSIBILITY_API_KEY="pdf_live_..."

Run from the directory containing this SKILL.md:

bash

cd <directory containing this SKILL.md> && uv run scripts/autotag.py --help

DWS Accessibility API是一款独立产品，拥有独立的API密钥（与Processor密钥

NUTRIENT_API_KEY

和提取密钥

NUTRIENT_EXTRACT_API_KEY

不同）。若使用错误的产品密钥调用无障碍端点，会返回

（密钥格式错误/未知）或

（密钥有效但属于其他DWS产品——已通过实时测试确认）。

访问https://dashboard.nutrient.io/获取DWS Accessibility API密钥。

将其导出为环境变量

NUTRIENT_ACCESSIBILITY_API_KEY

（密钥以

pdf_live_

为前缀）：

bash

export NUTRIENT_ACCESSIBILITY_API_KEY="pdf_live_..."

进入包含本SKILL.md的目录运行：

bash

cd <包含本SKILL.md的目录> && uv run scripts/autotag.py --help

Operations

操作指南

autotag.py

— remediate a PDF with PDF/UA tags

autotag.py

——为PDF添加PDF/UA标签以完成修复

bash

uv run scripts/autotag.py --input doc.pdf --output doc-tagged.pdf
uv run scripts/autotag.py --url https://example.com/doc.pdf --output doc-tagged.pdf

```
POST https://api.nutrient.io/accessibility/autotag
```
,
```
Authorization: Bearer <key>
```
, always as
```
multipart/form-data
```
(field
```
file
```
).
```
--url
```
is validated (https-only, must resolve to a public address) then downloaded client-side and uploaded as bytes — the Nutrient backend never fetches the URL, so there is no backend SSRF surface (redirects are not followed).
On success the remediated PDF is written to
```
--output
```
(default
```
<input-stem>-tagged.pdf
```
).
The script prints the pages-processed and quota-unit count from the response build stats.

bash

uv run scripts/autotag.py --input doc.pdf --output doc-tagged.pdf
uv run scripts/autotag.py --url https://example.com/doc.pdf --output doc-tagged.pdf

请求地址为
```
POST https://api.nutrient.io/accessibility/autotag
```
，请求头
```
Authorization: Bearer <key>
```
，始终采用
```
multipart/form-data
```
格式（字段
```
file
```
）。
```
--url
```
参数会经过验证（仅支持https，必须指向可公开访问的地址），随后在客户端下载并以字节形式上传——Nutrient后端不会获取该URL，因此不存在后端SSRF风险（不跟随重定向）。
成功后，修复后的PDF会写入
```
--output
```
指定路径（默认值为
```
<输入文件名前缀>-tagged.pdf
```
）。
脚本会打印响应构建统计信息中的已处理页数及配额单位数量。

Decision rules

决策规则

Quota gate. Auto-tagging consumes from the monthly auto-tagged-pages quota (Free tier = 20 pages/month; quotas do not roll over and the API blocks at the limit).
```
autotag.py
```
estimates the page count and requires confirmation before any run exceeding remaining quota (when the account surfaces it) or exceeding
--confirm-over
(default 20) when remaining is unknown. Pass
```
--yes
```
to bypass for known-safe runs.
Max file size is 150 MiB per request; the script enforces this client-side before upload. For larger documents, split first with
```
document-processor-api/split.py
```
.
Do not auto-retry on a 2xx response — each call consumes quota.

配额限制：自动标记会消耗月度自动标记页面配额（免费层级为每月20页；配额不结转，达到上限后API会阻止请求）。
```
autotag.py
```
会预估页数，当剩余配额不足或超过
--confirm-over
默认值20页（剩余配额未知时）时，需要确认后才可运行。已知安全的运行可通过
```
--yes
```
参数跳过确认。
最大文件大小：每次请求的文件大小上限为150 MiB；脚本会在上传前在客户端强制执行该限制。对于更大的文档，请先使用
```
document-processor-api/split.py
```
拆分。
2xx响应请勿自动重试——每次调用都会消耗配额。

Anti-patterns

反模式

Do not represent auto-tagged output as guaranteed PDF/UA-compliant. Auto-tagging improves but does not guarantee conformance (Nutrient's benchmark cites ~96.5% PDF/UA conformance, not 100%). Check output with the bundled
```
verify-pdf.py
```
(and veraPDF for a full audit); treat the output as remediated, not certified.

Do not route

convert to PDF/A

produce PDF/UA

via

/build

merge

, or

sign

here — those belong to

document-processor-api

Do not use a Processor or Extraction key against this endpoint — it returns
```
401
```
.

请勿将自动标记后的输出结果宣传为保证符合PDF/UA标准。自动标记可改善无障碍性，但无法保证完全合规（Nutrient的基准数据显示约96.5%符合PDF/UA标准，并非100%）。请使用附带的
```
verify-pdf.py
```
检查输出结果（若安装了veraPDF可进行完整审计）；将输出视为已修复，而非已认证。

请勿将

转换为PDF/A

、

通过/build生成PDF/UA

、

合并

或

签名

等操作路由至本技能——这些功能属于

document-processor-api

。

请勿使用Processor或提取密钥调用本端点——会返回
```
401
```
错误。

Security Hardening Addendum

安全加固补充说明

Never store
```
NUTRIENT_ACCESSIBILITY_API_KEY
```
in committed files. Use process env injection at runtime (shell/export, secrets manager, or host env).
The script never prints or logs the API key, and redacts the key from any error response body before printing it.
```
--url
```
inputs are validated (https-only; the host must resolve to a globally-routable public address) and then fetched client-side with redirects disabled, so the Nutrient backend never fetches the URL — there is no backend SSRF surface. The client fetch is still operator-scoped egress: do not pass unsanitized user-controlled strings to
```
--url
```
.

切勿将
```
NUTRIENT_ACCESSIBILITY_API_KEY
```
存储在已提交的文件中。请在运行时通过进程环境注入（shell/export、密钥管理器或主机环境）。
脚本不会打印或记录API密钥，并且在打印错误响应体前会自动脱敏密钥。
```
--url
```
输入会经过验证（仅支持https；主机必须指向可全局路由的公开地址），随后在客户端获取并禁用重定向，因此Nutrient后端不会获取该URL——不存在后端SSRF风险。客户端获取仍属于运营商范围的出口：请勿将未净化的用户控制字符串传入
```
--url
```
参数。

Reference map

参考资源

```
references/accessibility-api-reference.md
```
— confirmed endpoint, request/response shape, quota model, error envelope, and the validation-endpoint probe findings.
```
references/pdf-ua-wcag-compliance-notes.md
```
— what PDF/UA auto-tagging does, PDF/UA vs WCAG, Section 508 relationship.
Sibling
```
document-processor-api/SKILL.md
```
—
```
/build
```
PDF/UA output target and the same underlying auto-tagging engine.
```
scripts/verify-pdf.py
```
— the bundled standalone structural checker for tagged output (the identical file ships in the
```
make-pdf
```
plugin; keep them in sync).
The
```
make-pdf
```
skill (separate plugin:
```
make-pdf@nutrient-skills
```
) — generate NEW compliant PDFs from Markdown/HTML.

```
references/accessibility-api-reference.md
```
——已确认的端点、请求/响应格式、配额模型、错误包以及验证端点的探测结果。
```
references/pdf-ua-wcag-compliance-notes.md
```
——PDF/UA自动标记的作用、PDF/UA与WCAG的区别、与Section 508的关系。
同类技能
```
document-processor-api/SKILL.md
```
——
```
/build
```
的PDF/UA输出目标及相同的底层自动标记引擎。
```
scripts/verify-pdf.py
```
——附带的用于标记输出结果的独立结构检查工具（
```
make-pdf
```
插件中也包含相同文件；请保持两者同步）。
```
make-pdf
```
技能（独立插件：
```
make-pdf@nutrient-skills
```
）——从Markdown/HTML生成新的合规PDF。

remediate-pdf

Original

Translation

Nutrient Remediate PDF

Nutrient PDF无障碍修复

When to use

使用场景

Disambiguation from sibling skills

与同类技能的区分

Setup

配置步骤

Operations

操作指南

`autotag.py`
— remediate a PDF with PDF/UA tags

`autotag.py`
——为PDF添加PDF/UA标签以完成修复

Decision rules

决策规则

Anti-patterns

反模式

Security Hardening Addendum

安全加固补充说明

Reference map

参考资源

remediate-pdf

Original

Translation

Nutrient Remediate PDF

Nutrient PDF无障碍修复

When to use

使用场景

Disambiguation from sibling skills

与同类技能的区分

Setup

配置步骤

Operations

操作指南

autotag.py — remediate a PDF with PDF/UA tags

autotag.py——为PDF添加PDF/UA标签以完成修复

Decision rules

决策规则

Anti-patterns

反模式

Security Hardening Addendum

安全加固补充说明

Reference map

参考资源

`autotag.py`
— remediate a PDF with PDF/UA tags

`autotag.py`
——为PDF添加PDF/UA标签以完成修复