DeerFlow chart-visualization 技能详解：generate_bar_chart 条形图工具的参数规范与生成实现

本篇指南聚焦 DeerFlow 内置 chart-visualization 技能中的条形图（bar chart）能力，完整解析 条形图参数规范 中定义的输入字段、默认值与返回结构，并结合 生成脚本 与 技能定义 讲清「从数据到图表图像 URL」的完整调用链。读完后你将掌握如何为 Top-N 排行、地区或渠道对比等场景正确构造条形图参数、理解分组与堆叠的互斥约束，以及脚本底层如何把参数映射为可视化请求。

一、条形图在 DeerFlow 图表技能中的定位

chart-visualization 是 DeerFlow 提供的公共技能，其 SKILL.md 描述了「数据 → 可视化图表」的完整工作流：智能选择图表类型、抽取参数、调用脚本生成图像、返回结果。在「对比（Comparisons）」这一类需求中，技能明确给出了选型指引：

• 横向比较不同类别的指标，使用 generate_bar_chart（横向条形）；
• 纵向比较不同类别或时间段，使用 generate_column_chart；
• 关注频率分布时，使用 generate_histogram_chart。

因此 generate_bar_chart 的核心场景是以横向条形比较不同类别或分组的指标表现，适合 Top-N 排行、不同地区或渠道对比。它与柱状图 generate_column_chart 的关键差异在于方向（横向 vs 纵向）以及分组/堆叠的默认值不同——这直接影响参数如何书写。

二、输入字段规范：必填与可选参数

以下内容直接继承自 条形图参数规范，并结合字段语义做了说明，可直接作为构造 args 的依据。

2.1 必填字段

• data: array<object>，数据主体。每条记录至少包含：
  • category（string）：类别名称，对应条形图的一个维度（如地区、渠道、产品名称）；
  • value（number）：该类别的指标数值；
  • 若需要分组或堆叠，还需额外提供 group（string），用于区分同一条形上的不同系列。

2.2 可选字段与默认值

参数	类型	默认值	说明
group	boolean	false	启用后以并排形式展示不同 group。要求 stack=false 且数据含 group 字段
stack	boolean	true	启用后把不同 group 堆叠在同一条形上。要求 group=false 且数据含 group 字段
style.backgroundColor	string	—	自定义背景色（如 #fff）
style.palette	string[]	—	设置系列颜色列表
style.texture	string	default	可选 default / rough
theme	string	default	可选 default / academy / dark
width	number	600	图表宽度
height	number	400	图表高度
title	string	""	图表标题
axisXTitle	string	""	X 轴标题
axisYTitle	string	""	Y 轴标题

2.3 分组与堆叠的互斥约束

group 与 stack 二者互斥，这是构造参数时最容易出错的地方：

• 使用分组（并排）：设 group=true，同时必须 stack=false，且每条数据都要带 group 字段；
• 使用堆叠：设 stack=true（默认即 true），同时必须 group=false，且每条数据都要带 group 字段；
• 不需要多系列时：保持 group=false 即可，data 中无需 group 字段。

注意条形图与柱状图的默认值差异：条形图 group 默认 false、stack 默认 true；而柱状图 generate_column_chart 中 group 默认 true、stack 默认 false。从源码结构看，这决定了在两种图表中「不写分组参数」时的默认行为完全不同，跨图表迁移参数时要特别留意。

三、调用方式：脚本执行与 Payload 结构

SKILL.md 定义了统一的工作流：选定图表类型后读取对应的 references/ 规格文件，把用户数据映射到 args，然后调用脚本生成图像。

3.1 执行命令

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

3.2 Payload 格式

{
  "tool": "generate_bar_chart",
  "args": {
    "data": [
      { "category": "华东", "value": 120 },
      { "category": "华北", "value": 98 },
      { "category": "华南", "value": 76 }
    ],
    "title": "各区域销售对比",
    "theme": "default",
    "style": { "texture": "default" }
  }
}

其中 tool 字段取值 generate_bar_chart，args 即上节所述的输入字段。

四、脚本底层实现：参数如何变成图像 URL

结合 generate.js，可以看清 generate_bar_chart 在运行时的完整链路。

4.1 图表类型映射

脚本内维护了一张工具名到图表类型的映射表 CHART_TYPE_MAP，其中 generate_bar_chart 被映射为 "bar"：

const CHART_TYPE_MAP = {
  ...
  generate_bar_chart: "bar",
  ...
};

脚本在 main() 中通过 const chartType = CHART_TYPE_MAP[tool] 取出类型；若 tool 不在表中（如拼写错误），会打印 Error: Unknown tool '${tool}' 并跳过。这说明 tool 字段必须严格匹配映射表的键，否则请求不会发出。

4.2 请求地址与服务标识

function getVisRequestServer() {
  return (
    process.env.VIS_REQUEST_SERVER ||
    "https://antv-studio.alipay.com/api/gpt-vis"
  );
}

从源码结构看，可视化请求的目标服务器可通过环境变量 VIS_REQUEST_SERVER 覆盖，未设置时使用脚本内的默认地址。这意味着在需要接入私有或内网可视化服务时，可通过该环境变量切换，而无需改动代码。

4.3 请求体构造与结果返回

非地图类图表（条形图属于此类）走 generateChartUrl：

async function generateChartUrl(chartType, options) {
  const url = getVisRequestServer();
  const payload = {
    type: chartType,                       // "bar"
    source: "chart-visualization-creator",
    ...options,                            // 展开的 args
  };
  const data = await httpPost(url, payload);
  if (!data.success) {
    throw new Error(data.errorMessage || "Unknown error");
  }
  return data.resultObj;
}

关键点：

• type 取映射后的 "bar"，args 被原样展开并入请求体；
• source 固定为 chart-visualization-creator，作为请求来源标识；
• 响应体若 success 为假，抛出 errorMessage；成功时返回 resultObj，即生成的图表图像 URL。

4.4 入参解析：支持 JSON 字符串与文件路径

main() 的入参解析逻辑值得注意——它先判断参数是否为存在的文件路径，是则读文件并 JSON.parse，否则直接按字符串解析：

const specArg = process.argv[2];
if (fs.existsSync(specArg)) {
  spec = JSON.parse(fs.readFileSync(specArg, "utf-8"));
} else {
  spec = JSON.parse(specArg);
}

这意味着 node ./scripts/generate.js '<payload_json>' 与 node ./scripts/generate.js ./bar_chart.json 两种写法等价，后者更适合把较长的参数写入文件后再执行。此外，脚本还支持传入一个 JSON 数组进行批量生成（const specs = Array.isArray(spec) ? spec : [spec];），并对每个元素独立处理，单个失败不影响其余条目。

4.5 运行环境要求

SKILL.md 的 frontmatter 声明了 compatibility.nodejs: ">=18.0.0"，因为脚本使用了 fetch 等特性，故运行环境需 Node.js 18 及以上版本。

五、返回结果

根据 条形图参数规范 的「返回结果」一节：

• 脚本输出条形图图像 URL（对应 generateChartUrl 返回的 resultObj，经 console.log 打印到标准输出）；
• 同时应在 _meta.spec 中给出完整配置以便复用。

SKILL.md 的「Result Return」步骤也强调：返回给用户时，除图像 URL 外，还应附上用于生成的完整 args（即 spec），方便下游复现或微调。

六、使用建议与可运行示例

条形图参数规范 给出的使用建议是：类别名称保持简短；若系列数较多可改用堆叠或筛选重点项目，以免图表拥挤。 结合源码，可以补充如下实操要点：

1. 多类别且需对比：类别数量较多时，优先保证 category 名称简短；需要对比多个系列时，按 2.3 节的互斥约束正确设置 group / stack。
2. 避免拥挤：当系列或类别过多时，改用堆叠（stack=true、group=false）或只保留重点类别（Top-N）。
3. 配色与主题：需要统一品牌色时，用 style.palette 指定系列颜色列表；需要深色或论文风格时，分别设置 theme 为 dark 或 academy。
4. 尺寸与标题：width / height 默认 600 / 400，可按展示场景调整；title、axisXTitle、axisYTitle 用于补充语义信息。

下面给出一个可直接执行的分组条形图示例（并排对比），注意 group=true 且 stack=false：

{
  "tool": "generate_bar_chart",
  "args": {
    "data": [
      { "category": "A 产品", "value": 120, "group": "线上" },
      { "category": "A 产品", "value": 80,  "group": "线下" },
      { "category": "B 产品", "value": 95,  "group": "线上" },
      { "category": "B 产品", "value": 60,  "group": "线下" }
    ],
    "group": true,
    "stack": false,
    "title": "A/B 产品线上线下销量对比",
    "axisXTitle": "销量",
    "axisYTitle": "产品",
    "theme": "default",
    "width": 700,
    "height": 400
  }
}

七、技能在 DeerFlow 中的加载与检索

chart-visualization 作为内置公共技能，其目录结构位于 skills/public/chart-visualization，包含 SKILL.md、scripts/generate.js 以及 references/ 下 26 个图表类型的规格文档。在前端文档 skills.mdx 的内置技能表中，chart-visualization 被描述为「从数据创建图表和可视化」。

从源码结构看，技能目录会被 skills/loader.py 的 load_skills() 扫描，parser.py 解析 SKILL.md 提取元数据，security_scanner.py 在加载前检查危险模式。技能目录可按名称被检索命中：后端测试 test_skill_catalog.py 中即验证了用关键词 chart 搜索时，chart-visualization 会因名称匹配而排在首位（catalog.search("chart") 的首个结果 name 为 chart-visualization），说明该技能在技能目录检索中具有良好的可发现性。

小结

generate_bar_chart 是 DeerFlow chart-visualization 技能中专用于横向类别对比的工具，其参数规范、默认值与分组/堆叠互斥约束都明确记录在 条形图参数规范 中。理解这套规范后，再配合 generate.js 中的 CHART_TYPE_MAP、请求地址解析与 generateChartUrl 调用链，即可完整掌握从「构造 args」到「拿到图表图像 URL」的全过程，并能在 Top-N 排行、地区/渠道对比等场景下正确、可复现地生成条形图。