Excel全能工具箱

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

功能路由表

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

快速开始

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

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

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

cd scripts/
pip install -r requirements.txt

典型工作流

# 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，无需用户指定

技术栈

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 清单

Pre-Delivery Checklist

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

references/ 索引