DeerFlow 漏斗图生成实战：chart-visualization 技能中 generate_funnel_chart 的参数规范与底层调用链

本篇围绕 DeerFlow 内置 chart-visualization 技能中的漏斗图（generate_funnel_chart）展开，讲清它的适用场景、完整输入字段规范、可复制的调用命令，以及底层 generate.js 的映射与 HTTP 请求实现。读完你可以独立完成多阶段转化/流失数据的可视化配置，并理解参数是如何从 JSON payload 一路传递到渲染服务的。

漏斗图解决什么问题

漏斗图（funnel chart）用于展示多阶段转化或流失情况，是销售管道（lead → 商机 → 成交）、用户旅程（访问 → 注册 → 激活 → 付费）等逐步筛选过程的典型表达。在 DeerFlow 的 26 种图表工具中，SKILL.md 将其归类为 Specialized 场景：

• generate_radar_chart：多维对比；
• generate_funnel_chart：流程阶段（Process stages）；
• generate_liquid_chart：百分比/进度；
• 其余包括词云、箱线图、网络图、鱼骨图、流程图、表格视图等。

也就是说，当你手上的数据是“一串有先后顺序的阶段 + 每阶段的量级”，漏斗图就是技能智能选型时的首选。

技能工作流：选型 → 抽参 → 生成 → 回传

理解单个图表前，先看它在技能工作流中的位置。SKILL.md 定义的完整流程为：

1. 智能选型：根据数据特征选择 26 种图表之一，细则见 references/ 目录；
2. 参数抽取：读取对应的 references/generate_xxx.md 规格文件（漏斗图即 generate_funnel_chart.md），把用户数据映射为 args；
3. 生成：以 JSON payload 调用 scripts/generate.js；
4. 回传：返回图表图片 URL 与完整的 args 规格，方便复用。

Payload 的标准结构是：

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

执行命令（要求 Node.js ≥ 18，见 SKILL.md frontmatter 的 compatibility 声明）：

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

输入字段规范：必填与可选

以下是漏斗图的完整参数规范，直接继承自 generate_funnel_chart.md，并结合其他图表规格做了字段对照。

必填字段

字段	类型	说明
data	array	需按流程顺序排列，每条包含 category（string，阶段名称）与 value（number，该阶段的量级）

顺序是漏斗图的语义核心：渲染端按数组下标自上而下绘制层级，若数据未按实际流程排序，漏斗会呈现错误的转化叙事。

可选字段

字段	类型	默认值	说明
style.backgroundColor	string	无	设置图表背景色
style.palette	string[]	无	定义各阶段颜色，按 data 顺序取色
style.texture	string	default	可选 default / rough（粗糙手绘质感）
theme	string	default	可选 default / academy / dark
width	number	600	图表宽度
height	number	400	图表高度
title	string	空字符串	图表标题

这些可选字段的语义在技能内其他图表规格中是一致的（例如 generate_bar_chart.md 中 theme、style.texture、width/height 的默认值与取值完全相同），意味着它们是一套跨图表的统一渲染约定，配置经验可以横向迁移。

可复制的完整示例

以“电商用户转化”为例，一个可以直接运行的 payload：

{
  "tool": "generate_funnel_chart",
  "args": {
    "title": "电商用户转化漏斗（本月）",
    "theme": "default",
    "width": 600,
    "height": 400,
    "style": {
      "palette": ["#5B8FF9", "#5AD8A6", "#5D7092"]
    },
    "data": [
      { "category": "访问", "value": 52000 },
      { "category": "注册", "value": 18400 },
      { "category": "首次付费", "value": 4300 }
    ]
  }
}

执行：

node ./scripts/generate.js '{"tool":"generate_funnel_chart","args":{"title":"电商用户转化漏斗（本月）","data":[{"category":"访问","value":52000},{"category":"注册","value":18400},{"category":"首次付费","value":4300}]}}'

底层调用链：generate.js 是如何处理漏斗图的

结合 generate.js 的源码，可以看到从命令到渲染服务的完整链路：

1. 工具名映射（generate.js）：CHART_TYPE_MAP 把 26 个工具名映射为渲染端类型名，漏斗图对应 generate_funnel_chart: "funnel"。脚本对未知工具名会打印 Unknown tool 并跳过，不会中断批处理。

2. spec 解析（generate.js）：第一个参数既可以是内联 JSON 字符串，也可以是一个存在的 JSON 文件路径（fs.existsSync 判断）；若传入的是数组则按批处理，逐个 spec 依次生成，单个失败不影响其他项。

3. HTTP 请求（generate.js）：generateChartUrl 将 args 与 type: "funnel"、source: "chart-visualization-creator" 合并为 payload，POST 到渲染服务；服务端返回 success: false 时抛出 errorMessage，成功则返回 resultObj。

4. 服务端点可配置（generate.js）：

   • VIS_REQUEST_SERVER 环境变量可覆盖默认的 gpt-vis 渲染端点；
   • SERVICE_ID 环境变量仅对地图类工具（generate_district_map / generate_pin_map / generate_path_map）走 generateMap 分支时使用，漏斗图不经过该分支。

   因此默认配置下漏斗图生成依赖外网渲染服务，这是当前实现的适用前提；如需私有化或离线使用，从源码结构看需要通过 VIS_REQUEST_SERVER 指向自建端点。

5. 输出：非地图类图表直接在 stdout 打印图片 URL（generate.js），脚本对错误采取“打印到 stderr 并继续”的容错策略。

使用建议：数据口径与阶段数量

原文档给出的三条实操建议值得展开：

• 阶段顺序按实际流程排列：漏斗图无坐标轴，读者唯一的空间参照就是“从上到下”，乱序数据会直接产生错误结论；
• 百分比需统一口径：若 value 填的是转化率而非绝对量，所有阶段必须相对同一基准（通常是首阶段），且应在 title 或备注中写明口径，否则读者无法区分“5% 的流失”与“5% 的留存”；
• 阶段数建议 ≤ 6：层级过多时每层宽度差异变小，阅读难度陡增。若业务流程确实很长，建议先合并低量级尾部阶段再绘图。

返回结果与复用

脚本成功执行后，stdout 输出漏斗图图片 URL。按技能工作流的约定，回传给用户时还应附上完整的 args（即规格 spec），渲染端同时会在 _meta.spec 中给出完整配置——这使图表在 DeerFlow 会话中可以被精确复现与微调：修改 palette、更换 theme 或增删阶段后，用同一 payload 结构再次调用即可，无需重新组织数据。

在 DeerFlow 中如何被加载

漏斗图不是独立工具，而是 chart-visualization 技能包的一部分。该技能位于 skills/public/chart-visualization/，由 skills/public/ 下的技能加载体系发现：SKILL.md 的 frontmatter（name、description、nodejs 兼容性声明）由后端技能解析器读取，例如 parser.py 中的 parse_skill_file 负责从 SKILL.md 提取名称、描述与指令。技能目录（含 references/ 规格文档与 scripts/generate.js）作为整体挂载给 Agent，Agent 在运行时按需查阅具体图表的 reference 文档来组织 args，这正是“26 份规格文件 + 1 份统一脚本”这种组织方式的价值所在——单一入口脚本，规格文档按需引用，避免上下文膨胀。

技能目录的测试覆盖可见 test_skill_catalog.py，其中 chart-visualization 作为内置技能参与目录构建与名称模糊匹配（如输入 "chart" 可命中该技能）。

小结

• 漏斗图输入极简：一个按流程顺序排列的 data 数组（category + value），其余 style / theme / width / height / title 均为有默认值的可选项；
• 调用方式统一：node ./scripts/generate.js '<payload_json>'，支持内联 JSON 或 JSON 文件、支持数组批量生成；
• 底层实现是工具名到渲染类型的映射加一次带固定 source 标识的 HTTP POST，服务端点可用 VIS_REQUEST_SERVER 覆盖；
• 返回图片 URL 与 _meta.spec，配合完整的 args 回传即可实现图表的精确复现与迭代调整。

掌握这套参数规范后，你可以把销售管道、用户旅程等任何多阶段筛选数据快速转化为可分享的漏斗图，并与 DeerFlow 会话中的其他 25 种图表共享同一套调用约定。