DeerFlow chart-visualization 技能实战：用 generate_treemap_chart 生成矩形树图

DeerFlow 内置的 chart-visualization 技能 提供 26 种图表生成能力，其中 generate_treemap_chart 用于以嵌套矩形展示层级结构及各节点权重，适合资产占比、市场份额、目录容量等"整体—部分"且具有层次关系的场景。读完本文，你将掌握矩形树图数据的构造规范、完整参数说明、通过 scripts/generate.js 生成图表图像的调用方式，以及返回结果中 _meta.spec 的用途。

技能定位：什么时候选矩形树图

chart-visualization 技能的 SKILL.md 定义了标准工作流：智能选图 → 参数提取 → 调用脚本生成 → 返回结果。在选图环节，官方指引按数据特征分类推荐：

• 时间序列：generate_line_chart（趋势）或 generate_area_chart（累积趋势）；
• 对比类：generate_bar_chart（分类对比）或 generate_histogram_chart（频率分布）；
• 部分与整体（Part-to-Whole）：generate_pie_chart（单层占比）或 generate_treemap_chart（带层级结构的占比）；
• 关系与流向：generate_scatter_chart、generate_sankey_chart、generate_veen_chart 等。

矩形树图与饼图的关键区别在于：饼图只能表达单层占比，而矩形树图通过嵌套矩形同时表达层级结构与各节点权重。当数据本身是树形的（如"部门 → 项目 → 子项目"的预算分配、"盘 → 目录 → 子目录"的磁盘占用），或者占比类别过多、饼图已无法阅读时，矩形树图是更合适的选择。

输入字段规范：data 结构与可选参数

依据 generate_treemap_chart.md 的定义，参数分为必填与可选两组。

必填字段

• data：array<object>，节点数组。每条节点必须包含：
  • name（string）：节点名称，作为矩形内的标签展示；
  • value（number）：节点权重，决定矩形面积大小；
  • 可选 children（array）：递归嵌套子节点数组，用于表达层级结构。

可选字段

参数	类型	默认值	说明
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	空字符串	图表标题

这套可选参数与同目录下其他图表（如 generate_pie_chart.md）保持了一致的通用字段约定，便于在 26 种图表间迁移参数经验。

数据构造要点

参考文档的"使用建议"给出了三条硬性约束，构造 data 时必须遵守：

1. 每个节点 value 必须 ≥ 0：负数或零值节点没有合法的面积表达；
2. 父节点 value 必须与子节点 value 之和一致：否则面积比例与层级语义冲突，渲染结果会失真；
3. 树层级不宜过深：层级过深会导致底层矩形过小无法容纳标签，建议按需在调用前对数据做聚合（如把小额类别合并为"其它"）；
4. 可读性技巧：在节点名中带上数值单位（如"研发 120万"），避免读者跨图查表。

一个表达"公司资产占比"的典型树形数据如下（父节点值等于子节点之和）：

[
  {
    "name": "流动资产 60",
    "value": 60,
    "children": [
      { "name": "现金 25", "value": 25 },
      { "name": "应收账款 35", "value": 35 }
    ]
  },
  {
    "name": "固定资产 40",
    "value": 40,
    "children": [
      { "name": "厂房 28", "value": 28 },
      { "name": "设备 12", "value": 12 }
    ]
  }
]

调用方式：payload 格式与 generate.js 实现细节

标准 payload 与执行命令

chart-visualization 技能约定以 JSON payload 调用生成脚本（SKILL.md 第 40–59 行）：

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

执行命令：

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

其中 tool 固定为 generate_treemap_chart，args 即上一节定义的 data 与可选字段。

源码级实现：tool 如何映射为图表类型

从 scripts/generate.js 的源码结构看，调用链如下：

1. 工具名映射：脚本内部维护 CHART_TYPE_MAP（generate.js#L6-L32），generate_treemap_chart 被映射为远端渲染类型 treemap（generate.js#L28）。若传入未知 tool，脚本会打印 Error: Unknown tool '...' 并跳过该条目，而不是崩溃。
2. 参数透传：generateChartUrl()（generate.js#L62-L77）将 payload 组装为 { type: "treemap", source: "chart-visualization-creator", ...args } 后，以 POST JSON 发送到可视化渲染服务，服务返回的 resultObj（即图表图片 URL）打印到标准输出。
3. 渲染服务地址可配置：默认请求 https://antv-studio.alipay.com/api/gpt-vis，可通过环境变量 VIS_REQUEST_SERVER 覆盖（generate.js#L34-L39）；地图类工具额外需要 SERVICE_ID 环境变量，矩形树图属于普通图表，无需该变量。
4. 参数容错：脚本解析 JSON 失败时打印 Error parsing spec: ... 并以非零码退出；单个条目生成失败时打印 Error generating chart for generate_treemap_chart: ...，便于在 Agent 工作流中定位失败原因。

批量生成与文件输入两个实用特性

从 main() 的实现（generate.js#L97-L163）可以确认两个文档未强调、但实测可用的能力：

• 批量模式：spec 可以是数组，一次命令生成多张图。例如同时产出默认主题与暗色主题的两版矩形树图：

node ./scripts/generate.js '[
  {"tool":"generate_treemap_chart","args":{"data":[{"name":"A 60","value":60},{"name":"B 40","value":40}],"title":"资产占比"}},
  {"tool":"generate_treemap_chart","args":{"data":[{"name":"A 60","value":60},{"name":"B 40","value":40}],"theme":"dark"}}
]'

• 文件输入：第一个参数若是一个已存在的文件路径，脚本会读取该文件内容作为 JSON 解析（generate.js#L107-L112），适合 payload 较大、不便内嵌在命令行引号中的场景。

完整可复制示例

结合上文数据构造要点，一份可直接执行的完整命令（工作目录为技能根目录，要求 Node.js ≥ 18，与 SKILL.md 中 compatibility 声明一致）：

node ./scripts/generate.js '{
  "tool": "generate_treemap_chart",
  "args": {
    "data": [
      {"name": "流动资产 60", "value": 60,
       "children": [{"name": "现金 25", "value": 25},
                     {"name": "应收账款 35", "value": 35}]},
      {"name": "固定资产 40", "value": 40,
       "children": [{"name": "厂房 28", "value": 28},
                     {"name": "设备 12", "value": 12}]}
    ],
    "title": "公司资产占比（万元）",
    "theme": "default",
    "width": 800,
    "height": 500
  }
}'

返回结果：图片 URL 与 _meta.spec

生成成功后，脚本向标准输出打印矩形树图的图片 URL。按技能工作流第 4 步的要求，交付给用户的内容应包含两部分：

1. 图片 URL：可直接渲染的图表图像；
2. 完整 args（即 spec）：文档表述为"并同步 _meta.spec"，即随结果同步本次生成所用的完整参数规格。保留 spec 的价值在于可复现与可修正——当图表不满足预期（配色、尺寸、层级聚合方式）时，只需微调 spec 重新执行同一命令，无需从零重建数据。

小结

generate_treemap_chart 是 chart-visualization 技能中专门处理"层级占比"的图表工具：用 data 数组表达树形结构，父节点值等于子节点值之和是数据合法性的核心约束；通过 tool + args payload 调用 scripts/generate.js，由脚本将工具名映射为 treemap 类型并请求远端渲染服务，最终输出图片 URL 与 spec。配合 theme、style.palette 等通用样式参数和批量/文件输入能力，可以在 DeerFlow 的 Agent 工作流中稳定地产出高质量矩形树图。