document-sanitizer（文件消毒剂）

document-sanitizer

技能说明 / Skill Description

概述 / Overview

本技能用于批量对 Word (.docx) 和 Excel (.xlsx) 文件执行脱敏处理，支持关键字精确替换和正则表达式动态替换，并提供一键恢复功能。

This skill batch-desensitizes Word (.docx) and Excel (.xlsx) files using keyword exact-match and regex dynamic replacement, with one-click reversible restoration.

核心特性 / Key Features

前置依赖 / Prerequisites

Python 包依赖 / Python Dependencies

pip install python-docx openpyxl

可选依赖（旧格式转换）/ Optional (Legacy Format Conversion)

pip install xlrd pywin32

• .doc → .docx 转换需要 Windows + Microsoft Word（使用 Word COM 自动化）
• .xls → .xlsx 转换使用 xlrd + openpyxl（跨平台）

使用方法 / Usage

1. 准备配置文件 / Prepare Config File

在工作目录下创建 _sanitize_config.json：

Create _sanitize_config.json in your workspace:

{
  "exact_rules": [
    {"pattern": "白云", "replacement": "黑水"},
    {"pattern": "南方", "replacement": "北风"},
    {"pattern": "广州", "replacement": "镇北"}
  ],
  "regex_rules": [
    {"pattern": "1[3-9]\\d{9}", "label": "手机号"},
    {"pattern": "\\d{6}(?:19|20)\\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])\\d{3}[\\dXx]", "label": "身份证号"},
    {"pattern": "[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}", "label": "邮箱"}
  ]
}

2. 执行脱敏 / Run Sanitization

# 基本脱敏（默认脱敏文件名）
python <skill_dir>/scripts/sanitize.py sanitize <工作目录>

# 不脱敏文件名
python <skill_dir>/scripts/sanitize.py sanitize <工作目录> --no-rename

# 自动转换 .doc/.xls 旧格式文件
python <skill_dir>/scripts/sanitize.py sanitize <工作目录> --auto-convert

3. 恢复文档 / Restore Documents

python <skill_dir>/scripts/sanitize.py restore <工作目录>

命令行参数 / CLI Arguments

输出目录 / Output Directories

脱敏记录结构 / Record Structure

{
  "version": 2,
  "created_at": "2026-04-08 16:02:07",
  "last_updated": "2026-04-08 16:02:07",
  "mapping": {
    "黑水": "白云",
    "[RED_手机号_1]": "13828417396"
  },
  "filename_mapping": {
    "黑水物流文档.docx": "白云物流文档.docx"
  },
  "runs": [
    {"timestamp": "...", "files_processed": ["..."]}
  ]
}

核心原理 / Core Principle：只要 mapping（脱敏值→原始值）完整，无论文档经过多少修改，都可以用它来反向替换恢复。

As long as the mapping (sanitized value → original value) is complete, documents can be restored regardless of modifications.

示例 / Examples

示例 1：基本脱敏流程 / Example 1: Basic Sanitization

# 1. 创建配置文件 _sanitize_config.json
# 2. 执行脱敏
python sanitize.py sanitize ./my-docs

# 输出:
# [RENAME] 白云物流文档.docx → 黑水物流文档.docx
# [1/1] 白云物流文档.docx [OK]
# 脱敏输出目录: ./my-docs/_sanitized_output

示例 2：脱敏后恢复 / Example 2: Sanitize then Restore

# 脱敏
python sanitize.py sanitize ./my-docs

# 恢复（可多次执行，对修改后的文档也有效）
python sanitize.py restore ./my-docs

# 输出:
# [RENAME] 黑水物流文档.docx → 白云物流文档.docx
# [OK] 无残留占位符

示例 3：处理包含旧格式文件的目录 / Example 3: Directory with Legacy Files

# 自动转换 .doc/.xls 并脱敏
python sanitize.py sanitize ./my-docs --auto-convert

技术要点 / Technical Notes

1. Word run 拆分 / Run Splitting: Word 会将文本拆分到多个 <w:r> 元素中，脚本先合并所有 w:t 文本再替换再写回，确保跨 run 的关键字也能正确匹配

Word splits text across multiple <w:r> elements. The script merges all w:t text first, applies replacements, then writes back — ensuring cross-run keywords are correctly matched.

1. 反向替换顺序 / Reverse Order: 恢复时按 key 长度降序替换，避免短 key 误匹配长 key 的子串

Restoration sorts keys by length descending to prevent short keys from partially matching longer keys.

1. 脱敏范围 / Scope: 仅支持 .docx/.xlsx 格式。.doc/.xls 旧格式需先转换（可自动完成）

Only .docx/.xlsx are supported. Legacy .doc/.xls must be converted first (auto-conversion available).

1. 原始文件安全 / Original Safety: 原始文件不会被修改，所有操作在输出目录中进行

Original files are never modified — all operations happen in output directories.

错误处理 / Error Handling