DB-GPT walmart-sales-analyzer Skill 实战：一键生成沃尔玛销售数据深度分析报告-育师

DB-GPT walmart-sales-analyzer Skill 实战：一键生成沃尔玛销售数据深度分析报告

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

导读

walmart-sales-analyzer是 DB-GPT 内置的 DataAnalysis 类技能（Skill），用于对沃尔玛（Walmart）销售数据进行深度分析，重点探索各门店销售额与宏观失业率之间的关系，并自动生成包含相关性热力图、散点回归图、时间序列趋势图、门店横向对比图与深度解读的响应式 HTML 报告。读完本文，你将掌握该 Skill 的完整使用流程、五个绘图脚本与 HTML 模板的实现原理，并能在 DB-GPT Agent 中复现从 CSV 上传到专业报告呈现的全过程。

一、Skill 概览与定位

该 Skill 的元信息定义在 skills/walmart-sales-analyzer/SKILL.md 的 Front Matter 中：

name：walmart-sales-analyzer
description：分析沃尔玛销售数据，探索门店销售额与失业率之间的趋势，生成富有洞察力的可视化图表与美观的 HTML 深度分析报告，适合快速洞察销售数据与宏观经济因素的关系。

从 DB-GPT 的 Skill 类型体系看（参见 skills/README.md），这是一个典型的数据分析类技能：由「元数据（Metadata）」「提示词模板」「必需工具」「动作」和「配置」组成，最终通过 Skill Manager 注册、被 Agent 加载执行。如果你需要将该 Skill 集成进自定义 Agent，可参考 skills/INTEGRATION_GUIDE.md 中的SkillEnabledAgent实现——它会将 Skill 的prompt_template绑定到 Agent，并在资源加载阶段校验required_tools与required_knowledge是否齐备。

二、功能特性

该 Skill 提供以下五项核心分析与可视化能力：

序号	功能	说明
1	数据相关性热力图	展示数据集中所有数值变量之间的相关系数，并给出详细解读
2	销售额 vs 失业率散点图	带回归线直观呈现周销售额与失业率的关系，深入分析经济压力下的消费韧性
3	特定门店销售与失业率时间序列	追踪所选门店随时间变化的销售与失业率趋势，区分季节力量与宏观趋势
4	各门店平均销售额与平均失业率对比	横向比较不同门店的销售表现与其所在地区平均失业率，为区域运营策略提供建议
5	HTML 深度分析报告生成	自动将所有图表整合进美观、响应式的 HTML 报告，附带详细分析结论与业务建议

三、使用前提：数据格式要求

使用该 Skill 时，需要向 Agent 提供一个包含沃尔玛销售数据的CSV 文件。文件至少应包含以下列：

Store：门店 ID
Date：日期
Weekly_Sales：周销售额
Unemployment：失业率

仓库中提供了可复现运行的示例数据 docker/examples/dashboard/Walmart_Sales.csv，以及用于数据库场景的 docker/examples/sqls/test_case_info_sqlite.sql、docker/examples/sqls/test_case_info_mysql.sql 等建表/导入脚本，可据此构造符合列要求的 CSV。若数据来自 SQLite 数据库（如 examples/test_files/datamanus_test.db），可先用 DuckDB/SQLite 导出为 CSV 再交给本 Skill。

四、核心工作流

Skill 文档定义的执行流程如下，共四步：

1. 检查上传文件

首先确认用户提供了有效的 Walmart 销售数据 CSV 文件，并校验所需列（Store、Date、Weekly_Sales、Unemployment）是否齐全。

2. 执行分析脚本

使用execute_skill_script_file工具运行generate_html_report.py，将 CSV 文件路径传给args参数中的input_file：

{"skill_name": "walmart-sales-analyzer", "script_file_name": "generate_html_report.py", "args": {"input_file": "/path/to/Walmart_Sales.csv", "output_dir": "."}}

说明：该脚本会自动生成全部所需图表（correlation_heatmap.png、sales_vs_unemployment_scatter.png、time_series_trend.png、store_avg_comparison.png）以及基础报告文件。

3. 呈现报告

为通过 DB-GPT UI 向用户呈现结果，必须使用html_interpreter工具，提供template_path（walmart-sales-analyzer/templates/report_template.html）和必要的文本数据以交互式渲染报告。必须基于你的分析动态填充所有占位符（包括所有章节标题、报告标题和分析内容，否则会渲染为 'NA'），并确保它们被翻译成用户使用的语言。

完整data载荷示例：

{ "LANG": "en", "REPORT_TITLE": "Walmart Sales Deep Analysis Report", "REPORT_SUBTITLE": "Based on macroeconomic indicators and store performance", "EXEC_SUMMARY_TITLE": "Executive Summary", "EXEC_SUMMARY_CONTENT": "<p>Your detailed summary...</p>", "SECTION_1_TITLE": "1. Multi-dimensional Correlation Analysis", "SECTION_1_ANALYSIS": "<h3><span class=\"tag\">Insights</span> Variable relationships</h3><ul><li>...</li></ul>", "SECTION_2_TITLE": "2. Sales vs Unemployment Regression", "SECTION_2_ANALYSIS": "<h3><span class=\"tag\">Deep Dive</span> Resilience under pressure</h3><p>...</p>", "SECTION_3_TITLE": "3. Dynamic Trends Tracking", "SECTION_3_ANALYSIS": "<h3><span class=\"tag\">Trends</span> Seasonal vs Macro</h3><p>...</p>", "SECTION_4_TITLE": "4. Store Performance Comparison", "SECTION_4_ANALYSIS": "<h3><span class=\"tag\">Strategy</span> Regional operations</h3><p>...</p>", "CONCLUSION_TITLE": "Final Conclusions & Recommendations", "CONCLUSION_CONTENT": "<ol><li>...</li></ol>", "FOOTER_TEXT": "Deep Data-Driven Decisions" }

上述占位符对应模板中执行摘要、四个分析章节、最终结论与页脚五大区域，其中EXEC_SUMMARY_CONTENT、SECTION_N_ANALYSIS、CONCLUSION_CONTENT均支持直接嵌入 HTML（<p>、<ul>、<ol>、<h3>等），便于在analysis-box中渲染带标签的深度解读。

4. 完成任务

调用terminate工具，附上总结本次分析动作的最终回答。

五、脚本清单与逐文件源码解析

Skill 共包含 5 个脚本与 1 个 HTML 模板，统一由generate_html_report.py一键串联。所有脚本都遵循「从input_file/file_path/data_path读取 CSV → 绘图 → 输出 PNG」的统一接口约定，参数优先级为input_file>file_path>data_path，且支持通过OUTPUT_DIR环境变量指定输出目录。

5.1 generate_html_report.py（推荐，一键报告）

skills/walmart-sales-analyzer/scripts/generate_html_report.py 是编排入口，核心逻辑：

os.makedirs(output_dir, exist_ok=True)确保输出目录存在；
依次调用其余四个绘图函数，将四张 PNG 写入输出目录；
遍历固定图片名列表，把实际存在的图片以{"output_type": "image", "content": 绝对路径}结构组装进chunks；
读取模板 templates/report_template.html 并原样保存为walmart_sales_report.html（图表通过相对路径src="correlation_heatmap.png"引用，因此图片与报告必须放在同一目录）；
最后以 JSON 形式打印{"chunks": [...]}结果，供上层 Agent 工具解析。

命令行调用方式：

python generate_html_report.py '{"input_file": "Walmart_Sales.csv", "output_dir": "./report"}'

5.2 generate_correlation_heatmap.py（相关性热力图）

skills/walmart-sales-analyzer/scripts/generate_correlation_heatmap.py 实现功能 1：

df.corr(numeric_only=True)计算全部数值列的两两 Pearson 相关系数矩阵；
sns.heatmap(corr, annot=True, cmap='coolwarm', fmt=".2f")绘制带数值标注的热力图，coolwarm配色使正负相关一目了然；
以dpi=150、bbox_inches="tight"保存，兼顾清晰度与留白裁剪。

典型解读方向（模板中已内置示例结论）：Weekly_Sales与Unemployment呈微弱负相关（约 -0.11），与节假日呈显著正相关，CPI与Unemployment通常负相关——这些结论会由 Agent 结合实际数据动态重写。

5.3 generate_sales_unemployment_scatter.py（散点 + 回归线）

skills/walmart-sales-analyzer/scripts/generate_sales_unemployment_scatter.py 实现功能 2：

sns.regplot(data=df, x='Unemployment', y='Weekly_Sales', scatter_kws={'alpha':0.3}, line_kws={'color':'red'})在散点基础上叠加线性回归拟合线，alpha=0.3降低散点透明度以缓解重叠；
从源码结构看，回归线斜率为负说明失业率上升对整体销售有轻微抑制作用，但点的高离散度又提示「消费刚性」：Walmart 经营大量生活必需品，抗经济波动能力较强，高失业率区域仍可能存在高销售门店（异常值，可能与当地竞争格局或门店规模有关）。

5.4 generate_time_series_trend.py（时间序列双轴趋势）

skills/walmart-sales-analyzer/scripts/generate_time_series_trend.py 实现功能 3：

默认选取selected_stores=[1, 4, 20]三个门店；
pd.to_datetime(df["Date"], dayfirst=True)解析日期（注意dayfirst=True，即日期按「日/月/年」顺序解析，要求源数据日期格式与此匹配）；
通过ax1.twinx()创建共享 x 轴的双 y 轴图：左侧（蓝色）绘制各门店Weekly_Sales时序，右侧（红色虚线）仅对第一个门店绘制Unemployment曲线——注释表明这是因为失业率多为区域共享、门店间差异小；
可据此观察 Q4（11–12 月）的爆发式增长、季节性力量远超失业率波动、各门店波动节奏一致等结论。

5.5 generate_store_avg_comparison.py（门店均值对比）

skills/walmart-sales-analyzer/scripts/generate_store_avg_comparison.py 实现功能 4：

df.groupby("Store").agg({"Weekly_Sales": "mean", "Unemployment": "mean"})先按门店聚合出平均周销售额与平均失业率；
sns.scatterplot(..., hue="Store", palette="viridis", s=100)以点大小放大、门店作色绘制分布，直观暴露区域差异；
分析落点：低失业率 + 高销售额的门店可作为旗舰店重点投入；高失业率 + 低迷销售额的门店需优化商品结构、提升高性价比商品占比。

5.6 font_setup.py（多语言字体兜底）

skills/walmart-sales-analyzer/scripts/font_setup.py 是全部绘图脚本共享的字体配置模块：

按优先级探测 macOS（PingFang SC、Heiti TC 等）、Linux（Noto Sans CJK SC、WenQuanYi Micro Hei 等）、Windows（Microsoft YaHei、SimHei 等）常见 CJK 字体；
命中即设置plt.rcParams["font.sans-serif"]与axes.unicode_minus = False（修复负号显示为方块的问题）；
全部候选缺失时，仍强制关闭 Unicode 负号以保证基本可读性。

这也是所有图表支持多语言显示、标题可直接使用中文（如「Walmart 销售数据相关性热力图」）的原因。

六、HTML 报告模板解析

skills/walmart-sales-analyzer/templates/report_template.html 是一份完整的单页 HTML，内置了：

主题化 CSS 变量：--primary-color: #0071ce（沃尔玛蓝）、--secondary-color: #ffc220（沃尔玛黄），配合渐变页头、圆角卡片（.section）、左侧黄色竖线的章节标题、浅蓝analysis-box解读框，整体为响应式布局（max-width: 1100px容器 + 图片max-width: 100%）。
五大内容区块：执行摘要、4 个分析章节（每章含一张图表 + 一个带.tag标签的解读框）、最终结论与建议（有序列表）、页脚（标明Generated by DB-GPT AI Professional Suite）。

模板自带一份「示例级」分析与业务建议（如：提前 3–6 个月完成 Q4 供应链优化、失业率上升区域适度增加促销、密切监控 CPI 波动等），但正如 SKILL.md 强调的：Agent 必须根据本次实际分析动态填充所有占位符（包括标题与结论），并翻译为用户语言，否则对应位置将渲染为 'NA'。这也决定了该模板的占位符设计——固定样式骨架 + 动态内容注入。

七、重要注意事项

语言一致性（强制要求）：Agent 的输出语言必须与用户在输入/请求中所使用的语言完全一致——报告标题、章节标题、分析内容都要翻译成用户的母语。
多语言图表：所有图表均支持多语言显示（得益于font_setup.py的字体兜底机制）。
响应式报告：报告模板采用响应式设计，适合在电脑、平板、手机等不同设备上查看，并内置了详细的分析解读与业务建议。
占位符必填：渲染报告前务必补齐全部占位符字段，避免出现 'NA'。

八、扩展阅读

Skill 定义文档：skills/walmart-sales-analyzer/SKILL.md
Skill 机制与注册 API：skills/README.md
Skill 集成到自定义 Agent 指南：skills/INTEGRATION_GUIDE.md
示例数据：docker/examples/dashboard/Walmart_Sales.csv（另有Walmart_Sales.dbSQLite 版本可在同目录找到）
其他同类 Skill 参考：skills/csv-data-analysis/SKILL.md、skills/financial-report-analyzer/SKILL.md

结合 examples/agents/skill_agent_example.py 可以进一步理解 Skill 在 Agent 对话中的加载方式。整体而言，walmart-sales-analyzer展示了 DB-GPT「Skill + 脚本 + 模板」三件套的最佳实践：把标准化的数据分析流水线封装为可复用技能，再借助html_interpreter在 Web UI 中即时呈现专业报告——这种模式同样适用于财务、零售、电商等其他需要「数据 → 洞察 → 报告」一键输出的业务场景。

【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI + Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考