DB-GPT csv-data-analysis 内置技能详解从统计提取脚本到 ECharts 交互报告【免费下载链接】DB-GPTopen-source agentic AI data assistant for the next generation of AI Data products.项目地址: https://gitcode.com/GitHub_Trending/db/DB-GPT本文基于 DB-GPT 仓库中csv-data-analysis内置技能的官方文档与配套源码系统讲解该技能如何在 Agent 对话中把用户上传的 CSV / Excel / TSV 文件转化为一份可交互的 HTML 数据分析报告包括技能触发机制、两步式工作流契约、9 个模板占位符、统计提取脚本csv_analyzer.py的分析模块与输出协议以及后端自动注入图表数据的设计原理。技能定位与适用场景csv-data-analysis是 DB-GPT 内置的深度数据分析技能面向 CSV、Excel.xlsx / .xls和 TSV 文件将统计特征提取、异常发现、图表就绪的结构化数据与 HTML 报告生成组合成一个完整的技能包。它的设计哲学是机器提取 LLM 推理分工Python 脚本负责确定性的统计计算LLM 负责基于统计摘要撰写业务洞察模板负责前端渲染。典型使用场景继承自官方文档分析用户上传的 CSV 文件分析 Excel 工作簿计算统计量并检测异常值生成精致的交互式分析报告。从技能触发机制看技能的身份信息定义在 SKILL.md 的 YAML frontmatter 中name为csv-data-analysisdescription中同时列出了中英文触发关键词analyze CSV、generate charts、数据分析、生成图表等。DB-GPT 的技能加载层 skills.py 中的SkillsLoader会扫描各技能源目录下含SKILL.md的子目录解析 frontmatter 生成SkillMetadata要求 name 最长 64 字符、description 超长截断至 1024 字符并通过SkillsMiddleware.create_skills_prompt_section()以渐进式披露progressive disclosure方式注入系统提示词——Agent 平时只看到技能的名称与描述命中任务时才读取完整 SKILL.md 指令。技能目录结构与关键资源技能在仓库中的布局如下与官方文档的 Repo path 完全一致另含两个脚手架占位文件skills/csv-data-analysis/ ├── SKILL.md # 技能说明书含 LLM 必读的工作流与规则 ├── scripts/ │ ├── csv_analyzer.py # Python 分析引擎约 990 行支持 CSV/Excel/TSV无图形依赖 │ └── example.py # 脚手架占位脚本 ├── references/ │ └── reference.md # 补充参考文档当前为 TODO 骨架 └── templates/ └── report_template.html # ECharts Tailwind 响应式报告模板约 1179 行资源作用scripts/csv_analyzer.py提取统计量、数据质量信号与图表标记数据references/reference.md技能的补充参考文档当前内容仍为 TODO 占位骨架templates/report_template.html最终交互式报告模板其中scripts/example.py与references/reference.md属于技能脚手架生成的占位文件内容均为 TODO 模板实际工作负载集中在csv_analyzer.py与报告模板上。核心工作流Agent 必须遵循的两步契约官方文档给出的核心工作流为五步本质是先执行脚本取数再注入模板出报告通过execute_skill_script_file工具运行scripts/csv_analyzer.py读取脚本返回的统计摘要Statistical Summary使用html_interpreter工具加载csv-data-analysis/templates/report_template.html只填充必需的文字占位符9 个图表标记数据由后端自动捕获注入LLM 无需处理。第 1 步执行统计提取脚本execute_skill_script_file的调用参数示例继承自 SKILL.md{ skill_name: csv-data-analysis, script_file_name: csv_analyzer.py, args: {input_file: /path/to/data.csv or /path/to/data.xlsx} }脚本返回一个大块text内容由两部分组成【统计摘要】供 LLM 阅读理解数据集的基本特征、分布、相关性与类别构成标记数据块形如###KEY_START###...###KEY_END###的数据块本技能中主要是CHART_DATA_JSON由后端自动捕获并注入模板——LLM 不需要也不应该手动传递这部分内容。第 2 步生成洞察并注入模板读取统计摘要后LLM 推理数据背后的业务含义再调用html_interpreter加载模板。SKILL.md 中列出的关键规则必须遵循template_path必须设置为csv-data-analysis/templates/report_template.html。模板内置完整的 ECharts 渲染 JS 与全部章节标题、页脚文字LLM 只需通过data参数填 9 个内容占位符绝不允许自行编写或修改任何 JavaScript 图表代码标记数据块由后端自动注入不能出现在data中*_INSIGHTS、EXEC_SUMMARY、CONCLUSIONS必须使用 HTML 格式p、ul、li、strong、ol以保证版式输出语言必须匹配用户输入语言并显式传递LANG占位符en或zh模板据此翻译硬编码的章节标题、标签与页脚不确定时默认zh恰好传 9 个占位符不多不少——CHART_DATA_JSON等标记字段由后端处理章节标题由模板按LANG自动翻译洞察内容必须实质性每个洞察模块尽量覆盖观察现象、可能原因、业务影响、行动建议四层信息不要只复述统计值报告遵循基础分析在前、归因增强在后的结构前半部分聚焦数据本身特征分布、类别结构、离群值、相关性、排名模式数据异常概览归因分析根因推断作为后半部分增强模块。html_interpreter调用示例继承自 SKILL.md{ template_path: csv-data-analysis/templates/report_template.html, data: { LANG: en, REPORT_TITLE: Sales Dataset Deep Analysis Report, REPORT_SUBTITLE: Multi-dimensional Data Feature Business Insight Mining, EXEC_SUMMARY: pThis dataset contains 1,000 rows and 5 columns with good data completeness.../pullistrongAudience Distribution:/strong .../li/ul, DISTRIBUTION_INSIGHTS: pThe numerical distribution chart reveals that Metric A exhibits a pronounced right-skewed distribution.../p, CORRELATION_INSIGHTS: pThe heatmap reveals strong positive correlations, particularly between.../p, CATEGORICAL_INSIGHTS: pCategory proportions show that Beijing and Shanghai account for over 50% of the City field./p, TIME_SERIES_INSIGHTS: pThe time series trend indicates a significant seasonal uptick toward year-end./p, CONCLUSIONS: pBased on the comprehensive analysis.../ph3Recommendations/h3ulli.../li/ul } }SKILL.md 同时给出了明确的严格禁止清单不要在data中传CHART_DATA_JSON等自动注入字段不要在data中加入任何 JavaScript 代码不要省略template_path省略会导致图表无法渲染不要返回静态 PNG 图片工具已全面升级为 ECharts 动态前端渲染不要传递不存在的占位符模板仅有 9 个文本占位符 1 个自动注入的CHART_DATA_JSON其他名称会被忽略。模板占位符契约9 个模板的完整占位符契约如下表继承自 SKILL.md 的 Placeholder Reference占位符类型必填说明LANGText是报告语言英文en中文zh决定全部章节标题、标签与页脚文字的语言从用户输入语言检测默认zhREPORT_TITLEText是报告标题如销售数据集深度分析报告REPORT_SUBTITLEText是报告副标题EXEC_SUMMARYHTML是执行摘要数据规模、关键发现、结论预告DISTRIBUTION_INSIGHTSHTML是数值分布特征解读偏态、波动性、分位区间、离散度CORRELATION_INSIGHTSHTML是关系分析与异常识别解读相关性、联动、离群点、结构关系CATEGORICAL_INSIGHTSHTML是特征分析与结构分析解读类别结构、集中度、排名与分组特征TIME_SERIES_INSIGHTSHTML是数据异常概览节的补充解读有时间列时讨论趋势无时间列时讨论分层差异与异常模式CONCLUSIONSHTML是根因推断、结论与建议正文必须区分数据证据与合理推测注意所有章节标题Distribution Analysis、Correlation Analysis等、洞察框标题与页脚文字均硬编码在 report_template.html 中并依据LANG占位符自动翻译不需要也不应该通过data传入。统计提取脚本 csv_analyzer.py 的源码级解析csv_analyzer.py约 990 行仅依赖 pandas / numpy日志走 stderr 以避免污染 stdout 的 JSON 输出是整个技能的计算内核可脱离 Agent 独立运行。命令行接口与输出协议脚本入口main()的参数解析逻辑很宽松优先把sys.argv[1]当作 JSON 解析依次尝试input_file、file_path、csv_file三个键JSON 解析失败时则把原始参数当作文件路径。这解释了 SKILL.md 中args: {input_file: ...}的写法与手动运行python3 csv_analyzer.py {input_file: data.csv}两种用法。文件读取按扩展名分派.xls/.xlsx走pd.read_excel.tsv走sep\t其余按 CSV 读取仅接受.csv / .xls / .xlsx / .tsv四种格式其余直接报不支持的文件格式并以退出码 1 结束。所有结果包括错误统一以如下 JSON 协议打印到 stdout{chunks: [{output_type: text, content: 统计摘要 标记数据块}]}该chunks结构正是execute_skill_script_file工具消费脚本输出的标准载体。分析模块一览analyze_csv()依次计算十余个分析模块最终产出两类产物——给 ECharts 渲染的chart_dataJSON 与给 LLM 阅读的文本摘要基础概览overview行列数、缺失单元格数与缺失率、重复行数、内存占用KB数据质量data_quality每列缺失率、dtype、唯一值数并把列按 numeric / datetime / text 归类汇总主指标选择select_primary_metric通过唯一值 5 加分、非排名/ID 类列名加分、命中业务关键词score、amount、revenue、销售额等加倍、标准差 0 加分的启发式打分从数值列中挑出主分析指标另有select_label_col()挑选第一个非唯一文本列作为排名标签数值分布distributions对前 8 个数值列各画 10 个 bin 的直方图并计算 min / P5 / Q25 / 中位数 / 均值 / Q75 / P95 / max / 标准差 / CV% / 偏度 / 峰度。偏度按阈值分类|skew|≥1 明显偏态、≥0.5 中度偏态、否则近似对称CV 按阈值分类≥100 极高波动、≥50 高波动、≥20 中等波动、否则低波动相关性correlations全数值列的 Pearson 相关矩阵NaN 填 0并以[i, j, value]三元组形式输出供热力图使用同时挑出 Top3 正相关与 Top3 负相关组合写入correlation_highlights分类列分析categories / cat_summary对前 6 个基数 ≤ 50 的分类列取 Top10 取值计算 Shannon 熵log2、Top1 占比与 Top3 集中度top3_share分组切片segment_breakdown / segment_comparison以主指标为度量对前 3 个分类列做 groupby 的 count / mean / sum输出各维度头部 5 组的表现时间序列time_series自动探测可解析为日期的文本列按月点数 3 时退化为按日重采样取最近 100 个点并输出诊断量起点、终点、整体变化百分比、线性斜率np.polyfit、波动率、峰值/谷值日期与数值额外最多附加 2 条次级趋势线散点图scatter优先选与主指标相关系数绝对值最大的数值列配对采样上限 500 个点random_state42避免载荷过大箱线图与 IQR 异常值box_plots / outliers前 8 个数值列按 Q1−1.5×IQR、Q31.5×IQR 围栏检测异常渲染离群点最多 50 个Top/Bottom 排名top_bottom / ranking_signal按主指标或首个数值列输出 Top5 / Bottom5标签列取select_label_col结果并计算排名断层Top5 均值 − Bottom5 均值异动概览与归因anomaly_overview / driver_analysis以 P90 / P10 划分高低组计算组间差值、P0-P25/P25-P50/P50-P75/P75-P100 分位带样本分布归因打分公式为score min(100, |相关系数| × 55 min(|组间差异强度|, 3) × 15)取 Top8 候选驱动因子统计表stats_table13 列变量、最小值、P5、Q25、中位数、均值、Q75、P95、最大值、标准差、CV%、偏度、峰度的完整统计明细表。统计摘要与标记注入chart_data汇总了上述全部模块overview、data_quality、distributions、correlations、categories、time_series、scatter、box_plots、outliers、primary_metric、anomaly_overview、driver_analysis、top_bottom、stats_table等序列化为CHART_DATA_JSON。脚本输出的文本末尾固定拼接###CHART_DATA_JSON_START### { ...chart_data JSON... } ###CHART_DATA_JSON_END###而在此之前输出的【数据概览】【质量关注点】【数值型特征统计 (Top 8)】【波动性与偏态重点】【异常值检测 (IQR 方法)】【Top 5 / Bottom 5 排名】【数据异动概述】【归因分析线索】【分类型特征摘要】【核心相关性】【时间序列】等段落就是 SKILL.md 所称的Statistical Summary摘要结尾还附有一条给 LLM 的指令要求每个洞察模块覆盖现象、可能原因、业务影响、行动建议四层内容并再次强调 marker 中的CHART_DATA_JSON由后端自动注入模板、无需手动传递。这正是后端自动捕获标记块机制的脚本侧实现。报告产出结构按官方文档的 Output expectations该技能设计产出的报告包含七个板块执行摘要executive summary、数据质量评审data quality review、分布分析distribution analysis、相关性分析correlation analysis、分类与结构分析categorical and structural analysis、异常概览anomaly overview、结论与建议conclusions and recommendations。SKILL.md 进一步将其组织为前半部分基础数据分析 后半部分异常检测与归因增强的两段式结构对应模板中Executive Summary → Data Overview Quality Check → 数值分布 → 特征/结构分析 → 关系分析与异常识别 → 数据异常概览 → 归因分析 → 分析结果与统计明细 → 根因推断/结论/建议的章节序列前端由 ECharts 平滑动画与 Tailwind CSS 响应式布局渲染。落地与验证建议直接运行脚本准备任意.csv/.xlsx/.tsv样例文件后可以python3 skills/csv-data-analysis/scripts/csv_analyzer.py {input_file: /abs/path/to/data.csv}独立验证其chunks输出检查统计摘要段落与CHART_DATA_JSON标记块是否完整——这一步不依赖 LLM是排查报告问题的第一现场通过技能中间件加载create_skills_middleware([skills/])见 skills.py会把csv-data-analysis纳入可用技能列表Agent 在命中分析 CSV / Excel类请求时读取 SKILL.md 并遵循两步工作流排查报告不渲染图表优先核对template_path是否传入、是否误传了CHART_DATA_JSON、LANG是否指定——这三条恰好是 SKILL.md 严格禁止清单中最易踩中的项。需要说明的是references/reference.md目前仍是 TODO 骨架API 细节需要以 SKILL.md 与csv_analyzer.py源码本身为准技能整体属于契约驱动设计——脚本输出协议、9 个占位符与模板三者共同构成技能契约模板被 SKILL.md 明确声明为技能契约的一部分Agent 应使用随包 HTML 模板而不是手写报告渲染逻辑。【免费下载链接】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），仅供参考