数据脱敏工具 (Data Mask)

对文档和文本中的敏感数字数据自动识别并脱敏，解决日常文件或发送给大模型时需要手动修改真实数字的重复劳动。

🎯 新手入门（直接复制就能用）

不需要读完文档，直接把需求发过来就行。几个典型开场白：

✅ "帮我把这段文字的敏感数字脱敏"
✅ "这份 Excel 表格帮我脱敏，只脱敏金额列"
✅ "这个 Word 报告要发给外包团队，帮我把数字都模糊化"
✅ "这份销售数据发给 AI 做分析，帮我脱敏但要能还原"
✅ "这个目录下所有 .xlsx 文件都脱敏一下"

脱敏后默认输出： 原文件名_mask.原后缀（如 report.docx → report_mask.docx）

能力边界说明

✅ 擅长处理

1. 对 Word/PPT/Excel/CSV/Markdown/纯文本中的数字自动识别并脱敏
2. 保留 Word/PPT 原始排版、字体、表格、页眉页脚等全部格式
3. 通过映射表完整还原 hash 和 placeholder 策略脱敏后的数据
4. 批量处理同目录下多个文件
5. 自动识别并跳过非敏感数字（ID、序号、年份等）
6. 对图片进行 OCR 识别后脱敏（需安装 Tesseract）

⚠️ 需要素材/前置条件

1. 图片 OCR 脱敏：需要安装 Tesseract OCR 引擎（文档提供各平台安装指引）
2. Excel 列级精准控制：需要提供具体的列名（或让工具自动检测数值列）
3. 还原数据：需要脱敏时保存的映射表 JSON 文件（脱敏时加 -m 参数）
4. 自定义单位：如需识别非标准单位后缀，需要在 config.yaml 中配置

❌ 超出范围（附替代方案）

1. .doc / .xls 旧格式：不支持旧版 Office 格式 → 先手动转为 .docx / .xlsx
2. 扫描版 PDF（无文字层）：自动委托 PDF skill 做 OCR → 输出为 .txt
3. JS 渲染的复杂 HTML（SPA 页面）：自动委托浏览器 skill 提取文本 → 输出为 .txt
4. 数据加密：本工具是脱敏工具非加密工具 → 需要加密请使用专业加密工具
5. 非数字敏感信息（人名、地名等）：工具只脱敏数字 → 对非数字敏感信息需人工处理

📛 输出文件命名规范

脱敏后的文件统一遵循以下命名规则：

原文件名_mask.原后缀

| 输入文件 | 脱敏后输出 |

|---------|----------|

| 运营月报.docx | 运营月报_mask.docx |

| Q2数据.xlsx | Q2数据_mask.xlsx |

| 汇报PPT.pptx | 汇报PPT_mask.pptx |

| notes.md | notes_mask.md |

| page.html | page_mask.txt（HTML 固定输出 .txt） |

| screenshot.png | screenshot_mask.txt（图片 OCR 固定输出 .txt） |

| report.pdf | report_mask.pdf（或 report_mask.txt，见 PDF 说明） |

> 如果需要自定义输出路径，所有工具也支持通过 -o / --output 参数手动指定。

🚀 快速开始（30 秒上手）

我最常用的场景是？ 选一个直接看：

| 你手里有什么 | 去哪里看 |

|------------|---------|

| 一段文字/粘贴的文本 | → 纯文本脱敏 |

| Excel 表格 (.xlsx/.csv) | → 表格脱敏 |

| Word 文档 (.docx) | → Word 脱敏 |

| PPT 演示文稿 (.pptx) | → PPT 脱敏 |

| PDF 文件 | → PDF 脱敏 |

| 不了解策略，想先选一个 | → 策略选择指南 |

| 遇到报错/问题 | → 常见错误与排障 |

| 需要批量处理多个文件 | → 批量处理 |

模块结构

| 文件 | 用途 | 适用场景 |

|------|------|---------|

| scripts/mask.py | 纯文本脱敏核心 | 文本内容、对话粘贴 |

| scripts/dataframe_mask.py | 结构化数据脱敏 | Excel/CSV 表格，支持列级控制 |

| scripts/file_mask.py | 文档级脱敏（统一入口） | Word/PPT/PDF/图片/HTML/Markdown/TXT |

| config.yaml | 可扩展配置 | 自定义单位、列过滤规则、回退参数 |

策略选择指南

不知道怎么选策略？按这个决策流程走：

你脱敏完的数据要用来干嘛？
├─ 发给 AI 分析，结论要对应回真实数据
│  → 选 hash（默认）  ← 最常用，推荐首选
├─ 发给完全不信任的外部，一点都不想暴露量级
│  → 选 placeholder
├─ 内部团队分享，数据还要能做趋势分析/画图表
│  → 选 blur
├─ 对外发布，知道个大概范围就够了
│  → 选 range
└─ 不确定
   → 用默认 hash，最稳妥

四种策略效果对比

以数字 158000万元 和 23.5% 为例：

| 策略 | 158000万元 脱敏后 | 23.5% 脱敏后 | 能还原 | 推荐场景 |

|------|-------------------|--------------|:--:|------|

| hash（默认） | 443350万元 | 77% | ✅ | 日常分析、需还原 |

| placeholder | [A]万元 | [B] | ✅ | 极致安全 |

| blur | 162350万元 | 24.1% | ❌ | 内部分享、做分析 |

| range | [110600~205400]万元 | [16.5%~30.6%] | ❌ | 对外发布 |

策略特性速查

| | hash | placeholder | blur | range |

|------|:--:|:--:|:--:|:--:|

| 数值看起来像真的 | ✅ | ❌ | ✅ | ⚠️ |

| 同一数字脱敏后一致 | ✅ | ✅ | ❌ | ❌ |

| 支持还原 | ✅ | ✅ | ❌ | ❌ |

| 保留数量级 | ✅ | ❌ | ✅ | ✅ |

| 安全等级 | ⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐ | ⭐⭐⭐⭐ |

架构概览

本 skill 采用内置解析为主、专项 skill 为补充的混合策略：

┌─ 输入文件 ─────────────────────────────────────────────────────┐
│                                                                │
│  ├─ 原生支持（同格式输出）───────────────────────────────────   │
│  │   .docx → 保留字体/表格/页眉页脚 → .docx                    │
│  │   .pptx → 保留幻灯片/文本框/表格  → .pptx                    │
│  │   .xlsx → 列级精准脱敏           → .xlsx                    │
│  │   .csv  → 列级精准脱敏           → .csv                     │
│  │   .md   → 保留 Markdown 语法     → .md                      │
│  │   .txt  → 纯文本脱敏             → .txt                     │
│  │                                                             │
│  ├─ 文本提取（.txt 输出）───────────────────────────────────    │
│  │   .html → 剥离标签/保留段落结构  → .txt                     │
│  │   .pdf  → PyPDF2 提取文字       → .pdf 或 .txt             │
│  │   .png/.jpg/... → OCR识别 → 脱敏 → .txt                    │
│  │                                                             │
│  └─ 回退/委托 ─────────────────────────────────────────────    │
│      .json/.xml/.yaml → 文本读取 → mask.py 脱敏 → .txt         │
│      扫描版 PDF → PDF skill OCR → mask.py 脱敏 → .txt          │
│      复杂 HTML  → 浏览器 skill 提取 → mask.py 脱敏 → .txt      │
│                                                                │
└────────────────────────────────────────────────────────────────┘

使用方式

方式1：纯文本脱敏（最常用）

通过管道或文件输入：

# 管道输入
echo "今年营收12345万元，同比增长15.3%" | python scripts/mask.py

# 文件输入 → 自动生成输出文件（原文件名_mask.原后缀）
python scripts/mask.py --input report.txt --strategy hash

# 或手动指定输出文件
python scripts/mask.py --input report.txt --output masked.txt --strategy hash

输入 → 输出示例（hash 策略）：

输入: 公司2025年实现营业收入158000万元，同比增长23.5%。
输出: 公司8729年实现营业收入443350万元，同比增长77%。

方式2：Excel/CSV 表格脱敏

智能识别数值列，自动跳过 ID、序号、年份等非敏感列。

# 自动检测数值列并脱敏（自动生成 data_mask.xlsx）
python scripts/dataframe_mask.py -i data.xlsx

# 手动指定输出
python scripts/dataframe_mask.py -i data.xlsx -o masked.xlsx

# 手动指定列
python scripts/dataframe_mask.py -i data.xlsx -c "销售额,利润"

# 保存映射表，支持还原
python scripts/dataframe_mask.py -i data.xlsx -m mapping.json
python scripts/dataframe_mask.py --unmask -i masked.xlsx -o restored.xlsx -m mapping.json

输入 → 输出示例（hash 策略）：

| 城市 | 日均订单（脱敏前） | 日均订单（脱敏后） | 完单率（脱敏前） | 完单率（脱敏后） |

|------|------------------|------------------|----------------|----------------|

| 北京 | 853000 | 720000 | 94.2% | 47% |

| 上海 | 621000 | 700000 | 93.8% | 23% |

| 广州 | 487000 | 195000 | 91.5% | 10% |

方式3：Word 文档脱敏

全文脱敏，保留字体、字号、表格、页眉页脚全部格式。

# 全文脱敏（自动生成 report_mask.docx）
python scripts/file_mask.py -i report.docx

# 手动指定输出路径
python scripts/file_mask.py -i report.docx -o masked_report.docx

# 指定策略
python scripts/file_mask.py -i report.docx -s placeholder

> 格式保留：脱敏后的 Word 和原始文档排版完全一致，只是数字变了。表格内数字、页眉页脚中的日期/数字也一并处理。

方式4：PowerPoint 脱敏

遍历所有幻灯片、文本框、表格、组合形状。

# 全文脱敏（自动生成 slides_mask.pptx）
python scripts/file_mask.py -i slides.pptx

# 手动指定输出
python scripts/file_mask.py -i slides.pptx -o masked_slides.pptx

# 模糊化策略
python scripts/file_mask.py -i slides.pptx -s blur

> 处理范围：每页幻灯片中的文本框、表格单元格、嵌套组合图形中的文字——全部逐页遍历处理。

方式5：PDF 脱敏

# 生成新 PDF（自动生成 document_mask.pdf）
python scripts/file_mask.py -i document.pdf

# 输出为纯文本（自动生成 document_mask.txt）
python scripts/file_mask.py -i document.pdf --as-text

# 保存映射表
python scripts/file_mask.py -i document.pdf -m mapping.json

> 注意：PDF 脱敏依赖 PyPDF2 和 fpdf2 库。扫描版 PDF（无文字层）会自动委托 PDF skill 做 OCR。

方式6：HTML 脱敏

# 剥离标签 → 保留段落结构 → 脱敏 → .txt 输出
python scripts/file_mask.py -i page.html -o masked.txt
python scripts/file_mask.py -i page.html -o masked.txt -s placeholder

> 限制：HTML 脱敏固定输出为 .txt，无法写回原 HTML 结构。

方式7：Markdown 脱敏

# 数字替换不影响 Markdown 语法，输出仍为 .md
python scripts/file_mask.py -i notes.md -o masked_notes.md
python scripts/file_mask.py -i notes.md -o masked.md -s blur

方式8：图片脱敏（OCR）

# ⚠️ 前置条件：需安装 Tesseract OCR 引擎（见下方说明）
python scripts/file_mask.py -i screenshot.png -o masked.txt --ocr-lang chi_sim+eng

# 纯英文图片
python scripts/file_mask.py -i chart.jpg -o masked.txt --ocr-lang eng

Tesseract OCR 安装（首次使用需要）：

| 系统 | 安装方式 |

|------|---------|

| Windows | 下载安装： |

| macOS | brew install tesseract tesseract-lang |

| Linux | apt-get install tesseract-ocr tesseract-ocr-chi-sim |

| Python | pip install pytesseract Pillow |

若未安装 Tesseract 就直接使用，会收到明确的安装指引提示。

方式9：未知格式回退

# JSON / XML / YAML 等文本格式自动尝试多编码读取并脱敏
python scripts/file_mask.py -i data.json -o masked.txt
python scripts/file_mask.py -i config.xml -o masked.txt

方式10：统一入口（编程调用）

from file_mask import mask_document

# 一行代码，自动识别格式（output_path 可选，传 None 自动按规范命名）
mask_document('report.docx', None, strategy='hash')      # → report_mask.docx
mask_document('slides.pptx', None, strategy='blur')       # → slides_mask.pptx
mask_document('data.pdf', None, strategy='range')         # → data_mask.pdf
mask_document('data.xlsx', None)                           # → data_mask.xlsx
mask_document('page.html', None, strategy='hash')         # → page_mask.txt
mask_document('notes.md', None, strategy='placeholder')   # → notes_mask.md
mask_document('screenshot.png', None, ocr_lang='chi_sim+eng')  # → screenshot_mask.txt

方式11：还原脱敏数据

# 文本还原
python scripts/mask.py --unmask -i masked.txt -o restored.txt -m mapping.json

# Excel 还原
python scripts/dataframe_mask.py --unmask -i masked.xlsx -o restored.xlsx -m mapping.json

> 注意：只有 hash 和 placeholder 策略支持还原。blur 和 range 策略不可逆。

方式12：批量处理多个文件

# 批量脱敏同一目录下的所有 Word 文档（自动生成 *_mask.docx）
for f in *.docx; do
    python scripts/file_mask.py -i "$f" -s hash
done

# 批量脱敏所有 Excel 文件并保存映射
for f in *.xlsx; do
    python scripts/dataframe_mask.py -i "$f" -m "${f%.xlsx}_map.json"
done

🔒 安全与隐私说明

数据处理原则

1. 本地处理：所有脱敏操作在本地机器完成，不将数据上传到任何云端服务
2. 不存储原始数据：脱敏脚本读取文件后直接处理输出，不保留原始数据副本
3. 映射表安全：映射表（JSON 文件）包含原始数字到脱敏数字的对应关系，相当于「还原密钥」，请单独保管，不要和脱敏文件一同发送
4. 脱敏后需人工复核：工具只替换数字，不做语义级安全检查。脱敏后的数据中可能仍包含非数字敏感信息（人名、地名、特定表述等），发往外部前请通读确认

禁止行为

• ❌ 不要将映射表上传到公开的 Git 仓库或云盘
• ❌ 不要将映射表和脱敏文件一起发送给第三方
• ❌ 不要在未人工复核的情况下将脱敏数据发送给完全不信任的外部方
• ❌ 不要用本工具处理需要加密才能满足合规要求的数据（本工具是脱敏，不是加密）

不同策略的安全等级

| 策略 | 安全等级 | 适用场景 |

|------|:--:|------|

| placeholder | ⭐⭐⭐⭐⭐ | 发给完全不信任的外部，极致安全 |

| range | ⭐⭐⭐⭐ | 对外发布，知道大概范围 |

| hash | ⭐⭐⭐ | 发给 AI 分析，日常最常用 |

| blur | ⭐⭐ | 内部分享，趋势分析 |

输出准确性约束

系统处理遵循以下规则确保输出可靠：

• 不确定的逻辑先行标注：当脱敏策略在边界情况（如超大数字、非标准单位）下行为不确定时，在输出中标注假设条件
• 不胡编数据：脱敏后的数字严格基于原始数据通过确定性算法生成（hash）或基于量级区间采样（blur/range），不会凭空生成
• 映射表可验证：hash 和 placeholder 策略生成映射表 JSON，可事后验证每次替换的准确性
• 已知限制透明：文档中已列出 7 项已知限制（PDF 排版、HTML 输出格式等），不隐瞞工具的局限性

异常处理规则

当用户输入信息不足时，遵循「先给默认行为 + 列具体缺失项」原则，禁止笼统回复「请提供更多信息」：

示例：用户只说「帮我脱敏这个文件」

✅ 正确回复：
"我先用默认策略（hash）对文件做全文脱敏。输出文件：xxx_mask.docx。
如果这不是你想要的，需要补充：
1. 想用哪个策略？hash（可还原）/ blur（模糊化）/ placeholder（完全隐藏）/ range（区间）
2. 需要保存映射表吗？（加 -m 参数）
3. 只要脱敏特定列吗？（Excel场景，用 -c 指定列名）"

❌ 错误回复：
"请提供更多信息"

受众说明

| 用户类型 | 如何使用 |

|---------|---------|

| 日常办公用户 | 直接复制「新手入门」中的开场白触发，工具自动选择默认策略（hash）处理 |

| 数据分析师 | 使用 dataframe_mask.py 做列级精准脱敏，保存映射表以便事后还原 |

| 团队协作 | 批量处理多文件时使用统一映射表（同一 -m 参数），确保跨文件数字一致性 |

| CI/CD 集成 | 通过 Python API 调用（from file_mask import mask_document），传入策略和输出路径 |

| 安全管理 | 使用 placeholder 策略做高安全等级脱敏，配合人工复核后发往外部 |

定制化使用指南

配置文件定制 (config.yaml)

# 追加自定义单位后缀（如"人次"、"笔订单"）
custom_units:
  - "人次"
  - "笔订单"

# Excel 列规则：强制脱敏/跳过脱敏
column_rules:
  force_mask_patterns:
    - ".*金额"   # 所有含"金额"的列强制脱敏
  skip_patterns:
    - "^ID$"     # ID 列跳过脱敏

# 默认参数：无需每次命令行指定
defaults:
  strategy: hash     # 默认策略，可改为 blur/placeholder/range
  seed: 42           # 随机种子，确保可复现

参数传递定制

| 需求 | 参数 | 示例 |

|------|------|------|

| 只脱敏不还原 | 不加 -m | python scripts/file_mask.py -i report.docx |

| 脱敏并保存映射 | -m mapping.json | python scripts/file_mask.py -i report.docx -m map.json |

| 指定输出路径 | -o output.docx | python scripts/file_mask.py -i in.docx -o out.docx |

| 跳电话号码 | --skip-phone | python scripts/file_mask.py -i report.docx --skip-phone |

| 纯英文 OCR | --ocr-lang eng | python scripts/file_mask.py -i chart.png --ocr-lang eng |

参考文档

深度使用请查阅以下 reference 文件：

• references/anti-patterns.md — 最常见误用场景 + 正确做法对比 + 禁忌清单
• references/faq-deep.md — 深度 FAQ（边缘场景/安全合规/CICD 集成，9 题）
• references/examples.md — 6 个完整使用示例（文本/Excel/Word/PPT/图片/批量）

常见问题 FAQ

Q1：脱敏后的数字为什么看起来怪怪的？

这是正常现象。hash 策略用确定性算法替换数字，脱敏后的数字和原始值完全不同——这正是设计目标。如果不希望数据看起来太假，请用 blur 策略；如果要彻底隐藏，请用 placeholder。

Q2：我可以只脱敏 Excel 中的部分列吗？

可以。用 -c 参数指定列名（逗号分隔）：python scripts/dataframe_mask.py -i data.xlsx -c "销售额,利润"。不指定时工具自动检测数值列。

Q3：脱敏后还能还原吗？

只有 hash 和 placeholder 策略支持还原，需要脱敏时保存的映射表。脱敏时加 -m mapping.json，还原时用 --unmask -m mapping.json。blur 和 range 策略不可逆。

Q4：Word/PPT 脱敏后格式会乱吗？

不会。工具保留原文档的全部格式（字体、字号、颜色、表格结构、页眉页脚等），只替换数字内容。

Q5：图片里的数字能脱敏吗？

可以。需要先安装 Tesseract OCR 引擎（各平台安装指引见「方式8」），然后通过 OCR 识别文字并脱敏，输出为 .txt 文件。

Q6：脱敏后的数据发给 AI 大模型，模型平台会存储吗？

不会存储你的原始数据，因为脱敏后已不包含真实数字。但建议：敏感度极高的数据用 placeholder 策略，完全不保留数值信息。

参数说明

file_mask.py（文档脱敏统一入口）

| 参数 | 说明 |

|------|------|

| -i, --input | 输入文件路径（.docx/.pptx/.pdf/.png/.jpg/.html/.md/.txt/.json...，必填） |

| -o, --output | 输出文件路径（可选，默认：原文件名_mask.原后缀） |

| -s, --strategy | 脱敏策略：hash/placeholder/blur/range（默认 hash） |

| -m, --map-file | 映射表输出路径（JSON，仅 hash/placeholder 可还原） |

| --seed | 随机种子（默认 42） |

| --skip-phone | 跳过电话号码 |

| --as-text | PDF 脱敏后输出为 .txt 而非 PDF |

| --ocr-lang | 图片 OCR 语言（默认 chi_sim+eng，纯英文用 eng） |

dataframe_mask.py（表格脱敏）

| 参数 | 说明 |

|------|------|

| -i, --input | 输入文件路径（.xlsx/.csv，必填） |

| -o, --output | 输出文件路径（可选，默认：原文件名_mask.原后缀） |

| -c, --columns | 手动指定脱敏列（逗号分隔），默认自动检测数值列 |

| -s, --strategy | 脱敏策略（默认 hash） |

| -m, --map-file | 映射表输出路径（JSON） |

| --seed | 随机种子（默认 42） |

| --skip-phone | 跳过电话号码 |

| --unmask | 还原模式，需配合 -m |

| --sheet-name | Excel 工作表名或索引（默认 0） |

| --encoding | CSV 文件编码（默认 utf-8） |

mask.py（纯文本脱敏）

| 参数 | 说明 |

|------|------|

| -s, --strategy | 脱敏策略（默认 hash） |

| -i, --input | 输入文件路径 |

| -o, --output | 输出文件路径（可选，默认：原文件名_mask.原后缀） |

| -m, --map-file | 映射表 JSON 路径 |

| --unmask | 还原模式，需配合 -m |

| --seed | 随机种子（默认 42） |

| --skip-phone | 跳过电话号码 |

支持的文件格式总览

| 格式 | 扩展名 | 处理方式 | 输出格式 | 保留结构 | 还原 |

|------|--------|---------|---------|---------|:--:|

| 纯文本 | .txt | mask.py | .txt | - | hash/placeholder |

| Markdown | .md | 按纯文本 | .md | ✅ | hash/placeholder |

| Excel | .xlsx/.xls | dataframe_mask | .xlsx | ✅ | hash/placeholder |

| CSV | .csv | dataframe_mask | .csv | ✅ | hash/placeholder |

| Word | .docx | file_mask | .docx | ✅ 格式/表格/页眉页脚 | hash/placeholder |

| PPT | .pptx | file_mask | .pptx | ✅ 幻灯片/文本框/表格 | hash/placeholder |

| PDF | .pdf | PyPDF2+fpdf2 | .pdf/.txt | ⚠️ 文字内容保留 | hash/placeholder |

| HTML | .html/.htm | stdlib 解析 | .txt | ⚠️ 文本+段落 | hash/placeholder |

| 图片 | .png/.jpg/.gif/.bmp/.webp/.tiff | Tesseract OCR | .txt | - | hash/placeholder |

| JSON等 | .json/.xml/.yaml | 文本回退 | .txt | - | hash/placeholder |

| 扫描PDF | .pdf | 委托 PDF skill | .txt | - | hash/placeholder |

| 复杂HTML | .html | 委托浏览器 skill | .txt | - | hash/placeholder |

性能与能力边界

处理速度参考

| 文件类型 | 典型大小 | 预计耗时 |

|---------|---------|---------|

| 纯文本 (.txt) | 1 MB（约 10 万字） | < 1 秒 |

| Markdown (.md) | 500 KB | < 1 秒 |

| Excel (.xlsx) | 10 MB（约 5 万行） | 3~8 秒 |

| Word (.docx) | 50 页 | 2~10 秒 |

| PPT (.pptx) | 100 页 | 3~15 秒 |

| PDF（文字型） | 100 页 | 5~20 秒 |

| 图片 OCR | 1920×1080 截图 | 2~10 秒 |

> 大文件建议：超过 100 MB 的 Excel 或超过 200 页的 Word/PPT，建议先拆分后再脱敏。

已知限制

1. PDF 排版：脱敏后生成的 PDF 仅保留文字内容和分页，不保留原始排版、图片、表格样式
2. HTML 输出：HTML 脱敏固定输出 .txt，无法写回原 HTML 结构
3. 图片 OCR：依赖外部 Tesseract 引擎安装；手写体、模糊图片识别率有限
4. 编码：纯文本文件默认用 UTF-8 读写；遇到 GBK/GB2312 编码会自动回退尝试
5. .doc / .xls 旧格式：不支持旧版 Office 格式，需先转为 .docx / .xlsx
6. 超大数字：超过 10 位的整数可能因浮点精度问题产生微小偏差
7. 并发安全：脚本非线程安全，不建议多进程同时写同一个输出文件

可配置选项 (config.yaml)

custom_units:        # 追加自定义单位后缀
column_rules:        # Excel 列名匹配规则
  force_mask_patterns:   # 强制脱敏的列（正则）
  skip_patterns:         # 跳过脱敏的列（正则）
skip_rules:          # 排除特定格式
defaults:            # 默认参数
pdf:                 # PDF 输出设置
ocr:                 # OCR 语言和路径配置
fallback:            # 未知格式回退参数

常见错误与排障

❌ 错误："文件不存在" / "No such file"

错误：文件不存在: /path/to/file.xlsx

原因与解决：

• 检查文件路径是否拼写正确，注意相对路径和绝对路径的区别
• Windows 下路径包含中文时，确认终端编码设置正确
• 如果是拖拽文件到终端，确认路径中没有多余的空格或引号

❌ 错误：缺少依赖库

错误：需要安装 python-docx: pip install python-docx

原因与解决：

• 不同文件格式需要不同的 Python 包，按提示安装即可
• 常见依赖：python-docx（Word）、python-pptx（PPT）、openpyxl（Excel）、PyPDF2 + fpdf2（PDF）、pytesseract + Pillow（图片 OCR）
• 一键安装所有依赖：pip install python-docx python-pptx openpyxl pandas PyPDF2 fpdf2

❌ 错误：Excel 列名不存在

警告：列 "销售额" 不存在，已跳过

原因与解决：

• 用 -c 指定列名时，列名必须和 Excel 表头完全一致（包括空格、标点）
• 如果不确定列名，不带 -c 参数运行，工具会自动检测数值列
• 可以先用 -c 不指定列跑一次，看输出日志中显示的列名

❌ 错误：还原时映射表不存在

错误：还原模式需要提供映射表文件 (--map-file)

原因与解决：

• 还原（--unmask）必须配合之前脱敏时保存的映射表 JSON 文件
• 脱敏时记得加 -m mapping.json 保存映射表
• 映射表文件和脱敏后的文件要配对使用，不能混用

❌ 错误：CSV 中文乱码

原因与解决：

• CSV 默认用 UTF-8 编码读取。如果你的 CSV 是 GBK 编码，加 --encoding gbk
• 如果有 BOM 头的 UTF-8，尝试 --encoding utf-8-sig

❌ 错误：PDF 生成失败

PDF 生成失败，保存为文本文件

原因与解决：

• 通常是因为系统缺少中文字体，工具会自动回退到 .txt 输出
• 如需 PDF 输出，确保系统安装了中文字体（如微软雅黑、宋体）
• 也可以直接加 --as-text 参数指定输出为文本

❌ 错误：OCR 未识别到文字

警告: OCR 未识别到文字内容，输出为空文件

原因与解决：

• 图片可能不含文字，或文字太小/太模糊
• 纯中文图片试试 --ocr-lang chi_sim（不加 eng）
• 确认 Tesseract 已正确安装：命令行输入 tesseract --version 检查
• Windows 用户确认安装时勾选了中文语言包

❌ 错误：脱敏后数字看起来"不对"

这是正常现象！ hash 策略脱敏后的数字会看起来像真实数据，但和原始值完全不同——这正是设计目标。如果你希望脱敏后的数字也"合理"，请使用 blur 策略；如果希望彻底隐藏数值，请使用 placeholder 策略。

💡 常见踩坑总结

| 踩坑 | 正确做法 |

|------|---------|

| 用 placeholder 脱敏后发给 AI 做数据分析 | placeholder 只保留结构，AI 无法做数值分析。数据分析用 hash 或 blur |

| Excel 脱敏没保存映射表，事后想还原 | 脱敏时务必加 -m mapping.json |

| 对 PDF 输出排版期望过高 | PDF 脱敏后保留文字内容和分页，不保留原排版样式 |

| 忘记安装 OCR 依赖就要脱敏图片 | 图片脱敏前先确认已安装 Tesseract OCR 引擎 |

| 对 .doc 旧格式直接脱敏 | 先手动转为 .docx 再脱敏 |

与其他技能的协作

本技能独立处理

• .docx、.pptx、.xlsx、.csv、.md、.txt、.html（简单）、.pdf（文字型）
• .png、.jpg、.gif、.bmp、.webp、.tiff（图片 OCR，需 Tesseract）
• .json、.xml、.yaml 等文本格式（自动回退）

委托专项 skill 的场景

| 场景 | 合作 skill | 流程 |

|------|-----------|------|

| 扫描版 PDF（图片型，无文字层） | pdf skill | OCR 提取文本 → mask.py 脱敏 → .txt 输出 |

| JS 渲染的复杂 HTML（SPA 页面） | agent-browser / playwright-cli | 浏览器提取可见文本 → mask.py 脱敏 → .txt 输出 |

| .doc（旧版 Word） | 用户先转为 .docx | file_mask.py 正常处理 |

| .xls（旧版 Excel） | 用户先转为 .xlsx | dataframe_mask.py 正常处理 |

特别说明

• 格式保留：Word/PPT 脱敏后保留原文档的字体、字号、颜色、表格等所有格式
• 页眉页脚：Word 文档的页眉页脚中的数字也会被脱敏
• 中文 PDF：PDF 输出自动查找系统 CJK 字体，支持中文内容
• 电话号码保护：使用 --skip-phone 保留电话号码不被脱敏
• 金额数据：自动识别带"元""万""亿"等单位的数字
• 负数保护：负数脱敏后保留负号
• 哈希相对位置：hash 策略在量级区间内保持相对位置，101 脱敏后仍小于 900
• 映射表：hash 和 placeholder 策略自动生成映射表，支持完整还原
• 脱敏后需人工复核：工具不做内容级别的安全判断。脱敏后的数据能否外用（上传大模型、发送第三方等），仍需人工核查