Excel大师

处理Excel文件、表格数据、批量转换或报表生成时应用本skill。核心信条：先看文件多大，再选工具；先问要不要保格式，再动笔。

四大痛点与对策

第一步：按文件规模选工具

中大文件流式读取（避免OOM）

from openpyxl import load_workbook

# read_only=True 不把整个文件载入内存
wb = load_workbook("big.xlsx", read_only=True, data_only=True)
ws = wb["Sheet1"]
for row in ws.iter_rows(values_only=True):
    # 逐行处理，内存恒定
    process(row)
wb.close()  # read_only 必须显式关闭

大文件流式写入

from openpyxl import Workbook

wb = Workbook(write_only=True)  # 流式写，无法修改已写行
ws = wb.create_sheet("结果")
ws.append(["列A", "列B", "列C"])
for row in data_stream:
    ws.append(row)
wb.save("output.xlsx")  # 不会OOM

第二步：格式保留矩阵

> 90%的"格式丢失"问题源于选错了工具。

两条路径选择

路径A：纯数据处理（不关心格式）

import pandas as pd
df = pd.read_excel("input.xlsx", engine="openpyxl")
# ... 处理 ...
df.to_excel("output.xlsx", index=False, engine="openpyxl")

路径B：保留原格式改数据（只动目标单元格）

import openpyxl
wb = openpyxl.load_workbook("input.xlsx")  # 不加read_only
ws = wb["Sheet1"]
ws["C2"] = new_value  # 只改这一格，其余格式全保留
wb.save("output.xlsx")

第三步：四大陷阱与规避

陷阱1：data_only=True拿到None

# 错误：文件从未被Excel打开过，公式没有缓存值
wb = openpyxl.load_workbook("file.xlsx", data_only=True)
ws = wb.active
print(ws["A1"].value)  # None，因为公式结果从未被Excel计算并保存

# 正确方案1：用Excel打开保存一次（让Excel写入缓存值）
# 正确方案2：用formulas库重算
# pip install formulas
import formulas
xl = formulas.ExcelModel().loads("file.xlsx").finish()
sol = xl.calculate()
# 正确方案3：只读公式字符串（不读值）
wb = openpyxl.load_workbook("file.xlsx", data_only=False)
print(ws["A1"].value)  # "=SUM(B1:B10)" 公式字符串

陷阱2：长数字变科学计数法

# 错误：身份证号110101199001011234变成1.10E+17
df = pd.read_excel("input.xlsx")
df["身份证号"]  # 已是float，精度丢失

# 正确方案1：读取时指定dtype
df = pd.read_excel("input.xlsx", dtype={"身份证号": str})

# 正确方案2：openpyxl读
wb = openpyxl.load_workbook("input.xlsx")
ws = wb.active
for row in ws.iter_rows(values_only=True):
    id_card = str(row[0])  # 字符串保留

# 正确方案3：写入前强制文本格式
from openpyxl.styles import numbers
ws["A1"].number_format = numbers.FORMAT_TEXT
ws["A1"] = "110101199001011234"

陷阱3：CSV编码错乱

# 错误：中文乱码或报错
df = pd.read_csv("input.csv")  # 默认UTF-8，但Excel导出的CSV可能是GBK

# 正确方案1：尝试多种编码
for enc in ["utf-8", "gbk", "gb18030", "utf-8-sig"]:
    try:
        df = pd.read_csv("input.csv", encoding=enc)
        break
    except UnicodeDecodeError:
        continue

# 正确方案2：写入CSV时加BOM（让Excel正确识别UTF-8）
df.to_csv("output.csv", index=False, encoding="utf-8-sig")

陷阱4：合并单元格读写

# 读取：合并单元格只有左上角有值，其余为None
ws = wb["Sheet1"]
for row in ws.iter_rows():
    for cell in row:
        if cell.value is None and cell.coordinate in ws.merged_cells:
            # 处于合并区域内，取左上角值
            pass

# 写入：先解除合并再写
from openpyxl.utils import range_boundaries
for merged_range in list(ws.merged_cells.ranges):
    ws.unmerge_cells(str(merged_range))
ws["A1"] = value

第四步：脚本速查表

本地运行

# 进入skill目录或把scripts/加入PATH
pip install -r scripts/requirements.txt
python scripts/merge_sheets.py --help

第五步：通用处理流程

1. 确认输入：文件路径、sheet名或索引、是否有表头、编码（CSV时）
2. 选工具：按文件规模分层表选pandas或openpyxl
3. 读取：按需读整表/区域/流式
4. 处理：转换、过滤、合并、计算
5. 写出：指定输出路径与格式；需保格式则用openpyxl单格改写
6. 校验：检查行数、关键列、重复值、业务规则

读取Excel

# 整表为list of dict（保表头）
import openpyxl
wb = openpyxl.load_workbook("input.xlsx", read_only=True, data_only=True)
ws = wb.active
rows = list(ws.iter_rows(values_only=True))
header = rows[0]
data = [dict(zip(header, row)) for row in rows[1:]]
wb.close()

# pandas（适合分析、过滤、合并）
import pandas as pd
df = pd.read_excel("input.xlsx", sheet_name=0, engine="openpyxl")

# 指定区域
df = pd.read_excel("input.xlsx", usecols="A:D", header=0, nrows=100)

写入Excel

# 新建并写入（openpyxl）
from openpyxl import Workbook
from openpyxl.styles import Font
wb = Workbook()
ws = wb.active
ws.title = "结果"
ws.append(["列A", "列B", "列C"])
for row in data_rows:
    ws.append(row)
ws["A1"].font = Font(bold=True)
wb.save("output.xlsx")

# pandas多sheet写出
with pd.ExcelWriter("output.xlsx", engine="openpyxl") as writer:
    df1.to_excel(writer, sheet_name="汇总", index=False)
    df2.to_excel(writer, sheet_name="明细", index=False)

# 追加到已有文件
wb = openpyxl.load_workbook("existing.xlsx")
ws = wb["Sheet1"]
for row in new_rows:
    ws.append(row)
wb.save("existing.xlsx")

第六步：批量处理目录

from pathlib import Path
import openpyxl, json

results = []
errors = []
for file in Path("目录").glob("*.xlsx"):
    try:
        wb = openpyxl.load_workbook(file, read_only=True, data_only=True)
        ws = wb.active
        # 处理...
        results.append({"file": file.name, "rows": ws.max_row})
        wb.close()
    except Exception as e:
        errors.append({"file": file.name, "error": str(e)})
        continue  # 出错继续处理其余文件

# 汇总报错列表
if errors:
    with open("errors.json", "w", encoding="utf-8") as f:
        json.dump(errors, f, ensure_ascii=False, indent=2)

批量输出命名规则建议：原名_out.xlsx 或统一汇总到一个文件。

第七步：性能优化技巧

校验与错误处理

• 读取前用Path(file).exists()检查文件存在
• 表为空或缺少预期列时给出明确提示（列名/行数）
• 写入前若目标文件已存在，按用户要求覆盖或换名；大文件用write_only=True或分块
• 捕获openpyxl.utils.exceptions.InvalidFileException、KeyError（工作表名）并返回可读错误

常见错误代码

技术栈

• 读写.xlsx：openpyxl（保留格式、公式、多工作表）
• 数据分析/透视：pandas + openpyxl引擎
• 旧格式.xls：xlrd（只读）
• 公式重算：formulas库（按需）

pip install openpyxl pandas xlrd formulas

FAQ

Q：50万行Excel一读就OOM怎么办？
A：用load_workbook(read_only=True, data_only=True)流式读取，配合iter_rows(values_only=True)逐行处理，内存恒定。

Q：用pandas读写后Excel颜色和公式都没了？
A：pandas只处理数据不处理格式。需要保格式就用openpyxl加载原文件，只改目标单元格再save（见"路径B"）。

Q：身份证号变成科学计数法怎么救？
A：读取时dtype={"身份证号": str}，或openpyxl读后str(cell.value)。写入前设number_format = FORMAT_TEXT。

Q：data_only=True读公式单元格是None？
A：文件从未被Excel打开保存过，没有缓存值。要么用Excel打开存一次，要么用formulas库重算，要么data_only=False读公式字符串。

Q：多个Excel文件需要合并到一个sheet？
A：用merge_sheets.py --inputs 目录 --output out.xlsx，或pandas的pd.concat([pd.read_excel(f) for f in files])。

Q：CSV用Excel打开中文乱码？
A：写入时encoding="utf-8-sig"加BOM，Excel就能正确识别UTF-8。

故障排查

依赖说明

运行环境

• Agent平台：支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统：Windows / macOS / Linux
• Python：3.8+（推荐3.10+）

第三方依赖

API Key 配置

• 本skill基于本地脚本，无需额外API Key
• 涉及读取在线Excel（如OneDrive）时需对应平台OAuth Token

可用性分类

• 分类：MD+EXEC（Markdown指令 + Python脚本执行）
• 说明：通过自然语言指令驱动Agent调用scripts/下的Python脚本完成Excel处理