Excel全能工具箱

Excel全能工具箱：读写、预览、合并、拆分、关联、去重、清洗、校验、模板填充、样式、条件格式、公式、图表、透视表、数据分析、差异对比、图片插入、密码保护。典型场景：月度业务报表合并汇总、HR花名册/考勤表关联清洗、运营数据透视分析、绩效数据校验去重、批量生成offer/通知模板、薪酬表加密保护、业务周报图表生成。触发词：Excel、表格、xlsx、csv、电子表格、合并Excel、拆分Excel、Excel图表、数据透视表、Excel公式、条件格式、数据清洗、Excel模板、Excel对比、Excel加密、VLOOKUP、去重、数据校验、统计分析、格式转换、业务报表、花名册、考勤表、绩效数据、运营数据、excel toolbox、spreadsheet、merge excel、split excel、excel chart、pivot table。即使用户没有明说'用Excel工具箱'，只要涉及Excel/表格/xlsx/csv文件的操作都应触发。不适用：在线协作编辑(用Google Sheets等在线工具)、纯代码开发、Skill管理。

IRON LAW：①操作前必须先 peek 了解文件结构（WHY：盲操作=猜列名猜Sheet名，错误率极高）；②写入/修改操作必须保留原文件备份（WHY：Excel 操作不可逆，无备份=数据丢失风险）；③大文件（>10万行）必须用流式模式（WHY：全量加载会撑爆内存导致进程被 kill）；④输出文件路径必须用绝对路径并确认目录存在（WHY：相对路径在不同 cwd 下行为不一致）。

功能路由表

根据用户意图匹配对应脚本。所有脚本位于 scripts/ 目录下

#	功能	脚本	场景举例
1	📋 智能预览	peek.py	"帮我看看这个Excel有几个Sheet、每个Sheet有什么列"
2	📖 读取Excel	read_excel.py	"读取sales.xlsx的Sheet2，取A~D列前100行"
3	✏️ 写入/创建	write_excel.py	"把这份数据生成一个Excel文件"
4	🔄 格式互转	convert.py	"把这个csv转成xlsx"、"把Excel导出为JSON"
5	📎 合并文件	merge.py	"把这5个月度报表合并成一个年度汇总表"
6	✂️ 拆分文件	split.py	"把大表按Sheet拆成独立文件"
7	✂️ 按列值拆分	split.py --mode by-column	"按'部门'列拆分，每个部门一个独立Excel"
8	🔗 VLOOKUP/关联	vlookup.py	"用工号把花名册和考勤表关联起来"
9	🧹 去重	dedup.py	"按姓名+手机号去重，保留最新的那条"
10	🧽 数据清洗	clean.py	"把空行删掉，手机号统一11位，日期统一YYYY-MM-DD"
11	📄 模板填充	template_fill.py	"用员工数据批量生成offer letter"
12	✅ 数据校验	validate.py	"检查哪些行邮箱格式不对、哪些工号重复了"
13	🎨 条件格式	style.py --mode conditional	"绩效低于60标红，高于90标绿"
14	💅 样式排版	style.py	"给表头加粗加背景色，列宽自适应，加边框"
15	📐 函数公式	formula.py	"在E列加SUM公式汇总B~D列"
16	📊 图表生成	chart.py	"用销售数据生成柱状图+折线图组合"
17	📈 数据透视表	pivot.py	"按部门和月份交叉汇总销售额"
18	🔬 数据分析	analyze.py	"给我这份数据的统计摘要：均值、中位数、分布"
19	🔍 差异对比	diff.py	"对比两版花名册，哪些人新增/离职/信息变更"
20	🖼️ 图片插入	image.py	"在每个员工对应行插入照片"
21	🔒 密码保护	protect.py	"给薪酬表加密码保护"、"解密这个加密的Excel"
22	⚡ 大文件处理	自动触发	超10万行自动切换流式模式，坏行跳过并汇报

快速开始

环境准备（全自动，无需手动操作）

首次调用任何脚本时，utils.py 会自动检测并安装缺失依赖（版本锁定，120s 超时兆底）。安装完成后自动验证导入成功才继续执行。

手动安装（仅当自动安装失败时）：

bash

cd scripts/
pip install -r requirements.txt

典型工作流

bash

# 1. 先看文件结构
python3 peek.py input.xlsx

# 2. 根据需要操作
python3 read_excel.py input.xlsx --sheet Sheet1 --format json
python3 merge.py file1.xlsx file2.xlsx --output merged.xlsx
python3 chart.py data.xlsx --type bar --x-column 月份 --y-columns 销售额 --output report.xlsx

核心设计原则

1. Peek First：任何操作前先预览文件结构，避免盲操作
2. 安全写入：修改操作自动备份原文件（原文件名_backup_时间戳.xlsx）
3. 流式处理：>10 万行自动切换 read_only/write_only 模式，防止内存溢出
4. 错误容错：遇到坏行/坏单元格跳过继续，最后汇总错误报告（ErrorCollector）
5. 统一输出：所有脚本支持 --format（json/csv/markdown/table）
6. 管道友好：支持 stdin/stdout，可与其他工具组合
7. 依赖自愈：首次运行自动安装缺失依赖（版本锁定），安装后验证导入成功才继续
8. 编码自适应：CSV 自动尝试 UTF-8/GBK/GB2312/Latin-1，无需用户指定

技术栈

库	用途
openpyxl	核心读写 + 样式 + 公式
pandas	数据分析 + 透视 + 清洗
xlsxwriter	高性能写入 + 图表渲染
xlrd	.xls 旧格式只读兼容
msoffcrypto-tool	文件级加密/解密
numpy	数值计算（分析/清洗）

Gotchas

• chart.py 用 xlsxwriter 不能修改已有文件：它会新建文件写入数据+图表。如需在已有文件加图表，先用 openpyxl 读数据，再用 xlsxwriter 生成新文件
• openpyxl 的 data_only=True 会丢失公式：读取计算结果时用 data_only=True，但保存后公式消失。需要公式时不加此参数
• 条件格式的颜色值不带 #：openpyxl 颜色用 6 位十六进制（如 FF0000），不要加 # 前缀
• csv 编码：Windows Excel 生成的 csv 常为 GBK/GB2312，用 --encoding gbk 参数处理
• 合并时列名对齐：不同文件列名不完全一致时，用 concat 模式会自动对齐（缺失列填 NaN）
• 模板填充占位符：使用 {{字段名}} 语法，字段名必须与数据源列名完全一致（含大小写）

子Agent最小执行规范

必读文件：SKILL.md

不可跳过的硬 Gate：

• 操作前必须 peek.py 了解文件结构
• 写入操作确认输出路径存在
• 大文件自动走流式模式

禁止行为：

• 禁止不 peek 直接操作（盲猜列名）
• 禁止覆盖原文件不备份
• 禁止全量加载 >10 万行的文件

Anti-Pattern 清单

#	反模式	正确做法
1	不看文件结构直接操作	先 peek.py 确认 Sheet/列名/行数
2	猜测列名填参数	从 peek 结果中复制精确列名
3	大文件全量加载	utils.py 自动检测并切换流式模式
4	覆盖原文件	输出到新路径或让 safe_write 自动备份
5	硬编码文件路径	用用户提供的路径，不假设固定位置
6	忽略错误继续	用 ErrorCollector 收集所有错误最后汇报

Pre-Delivery Checklist

• 操作前已 peek 确认文件结构
• 输出路径已确认存在且可写
• 写入操作有原文件备份
• 大文件已走流式模式
• 错误已汇总报告给用户
• 输出格式符合用户要求

references/ 索引

文件	说明
references/api-reference.md	各脚本完整参数说明 + 代码示例
references/examples.md	22 个功能的场景举例合集