DeerFlow 图表技能详解：generate_pin_map 点标地图的字段规范、调用链路与高德地理数据实践

在 DeerFlow 的 chart-visualization 公共技能中，地图类图表被划分为三种形态：行政区地图（generate_district_map）、点标地图（generate_pin_map）与路径地图（generate_path_map）。本文聚焦其中的点标地图能力——在中国地图上以标记展示多个 POI（兴趣点）位置，并可配合图片弹窗展示说明信息，适用于门店分布、资产布点等场景。读完后你可以掌握 generate_pin_map 的完整字段规范、可复制的 JSON 调用载荷，以及它在技能脚本 scripts/generate.js 中的底层调用链路和返回结构。

功能定位：点标地图在三种地图工具中的分工

chart-visualization 技能内置 26 种可视化类型，其中地图类共三种，分工明确（见 SKILL.md 的选择指南）：

• generate_district_map：省/市/区/县层级的覆盖或热力图，适合区域销售、政策覆盖等指标展示；
• generate_pin_map：以离散点位标记展示 POI 集合，适合门店分布、资产布点、设备分布等"点"形态数据；
• generate_path_map：按顺序连接 POI 形成路线，适合物流路线、旅游规划、配送轨迹等"线"形态数据。

三者的共同边界是：地图依赖高德数据，仅支持中国境内。POI 必须可被高德地理编码解析，名称需包含足够的地理限定（城市+地标），例如"上海徐汇门店 A"，而非孤立的"门店 A"。

输入字段规范

必填字段

• title: string，必填且不超过 16 字，用于概述点位集合，会渲染为地图标题；
• data: string[]，必填，中国境内 POI 名称列表。数组顺序即点位集合，脚本侧不做排序或聚合。

可选字段

字段	类型	默认值	说明
markerPopup.type	string	—	固定为 image，表示点位弹窗展示图片
markerPopup.width	number	40	弹窗图片宽度
markerPopup.height	number	40	弹窗图片高度
markerPopup.borderRadius	number	8	弹窗图片圆角
width	number	1600	生成图宽（像素）
height	number	1000	生成图高（像素）

注意弹窗配置的嵌套结构：markerPopup 是一个对象，type 固定取 image；width/height 缺省 40 属于较小的图标式弹窗，若希望放大可显式调高。地图整体画布缺省为 1600×1000，与 generate_district_map.md 和 generate_path_map.md 保持一致的默认画幅。

可复制的调用示例

按照技能 SKILL.md 定义的标准载荷格式，一次点标地图生成请求如下：

{
  "tool": "generate_pin_map",
  "args": {
    "title": "全国直营门店分布",
    "data": [
      "上海市南京西路旗舰店",
      "北京市朝阳区望京店",
      "深圳市南山区科技园店",
      "杭州市西湖区长桥银泰店"
    ],
    "markerPopup": {
      "type": "image",
      "width": 60,
      "height": 60,
      "borderRadius": 8
    },
    "width": 1600,
    "height": 1000
  }
}

对应执行命令（详见 SKILL.md 的"Chart Generation"一节）：

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

其中 ./scripts/generate.js 相对 chart-visualization 技能根目录 解析；脚本同样接受 JSON 文件路径作为参数（源码中先用 fs.existsSync(specArg) 判断入参是否为文件，是则读取文件内容解析，否则按内联 JSON 解析）。技能要求 Node.js 版本 >=18.0.0，因为脚本使用了全局 fetch。

源码级调用链路：地图工具走的是独立分支

阅读 generate.js 可以确认 generate_pin_map 与其他 23 种普通图表在请求链路上存在本质差异：

1. 工具名到图表类型的映射：CHART_TYPE_MAP 中 generate_pin_map 映射为 pin-map（generate.js）。该映射注释说明与上游 src/utils/callTool.ts 保持一致。
2. 地图工具的特殊路由：脚本维护了一个名单 ["generate_district_map", "generate_path_map", "generate_pin_map"]（generate.js），命中名单的工具不走普通图表的 generateChartUrl（type + 图表选项直发），而是走 generateMap 分支：

const payload = {
  serviceId: getServiceIdentifier(), // process.env.SERVICE_ID
  tool,                              // 原始工具名，如 generate_pin_map
  input: inputData,                  // 即载荷中的 args 对象
  source: "chart-visualization-creator",
};

也就是说，点标地图的 args（含 title、data、markerPopup 等）会整体放入 input 字段提交，并附带 serviceId——若设置了环境变量 SERVICE_ID，生成记录会同步到"我的地图"小程序（与行政区地图、路径地图的文档描述一致）；未设置时该字段为 undefined，不影响出图。 3. 服务地址可覆盖：请求地址取 process.env.VIS_REQUEST_SERVER，缺省为 generate.js 中硬编码的蚂蚁 AntV Studio 服务地址。需要内网或自建代理时可注入该环境变量。 4. 结果输出形态：地图接口的响应体若含 content 数组，脚本会遍历并逐行打印 type === "text" 的条目（generate.js），其余类型则回退为 JSON 打印。批量场景下，脚本接受一个或多个 spec（非数组入参会被包成单元素数组）循环处理，单个失败会打印错误并继续，不会中断整批。

返回结果与 _meta.spec

按 generate_pin_map.md 的约定，成功后返回点标地图的图像 URL，并在 _meta.spec 中保存点位与弹窗配置。结合 SKILL.md 的"Result Return"步骤，技能规范要求向用户同时返回两样东西：图像 URL 与生成所用的完整 args（即 specification）。_meta.spec 正是后续编辑复用这份规格的基础——修改某个 POI 或弹窗尺寸后，可直接基于该 spec 重新调用脚本再生成，无需从零组织参数。

使用建议与边界

• POI 命名：必须包含城市+地标级别的地理限定，模糊名称会导致地理编码失败或落点漂移；根据业务可在名称中附带属性，如"上海徐汇门店 A"，这些文字会随点位一起呈现。
• 地域边界：仅支持中国境内 POI，这是高德地理数据源的固有限制，海外点位不会出图。
• 批量生成：一次命令行可传入 spec 数组，适合同一批门店/资产数据多轮调参（如对比不同 markerPopup 尺寸）。
• 运行环境：需要 Node.js ≥ 18 与可访问图表服务的网络；技能元数据（SKILL.md frontmatter）中显式声明了 nodejs: ">=18.0.0" 的兼容性约束。

在 DeerFlow 中的加载位置

chart-visualization 是 DeerFlow 内置公共技能之一，前端文档 skills.mdx 将其列为"从数据创建图表和可视化"能力；后端技能目录测试 test_skill_catalog.py 验证了按名称检索时该技能可被正确命中。技能由 skills/loader.py 扫描 skills/public/ 目录加载，Gateway API 启停技能即时生效。当你希望 Agent 自动产出点位分布图时，Agent 会依据 SKILL.md 的选择规则（"Maps: use generate_pin_map (points)"）命中本文讲解的参考规范，再按上述载荷格式调用脚本完成出图。