| name | build-ai-report |
| description | 只读分析本地 Excel 工作簿，完成数据剖析、清洗口径、结论提炼、图表选型、离线 HTML 报表生成和双端验收。用户要求理解或分析 .xlsx/.xlsm 数据、把 Excel 变成可视化报告、更新 Epoch AI 演示报表、选择合适图表或核对报表数据时使用。 |
构建 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：锁定输入和只读基线
- 更新或复现当前案例时，使用
read 查看既有 package.json、scripts/build_report.py 和输入约定；适配新工作簿时，先读取用户指定的 Excel 路径，并新建上面的 generated/<工作簿名>/，不要寻找案例脚本。
- 将输入解析为规范化路径，确认文件存在、可读，扩展名为
.xlsx 或 .xlsm。
- 记录文件大小、修改时间和 SHA-256；不要通过复制工作簿建立所谓“保护副本”。
- 使用只读模式打开工作簿。
.xlsm 如需保留宏，仅分析数据，不写回文件。
阶段 2：剖析工作簿
当输入、字段或分析问题发生变化时，必须完整读取 Excel 数据分析规则，再执行剖析。
至少确认：
- 工作表名称、可见性、有效区域、候选表头、数据行列数；
- 合并单元格、空白行列、重复表头、筛选区域、Excel Table 和命名区域；
- 每列的推断类型、非空数、缺失率、唯一值数、最小/最大值、时间范围和单位线索；
- 公式单元格、公式缓存、日期序列、百分比、货币和千分位显示格式；
- 可能的 ID、维度、度量、时间、层级、分类和备注字段。
不要默认第一行是表头，也不要默认最大工作表就是目标数据。结合连续数据区域、列名、类型一致性和用户问题选择。
阶段 3：建立分析口径
先写清楚问题，再计算数据。对每个结论记录以下五项：
| 项目 | 必须说明 |
|---|
| 问题 | 这张图具体回答什么，而不是“展示一下数据” |
| 字段 | 使用哪些维度、度量、时间和 ID |
| 筛选 | 纳入和排除哪些记录，是否排除合计行、缺失值或未完整周期 |
| 计算 | 聚合函数、分母、去重键、单位换算、Top N 与 Other 规则 |
| 校验 | 能回算到工作簿的总数、占比或边界是什么 |
处理原则：
- 区分“缺失”“零”“不适用”和“未知”，不得互相替换。
- 去重必须先确定业务主键；没有可靠主键时不自动删重。
- 识别“合计/小计/总计”行，避免重复聚合。
- 百分比必须保存分子、分母和舍入规则；多分类占比应核对加总。
- 2026 年这类未完整周期必须在标题或副标题中明确，不与完整年度直接下结论。
- 默认提炼 1～6 个互不重复的结论；每张图只回答一个主要问题。
阶段 4：选择图表和叙事顺序
开始写页面前，必须完整读取 图表选型规则。不要按“哪个图好看”选择，而要按“分析问题 + 数据形状 + 阅读任务”选择。
每张图至少记录两个合法候选，并写一句淘汰理由。最终记录：
- 结论式标题；
- 数据形状和最终图表；
- 编码关系，例如长度、位置、面积或颜色分别代表什么；
- 口径、单位、时间范围和来源；
- 一个可回算的验收值。
多图报告按“总览 → 变化 → 构成/排名 → 关系/原因 → 结论”组织。相邻图不能重复回答同一问题，也不要连续堆叠轮廓相似的图。
阶段 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：数据对账和浏览器验收
先对账，再评价视觉。至少检查：
- 页面总数、均值、占比、排名、Top N、时间范围和标注值能回算到源 Excel。
- 百分比分母和舍入正确；面积编码使用面积而非半径表达数值；对数轴有明确标记。
- HTML 不含远程脚本、在线字体、完整原始表或数据下载链接。
- JavaScript 通过语法检查，页面没有控制台错误和远程资源请求。
- 约 1440px 桌面端和约 390px 移动端均无横向溢出、裁切、标签碰撞或过度留白。
- 交互控件真实改变图表，而不是只切换按钮状态。
- 再次核对源工作簿 SHA-256、大小和修改时间未改变。
当前 Epoch AI 案例执行 npm run verify:browser。适配新工作簿时，应为本次 generated/<工作簿名>/ 编写等价的 Playwright 验收脚本，或直接用 DSH Shell 调用本机浏览器完成相同检查：
node generated/<工作簿名>/scripts/visual-qa.cjs
发现问题就修复数据脚本或页面模板，并重复相应检查。不能把未运行的项目写成通过。
失败时如何处理
- 找不到工作表或字段：停止构建，列出实际发现的工作表/列和预期项。
- 哈希或行列基线变化：先重新剖析并解释变化，不得删除校验绕过失败。
- 公式无缓存：不使用该指标，说明需要由 Excel 或兼容计算引擎重算。
- 分类加总不一致：定位缺失类、重复类、筛选条件和分母，不要用“其他”强行抹平。
- 浏览器验收失败：保留真实错误，修复后重跑；缺少浏览器时明确写“未验证”。
最终回复
用中文简洁报告：
- 输入工作表/区域、有效记录数和排除记录数；
- 采用的分析问题、核心结论和图表类型；
- 构建后的 HTML 与预览图路径；
- 数据对账、离线打开、桌面端、移动端、交互和源文件未修改是否通过；
- 任何未验证项、公式限制或数据口径风险。
不要只回复“已完成”，也不要把脚本存在当作脚本已经运行。
