version: "1.0.1" name: xlsx description: "当电子表格是主要输入或交付物时必须使用本技能。适用于打开、读取、清洗、修复、编辑或创建 .xlsx、.xlsm、.xltx、.csv、.tsv，包括中文销售台账、预算表、排期表、数据清洗、补公式、格式化、图表和模板更新。用户只说“下载目录里那个表”“把脏 CSV 整成 Excel”也应触发。若主要产物是 Word、HTML、独立 Python 脚本、数据库流水线或 Google Sheets API，则不要触发。" license: Proprietary. LICENSE.txt has complete terms

XLSX 创建、编辑与分析

openpyxl、pandas、markitdown 通常已预装。先直接使用，只有导入失败时才安装。脚本路径均相对于本 Skill 目录。

中文场景 few-shot

输入：“下载目录里的销售台账.xlsx 帮我补毛利率、按区域汇总，再做一张趋势图。”

执行：先识别原表字段、输入单元格和既有样式；用公式生成毛利率，用汇总表和原生图表呈现趋势；回算后检查公式错误和关键数字。

输入：“把这份错位的 CSV 整成下周继续填报的运营模板。”

执行：用 pandas 纠正表头和脏行，输出中文列名清晰的 .xlsx；添加“可编辑区域”说明和一行真实格式示例，但不在已有业务表中擅自插入示例数据。

每个交付物都要满足

• 用户或既有模板的字段名、sheet 名、格式和公式约定优先。
• 新建中文表格时选用目标环境可用的专业中文字体；已有表格必须继承原字体。
• 公式必须写入 Excel，不把 Python 计算结果硬编码成静态值。
• 所有假设和硬编码数字应在可见位置说明来源；用户提供的数据明确标注“来源：用户提供”。
• 用户要继续填写的空模板需要短图例和一行格式示例；编辑已有文件时不要擅自添加。
• 交付前 recalc.py 必须达到零公式错误。

通用工作流

1. 快速浏览所有 sheet、表头、合并单元格、公式和输入样式。
2. 明确哪些是输入、公式、跨表引用和外部链接。
3. 先写 2–3 个代表性公式并核对引用，再批量填充。
4. 保存后执行回算。
5. 检查公式正确性、格式、图表范围和中文显示。

公式回算

openpyxl 只写公式字符串，不产生缓存值。含公式文件必须运行：

python scripts/recalc.py output.xlsx

脚本会原地改写工作簿，并输出 JSON：

• status: success：公式已回算且没有已识别错误。
• status: errors_found：进程仍可能退出 0，必须读取 total_errors 和 error_summary。
• 出现 error 字段而不是 status：没有完成回算。

绿色回算只证明公式能求值，不证明业务引用正确。抽查至少 2–3 个关键公式的行列和边界。

公式兼容性

优先使用 SUMIFS、INDEX、MATCH、IFERROR、SUMPRODUCT 等兼容函数。

以下函数需要 _xlfn. 前缀：TEXTJOIN、CONCAT、IFS、SWITCH、MAXIFS、MINIFS。

不要使用当前校验链无法可靠回算的动态数组函数：

• XLOOKUP
• XMATCH
• SORT
• FILTER
• UNIQUE
• SEQUENCE

查找使用 INDEX/MATCH，排序、筛选和去重在 Python 中完成后再写入单元格。

openpyxl 高风险点

• 同时拿公式和值需要加载两次；一次加载无法兼得。
• data_only=True 的工作簿不能保存，否则公式会被静态值替换。
• 刚由 openpyxl 写出的公式，用 data_only=True 读取通常是 None；先回算。
• 合并单元格只能写左上角锚点。
• .xlsm 必须使用 keep_vba=True，否则宏会丢失。
• 含空格的 sheet 名在公式中必须加单引号，如 ='参数 输入'!$B$5。
• 修改现有文件时先识别其输入颜色/填充，只写指定区域，不覆盖原公式。

外部链接

公式如 ='[1]Returns Analysis'!$B$2 指向外部文件。openpyxl 保存后可能丢失原缓存值，LibreOffice 无法解析时会写入 #NAME? 并删除链接。

遇到外部链接时：

1. 在修改前读取并保存原缓存值。
2. 不要直接覆盖原文件。
3. 明确说明外部依赖是否可用。
4. 只有用户接受链接丢失风险时才使用 recalc.py --force。

财务模型默认约定

既有模板或用户要求优先；否则：

• 蓝字：硬编码输入和情景变量。
• 黑字：公式。
• 绿字：同工作簿跨表引用。
• 红字：外部文件引用。
• 黄底：关键假设或待填写单元格。
• 百分比存为小数，0.15 显示为 15.0%。
• 负数用括号，零显示为 -，倍数显示 0.0x。
• 每个假设放在独立单元格并由公式引用，不把 1.05 写死在公式里。

最终验收

python scripts/recalc.py output.xlsx

随后检查：

• total_errors == 0
• 关键公式引用正确
• sheet 名、列名、日期和数值格式符合用户要求
• 图表数据范围和图例正确
• 中文字符、列宽、冻结窗格、筛选和打印区域可用

依赖

openpyxl · pandas · markitdown · LibreOffice