docs-masked

在将文档发送到语言模型之前，在本地对其进行脱敏处理——并在收到响应后反向替换。

文档永远不会以原始形式离开机器。个人数据会被替换为稳定的标签（#PERSON_1#、#PHONE_2#、#ADDRESS_1#），只有带标签的文本才会发送给模型，而收到的响应会根据本地安全映射进行恢复。

документ ──▶ маска ──▶ контроль утечки ──▶ модель ──▶ обратная подстановка
           локально      локально          сеть           локально

它既可以作为 Claude Code 的技能使用，也可以作为任何其他代理的 MCP 服务器使用，还可以作为普通的命令行工具使用。

工作原理

1. 掩码。 文档被解析为文本片段——段落、单元格、标记节点。在每个片段中查找个人数据，每个值都会获得一个稳定的标签。同一个人在整个文档中获得相同的标签，包括格的变化和缩写："Иванов Иван Иванович"、"Иванову" 和 "Иванов И.И." 都是同一个 #PERSON_1#。

2. 泄漏控制。 掩码后的文本会再次通过所有检测器，外加一次偏执检查：任何 @、任何七个或更多数字的序列、任何类似电话号码的组合。如果发现任何残留，发送操作会被阻止并抛出异常，而不是在日志中发出警告。

3. 发送。 只有带标签的文本才会发送到外部。唯一的网络出口点是 llm.send() 函数，并且它必须在请求之前执行检查。每次发送都会记录到 ~/.pii_shield/egress.jsonl 日志中：时间、提供商、模型、大小、sha256、检查状态。内容不会被记录。

4. 反向替换。 模型的响应会通过安全映射：标签被替换为原始值。对于全名，会恢复为主格形式——如果文档中某人仅被提及为 "Кузнецову Ивану Петровичу"，那么在响应中他将变为 "Кузнецов Иван Петрович"。

Related MCP server: Doc Sanitizer MCP Server

安装

git clone https://github.com/kpshinnik/docs_masked.git ~/.docs_masked/src
cd ~/.docs_masked/src && ./install.sh

脚本将安装依赖项，将技能放置在 ~/.claude/skills/docs-masked 中，并打印出准备好的 MCP 配置片段。详细信息和选项请参阅 docs/INSTALL.md。

连接到代理

每种 harness 的详细步骤请参阅 docs/HARNESSES.md。

MCP 服务器无需依赖：只需要 python3。它提供六个工具——mask_text、unmask_text、verify_text、scan_document、mask_document、unmask_document。

使用

docs-masked scan   договор.docx                    # что будет скрыто
docs-masked mask   договор.docx                    # маска + сейф
docs-masked report договор.docx --open             # посмотреть глазами
docs-masked ask    договор.docx -p "Найди риски по срокам"
docs-masked unmask договор.masked.docx --vault договор.docx.vault.json

命令

完整标志列表请参阅 skills/docs-masked/references/cli.md。

可识别的内容

任何格的全名（俄语、拉丁字母、音译）、组织、地址、电子邮件、电话号码、护照及部门代码、SNILS、INN、OGRN、KPP、BIK、结算账户、银行卡、IBAN、强制医疗保险保单、驾驶执照、车牌号、IP 地址、@昵称、出生日期和证件签发日期、凭证代码（OKTMO、OKPO、KBK），以及您自定义的字符串。

标识符会进行真实校验：SNILS 校验和、INN 和 OGRN 的校验位、银行卡的 Luhn 算法、IBAN 的 mod-97。完整表格请参阅 references/coverage.md。

格式

DOCX 通过 XML 遍历，而不是通过 document.paragraphs：否则会丢失内容控件和标注内的段落——在实际合同中，这会导致整个凭证块列丢失。在表格中，列标题用作上下文：单元格 500100732259 本身与随机数无异，但在“INN”列中则能被可靠识别。

Python API

from pii_shield import ask_document

res = ask_document("договор.docx", "Составь резюме и найди риски",
                   provider="anthropic")
print(res.answer)          # имена уже восстановлены

手动控制每一步：

from pii_shield import mask_text, assert_clean, unmask_text

r = mask_text(raw)                 # r.text — с тегами, r.vault — сейф
assert_clean(r.text)               # LeakGuardError, если что-то осталось
answer = call_model(r.text)        # наружу уходит только маска
final, unknown = unmask_text(answer, r.vault, mode="canonical")

更多信息请参阅 references/api.md。

安全映射

安全映射是连接标签与原始值的唯一纽带。没有它，反向替换是不可能的。

• 与文档一起写入为 <文件>.vault.json，权限 0600。

• 通过 --pass-env 标志加密（scrypt + Fernet）。

• 存储规范形式、所有遇到的变体以及按文档顺序的出现日志——由于日志的存在，精确恢复会返回原始词形，而不是规范形式。

• 已添加到 .gitignore。不要提交它。

准确性与边界

该工具的设计原则是在安全方面犯错：宁可多掩码，也不遗漏。需要了解的事项：

• 没有文本层的扫描 PDF 无法处理——需要 OCR。

• 没有缩写名的同姓者 会获得单独的标签，而不会合并为同一个人。

• 没有上下文的裸数字 可能不会被识别为标识符——但偏执检查仍然不会让这样的文本泄露出去。

• 没有斯拉夫语结尾且没有称呼（Mr.、Dr.）的任意拉丁名字 不会被识别：捕获任意一对大写单词带来的弊大于利。

对于关键文档，建议用肉眼查看一次 docs-masked report。

开发

python3 -m pytest tests/ -q          # тесты
python3 -m pii_shield.cli selftest
python3 samples/make_samples.py      # пересоздать тестовые документы

不可违反的不变量列在 AGENTS.md 中。 sample/ 中的所有内容都是合成的；examples/ 目录保留用于您的本地文档，不会进入仓库。

许可证

MIT。