pii-guard: Instructions file for Claude Code

AGENTS.md

This file provides guidance to coding agents (Claude Code, Codex, and others) working in this repository. CLAUDE.md is a symlink to this file.

Project Overview

pii-guard-tw — 繁體中文（台灣）個人資料去識別化工具。將文件中的 PII 替換為佔位符後送 AI 處理，完成後自動還原，確保真實資料全程不離開本機。

Tech Stack

• Language: Python 3.11+
• Package manager: uv（必用 uv run / uvx，禁用 pip）
• PII framework: Microsoft Presidio（偵測 + 匿名化 + 還原）
• Chinese NER: ckiplab/bert-base-chinese-ner（中研院，繁體中文）
• Taiwan PII Regex: 自建 PatternRecognizer（身分證、手機、市話、統一編號）
• Pipeline: LangChain PresidioReversibleAnonymizer（mapping table 序列化/還原）

Architecture

原始文件
  ↓ [偵測層] CKIP NER + 台灣 Regex PatternRecognizer
  ↓ [替換層] 建立 mapping table → 去識別化文本
  ↓ [LLM 處理] AI 只看到佔位符版本
  ↓ [還原層] reverse replace → 還原後 AI 回答

關鍵原則：LLM 只做輔助偵測，替換與還原全由程式碼完成，decode 可靠性 100%。

Commands

# 安裝依賴
uv sync

# 執行主程式（CLI）
uv run python -m pii_guard <input_file>

# 執行測試
uv run pytest

# 執行單一測試
uv run pytest tests/test_recognizers.py::test_tw_id_number -v

# 型別檢查
uv run mypy src/

# Lint
uv run ruff check src/

# 常駐 hook 去識別化服務（install 會併好 settings 並自動啟動）
uv run pii-guard-hookd install [--engine full|regex] [--scope user|project] [--no-launchd] [--harden] [--mod]
uv run pii-guard-hookd doctor [--harden] [--mod] | uninstall
uv run pii-guard-hookd serve [--engine full|regex] [--foreground] [--session-ttl-days N]
uv run pii-guard-hookd status | stop | purge [session_id|--all]

# 參考名單：把客戶名單（xlsx/csv）的欄位對應存成描述檔，值留在原檔
uv run pii-guard-hookd terms inspect <表格> [--sheet 名稱] [--json]
uv run pii-guard-hookd terms import <表格> [--map 姓名=PERSON,金額=SKIP] [--yes] [--materialize]
uv run pii-guard-hookd terms status | remove <表格>|--all | ui

PII Types Supported

類型	方式
人名、組織、地名	CKIP NER
身分證字號	Regex
外籍居留證	Regex
手機號碼（本地）	Regex
手機號碼（+886）	Regex
市話	Regex
統一編號	Regex + context
Email、信用卡	Presidio 內建（zh 覆寫）
車牌	Regex + context
出生日期	Regex + context
銀行帳號	Regex + context