# Build AI Report

> 只读分析本地 Excel 工作簿，完成数据剖析、清洗口径、结论提炼、图表选型、离线 HTML 报表生成和双端验收。用户要求理解或分析 .xlsx/.xlsm 数据、把 Excel 变成可视化报告、更新 Epoch AI 演示报表、选择合适图表或核对报表数据时使用。

- Skill: `fufankeji/build-ai-report` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add fufankeji/build-ai-report`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fufankeji/build-ai-report/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: fufankeji (https://skillmd.com/u/fufankeji)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fufankeji/build-ai-report

---


# 构建 AI 数据叙事报告

把 Excel 转换成读者能快速理解的离线交互报告。目标不是复刻表格，而是从数据问题出发，形成“可信口径 → 明确结论 → 合适图表 → 可核验成果”的闭环。

## 硬边界

- 只读打开源工作簿；不得覆盖、另存、重算或重新格式化源文件。
- 生成前后记录源文件的 SHA-256、大小和修改时间，确认源文件没有变化。
- 不编造缺失值、分类、单位、时间、来源或业务含义；推断必须明确标记。
- 不把公式文本当作结果。公式缓存为空、过期或无法验证时，报告限制并停止使用该指标。
- HTML 只嵌入绘图所需的聚合数据，不嵌入完整明细，不提供原始数据下载入口。
- 不直接修改 `output/` 中的生成文件；数据逻辑改 `scripts/build_report.py`，页面改 `source/report-template.html`。
- 不复制 PolyForm Noncommercial 项目的模板、SVG 函数、图型结构、设计 Token 或源码。

## 先判断任务类型

- **复现当前案例**：输入文件和分析问题没有变化时，核对项目约定后直接走确定性构建与验收。
- **更新当前案例**：数据发生变化但字段语义相同，重新剖析数据、核对口径，再更新聚合逻辑和结论。
- **适配新工作簿**：工作表、字段或业务问题改变时，必须完整执行下面第 1～6 阶段，不得套用当前六张图。

只有当工作表或指标口径存在两种实质不同、且无法从内容判断的解释时，向用户提一个简短问题；其他小歧义采用保守、可说明的默认值继续。

## 新工作簿的项目目录

当用户提供的不是当前 Epoch AI 案例工作簿时，必须从零建立：

```text
generated/<工作簿语义名>/
├── scripts/build_report.py
├── source/report-template.html
├── output/index.html
├── output/解析汇总.json
├── output/预览-桌面.png
└── output/预览-移动端.png
```

- 不读取或复制案例根目录的 `input/Epoch_AI显著模型数据.xlsx`、`output/`、`scripts/build_report.py` 或 `source/report-template.html` 作为本次成果。
- 先用 DSH 文件工具写入本次专属的剖析、构建和验收文件，再用 Shell 工具真实运行。
- 可以复用本机已经安装的 `openpyxl`、Apache ECharts 和 Playwright 运行时，但数据字段、聚合逻辑、图表组合、标题和页面结构必须由本次工作簿决定。
- 输出 HTML 必须是新的、离线可打开的单文件，不要求用户先准备代码骨架。

## 阶段 1：锁定输入和只读基线

1. 更新或复现当前案例时，使用 `read` 查看既有 `package.json`、`scripts/build_report.py` 和输入约定；适配新工作簿时，先读取用户指定的 Excel 路径，并新建上面的 `generated/<工作簿名>/`，不要寻找案例脚本。
2. 将输入解析为规范化路径，确认文件存在、可读，扩展名为 `.xlsx` 或 `.xlsm`。
3. 记录文件大小、修改时间和 SHA-256；不要通过复制工作簿建立所谓“保护副本”。
4. 使用只读模式打开工作簿。`.xlsm` 如需保留宏，仅分析数据，不写回文件。

## 阶段 2：剖析工作簿

当输入、字段或分析问题发生变化时，必须完整读取 [Excel 数据分析规则](references/excel-analysis.md)，再执行剖析。

至少确认：

- 工作表名称、可见性、有效区域、候选表头、数据行列数；
- 合并单元格、空白行列、重复表头、筛选区域、Excel Table 和命名区域；
- 每列的推断类型、非空数、缺失率、唯一值数、最小/最大值、时间范围和单位线索；
- 公式单元格、公式缓存、日期序列、百分比、货币和千分位显示格式；
- 可能的 ID、维度、度量、时间、层级、分类和备注字段。

不要默认第一行是表头，也不要默认最大工作表就是目标数据。结合连续数据区域、列名、类型一致性和用户问题选择。

## 阶段 3：建立分析口径

先写清楚问题，再计算数据。对每个结论记录以下五项：

| 项目 | 必须说明 |
| --- | --- |
| 问题 | 这张图具体回答什么，而不是“展示一下数据” |
| 字段 | 使用哪些维度、度量、时间和 ID |
| 筛选 | 纳入和排除哪些记录，是否排除合计行、缺失值或未完整周期 |
| 计算 | 聚合函数、分母、去重键、单位换算、Top N 与 Other 规则 |
| 校验 | 能回算到工作簿的总数、占比或边界是什么 |

处理原则：

- 区分“缺失”“零”“不适用”和“未知”，不得互相替换。
- 去重必须先确定业务主键；没有可靠主键时不自动删重。
- 识别“合计/小计/总计”行，避免重复聚合。
- 百分比必须保存分子、分母和舍入规则；多分类占比应核对加总。
- 2026 年这类未完整周期必须在标题或副标题中明确，不与完整年度直接下结论。
- 默认提炼 1～6 个互不重复的结论；每张图只回答一个主要问题。

## 阶段 4：选择图表和叙事顺序

开始写页面前，必须完整读取 [图表选型规则](references/chart-selection.md)。不要按“哪个图好看”选择，而要按“分析问题 + 数据形状 + 阅读任务”选择。

每张图至少记录两个合法候选，并写一句淘汰理由。最终记录：

- 结论式标题；
- 数据形状和最终图表；
- 编码关系，例如长度、位置、面积或颜色分别代表什么；
- 口径、单位、时间范围和来源；
- 一个可回算的验收值。

多图报告按“总览 → 变化 → 构成/排名 → 关系/原因 → 结论”组织。相邻图不能重复回答同一问题，也不要连续堆叠轮廓相似的图。

## 阶段 5：生成离线报告

当前 Epoch AI 案例使用 `npm run build`。适配新工作簿时，不要求根目录已有该命令；应在本次 `generated/<工作簿名>/scripts/` 编写并执行专属构建脚本：

```bash
python3 generated/<工作簿名>/scripts/build_report.py \
  --input <用户工作簿绝对路径> \
  --output generated/<工作簿名>/output/index.html
```

构建必须做到：

- 使用 `openpyxl` 只读解析 Excel，并执行显式聚合；
- 校验工作簿 SHA-256、记录数、字段数和关键分类加总；
- 只向 HTML 写入聚合数据；
- 使用 Apache ECharts `6.1.0` 渲染，并将运行时内联；
- 使用一套统一的颜色体系，颜色承担稳定语义；
- 标题先表达结论，副标题再说明口径，来源行标明数据来源；
- 支持响应式布局、键盘可达文本和 `prefers-reduced-motion` 降级；
- 最终成果无需服务器和 CDN，双击即可打开。

当前案例的六个分析问题是年度趋势、领域构成、机构排名、开放方式迁移、国家×领域关系、参数量×训练算力关系。它们是本数据集的选择，不是所有 Excel 的固定模板。

## 阶段 6：数据对账和浏览器验收

先对账，再评价视觉。至少检查：

1. 页面总数、均值、占比、排名、Top N、时间范围和标注值能回算到源 Excel。
2. 百分比分母和舍入正确；面积编码使用面积而非半径表达数值；对数轴有明确标记。
3. HTML 不含远程脚本、在线字体、完整原始表或数据下载链接。
4. JavaScript 通过语法检查，页面没有控制台错误和远程资源请求。
5. 约 1440px 桌面端和约 390px 移动端均无横向溢出、裁切、标签碰撞或过度留白。
6. 交互控件真实改变图表，而不是只切换按钮状态。
7. 再次核对源工作簿 SHA-256、大小和修改时间未改变。

当前 Epoch AI 案例执行 `npm run verify:browser`。适配新工作簿时，应为本次 `generated/<工作簿名>/` 编写等价的 Playwright 验收脚本，或直接用 DSH Shell 调用本机浏览器完成相同检查：

```bash
node generated/<工作簿名>/scripts/visual-qa.cjs
```

发现问题就修复数据脚本或页面模板，并重复相应检查。不能把未运行的项目写成通过。

## 失败时如何处理

- 找不到工作表或字段：停止构建，列出实际发现的工作表/列和预期项。
- 哈希或行列基线变化：先重新剖析并解释变化，不得删除校验绕过失败。
- 公式无缓存：不使用该指标，说明需要由 Excel 或兼容计算引擎重算。
- 分类加总不一致：定位缺失类、重复类、筛选条件和分母，不要用“其他”强行抹平。
- 浏览器验收失败：保留真实错误，修复后重跑；缺少浏览器时明确写“未验证”。

## 最终回复

用中文简洁报告：

- 输入工作表/区域、有效记录数和排除记录数；
- 采用的分析问题、核心结论和图表类型；
- 构建后的 HTML 与预览图路径；
- 数据对账、离线打开、桌面端、移动端、交互和源文件未修改是否通过；
- 任何未验证项、公式限制或数据口径风险。

不要只回复“已完成”，也不要把脚本存在当作脚本已经运行。