office-excel

name	office-excel
description	Excel/CSV 数据全场景处理技能，覆盖数据分析洞察、文本语义分类、数值计算、量化建模（预测/评价/优化）、数据挖掘、表格创建与格式整理，并支持数据透视表/透视图增强展示。只要任务涉及结构化数据的处理、分析或输出，就应使用本技能——无论用户是否上传了文件。用户上传 Excel/CSV 要求处理时使用；用户口述数据要求整理成表时使用；用户要求计算、统计、建模、预测、分类、挖掘、可视化时使用；用户要求创建或编辑 Excel 时使用；用户要求透视表、交叉分析、分组汇总图表时使用。本技能不负责获取外部信息，如需补充数据须先通过其他途径获得。

Excel 数据全场景处理技能

一、场景识别与分派

收到请求后，先识别场景，再读取对应 reference 文件，按其指导执行任务。

场景分派表

场景	典型信号词 / 意图	读取的 reference
数据洞察	"分析一下"、"帮我看看"、"有什么发现"、"给出洞察"、"解读数据"、"业务诊断"、"趋势如何"、"表现怎样"	references/guide-data-insights.md
文本语义处理	"提炼要点"、"归类"、"贴标签"、"标准化文本"、"语义抽取"、"分类观点"、"汇总文字"	references/guide-semantic-analysis.md
数值计算处理	"计算"、"统计"、"求和"、"公式"、"加工数据"、"处理格式"、"汇总数值"、"时间计算"、"合并表格"、"拆分数据"、"去重"、"格式转换"	references/guide-data-processing.md
量化建模	"建模"、"预测"、"评价模型"、"排名打分"、"优化分配"、"回归"、"AHP"、"TOPSIS"	references/guide-data-modeling.md
数据挖掘	"挖掘"、"发现模式"、"关联分析"、"聚类"、"找规律"、"相关性分析"、"特征提取"	references/guide-data-digging.md
表格创建与整理	"做个表"、"整理成Excel"、"生成表格"、"创建报表"、"做个模板"、"整理一下格式"	references/ref-xlsx-workflow.md（含行高/列宽/截断默认规则）

场景边界说明

• 洞察 vs 建模：洞察侧重业务结论（"现状是什么、为什么、建议什么"），建模侧重构建量化模型（预测/评价/优化目标函数）
• 洞察 vs 挖掘：洞察以业务问题为导向，挖掘以算法方法论为核心（聚类、关联规则等）
• 计算 vs 建模：计算是明确公式的数值处理，建模是构建预测/评价/优化模型
• 文本语义 vs 洞察：文本语义处理针对非结构化文字列（抽取、归类、标签），洞察针对已有结构化指标的分析
• 表格创建 vs 其他场景：当用户没有现成数据文件、需要从零创建 Excel（如做模板、整理信息成表格）时走此场景；若创建后还需分析/建模，则创建完成后再按对应场景继续

多场景叠加：若任务横跨多个场景，按主诉求选主场景，次要场景的相关说明也可参考对应 reference 文件。

---

二、通用执行流程

以下流程适用于所有场景。具体的分析方法、建模步骤等由各 reference 文件指导。

2.0 基本原则

1. 修改范围以完成目标为准：默认允许为完成任务在必要范围内修改现有工作簿（值、公式、样式、合并、列宽/行高等），但不要引入与任务无关的破坏性改动（如删除明细、改变数据口径、重命名/删除 sheet）。若用户明确要求"除指定位置外其他任何单元格（含格式/公式/其他 sheet）都不能动"，则严格按其约束执行。
2. 输出落点按用户诉求：用户要求"直接在原表改/在某 sheet 填写/覆盖原文件"则就地修改；用户要求"保留原表/不要改原 sheet/需要留底"则复制 sheet 或另存新文件，保证原 sheet 不变。
3. 公式优先原则：凡是需要计算，优先写 Excel 公式到最终交付给用户的表格对应单元格（原 sheet 或用户要求的输出 sheet）。

关于公式 vs 硬编码：可以用 Excel 公式表达的计算，一律使用公式写入单元格，保持表格的动态计算能力。

公式写入示例：

ws['C2'] = '=A2+B2'
ws['D2'] = '=C2/B2*100'
ws['E2'] = '=SUM(A2:A100)'

不应在 Python 中预先计算好数值再写入（这样会丧失公式的动态性）：

# 避免这种做法
result = value_a + value_b
ws['C2'] = result

例外情况——以下场景允许直接写入静态值：

• 从外部来源抓取的数据
• 永不变化的常量
• 使用公式会产生循环引用

2.1 判断数据来源

情况	处理方式
用户上传了 Excel/CSV 文件	直接进入 2.2
用户口述/粘贴了数据但没有文件	先将信息结构化为 DataFrame，直接按需求创建 Excel；表格排版（含行高/列宽/截断）按 references/ref-xlsx-workflow.md 执行。针对生成的 Excel 如有进一步数据洞察等需求，可进入 2.2 继续
信息不足以完成任务	向用户询问补充，或先调度其他 skill/工具获取数据后再继续

2.2 数据结构和内容的预先检查

拿到数据文件后，先检查结构再动手处理：

1. 运行结构检查脚本了解数据概况（注意 inspect_workbook 只是方便了解数据的预检函数，具体执行任务必须使用 Read 了解文件完整的内容）：

   • Excel 文件：python scripts/inspect_workbook.py <文件路径>
   • CSV 文件：用 pd.read_csv(..., nrows=15) 预览，注意编码（优先尝试 utf-8-sig、gbk、gb18030）

2. 评估数据规模，决定执行策略：

   • 小数据（行数 ≤ 1000，文件 ≤ 5MB）：一次性加载处理
   • 大数据（行数 > 1000 或文件 > 5MB）：采用分批策略（分 sheet / 分行批处理 / 流式读取 / 列裁剪）
   • 多 sheet 文件：逐个 sheet 单独执行完整的「预检 → 处理 → 输出」流程

3. 识别合并单元格：查看预检输出中的 merged_cells 字段，合并单元格的值仅存储在左上角；提取类任务需 ffill 填充；写公式/做合并时只允许在左上角单元格写值/公式，详见 references/ref-xlsx-workflow.md

4. 识别"表头不清晰"并做字段理解：若出现无表头/空表头列/多行表头/前几行是标题说明而非表头：

   • 用 scripts/preview_excel_rows.py 对可疑 sheet 预览更多行（如前 30 行），结合数据形态判断哪一行才是真正表头
   • 对空表头列，观察该列前 20 个非空值的类型与模式（日期/金额/ID/文本类别等），并基于相邻列与用户需求推断临时列名（如 未命名_金额、未命名_日期、未命名_ID）
   • 在后续映射与计算中，优先用"列坐标/列字母 + 行号范围"锁定字段来源，避免因表头缺失导致引用错列

5. 识别"特殊行/特殊单元格"并特殊处理：若出现"合计/总计/小计/汇总/累计"等与明细口径不同的行：

   • 在预检输出的 special_rows 中定位这些行，并结合预览确认其是否为汇总行
   • 做聚合/统计/建模前，从明细数据中排除这些汇总行，避免重复统计

2.3 字段语义对齐

在动手处理前，确认用户的指标/概念与数据中的字段如何对应。用户说的"收入"是哪一列？"完成率"怎么算？避免"答非所问"。

2.4 按场景执行

读取场景分派表中对应的 reference 文件，按其中的工作流程执行任务。

2.5 透视表增强判定

在主任务执行完毕后、交付前，判断是否需要叠加透视表/透视图。透视表是增强层，不改变主任务逻辑。 如果预计或者检查发现透视表效果较差可以不生成。

激活条件（满足任一即激活）：

1. 显式：用户提到"透视表"、"pivot table"、"用图表汇总展示"、"交叉分析"、"分组对比图"
2. 隐式：数据满足 行数 >= 50 + 至少 1 个分类字段 + 1 个数值字段 + 任务涉及分组汇总/对比/占比 ，并且任务不会太复杂导致显示的透视图美观

激活后执行：

1. 读取 references/guide-pivot-table.md，按其工作流执行：字段规划 → pandas 计算 → openpyxl 格式化 → 图表生成 → 强制五项验证 → 视觉校验 → Canvas 预览 → 交付
2. 强制验证五项：原始数据完整性、透视数据准确性、图表有效性、公式重算零错误（formula_verify.py）、文件可用性
3. 任一验证失败且无法快速修复 → 删除透视 Sheet，回退到无透视版本交付，用 Canvas 展示透视数据作为替代

工具链：Bash（运行 Python 脚本）→ open_url_in_browser + take_screenshot（视觉校验）→ CanvasCreateFile（webview 上屏预览）→ NotifyHuman（文件交付）

2.6 交付

• 改动策略匹配诉求：默认可在必要范围内修改以完成任务；若用户要求"只改指定位置/保留原表/不改原 sheet"，则严格遵守并通过新建 sheet/复制 sheet/另存等方式实现
• 保留诉求优先：用户要求保留原表时再保留（复制 sheet 或另存）；未要求保留时允许直接在原表填写
• 公式在交付表：计算结果用 Excel 公式写在最终交付的表格位置，不在临时表/中间 sheet 计算后回填数值
• 结论优先于过程：最终交付物聚焦用户需要的结论和建议，过滤中间过程
• 格式专业：图表须有中文标题/坐标轴/图例；新建表格的行高/列宽须按下方"列宽行高自适应规范"执行；其余格式细节见 references/ref-xlsx-workflow.md 和下方质量规范
• 不主动做外部搜索补全：除非用户要求不得自行搜索扩充数据，信息不足时先向用户确认

2.7 信息合理性校验（生成/推断信息时必做）

当任务需要"生成信息""补全缺失值""把口述信息整理成表""输出结论/建议""构造示例数据"时，交付前必须进行合理性校验。

重点检查（不止于此）：

1. 单位合理：
   • 液体优先体积单位（ml/L），非液体优先质量单位（g/kg）；若用户混用，按常识修正并标注。
   • 货币、数量、百分比、温度等单位要一致；表头写清单位（如 Revenue (¥)、Weight (g)）。
2. 取值范围：
   • 时间/时长/数量一般不应为负数；出现负数优先判为输入错误并修正（如取绝对值或置空）并标注原因。
   • 百分比一般在 [0, 1] 或 [0%, 100%]；若出现 120% 之类，判断是否是"1.2"或"120"格式混淆并统一。
3. 日期时间一致：
   • 结束时间不得早于开始时间；若跨天需要显式说明或拆分日期。

---

三、Excel 输出质量规范

所有输出 Excel 文件必须满足以下标准（含格式、行高/列宽/截断、公式重算与验证）。详细技术工作流参见 references/ref-xlsx-workflow.md。

基础规范

项目	要求
字体	全文使用统一专业字体（如 Arial、宋体），不同区域字体一致
公式错误	交付前必须零公式错误（#REF! #DIV/0! #VALUE! #N/A #NAME?），使用 scripts/formula_verify.py 验证
现有模板	修改已有文件时，精确匹配其格式、样式和规范；现有模板约定优先于本规范
公式 vs 硬编码	计算结果必须写成 Excel 公式（如 =SUM(B2:B9)），不得在 Python 中算好再硬编码写入单元格

列宽行高自适应规范

生成或修改 Excel 表格时，列宽和行高必须根据内容自适应，确保表格不拥挤、不浪费空间。

列宽：扫描该列所有单元格，取最长内容的显示宽度（中文字符按 2 宽度）+ padding 3 字符。下限 8、上限 40。超过上限的列启用 wrap_text=True 自动换行。

行高：表头行 30、普通数据行 20、汇总行 26、含换行单元格的行 36。

内边距：通过列宽 padding（+3）和行标签列 Alignment(indent=1) 提供呼吸空间。

详细实现函数（auto_fit_columns、set_row_heights）见 references/guide-pivot-table.md 通用格式规则章节，所有新建 Sheet 和表格区域均应调用。修改用户现有模板时保持原有行高列宽不变（除非用户要求调整）。

财务模型专用规范

颜色编码（行业标准，用户未另行指定时遵循）：

颜色	含义
蓝色文字 RGB(0,0,255)	硬编码输入值、用户场景调整项
黑色文字 RGB(0,0,0)	所有公式与计算结果
绿色文字 RGB(0,128,0)	跨 sheet 引用（同一工作簿内）
红色文字 RGB(255,0,0)	跨文件外部链接
黄色底色 RGB(255,255,0)	需要关注的关键假设或待填写项

数字格式：

类型	格式
年份	文本字符串，如 "2024"，不用数字格式
货币	$#,##0，表头注明单位（如 Revenue ($mm)）
零值	显示为 -，格式 $#,##0;($#,##0);-
百分比	0.0%（保留一位小数）
倍数	0.0x（如 EV/EBITDA、P/E）
负数	括号表示 (123)，不用负号 -123

公式规范：

• 所有假设（增长率、利润率、倍数等）放在独立假设单元格，公式引用单元格而非直接写数字
  • 正确：=B5*(1+$B$6)，错误：=B5*1.05
• 硬编码数值必须在旁边注明来源，格式：Source: [来源], [日期], [具体引用]

---

四、数据透视表增强模块

透视表是附加增强能力，在主任务完成后叠加，不改变原有任务逻辑。

能力概述

• 使用 pandas.pivot_table() 计算多维汇总数据
• 使用 openpyxl 将结果写入新 Sheet 并应用专业格式（Monochrome / Finance 两套风格）
• 使用 openpyxl.chart 生成配套图表（柱形/折线/饼图，根据数据特征自动选型）
• 通过 CanvasCreateFile (webview) 上屏展示透视表预览，让用户无需下载即可确认
• 通过 open_url_in_browser + take_screenshot 视觉校验图表效果

强制质量要求

添加透视表后必须通过五项验证，任一失败则回退：

1. 原始数据完整性：添加透视 Sheet 后原数据 Sheet 行列数不变、抽检值一致
2. 透视数据准确性：用 pandas 独立重算聚合值，与透视 Sheet 逐一比对（误差 < 0.01）
3. 图表有效性：openpyxl 确认图表有数据系列和标题 + 截图视觉确认非空壳
4. 公式重算：python scripts/formula_verify.py output.xlsx → total_errors == 0
5. 文件可用性：openpyxl 重新加载确认无异常，透视表 Sheet 存在

详细实现指引：references/guide-pivot-table.md

工具链

步骤	工具	用途
预览数据	Read / Bash (inspect_workbook.py)	快速了解数据结构和适合度
计算+格式化+图表	Bash (Python 脚本)	pandas 聚合 → openpyxl 写入 → 图表生成
公式验证	Bash (formula_verify.py)	确认零公式错误
视觉校验	open_url_in_browser + take_screenshot	LibreOffice 打开截图确认图表效果
预览上屏	CanvasCreateFile (webview)	HTML 表格 + 图表截图直接展示给用户
文件交付	NotifyHuman	推送最终 Excel 文件
截图上传	FileBatchUpload	将截图上传为公开 URL 嵌入 Canvas