shield_lock
JinDaGe
← Back to skills
extension
Category: Development & EngineeringNo API key required

local-doc-desensitize

面向生产力 Agent 的本地文档脱敏与隐私泄漏复检。用户要求对 Word(.docx)、PowerPoint(.pptx)、PDF、TXT 或一批办公文档进行“脱敏、打码、匿名化、隐藏隐私、外发前检查、去掉姓名/手机号/身份证/银行卡/地址”等处理时使用。通过规则、可选 localhost LLM 和本地 OCR 识别文本与图片；OCR 优先 OpenVINO，没有 OpenVINO 时自动回退 ONNX Runtime，没有任何 OCR 时仍可处理文本层并明确报告图片覆盖不完整。支持打码、同名同换、人工确认、不可逆图片处置、输出复检和审计报告。Use for local/offline document redaction, anonymization, privacy review, PII masking, and pre-share data-loss checks, including when the user does not explicitly name this skill.

personAuthor: buzhidao22066hubModelScope
downloadDownload package

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。
  • 已知清单申报值不回显到脱敏报告；检测控制台警告只显示清单项 ID 与类别。
  • 默认脱敏方式为部分打码；用户提出角色替换时才用 --mode replace。
  • 高置信规则项自动处理；低置信 OCR 和 LLM 项进入 uncertain，逐项向用户确认。
  • 不覆盖已有输出；用户明确同意后才传 --overwrite。
  • 不跳过自动复检；只有用户接受风险时才传 --skip-verify。

标准工作流

1. 确认任务

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

随后询问使用者是否有已知的敏感信息（特定姓名、手机号、证件号、地址、项目代号等）：

  • 有 → 整理为已知清单 JSON，回显确认后保存，检测时经 --known-file 传入。使用者主动申报的项视为已确认，检测命中后自动并入处理，不再逐条确认。
  • 使用者不方便在对话中粘贴时 → 让其把清单保存为本地文件，只提供路径（申报值不进会话记录）。
  • 没有/跳过 → 不传 --known-file，后续流程与无清单时完全一致。

清单格式（宽容：字符串数组即可，类别可省略）：

{ "known_items": [
  { "id": "K1", "type": "姓名", "value": "张三" },
  { "id": "K2", "type": "手机号", "value": "13812345678" }
] }

2. 检测

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

需要纯规则模式时加 --no-llm。默认本地模型为 Ollama 的 OpenAI 兼容接口；端点不可达会降级为规则层。使用者提供了已知清单时加 --known-file known.json。

读取输出中的关键字段：

  • high_confidence：自动处理候选；身份证包含日期和校验码验证，银行卡包含 Luhn 验证。
  • uncertain：低置信 OCR、本地 LLM 候选，以及校验位不通过/15 位一代证号的疑似身份证、Luhn 校验不通过的 16-19 位疑似银行卡号（不得静默漏检），必须由用户决定。
  • known：已知清单核对结果；summary.missed > 0 时必须向使用者逐项警告"检测未命中，需人工排查，不得视为已处理"。
  • ocr_engine：实际 OCR 后端及回退原因。
  • coverage_complete：含图片但 OCR 不可用时为 false。

3. 请求确认

逐条展示 uncertain 的 ID、类别、上下文、来源、置信度和理由。不要替用户确认。已知清单命中项（from_known 标记）已自动并入处理，不占用确认流程。

多文档的 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>。已知清单命中项自动包含在处理集合中，无需写进 --include。

apply 默认执行自动复检：重新提取文本、重新 OCR 图片并查找残留；已知清单项升级为必查项，输出中出现任何申报值（含全角等变体形态）即为失败。退出码含义：

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

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

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

5. 交付

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

  • 实际 OCR 后端，是否为 OpenVINO；
  • 自动复检状态及残留数量；
  • 是否存在未确认项或图片覆盖不完整；
  • 若使用了已知清单：报告含「已知清单核对」表（按隐私要求不回显申报值）；未命中项必须如实转告使用者"未找到、需人工排查"；
  • 命中图片优先按 OCR 定位框局部涂黑（像素真删除）；处置说明中若出现 "整图涂黑"，说明该命中项缺少有效定位框或图片处理异常，属安全优先的回退， 必须向用户如实说明，不得略过。

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 时不会继续声称完成。
  • 文本层按"值全局替换"处理：某敏感值若恰好作为片段嵌入更长的数字串（如订单号内嵌手机号），替换会波及该片段。检测层有数字边界保护不会误报，但 apply 的替换语义无法区分，涉及长编号文档时建议人工抽查输出。
  • PPT 的 SmartArt、图表内嵌文字、母版和版式文字默认不扫描。
  • Word 文本框、批注、脚注等复杂部件可能需要人工抽查。
  • 段落跨 run 的替换会保留段落样式，但局部加粗等格式可能变化。
  • 文档级脱敏不能替代组织的数据分类、访问控制和人工终审。

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