技能介绍

要解决的问题

写 Python 生成 Excel 时，常见的坑是：算完数再把结果写进单元格，表格看起来正常，一旦原始数据变动，所有汇总全都对不上。另一个问题是编码——在中文 Windows 上打开没带 BOM 的 CSV，中文直接变乱码。再加上财务模型该有的配色约定、数字格式、硬编码来源说明，手工拼 openpyxl 很容易漏掉其中一两项。

核心能力

公式优先：所有合计、比率、差异都用 Excel 公式表达，Python 只负责写入公式，不做离线计算；假设参数单独放在假设单元格里，公式通过引用取值，而不是写死常数。
重算与校验：openpyxl 写入的公式只是字符串，没有计算结果。scripts/recalc.py 会调用 LibreOffice 完成重算，扫描所有单元格，返回 JSON 格式的错误清单，标出 #REF!、#DIV/0!、#VALUE!、#NAME? 的具体位置，改完再跑一遍直到状态干净。
财务模型约定：蓝色表示硬编码输入，黑色表示公式，绿色表示跨表链接，红色表示外部文件链接，黄色底纹标注需要关注的假设；年份按文本存储，货币统一 $#,##0 并把单位写进表头，百分比默认 0.0%，倍数用 0.0x，负数用括号，零显示为 -。
编码策略：写给 Excel 看的 CSV 一律用 utf-8-sig，读不确定来源的 CSV 先用 chardet 探测，失败则回落到 utf-8。
工具分工：pandas 负责数据分析与批量处理，openpyxl 负责公式与格式；data_only=True 只用于读值，不能用来保存。

适用边界

平台差异：utf-8-sig 在 macOS Numbers 的旧版本里会在第一个单元格显示 ï»¿ 前缀；如果输出目标是 Numbers，改用不带 BOM 的 utf-8 并提示用户手动指定编码。面向 cat、awk、grep 这类命令行工具时也应去掉 BOM，否则首列匹配会被三个字节破坏。
行号错位：pandas 的 DataFrame 行号从 0 开始，Excel 行号从 1 开始，第 5 行数据对应第 6 行；列映射也要核对，第 64 列是 BL 而不是 BK。
写入限制：用 data_only=True 打开的文件一旦保存，公式会被永久替换成静态值，不可逆。
模板优先级：已有模板的格式约定高于本技能的默认规范，改之前先读透原有结构。

适用边界与注意点

该技能主要面向 Excel 模型的自动化生成与维护，不适合需要复杂宏或自定义 VBA 的场景，也不保证在 Excel 以外的所有电子表格工具中表现一致。使用时应遵循上述编码、公式和格式约定，并根据实际目标平台调整策略；同时注意，修改已有模板时应保留其既有格式约定，且任何外部链接、跨表引用和硬编码假设都需显式标注来源，以降低数据漂移风险。