核心功能: 本技能提供中文交互、工作流程和配置参考、化工作流场景等能力。

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%的"格式丢失"问题源于选错了工具. | 操作需求 | 用pandas | 用openpyxl | 说明 | |---:|---:|---:|---:| | 纯数据读写 | ✅ | ✅ | pandas更简洁 | | 保留单元格颜色/字体 | ❌ | ✅ | pandas会丢 | | 保留公式 | ❌ | ✅ | pandas只存值或公式字符串 | | 保留图表/透视表 | ❌ | ⚠️部分 | openpyxl能保留已有图表，不能新建复杂图表 | | 保留合并单元格 | ❌ | ✅ | pandas会展开 | | 保留条件格式 | ❌ | ✅ | pandas会丢 | | 多表合并/分析 | ✅ | ⚠️慢 | pandas DataFrame更适合 | | 大文件流式 | ⚠️chunksize | ✅read_only | openpyxl更稳 |

两条路径选择

路径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.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:
            # 处于合并区域内，取左上角值
            ...  # 具体实现请参考上下文文档
# ...
# 写入：先解除合并再写
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目录或把（请参考skill目录中的脚本文件）
pip install -r （请参考skill目录中的脚本文件）
python （请参考skill目录中的脚本文件） --help

---

第五步：通用处理流程

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

读取Excel

# 整表为list of dict（保表头）
import openpyxl
wb = openpyxl.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.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

---

问题解答汇总

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基于本地脚本，基础LLM由Agent平台提供
• 涉及读取在线Excel（如OneDrive）时需对应平台OAuth Token

可用性分类

• 分类：MD+EXEC（Markdown指令 + Python脚本执行）
• 说明：通过自然语言指令驱动Agent调用（请参考skill目录中的脚本文件）

功能清单

• Excel大师是面向批量表格处理的能力包
• 它不只罗列脚本，更解决四个高频痛点： 大xlsx一加载就内存爆炸、用pandas读写后格式公式全丢失、长数字变成科学计数法、 data_only=True拿到公式却是None 技术实现要点：核心能力基于input_params参数与output_format配置实现,支持创建/查询/修改/删除等操作模式,通过config_options进行运行时配置.

核心功能执行

用input_params参数进行配置. 处理: 解析核心功能执行的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回核心功能执行的响应数据,包含返回码、数据和处理记录.

• 调用时传入input_params参数,支持创建/查询/导出操作

参数配置与调用

用config_options参数进行配置. 处理: 解析参数配置与调用的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回参数配置与调用的响应数据,包含返回码、数据和处理记录.

• 执行此能力时使用config_options参数,支持修改/重置/导入操作

结果处理与输出

用output_format参数进行配置. 处理: 解析结果处理与输出的输入参数,完成核心逻辑,输出标准化响应数据. 输出: 返回结果处理与输出的响应数据,包含返回码、数据和处理记录.

• 执行此能力时使用output_format参数,支持导出/保存/转换操作 能力覆盖范围：本技能覆盖以下场景：解决大文件内存爆、格式丢失、公式不计算四大痛、按文件规模分层处、Use、when、需要文件处理、文档转换、格式互转、内容提取时使用、不适用于加密文件等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

实操说明

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。

应用场景

使用指南

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

应用示例

示例1：大文件流式读取避免OOM

用户需要读取一个 50 万行的 Excel 文件并提取关键列，直接加载会内存爆炸：

输入: 50万行xlsx文件，需提取"订单号"和"金额"两列
处理:
  1. 按文件规模分层：>50万行 → openpyxl read_only 流式
  2. 使用 iter_rows(values_only=True) 逐行读取
  3. 身份证号/订单号列指定 dtype=str 防止科学计数法
  4. 内存恒定，不随行数增长
输出: 成功提取 500,000 行数据
      内存占用: ~50MB（恒定）
      耗时: 12秒
      保存为 output.csv（utf-8-sig 编码）

示例2：保留格式修改单元格

用户需要在保留原有颜色、公式、合并单元格的前提下修改某列数据：

输入: 在已有的报表xlsx中更新C列销售额，保留所有格式
处理:
  1. 选择路径B：openpyxl load_workbook（不加read_only）
  2. 只修改目标单元格 ws["C2"] = new_value
  3. 其余格式（颜色/字体/公式/合并）全部保留
  4. save 输出新文件
输出: output.xlsx 已保存
      原有格式: 100%保留（颜色、公式、合并单元格均未丢失）
      修改内容: C列 200 行销售额已更新

限制条件

• 大文件处理（>100MB xlsx）仍可能触发内存限制，openpyxl模式建议文件不超过50MB
• 格式保真度受openpyxl/pandas能力限制，部分Excel高级特性（如数据透视表、条件格式中的色阶）可能丢失
• 科学计数法转换需指定列范围，全表扫描可能将非数值文本误判为数字导致数据损坏

输出规范

{
  "success": true,
  "data": {
    "result": "Excel大师处理结果",
    "execution_time": "0.5s",
    "metadata": {
      "version": "1.0",
      "processor": "excel maestro"
    }
  },
  "execution_log": ["解析输入参数", "执行核心处理", "格式化输出结果"],
  "error": null
}

安全规范

优势对比

部署指引

1. 配置API密钥: 在环境变量中设置对应的API Key
2. 初始化连接: 使用提供的凭证建立API连接
3. 调用接口: 传入必要参数执行API调用
4. 准备文件: 确认文件路径正确且格式受支持
5. 执行处理: 调用对应的处理函数
6. 查看结果: 检查输出文件或返回数据
7. 检查环境: 确认运行时和依赖已安装
8. 执行命令: 使用正确的参数格式执行
9. 查看输出: 检查命令输出和退出码

前置条件

• 已安装所需运行环境(参考依赖说明)
• 已获取必要的API密钥或访问凭证(如适用)
• 输入数据已准备就绪

Excel大师通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

用户答疑汇总

Q1: Excel大师支持哪些输入格式？

A1: 解决大文件内存爆炸、格式丢失、科学计数法、公式不计算四大痛点，按文件规模分层处理.。Excel大师是面向批量表格处理的能力包。它不只罗列脚本，更解决四个高频痛点。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

故障修复指南

针对Excel大师使用中可能遇到的常见问题,提供以下排查方案:

依赖说明

运行环境

• Agent 平台: 支持SKILL.md的任意AI Agent
• 操作系统: Windows / macOS / Linux

可用性分类

• 分类: MD（纯Markdown指令，通过自然语言驱动Agent完成操作）
• 说明: 基于Markdown的AI Skill，通过自然语言指令驱动Agent完成操作。