适用场景

当主要交付物为 Microsoft Excel 工作簿（.xlsx 文件）或电子表格文件时使用，尤其适用于公式、日期、格式、合并单元格、工作簿结构或跨平台行为具有实际业务意义的场景。

核心规范

1. 按任务选择工作流，而非凭习惯

• 执行数据分析、数据重塑或类 CSV 任务时，使用 pandas。
• 当公式、样式、工作表、批注、合并单元格或工作簿结构需完整保留时，使用 openpyxl。
• 将 CSV 视为纯数据交换格式，而非具备 Excel 全功能特性的替代方案。
• 读取单元格值、维护活动工作簿（live workbook）、从零构建模型——这些属于不同类别的电子表格任务。

2. 日期是带历史缺陷的序列号

• Excel 将日期存储为序列号，而非真正的日期对象。
• 1900 年日期系统包含一个虚构的闰日（leap-day）缺陷；部分工作簿则采用 1904 年系统。
• 时间以“天的小数部分”形式存储，因此格式设置与类型转换均影响结果准确性。
• 仅保证日期数值正确还不够——若单元格数字格式仍向用户显示错误内容，则结果不可接受。

3. 当工作簿需保持活动状态时，将计算保留在 Excel 中

• 在单元格中写入公式，而非由 Python 硬编码推导结果。
• 在公式中引用假设参数所在的单元格，避免直接嵌入“魔法数字”（magic numbers）。
• 缓存的公式计算结果可能已过期，编辑后切勿盲目信任其值。
• 交付前须检查复制的公式是否存在区域范围错误、工作表引用错误，以及静默发生的偏移一位（off-by-one）漂移问题。
• 绝对引用与相对引用本身即构成逻辑的一部分——即使复制后的公式“仍能运行”，也可能逻辑错误。
• 在整块区域填充新公式前，应先在若干典型单元格上进行测试验证。
• 发布依赖分母、命名区域（named ranges）或前置单元格（precedent cells）的公式前，须逐一确认其有效性。
• 交付的工作簿应无任何公式错误：不得遗留已知的 #REF!、#DIV/0!、#VALUE!、#NAME? 或循环引用导致的异常结果，交由用户自行修复。
• 针对建模类工作，应在批注或邻近说明中明确记录非显而易见的硬编码值、假设条件或原始输入来源。

4. 在 Excel 破坏数据类型前主动保护

• 长标识符、电话号码、邮政编码及含前导零的值，通常应以文本形式存储。
• Excel 会静默截断超过 15 位的数字精度。
• 混合文本与数字的列，在读取和写入时均需显式处理。
• 科学计数法表示、自动解析为日期、前导零被剥离等现象，属于数据损坏，而非仅视觉层面的问题。

5. 修改内容前先保留工作簿结构

• 已有模板优先于通用样式建议。
• 仅合并区域左上角单元格存储该区域的值。
• 隐藏行、隐藏列、命名区域及外部引用仍可能影响公式计算与输出结果。
• 共享字符串（shared strings）、已定义名称（defined names）及工作表级约定，即便在可见单元格看似简单时也可能至关重要。
• 对新填充的单元格应匹配既有样式，而非悄无声息地引入一套全新视觉体系。
• 若工作簿为模板，除非任务明确要求变更，否则须保留工作表顺序、列宽、冻结窗格、筛选器、打印设置、数据验证规则及视觉惯例。
• 条件格式、筛选器、打印区域与数据验证往往承载业务含义——即便用户仅提及“数字”本身。
• 若无现成样式指南且该文件为模型类工作簿，应使可编辑输入项在视觉上明显区别于公式；但绝不可强行覆盖既有模板以推行通用公司风格（house style）。

6. 发布前务必重新计算并人工复核

• 仅提供公式字符串不足以满足接收方对当前计算值的需求。
• openpyxl 可保留公式，但不执行计算。
• 须确保不存在 #REF!、#DIV/0!、#VALUE!、#NAME? 或循环引用引发的异常结果。
• 若布局呈现效果重要，应在标记为“完成”前进行渲染预览或人工视觉审查。
• 注意读取模式风险：以“仅读取值”方式打开工作簿后再保存，可能导致公式被扁平化为静态数值。
• 若必须保留某些假设值或硬编码覆盖项，请确保其足够醒目，以便后续编辑者可快速审计整个工作簿。

7. 根据文件规模调整工作流

• 大型工作簿常因平凡原因失败：内存峰值激增、存在大量空白填充行、全表读取速度缓慢等。
• 当文件大到一次性加载变得脆弱时，应采用流式（streaming）或分块（chunked）读取方式。
• 处理大文件的工作流还需限制读取范围、显式声明数据类型（dtypes）、精确指定目标工作表，以防意外破坏。

常见陷阱

• 读取时的类型自动推断可能导致数字被误判为文本，或 ID 被错误转为损坏的数值。
• 不同工具列索引方式不一致，生成公式时极易出现“偏移一位”（off-by-one）错误。
• 单元格内换行符需启用自动换行（wrap text）才能正确显示。
• 外部引用在源文件移动后极易失效。
• 旧版 Excel 工作流中的密码保护不具备实质安全性。
• .xlsm 文件可能包含宏；.xls 则是更严格的遗留格式。
• 大文件可能需要流式读取或更精细的内存管理策略。
• Google Sheets 和 LibreOffice 对日期、公式或样式的解释逻辑可能与 Excel 不同。
• FILTER、XLOOKUP、SORT、SEQUENCE 等动态数组函数或新版 Excel 函数，在较老版本查看器中可能无法运行或降级失效。
• 工作簿外观正常，却仍携带上一次重算后未更新的陈旧缓存值。
• 保存错误的工作簿视图（如“值视图”而非“公式视图”）会将公式替换为缓存值，悄然摧毁一个正在运行的模型。
• 复制公式时未校验相对引用，可能导致一个错误的引用范围扩散至整块区域。
• 隐藏工作表、命名区域、数据验证规则与合并区域常隐含关键业务逻辑，快速浏览时极易忽略。
• 工作簿数值计算完全正确，却因过滤器、条件格式、打印设置或数据验证被移除而实际失效。
• 工作簿数值正确，但因自动换行未启用、标签被截断或列宽过窄而视觉呈现失败，且从未经过人工审查。

相关技能

若用户确认，可通过以下命令安装：

• csv —— 纯文本表格数据的导入与导出工作流。
• data —— 在输出为电子表格前的通用数据处理模式。
• data-analysis —— 更高层级的数据分析流程，可为工作簿交付物提供支撑。

反馈

• 若本指南有用：clawhub star excel-xlsx
• 保持更新：clawhub sync

代码实现

Python 实现: excel_parser.py

from excel_parser import ExcelParser, read_excel, write_excel, excel_to_csv

# 读取
parser = ExcelParser('data.xlsx')
df = parser.to_dataframe()
parser.close()

# 或使用便捷函数
df = read_excel('data.xlsx')

# 写入
write_excel(df, 'output.xlsx')

# XLSX转CSV
excel_to_csv('data.xlsx', 'data.csv')