DeerFlow 可视化技能中的 generate_pie_chart：饼图/环图参数规范与生成链路解析

generate_pie_chart 是 DeerFlow 内置 chart-visualization 技能中负责"部分与整体"占比展示的图表工具，适用于市场份额、预算构成、用户群划分等场景。本文基于技能自带的参考文档 generate_pie_chart.md，完整梳理其输入字段、默认值与使用建议，并结合 SKILL.md 的工作流定义与 generate.js 的源码实现，说明从 JSON payload 到图表 URL 的完整生成链路，以及该技能在 DeerFlow 中的加载与调用方式。

一、工具定位与适用场景

generate_pie_chart 用于展示整体与部分的占比关系，可通过设置内径形成环图（donut chart）。典型适用场景：

• 市场份额构成（各厂商占比）；
• 预算构成（各部门/科目金额占比）；
• 用户群划分（年龄、地域等维度的人群占比）。

在技能的主入口 SKILL.md 中，图表选择指南将 generate_pie_chart 归入 Part-to-Whole（部分与整体） 类别，与层次化的 generate_treemap_chart（矩形树图）并列。也就是说：数据表达"各部分加起来等于一个整体"时优先选饼图；若层级结构较深（如"国家→省→城市"的多级占比），则更适合树图。

该技能共提供 26 种图表类型，generate_pie_chart 是其中的占比类基础工具之一。

二、输入字段规范

2.1 必填字段

• data：array<object>，每条记录包含两个字段：
  • category（string）：扇区类别名称；
  • value（number）：该类别对应的数值。

示例（市场份额数据）：

[
  { "category": "厂商A", "value": 38.5 },
  { "category": "厂商B", "value": 24.0 },
  { "category": "厂商C", "value": 18.2 },
  { "category": "其它",   "value": 19.3 }
]

2.2 可选字段与默认值

参考文档列出的可选参数如下，均可省略、使用默认值：

字段	类型	默认值	说明
innerRadius	number	0	取值范围 [0, 1]；设为 0 为标准饼图，设为 0.6 等值则生成中间带空洞的环图
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	空字符串	图表标题

这些参数中，innerRadius 是区分饼图与环图的关键：同一份 data，仅改变 innerRadius 即可在实心饼图（0）与环图（如 0.6）之间切换，无需改动数据。

2.3 使用建议

参考文档给出两条实操建议：

1. 类别数量建议 ≤ 6。若类别过多，应将尾部小项聚合为"其它"，避免扇区过窄、图例冗长；
2. 确保数值单位统一（全部为百分比或全部为绝对值），必要时在 title 中说明基数（例如"2025 年 Q3 各产品线营收占比（单位：百万元）"），防止读者误解占比含义。

三、完整调用示例

按 SKILL.md 定义的工作流，生成图表分三步：选择图表类型 → 按参考文档提取参数 → 以 JSON payload 调用脚本。

3.1 Payload 格式

技能约定的 payload 结构为：

{
  "tool": "generate_pie_chart",
  "args": {
    "data": [
      { "category": "厂商A", "value": 38.5 },
      { "category": "厂商B", "value": 24.0 },
      { "category": "厂商C", "value": 18.2 },
      { "category": "其它", "value": 19.3 }
    ],
    "title": "2025 年 Q3 智能手机市场份额",
    "innerRadius": 0.6,
    "theme": "default",
    "width": 600,
    "height": 400,
    "style": { "backgroundColor": "#fff" }
  }
}

3.2 执行命令

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

其中 <payload_json> 为上面 payload 的 JSON 字符串。脚本要求 Node.js >= 18.0.0（见 SKILL.md 的 frontmatter compatibility 声明）。

四、源码级生成链路

从 generate.js 的实现看，generate_pie_chart 的执行路径如下：

4.1 工具名到图表类型的映射

脚本内维护了 CHART_TYPE_MAP（generate.js），其中 generate_pie_chart 映射为 "pie"：

const CHART_TYPE_MAP = {
  ...
  generate_pie_chart: "pie",
  ...
};

main() 先解析第一个命令行参数——既可以直接是 JSON 字符串，也可以是存在的 JSON 文件路径（脚本通过 fs.existsSync(specArg) 区分两者，见 generate.js）。若传入的是数组，则逐条处理多个 spec。

4.2 远端渲染服务与请求体

解析后，非地图类工具（饼图属于此类）走 generateChartUrl() 分支（generate.js）：

const payload = {
  type: chartType,          // "pie"
  source: "chart-visualization-creator",
  ...options                // 即 args 全量展开：data/title/innerRadius/style...
};

请求发往 getVisRequestServer() 返回的服务地址：优先读取环境变量 VIS_REQUEST_SERVER，未设置时回退到默认的 gpt-vis 渲染接口。响应成功时，脚本将 data.resultObj 打印到标准输出——这正是技能工作流第 4 步"返回图表图像 URL"的来源；若响应 success 为 false，则抛出 errorMessage 并在 stderr 输出 Error generating chart for generate_pie_chart: <原因>。

从源码结构看，饼图的扇区角度计算、配色与主题渲染都发生在远端渲染服务中，本地脚本只负责组装 type + args 并透传结果，这也解释了为什么参考文档中 theme、style.texture 等外观参数只需按字符串/数组传入即可。

4.3 返回结果

按参考文档说明，成功后返回饼/环图 URL，并附 _meta.spec（完整生成规格，便于复用与审计）。SKILL.md 要求最终回复用户两样内容：图像 URL 与本次使用的完整 args（即 spec）。对于 generate.js，单图场景下 stdout 直接就是 URL 字符串，失败信息走 stderr，便于在 Agent 的 shell 工具中捕获与判错。

五、在 DeerFlow 技能体系中的位置

chart-visualization 是 DeerFlow 的内置公共技能之一，官方文档 skills.mdx 将其描述为"从数据创建图表和可视化"，并给出完整生命周期：

1. 发现和加载：skills/loader.py 的 load_skills() 扫描 skills/public/ 与 skills/custom/，每次调用都重新读取扩展配置，通过 Gateway API 启用/禁用技能可即时生效、无需重启；
2. 解析：parser.py 从 SKILL.md 提取名称、描述、类别与指令（frontmatter 中 description 即为触发该技能的语义依据——"当用户想可视化数据时使用"）；
3. 安全扫描：security_scanner.py 在内容注入 Agent 上下文前检查危险模式；
4. 上下文注入：当 Agent 在该技能范围内被调用时，技能工作流（含"选择图表类型 → 查阅 references/ 对应文档提取参数 → 调用 scripts/generate.js"这三步）被注入系统提示。

目录中的 references/ 存放 26 份图表规格文档（本文主角 generate_pie_chart.md 即是其一），scripts/generate.js 为统一执行入口。文档中 references/generate_pie_chart.md 这类相对于技能目录的路径，在仓库内对应全局路径 skills/public/chart-visualization/references/generate_pie_chart.md。

技能可用性由 extensions_config.json 跟踪，可通过应用界面、Gateway API（POST /api/extensions/skills/{name}/enable 与 /disable）或直接编辑该文件管理；技能根目录则配置在 config.yaml 的 skills: 段（含沙箱内挂载路径 container_path，默认 /mnt/skills）。此外，Agent 配置可以 skills 白名单方式将某个自定义 Agent 限定为只加载 chart-visualization 等特定技能子集，官方前端文档 agents-and-threads.mdx 中就给出了 "skills": ["data-analysis", "chart-visualization"] 的组合示例——数据分析与图表可视化搭配使用是该技能的典型落地方式。

技能目录本身也有测试覆盖：test_skill_catalog.py 验证了 chart-visualization 能被技能目录发现，且按名称模糊匹配（如输入 "chart"）可命中该技能。

六、参数速查与注意事项

• 饼图 vs 环图：仅由 innerRadius 决定，0 实心饼图、0.6 左右为常见环图，取值必须落在 [0, 1]；
• 类别数：> 6 时聚合"其它"；
• 单位一致性：百分比与绝对值不可混用，标题中注明基数；
• 配色与主题：style.palette 自定义扇区色序，theme 三选一（default/academy/dark），style.texture 可选 rough 质感；
• 画布尺寸：默认 600 x 400，需要大图或嵌入文档时可分别调 width/height；
• 运行前提：Node.js >= 18；远端渲染服务地址默认内置，可用环境变量 VIS_REQUEST_SERVER 覆盖（地图类工具另需 SERVICE_ID，饼图不涉及）；
• 失败诊断：脚本对每条 spec 单独捕获异常并输出 Error generating chart for generate_pie_chart: <message>，多条 spec 时一条失败不影响其余条目继续执行。

小结

generate_pie_chart 的参考文档虽短，但完整定义了该工具"何时用、传什么、怎么调、返回什么"四个维度：以 data 中 category/value 对为核心，innerRadius 切换饼图与环图，theme/style/width/height/title 控制外观；配合 SKILL.md 的三步工作流与 generate.js 的 pie 类型映射，即可在 DeerFlow Agent 中以一条 node ./scripts/generate.js '<payload_json>' 命令完成占比类图表的生成，并把图像 URL 与完整 spec 返还给用户复用。