文隐匣 · WenVeil

面向 Windows 的 DOCX 智能脱敏与人工复核工作台

作者：ZheZZ

文隐匣（WenVeil）在本机解析和改写 .docx 文件。它直接读取 DOCX 包内的 OOXML，在保留文字节点与字符位置映射的前提下识别和替换敏感内容；不会使用 paragraph.text 重建段落，也不会对 XML 做全文字符串替换。原文件始终只读，最终替换必须经过人工确认。

Important

文档解析、风险扫描、人工复核和 DOCX 改写均在本机完成，并且服务仅监听 127.0.0.1。点击“开始识别”后，文件名（不含路径和扩展名）及文档可见文字会发送给你配置的第三方模型服务；图片、嵌入对象和本机路径不会发送。使用前请确认模型服务商的隐私条款。

界面预览

文档结构与风险扫描	逐位置人工复核与替换

主要能力

• 扫描正文、表格、页眉、页脚、脚注、尾注、批注、超链接和文本框中的 <w:t> 文字。
• 以 <w:p> 为逻辑段落，建立每个字符到 XML 文字节点及节点内偏移的映射。
• 将文件名（不含路径和扩展名）及逻辑段落按字符预算分批发送给兼容 OpenAI API 的模型；超长单段会带少量重叠地切批，以降低边界实体漏检概率。
• 严格校验模型 JSON、Schema、实体类型、置信度、segment_id 和 exact_text；模型可结合上下文判断各类隐私、交易及商业敏感信息，无法归入具体类型时使用 OTHER_SENSITIVE，但不能直接修改文档。
• 对股权、持股、出资比例和表决权语境中的百分比进行本地高确定性补漏，并以 EQUITY_RATIO 进入人工复核；本地补漏不会限制模型发现其他类型。
• 将同一原文实体合并为稳定的全文映射。复核表默认每个敏感词只显示一行和出现次数；需要时可切换到“按出现位置”，逐项启用或禁用。
• 检测重复、包含和重叠实体。较长实体默认优先，短实体不会消失，仍会在复核表中显示；可一键处理，导出时也会自动停用较短的重叠位置，不再要求用户自行查找。
• 支持编号匿名化、星号遮盖和自定义替换。
• 从后向前执行替换；跨多个 <w:t> 时把替换值写入首个节点，只清空命中范围内后续节点的文字，不删除 run 或 run 属性。
• 导出前重新读取未修改的源包，验证原文件哈希、所有定位、冲突、ZIP 结构、必要包部件和全部 XML。
• 原文件永不覆盖。结果文件保留到程序退出；退出时清理会话临时目录。
• 提供中文五步工作台界面、流程锚点导航、服务状态提示、卡片化复核操作和窄屏响应式布局；关闭网页与退出本地服务的区别会持续显示。

安装和启动

要求 Windows、Python 3.11 或更高版本。

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python app.py

也可以双击 run.bat。程序会：

1. 仅监听 127.0.0.1；
2. 自动寻找可用本地端口；
3. 自动打开默认浏览器；
4. 明确以 share=False 启动，不创建 Gradio 公网分享链接；
5. 在 Windows 通知区域显示常驻图标，可重新打开页面或退出程序。

关闭浏览器页面不会停止本地服务。请使用网页顶部“关闭程序”按钮、Windows 通知区域图标的“退出并清理临时文件”，或在启动控制台按 Ctrl+C；退出时会取消识别任务并清理会话临时目录。

模型配置

界面提供以下配置：

• API Base URL，例如供应商给出的 OpenAI 兼容 /v1 地址；使用 OpenAI 官方默认地址时可留空；
• API Key（密码输入框）；
• 模型名称；
• Temperature；
• 单批最大字符数；
• 最大输出 Token；
• 请求超时；
• 最大重试次数；
• 思考模式（自动、关闭、开启或不发送参数）；
• “保存模型配置”按钮，以及可选的“同时保存 API Key”。

硅基流动可填写：

API Base URL: https://api.siliconflow.cn/v1
模型名称: deepseek-ai/DeepSeek-V4-Flash
思考模式: 自动（硅基流动默认关闭思考）

“自动”只会对 siliconflow.cn 域名发送 enable_thinking=false，其他兼容服务商不会收到该供应商参数。识别请求采用流式响应，页面会持续显示本次耗时、尝试次数、已接收流式块和响应字符数。默认单批 3000 字符、超时 120 秒、最多重试 1 次，避免一次故障因多轮长超时等待数分钟。

也可以在启动前设置环境变量：

$env:OPENAI_BASE_URL = "https://provider.example/v1"
$env:OPENAI_API_KEY = "你的密钥"
$env:WENVEIL_MODEL = "模型名称"
python app.py

点击“保存模型配置”后，开发环境写入 config/model_config.local.json；打包版写入 %LOCALAPPDATA%\WenVeil\model_config.local.json。两者都只保存在本机，开发环境文件已加入 .gitignore。默认不保存 API Key；只有主动勾选“同时保存 API Key”后，密钥才会以明文写入本机配置文件。环境变量 OPENAI_API_KEY 的优先级高于配置文件。

API Key 不写死、不导出到实体或风险报告，也不会进入应用日志。连接失败、超时、HTTP 429 和服务端错误会以错误类型记录，不记录请求正文。部分兼容服务不支持 response_format=json_object 时，客户端会自动回退为严格 JSON 提示词模式，返回内容仍需经过本地严格校验。

使用流程

1. 上传或拖入一个 .docx，点击“开始解析”。此时不会调用模型。
2. 查看部件统计和风险提示。无法扫描的图片、嵌入对象、宏、自定义 XML、外部链接等不会被宣称为已脱敏。
3. 填写模型配置，可先测试连接，再开始识别。
4. 在复核表中修改“是否替换”和“最终替换值”。默认“按敏感词汇总”，相同原文只显示一行并共用一个替换值；如只想保留某一次出现，切换到“按出现位置”后取消对应行即可。
5. 可按类型、置信度和原文筛选，批量启用/禁用、删除误识别、手动新增实体，或根据 segment 查看完整上下文。
6. 点击“保存表格修改”，再生成脱敏文档。可选导出实体清单和风险报告 JSON。

浏览器不能安全地直接指定任意本地输出目录，因此 MVP 采用浏览器下载方式；最终文件由本地后端生成并交给下载组件。

隐私与安全边界

始终留在本机的内容：

• DOCX 解压、OOXML 解析、字符映射和改写；
• 原始文件路径、用户名、临时目录路径；
• 图片和嵌入二进制对象；
• Word 文件属性，除非未来被明确作为扫描对象（当前不会发送）；
• 人工复核状态和导出的 DOCX。
• 可选保存的模型参数和 API Key 本地配置；该文件不会随文档或报告导出。

点击“开始识别”后会发送给第三方模型的内容只有：

{"segments":[{"segment_id":"package:filename","text":"待识别的文件名主体"},{"segment_id":"word/document.xml:p:18","text":"待识别的可见文字"}]}

程序不会发送原始文件路径、Windows 用户名或临时目录。文件名中经人工确认的敏感实体会同步应用到默认导出文件名。默认命名会优先移除主体、项目、日期等敏感片段，并保留“补充协议二”“审计报告”“会议纪要”等能够说明文件用途的通用标题；若无法留下有意义的用途标题，才使用“人员A”“公司A”等匿名占位符。

“增资协议”“补充协议（二）”“增资协议之补充协议（二）”等通用文档类型本身不视为敏感实体。即使模型误将这类纯通用标题返回，本地校验也会安全忽略；包含通用标题的完整文件名同样不会被整体替换成“敏感信息A”。

请根据所用供应商的隐私条款决定是否调用在线模型。程序默认不保存模型请求正文和完整响应正文，日志也不记录完整段落、人名、手机号、身份证号、银行卡号或邮箱。

Word 写入方式

替换以原始逻辑段落坐标为准，并在每段中按起始位置从后向前执行：

1. 同一 <w:t> 内命中：只修改该节点文字；
2. 跨节点命中：首节点保留命中前文字并追加替换值；中间命中文字清空；末节点只保留命中后文字；
3. 不删除 <w:r>、<w:rPr>、超链接、书签、批注锚点或修订容器；
4. 替换值继承首字符所在 run 的格式；
5. 每次修改后根据首尾空白同步 xml:space="preserve"。

重新打包时会先复制源 DOCX 到系统临时目录，完整解压、仅写回发生变化的 XML 部件、按原相对路径重新压缩，再验证并复制到会话输出目录。

风险检测

当前会检测并报告：图片、嵌入对象、OLE、图表、SmartArt、文本框、批注、脚注、尾注、超链接、内容控件、w:ins、w:del、w:delText、自定义 XML、宏相关部件、损坏或不可解析 XML、兼容内容和外部关系。

特别注意：

• <w:ins> 中当前可见的 <w:t> 会参与扫描；
• <w:delText> 和删除修订文字不并入普通可见文本，也不会被本工具清除；
• 图片文字、嵌入文件、图表数据、SmartArt 非 <w:t> 内容、宏代码和自定义 XML 不会被脱敏；
• 有修订记录的文档应在 Word 中接受/拒绝修订并再次检查后再对外发送。

自动化测试

.\.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
.\.venv\Scripts\python.exe -m pytest -q

测试 fixture 由 tests/fixtures/generate_fixture.py 编程生成，覆盖跨 run、字体、字号、加粗、颜色、表格、页眉页脚、脚注尾注、批注、超链接、文本框、内容控件、修订、OLE、外部链接及异常部件。需要生成一份可手动检查的样例时：

.\.venv\Scripts\python.exe tests\fixtures\generate_fixture.py

Windows onedir 打包

双击 build.bat，或执行：

.\.venv\Scripts\python.exe -m PyInstaller --noconfirm --clean wenveil.spec

构建脚本会先运行全量测试，测试失败则停止。成功后目录为：

dist/
└── WenVeil/
    ├── WenVeil.exe
    └── _internal/...

双击 WenVeil.exe 会打开一个控制台、启动本地网页，并在 Windows 通知区域显示“文隐匣 · WenVeil”常驻图标。网页顶部会明确提示“关闭网页不会退出程序”；可从网页或托盘菜单退出。保留控制台便于显示本地地址和不含文档正文的错误摘要。

项目结构

app.py
assets/       WenVeil 品牌图标及 Windows ICO 生成脚本
config/       开发环境本地模型配置说明；实际 *.local.json 已忽略
docs/images/  GitHub README 界面截图
wenveil/
  docx/       DOCX 包、部件发现、风险、字符映射、替换、验证
  llm/        Schema、提示词、分批和 OpenAI 兼容客户端
  services/   文档、识别、实体映射和匿名化编排
  web/        Gradio 页面、复核表和会话临时文件
  utils/      配置、异常、安全日志和清理
tests/        核心、模型、实体、UI 和端到端测试

当前限制

• 只支持 .docx；不支持 .doc、PDF、Excel、OCR、图片文字或本地大模型。
• 不读取图片、嵌入对象和自定义 XML 中的敏感文字。
• 不主动接受、拒绝或删除修订；删除修订和历史内容仍可能泄露信息。
• 不保证所有第三方自定义 Word 部件都能安全改写；含 <w:t> 的未知 word/*.xml 会谨慎纳入扫描并显示风险。
• 文本替换可最大限度保留 OOXML 结构，但 Word 的复杂域、第三方插件对象、损坏包或非常规 XML 仍需人工打开结果复核。
• 在线模型可能漏检、误识别或返回不合规内容；任何结果都必须人工确认。

许可证

本项目采用 MIT License。Copyright © 2026 ZheZZ。