DeerFlow chart-visualization 技能实战：generate_fishbone_diagram 鱼骨图参数全解

本文围绕 DeerFlow 仓库中 chart-visualization 技能的鱼骨图（generate_fishbone_diagram）参考文档展开，完整讲解其输入字段、树形数据设计与默认值，并深入 scripts/generate.js 的调用链，说明从 JSON 载荷到图片 URL 的完整生成流程。读完后可在 DeerFlow 的 Agent 对话中准确构造鱼骨图生成参数，并理解底层脚本如何路由、批处理和返回结果。

一、鱼骨图在技能体系中的定位

鱼骨图（Ishikawa Diagram，因果图）专用于根因分析：将中心问题放在主干，左右分支展示不同类别的原因及其细化节点，常见于质量管理、流程优化等场景（见 generate_fishbone_diagram.md 的功能概述）。

chart-visualization 是 DeerFlow 内置的公共技能，位于 skills/public/chart-visualization/ 目录，其 SKILL.md 声明了技能元数据（name: chart-visualization、Node.js 兼容性要求 >=18.0.0）与完整工作流。技能从 26 种可视化类型中智能选型，鱼骨图对应的选型规则是：

generate_fishbone_diagram: Cause-effect analysis.（因果/根因分析）

即当用户的数据特征表现为"一个问题、多类原因、逐层细化"时，应选中该图表。技能目录结构为：

• SKILL.md：工作流定义（选型 → 参数提取 → 生成 → 返回）；
• references/：26 个图表类型的参数规格文档，鱼骨图对应 references/generate_fishbone_diagram.md；
• scripts/generate.js：统一的图表生成入口脚本。

二、输入字段规格

参考文档将输入分为必填与可选两部分，全部作为 args 传入：

必填字段

字段	类型	说明
data	object	必填。至少提供根节点 name，可通过 children（array<object>）递归拓展子节点，最大建议 3 层

data 是一棵节点树：根节点描述中心问题，children 数组中每个子节点同样是 { name, children } 结构。层数控制在 3 层以内是为了保证渲染后的可读性——主干、一级分支、叶子三层恰好对应"问题 → 原因类别 → 具体现象"的因果层次。

可选字段

字段	类型	默认值	取值
style.texture	string	default	default / rough（切换线条风格，rough 为手绘风）
theme	string	default	default / academy / dark
width	number	600	画布宽度（像素）
height	number	400	画布高度（像素）

其中 texture 位于 style 对象内（即 args.style.texture），而 theme、width、height 直接挂在 args 顶层。需要区分"学术报告风"（academy）、"暗色仪表盘"（dark）与默认风格时，theme 是关键开关；在节点较多、标签拥挤时，可显式调大 width。

使用建议（来自参考文档）

• 主干节点：写问题陈述，例如"产品退货率上升 5%"；
• 一级分支：命名原因类别，质量管理领域惯用"人、机、料、法"（Man/Machine/Material/Method），也可按业务场景替换为"人员、设备、数据、流程"等；
• 叶子节点：写具体现象，保持短语式表达，避免长句。

三、完整载荷示例

结合 SKILL.md 定义的 Payload Format，一份可直接执行的鱼骨图生成载荷如下：

{
  "tool": "generate_fishbone_diagram",
  "args": {
    "data": {
      "name": "订单交付延迟",
      "children": [
        {
          "name": "人",
          "children": [
            { "name": "拣货员排班不足" },
            { "name": "新员工操作不熟练" }
          ]
        },
        {
          "name": "机",
          "children": [
            { "name": "打包机故障率上升" }
          ]
        },
        {
          "name": "料",
          "children": [
            { "name": "热销 SKU 缺货" }
          ]
        },
        {
          "name": "法",
          "children": [
            { "name": "波次策略未按峰值调整" }
          ]
        }
      ]
    },
    "theme": "default",
    "style": { "texture": "default" },
    "width": 600,
    "height": 400
  }
}

执行命令（见 SKILL.md 的 Execution Command）：

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

工作流要求返回给用户的不仅是图片 URL，还包括完整的 args（规格），以便后续增删节点时复用。

四、底层调用链：generate.js 是如何处理 fishbone-diagram 的

scripts/generate.js 是所有 26 种图表的统一入口。从源码结构看，鱼骨图的处理链路如下：

1. 工具名到图表类型的映射：CHART_TYPE_MAP 中 generate_fishbone_diagram 映射为 fishbone-diagram（见 generate.js）。该映射注释说明其与上游 src/utils/callTool.ts 保持一致，是渲染服务的类型标识。
2. 载荷解析：main() 读取 process.argv[2]，若参数是已存在的文件路径则读取文件内容，否则按 JSON 字符串解析（generate.js）。这意味着长载荷可以写成 JSON 文件再传入，规避 shell 引号转义问题。
3. 批处理支持：若解析结果是数组，脚本会逐个处理（generate.js），一次命令可生成多张图；单条 spec 中 tool 缺失或类型未知时打印错误并 continue，不会中断其余项。
4. 服务端调用：非地图类图表（鱼骨图不属于 generate_district_map/generate_path_map/generate_pin_map 这三个走 generateMap 分支的工具）统一走 generateChartUrl()：构造 { type: "fishbone-diagram", source: "chart-visualization-creator", ...options } 的 POST 请求，请求地址取自环境变量 VIS_REQUEST_SERVER，未设置时回退到脚本内置的默认服务端点（见 generate.js 的 getVisRequestServer()）。因此部署方可以通过设置 VIS_REQUEST_SERVER 指向自建或内网渲染服务，而不修改脚本代码。
5. 结果输出：服务端响应中 success 为假时抛出 errorMessage；成功时取 data.resultObj——对鱼骨图即生成的图片 URL，由脚本 console.log 输出到 stdout（generate.js）。

五、返回结果与后续迭代

参考文档"返回结果"一节说明：

• 返回鱼骨图 URL（图片地址）；
• 并在 _meta.spec 中保存树形结构，便于后续增删节点。

这与 SKILL.md 的"Result Return"步骤呼应：Agent 应把图片 URL 与完整 args 一并返回给用户。由于 data 本身是纯 JSON 节点树，迭代方式就是基于 _meta.spec 修改 children（如给"法"分支新增叶子"复核流程缺签字"），再以同样的 tool + args 重新调用脚本重新生成，无需任何服务端改动。

六、在 DeerFlow 中如何被加载与使用

chart-visualization 属于 DeerFlow 技能系统的公共技能：

• 目录约定：公共技能位于 skills/public/，自定义技能位于 skills/custom/，每个技能以 SKILL.md 为权威定义（见 frontend 技能文档）；
• 加载机制：load_skills() 每次调用都重新扫描技能路径下的 public/ 与 custom/ 目录，并重新读取扩展配置，因此通过 Gateway API 启停技能会立即生效、无需重启；
• 运行位置：技能在沙箱中挂载，container_path 默认为 /mnt/skills，即 Agent 执行 node ./scripts/generate.js 时工作目录即技能目录；
• 能力前置条件：SKILL.md frontmatter 声明 nodejs: ">=18.0.0"，因为脚本依赖 Node 18 内置的全局 fetch（见 generate.js 的 httpPost 实现）。

此外，仓库测试 backend/tests/test_skill_catalog.py 会校验 SKILL.md 的存在与解析，说明该技能目录结构是受测试契约保护的。

七、实践要点小结

1. 因果/根因分析场景选用 generate_fishbone_diagram，树深建议 ≤3 层：根节点 = 问题陈述，一级 = 原因类别，叶子 = 具体现象短语；
2. data 是唯一必填字段，theme、style.texture、width、height 全部可选且有默认值（default/default/600/400）；
3. 载荷既可内联为 JSON 字符串，也可写成 JSON 文件后把路径传给 scripts/generate.js，数组形式还可一次批量出多张图;
4. 结果 = 图片 URL + _meta.spec 中的节点树，基于该 spec 增删 children 即可低成本迭代图表；
5. 需要内网/自建渲染端点时，通过环境变量 VIS_REQUEST_SERVER 覆盖默认服务端，无需改动脚本。