nutrient-document-processing

Nutrient 文档处理

当文档保真度、合规性或多步工作流足以证明将用户文件传输至 Nutrient DWS 是合理的时，请使用此技能进行托管式文档处理。

产品选择

在估算费用或选择凭据之前，先选择产品：

需求	产品	此处使用的路由
转换、生成、组装、OCR、JSON 内容提取、涂黑、签名、优化、输出 PDF/A 或 PDF/UA	DWS Processor	使用 scripts/ 中固定版本的 Python 辅助脚本和 NUTRIENT_API_KEY
高保真地将文档解析为 Markdown 或空间 JSON	Data Extraction	独立的 /extraction/parse 产品、凭据和信用额度池；使用其当前官方客户端和文档
无障碍自动标记和 PDF/UA 验证工作流	Accessibility	使用当前独立的 Accessibility API/产品；不要使用已弃用的 Processor /processor/pdfua 端点

不要将 Processor 的费用估算、凭据或请求负载用于 Data Extraction 或 Accessibility。

设置

• 从 https://dashboard.nutrient.io/sign_up/?product=processor 获取 Processor API 密钥。

• 通过 Agent 主机的受保护运行时环境或密钥管理器配置 NUTRIENT_API_KEY。切勿要求用户在聊天中粘贴密钥，也不要将密钥放入命令参数、日志、生成的脚本或已提交的配置中。只验证变量是否存在，不要检查其值。

• 每个脚本都使用固定版本为 nutrient-dws==3.1.0 的 PEP 723 元数据；使用 uv run 运行。

• 从已安装的技能目录按路径运行辅助脚本。切勿假设当前目录就是技能目录。

• 页面范围从 0 开始且包含末页。0:4 表示五页。负索引从末尾开始计数。

付费运行审批关卡

每次调用辅助脚本都会将文档内容发送至外部 DWS Processor API，并消耗信用额度。每次运行前：

1. 确认具体操作以及将要传输的每个本地文件或远程 URL。
2. 从适用于该操作的控制面板或定价页面获取当前信用额度估算。
3. 向用户说明产品、操作、传输的输入、估算额度和计划的输出路径。
4. 在请求发出前立即等待批准。
5. 获批后，才传入 --estimated-credits NUMBER 和 --confirm-external-processing。

批准不会沿用至重试、批处理、第二阶段、涂黑应用或签名。不要推测性地添加确认标志。

辅助脚本选择

1. 优先使用已覆盖的 scripts/*.py 辅助脚本；它使用固定版本的类型化客户端和安全输出写入器。
2. 对于多步 Processor 作业，运行时复制并自定义 assets/templates/custom-workflow-template.py。
3. 仅在相关参考资料中引用了当前官方契约时，才使用原始请求。如果具体契约不确定，请使用类型化的 3.1.0 辅助脚本，而不要猜测。

所有输出辅助脚本都会以原子方式创建文件，并设置仅所有者可访问的权限；如果目标路径已存在，则会拒绝覆盖。重试时请选择新路径。

单操作辅助脚本

• convert.py：pdf、pdfa、pdfua、docx、xlsx、pptx、png、jpeg、jpg、webp、html 或 markdown；处理二进制、文本内容和 JSON 内容结果。
• merge.py、split.py、add-pages.py、delete-pages.py、duplicate-pages.py、rotate.py：页面和文档包操作。
• ocr.py、extract-text.py、extract-table.py、extract-key-value-pairs.py：Processor OCR 和 JSON 内容提取。
• watermark-text.py、optimize.py：交付转换。
• redact-ai.py：仅对本地 PDF 进行 AI 暂存。请先目视检查暂存结果，再单独审批应用步骤。
• sign.py：仅支持本地 PDF；需要包含 signatureType 的显式 JSON 配置文件，并会验证输出是否为 PDF 容器。请独立验证嵌入的签名和信任链。
• password-protect.py：仅从仅所有者可访问的本地文件（chmod 600）读取密码，绝不从 argv 读取。

多步骤工作流模板

不要将特定任务的流水线提交到 scripts/ 下。将模板复制到任务专用的临时路径，然后将其指向已安装的技能目录：

export NUTRIENT_SKILL_DIR="/absolute/path/to/nutrient-document-processing"
cp "$NUTRIENT_SKILL_DIR/assets/templates/custom-workflow-template.py" /tmp/ndp-workflow.py
# customize /tmp/ndp-workflow.py
NUTRIENT_SKILL_DIR="$NUTRIENT_SKILL_DIR" uv run /tmp/ndp-workflow.py --help

最终的付费调用仍需提供操作估算并设置明确的确认标志。任务完成后删除临时脚本，除非用户要求保留。

安全规则

• 仅当源文件缺少有用的文本层时，才在提取或涂黑之前进行 OCR。
• 涂黑分两步进行：创建注释，逐一目视检查所有匹配项和遗漏项，然后另行请求批准以不可逆地应用涂黑。搜索/渲染最终 PDF，以验证内容已移除。
• 签名需要明确配置 CMS 或 CAdES。签名之前完成填充、扁平化、涂黑、组装和优化；将已签名的 PDF 视为不可修改。
• 使用以 Instant JSON 或 XFDF 表示的真实表单字段数据。不要虚构 fillForm 构建操作。
• 不要将密码和签名密钥放入 argv、日志或已提交的 JSON 中。
• 将 PDF/A 和 PDF/UA 视为合规目标。在声称符合要求之前，使用用户指定的验证器验证最终产物。
• 对于新的集成，切勿调用已弃用的 /processor/pdfua 端点。

参考索引

• references/request-basics.md：产品边界、身份验证、类型化输出、审批和错误
• references/generation-and-conversion.md：当前的转换和生成模式
• references/pdf-manipulation.md：包含端点的范围和页面操作
• references/extraction-and-ocr.md：Processor JSON 内容提取与 Data Extraction 解析
• references/security-signing-and-forms.md：分阶段涂黑、签名、表单、密码和水印
• references/compliance-and-optimization.md：PDF/A、PDF/UA 路由、优化和验证
• references/workflow-recipes.md：多步骤任务的安全排序