这是个啥？
-
项目名：mask-tool
一个本地文件脱敏工具。作为社畜牛马，天天跟合同、可研报告、立项汇报打交道，里面全是公司名、金额、项目名，不敢扔给AI处理，想要脱敏一个个替换，眼睛都瞎了。一动不如一静，干活不如摸鱼，为了解救本牛马的视网膜，本牛马决定要做一个程序帮我续命延寿保肝护眼。
这个工具就是干这个的：扔进去一个文件夹，自动识别敏感信息，一键批量脱敏。脱敏完全本地化处理，处理后可以放心的交给大模型和agent进行分析。可以选择可逆脱敏，利用映射表将还可以将分析结果中的文件掩码还原成万原本的名称。堪称牛马续命神器。
纯小白作品，但确实能用了。
开发时间线
2025年4月17日 ~ 4月22日，5天。
Day 1（4月17日晚上）：从零到第一版
第一版代码架构当天晚上就搞出来了。分层设计、CLI命令、检测引擎、文件适配器、单元测试，一口气写了一堆文件2000行代码。当时觉得：这也太顺了吧？
然后现实就开始毒打了。
Day 2-3：小白的至暗时刻
GitHub PAT事件：
-
不知道GitHub已经不支持密码登录了，终端里疯狂输密码被拒
-
好不容易知道要用Personal Access Token，一激动生成了一个全部权限的PAT
-
Trae立刻弹出警告：“施主万万使不得！”
-
赶紧删掉，重新生了一个最小权限的
依赖地狱：
-
Python版本不对（3.9 vs 3.10），改了pyproject.toml
-
pip版本太旧，
pip install -e .直接报错 -
装好的包是x86架构的，Mac是ARM的，lxml、Pillow、PyMuPDF轮番报架构不兼容
-
pip install --force-reinstall --no-cache-dir成了口头禅
会话快满了：
-
聊着聊着上下文爆了，只好把当前进度总结一下，开新会话接着干
-
新会话的第一句话永远是：“继续开发mask-tool，项目总结见上文”
Day 4：甲方本色暴露
第一版能跑之后，拿真实文件一测，问题全来了：
-
"XX行"4处只替换了2处（Word把文字拆到不同run里了）
-
地名，国名根本没识别出来
-
脱敏范围太大，连"汇报"、"深度"都被标记了
-
各种词语切分错误
原本以为差不多就行了，结果测着测着要求越来越多：
-
命令行跑着多不舒服，做一个可以互动的UI，不难吧；
-
能不能加个词典功能，把脱敏过的单词放进去后续都照着执行；
-
反过来词典也无法穷尽，你得发挥主观能动性，把各种公司、地名什么的自动加进去，别麻烦我；
-
jieba NER比较笨，能不能加多点智能；
-
自制的软件迁移到win/mac上各种环境依赖还叠重装，直接连个im远程调用行不行，就当一个脱敏龙虾用？
-
OCR啥时给解决下？
-
这个表格不好看，不好用，能不能给我微调一下。
-
结果发现，我心里以为很简单的改动，确实个不小的活。
Day 5：心态平和
改来改去花了好几天，心想：能先出一版能用的就行吧。
于是定了路线：第一版可用 → 后续加Web界面/OCR/词库编辑/更准的识别。
技术架构（正经部分）
Plain Text
mask-tool/
├── src/mask_tool/
│ ├── cli/ # 命令行入口（typer）
│ ├── models/ # 数据模型
│ ├── core/ # 核心引擎
│ │ ├── detector.py # 检测：词典 > NER > 正则
│ │ ├── policy.py # 策略：focused/strict/smart/aggressive
│ │ ├── masker.py # 脱敏执行器
│ │ ├── tokenizer.py # Token生成
│ │ ├── confirm.py # 人工确认引擎
│ │ ├── pipeline.py # 流水线
│ │ └── ner/ # NER（jieba posseg）
│ ├── adapters/ # 文件适配器（docx/xlsx/pptx/pdf）
│ ├── store/ # 词库管理
│ └── utils/ # 工具函数
├── config/ # 配置文件+词库+白名单
├── tests/ # 45个单元测试，全部通过
└── pyproject.toml
依赖：typer, rich, pyyaml, python-docx, openpyxl, python-pptx, pymupdf, jieba, lxml, Pillow
四种模式：focused（精准）< strict（保守）< smart（标准）< aggressive（激进）
CLI命令：
Bash
mask-tool inspect <文件> [--mode focused] # 检测
mask-tool mask <文件> -o ./output/ [--confirm] # 脱敏（可加人工确认）
mask-tool unmask <文件> --mapping mapping.json -o ./restored/ # 反脱敏
mask-tool config -o ./ # 生成配置
SOLO 在我流程中做了什么
-
架构设计：帮我规划了清晰的分层结构
-
代码生成：生成了 80% 以上的核心代码
-
Bug 修复：快速定位并修复了多个关键问题
-
跨平台部署：生成了 Mac/Windows 安装脚本
已知问题（诚实版）
-
jieba会把"东西长"识为人名、"汇报"识别为专名 → 需要Web界面让用户手动调整
-
长词组往往被切成好几个短的词语 → 需要词典最长匹配
-
终端逐条确认太慢（几十上百条词条） → 需要Web界面批量操作
-
同一批次不同文件有相同敏感词，要重复确认 → 需要跨文件合并
-
PDF只读不能回写 → 需要OCR
-
词库里还有测试用的"华为"“张三” → 需要清理
后续开发计划
| 阶段 | 内容 | 一句话 |
|---|---|---|
| Phase 4a | Streamlit Web界面 | 告别终端，浏览器里勾选 |
| Phase 4b | 识别精度提升 | 最长匹配+缩写关系+词条补充 |
| Phase 4c | 词库充实 | 导入国央企/上市公司名单 |
| Phase 5 | OCR | PaddleOCR识别扫描件和图片 |
| Phase 6 | README + v0.1.0 | 正式发布 |