DeerFlow chart-visualization 技能实战：generate_column_chart 柱状图从字段契约到生成链路

2026-09-06 15:08:35作者：胡唯隽

An open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.

项目地址：https://gitcode.com/GitHub_Trending/de/deer-flow

本文基于 DeerFlow 仓库中 generate_column_chart.md 参考文档展开，完整解析柱状图工具的输入字段契约（含分组/堆叠互斥规则）、可选样式参数与默认值，并结合 SKILL.md 工作流和 generate.js 脚本源码，讲清楚一次柱状图生成的完整调用链、Payload 格式与运行环境前提。读完本篇，你可以直接组装合法的 JSON Payload 调用该图表工具，并理解参数在底层是如何被映射、校验并发送到可视化服务的。

一、在 chart-visualization 技能中的位置

generate_column_chart 是 DeerFlow 内置公共技能 chart-visualization 提供的 26 种图表工具之一。该技能的整体工作流定义在 SKILL.md 中，分为四步：

智能选图：根据数据特征选择图表类型。在对比类场景中，generate_column_chart 与 generate_bar_chart 并列——前者为纵向柱状图，适合"销量、营收、客流"等类别/时间指标对比；后者为横向条形图，更适合 Top-N 排行。
参数提取：选中 generate_column_chart 后，读取 references/generate_column_chart.md（即本文档），将用户数据映射到 args 格式。
图表生成：调用 scripts/generate.js，执行命令为：
```
node ./scripts/generate.js '<payload_json>'
```
结果返回：脚本输出图表图片 URL，同时需要把完整 args（即生成所用的规格）一并返回给用户。

每种图表的字段契约独立存放在 references/ 目录下（如 generate_line_chart.md、generate_pie_chart.md），generate_column_chart.md 正是柱状图这一份契约。前端文档 skills.mdx 也将 chart-visualization 列为 DeerFlow 内置公共技能，描述为"从数据创建图表和可视化"。

二、柱状图功能概述

generate_column_chart 以纵向柱状形式对比不同类别或时间段的指标，支持两种组织方式：

分组（grouped）：同一类别下不同系列的柱子并排展示；
堆叠（stacked）：同一类别下不同系列的值叠加到同一根柱子上。

典型应用场景是各类销售数据、营收、客流等"类别 × 数值（× 系列）"结构的对比分析。

三、输入字段完整契约

必填字段

data: array<object>，每条记录至少包含：
- category（string）：类别名，落在 X 轴上；
- value（number）：指标数值；
- 如需分组或堆叠，还需补充 group（string）：系列名。

可选字段

字段	类型	默认值	说明
`group`	boolean	`true`	按系列并排展示不同 `group`。开启时需确保 `stack=false` 且数据中包含 `group` 字段
`stack`	boolean	`false`	将不同 `group` 堆叠到同一柱子。开启时需确保 `group=false` 且数据中包含 `group` 字段
`style.backgroundColor`	string	—	自定义背景色
`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 轴标题

分组与堆叠的互斥规则

group 与 stack 存在明确的互斥约束，这是调用时最容易踩坑的地方：

二者不能同时为 true：并排与堆叠是两种互斥的系列组织方式；
任一模式开启时，data 中每条记录都必须携带 group 字段，否则会因字段缺失导致校验失败。这一点在文档"使用建议"中也再次强调："堆叠模式要确保各记录都含 group 字段以免校验失败"。
单系列场景（只有 category + value）则不需要提供 group/stack。

对比参照：横向条形图 generate_bar_chart.md 的默认值恰好相反（group 默认 false、stack 默认 true），但互斥约束逻辑一致。

四、使用建议

类别过多时做收敛：当类别数量较多（>12）时，建议先按 Top-N 或聚合处理再作图，避免柱子过密难以辨识；
堆叠模式检查 group 字段：所有记录统一携带 group，防止个别记录缺失导致整图校验失败。

五、返回结果

生成成功后返回柱状图图片 URL；
同时随 _meta.spec 提供完整配置详情，便于复现或二次调整（与 SKILL.md 第 4 步"返回图像 URL + 完整 args"的要求一致）。

六、从源码看生成链路：generate.js 如何执行这个工具

generate.js 是整个技能的执行入口，阅读源码可以确认 generate_column_chart 的底层行为：

1. 工具名到图表类型的映射

脚本内维护 CHART_TYPE_MAP，将 26 个 tool 名映射为服务端的 type 值，柱状图对应：

generate_column_chart: "column",

若传入的 tool 不在映射表中，脚本会打印 Error: Unknown tool '<tool>' 并跳过该条目（不中断批量任务）。

2. 服务地址与环境变量

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

默认请求可视化服务 antv-studio.alipay.com/api/gpt-vis；
可通过环境变量 VIS_REQUEST_SERVER 覆盖服务地址（便于接入自托管可视化后端）；
脚本对非 2xx 响应会抛出 HTTP <status>: <body>，对响应体中 success=false 会抛出 errorMessage。

3. 请求体组装

对柱状图这类非地图工具，走 generateChartUrl(chartType, options)，实际 POST 的 Payload 为：

{
  type: "column",                       // 由 CHART_TYPE_MAP 映射而来
  source: "chart-visualization-creator",
  ...options                            // 即 args：data / group / stack / style / theme / width / height / title ...
}

成功时返回 data.resultObj（即图片 URL），由 console.log(url) 打印到 stdout。

4. 输入形态与批量能力

main() 支持两种输入方式：

内联 JSON：node ./scripts/generate.js '<payload_json>'；
JSON 文件：参数为已存在的文件路径时，直接读取文件内容解析。

且若顶层 JSON 是数组，会逐项生成（批量出图）。单个条目的结构即 SKILL.md 定义的 Payload 格式：

{
  "tool": "generate_column_chart",
  "args": {
    "data": [...],
    "title": "...",
    "theme": "default",
    "style": { }
  }
}

七、可复制的实操示例

以"华东/华南/华北三个区域 2024 年 Q1、Q2 营收对比"为例，堆叠模式 Payload（注意每条记录都带 group，且 group=false 与 stack=true）：

node ./scripts/generate.js '{
  "tool": "generate_column_chart",
  "args": {
    "data": [
      { "category": "Q1", "group": "华东", "value": 1200 },
      { "category": "Q1", "group": "华南", "value": 980 },
      { "category": "Q2", "group": "华东", "value": 1350 },
      { "category": "Q2", "group": "华南", "value": 1120 }
    ],
    "group": false,
    "stack": true,
    "title": "各区域季度营收对比（堆叠）",
    "axisXTitle": "季度",
    "axisYTitle": "营收（万元）",
    "theme": "default",
    "width": 600,
    "height": 400,
    "style": { "backgroundColor": "#fff", "texture": "default" }
  }
}'

改为分组（并排）展示时，只需将 "group": true, "stack": false，其余不变。脚本成功时会输出一行图片 URL。

八、运行环境与前提

Node.js 版本：SKILL.md 的 frontmatter 声明 compatibility.nodejs: ">=18.0.0"。脚本使用了全局 fetch，因此 Node 18+ 是硬性前提；
网络可达性：默认依赖远端可视化服务，离线环境需通过 VIS_REQUEST_SERVER 指向可用服务；
技能启用状态：在 DeerFlow 中，chart-visualization 作为内置公共技能位于 skills/public/ 下，其可用性由 extensions_config.json 跟踪，可通过应用界面、Gateway API（POST /api/extensions/skills/{name}/enable 与 /disable）或直接编辑该文件切换；由于 load_skills() 每次调用都会重新读取扩展配置，改动即时生效（详见 skills.mdx）。

九、小结与延伸阅读

generate_column_chart 的契约可以概括为三句话：data 必填且每条含 category/value；系列对比时补充 group 字段，并用 group/stack 二选一控制并排或堆叠；其余 style、theme、尺寸与标题均为有默认值的可选项。它通过 references/ 下的字段文档约束参数提取，再由 scripts/generate.js 将 tool 映射为 column 类型并 POST 到可视化服务，最终以图片 URL + _meta.spec 的形式返回。