pdf-processing

PDF 处理

保留原件，根据实际可用的工具选择处理方式，并验证文档结构和渲染效果。

输入

收集或说明：

• 源文件、请求的操作、目标位置、命名约定以及页面顺序／范围。
• 优先考虑的是布局保真度、文本可搜索性、文件大小、无障碍性、存档质量还是打印输出。
• OCR 语言、表格／图像要求、表单字段、注释、书签、链接和元数据预期。
• 通过经批准的安全渠道提供的密码或签名凭证；绝不要在聊天中索要私钥。
• 内容是否机密，以及是否要求仅在本地处理。

明确含糊的页面引用：人工标注的页码可能与从 0 或从 1 开始的物理页码不同。

输出约定

返回：

1. 位于明确路径的新输出文件；绝不静默覆盖源文件。
2. 在可确定时，提供源文件和输出文件的 SHA-256 哈希值、字节大小、页数和加密状态。
3. 简明的操作日志：使用的工具、选项、页面映射、OCR 语言、删除内容和元数据变更。
4. 结构、内容和渲染效果的验证依据，以及局限性。
5. 关于密码、签名、无障碍性、字体、OCR 或主动内容的注意事项。

如果检查只是启发式的，或某页无法渲染，不要声称结果完全准确。

工作流

1. 保留并检查

• 确定精确的输入路径，并在进行任何更改前计算哈希值。
• 写入新文件或临时工作副本。绝不直接修改唯一的源文件。
• 从此技能目录运行无依赖的结构检查器：

python3 scripts/inspect_pdf.py /path/to/input.pdf --pretty
python3 scripts/inspect_pdf.py /path/to/input.pdf --output /path/to/report.json --pretty

默认扫描会读取字节，而不调用 PDF 解析器。使用 --output 时，它会拒绝与输入别名相同的路径和非普通文件目标，然后通过同级临时文件原子创建或替换报告。只有在确认文件可信、足以进行解析后，或在验证第 2 步中的不可信输入沙盒配置后，才使用 --deep。明确说明此决定：

python3 scripts/inspect_pdf.py /path/to/input.pdf --deep --trust-level trusted --pretty
python3 scripts/inspect_pdf.py /path/to/untrusted.pdf --deep --sandbox-profile-confirmed --pretty

将 JavaScript、启动操作、自动操作、嵌入文件和富媒体视为惰性风险；不要激活它们。

2. 选择可用的工具链

在选择方法前，盘点已安装的工具和库。阅读 tool-routing.md，根据能力选择处理方式并了解回退行为。优先选择能保留所需特性的工具；文本提取器不是页面编辑器，栅格化也不是忠实且可编辑的转换方式。

对于不可信 PDF，只能在一次性、低权限沙盒中解析或渲染；沙盒不得包含机密或具备网络访问能力，并且必须使用只读源文件挂载、隔离的临时文件／输出存储，以及 CPU、内存、进程、文件大小、页数和时间限制；同时不得与宿主机查看器、Shell、URL 处理程序或剪贴板集成。配置解析器／渲染器，禁用 JavaScript、OpenAction／附加操作／启动操作、表单提交、外部 URI 获取、附件提取／打开、富媒体，以及自动字体／资源下载。针对确切的工具／版本验证这些控制措施。如果可用的解析器或渲染器无法满足此配置要求，请在原始字节检查后停止，并报告能力缺口。

如果没有合适的依赖项，请说明缺少的能力，并提出安装建议或替代工作流。未经许可，不要安装软件或上传 PDF。

3. 建立视觉和内容基线

在进行任何对布局敏感的更改之前，先使用可信的本地查看器打开或渲染可信的原件。对于不可信的原件，只能使用第 2 步中经过验证的沙箱配置；如果该配置不可用，请停止操作，不要解析或渲染。检查有代表性的页面以及所有将要更改的页面。记录页数、尺寸／方向、是否支持搜索文本、表单字段、注释、书签、附件、加密情况，以及明显的字体或图像问题。

对于扫描页面，判断是否需要 OCR。除非用户明确要求进行破坏性清理，否则应保留原始图像层。

4. 执行最小幅度的转换

• **提取：**保留阅读顺序的不确定性、页码引用、表格结构和 OCR 置信度。不要臆造缺失文本。
• **合并／拆分／重排／旋转：**明确页面映射，并在需要时保留书签、标签、表单和元数据。
• **创建／转换：**谨慎嵌入或替换字体；明确页面尺寸、页边距、链接、标题和无障碍要求。
• **填写／添加注释：**区分注释与扁平化的页面内容，并在有用时保留可编辑副本。
• **涂黑：**使用真正的对象级涂黑，而不是彩色矩形。根据范围移除底层文本／图像、相关元数据、评论、附件和隐藏图层。将内容完全重写到新的 PDF 中，并禁用增量保存；输出中不得保留先前的修订、原始对象流或附加的历史字节。
• **压缩：**评估视觉损失以及文本／搜索能力的变化；未经授权，不要进行有损栅格化。
• **加密／签名：**确认算法、权限、身份和密钥处理方式。任何签名后的更改都可能导致签名失效。

先处理到临时输出文件；只有验证通过后，才将其移动或复制到最终请求的路径。

5. 验证结构和内容

按照 verification-checklist.md 执行。至少应做到：

• 如有条件，使用独立的阅读器或解析器重新打开输出文件。
• 确认文件魔数、EOF 标记、页数／顺序、尺寸、加密情况和预期元数据。
• 对于应保持不变的内容，逐页比较提取的文本或 OCR 结果。
• 根据具体情况确认表单值、书签、链接、注释、附件和签名。
• 对于涂黑内容，搜索提取的文本并检查页面对象，或使用第二个解析器；仅凭视觉遮盖并不足够。确认输出已完全重写，不含保留的增量修订，也未保留原始字节或已涂黑对象。

6. 渲染并检查

根据适用的信任／沙箱配置，渲染所有已更改页面以及有代表性的未更改页面样本。以清晰可读的分辨率检查是否存在裁切、字形缺失、表格错位、图像损坏、空白页、旋转错误和涂黑信息泄漏。对于篇幅较短或风险较高的文档，应检查每一页。只有在信任分类和活动内容控制允许时，才在用户指定的查看器中打开最终文件。

7. 提供交付内容和证据

对于复杂或受监管的工作，请使用 processing-record-template.md。报告输出路径、哈希值、已执行的验证、失败情况和未经测试的行为。仅在需要的时限内保留临时产物，并且只在获得授权后删除。

安全与权限边界

• 除非用户明确批准特定服务及其数据处理方式，否则请将机密 PDF 保留在本地。
• 切勿执行嵌入式脚本、启动操作、宏、媒体或附件。
• 不得绕过密码、访问控制、数字版权或签名。
• 不得在日志中暴露密码、私钥、个人数据或文档内容。
• 将真正的涂黑、应用签名、提交表单和发布视为需要明确界定范围的高影响操作。
• 不得声称 OCR 对法律、医疗、财务或身份数据具有权威性；必须由人工核验。
• 若没有使用相关验证器并取得证据，不得声称符合 PDF/A、PDF/UA、无障碍、证据或签名要求。

恢复

如果处理失败，请分别保留源文件和失败的输出，记录确切的命令、工具、版本和错误，并从未更改的原文件重试。如果在发现缺陷前已分发输出，请找出受影响的版本和接收者，但未经授权不得撤回或替换文件。如果怀疑涂黑内容泄漏或签名密钥暴露，请立即停止分发并升级处理。

示例

提取扫描版合同

请求：“将这份 38 页的扫描版合同提取为带页码引用的可搜索文本。”

对原件进行哈希校验并渲染，使用指定语言进行 OCR，保留 PDF 图像层，逐页抽查姓名和数字，标出低置信度段落，并交付附有物理页码引用的文本及 OCR 限制说明。

合并董事会资料包

请求：“按议程顺序合并这五份 PDF 并添加书签。”

确认顺序和页码映射，合并为新文件，保留页面方向和尺寸，添加书签，用第二个阅读器重新打开，渲染边界页，并报告最终页数和哈希值。

涂黑客户标识符

请求：“在公开分享这份 PDF 前，删除账号编号。”

定义标识符模式和所有受影响页面，将真正的涂黑应用于副本，移除指定范围内的元数据、评论和附件，使用独立解析器进行搜索和检查，渲染所有涂黑页面，并说明没有仅靠视觉方框来实现涂黑。