⚡ ExcelPilot 表格效率工具箱

本地离线运行的 Excel 效率工具箱，27 个工具，浏览器图形界面操作。 数据全程在本机内存和本地磁盘处理，不联网、不上传、不依赖任何在线服务。

每个工具都自带图文说明：一句话定位、适用场景、以及一段「处理前 → 处理后」的 循环动画演示（用真实样例数据渲染，无需任何外部图片/动图文件，鼠标悬停可暂停）。

每个工具还有操作引导：点标题右侧的「🎓 操作引导」，界面会依次高亮真正的控件、 说明这一步该填什么；你真的做完该步（传完文件 / 点了运行 / 出了结果）后会自动跳到 下一步，也可以手动点上一步、下一步或结束引导。

---

一、启动方式

方式 A：一键启动（推荐）

双击 启动工具箱.bat

• 首次运行时会自动安装依赖库（这一次需要联网）
• 之后每次双击即开即用，完全离线

方式 B：命令行

python -m excelpilot

然后浏览器访问终端里打印的地址（默认 http://127.0.0.1:8765）。 端口被占用时会自动顺延到下一个可用端口。

关闭那个黑色终端窗口即可停止服务。

---

二、27 个工具

🧹 整理清洗（8）

工具	说明
多表合并	一堆结构相近的表拼成一张，自动对齐表头
多 Sheet 合并	一个工作簿里十几个 Sheet 合并成一张总表
批量新建 Sheet	① 按列拆成多 Sheet ② 按名称清单批量建空表 ③ 复制模板 Sheet
一键拆分	按列拆成多个独立文件，或按行数切成小文件
智能去重	可忽略大小写/空格，支持只导出重复行核查
数据清洗	去空格、全角转半角、日期统一、删空行空列
智能向下填充	专治合并单元格留下的空格，自动填上方最近值
表头标准化	批量重命名列名，统一「客户名称/客户名」这类别名

✏️ 文本处理（4）

工具	说明
文本分列/合并	按分隔符或固定宽度拆分；多列按连接符合并
批量查找替换	跨多列替换，支持正则表达式
智能提取	从文本里抠出手机号/邮箱/身份证/网址/金额/日期
金额转大写	1234.56 → 壹仟贰佰叁拾肆元伍角陆分

✅ 校验转换（3）

工具	说明
数据校验	必填/唯一/正则/数值区间/枚举，输出问题清单并标红
格式转换	xlsx / csv / json 互转（csv 带 BOM，中文不乱码）
一键美化	冻结首行、自动筛选、自动列宽、隔行底色

📊 分析洞察（7）

工具	说明
数据透视	选行列维度+聚合方式，直接出交叉汇总表
统计画像	每列的类型/空值率/唯一值/均值中位数，类 pandas describe
模糊查重	编辑距离相似度，错别字也能归为一组近似重复
智能采样	随机抽 N 行、按比例、分层抽样，随机种子可复现
表格差异对比	两表按主键对比，标出新增/删除/修改了什么
长宽表转换	宽表转长表、长表转宽表
表格转置	行列互换

🚀 效率工具（5）

工具	说明
关联匹配	比 VLOOKUP 更强，支持左/内/外连接
数据脱敏	手机/身份证/姓名/邮箱/银行卡自动打码
造测试数据	一键生成逼真的中文测试数据
生成图表	在 Excel 里插入可编辑的真图表（柱/折线/饼）
公式助手	20 条高频公式速查

---

三、离线是怎么保证的

关注点	做法
Excel 读写	openpyxl（成熟库，纯 Python），不调用任何在线接口
Web 服务	Flask 只监听 127.0.0.1，外部机器访问不到
编码识别	chardet 本地探测，兼容 GBK 老文件
运行期联网	完全没有，可拔网线使用
唯一需要联网的时刻	首次安装依赖库那一次

---

四、项目结构

excel-toolkit/
├── 启动工具箱.bat      # 双击启动（Windows）
├── excelpilot/         # 包：Flask 服务端 + 27 个工具 + templates/
│   ├── app.py          #   Flask 服务端（路由）
│   ├── core.py         #   表格读写引擎（openpyxl 封装）+ 通用工具
│   ├── tools.py        #   工具集第一批（整理清洗 / 文本处理）
│   ├── tools_advanced.py#  工具集第二批（校验 / 分析 / 效率）
│   └── templates/index.html  # Web 界面
├── requirements.txt    # 依赖清单
├── test_all.py         # 工具逻辑测试（37 项）
├── test_web.py         # Web 路由测试（49 项）
├── test_http_real.py   # 真实 HTTP 端到端测试（21 项）
└── workspace/          # 运行时产生的上传与结果文件

加新工具只需两步：在 excelpilot/tools.py 里用 @register(...) 写一个函数， 前端表单会自动根据参数定义渲染，无需改动 HTML。

---

五、测试

python test_all.py        # 全部 27 个工具的逻辑与产出文件
python test_web.py        # Flask 路由：上传/运行/下载/错误处理
python test_http_real.py 8766   # 对运行中的服务做真实 HTTP 全流程

当前状态：37 + 49 + 21 = 107 项全部通过。

---

六、常见问题

Q：双击 bat 后闪退？ 把 bat 拖到已打开的 cmd 窗口里回车运行，能看到报错信息。多数是 Python 没装或没勾选 Add to PATH。

Q：提示「不是有效的 xlsx 文件」？ 老版 .xls 不是 xlsx（xlsx 本质是 zip 包）。请先用 Excel 另存为 .xlsx，或另存为 CSV。

Q：CSV 打开中文乱码？ 本工具写出 CSV 默认带 BOM（utf-8-sig），Excel 双击打开正常。若你要给老系统用，可在「格式转换」里选 GBK 编码。

Q：处理大文件会卡吗？ 预览只取前 200 行，实际处理全量。十万行级别的单表各工具一般几秒内完成。

Q：端口被占用？ 程序会自动顺延到下一个可用端口，看终端里打印的实际地址即可。也可设置环境变量 EXCELPILOT_PORT 指定。

---

七、完全离线分发（含依赖 wheel）

若目标机器不能联网，本仓库已附带 whls/ 目录，内含全部依赖的离线 wheel 包 （openpyxl / flask / chardet 及其传递依赖，共 16 个：Windows + Linux，Python 3.12/3.13）。

在目标机解压后，运行：

python -m pip install --no-index --find-links=whls -r requirements.txt

即可不联网装好全部依赖，随后双击 启动工具箱.bat 即可使用。

说明：whls/ 已内置 Windows(x86_64) 与 Linux(manylinux x86_64) 下 Python 3.12 / 3.13 的 wheel，pip 会根据目标机自动选用匹配的版本。 若目标机是 macOS 或非 x86_64 架构（如 ARM），请在有网的同环境下用以下命令重新拉取对应平台的 wheel：

python -m pip download -r requirements.txt -d whls -i https://pypi.tuna.tsinghua.edu.cn/simple/

---

八、使用 uv 启动

如果你习惯用 uv 管理环境，本仓库已附带 uv.lock， 可直接用 uv 一键创建虚拟环境并启动，无需手动 pip install：

uv sync          # 按 uv.lock 创建 .venv 并安装依赖（首次需联网）
uv run -m excelpilot    # 启动服务

或双击 启动工具箱-uv.bat（Windows）/ 运行 启动工具箱-uv.sh（Linux、macOS）： 脚本会先尝试 uv sync --offline（离线），失败再回退到联网 uv sync，然后自动 uv run -m excelpilot。 在 Linux/macOS 上首次运行前请先赋予执行权限：chmod +x 启动工具箱-uv.sh。

uv 自带 Python 版本管理；pyproject.toml 已声明 requires-python = ">=3.12"， 在 3.12 / 3.13 上均可运行。离线分发用的 whls/ 也已同时包含这两个版本、双平台的 wheel。

whls/ 是如何被「自动关联」的：pyproject.toml 里已配置 [tool.uv] find-links = ["whls"]，uv 会优先从 whls/ 目录匹配轮子； 因此 uv sync --offline 全程不联网、只用本地 uv.lock + whls/ 即可装好全部依赖。 （pip 路径则靠 启动工具箱.bat 里的 --find-links=whls 显式指定，效果相同。）