企业官网建设流程全解析

DB-GPT 内置技能 walmart-sales-analyzer：从沃尔玛销售 CSV 到业务级 HTML 深度分析报告

【免费下载链接】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 内置的数据分析技能（Skill），专为沃尔玛销售数据集设计：它围绕"周销售额与失业率"的关系展开多维度统计分析，自动生成四类可视化图表，并把结论封装成一份可直接交付给业务方的响应式 HTML 报告。读完本文，你将掌握该技能的输入数据要求、核心工作流、各图表脚本的实现细节，以及如何通过 DB-GPT 的execute_skill_script_file与html_interpreter工具链完成从数据分析到报告呈现的完整闭环。

一、技能定位：它解决什么问题

官方文档 walmart-sales-analyzer.md 将其定义为"面向沃尔玛销售数据集的内置分析技能"，核心关注点是周销售额与失业率之间的趋势关系，并将分析结论打包为面向业务的 HTML 报告。适合它的典型场景包括：

• 分析沃尔玛销售 CSV 数据；
• 探索销售额与失业率之间的宏观关系；
• 生成门店间的对比图表与时间趋势；
• 渲染一份带业务解读的精美 HTML 报告。

技能在仓库中的实际目录结构如下：

skills/walmart-sales-analyzer/ ├── SKILL.md ├── scripts/ │ ├── generate_html_report.py │ ├── generate_correlation_heatmap.py │ ├── generate_sales_unemployment_scatter.py │ ├── generate_time_series_trend.py │ ├── generate_store_avg_comparison.py │ └── font_setup.py └── templates/ └── report_template.html

其中 SKILL.md 是技能的"说明书"，其 frontmatter 中的name与description会被 DB-GPT 的技能加载机制读取，作为 Agent 判断"该用哪个技能"的依据；正文部分则直接指导 Agent 按什么流程执行脚本、如何填充报告占位符。

二、输入数据要求：CSV 必须包含哪些列

技能要求提供一个沃尔玛销售 CSV 文件，至少包含以下四列：

在仓库中可直接找到示例数据 Walmart_Sales.csv，它是各图表脚本的默认输入文件名。所有脚本对输入路径的解析遵循同一套约定（见 generate_html_report.py 的主入口）：

args = json.loads(sys.argv[1]) if len(sys.argv) > 1 else {} data_path = args.get('input_file') or args.get('file_path') or args.get('data_path', 'Walmart_Sales.csv') out_dir = args.get('output_dir', os.environ.get('OUTPUT_DIR', '.'))

也就是说：脚本接收一个 JSON 字符串作为第一个命令行参数，输入文件按input_file→file_path→data_path的优先级取值，缺省时使用当前目录下的Walmart_Sales.csv；输出目录取output_dir参数，缺省时读环境变量OUTPUT_DIR，再缺省输出到当前目录.。

三、核心工作流：四步完成从数据到报告

技能文档与 SKILL.md 中的 Core Workflow 一致，完整流程为四步：

1. 校验上传文件：确认用户提供的是合法的沃尔玛销售 CSV（列名满足上文要求）；
2. 执行分析脚本：通过execute_skill_script_file工具运行generate_html_report.py，在args中传入input_file与output_dir。该脚本会自动生成全部图表（correlation_heatmap.png、sales_vs_unemployment_scatter.png等）和基础报告；
3. 呈现报告：调用html_interpreter工具，指定template_path为walmart-sales-analyzer/templates/report_template.html，并传入渲染所需的文本数据。必须动态填充全部占位符（含所有章节标题、报告标题与分析内容），否则对应位置会渲染为 "NA"；且内容语言必须与用户输入语言一致；
4. 结束任务：调用terminate并给出最终答复，总结所做操作。

第 2 步的调用示例（来自 SKILL.md）：

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

四、四个图表脚本的源码级实现

generate_html_report.py并不是独立绘图，而是依次调用四个专门的绘图函数（generate_html_report.py）：

generate_correlation_heatmap(data_path, output_dir) generate_sales_unemployment_scatter(data_path, output_dir) generate_time_series_trend(data_path, output_dir) generate_store_avg_comparison(data_path, output_dir)

下面逐一看每个脚本的核心实现。

4.1 数据相关性热力图

generate_correlation_heatmap.py 读取 CSV 后对全部数值列计算相关系数矩阵，并用 seaborn 热力图呈现：

plt.figure(figsize=(10, 8)) corr = df.corr(numeric_only=True) sns.heatmap(corr, annot=True, cmap='coolwarm', fmt=".2f") plt.title('Walmart 销售数据相关性热力图') plt.savefig(output_path, dpi=150, bbox_inches="tight")

要点：annot=True会在每个格子中标注相关系数（保留两位小数），coolwarm配色以冷色表示负相关、暖色表示正相关，dpi=150保证报告中的图片清晰度。输出文件为correlation_heatmap.png。

4.2 销售额 vs 失业率回归散点图

generate_sales_unemployment_scatter.py 使用 seaborn 的regplot一次完成散点 + 回归线：

sns.regplot(data=df, x='Unemployment', y='Weekly_Sales', scatter_kws={'alpha': 0.3}, line_kws={'color': 'red'})

散点透明度设为 0.3 以缓解高密度重叠，红色回归线直观展示"经济压力下消费韧性"这一业务命题。输出文件为sales_vs_unemployment_scatter.png。

4.3 指定门店的时间序列趋势

generate_time_series_trend.py 的双轴图设计值得注意：

def generate_time_series_trend(data_path, output_dir, selected_stores=[1, 4, 20]): ... df["Date"] = pd.to_datetime(df["Date"], dayfirst=True) fig, ax1 = plt.subplots(figsize=(12, 6)) ax2 = ax1.twinx()

• selected_stores默认跟踪门店 1、4、20 三家（可通过函数参数调整）；
• 日期解析使用dayfirst=True，即按"日/月/年"格式理解数据源中的日期，若你的数据为美国常见的"月/日/年"格式，解析前需要自行确认；
• 左轴绘制各门店周销售额，右轴（twinx()）用红色虚线叠画第一家门店的失业率，注释中说明这样处理是因为失业率通常是区域级、各门店相近的指标；
• 输出文件为time_series_trend.png。

4.4 门店平均业绩对比

generate_store_avg_comparison.py 先按门店聚合再作图：

store_agg = df.groupby("Store").agg({"Weekly_Sales": "mean", "Unemployment": "mean"}).reset_index() sns.scatterplot(data=store_agg, x="Unemployment", y="Weekly_Sales", hue="Store", palette="viridis", s=100)

每个点对应一家门店的"平均周销售额 vs 平均失业率"，按门店着色，用于支撑区域运营策略建议。输出文件为store_avg_comparison.png。

4.5 中文字体兜底：font_setup.py

四个绘图脚本开头都会调用 font_setup.py 中的setup_chinese_font()。它按 macOS（如 PingFang SC）、Linux（如 Noto Sans CJK SC）、Windows（如 Microsoft YaHei、SimHei）的优先级遍历候选中文字体，命中第一个系统已安装的字体即配置plt.rcParams["font.sans-serif"]；若全部缺失，则仅关闭 Unicode 减号问题并让 matplotlib 自行兜底。这解释了为什么图表标题（如"Walmart 销售数据相关性热力图"）在装了中文字体的机器上能正常渲染。

五、一键入口 generate_html_report.py 的输出机制

generate_html_report.py 除调用四个绘图函数外，还做两件事：

1. 收集图片产物：按固定文件名列表（correlation_heatmap.png、sales_vs_unemployment_scatter.png、time_series_trend.png、store_avg_comparison.png）检查输出目录，把实际存在的图片打包为{"output_type": "image", "content": 绝对路径}的 chunk；
2. 落盘基础报告：读取 report_template.html 模板内容，写入walmart_sales_report.html，最后以 JSON 形式向 stdout 输出{"chunks": [...]}（含图片 chunk 与文本 chunk "HTML report and 4 charts generated successfully."），供上层执行环境解析并回传给 Agent。

这一"stdout 输出 JSON chunks"的约定，是该技能与 DB-GPT 脚本执行工具链的对接方式——Agent 依据输出中的图片路径与状态文本判断执行结果。

六、报告模板与 html_interpreter 渲染

最终呈现给用户的交互式报告由 templates/report_template.html 渲染。该模板采用响应式设计（max-width: 1100px容器、卡片式 section、viewportmeta），主色为#0071ce、强调色#ffc220，内置.analysis-box、.tag、.chart-container等样式类，适合不同设备查看。

Agent 通过html_interpreter工具把分析文本注入模板，需要填充的占位符与示例datapayload 如下（完整示例见 SKILL.md）：

{ "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" }

四个分析章节与四张图表一一对应：多维相关性分析（热力图）、销售额-失业率回归（散点图）、动态趋势跟踪（时间序列图）、门店业绩对比（平均对比图），外加执行摘要与最终结论建议。SKILL.md 中特别强调两点硬性要求：所有占位符必须动态填充，否则渲染为 "NA"；输出语言必须与用户输入语言严格一致（图表同样支持多语言显示）。

七、使用建议与注意事项

• 优先使用一键入口：SKILL.md 将generate_html_report.py标注为 Recommended，一次运行即可产出全部图表与基础报告；单图脚本（热力图、散点、时序、门店对比）适合按需单独重跑某一张图；
• 语言一致性：无论图表还是报告文本，都必须匹配用户请求语言，这是 SKILL.md 的强制约束；
• 默认门店与日期格式：时间序列图默认跟踪门店 1、4、20，日期按dayfirst=True解析，数据源日期格式不同的场景需要预先核实；
• 运行前提：脚本依赖pandas、matplotlib、seaborn（可从各脚本 import 确认），中文字体为可选增强，缺失时英文/数字仍可正常显示；
• 延伸阅读：技能的整体设计与使用方式可参考 overview.md、how-to-use-skill.md 与 how-to-use-custom-skill.md，本技能可作为理解 DB-GPT"SKILL.md + scripts + templates"技能范式的典型样本。

综上，walmart-sales-analyzer 展示了 DB-GPT 内置技能的一个完整形态：SKILL.md 定义能力边界与执行规程，scripts 目录提供确定性的分析实现，templates 目录承载交付物样式，三者协作使 Agent 能在对话中完成"数据校验 → 图表生成 → 业务解读 → 报告渲染"的全链路分析任务。

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