DeerFlow 的 generate_network_graph：用 nodes/edges 数据生成网络关系图的参数规范与完整调用链

本文围绕 generate_network_graph.md 这份参考文档展开，完整解析 DeerFlow chart-visualization 技能中网络关系图的输入字段规范（nodes/edges 结构、theme、style.texture 与画布尺寸）、使用建议与返回结果，并结合 generate.js 与 SKILL.md 的源码，还原从 JSON spec 到图表 URL 的完整调用链，读完后可直接在项目中复现一次可运行的网络图生成。

网络关系图的功能定位与适用场景

参考文档对 generate_network_graph 的定义是：以节点与连线呈现实体之间的连接关系，适合社交网络、系统依赖、知识图谱等场景。它面向的是"关系"这一类数据结构——当数据的核心不是趋势、占比或层级，而是"谁和谁之间、以什么关系相连"时，网络图就是最直接的可视化形式。

这一点也与技能的主入口文档 SKILL.md 中的选型指南一致。SKILL.md 把 26 种图表按数据特征分组，其中：

• Relationships & Flow（关系与流向） 一组包含 generate_scatter_chart（相关性）、generate_sankey_chart（流向）、generate_venn_chart（重叠）；
• Specialized（专用型） 一组中明确列出 generate_network_graph: Complex node-edge relationships（复杂节点-边关系）。

也就是说，在 DeerFlow 的图表选型决策树中，网络图被定位为处理复杂节点-边关系的专用工具，与桑基图（强调流量）、韦恩图（强调集合重叠）形成互补。前端文档 skills.mdx 的技能清单也将 chart-visualization 概括为"从数据创建图表和可视化"，网络关系图是其中 26 种可选图表之一。

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

参考文档对 generate_network_graph 的 args 定义如下，这是构造调用 payload 的完整依据。

必填字段：data.nodes 与 data.edges

字段	类型	约束
data	object	必填，包含节点与连线
data.nodes	array<object>	必填，至少 1 条，每个节点需提供唯一 name
data.edges	array<object>	必填，至少 1 条，包含 source 与 target（string），可选 name 说明关系

两个关键约束值得注意：

1. name 的唯一性是节点身份的唯一标识。edges 中的 source/target 通过字符串匹配 nodes 里的 name 来定位两端节点，因此节点命名必须稳定且唯一。
2. edges.name 是可选的关系标注。文档在"使用建议"中进一步提示"可在 label 中注明关系含义"——两者指向同一件事：给每条边一个可读的关系描述（如"依赖"、"汇报给"、"协作"），让图谱不只是拓扑结构，还能表达关系语义。

可选字段：theme、style.texture 与画布尺寸

字段	类型	默认值	可选值
style.texture	string	default	default / rough
theme	string	default	default / academy / dark
width	number	600	—
height	number	400	—

• theme 控制整体配色主题，dark 适合深色页面背景，academy 为偏学术的浅色调；不传时一律回落到 default。
• style.texture 控制笔触风格，rough 会呈现手绘/草图质感，适合演示性输出。
• width/height 以 600 x 400 为默认画布，节点较多、期望更舒展的布局时可自行放大。

使用建议：节点规模与连线一致性

参考文档给出的使用建议包含三条可操作的检查项，可以视作生成前的自检清单：

1. 节点数量保持在 10~50 之间以避免拥挤。少于 10 个节点时网络图往往退化成了简单的星型图或链状图，用组织图或桑基图表达可能更清晰；超过 50 个节点后，默认力导向布局下标签会互相遮挡，建议先在数据侧做聚合（如按部门/类别归并）再绘制。
2. 确保 edges 中的 source/target 对应已存在的节点。悬空的边（指向不存在的节点名）会破坏拓扑完整性，构造 payload 前建议先做一次 source/target ∈ nodes.name 的集合校验。
3. 在边的 name 中注明关系含义，提升图谱可读性。

返回结果：URL 与 _meta.spec

参考文档说明，调用成功后返回网络图 URL，并提供 _meta.spec 以便后续增删节点。

从 generate.js 的源码结构看，非地图类工具（网络图属于此类）走 generateChartUrl 分支：脚本把 { type, source: "chart-visualization-creator", ...args } POST 到可视化服务，校验响应 data.success 后将 data.resultObj 原样打印到 stdout（见 generateChartUrl 函数及 main() 中的 console.log(url)）。也就是说，stdout 输出的内容来自服务端返回的 resultObj，_meta.spec 即其中携带的完整规格快照。结合 SKILL.md 第 4 步"Result Return"的要求——把图片 URL 和生成所用的完整 args（specification）一并返回给用户——_meta.spec 的实际用途是：下一轮对话要增删节点、调整关系时，可以直接基于这份 spec 做增量修改，而无需从头重新描述整张图。

调用链解析：从 SKILL.md 工作流到 generate.js

generate_network_graph 不是一个独立入口，而是 chart-visualization 技能四步工作流中的一环。SKILL.md 定义的流程为：智能选图（Step 1）→ 读取对应 references/ 文档提取参数（Step 2）→ 调用脚本生成（Step 3）→ 返回 URL 与 args（Step 4）。

Step 3 的 payload 格式与执行命令

payload 采用统一的 { tool, args } 结构，tool 取值为 generate_network_graph：

{
  "tool": "generate_network_graph",
  "args": {
    "data": { "nodes": [], "edges": [] },
    "theme": "default",
    "style": { "texture": "default" },
    "width": 600,
    "height": 400
  }
}

执行命令为：

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

该技能在 frontmatter 中声明了 nodejs: ">=18.0.0" 的兼容要求，运行时需准备 Node.js 18 及以上版本（脚本内部使用了原生 fetch）。

generate.js 如何处理 generate_network_graph

从 generate.js 源码可以看到几个与网络图直接相关的实现细节：

1. 工具名映射：CHART_TYPE_MAP 将 generate_network_graph 映射为服务端类型 network-graph（见文件头部映射表）。若 tool 不在映射表中，脚本打印 Unknown tool 并跳过该条目。
2. 请求端点可配置：getVisRequestServer() 读取环境变量 VIS_REQUEST_SERVER，未设置时默认指向内置的可视化服务地址。需要替换渲染后端时只需设置该环境变量，无需改代码。对比之下，SERVICE_ID 环境变量仅被地图类工具（generate_district_map、generate_path_map、generate_pin_map）的 generateMap 分支使用，网络图不涉及。
3. spec 参数既可以是 JSON 字符串也可以是文件路径：main() 中先用 fs.existsSync 判断参数——若参数是已存在的文件路径则读文件解析，否则按内联 JSON 解析；解析失败会以 Error parsing spec: 报错退出（exit code 1）。
4. 支持批量生成：顶层 spec 若是数组（Array.isArray(spec)），会逐个处理并在 stdout 依次输出每张图的 URL，适合一次性生成多张图表的批处理场景。
5. 测试友好：文件末尾 module.exports = { generateChartUrl, generateMap, httpPost, CHART_TYPE_MAP } 导出了核心函数，便于单测 mock HTTP 层验证映射与响应处理逻辑。

可复制的完整示例

以"研发团队依赖关系"为例，把参考文档的全部约束落地成一个可直接执行的 payload（节点 5 个，在建议的 10~50 区间内偏小，仅作格式演示；实际使用时按真实规模补足）：

node ./scripts/generate.js '{
  "tool": "generate_network_graph",
  "args": {
    "data": {
      "nodes": [
        { "name": "deer-flow" },
        { "name": "gateway" },
        { "name": "sandbox" },
        { "name": "memory" },
        { "name": "skills" }
      ],
      "edges": [
        { "source": "gateway", "target": "deer-flow", "name": "接入" },
        { "source": "sandbox", "target": "deer-flow", "name": "执行环境" },
        { "source": "memory", "target": "deer-flow", "name": "持久化" },
        { "source": "skills", "target": "deer-flow", "name": "能力扩展" }
      ]
    },
    "theme": "default",
    "style": { "texture": "default" },
    "width": 600,
    "height": 400
  }
}'

执行成功后，stdout 输出生成的网络图 URL；如需增删节点，基于返回的 _meta.spec 修改 data.nodes/data.edges 后重新调用即可。

相关代码与文档索引

• 参考文档（本文主体）：generate_network_graph.md
• 技能工作流与 payload 规范：SKILL.md
• 生成脚本（映射表、端点配置、批量处理）：generate.js
• 技能选型分组（Relationships & Flow / Specialized）：SKILL.md 的 Step 1 部分
• 技能目录测试（chart-visualization 技能名匹配用例）：test_skill_catalog.py
• 前端技能清单文档：skills.mdx
• 同目录下另有 25 份同构参考文档（如 generate_sankey_chart.md、generate_mind_map.md），字段组织方式与本文一致，可按相同模式阅读。