文档脱敏技能（doc-desensitize）

概述

零依赖（纯 Python 标准库），对 .docx 和 .xlsx 文档中的敏感信息进行等长星号替换，生成脱敏后的文档。星号数量等于原文长度，保持排版不变。

原理：.docx / .xlsx 本质是 ZIP 包，直接操作内部 XML 实现脱敏。

v3.3 优化： 执行脱敏前必须先问用户要脱敏哪些内容类型，避免过度脱敏。

v3.2 优化： 目录模式不再复制非 docx/xlsx 文件（只输出脱敏文档）；新增 --move-original 把原始文档剪切到「原始文档」子文件夹；无敏感内容的文件也生成副本（加_脱敏后缀）；处理进度提示 [N/总数]。

v3.1 修复： 修正统计计数 bug（docProps 统计恒为零、xlsx 统计覆盖丢失）、删除重复调用、收紧 landline/school/company/postcode 正则边界、修复 Windows GBK 终端测试崩溃。

v3 增强： 文档属性脱敏、脱敏统计报告、输出目录自动创建、文件占用友好提示、Excel 科学记数法检测提示、输出覆盖警告、非 UTF-8 编码容错。段落级文本合并、域代码脱敏（TOC/Hyperlink）、修订模式脱敏、文本框/形状文字脱敏、Excel 数值单元格脱敏。

更新日志

何时使用

• 用户提到"文档脱敏""去除敏感信息""批量打码""脱敏处理"
• 用户上传或指定了 .docx / .xlsx 文件，要求去除敏感内容
• 用户提到需要对手机号、身份证、姓名等信息打码

执行流程

⚠️ 必须遵守：执行脱敏前，先问用户要脱敏哪些内容类型。

1. 用户要求脱敏时，先列出可选规则（参考下方「脱敏规则」表格），用 AskUserQuestion 让用户勾选要脱敏的类型
2. 用户选择后，用对应的 --rules 参数执行脚本
3. 如果用户说"全部"或没有特别指定，则不传 --rules（默认全部规则）

使用方式

# 全部规则（默认）
python scripts/desensitize.py <输入文件或目录> [输出路径]

# 只脱敏指定类型
python scripts/desensitize.py <输入> [输出] --rules phone,id_card

# 剪切原始文档到「原始文档」文件夹（方便从混合目录中分离）
python scripts/desensitize.py <输入> [输出] --move-original

# 预览模式（只检测不生成文件）
python scripts/desensitize.py <输入> --dry-run
python scripts/desensitize.py <输入> -n --rules phone,id_card

• 输入为文件：脱敏后保存为 <原名>_脱敏.docx，原文件不修改
• 输出路径可指定任意位置，父目录不存在会自动创建
• 输入为目录：只处理 docx/xlsx，输出目录只包含脱敏后的文档，不复制其他文件（PDF、zip、图片等留在原目录不动）
• --move-original（或 -m）：目录模式下，将原始 docx/xlsx 从源目录剪切到输出目录下的「原始文档」子文件夹，方便用户从混合文件中分离
• 无敏感内容的 docx/xlsx 也会生成 _脱敏 副本（内容不变），确保输出目录文档数量与源一致
• --rules（或 -r）：可选，逗号分隔要启用的规则 key；不传则全部启用
• --dry-run（或 -n）：预览模式，只报告检测到的敏感内容类型和数量，不生成文件
• 处理过程显示进度：[3/59] xxx.docx
• 处理完成自动输出统计报告：📊 脱敏统计: 学校名×386, 手机号×15, ...

脱敏规则

全部规则 key 为上述所有。--rules 传入逗号分隔的子集即可只启用指定规则。

脚本 API

from scripts.desensitize import process_path, mask_text

# 处理文件/目录
process_path('input.docx', 'output.docx')                   # 全部规则
process_path('input.docx', 'output.docx', rules='phone')   # 仅手机号
process_path('input_dir', 'output_dir')                     # 批量目录（只输出脱敏文档）
process_path('input_dir', 'output_dir', rules='phone,id_card')
process_path('input_dir', 'output_dir', move_original=True) # 剪切原始文档到「原始文档」子文件夹
process_path('input.docx', dry_run=True)                    # 预览模式

# 纯文本脱敏
mask_text('联系电话：13812345678')                          # 全部规则
mask_text('联系电话：13812345678', enabled_keys={'phone'})  # 仅手机号

注意事项

• 仅支持 .docx / .xlsx，不支持 .doc / .xls / .ppt / .pptx（旧格式请先另存为 .docx/.xlsx）
• 不支持加密/密码保护的文档
• Excel 中身份证号如以数值存储（显示为科学记数法），无法脱敏，请在 Excel 中将该列设为"文本"格式后重新保存
• 正则匹配可能有轻微过度脱敏，建议人工复核
• 脱敏覆盖范围：正文、页眉页脚、批注、目录域代码、超链接域代码、文本框中文字、修订痕迹、文档属性（作者/公司等元数据）
• 嵌入式文档（OLE 对象）及超大文件（>500MB）暂不支持
• 文件被 Word/Excel 打开时无法处理，请先关闭
• 星号数量等于原文长度（如"张三"→""，"13800138000"→"*********"），保证排版不变

常见问题

• Windows 终端乱码/崩溃：运行测试时加 -X utf8 参数：python -X utf8 scripts/test_desensitize.py
• 文件被占用：关闭 Word/Excel 后重试；如仍失败，检查文件是否在共享目录中被其他用户打开
• 旧格式 .doc/.xls：用 Word/Excel另存为 .docx/.xlsx，或用 LibreOffice 命令行批量转换：soffice --convert-to docx *.doc
• 误脱敏正常文本：用 --rules 指定只启用需要的规则类型，或用 --dry-run 先预览再处理

自动化测试

验证技能是否正常工作：

cd scripts && python test_desensitize.py

覆盖 27 项测试：手机号/身份证/邮箱脱敏、XML 结构完整性、跨 run 断裂、修订模式、绘图文字、域代码、docProps、递归文件夹、输出目录创建、覆盖警告、dry-run、规则过滤、xlsx 单元格、科学记数法、加密文件容错、原文件保护、目录模式不复制非文档文件、--move-original 剪切原始文档等。