Local Privacy Guard（local-doc-desensitize）

在文档离开本机或交付他人前完成“检测—确认—不可逆处置—复检—审计”。隐私任务最怕静默漏检，因此没有 OCR 时可以继续处理文本层，但不得把含图片的文档声称为完整脱敏。

固定入口

以下 <skill目录> 指本文件所在目录。优先使用统一入口，便于 Qoder、WorkBuddy、TRAE Work 等 Agent 稳定调用：

python <skill目录>/scripts/run.py <doctor|detect|apply|verify|serve> [参数...]

Windows PowerShell 也可调用（首次运行自动创建 venv 并安装依赖，%USERPROFILE%\.openvino\venv\local-doc-desensitize）：

<skill目录>/scripts/run.ps1 <doctor|detect|apply|verify|serve> [参数...]

macOS/Linux 直接用 run.py。跳过自动装依赖可设 DESENSITIZE_NO_INSTALL=1。

OCR 运行档位

安装前先确认用户环境；不要为了启用 OpenVINO 而阻断没有 OpenVINO 的机器。

| 档位 | 安装命令 | 行为 | |---|---|---| | OpenVINO（推荐参赛/AI PC） | pip install -r <skill目录>/scripts/requirements-openvino.txt | OpenVINO 优先，初始化失败自动回退 ONNX | | 通用本地 CPU | pip install -r <skill目录>/scripts/requirements.txt | 使用 ONNX Runtime，不依赖 OpenVINO | | 无 OCR | 不安装 OCR 依赖 | TXT 及文档文本层仍可处理；图片覆盖标记为不完整 |

运行诊断并把结果保留为参赛或排障证据（含 OpenVINO 可用设备清单）：

python <skill目录>/scripts/run.py doctor --probe --backend auto --device auto

OCR 后端优先级为：localhost OCR 服务 → RapidOCR/OpenVINO → RapidOCR/ONNX → 旧版兼容后端 → 无 OCR。检测 JSON 和报告会记录实际选中的后端，不能仅凭安装包推断 OpenVINO 已启用。

推理设备（OpenVINO）

OpenVINO 后端支持 --device auto|cpu|gpu|npu（环境变量 DESENSITIZE_OCR_DEVICE）：auto 请求 OpenVINO AUTO，在 AI PC 上优先落到 NPU/GPU、无 NPU/GPU 时自动用 CPU；cpu/gpu/npu 指定设备。设备请求失败时自动回退引擎默认设备，绝不阻断脱敏。doctor/serve/检测/复检均记录请求设备与 devices_available 证据。

默认隐私策略

LLM 和 OCR 默认只允许 localhost，避免敏感文档意外外传。
只有用户明确同意远程处理时才传 --allow-remote。
默认脱敏方式为部分打码；用户提出角色替换时才用 --mode replace。
高置信规则项自动处理；低置信 OCR 和 LLM 项进入 uncertain，逐项向用户确认。
不覆盖已有输出；用户明确同意后才传 --overwrite。
不跳过自动复检；只有用户接受风险时才传 --skip-verify。

标准工作流

1. 确认任务

确定输入文档、输出位置和脱敏方式。用户给出目录时，先枚举支持的文件，再逐文件检测。.doc/.ppt 需先另存为新格式。

2. 检测

python <skill目录>/scripts/run.py detect "<文档>" -o "<detection.json>" --ocr-backend auto

需要纯规则模式时加 --no-llm。默认本地模型为 Ollama 的 OpenAI 兼容接口；端点不可达会降级为规则层。

读取输出中的关键字段：

high_confidence：自动处理候选；身份证包含日期和校验码验证，银行卡包含 Luhn 验证。
uncertain：低置信 OCR 或本地 LLM 候选，必须由用户决定。
ocr_engine：实际 OCR 后端及回退原因。
coverage_complete：含图片但 OCR 不可用时为 false。

3. 请求确认

逐条展示 uncertain 的 ID、类别、上下文、来源、置信度和理由。不要替用户确认。

多文档的 U1/U2 会重复。对多文档使用 --include-map，不要把单个 --include U1 套到所有文件：

{
  "合同A.pdf": ["U1", "U3"],
  "合同B.pdf": "all"
}

4. 执行与复检

python <skill目录>/scripts/run.py apply \
  "<文档>" "<detection.json>" \
  --mode mask --include U1,U3 --ocr-backend auto

角色替换用 --mode replace。多文档把文档与 detection 成对传入，并用 --include-map <json>。

apply 默认执行自动复检：重新提取文本、重新 OCR 图片并查找残留。退出码含义：

0：复检通过，或用户显式跳过复检；
1：发现残留；
2：复检覆盖不完整或参数错误。

复检不通过或不完整时，保留 detection 和临时图片供排查，不得向用户宣称“已安全完成”。

退出码与官方指南约定的映射：本 skill 用 0（通过/显式跳过）、1（发现残留）、2（覆盖不完整或参数错误）表达任务结果；run.ps1 环境自检失败（无解释器/依赖装不上）时也用 1，对应官方"平台不支持"；本 skill 无自定义模型下载器（权重由 rapidocr 首次运行自动获取），官方预留的 3（下载超时）不适用。

5. 交付

交付 <原名>_脱敏.<扩展名> 与 <原名>_脱敏报告.md，并说明：

实际 OCR 后端，是否为 OpenVINO；
自动复检状态及残留数量；
是否存在未确认项或图片覆盖不完整；
PPT/Word 的命中图片采用整图像素替换，安全优先于保留图片局部内容。

Client/Server 部署

频繁调用时启动常驻 OCR 服务，避免每次重新加载模型：

python <skill目录>/scripts/run.py serve --host 127.0.0.1 --port 8300 --backend auto --device auto

然后设置 DESENSITIZE_OCR_URL=http://localhost:8300。服务端仍遵循 OpenVINO → ONNX 回退；设备在服务端选择，客户端无需传 --device。健康检查（GET）返回实际引擎、请求设备与 OpenVINO 可用设备。

边界与限制

扫描版 PDF 依赖 OCR；无 OCR 时不会继续声称完成。
PPT 的 SmartArt、图表内嵌文字、母版和版式文字默认不扫描。
Word 文本框、批注、脚注等复杂部件可能需要人工抽查。
段落跨 run 的替换会保留段落样式，但局部加粗等格式可能变化。
文档级脱敏不能替代组织的数据分类、访问控制和人工终审。

类别、打码样式与 detection 结构见 references/sensitive-rules.md；历史易错点见 errors/common-mistakes.md。