调研数据可视化报告生成
触发场景
用户给出调研统计表 Excel（.xlsx/.csv），希望直接拿到一个可分享、可离线打开的可视化 HTML 看板，而不是手写脚本或部署服务。
典型表述：
- "这是 XX 调研数据，帮我生成可视化报告"
- "把这份 Excel 做成调研可视化界面"
- "用调研分析平台处理这份数据"
- 直接把 Excel 文件/路径甩过来
不要用于：用户明细表（脚本会拒绝）、含复杂宏或非表格内容的 Excel、JSON/数据库数据。
工作流
- 确认输入：拿到 Excel 路径（用户消息或自动从对话中识别）。
- 自动预处理（脚本内置，不需要手动做 VBA）：如果是腾讯调研原始「交付数据表」（含「封面」「原始数据」sheet，或表头有合并单元格），
build_report.py会先调用scripts/preprocess.py，用 Python 完成平台说明里 VBA 宏ProcessTableHeadersAndSplitMergedCells的同等处理：
- 删除「封面」「原始数据」，只保留「数据统计」sheet
- 拆分第 1 行表头合并单元格并填充原值（如「职业」→ 覆盖 E1:Q1）
- 第 1/2 行表头用-拼成单行（如职业 - 在校学生、整体人群 - 百分比），删除第 2 行
- 拆分 A 列（题目列）合并单元格并把题目填到每一行
- 结果另存为<源名>_预处理.xlsx（同目录，原文件不改动）
已预处理过的单 sheet 表会自动跳过；如需强制跳过加--no-preprocess。也可单独运行preprocess.py <Excel>。 - 运行脚本（一条命令包含预处理 + 生成）：
bash /Users/susanlao/.workbuddy/binaries/python/envs/default/bin/python \ ~/.workbuddy/skills/survey-excel-visualization/scripts/build_report.py \ <Excel路径> -o <输出HTML路径> - 在 WorkBuddy 预览面板打开生成的 HTML（左侧带侧栏的预览界面，不是唤起系统浏览器）：
python present_files(files=["<输出HTML路径>"], cwd="<源Excel所在目录>")
present_files会同时把 HTML 文件作为产物卡片展示，并在内置预览面板里用 iframe 渲染。预览地址形如http://127.0.0.1:xxxxx/static-html/...html，与"截图这个位置"对应。 - 简短告知：列数 / 行数 / 文件大小 / HTML 路径。
> 注意：第 4 步是默认且必须的——用户希望直接在 WorkBuddy 预览面板里看报告（这个面板支持交互、上方有 WorkBuddy 工作区侧栏）。不要用 macOS open 命令唤起系统浏览器，也不要用本地静态服务器（http.server）。
数据格式约定
脚本默认按腾讯调研平台格式解析：
| 列序号 | 含义 | 说明 |
|---|---|---|
| 第 1 列 | 题目 | 同一道题的各选项行该列相同 |
| 第 2 列 | 选项 | 含"总体/合计/汇总"等关键词的行被识别为总人数行，会被自动跳过不作为选项显示 |
| 第 3 列 | 样本量/合计 | 任意内容，仅作为附加列展示 |
| 第 4 列起 | 分组数据 | 各人群/分组的百分比；脚本会自动从第 4 列开始作为"可分析列" |
表头中的「参与人数」会自动替换为「整体」（与原平台一致）。
百分比单元格：脚本会还原 Excel 的百分比格式（0.0% → 18.2%），所以原始 Excel 可以直接用数字 + 百分比格式，无需手动改。
数字单元格：按 Excel 数字格式取位（0 → 整数、0.00 → 两位），加权数据的回答人数（如 803.9999999）会显示为 804，与 Excel 中看到的一致。
命令行参数
python build_report.py <Excel> [-o 输出] [--sheet 名/序号] [--title 浏览器标题] [--cdn] [--list-sheets]
-o / --output：默认输出到 Excel 同目录，命名调研数据可视化_<源名>_<时间戳>.html--sheet：工作表名或序号（默认第一个）--title：浏览器标签页标题（不改页面主标题）--cdn：不内联第三方依赖，改保留 CDN 引用（HTML 体积约 100KB，需联网才能看图）--list-sheets：仅列出工作表后退出--no-preprocess：跳过自动预处理（输入已是处理好的统计表时用）- 输出 HTML 文件名始终沿用原始 Excel 名（不带
_预处理）
输出特性
- 单文件 HTML：所有 JS/CSS/ECharts/SheetJS/Tailwind/FontAwesome/Logo/截图均内联，无外部依赖
- 默认约 3 MB：含数据大小估算 ≈ 2.5 MB 资源 + 数据 JSON
- 双击即开：file:// 协议直接用浏览器打开即可（无需起服务器、无需联网）
- 数据保密：处理全程在本机 Python 进程完成，生成的 HTML 也只在本地保存
- 保留上传能力：生成的 HTML 仍带"上传 Excel"按钮，用户可换文件
- 首次切换到"对比分析"标签会调用本地 JS 生成智能分析摘要（无需外部 LLM）
失败排查
| 现象 | 原因 | 处理 |
|---|---|---|
不支持旧版 .xls 格式 |
老格式未支持 | 在 Excel 中"另存为 .xlsx" |
文件不存在 |
路径错误 | 用绝对路径或确认当前工作目录 |
工作表为空 / 未读取到数据行 |
表格无内容或表头有合并导致读取不到 | 检查 Excel 第一个 sheet 是否是真正的数据表 |
[警告] 缺少本地依赖 ... |
首次运行 vendor 目录缺失 | 让脚本走 CDN 回退，或运行 bash ~/.workbuddy/skills/survey-excel-visualization/scripts/fetch_vendor.sh 补齐 |
| 图表数字全是 0 | 单元格是纯数字而非百分比格式 | 把数字单元格的格式设为百分比（0.0% 或 0.00%），脚本会按 Excel 显示值还原 |
| 打开 HTML 后图标不显示 | FontAwesome solid 字体缺失 | 检查 assets/vendor/fa-solid-900.woff2 是否存在 |
依赖
- Python 3.x（managed venv 已含 openpyxl，无需额外安装）
- 浏览器：Chrome / Safari / Edge / Firefox 任意现代浏览器
- 首次使用建议联网一次：脚本会从
assets/vendor加载本地依赖（已预下载）；若缺失则自动回退到 CDN
文件结构
survey-excel-visualization/
├── SKILL.md
├── scripts/
│ ├── build_report.py # Excel → HTML（主入口，自动调用预处理）
│ ├── preprocess.py # 交付数据表预处理（等价 VBA 宏）
│ └── fetch_vendor.sh # 补齐 vendor 依赖（可选，会自动转 b64）
└── assets/
├── app/ # 前端源码副本（含预加载补丁、相对路径）
└── vendor/ # 离线运行所需的所有依赖（约 3.0MB，全为文本）
提交 SkillHub / 打包分享
SkillHub 会校验文件类型，拒收 .woff2、.png 等二进制文件（报错形如
不允许的文件类型: assets/vendor/fa-solid-900.woff2）。因此本 skill 的
assets/vendor/ 里全部是纯文本，二进制资源一律以 base64 文本保存：
| 用途 | 文件 | 说明 |
|---|---|---|
| FontAwesome 图标字体 | fa-solid-900.b64.txt |
由 fa-solid-900.woff2 转来 |
| 页面 Logo | logo.b64.txt |
由 logo.png 转来 |
| 操作示意图 | guide.b64.txt |
由 guide.png 转来 |
| SheetJS | xlsx.full.min.js.b64.txt |
压缩 JS 超长行会被识别为 data，一并转文本 |
build_report.py 会自动读取这些 .b64.txt 并解码内联到 HTML；同时保留读取
旧版原始二进制文件的兼容回退。若运行过 fetch_vendor.sh 重新下载依赖，
脚本会自动把上述 4 类资源转成 b64 文本并删除原文件。
自查命令（应无输出）：
cd ~/.workbuddy/skills/survey-excel-visualization && \
find . -type f -print0 | xargs -0 file | grep -viE "text|json|empty|script"
注意事项
- 原平台要求用户手动删 sheet + 在 Excel 里粘贴运行 VBA；本 skill 已用
preprocess.py自动完成，不要再让用户手动打开 VBA 编辑器（Mac 版 Excel 无法被脚本驱动运行宏，Python 等价实现更稳）。 - 预处理后表头第 1、2 列会带「生成时间：xxx - 问题内容/问题选项」前缀，这是原 VBA 的同样行为，不影响解析（脚本按列位置取题目/选项）。
- 不要把生成的 HTML 上传到公网——HTML 中已内联原始数据。
- 与腾讯调研分析平台部署版的区别：此 skill 输出的是离线单文件，没有多用户、状态管理、远程存储等能力；可视化引擎和功能 1:1 保持一致。
