适用场景

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

核心规则

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

• 使用 pandas 进行数据分析、数据重塑及类 CSV 任务。
• 当需保留公式、样式、工作表结构、批注、合并单元格，或需完整保活工作簿时，使用 openpyxl。
• 将 CSV 视为纯数据交换格式，而非功能完备的 Excel 替代方案。
• 读取单元格值、维持工作簿实时可编辑状态、从零构建模型——这些属于截然不同的电子表格任务，应采用不同策略。

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

• Excel 将日期存储为序列号，而非真正的日期对象。
• 1900 年日期系统包含一个错误的闰日（1900-02-29），部分工作簿则采用 1904 年系统。
• 时间以“天的小数部分”表示，因此格式设置与类型转换均至关重要。
• 仅保证日期数值正确并不足够；若数字格式仍向用户显示错误内容，则仍属失败。

3. 当工作簿需保持“活态”时，将计算逻辑保留在 Excel 中

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

4. 在 Excel 篡改数据类型前主动保护

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

5. 修改内容前，先确保工作簿结构完整保留

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

6. 交付前务必重新计算并人工复核

• 若接收方需要的是当前计算值，仅保留公式字符串远远不够。
• openpyxl 可保留公式，但不会执行计算。
• 确认交付版本中不存在 #REF!、#DIV/0!、#VALUE!、#NAME? 或循环引用导致的异常残留。
• 若版式呈现至关重要，则应在标记为“完成”前，渲染预览或进行可视化复核。
• 注意读取模式风险：以“仅读取值”模式打开工作簿后直接保存，会导致所有公式被扁平化为静态数值。
• 若必须保留某些假设值或硬编码覆盖项，请确保其足够醒目，以便后续编辑者可快速审计整个工作簿。

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

• 大型工作簿容易因平凡原因失败：内存峰值激增、大量空行填充、整表读取耗时过长等。
• 当文件体积大到一次性加载存在稳定性风险时，应启用流式读取（streaming）或分块读取（chunked reads）。
• 大文件工作流还需限制读取范围、显式指定数据类型（dtypes）、精准定位目标工作表，以规避意外破坏。

常见陷阱

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

关联技能

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

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

反馈

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