Noirdoc

Noirdoc 是什麼？

Noirdoc 是 Claude Code 的開源「PII guard」，可在資料傳至 Claude 前將敏感資料假名化，然後以使用者控制的方式還原原始值。其核心目的是防止真實姓名、電子郵件、IBAN 及其他偵測到的識別碼進入 Claude Code 脈絡，同時您進行工作。

本頁亦描述透過其他入口點提供的相同底層方法：用於任何 LLM 工作流程的本地 CLI 遮蔽文件，以及清洗 OpenAI、Anthropic 和 Azure API 呼叫的託管代理。

主要功能

• Claude Code 的 PreToolUse 遮蔽：鉤子在 Claude Code 讀取前遮蔽受保護檔案，因此真實值不會進入 Claude 脈絡。
• 本地偵測與處理：偵測與假名化在本機執行；本頁指出無任何 API 呼叫離開您的機器「甚至不傳給我們」。
• 具本地還原的可逆映射：假名化輸出在處理後自動還原；您可執行 noirdoc reveal 在自家終端檢視原始值。
• 透過路徑規則的可設定保護：Glob 模式（例如 ./incoming/** 或 *.contract.*）決定哪些檔案需假名化；其他檔案保持不變。
• 本地儲存映射：外掛將假名化副本保存在 .noirdoc/cache/，並本地保存可逆映射（行為依 CLI 範例中的「one-shot」與「persistent」模式而定）。

如何使用 Noirdoc

• 安裝 Claude Code 外掛

  1. 新增至 Claude Code 市場：/plugin marketplace add nextaim-de/noirdoc-claude-plugin
  2. 在 Claude Code 內安裝：/plugin install noirdoc@nextaim
  3. 在 Claude Code 開啟或讀取受保護檔案；外掛會在 Claude 看見前遮蔽偵測項目。

• 工作流程後本地還原原始值

  • 在自家 shell 執行 noirdoc reveal 檢視原始值。本頁強調還原發生在 Claude Code 記錄之外。

• 用 CLI 處理本地文件工作流程

  • 安裝：pip install noirdoc
  • 範例 one-shot 往返：將檔案遮蔽至清理輸出，再使用輸出檔案還原。
  • 範例 persistent 模式使用命名空間，讓映射可在多個指令間重複使用。

使用情境

• 在 Claude Code 處理含個人或帳戶識別碼的文件：保護包含真實姓名、電子郵件、IBAN 或 ID 的檔案，讓 Claude Code 收到佔位符而非原始值。
• 批次遮蔽輸入合約或文件：使用路徑/glob 規則僅假名化特定資料夾（例如 incoming 目錄）或檔案類型（例如 *.contract.*），其他檔案不變。
• 受控檢視還原答案：保持 Claude Code 對話「乾淨」，需求時在自家終端執行 noirdoc reveal 取回原始值。
• 透過 CLI 整合至非 Claude LLM 工作流程：使用 noirdoc 本地遮蔽 PDF、DOCX 和純文字，再使用一致佔位符翻譯回應。
• 團隊清洗 LLM API 請求：需求時使用託管代理（或依本頁自託管版本），以兩行整合清洗每筆 OpenAI/Anthropic/Azure API 呼叫。

常見問題

• Noirdoc 會將我的資料傳給第三方嗎？ 本頁指出偵測在本機執行，無任何 API 呼叫離開您的機器「甚至不傳給我們」。

• Claude Code 執行期間敏感值如何處理？ 外掛在 Claude Code 傳遞前本地假名化輸入，將姓名、IBAN 和 ID 替換為佔位符。

• 我能取回原始值嗎？ 可以。外掛自動還原回應，您可在自家終端（Claude Code 記錄外）執行 noirdoc reveal 檢視原始值。

• 如何選擇哪些檔案受保護？ 本頁描述使用 glob 模式的路徑規則，決定哪些檔案自動假名化。

• Noirdoc 有不止一種使用方式嗎？ 有：本頁描述三種入口點—Claude Code 外掛、通用文件工作流程的本地 CLI，以及 API 呼叫的託管代理（可自託管）。

替代方案

• 手動預處理文件（提示前遮蔽）：您可以在將文字發送給 LLM 前自行遮蔽敏感欄位，但必須手動管理佔位符一致性和還原。
• 通用資料遺失防護 (DLP) 或內容篩選工具：這些工具有助於防止敏感資料外洩，但可能無法提供針對 Claude Code 工作流程的 reversible placeholder mapping 和回應還原。
• 其他 LLM「PII 遮蔽」中介軟體：此類替代方案通常在請求前遮蔽敏感字串；您需比較其整合方式（plugin vs proxy vs middleware）以及是否支援 reversible mappings 和本地工作流程。
• LLM API 的自託管代理解決方案：若主要需求是 API 清洗，代理式方法可集中控制，而 Claude Code plugin 則著重於 Claude Code 內的本地處理。