内容
# 隐私过滤器
即插即用的个人身份信息（PII）检测和编辑。只有一个小型Python包，提供三种接入方式：
1. **库** — 通过`pip install`安装并在进程中调用。唯一依赖：pydantic。
2. **REST API** — `privacy-filter`启动一个本地FastAPI服务器。任何语言都可以调用它。
3. **MCP服务器** — `privacy-filter-mcp`为Claude和其他LLM代理暴露了模型上下文协议工具。
4. **Docker** — 可选。包含Dockerfile，但不是必需的。
检测层：11条确定性正则表达式规则（电子邮件、英国电话号码、邮政编码、NI号码、银行详细信息、机密等）、启发式名称/地址/日期模式，以及可选的`openai/privacy-filter`令牌分类模型，用于ML级人员/地址检测。结果始终指示运行的引擎（`rules-only`或`model+rules`）。
> 新来者？请阅读纯英文的 **[概述](docs/overview.md)**，或跳转到 **[技术参考](docs/technical-reference.md)** 进行深入了解。
⭐ 如果您觉得这很有用，请给仓库一个星标——它可以帮助其他人找到它。
## 看看它的实际效果
这是 [文档编辑器示例应用](examples/document-redactor/) — 一个完全在您的机器上运行的拖放网页：
```powershell
pip install .
python examples\document-redactor\app.py
```
## 库
```powershell
pip install . # 从仓库根目录（或您克隆它的路径）
```
```python
from privacy_filter import redact
result = redact("Email jane.smith@example.org or call 07700 900123.")
print(result.text) # Email [EMAIL REDACTED] or call [PHONE REDACTED].
print(result.findings) # spans with type, offsets, confidence
```
参见 `examples/quickstart.py` 获取策略和可重用的 `Redactor` 引擎。
## REST API（无需 Docker）
```powershell
pip install ".[server]" # 从仓库根目录
privacy-filter
# -> serving on http://127.0.0.1:8081 (POST /v1/redact, POST /v1/detect, GET /health)
```
参见 `examples/rest-examples.md` 和 `.env.example` 获取配置。
## 启用 ML 模型（可选）
```powershell
pip install ".[model]" # 从仓库根目录
# 下载权重一次（或复制到隔离的机器上）：
python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='openai/privacy-filter', local_dir='models/privacy-filter', ignore_patterns=['onnx/*','original/*'])"
$env:PRIVACY_FILTER_MODEL_PATH = "C:\path\to\models\privacy-filter"
privacy-filter # /health 现在报告 "model+rules"
```
库等价于：`Redactor(model_path=r"C:\path\to\models\privacy-filter")`。
默认情况下，包 **从不下载任何内容**：`local_files_only=true` 除非您选择退出，否则服务器绑定到 `127.0.0.1`，输入文本从不记录，服务器拒绝超过 64 KiB 的请求体（`PRIVACY_FILTER_MAX_TEXT_BYTES`，默认为 `65536`）作为拒绝服务保护 — 如果您需要处理更大的文档，请提高它。
## Claude / MCP 集成
通过本地工具将模块暴露给 Claude（和任何 MCP 客户端）— 它在进程中导入库，因此没有网络跳转，也不需要额外运行：
```powershell
pip install ".[mcp]" # 从仓库根目录
privacy-filter-mcp # stdio MCP 服务器
```
通过将以下内容添加到您的 `.mcp.json`（参见 `examples/claude-mcp-config.json`）将其连接到 Claude Code / Claude Desktop：
```json
{
"mcpServers": {
"privacy-filter": { "command": "privacy-filter-mcp" }
}
}
```
暴露的工具：`redact_text(text, policy?, threshold?)`，`detect_pii(text, policy?, threshold?)`，以及 `list_policies()`。相同的 `PRIVACY_FILTER_*` 环境变量适用（模型路径、默认策略、大小限制）。
一个现成的 Claude 技能位于 [`skills/pii-redaction/`](skills/pii-redaction/SKILL.md) — 它教会 Claude 何时以及如何使用这些工具编辑 PII。复制或符号链接到您的 `~/.claude/skills/`（或插件的 `skills/`）以激活它。
## 策略
策略指定了哪些类别会被编辑（如果类别有标签，则该类别处于活动状态），用什么替换它们，以及审核阈值。预设策略：`default`，`witness_statement_external_disclosure`，`training_data_sanitisation`，`transcript_standard`，`external_sharing`。
```python
from privacy_filter import Policy, Redactor
emails_only = Policy(name="emails_only", labels={"private_email": "<email removed>"})
Redactor(policy=emails_only).redact("Write to a@b.co")
```
从库代码中加载 JSON 文件中的策略：
```python
from pathlib import Path
policy = Policy.model_validate_json(Path("my_policy.json").read_text())
```
服务器可以在启动时注册额外的策略：`PRIVACY_FILTER_POLICY_FILE=policies.json`（一个 Policy 对象的 JSON 列表）。
来自规则和启发式检测器的低置信度发现会被 **编辑并标记**（`review_required=true`，`reason="low_confidence"`），而不会被静默丢弃。可选的 ML 检测器是一个例外：它会过滤得分低于阈值的跨度（不会返回或标记），因此如果您想让临界的 ML 检测结果显示以供审核，请降低阈值。
## Docker（可选）
```powershell
docker build -t privacy-filter .
docker run --rm -p 8081:8081 privacy-filter
# 带有 ML 运行时并挂载本地权重：
docker build --build-arg INSTALL_MODEL_RUNTIME=true -t privacy-filter:model .
docker run --rm -p 8081:8081 -v C:\path\to\models\privacy-filter:/models/privacy-filter `
-e PRIVACY_FILTER_MODEL_PATH=/models/privacy-filter privacy-filter:model
```
## 开发
```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev,server,mcp]"
.\.venv\Scripts\python.exe -m pytest
```
## 文档
- **[docs/overview.md](docs/overview.md)** — 面向非技术读者的纯英文指南（它做什么、如何使用、效果如何、隐私）。
- **[docs/technical-reference.md](docs/technical-reference.md)** — 完整的 技术参考（架构、流程、数据模型、Python/REST/MCP API、配置、安全、扩展）。
- **[docs/README.md](docs/README.md)** — 文档索引。
