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 案例工作簿时，必须从零建立：

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：建立分析口径

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

处理原则：

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

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

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

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

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

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

阶段 5：生成离线报告

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

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 调用本机浏览器完成相同检查：

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

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

失败时如何处理

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

最终回复

用中文简洁报告：

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

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