使用说明

🛡️ PII Shield

Anonymize documents before Claude sees them. Restore real data after analysis.

PII Shield在本地读取您的文档，用占位符替换所有个人数据(<PERSON_1>, <ORG_1>等），并且当您需要分析时，只将匿名文本发送给LLM。经过分析，PII Shield将原始数据还原到最终文档中——完全在您的计算机上。 PII从不进入API。

Document ──> [PII Shield on your machine] ──> anonymized text ──> [LLM analyzes] ──> [PII Shield restores] ──> Result
              John Smith  → <PERSON_1>                                                <PERSON_1> → John Smith
              Acme Corp.  → <ORG_1>                                                   <ORG_1>    → Acme Corp.

使用它的两种方法，共享同一个引擎：

表单	适用对象	安装
独立CLI (`pii-shield`)	任何人——在本地匿名化任何LLM文件（或仅出于合规性/GDP）。纯离线。	`npm install -g pii-shield`
Claude桌面/代码扩展 (`.mcpb` + `.skill`)	Claude Desktop和Claude Code用户——在聊天HITL面板中获取工具+技能+。	拖动 `.mcpb` 从发布到设置→ 扩展，然后上传 `.skill`

v2是一个完整的Node.js重写。 原始Python产品仍然可用——请参阅 v1怎么了？在......下面

特征

	功能	详细信息
🔒	API中的零PII	`anonymize_file` 读取机器上的文档并仅返回文件路径+会话id。Claude从磁盘读取匿名文件-PII从不输入API请求。
🧠	GLiNER零样本NER	`knowledgator/gliner-pii-base-v1.0` 结束 `onnxruntime-node` + `@xenova/transformers` （钉扎三元组1.22.0，确定性 `npm ci`).处理ALL-CAPS、域名、多语言文本。没有Python，就没有PyTorch。
👤	Human in the Loop评论	MCP Apps的iframe UI直接在Claude Desktop中呈现。删除误报，添加遗漏的实体——所有事件都会自动更新，无需绕过本地主机浏览器。
📄	PDF+DOCX+纯文本	`.pdf`, `.docx` （保留格式化+跟踪更改）， `.txt`, `.md`, `.csv`纯JS `.docx` 管道——无需安装Word/LibreOffice即可进行读取、编辑和恢复。
🇪🇺	欧盟+英国模式识别器	英国（NIN、NHS、护照、CRN、驾驶执照）、DE（税务ID、社会保障）、FR（NIR、CNI）、IT（财政代码、增值税）、ES（DNI、NIE）、CY（TIC、身份证）、FI（henkilötunnus、Y-tunnus）、欧盟范围（增值税、护照）——在通用包（电子邮件、电话、IBAN、信用卡、加密货币、美国身份证、医疗执照）之上。共35种实体类型。
🔗	实体重复数据删除	“Acme”→ `<ORG_1>`“Acme公司”→ `<ORG_1a>`“Acme公司”→ `<ORG_1b>`.规范形式选择一次；每个变体在去匿名化上都映射回相同的真实值。
💾	跨会话去匿名化	每个匿名 `.docx` 携带其 `session_id` 在Word自定义属性中。几周后，在一个全新的聊天中，将文件放入并 `deanonymize_docx` 从嵌入的id中恢复PII——无需记忆。
📦	多文件会话	将N个相关文档匿名化 `session_id`；相同的实体在文件之间共享相同的占位符。一 `deanonymize_text` / `deanonymize_docx` 呼叫可以在任何地方恢复PII。
🤝	团队交接	`export_session(passphrase)` 将映射+匿名文档打包成加密文件 `.pii-session` 存档（通过scrypt的AES-GCM）。同事跑步 `import_session` 使用密码短语，PII永远不会传输。
📊	审核日志记录	每个工具调用+响应都记录在本地 `~/.pii_shield/audit/mcp_audit.log`.NER引导跟踪、会话生命周期、删除stderr——所有这些都在磁盘上、可追加、网络外

独立CLI-- `pii-shield`

如果不使用Claude Desktop/Claude Code，请全局安装CLI并在任何文件上运行它。工作在 一次会议20-30份文件 文件之间共享占位符。

npm install -g pii-shield

pii-shield doctor                                       # health check
pii-shield install-model                                # download GLiNER (~634 MB, one-off)

# anonymize one file
pii-shield anonymize contract.pdf --no-review

# anonymize a batch — same session_id, same placeholders for shared entities
pii-shield anonymize contracts/*.pdf attachments/*.docx

# review opens a browser (localhost:6789) with the bulk-mode panel
pii-shield review 2026-04-29_101617_9f40

# restore PII back when you're done
pii-shield deanonymize contract_anonymized.pdf --session 2026-04-29_101617_9f40

命令	它的作用
`pii-shield anonymize <files…>`	在一个会话中匿名一个或多个文件。跨文件共享占位符。
`pii-shield deanonymize <file>`	恢复PII。从中读取会话id `.docx` 元数据， `--session`，或最新。
`pii-shield scan <file> [--json]`	预览检测到的实体而不写入任何内容。
`pii-shield review <session-id>`	重新打开HITL审查小组进行会议。
`pii-shield sessions list` / `show` / `export` / `import`	检查并移交机器之间的会话。
`pii-shield install-model [--yes]`	下载/解压缩GLiNER ONNX型号。
`pii-shield doctor [--json]`	检查节点、deps、模型、路径。

CLI使用与MCP变体相同的引擎、映射和审核日志。会话可以互换：在CLI上匿名，在Claude Desktop上取消匿名，反之亦然——映射存储是共享的(~/.pii_shield/mappings/).需要节点22+。

克劳德桌面/克劳德代码

先决条件

克劳德桌面版（任何最新版本）
Windows或Linux:Claude Desktop提供了一个兼容的Node运行时环境。无需单独安装。
macOS：macOS .mcpb 下面捆绑了自己的Node 24.15.0。无需单独安装。

无终端命令。无需提前下载模型。 PII Shield通过您首次匿名时出现的面板处理聊天中的模型安装。

第一步——下载人工制品

选择 .mcpb 对于您的操作系统和技能包：

文件	内容	操作系统
`pii-shield-v2.2.0-windows-linux.mcpb`	约700 KB--使用主机节点	Windows/Linux
`pii-shield-v2.2.0-macos.mcpb`	约83 MB--捆绑节点24.15.0	macOS （臂64+x64）
`pii-contract-analyze.skill`	~25 KB——合约分析技能	任意

步骤2——安装MCP扩展

克劳德桌面版→ 设置→ 扩展→ 高级设置→ 安装扩展 → 选择你的 .mcpb.

在第一个工具调用PII Shield时运行 npm ci --ignore-scripts 安装一组固定的、确定性的运行时deps(onnxruntime-node, @xenova/transformers, gliner)进入 ~/.pii_shield/deps/installs/<slug>/每台机器2-3分钟一次，之后立即进行。

第三步——上传技能

克劳德桌面版→ 定制→ 技能→ + → 上传技能 → 选择 pii-contract-analyze.skill.

该技能精心策划端到端的合同匿名化+分析流程——克劳德用它来驱动 anonymize_file → HITL评论→ 分析→ deanonymize_docx 没有你把每一步都拼出来。

第四步——使用它

在Claude Desktop中启动新对话
选择 pii合同分析 技能
连接文件夹 包含您的文档（单击文件夹图标）
告诉克劳德你需要什么：

Analyze risks for the purchaser in contract.pdf and prepare a short memo

首次运行安装面板

当你第一次要求Claude匿名化任何东西时，PII Shield注意到NER模型还没有在磁盘上，并打开了一个 在聊天安装面板中。您看到两个按钮：

下载型号 --打开默认浏览器，下载 gliner-pii-base-v1.0.zip （约634 MB）。浏览器处理传输（未签名的脚本没有Defender/SmartScreen问题）。
安装下载的ZIP --PII Shield在您的Downloads/OneDrive/Desktop/Documents文件夹中查找ZIP，验证它，并将其原子提取到 ~/.pii_shield/models/，并重新初始化NER。匿名化会自动继续。

没有终端，没有脚本。后续运行将完全跳过该面板。

⚠️ 不要将文件直接附加到匿名化。 当你附加一个文件时，Claude Desktop会在API请求中发送其内容——Claude会在PII Shield处理之前看到原始数据。 连接文件夹 相反，Claude只获取文件路径并调用 anonymize_file 当地。

隐私架构

仅 文件路径 和 随机会话ID 流经API。所有匿名化和恢复都在本地进行。

阶段	发生了什么	API中的PII？
匿名化	服务器读取主机上的文件，将匿名文本写入磁盘，返回 `output_path`	❌
克劳德读	克劳德匿名阅读 `.txt` --只看到占位符	❌
审查	用户评论MCP Apps iframe中的实体（在Claude Desktop中呈现）	❌
重新匿名化	服务器在内部应用用户更正	❌
去匿名化	服务器将还原的文件写入磁盘，仅返回路径	❌
交付	Claude为用户提供文件路径。从不读取还原的文件。	❌

Human in the Loop评论

匿名化后，Claude提供了一个直接在Claude Desktop中呈现的审核步骤，通过 MCP应用程序:

克劳德打电话来 start_review --Claude Desktop在对话中打开一个面板
完整文档 颜色编码实体高亮显示
删除误报 --单击任何实体（删除所有引用）
添加遗漏的实体 --选择文本，选择类型（添加所有引用）
批准 --克劳德打电话来 apply_review_overrides，服务器会根据您的更正重新匿名

无需本地主机web服务器，无需绕过浏览器——UI是一个Vite单文件iframe，作为Claude Desktop的 ui:// MCP资源。

跨会话去匿名化

每个匿名 .docx PII Shield写带有它的 session_id Word内部自定义文档属性(docProps/custom.xml).稍后，在全新的聊天中，您可以：

删除匿名 .docx 放入一个连接的文件夹中——不需要记住会话id，没有占位符的屏幕截图，什么都不需要。
请Claude“恢复此文件中的PII。”
PII盾牌 deanonymize_docx 读取嵌入式 session_id，在中查找映射 ~/.pii_shield/mappings/，并将恢复的文件写入输入旁边。

地图实时发布于 ~/.pii_shield/mappings/ --根相同 models/, deps/，以及 audit/根目录在插件升级后仍然有效 /plugin remove 因为它在用户的主目录中，而不是Claude Desktop的每个插件的目录中 CLAUDE_PLUGIN_DATA （无论如何，MCPB插件都没有设置）。

基于时间的TTL由以下控制 PII_MAPPING_TTL_DAYS （默认值： 7天)--服务器会清理比启动时更早的映射。用它来处理更长久的事情(PII_MAPPING_TTL_DAYS=90等）通过克劳德桌面→ 扩展→ PII屏蔽→ 设置。如果在尝试去匿名化时缺少映射， deanonymize_docx 返回一个干净的错误，并提示 import_session （请参阅下面的团队切换），而不是默默地跳过实体。

平原 .txt / .md 输出没有嵌入元数据的地方，因此 deanonymize_text 工具采取 session_id 明确地作为一个论点。

多文件会话

将多个相关文档匿名化 session_id:

第一通电话： anonymize_file(path_A) --服务器返回 session_id=SID123.
第二次通话： anonymize_file(path_B, session_id="SID123") --PII Shield扩展了相同的映射。两个文件中的相同实体共享 相同的占位符 (Acme Corp. 成为 <ORG_1> 两者都有）。
您在Claude中编写了一份备忘录，其中混合了两个文件中的占位符。
一 deanonymize_text(..., session_id="SID123") 调用备忘录可以恢复各地的个人身份信息。

这 pii-contract-analyze 当用户上传N≥2个文件并确认它们属于一个事项时，技能会自动驱动此操作。看 plugin/skills/pii-contract-analyze/references/bulk-mode.md 对于完整的决策树。

团队交接——导出/导入会话

如果同事需要在不共享个人身份信息的情况下处理相同的文档：

你打 export_session(session_id, passphrase) --服务器将映射+匿名文档打包成加密文件 .pii-session 存档（AES-GCM，密钥通过scrypt从密码中导出）。
发送给他们 .pii-session 文件（电子邮件、Slack、拇指驱动器——没有密码就没用了）。
他们打电话 import_session(path, passphrase) 在他们的机器上——地图就在他们的脚下 ~/.pii_shield/mappings/ 他们现在可以 deanonymize_docx 当地。

PII永远不会在运输过程中留下匿名文件。存档格式已进行版本控制(.pii-session v1），因此未来的模式更改将保持可读性。

MCP工具

工具	说明
`anonymize_file`	在文件（.pdf、.docx、.txt、.md、.csv）中匿名化PII。退货 `output_path` 和 `session_id`.
`anonymize_next_chunk`	处理大型文档的下一块。反复呼叫，直到完成。
`get_full_anonymized_text`	完成分块匿名化。退货 `output_path`, `session_id`, `docx_output_path`.
`start_review`	打开对话回顾面板。
`apply_review_overrides`	应用审阅者更正并重新匿名。
`deanonymize_text`	还原PII——写入本地文件，仅返回路径。
`deanonymize_docx`	在.docx中还原PII，保留格式和跟踪的更改。
`get_mapping`	获取占位符键和实体类型（没有实际值）。
`list_entities`	服务器状态、支持的实体类型、最近的会话。
`resolve_path`	通过标记文件实现零配置路径解析（将VM路径映射到主机路径）。
`find_file`	在配置的工作目录中按名称查找文件。
`scan_text`	在不匿名的情况下检测PII（预览模式）。
`export_session` / `import_session`	可移植性——在主机之间传递会话。

技能模式

包括 pii-contract-analyze 技能支持：

模式	描述
备忘录	带有风险评估的法律分析备忘录
红线	使用Word本机修订标记跟踪更改
摘要	关键条款和义务概述
比较	两份文件的并排差异
批量	最多处理5个带有前缀占位符的文件
仅匿名	只是匿名，没有分析

检测到的实体类型

权威列表为 nodejs-v2/src/engine/entity-types.ts (SUPPORTED_ENTITIES).

NER基础 （ONNX运行时上的GLiNER零样本）： PERSON, ORGANIZATION, LOCATION, NRP

基于通用模式: EMAIL_ADDRESS, PHONE_NUMBER, URL, IP_ADDRESS, ID_DOC, CREDIT_CARD, IBAN_CODE, CRYPTO, MEDICAL_LICENSE

美国: US_SSN, US_PASSPORT, US_DRIVER_LICENSE

英国: UK_NHS, UK_NIN, UK_PASSPORT, UK_CRN, UK_DRIVING_LICENCE

欧盟范围: EU_VAT, EU_PASSPORT

特定国家: DE_TAX_ID, DE_SOCIAL_SECURITY, FR_NIR, FR_CNI, IT_FISCAL_CODE, IT_VAT, ES_DNI, ES_NIE, CY_TIC, CY_ID_CARD, FI_HETU, FI_BUSINESS_ID

总共35种类型（4种NER+31种模式）。

日志

日志	位置	目的
审计	`~/.pii_shield/audit/mcp_audit.log`	每一次工具调用和响应。证明只有路径和会话ID通过API。
Ner热	`~/.pii_shield/audit/ner_init.log`	Bootstrap跟踪-解析根/变压器/闪烁器的ORT路径、健全性检查结果、安装时间。
服务器	`~/.pii_shield/audit/pii_shield_server.log`	节点MCP服务器进程的stdout/stderr。

发展

所有代码都存在于 nodejs-v2/。从该目录：

# Install exact-pinned dev deps
npm ci --ignore-scripts --legacy-peer-deps

# Type-check
node node_modules/typescript/bin/tsc --noEmit

# Build the thin .mcpb (Windows / Linux + darwin via platform overrides)
npm run build:plugin

# Also build the darwin-universal .mcpb (downloads Node 24.15.0 arm64 + x64)
npm run build:plugin:mac

# MCP protocol smoke test
npm run smoke

# Focused clean-install smoke for the sharp shim + transformers + gliner
npm run smoke:sharp-shim

Project structure

PII-Shield/
├── nodejs-v2/                                        # The product
│   ├── src/
│   │   ├── index.ts                                  # MCP tool handlers
│   │   ├── engine/ner-backend.ts                     # GLiNER + ONNX runtime boot
│   │   ├── docx/ pdf/ mapping/ audit/                # Document pipelines
│   │   └── portability/                              # session export/import
│   ├── plugin/
│   │   ├── build-plugin.mjs                          # thin .mcpb builder
│   │   ├── build-mac-binary.mjs                      # darwin-universal .mcpb builder (bundles Node 24.15.0)
│   │   └── skills/
│   │       ├── pii-contract-analyze/                 # canonical skill source (SKILL.md + references/*.md)
│   │       └── pii-contract-analyze.zip              # release artefact — auto-rebuilt from the source dir by build-plugin.mjs
│   ├── scripts/
│   │   ├── smoke-protocol.mjs                       # MCP protocol round-trip smoke
│   │   ├── smoke-setup-panel.mjs                    # Setup-panel + install-tool smoke
│   │   └── smoke-sharp-shim.mjs                     # Clean-install sharp-shim smoke
│   ├── manifest.json                                 # MCPB manifest (server.type=node)
│   └── package.json
├── .github/workflows/test.yml                        # Node CI (ubuntu + windows + macos, Node 22 + 24)
├── LICENSE
└── README.md

故障排除

问题	解决方案
第一次运行很慢	第一次通话很慢 `npm ci` 进入 `~/.pii_shield/deps/` （约2-3分钟）。后续运行是即时的。
安装面板显示“找不到ZIP”	单击面板的下载型号按钮第一。浏览器保存到 `~/Downloads` 默认情况下；PII Shield还扫描OneDrive变体、桌面和文档。如果您的浏览器保存在其他位置，请设置设置→ 扩展→ PII屏蔽→ 模型下载文件夹然后再次单击“安装”。
安装面板根本不出现	面板需要Claude Desktop≥0.10（渲染 `ui://` 资源）。对于年长的房东，请克劳德打电话 `start_model_setup` 直接，或检查 `~/.pii_shield/audit/pii_shield_server.log`.
`Unsupported model IR version: 9` 老的 `onnxruntime-node` 缓存。删除 `~/.pii_shield/deps/` --下一次运行将使用固定的1.22.0三元组重新安装。
`Cannot find module '../build/Release/sharp-*.node'`	`sharp` 您的平台没有本机插件。PII屏蔽垫片截距 `sharp` 加载（纯文本NER不使用它）。如果你仍然看到这一点，那么你使用的是较旧的版本——升级到v2.2.0。
macOS：安装后服务器立即断开连接	确保您已安装 `pii-shield-v2.2.0-macos.mcpb`，不 `windows-linux`Mac版本捆绑了自己的Node，以避免克劳德桌面达尔文主机运行时启动错误。
查看面板空白	检查 `~/.pii_shield/audit/pii_shield_server.log` MCP应用程序资源错误。Claude Desktop版本<0.10无法渲染 `ui://` 资源。
工具未出现	重新启动Claude Desktop或发送任何消息——重新连接时工具列表会刷新。

v1怎么了？

v1.0.0是一个基于presidio+SpaCy+GLiNER/py构建的Python MCP服务器，作为 .dxt 捆绑。它仍然可用：

标签 v1.0.0 --固定源。
分支 python-legacy --Node.js重写前的完整树。

v2是一个完整的架构重置——Node.js，纯js .docx，MCP应用程序UI，精简 .mcpb --升级不会减少。

致谢

PII Shield建立在优秀的开源项目之上：

GLiNER + knowledgator/gliner-pii-base-v1.0 -零样本NER骨干。
onnxruntime节点 --CPU推理引擎。
@xenova/transformers --ONNX Runtime之上的tokenizer+HF权重加载器。
docx 文件 + Jzip + @再见/核心 --纯JS .docx 读/写/跟踪更改。
克劳德桌面版 +the 模型上下文协议 --主机运行时和工具界面。

作者

格里戈里莫斯卡列夫 — 领英

许可证

麻省理工学院