excel

description	用于读取、生成、编辑或分析 Excel 文件，以及处理公式重算、图表、透视表等电子表格任务。
lazy_load	true
name	excel
think_type	react

Excel 专业处理技能

🚀 完整代码示例（6 大场景 + 高级功能 + 性能优化）详见 @[skfile:references/examples.md]

---

Overview

Excel 处理技能，默认支持 .xlsx/.xlsm 的创建、读取、编辑、分析、公式验证和批量处理；.xls/.xlsb 需要可选依赖存在时才处理。

---

Capabilities & Triggering

🎯 该技能处理什么

能力域	具体操作	依赖库
读取	.xlsx/.xlsm 默认支持；.xls/.xlsb 需可选依赖	openpyxl, pandas；可选 xlrd, pyxlsb
创建/编辑	写入数据、公式、样式、图表、条件格式	openpyxl
公式重计算 ⭐	⭐首选：纯 Python 公式引擎（0.005s，支持 80+ 函数）	@[skfile:scripts/recalc_native.py]
数据分析	清洗、透视、统计分析	pandas, numpy
高级功能	pandas 透视汇总、数据清洗转换、保留宏文件(.xlsm)、条件格式、数据验证	openpyxl, pandas
批量处理	多文件并发、线程池加速	concurrent.futures

🚫 什么情况下不应激活此技能

不适用场景	说明
CSV/JSON/XML 等非 Excel 格式	不处理纯文本格式，由通用处理能力处理
PDF 转 Excel	不是本技能的直接能力
Excel 文件的内容理解/问答	仅提取数据，不进行语义分析
VBA 宏的编写/调试/执行	可读取/保留已有 VBA，但不编写、调试或执行宏代码

🔄 触发流程

用户请求 → 判断是否涉及 .xlsx/.xlsm 文件，或可选依赖支持的 .xls/.xlsb 文件
   ├─ 是 → 激活本技能
   │     ├─ 读取/分析 → 生成 Python 脚本 → Lint 检查 → 运行 → 返回数据
   │     ├─ 创建/编辑 → 生成 Python 脚本 → Lint 检查 → 运行
   │     │               └─ 是否含公式？
   │     │                   ├─ 是 → 公式强制 recalc ⭐
   │     │                   │        └─ recalc_native.recalc_detail() (模块导入)
   │     │                   └─ 否 → 直接交付
   │     └─ 公式重算 → recalc_native.py ⭐ → 验证 → 返回报告
   └─ 否 → 不激活

---

Work Flow

1. 需求分析 — 确定操作类型（读取/创建/编辑/分析/公式重算），选择对应依赖库
2. 初始化目录 — 确保 @[param:thread_dir]/tmps/ 与 @[param:user_work_dir] 存在
   • 中间脚本、调试日志、临时文件写入 @[param:thread_dir]/tmps/
   • 最终 .xlsx/.xlsm/.csv/.json/.txt 等交付物写入 @[param:user_work_dir]
   • 错误日志写入 @[param:thread_dir]/tmps/error.log
3. 依赖检查 — 生成脚本前确认所需库可导入；缺失时先报告缺少的包
   • 默认能力：openpyxl、pandas、numpy
   • .xls 读取：需要 xlrd
   • .xlsb 读取：需要 pyxlsb
   • 高性能写入：可选 xlsxwriter
4. 生成资源 — 使用 write tool 生成 Python 脚本到 @[param:thread_dir]/tmps/
5. Lint 检查 — 使用 @[tool:py_exec] 运行 py_compile 语法检查，确保代码无语法错误（详见下方 Lint 检查流程）
6. 执行脚本 — 使用 @[tool:py_exec] 的 file 参数执行脚本；不要用 shell 执行 python / python3 / pip
7. 公式强制 recalc 验证 ⭐ — 如果生成的脚本包含公式写入，必须执行 recalc（详见下方"公式强制 recalc 规则"）
8. 交付 — 返回 @[param:user_work_dir] 下的处理后文件 + 验证报告

公式重计算入口：只使用 recalc_native.py（纯 Python），不依赖外部办公套件。

---

⭐ 公式强制 recalc 规则

当 AI 生成的 Python 脚本包含公式写入（单元格值以 = 开头，或使用 openpyxl 的公式赋值如 ws['A1'].value = '=SUM(B1:B5)'）时，必须在脚本执行后追加 recalc 调用，以验证公式计算正确性并输出计算结果详情。

调用方式（按优先级）

优先级	方式	示例	适用场景
⭐	模块导入（推荐）	用 importlib.util.spec_from_file_location 从 @[skfile:scripts/recalc_native.py] 加载后调用 recalc_detail(output_path)	脚本与 recalc 在同一 Python 进程，无 I/O 开销
	py_exec 文件执行	使用 @[tool:py_exec] 执行 @[skfile:scripts/recalc_native.py] 并传入参数（如果工具支持）	脚本已执行完，单独验证

生成的 Python 脚本模板（含公式时）

# ... 前面的创建/编辑逻辑 ...
wb.save(output_path)

# ⭐ 公式强制 recalc — 验证计算结果并输出详情
import importlib.util
from pathlib import Path

RECALC_NATIVE_PATH = Path(r"@[skfile:scripts/recalc_native.py]")
spec = importlib.util.spec_from_file_location("excel_recalc_native", RECALC_NATIVE_PATH)
recalc_native = importlib.util.module_from_spec(spec)
spec.loader.exec_module(recalc_native)

recalc_result = recalc_native.recalc_detail(output_path)
if recalc_result.get("total_errors", 0) > 0:
    print(f"⚠️ 公式计算发现 {recalc_result['total_errors']} 个错误：")
    for err_type, info in recalc_result.get("error_summary", {}).items():
        print(f"  {err_type}: {info['count']} 处 — {', '.join(info['locations'][:5])}")
else:
    print(f"✅ 所有 {recalc_result['total_formulas']} 个公式计算无误")
    # 输出部分公式结果供用户确认
    for detail in recalc_result.get("formula_details", [])[:5]:
        print(f"  {detail['sheet']}!{detail['cell']}: {detail['formula']} = {detail['result']}")

豁免条件

• 用户明确要求"不要 recalc"、"跳过验证"时，跳过此规则
• 纯数据文件（无任何公式）不触发 recalc

失败处理

场景	处理
recalc_native.recalc_detail() 不可用或报错	报告错误详情；如需单独验证，使用 @[tool:py_exec] 执行 recalc 脚本，不要用 shell 调 Python
recalc_native 完全不可用	报告不支持的公式/错误详情，提示用户在 Excel 中手动打开重算

---

Lint 检查流程

生成的 Python 脚本在运行前必须通过语法检查，杜绝"边运行边报错边修改"的情况。流程如下：

生成代码 → 写入 .py 文件 → py_compile 编译检查
                                ↓
                          ✅ 通过 → 继续执行脚本
                                ↓
                          ❌ 失败 → 分析错误 → 重写修正 → 重新编译
                                                     ↓
                                          (最多重试 3 次)
                                ↓
                   3 次均失败 → 报告错误信息给用户

具体操作

1. 优先使用 @[tool:py_exec] 执行短代码完成编译检查：

   import py_compile
   py_compile.compile(r"<file_path>", doraise=True)
   

2. 编译通过后，使用 @[tool:py_exec] 的 file="<file_path>" 执行脚本。
3. 不要用 shell 调用 Python 编译或执行脚本。
4. 如果编译错误包含编码问题，检查文件头是否包含 # -*- coding: utf-8 -*-

Failure Strategy

失败场景	回退策略
文件格式不支持	检测扩展名；.xlsx/.xlsm 用 openpyxl，.xls 需 xlrd，.xlsb 需 pyxlsb；缺失依赖时明确报告
公式错误（#REF! / #DIV/0! / #NAME?）	#REF! 修复引用 · #DIV/0! 加 IFERROR · #NAME? 检查拼写
recalc_native.py 无法处理公式	报告不支持的公式/错误详情，提示用户在 Excel 中手动打开重算
内存不足（大文件）	使用 read_only 模式 / pandas 分块读取（chunksize）
文件被占用	提示关闭文件，重试
批量处理部分失败	记录失败文件和错误信息，继续处理其余文件
Lint 检查 3 次均失败	报告编译错误详情给用户，建议手动检查代码

---

脚本工具

⭐	脚本	用途	用法
⭐	@[skfile:scripts/recalc_native.py]	纯 Python 公式引擎（0.005-0.1s，80+ 函数，跨 sheet 引用）	推荐通过 importlib.util.spec_from_file_location 模块导入
		支持 --detail 输出每个公式的详细结果	如需单独运行，使用 @[tool:py_exec] 执行脚本文件，不要用 shell 调 Python
		支持模块导入（推荐方式）	recalc_native.recalc_detail(file)
	@[skfile:scripts/test_recalc_native.py]	recalc_native 开发验证脚本	仅维护/回归测试时使用

recalc_native.py 支持函数（80+ 种）

数学：SUM, AVERAGE, MIN, MAX, COUNT, COUNTA, ABS, SQRT, ROUND, ROUNDUP, ROUNDDOWN,
      INT, MOD, POWER, SUMIF, COUNTIF,
      SUMIFS, COUNTIFS, AVERAGEIF, SUMPRODUCT, PRODUCT, MEDIAN,
      RANK, CEILING, FLOOR, MROUND
逻辑：IF, AND, OR, NOT, IFERROR, IFNA, SWITCH, IFS, XOR
查找：VLOOKUP, HLOOKUP, INDEX, MATCH, XLOOKUP, UNIQUE, SORT,
      INDIRECT, OFFSET, CHOOSE, TRANSPOSE, LOOKUP, FILTER
文本：CONCATENATE, LEFT, RIGHT, MID, LEN, FIND, SEARCH, REPLACE, SUBSTITUTE,
      UPPER, LOWER, PROPER, TRIM, TEXT, TEXTJOIN, EXACT, VALUE, REPT
日期：TODAY, NOW, YEAR, MONTH, DAY, DATE, DATEDIF,
      EOMONTH, EDATE, WEEKDAY, NETWORKDAYS, HOUR, MINUTE, SECOND
信息：ISBLANK, ISNUMBER, ISTEXT, ISERROR, N
统计：STDEV, VAR, LARGE, SMALL, PERCENTILE, QUARTILE
财务：PMT, FV, PV, NPV

---

索引

内容	文件	章节
场景 1-6 完整代码示例	@[skfile:references/examples.md]	场景操作代码示例
高级功能（pandas 透视汇总/数据清洗转换/保留宏/条件格式/数据验证）	@[skfile:references/examples.md]	高级功能
性能优化（大文件/批量写入/并发）	@[skfile:references/examples.md]	性能优化
最佳实践（文件组织/错误处理/日志）	@[skfile:references/examples.md]	最佳实践