透過 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/ — 簽署編輯後的文件，以建立監管鏈。