DeerFlow chart-visualization 技能深度解析：generate_path_map 路径地图的规范、调用链与实现

本篇指南基于 DeerFlow 内置 chart-visualization 技能的参考文档，围绕 generate_path_map（中国境内路径地图）这一工具展开：完整梳理其输入字段规范与使用约束，并结合 scripts/generate.js 的源码实现，讲清该工具从 JSON payload 到地图 URL 返回的完整调用链，帮助读者掌握在 Agent 工作流中按规范生成路线、行程类地图的实战能力。

1. 背景：chart-visualization 技能在 DeerFlow 中的定位

DeerFlow 的公开技能目录 skills/public 下提供了 chart-visualization 技能，用于将数据转换为可视化图表。在 SKILL.md 中，该技能被描述为：从 26 种可选图表类型中智能选择最合适的类型，按 references/ 目录中的详细规格提取参数，再通过 JavaScript 脚本生成图表图像。它同时出现在 DeerFlow 的前端技能文档 skills.mdx 的技能清单中（“从数据创建图表和可视化”）。

该技能要求 Node.js >= 18.0.0（见 SKILL.md 的 frontmatter compatibility 字段），整个工作流分为四步：

1. 智能选图：根据数据特征选择图表类型。地图类工具共三个：generate_district_map（区域覆盖/热力）、generate_pin_map（点位标记）、generate_path_map（路线连接）；
2. 参数提取：读取 references/ 目录中对应图表的规格文件（如 references/generate_path_map.md），确定必填与可选字段，把用户数据映射到 args；
3. 生成调用：以 JSON payload 形式执行 node ./scripts/generate.js '<payload_json>'；
4. 结果返回：脚本输出图表图像 URL，同时返回完整的 args 规格供用户追溯。

generate_path_map 正是这套工作流中“地图类”分支下的路线型工具，以下各节先给出规范，再对照源码验证其实际行为。

2. generate_path_map 功能与输入字段规范

2.1 功能概述

按 generate_path_map.md 的定义，generate_path_map 基于高德地图展示中国境内的路线或行程，按顺序连接一系列 POI（兴趣点），典型适用场景包括：

• 物流路线展示；
• 旅游行程规划；
• 配送轨迹呈现。

2.2 输入字段

必填字段：

字段	类型	约束	说明
title	string	必填，长度 ≤ 16 字	描述路线主题
data	array<object>	至少 1 个路线对象	承载一条或多条路线
data[].data	string[]	必填	该路线上按顺序排列的中国境内 POI 名称

可选字段：

字段	类型	默认值	说明
width	number	1600	地图宽度
height	number	1000	地图高度

一个符合规范的最小 payload 示例如下（路线为西安钟楼 → 咸阳机场，途经咸阳博物馆）：

{
  "tool": "generate_path_map",
  "args": {
    "title": "西安一日行程",
    "data": [
      {
        "data": ["西安市钟楼", "咸阳博物馆", "咸阳国际机场"]
      }
    ]
  }
}

需要注意 data 的嵌套结构：外层 data 是路线对象数组，每个路线对象内部再用 data 字段承载 POI 名称数组——这决定了多路线时“每段对象即一条独立线路”。

2.3 使用建议与返回结果

参考文档给出了两条关键使用建议：

• POI 名称必须具体且位于中国，例如“西安市钟楼”“杭州西湖苏堤春晓”；名称要包含足够的地理限定（城市 + 地标），避免模糊词，且受限于高德地图数据，仅支持中国境内；
• 多条线路：在 data 中添加多个路线对象即可，每个对象独立描述一条线路。

关于返回结果，文档明确了三点行为：

• 返回路径地图的 URL；
• 在 _meta.spec 中保留本次使用的标题与 POI 列表，便于事后追溯与复现；
• 若配置了环境变量 SERVICE_ID，生成记录还会同步到“我的地图”小程序。

3. 源码级调用链：generate_path_map 在 generate.js 中的特殊路径

规范文档描述的是“输入契约”，而 scripts/generate.js 揭示了实际执行时该工具走的是一条与普通图表不同的分支。

3.1 CLI 入口：JSON 字符串或文件，支持批量

脚本入口 main()（generate.js）从 process.argv[2] 读取 spec：如果该参数是一个已存在的文件路径，则读取文件内容解析；否则直接将其作为 JSON 字符串解析。解析后的 spec 会先包一层数组（Array.isArray(spec) ? spec : [spec]），也就是说一次调用可以传入多个 spec 批量生成——对“多段路线地图 + 其他图表”组合输出很实用。

3.2 地图工具走 generateMap 分支，而非通用图表分支

脚本中维护了 CHART_TYPE_MAP（generate.js），其中 generate_path_map 映射为 path-map。但真正决定行为的是这段判定（generate.js）：

const isMapChartTool = [
  "generate_district_map",
  "generate_path_map",
  "generate_pin_map",
].includes(tool);

凡是命中该列表的地图类工具，统一走 generateMap(tool, args)，而不是普通图表的 generateChartUrl(chartType, options)。两者的请求 payload 结构不同：

• 普通图表：{ type: chartType, source: "chart-visualization-creator", ...options }；
• 地图工具：{ serviceId: getServiceIdentifier(), tool, input: inputData, source: "chart-visualization-creator" }，即工具名与完整入参放在 tool 和 input 字段中，并附带 serviceId（取自环境变量 SERVICE_ID，未设置时为 undefined）。

这与参考文档“若配置 SERVICE_ID，还会记录到‘我的地图’”的描述一一对应：SERVICE_ID 正是在 generateMap 的 payload 中传给服务端（generate.js）。

3.3 请求目标、响应解析与输出格式

• 请求地址：getVisRequestServer() 优先读取环境变量 VIS_REQUEST_SERVER，缺省时指向默认的 gpt-vis 服务端（generate.js）。通过 VIS_REQUEST_SERVER 可以切换到自建或测试端点，这在离线联调或私有部署时很有意义；
• 响应处理：httpPost 对非 2xx 状态直接抛出 HTTP <status>: <text> 错误；业务层则检查 data.success，失败时抛出 errorMessage；
• 地图结果输出：由于地图工具的返回是结构化内容，脚本会遍历 result.content，只打印 type === "text" 的项（其中即地图 URL 与元信息文本）；若响应结构不符合预期，则整体 JSON.stringify 输出（generate.js）。普通图表则直接 console.log(url)。

此外脚本把 generateChartUrl、generateMap、httpPost、CHART_TYPE_MAP 导出为 module.exports（generate.js）并注明 “Export functions for testing”，从源码结构看这是为了支持对 HTTP 交互的单元/集成测试打桩。

3.4 与其他两个地图工具的字段对比

理解 generate_path_map 的 data 结构，最好与同目录下的另外两个地图规格对照（generate_pin_map.md、generate_district_map.md）：

工具	data 结构	语义	场景
generate_path_map	array<object>，每项含 data: string[]	多段有序路线	路线、行程、轨迹
generate_pin_map	string[]（扁平 POI 列表），可选 markerPopup.* 弹窗配置	多个独立点位	门店分布、资产布点
generate_district_map	object，含 name（行政区关键词）及指标/下钻配置	区域覆盖/热力	区域销售、政策覆盖

三者都仅支持中国境内且依赖高德数据，但 path-map 独有“按顺序连接”的语义：data[].data 数组内的顺序就是路线的走向，这一点在提取用户数据时必须严格保持原始行程顺序。

4. 实操：在 DeerFlow 中运行一条路径地图

4.1 前置条件

• 已具备 Node.js >= 18（技能 frontmatter 声明的最低版本）；
• 可访问 gpt-vis 服务端（默认端点），或通过 VIS_REQUEST_SERVER 指定自定义服务端；
• 如需把生成记录同步到“我的地图”，设置环境变量 SERVICE_ID。

4.2 执行命令

在技能目录下执行（payload 与第 2 节示例一致）：

node ./scripts/generate.js '{
  "tool": "generate_path_map",
  "args": {
    "title": "杭州西湖环线",
    "data": [
      { "data": ["杭州西湖苏堤春晓", "杭州雷峰塔", "杭州灵隐寺"] }
    ]
  }
}'

也可以把 spec 写入文件后直接传文件路径，脚本会识别存在性并读文件解析——这对多 spec 批量场景更友好。

4.3 结果解读

• 成功时，stdout 输出地图 URL 及相关文本（来自 result.content 中 type === "text" 的项）；
• 生成结果的 _meta.spec 中保留了标题与 POI 列表，可用于复现或审计；
• 失败时脚本输出形如 Error generating chart for generate_path_map: <message> 的错误到 stderr，排查时应优先核对：POI 是否为中国境内具体地标、title 是否超过 16 字、data[].data 是否为非空数组。

5. 小结

generate_path_map 的规范核心可以浓缩为三句话：title 不超过 16 字、data 是有序 POI 数组的路线对象数组、仅支持中国境内具体地标；而从 generate.js 源码可以看到，它在执行链路上属于“地图工具分支”：请求 payload 携带 tool、input 与 serviceId，响应按 content 文本项解析输出，并支持环境变量 VIS_REQUEST_SERVER 与 SERVICE_ID 定制服务端与记录归属。规范文档与脚本实现相互印证，构成了 DeerFlow 图表可视化技能中路线类地图从参数到成图的完整闭环。