通过 Connect 从 PDF 移除 PII

通过 Connect 从 PDF 移除 PII

概览

本示例使用 NextPDF Connect 提供的遮蔽工具，从文档的文本图层移除已检测到的个人数据。这些工具属于 Enterprise 层级。ToolRegistry 会通过 class_exists() 探测 Enterprise 隐私类（RedactionEngine + PiiDetector），据此构建 redact_pdf、zone_redact_pdf 与 deidentify_pdf；只有在这些类能够自动加载时，才会将相应工具注册到 enterprise 层级之下。在仅安装开源版本的环境中，这些工具并不存在：调用会以未知工具错误失败，而不会静默降级。这三个工具全都声明 destructiveHint: true。这类编辑会改写页面内容，且无法从编辑后的文档还原。

本页说明工具在 Connect 接口上的行为。遮蔽工作流程并不构成某份文档在调用后已不含个人数据的认证。检测只作用于可提取的文本图层；部署方仍需自行负责验证结果。

安装

composer require nextpdf/server

只有在服务器环境中同时安装 Enterprise 隐私模块时，遮蔽工具才会注册。该模块随附于 nextpdf/premium 之中。在你依赖这些工具之前，请先确认运行中的部署已提供相应工具：

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"c","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

如果 redact_pdf 未出现在 tools/list 的结果中，说明 Enterprise 隐私类在该环境中未能解析。有关注册机制如何在启动时计算各层级工具集，请参阅 /connect/tool-catalog/。

概念总览

三个工具涵盖三种遮蔽策略。三者全都属于 Enterprise 层级，也全都带有破坏性提示：

• redact_pdf — 使用内置检测器检测并移除文档纯文本内容中的个人数据，并返回编辑后的内容以及一份结构化报告。
• zone_redact_pdf — 对纯文本内容应用基于坐标的区域遮蔽。当你根据位置而不是样式来确定要移除的区域时，请使用它。
• deidentify_pdf — 对检测到的实体系统地应用去标识化策略（遮蔽或抑制）。

从页面内容流中移除内容，是对该内容流的破坏性编辑；受影响的字节会被改写，且无法从编辑后的文档还原（ISO 32000-2 §14.11）。按设计，报告只记录每次移除的字符数与位置，绝不记录被移除的文本本身。

API 接口

每个工具的确切请求与响应结构描述，随定义它的 Enterprise 包一同提供。本页说明 Connect 的调用契约，而不是固定参数列表。经运行中注册机制验证的工具名称为 redact_pdf、zone_redact_pdf 与 deidentify_pdf，全都位于 document 类别，并带有 destructiveHint: true。依据请见工具目录 /connect/tool-catalog/。本示例不重述工具数量，因为它是部署运行时属性。

代码示例 — 快速上手

通过 MCP 检测并移除（tools/call）。下面的参数展示调用形状。权威的参数结构描述以你部署中的 tools/list 返回结果为准：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "redact_pdf",
    "arguments": {
      "source": "/var/lib/nextpdf/in/employee-directory.pdf"
    }
  }
}

调用成功后会返回一份报告。每次移除都会有一个条目，记录页面、类别标签、原始字符数以及一个边界框，而不是被移除的文本。

代码示例 — 生产环境

请将遮蔽调用视为破坏性操作，并在你发布文档之前审阅报告。在网络传输层面，传输失败与工具层级错误是彼此独立的两类情况：

curl -sS -X POST https://connect.example.com/v1/tools/redact_pdf \
  -H 'Authorization: Bearer '"$NEXTPDF_CONNECT_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"source":"/var/lib/nextpdf/in/legal-discovery-batch.pdf"}' \
  -o /tmp/redaction-report.json -w '%{http_code}' > /tmp/redaction-status

status="$(cat /tmp/redaction-status)"
if [ "$status" != "200" ]; then
  # 4xx/5xx is a normal HTTP outcome the caller inspects, not a transport
  # failure. A connection error (curl non-zero exit) is the separate case.
  echo "redact_pdf returned HTTP $status; inspect the body, do not release the document" >&2
  exit 1
fi

只有当人员或下游控制已审阅报告之后，才能发布编辑后的文档。将发布动作置于这次审阅之后，可将控制措施设在自动化编辑引入残留数据风险的那个点上（IEC 31010:2019）。

边界情况与陷阱

• 没有文本图层的扫描 PDF。 检测会在可提取的文本图层上运行。纯图像页面会产生零次移除，且这并非错误。若内容已栅格化，请在遮蔽之前先对文档进行 OCR。
• 已加密的来源。 请通过工具的参数结构描述提供文档密码。缺少密码时，调用会直接失败，而不是部分处理。
• 工具不存在。 在仅安装开源版本的环境中，Enterprise 隐私类无法解析，redact_pdf 不会被注册，因此调用会以未知工具错误失败。这是刻意设计的边界，而不是降级。
• 重叠的检测。 当多个检测器命中同一个区域时，该区域只会被移除一次，且报告会对条目去重。

性能

front-matter 中的性能预算是文档层级的上限，而不是服务等级保证。大型文档会逐页处理。请预留在某个页面范围子集上重新运行调用的空间，而不是调高全局超时。

安全注意事项

数据驻留与 PII 缓解措施

文档文本会在 Connect 主机进程内处理。报告会有意省略被移除的文本，只汇报数量与位置，因此报告本身不会重新引入其所描述的个人数据。输入与编辑后输出的数据驻留由部署层级决定，是集成方的责任，而不是工具属性。

安全的遥测与日志清洗

请勿在会向外部传送的日志级别记录来源文档路径或报告正文。只记录工具名称、请求 ID，以及 pass/fail 结果。

威胁模型

只在视觉上遮住文本、却未实际移除文本的遮蔽，会导致数据仍可被提取。这些工具会改写受影响的内容流，而不是叠加一个矩形；从编辑后的文档还原被移除的字节是不可能的（ISO 32000-2 §14.11）。残留风险来自检测器未命中的内容：超出其规则的样式，或仅以栅格图像形式存在的文本。此工作流程通过强制审阅报告来缓解这一点，而不是声称已经做到完整覆盖。

FIPS 模式行为

遮蔽不执行任何密码学运算，也不受主机上 FIPS 模式策略的影响。

符合性

主张	条款	reference_id
移除内容会改写受影响的内容流	ISO 32000-2 §14.11
遮蔽先标记再移除；移除本身是一次内容编辑	ISO 32000-2 §14.11
将控制措施设在自动化编辑引入风险的那个点上	IEC 31010:2019

支持这些遮蔽工具，并不构成处理后文档不含个人数据的认证。该判定应由独立审查作出。

商业背景

遮蔽工具属于 Enterprise 层级。只有在服务器环境中同时安装 nextpdf/premium 时，它们才会注册。请参阅 front-matter 中的转换链接。

Connect 细节

传输可用性（MCP / REST / gRPC）

在每一种由共享工具执行器驱动的传输方式中，你都以相同方式调用这些工具：MCP tools/call、REST 工具端点，以及 gRPC 服务。参数结构描述与传输方式无关，以 tools/list（MCP）或服务描述符（gRPC）返回的那一份为准。

HITL 风险层级

这三个工具全都声明 destructiveHint: true。如果操作者通过配置覆盖将某个工具提升到 approval_required 风险级别，该调用就会被置于 ConfirmationGate 之后。这种覆盖只能提高风险级别，绝不能降低。请参阅 /connect/hitl-risk-tiers/。

确认门 JSON 信封

当工具受门控控制，却在未携带有效令牌的情况下被调用时，门会返回如下形式的挑战信封：

{ "allowed": false, "challenge": "<human-readable text>", "token": "confirm_<nonce>" }

调用方随后将颁发的令牌设置到 arguments._confirmation_token，并重新调用同一个工具。该令牌绑定工具名称、一个 nonce 和一个 300 秒的 TTL，而不是绑定参数，并且只能使用一次。

另请参阅

• /connect/tool-catalog/ — 注册机制如何计算各层级的工具集。
• /connect/hitl-risk-tiers/ — 四级风险模型与该门控。
• /cookbook/connect/extract-text-content/ — 在遮蔽前先预览可提取的文本。
• /cookbook/connect/digital-signature/ — 签署编辑后的文档，以建立监管链。