pii-guard
繁體中文（台灣）個人資料去識別化工具。把文件裡的個資換成可還原的代號，讓你能用雲端 AI 處理機敏文件，處理完再換回來。偵測與還原全程在你自己的機器上跑。
English summary — Reversible PII de-identification for Traditional Chinese (Taiwan) documents.
核心去識別化不需要啟動 Ollama。它可以先用本機的規則與中文辨識模型快速產出去識別化副本，再由使用者在本機網頁介面補遮漏網資料或放回誤遮內容。需要更高召回率時，才選擇加入 Ollama 的本地稽核。
Most tools that strip PII before an LLM call are network gateways (LiteLLM + Presidio, PrivAiTe, AI Security Gateway) and they work well. None of them handle Taiwanese PII: national ID and ARC numbers, 統一編號 business IDs, local phone formats, or Traditional Chinese personal and organisation names — which need CKIP's Chinese NER rather than an English model with the locale switched.
This fills that gap, and differs in one more way: it produces a redacted file you can keep and hand to someone, not a per-request proxy. Detection is Presidio + CKIP BERT + Taiwan regex; substitution and restoration are plain code, so restoration is exact. A bundled Claude Code skill runs the whole thing without letting the cloud agent read the original.
Everything below is in Traditional Chinese. Start at 安裝.
為什麼還要一個？
處理「送進 LLM 之前先遮個資」的工具已經很多，而且做得好——但它們幾乎都是網路層的 gateway，攔在你的程式和模型供應商之間。
它們沒有處理的是台灣的個資：身分證與居留證字號、統一編號、本地電話格式，以及繁體中文的人名與組織名——後者需要中研院的 CKIP 中文 NER，不是英文模型換個語系就行。
這個專案補的是那一塊。另外還差一件事：它產出的是一份你可以留存、可以交給別人的檔案，不是逐次請求、用完即逝的代理。
實際輸出
下面是真的跑出來的，不是示意圖。輸入：
客戶：王小明
聯絡電話：0912345678
電子郵件：[email protected]
身分證字號：A123456789
所屬公司：範例科技股份有限公司（統一編號 10000009）
通訊地址：臺北市中正區忠孝東路一段
案由：本季顧問合約續約，金額新臺幣 30 萬元，付款分兩期。
uv run python -m pii_guard anonymize input.txt -o out.txt -m map.json 之後：
客戶：<PERSON_1>
聯絡電話：<TW_MOBILE_1>
電子郵件：<EMAIL_ADDRESS_1>
身分證字號：<TW_NATIONAL_ID_1>
所屬公司：<ORG_1>（統一編號 <TW_BUSINESS_ID_1>）
通訊地址：<LOCATION_1>
案由：本季顧問合約續約，金額新臺幣 30 萬元，付款分兩期。
七項個資全部換成代號，而金額、合約條款、日期原封不動。這是刻意的——把那些也拿掉，文件就沒有送進 AI 的意義了。
對照表另存一份，AI 回答完之後用它換回真名，逐字精確。
指定保留公開機構名稱
有些文件需要保留法院、醫院或公司名稱，才能讀懂上下文。anonymize 可在這一次處理時，只保留你明確指定且被偵測為 ORG 的完全相同名稱：
uv run python -m pii_guard anonymize judgment.txt \
--allow-org "臺灣士林地方法院" \
--allow-org-file public-organisations.txt
public-organisations.txt 每行一個名稱；空行和 # 開頭的註解會忽略。這份檔案只是本次文件規則，不會寫成永久白名單。它只跳過 ORG 偵測結果，不會改變其他仍被偵測到的類型，例如電話或身分證；也不會用文件類型猜測哪些組織可公開。
把名稱加入名單，就是你親自決定該值可保留；它不是模型已證明那是公開機構的意思。若人名或私人機構被誤判成 ORG，也可能因此留在輸出，所以不確定時請不要加入，改用補標介面逐筆放回。
人工補標介面
偵測層是機率性的，會有漏網，也會把不該遮的機構名遮掉。skill 因此提供一個在你自己的瀏覽器開的頁面：選取任何仍然裸露的文字就補遮（全文所有出現位置一起遮），點任何代號就看到背後的真實值，決定要不要放回。
上面這段是實際操作（示範用的判決書為虛構文件）。開頭那份判決書連「臺灣士林地方法院」都被切成兩個代號，看不出是哪個法院判的；點下去看到真實值，決定放回。醫院名更能說明偵測層的性質——同一家醫院在同一份文件裡，一處被整個吃掉、另一處只吃掉前兩個字，前後判成不同類別。最後圈選補遮漏網的公司名，全文所有出現位置一起遮。
靜態圖裡藍色的 MANUAL-1 是使用者補遮的證人姓名——他只圈了一處，三處同時變成同一個代號。MANUAL-2 是補遮的法官。紅色那些是偵測層自動抓到的，其中 ORG-1、ORG-3 是法院與醫院，點下去可以放回原文，判決書才讀得下去。
這一頁呼叫端連不上：網址帶一次性 token，在私有子行程內產生、只交給它自己開的瀏覽器，從不印出；回執只有數量，沒有網址。
這不是什麼
想要「所有雲端請求自動遮蔽、不用逐份處理、可批量」——你要的是 gateway，不是這個，請去用 LiteLLM + Presidio 或 PrivAiTe。它們做得比較好，我不打算重做一次。
這個專案適合的是：單份重要文件，你要一份可留存的去識別化版本，而且文件是繁體中文的。
它也不是機密分級工具。它遮的是「能指認到特定個人」的資訊。金額、病情、行程、合約條款只要不指向個人就會留著。不要單憑它宣稱「整份文件可以對外」。
還在做的事
第一階段的快速模式與完整本機網頁入口已完成。它們與 skill 的快速路徑共用同一個私有工作目錄、對照表與還原核心；一般 JSON、下載內容與 HTML 只會有去識別化文字、代號與工作編號。網頁伺服器預設只繫結 127.0.0.1，不提供加強模式的假入口。
第二階段也已加入文字型 PDF 的本機快審：瀏覽器上傳後只在記憶體中抽取可選取文字，再交給同一套 quick 私有工作核心。可下載去識別化 UTF-8 文字或安全的獨立 HTML。CLI 的多格式讀取與寫回現在都在有界的私有子行程中執行；PDF 可輸出與原頁面尺寸相同的去識別化 PDF，無法定位個資時會拒絕產檔。掃描型／圖片型 PDF 與 OCR（文字辨識）仍留待後續工作。
進階原生 PDF 整合（自行評估）
本專案的 PDF 輸出以點陣化作為安全下限：它會移除原本的文字層，代價是輸出檔不再能搜尋或複製未遮蔽文字。若你需要保留可搜尋的原生 PDF，可自行評估把本工具的遮蔽座標接到提供「真正移除內容」能力的 PDF 函式庫，例如 PyMuPDF。
這不是本專案內建或支援的整合。 PII Guard 不會安裝、呼叫或提供 PyMuPDF 的一鍵設定、程式碼或相容性保證；自行整合者必須自行確認其 AGPL 或商業授權是否適用，也必須自行承擔驗證責任。
安全上，請只在每筆個資都能以同一 PDF 引擎完整定位、完成真正移除、清理附件／metadata／JavaScript，並重新確認原始個資無法從輸出檔抽取時才交付。任何一項不確定時，應退回本專案的點陣化 PDF 輸出，而不是以視覺遮蓋取代實際移除。
歡迎有興趣協作者一起試用，也歡迎所有的提意見跟 PR。
安裝
需要 Python 3.13（3.11 以上可跑）、uv、以及 Ollama（只有加強模式與 skill 的稽核層需要）。
git clone https://github.com/danyuchn/pii-guard.git
cd pii-guard
uv sync
# 本機網頁要處理 PDF，或 CLI 直接處理 .docx / .xlsx / .pdf 時再加裝
uv sync --extra formats
首次執行會下載 CKIP BERT NER 模型（約 500MB）。未加裝 formats 時，tests/test_file_handlers.py 的 10 個測試會因缺少套件而跳不過，屬預期行為。
平台支援
macOS 與 Linux 是主要平台。Windows（NTFS）可以跑核心流程——anonymize／restore、quick、quick-restore、本機網頁與 PDF 快審、測試套件——但有三件事必須知道：
- 私有目錄 ACL：NTFS 沒有 POSIX 權限位。Windows 新建 jobs root 時會移除繼承，限定目前使用者、SYSTEM 與 Administrators 完全控制，並在使用前讀回驗證。jobs root 必須位於使用者設定檔內；父目錄若允許其他帳號建立、刪除或置換子項目也會拒絕。既有或自訂 root 任一檢查不符便 fail-closed。常駐 hook 服務的 home（
~/.local/share/pii-guard/hookd/，內含每個 session 的對照表）套用同一組 ACL 與父層檢查，差別是既有 home 會被收緊而非拒絕，細節見 examples/claude-code-hookd/README.md。威脅模型一節的 0600／0700 敘述以 POSIX 為準。
- 鎖語意：Windows 以
msvcrt byte-range lock 替代 flock，共享鎖一律降級為互斥鎖——序列化變多，保護不變少。
- 加強模式不可用：Ollama listener 驗證依賴
lsof，Windows 上會以 LOCAL_MODEL_UNVERIFIED 拒絕啟動（fail-closed）。快速模式與人工補標不受影響。
Claude Code Skill
本 repo 內含 pii-safe-documents skill，位於 .agents/skills/pii-safe-documents/。它在 CLI 之外做兩件事：
- 不讓主 agent 讀到原始文件、對照表與還原結果——讀檔、呼叫模型、還原都在獨立的本地行程裡完成，主 agent 只拿到路徑與回執。
- 在決定性偵測之後加一層本地模型稽核，補偵測層抓不到的漏網（真實判決書的簽名欄人名就是這一類）。
安裝方式是連結進 skills 目錄，不要複製：
ln -s "$(pwd)/.agents/skills/pii-safe-documents" ~/.claude/skills/pii-safe-documents
ollama pull ornith-1.5:9b
用連結而非複製，是因為 skill 需要找到它所屬的 repo 才能呼叫 pii-guard 本體。只能複製的環境改設 PII_GUARD_HOME 指向 clone 出來的路徑。
想把保護擴到「Claude Code 每一次工具讀取」而不只是單份文件，跑 uv run pii-guard-hookd install 裝上常駐服務 hookd 與其 classic hooks，說明見 examples/claude-code-hookd/。
同一個服務另有一個 Claude Mods 前端，用 uv run pii-guard-hookd install --mod 安裝。規則與涵蓋範圍一樣，但它的攔截點跑在 Edit 自己比對 old_string 之前，所以帶佔位符的 Edit 不會再失敗；prompt 也從「整則擋掉」改成「改寫」。說明見 examples/claude-code-mod/。
This is the beginning of the README. Read the rest at the original. Read the full README ↗
