| 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 基本原则
- 修改范围以完成目标为准：默认允许为完成任务在必要范围内修改现有工作簿（值、公式、样式、合并、列宽/行高等），但不要引入与任务无关的破坏性改动（如删除明细、改变数据口径、重命名/删除 sheet）。若用户明确要求"除指定位置外其他任何单元格（含格式/公式/其他 sheet）都不能动"，则严格按其约束执行。
- 输出落点按用户诉求：用户要求"直接在原表改/在某 sheet 填写/覆盖原文件"则就地修改；用户要求"保留原表/不要改原 sheet/需要留底"则复制 sheet 或另存新文件，保证原 sheet 不变。
- 公式优先原则：凡是需要计算，优先写 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 数据结构和内容的预先检查
拿到数据文件后，先检查结构再动手处理：
-
运行结构检查脚本了解数据概况（注意 inspect_workbook 只是方便了解数据的预检函数，具体执行任务必须使用 Read 了解文件完整的内容）：
- Excel 文件：
python scripts/inspect_workbook.py <文件路径>
- CSV 文件：用
pd.read_csv(..., nrows=15) 预览，注意编码（优先尝试 utf-8-sig、gbk、gb18030）
-
评估数据规模，决定执行策略：
- 小数据（行数 ≤ 1000，文件 ≤ 5MB）：一次性加载处理
- 大数据（行数 > 1000 或文件 > 5MB）：采用分批策略（分 sheet / 分行批处理 / 流式读取 / 列裁剪）
- 多 sheet 文件：逐个 sheet 单独执行完整的「预检 → 处理 → 输出」流程
-
识别合并单元格：查看预检输出中的 merged_cells 字段，合并单元格的值仅存储在左上角；提取类任务需 ffill 填充；写公式/做合并时只允许在左上角单元格写值/公式，详见 references/ref-xlsx-workflow.md
-
识别"表头不清晰"并做字段理解：若出现无表头/空表头列/多行表头/前几行是标题说明而非表头：
- 用
scripts/preview_excel_rows.py 对可疑 sheet 预览更多行（如前 30 行），结合数据形态判断哪一行才是真正表头
- 对空表头列，观察该列前 20 个非空值的类型与模式（日期/金额/ID/文本类别等），并基于相邻列与用户需求推断临时列名（如
未命名_金额、未命名_日期、未命名_ID）
- 在后续映射与计算中，优先用"列坐标/列字母 + 行号范围"锁定字段来源，避免因表头缺失导致引用错列
-
识别"特殊行/特殊单元格"并特殊处理：若出现"合计/总计/小计/汇总/累计"等与明细口径不同的行：
- 在预检输出的
special_rows 中定位这些行，并结合预览确认其是否为汇总行
- 做聚合/统计/建模前，从明细数据中排除这些汇总行，避免重复统计
2.3 字段语义对齐
在动手处理前，确认用户的指标/概念与数据中的字段如何对应。用户说的"收入"是哪一列？"完成率"怎么算？避免"答非所问"。
2.4 按场景执行
读取场景分派表中对应的 reference 文件，按其中的工作流程执行任务。
2.5 透视表增强判定
在主任务执行完毕后、交付前，判断是否需要叠加透视表/透视图。透视表是增强层，不改变主任务逻辑。 如果预计或者检查发现透视表效果较差可以不生成。
激活条件（满足任一即激活）：
- 显式：用户提到"透视表"、"pivot table"、"用图表汇总展示"、"交叉分析"、"分组对比图"
- 隐式：数据满足 行数 >= 50 + 至少 1 个分类字段 + 1 个数值字段 + 任务涉及分组汇总/对比/占比 ，并且任务不会太复杂导致显示的透视图美观
激活后执行：
- 读取
references/guide-pivot-table.md，按其工作流执行：字段规划 → pandas 计算 → openpyxl 格式化 → 图表生成 → 强制五项验证 → 视觉校验 → Canvas 预览 → 交付
- 强制验证五项：原始数据完整性、透视数据准确性、图表有效性、公式重算零错误（formula_verify.py）、文件可用性
- 任一验证失败且无法快速修复 → 删除透视 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 信息合理性校验（生成/推断信息时必做）
当任务需要"生成信息""补全缺失值""把口述信息整理成表""输出结论/建议""构造示例数据"时，交付前必须进行合理性校验。
重点检查（不止于此）：
- 单位合理：
- 液体优先体积单位（ml/L），非液体优先质量单位（g/kg）；若用户混用，按常识修正并标注。
- 货币、数量、百分比、温度等单位要一致；表头写清单位（如
Revenue (¥)、Weight (g)）。
- 取值范围：
- 时间/时长/数量一般不应为负数；出现负数优先判为输入错误并修正（如取绝对值或置空）并标注原因。
- 百分比一般在
[0, 1] 或 [0%, 100%]；若出现 120% 之类，判断是否是"1.2"或"120"格式混淆并统一。
- 日期时间一致：
- 结束时间不得早于开始时间；若跨天需要显式说明或拆分日期。
三、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 视觉校验图表效果
强制质量要求
添加透视表后必须通过五项验证，任一失败则回退：
- 原始数据完整性：添加透视 Sheet 后原数据 Sheet 行列数不变、抽检值一致
- 透视数据准确性：用 pandas 独立重算聚合值，与透视 Sheet 逐一比对（误差 < 0.01）
- 图表有效性：openpyxl 确认图表有数据系列和标题 + 截图视觉确认非空壳
- 公式重算：
python scripts/formula_verify.py output.xlsx → total_errors == 0
- 文件可用性：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 |
