适用场景

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

核心准则

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

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

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

• Excel 将日期存储为序列号，而非真正的日期对象。
• 1900 年日期系统包含一个错误的闰日（即“1900-02-29”），部分工作簿则采用 1904 年日期系统。
• 时间以“天的小数部分”表示，因此格式设置与类型转换均会影响最终显示和计算结果。
• 仅保证日期数值正确并不足够；若单元格数字格式仍向用户呈现错误结果，则业务逻辑即已受损。

3. 当工作簿需保持实时可编辑时，将计算保留在 Excel 中

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

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

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

5. 在修改内容前，先保全工作簿结构

• 已有模板优先于通用样式建议；切勿覆盖客户/业务方既定结构。
• 仅合并区域左上角单元格实际存储值，其余单元格为空。
• 隐藏行、隐藏列、命名区域、外部引用等元素，即便不可见，仍可能影响公式运算与输出结果。
• 共享字符串表（shared strings）、已定义名称（defined names）及工作表级约定（如特定列用途），即使表面单元格看似简单，也可能承载关键语义。
• 对新填充的单元格应用匹配样式，避免悄然引入一套不兼容的视觉体系。
• 若工作簿为模板，除任务明确要求变更外，须保全工作表顺序、列宽/行高、冻结窗格、筛选器、打印设置、数据验证规则及视觉规范。
• 条件格式、筛选器、打印区域与数据验证规则，往往隐含重要业务逻辑——即便用户仅提及“数字”本身。
• 若无现成样式指南且该文件为建模用途，应确保可编辑输入项在视觉上明显区别于公式；但绝不可为强推通用公司风格而覆盖既有模板。

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

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

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

• 大型工作簿易因平凡原因失败：内存峰值、大量空白填充行、整表慢速读取等。
• 当文件体积大到一次性加载存在风险时，应启用流式读取（streaming）或分块读取（chunked reads）。
• 处理大文件的工作流还需限定读取范围、显式声明数据类型（dtypes）、精确指定工作表，以防意外破坏结构。

常见陷阱

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

相关技能

若用户确认安装，执行：clawhub install

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

反馈

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