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

| 特性 | 说明 / Description |

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

| 关键字精确替换 / Exact Match | 配置关键字对，替换为带 [] 标记的占位符（如"白云"→[黑水]）|

| 正则动态替换 / Regex Dynamic | 匹配手机号、身份证号、邮箱等，自动生成占位符如 [RED_手机号_1] |

| 文件名脱敏 / Filename Sanitization | 默认开启，输出文件自动使用脱敏后的文件名 |

| 统一脱敏记录 / Unified Record | 所有映射累积到 _sanitize_record.json，无论文档如何修改都能恢复 |

| 一键恢复 / One-Click Restore | 读取记录反向替换，还原文件名和内容，校验残留占位符 |

| 旧格式自动转换 / Legacy Format Conversion | 检测到 .doc/.xls 时提示自动转换为 .docx/.xlsx |

前置依赖 / 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

| 参数 / Argument | 说明 / Description |

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

| sanitize | 执行脱敏 / Run sanitization |

| restore | 恢复文档 / Restore documents |

| --no-rename | 不对文件名脱敏 / Skip filename sanitization |

| --auto-convert | 自动转换 .doc/.xls，无需确认 / Auto-convert legacy formats |

输出目录 / Output Directories

| 目录 / Directory | 说明 / Description |

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

| _sanitized_output/ | 脱敏后的文件 / Sanitized files |

| _restored_output/ | 恢复后的文件 / Restored files |

| _sanitize_record.json | 统一脱敏记录（映射累积）/ Unified record (accumulative mapping) |

| _sanitize_config.json | 脱敏规则配置 / Sanitization rules config |

脱敏记录结构 / 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:t 文本再替换再写回，确保跨 run 的关键字也能正确匹配

Word splits text across multiple 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

| 错误 / Error | 解决方法 / Solution |

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

| "未找到配置文件" / Config not found | 在工作目录创建 _sanitize_config.json |

| "python-docx import error" | 运行 / Run: pip install python-docx |

| "openpyxl import error" | 运行 / Run: pip install openpyxl |

| ".doc 转换失败" / .doc conversion failed | 确保 Windows + Word 已安装 / Ensure Word is installed |

| "残留占位符" / Residual placeholders | 检查脱敏记录是否完整 / Check record completeness |