DeerFlow 图表可视化技能实战：箱型图工具 generate_boxplot_chart 的输入规格、调用链与统计用法

本篇围绕 deer-flow 仓库中 chart-visualization 技能的箱型图规格文档，完整拆解 generate_boxplot_chart 工具的输入字段、默认值与返回契约，并结合 generate.js 的源码还原"JSON 载荷 → 图表 URL"的完整调用链。读完本文，你可以直接复制可运行的命令生成箱型图，理解 VIS_REQUEST_SERVER 等环境变量的作用，并掌握"每类别至少 5 个样本"这类统计意义约束在 Agent 取参阶段应如何落实。

一、箱型图在 chart-visualization 技能中的定位

deer-flow 的 chart-visualization 技能是一个"选图型 → 提参数 → 出图"三件套式的可视化工作流，覆盖 26 种图表类型，规格定义位于 SKILL.md，每种图型的输入字段说明则集中在 references/ 目录下。箱型图对应的规格文件正是本文的主体：generate_boxplot_chart.md。

按照 SKILL.md 的智能选图规则，箱型图被归入 Specialized（专业图表）→ Statistical distribution（统计分布） 一类，与 generate_violin_chart（小提琴图）并列：

• generate_boxplot_chart：展示各类别数据的分布范围（最值、四分位、异常值），用于质量监控、实验结果或群体分布比较；
• generate_violin_chart：结合核密度曲线与箱型统计展示分布形态，适合对比多批次实验或群体表现（见 generate_violin_chart.md）。

两者的分工可以从参考文档的"使用建议"中读出：箱型图强调"单个类别至少提供 5 个样本以保证统计意义"，而小提琴图要求"各类别样本量建议 ≥30 以确保密度估计稳定"。样本量小时用箱型图、样本量充足且关注分布形态时用小提琴图，这是 Agent 在"智能选图"阶段可以依据的两个量化判据。

二、输入字段完整规格

以下字段规格完整继承自原文档，并结合同系列图型（如条形图 generate_bar_chart.md）的写法交叉印证了默认值约定。

必填字段

字段	类型	说明
data	array<object>	每条记录包含 category（string）与 value（number），可选 group（string）用于多组比较

与直方图（generate_histogram_chart.md 中 data 为 number[]）不同，箱型图的 data 是对象数组：值必须能按 category 归组，箱型统计（中位数、Q1/Q3、须线、离群点）以类别为单位计算。

可选字段

字段	类型	默认值	说明
style.backgroundColor	string	—	设置背景色
style.palette	string[]	—	定义配色列表
style.texture	string	default	可选 default / rough（rough 为手绘纹理风格）
theme	string	default	可选 default / academy / dark
width	number	600	图表宽度
height	number	400	图表高度
title	string	""	图表标题
axisXTitle	string	""	X 轴标题
axisYTitle	string	""	Y 轴标题

值得注意的一点：箱型图没有 group / stack 这类布尔开关（条形图有），多组比较完全依赖数据记录中是否携带 group 字段来触发，即"数据形态即配置"。

三、可运行的完整调用示例

SKILL.md 规定的工作流是：从 references/ 读取规格 → 提取参数映射为 args → 以 JSON 载荷调用 scripts/generate.js。对箱型图而言，载荷格式如下：

{
  "tool": "generate_boxplot_chart",
  "args": {
    "data": [
      {"category": "批次A", "value": 98.2},
      {"category": "批次A", "value": 101.5},
      {"category": "批次A", "value": 99.8},
      {"category": "批次A", "value": 100.3},
      {"category": "批次A", "value": 97.1},
      {"category": "批次B", "value": 105.2},
      {"category": "批次B", "value": 103.9},
      {"category": "批次B", "value": 106.1},
      {"category": "批次B", "value": 104.4},
      {"category": "批次B", "value": 102.8},
      {"category": "批次B", "value": 118.0}
    ],
    "title": "两批次质量指标分布对比",
    "axisXTitle": "批次",
    "axisYTitle": "指标值",
    "theme": "default",
    "width": 600,
    "height": 400,
    "style": {"texture": "default"}
  }
}

执行命令（在技能目录下）：

node ./scripts/generate.js '<payload_json>'

从 generate.js 的参数解析逻辑看，specArg 会先做存在性判断：若参数是一个已存在的文件路径，则读取文件内容解析；否则直接按 JSON 字符串解析。也就是说载荷既可以内联在命令行里，也可以先写入临时 JSON 文件再传路径，后者更适合在沙箱中复用载荷。技能前置元数据要求 Node.js >=18.0.0，因为脚本使用了原生 fetch。

四、源码级调用链：从 tool 名到图表 URL

generate.js 的实现可以完整解释原文档"返回箱型图 URL"这一契约的底层路径：

1. 工具名映射：CHART_TYPE_MAP 将 generate_boxplot_chart 映射为图型标识 "boxplot"（第 9 行）。映射表注释标明其与前端 src/utils/callTool.ts 保持一致。
2. 服务端点解析：getVisRequestServer() 优先读取环境变量 VIS_REQUEST_SERVER，未设置时回落到默认的远程渲染服务地址 https://antv-studio.alipay.com/api/gpt-vis。这意味着箱型图并非本地渲染，而是把规格 POST 到可视化服务换取图片 URL——部署时若需切换渲染后端，只需设置该环境变量。
3. 请求构造：generateChartUrl() 以 { type: "boxplot", source: "chart-visualization-creator", ...options } 构造请求体并 POST，options 即 args 全量透传，success 为假时抛出 errorMessage，成功则返回 data.resultObj（即图片 URL）。
4. 批处理与容错：main() 支持传入数组载荷逐个生成（第 118 行 Array.isArray(spec) ? spec : [spec]）；单条缺失 tool 或图型未知时仅打印错误并 continue，不会中断其余图形的生成。箱型图不属于地图类工具（district_map / path_map / pin_map），因此走标准 generateChartUrl 分支，直接向 stdout 打印 URL。

技能入口本身由 deer-flow 的技能体系加载，test_skill_catalog.py 的测试夹具中即以 "chart-visualization", "Visualize data with interactive charts" 作为公共技能样本，印证其以 skills/public/ 下的目录 + SKILL.md 形式被技能目录发现与索引。

五、统计用法与返回契约

样本量约束。原文档"使用建议"明确指出：单个类别至少提供 5 个样本以保证统计意义——少于 5 个样本时四分位数（Q1、中位数、Q3）退化为插值估计，须线与离群点判定（通常为 1.5×IQR 规则）失去稳健性。若需展示多批次，有两种等价做法：在记录中携带 group 字段做多组并排比较，或拆分为多次调用分别出图。

返回契约。脚本 stdout 输出图片 URL；按 SKILL.md 第 4 步的约定，Agent 需向用户同时返回图片 URL 与完整的 args 规格——原文档亦说明输入规格会随结果在 _meta.spec 中留存。这一设计让生成的图表可以精确复现：拿到 _meta.spec 即可作为下一次调用的输入，实现"结果即规格"的幂等复用。

适用边界。箱型图适合类别数不多、关注集中趋势与离散程度的场景（质量监控、A/B 实验结果对比）；若目标是"识别偏态与集中区间"且数据为单一连续变量，应改用直方图（data 为 number[]，支持 binNumber 自定义分箱）；若需要呈现密度形态且样本充足（≥30），则选择小提琴图。

六、延伸阅读路径

• 箱型图规格原文：generate_boxplot_chart.md
• 技能工作流与载荷格式：SKILL.md
• 生成脚本实现：generate.js
• 全部 26 种图型规格：skills/public/chart-visualization/references/ 目录
• 技能目录发现机制测试：test_skill_catalog.py