DeerFlow chart-visualization 技能：generate_spreadsheet 电子表格与数据透视表规格详解

generate_spreadsheet 是 DeerFlow 内置 chart-visualization 技能中负责结构化数据呈现的工具规格：它既能渲染常规电子表格，也能通过 rows/values 字段自动升级为数据透视表（交叉表）。本文基于该规格文档，结合 skills/public/chart-visualization 下的技能工作流与 generate.js 生成脚本源码，完整讲解其输入字段、调用流程、返回约定以及源码中可验证的实现细节，帮助你在 Agent 会话或脚本中准确构造并复用表格类可视化规格。

一、定位：chart-visualization 技能中的表格类工具

generate_spreadsheet 的规格文档位于 generate_spreadsheet.md，它是 chart-visualization 技能 26 个图表参考文档之一。该技能的入口定义在 SKILL.md 中，声明了完整的数据可视化工作流：

1. 智能图表选型：根据数据特征选择图表类型。SKILL.md 的选型指引将 generate_spreadsheet 归入 Specialized（专用）类别，定义为 "Tabular data or pivot tables for structured data display and cross-tabulation"——即用于结构化数据的表格展示与交叉汇总；
2. 参数提取：选定类型后读取 references/ 目录下对应的规格文件（本文主题即 references/generate_spreadsheet.md），识别必填与可选字段，把用户数据映射为期望的 args 格式；
3. 图表生成：以 JSON payload 调用 generate.js 脚本；
4. 结果返回：把脚本输出的图片 URL 连同完整 args 一起返回给用户。

在 DeerFlow 中，chart-visualization 是随仓库内置的公共技能，位于 skills/public/ 下，由技能加载器扫描发现、按需注入 Agent 上下文，并在沙箱内通过配置的 container_path（默认 /mnt/skills）访问技能文件；技能启用/禁用状态由 extensions_config.json 与 Gateway API 管理（详见 技能文档）。此外，SKILL.md 的 License 一节声明该技能由 antvis/chart-visualization-skills 项目提供，采用 MIT 许可。

二、核心机制：常规表格与数据透视表的自动切换

规格文档定义了一条关键判定规则，决定同一份输入渲染出哪种形态：

当提供 rows 或 values 字段时，渲染为数据透视表（交叉表）；否则渲染为常规表格。

这条规则的实际意义在于：

• 常规表格：只做"行列直排"，适合展示明细数据、字段清单等一维记录集合；
• 数据透视表：通过 rows（行标题字段）、columns（列分组字段）、values（聚合值字段）三个维度把长表数据"交叉"成汇总表，适合做跨类别比较与数据汇总，例如"按地区 × 季度的销售额"。

因此在使用时应先判断目标：明细展示只传 data；需要交叉汇总时才引入 rows/values（以及可选的 columns 分组）。

三、输入字段规格

以下为规格文档定义的完整字段清单，可直接用于构造 args。

必填字段

字段	类型	说明
data	array<object>	表格数据数组，每个对象代表一行。键是列名，值可以是字符串、数字、null 或 undefined。文档示例：[{ name: 'John', age: 30 }, { name: 'Jane', age: 25 }]

data 是唯一必填项。每个对象的键名即列名，行的键可以不完全一致——缺失值以 null/undefined 表达，这与透视表聚合场景下部分单元格天然为空的特点相匹配。

可选字段

字段	类型	默认值	说明
rows	array<string>	—	数据透视表的行标题字段。提供 rows 或 values 之一即触发透视表模式
columns	array<string>	—	列标题字段。常规表格中决定列的显示顺序；透视表中用于列分组
values	array<string>	—	数据透视表的值字段。提供 rows 或 values 之一即触发透视表模式
theme	string	default	主题，可选 default/dark
width	number	600	渲染宽度
height	number	400	渲染高度

对比同目录下其他图表规格（如 generate_pie_chart.md 还提供 style.palette、style.texture、innerRadius 等样式字段），generate_spreadsheet 的可选项明显更精简：没有 title，没有 style 样式对象，只保留了主题与画布尺寸两项视觉控制。这符合表格类可视化的需求——表格的观感主要由数据本身决定，装饰性样式空间较小。

数据透视表的三字段配合

构造透视表时，三个字段的分工是固定的：

• rows：行分组维度，例如 ["region"]；
• columns：列分组维度，例如 ["quarter"]；
• values：参与聚合的数值字段，例如 ["revenue"]。

规格文档在使用建议中强调：确保 data 中的字段名与 rows、columns、values 中指定的字段名完全一致，否则分组与聚合无法命中。

四、调用流程与 payload 构造

按 SKILL.md 的工作流，调用分三步：提取参数、组装 payload、执行脚本。

1. Payload 格式

{
  "tool": "generate_spreadsheet",
  "args": {
    "data": [
      { "region": "华东", "quarter": "Q1", "revenue": 128 },
      { "region": "华东", "quarter": "Q2", "revenue": 142 },
      { "region": "华北", "quarter": "Q1", "revenue": 96 },
      { "region": "华北", "quarter": "Q2", "revenue": 110 }
    ],
    "rows": ["region"],
    "columns": ["quarter"],
    "values": ["revenue"],
    "theme": "default",
    "width": 600,
    "height": 400
  }
}

其中 tool 固定为 generate_spreadsheet；args 即上文第三节的字段集合。上面示例因同时提供 rows 与 values，将渲染为"地区 × 季度"的销售额透视表；若删去 rows、columns、values 三个字段，同样数据则渲染为四行两列信息的常规表格。

2. 执行命令

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

scripts/ 目录相对于技能目录 skills/public/chart-visualization/ 解析，即实际执行 generate.js。SKILL.md 的 frontmatter 声明运行环境要求 nodejs: ">=18.0.0"（脚本使用了全局 fetch）。

从源码看，main() 对参数解析做了双路兼容：先用 fs.existsSync(specArg) 判断第一个参数是否为已存在的文件路径，是则按文件读取并 JSON.parse，否则直接把参数当作 JSON 字符串解析（见 参数解析段）。也就是说 spec 既可以内联在命令行里，也可以写入 JSON 文件后把路径传给脚本，后者更利于保存与复用。此外，spec 若是数组（L118）会被展开为列表，逐项生成并逐行打印结果，支持一次批量生成多张图表。

3. 请求链路与可配置端点

脚本内部对非地图类工具（generate_spreadsheet 即属此类）走 generateChartUrl() 分支（L62-L77）：把 args 与 type（图表类型映射值）、source: "chart-visualization-creator" 合并为请求体，POST 到可视化服务端点，成功时取 data.resultObj 打印到标准输出。端点与标识通过两个环境变量配置，可在源码中确认：

• VIS_REQUEST_SERVER：覆盖请求端点，未设置时使用默认的 antv-studio gpt-vis 服务地址（见 getVisRequestServer()）；
• SERVICE_ID：服务标识，仅在地图类工具（generate_district_map/generate_path_map/generate_pin_map 的 generateMap 分支）中随 payload 发送，对 generate_spreadsheet 无影响（见 getServiceIdentifier()）。

错误处理也值得注意：httpPost() 对非 2xx 响应抛出带状态码与响应文本的异常（L45-L60）；服务端返回 success: false 时抛出 errorMessage；单个 spec 生成失败只打印错误并继续处理后续项，不会中断整批任务（L143-L161）。

4. 工具注册与调用前提（源码可验证的差异）

需要说明一个从源码结构中可确认的细节：generate.js 的 CHART_TYPE_MAP 注册了 25 个图表类型（area、bar、pie、scatter 等），未包含 generate_spreadsheet。main() 中若 tool 查不到映射会进入 Error: Unknown tool 分支（L131-L135）。这意味着在仓库当前版本下，直接把 generate_spreadsheet 的 payload 交给本地 generate.js 执行会命中该错误分支——该工具的规格文档与本地脚本的工具注册表并不完全同步。可以推断，电子表格渲染预期经由远端 gpt-vis 服务通道以 type + args 形式处理，具体可用性需在真实运行环境中验证；本文档规格仍然完整给出了 args 的构造标准，这也是 Agent 侧提取参数所依赖的契约。

五、返回结果约定

规格文档对返回结果的定义是：返回电子表格/数据透视表图片 URL，并附 _meta.spec 供后续编辑。

结合 SKILL.md 第 4 步"Result Return"可以完整理解这个约定：Agent 需要把（1）生成的图片 URL 与（2）完整的 args（即规格）一并返回给用户。_meta.spec 保留完整输入规格的价值在于可复现与可迭代——后续要修改列顺序、更换分组维度或切换主题时，只需在已有 spec 上调整 columns/rows/values/theme 等字段重新提交，而不必从零重建数据。这也是该技能全部 26 份 reference 文档"返回结果"一节共同遵循的模式（例如 generate_bar_chart.md 同样在 _meta.spec 中给出完整配置以便复用）。

六、使用建议与校验清单

规格文档给出的三条使用建议，可整理为一条可执行的构造清单：

1. 常规表格：只提供 data，可选 columns 控制列顺序；
2. 数据透视表：提供 rows（行分组）+ columns（列分组）+ values（聚合值字段）；
3. 字段名一致性：data 中对象的键名必须与 rows/columns/values 中引用的名称逐字一致。

在此基础上的补充实践要点：

• 字段名不一致是最常见的失败模式，构造 spec 后应逐项比对 data[0] 的键集合与三个维度字段的引用；
• theme 取值仅限 default/dark，width/height 缺省时按 600×400 渲染，需要嵌进固定版式时可显式指定；
• 由于 data 的键名即列名且直接决定表头，字段名建议使用对用户有语义的列名而非临时索引名，保证生成图片的可读性与 spec 的自解释性；
• 批量生成多张表格时，可利用脚本的数组入参能力一次性提交多个 spec，失败项不会阻塞其余生成。

七、相关文件索引

文件	作用
skills/public/chart-visualization/references/generate_spreadsheet.md	本文主体：电子表格/数据透视表规格（功能、字段、建议、返回）
skills/public/chart-visualization/SKILL.md	技能工作流：图表选型 → 参数提取 → 脚本调用 → 结果返回；Node 版本要求与许可声明
skills/public/chart-visualization/scripts/generate.js	生成脚本：spec 解析、请求链路、环境变量、错误处理
frontend/src/content/zh/harness/skills.mdx	DeerFlow 技能体系：skills/public 布局、加载与启用/禁用机制、container_path 配置