Fusion Studio MCP

用于通过 Fusion 的脚本 API 检查和操控独立版 Blackmagic Fusion Studio 的本地 MCP 服务器。

本项目采取保守起步策略：先验证 Fusion 连接，再暴露只读检查工具，然后添加带 dry-run 和撤销行为的受保护编辑工具。

当前状态

• 项目脚手架创建于：2026-07-13

• 已找到目标应用：Blackmagic Fusion 21.0.2

• 已确认 Fusion 内置 fusionscript.so 的 Python 导入路径

• 已针对 Composition1 验证实时合成检查

• 已创建包含 pytest、ruff 和 Python MCP SDK 的本地 .venv

• 已实现只读 MCP 工具，涵盖状态、节点列表、单节点查询、选中节点读取和紧凑合成摘要

• 已实现受保护的编辑 MCP 工具，涵盖选择、输入读写、重命名和 FlowView 定位

• 已实现受控节点创建、图像连接编辑、输入断开、连接检查和确认的单节点删除

• 已实现可配置节点创建以及原生关键帧和表达式工具

• 已实现合成控制以及事务性图形和批处理工具

• 已实现渲染验证、Saver 设置、诊断、工具目录/架构和图形导出工具

• 已针对一次性 Composition1 通过实时编辑验证

Related MCP server: nuke-mcp

要求

• macOS

• Blackmagic Fusion Studio 21.0.2 或兼容版本

• 需要 Python 3.11+（requires-python = ">=3.11"）；macOS 自带的 Python 3.9 太旧

• Fusion 内置脚本库路径可用： /Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

• 服务器模式需要 Python MCP SDK

在 macOS 上通过 Claude Desktop 安装

推荐给艺术家和非开发者：安装 Fusion Studio MCP - Claude Desktop (macOS)。

这是面向 macOS 上独立版 Fusion Studio 和 Claude Desktop 的公开、两次粘贴式安装路径。它从公共 GitHub 仓库安装： https://github.com/bigsbypuglise/fusion-studio-mcp

如果你希望 Claude Desktop 检查 Fusion 合成、列出节点并构建受保护的节点树，而无需进行开发者设置，请使用此路径。

快速版本：

1. 打开 Fusion Studio 21 并打开或创建一个合成。

2. 运行 Claude Desktop macOS 指南中的安装粘贴内容。

3. 运行指南中的 Claude 配置粘贴内容。

4. 使用 Command-Q 完全退出 Claude Desktop，重新打开，然后让 Claude 检查 Fusion 连接。

注意：

• 推荐使用 Fusion Studio 21；Fusion Studio 20 可能也能工作。

• 目前针对独立版 Fusion Studio，而非 DaVinci Resolve。

• Fusion Studio 必须正在运行且已打开一个活动合成。

• 第一次 Claude 工具调用可能会请求权限。

• 默认的新手安装程序跟踪最新的公共 main 分支，因此重新运行粘贴 #1 会更新本地安装。希望固定稳定版本的用户可以使用指南中的标记版本选项。

高级安装

以下 macOS 工作流已使用 Fusion Studio 21.0.2 进行过实机测试。Windows 工作流已针对等效的 Fusion Studio 安装编写文档，但仍需在干净的 Windows 机器上进行验证。

macOS 开发者设置

已支持并实机测试的环境：

• Blackmagic Fusion Studio 21.0.2

• Python 3.11+

• 已确认的应用路径：/Applications/Blackmagic Fusion 21/Fusion.app

• 已确认的脚本库路径：/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries

如有需要，使用 Homebrew 安装 Python：

brew install python@3.11

创建并安装本地环境：

cd /path/to/fusion-studio-mcp
PYTHON_BIN=/opt/homebrew/bin/python3.11 scripts/setup_local.sh

或者手动操作：

cd /path/to/fusion-studio-mcp
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'

启动 Fusion Studio，创建或打开一个一次性合成，然后运行：

export PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src"
python scripts/test_fusion_connection.py
python -m fusion_mcp.server

python -m fusion_mcp.server 是一个 stdio MCP 服务器入口点。它旨在由 MCP 客户端启动；当在没有客户端附着的普通终端中直接运行时，它可能会在 stdin 关闭后干净退出。使用 scripts/test_fusion_connection.py 进行独立的连接冒烟测试。

macOS MCP 客户端示例：

{
  "mcpServers": {
    "fusion-studio": {
      "command": "/path/to/fusion-studio-mcp/.venv/bin/python",
      "args": ["-m", "fusion_mcp.server"],
      "env": {
        "PYTHONPATH": "/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:/path/to/fusion-studio-mcp/src"
      }
    }
  }
}

macOS 故障排除：

• 如果 Fusion 已关闭或没有活动合成，连接工具会返回 FUSION_NOT_RUNNING 或 NO_ACTIVE_COMP。

• 如果 fusionscript 无法导入，请确认 PYTHONPATH 包含 Fusion 的 Contents/Libraries 路径。

• macOS 在工具首次与其他应用通信时可能会显示安全提示。允许 Fusion 和终端/MCP 客户端在本地通信。

• 为 Saver 渲染使用唯一的绝对输出文件夹，以避免覆盖保护和 Fusion 文件名边缘情况。

Windows 开发者设置

已文档化的目标环境：

• Blackmagic Fusion Studio 21.0.2 或兼容版本

• Python 3.11+

• 常见应用路径：C:\Program Files\Blackmagic Design\Fusion 21\Fusion.exe

• 常见脚本库路径：C:\Program Files\Blackmagic Design\Fusion 21

从 https://www.python.org/downloads/windows/ 安装 Python 并启用“Add python.exe to PATH”，或使用 winget 安装：

winget install Python.Python.3.11
python --version
py -3.11 --version

从 PowerShell 创建并安装本地环境：

cd C:\path\to\fusion-studio-mcp
.\scripts\setup_local.ps1 -Python py -PythonArgs "-3.11"
.\.venv\Scripts\Activate.ps1

如果 PowerShell 阻止脚本，仅对当前进程运行：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\scripts\setup_local.ps1 -Python py -PythonArgs "-3.11"

手动命令提示符设置：

cd C:\path\to\fusion-studio-mcp
py -3.11 -m venv .venv
.venv\Scripts\activate.bat
python -m pip install --upgrade pip
python -m pip install -e .[dev]

启动 Fusion Studio，创建或打开一个一次性合成，然后从 PowerShell 运行：

.\.venv\Scripts\Activate.ps1
$env:PYTHONPATH = "C:\Program Files\Blackmagic Design\Fusion 21;C:\path\to\fusion-studio-mcp\src"
.\.venv\Scripts\python.exe .\scripts\test_fusion_connection.py
.\.venv\Scripts\python.exe -m fusion_mcp.server

与 macOS 一样，服务器命令旨在由 MCP 客户端通过 stdio 启动。如果在没有客户端附着的 shell 中手动运行，它可能会在 stdin 关闭时退出。

Windows MCP 客户端示例：

{
  "mcpServers": {
    "fusion-studio": {
      "command": "C:\\path\\to\\fusion-studio-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "fusion_mcp.server"],
      "env": {
        "PYTHONPATH": "C:\\Program Files\\Blackmagic Design\\Fusion 21;C:\\path\\to\\fusion-studio-mcp\\src"
      }
    }
  }
}

Windows 故障排除：

• 这些 Windows 步骤已编写文档，但尚未在干净的 Windows 机器上进行实机验证。

• 如果找不到 python，请使用 py -3.11 或重新安装启用了 PATH 集成的 Python。

• 如果 fusionscript 无法导入，请验证 Fusion 安装路径并将其脚本目录添加到 PYTHONPATH。

• 在 PowerShell 和 JSON 中引用带空格的路径；在 JSON 字符串中使用双反斜杠。

• 如果连接失败，请确认 Fusion Studio 已打开、未被 Windows 安全提示阻止，并且有活动合成。

• 在可写文件夹中使用绝对的 Saver 输出路径，并优先为每次渲染使用唯一的输出文件夹。

快速连接测试

1. 打开独立版 Fusion Studio。

2. 打开或创建一个一次性合成。

3. 运行：

cd /path/to/fusion-studio-mcp
PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python scripts/test_fusion_connection.py

该脚本打印结构化 JSON。如果 Fusion 已关闭，它应返回 success: false 并带有 FUSION_NOT_RUNNING。

只读检查探针

在不启动 MCP 客户端的情况下运行所有只读工具函数：

cd /path/to/fusion-studio-mcp
PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python scripts/inspect_read_only.py

当前只读工具：

• fusion_get_status_tool

• fusion_list_nodes_tool

• fusion_get_node_tool(node_name)

• fusion_get_selected_nodes_tool

• fusion_summarize_comp_tool

• fusion_get_node_input_tool(node_name, input_name)

节点列表条目包括：

• 节点名称和 Fusion 工具类型

• 当 Fusion 暴露时，来自 comp.CurrentFrame.FlowView.GetPosTable(tool) 的流程位置

• 输入，包含 ID、名称、数据类型、当前非图像值、连接的输出和输入属性

• 输出，包含 ID、名称、数据类型、连接的输入和输出属性

• 非图像控件的关键设置摘要

运行 MCP 服务器

设置完成后，运行：

cd /path/to/fusion-studio-mcp
PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python -m fusion_mcp.server

示例 MCP 风格操作：

fusion_get_status_tool()
fusion_list_nodes_tool()
fusion_get_node_tool(node_name="Blur1")
fusion_get_selected_nodes_tool()
fusion_summarize_comp_tool()
fusion_select_nodes_tool(node_names=["Background1", "Transform1"])
fusion_get_node_input_tool(node_name="Transform1", input_name="Blend")
fusion_set_node_input_tool(node_name="Transform1", input_name="Blend", value=0.5)
fusion_set_node_name_tool(node_name="Transform1", new_name="Transform_Main")
fusion_set_node_position_tool(node_name="Transform_Main", x=0, y=0)
fusion_create_node_tool(tool_id="Blur", name="Blur_Main", x=1, y=0)
fusion_create_node_tool(
  tool_id="Saver",
  name="Saver_Main",
  x=2,
  y=0,
  settings={"Clip": "/tmp/example.exr"}
)
fusion_connect_nodes_tool(
  source_node="Transform_Main",
  source_output="Output",
  target_node="Blur_Main",
  target_input="Input",
  replace=false
)
fusion_get_connections_tool(node_name="Blur_Main")
fusion_disconnect_input_tool(node_name="Blur_Main", input_name="Input")
fusion_delete_node_tool(node_name="Blur_Main", confirm=true)
fusion_set_keyframe_tool(node_name="Transform_Main", input_name="Size", frame=0, value=1.0, replace=false)
fusion_get_keyframes_tool(node_name="Transform_Main", input_name="Size")
fusion_delete_keyframe_tool(node_name="Transform_Main", input_name="Size", frame=10, confirm=true)
fusion_clear_keyframes_tool(node_name="Transform_Main", input_name="Center", confirm=true)
fusion_set_expression_tool(node_name="Transform_Main", input_name="Angle", expression="time/10", replace=false)
fusion_get_expression_tool(node_name="Transform_Main", input_name="Angle")
fusion_remove_expression_tool(node_name="Transform_Main", input_name="Angle", confirm=true)
fusion_get_comp_settings_tool()
fusion_set_comp_range_tool(start_frame=1, end_frame=48)
fusion_set_current_frame_tool(frame=24)
fusion_get_current_frame_tool()
fusion_save_comp_tool(path="/tmp/example.comp")
fusion_get_comp_path_tool()
fusion_create_graph_tool(
  nodes=[
    {"id": "bg", "tool_id": "Background", "name": "BG", "x": -4, "y": 0,
     "settings": {"TopLeftRed": 0.2, "TopLeftGreen": 0.4, "TopLeftBlue": 0.8}},
    {"id": "tx", "tool_id": "Transform", "name": "TX", "x": -2, "y": 0},
    {"id": "blur", "tool_id": "Blur", "name": "Blur", "x": 0, "y": 0,
     "settings": {"XBlurSize": 3.0}},
    {"id": "saver", "tool_id": "Saver", "name": "Saver", "x": 2, "y": 0,
     "settings": {"Clip": "/tmp/example.exr"}}
  ],
  connections=[
    {"source": "bg", "target": "tx", "source_output": "Output", "target_input": "Input"},
    {"source": "tx", "target": "blur", "source_output": "Output", "target_input": "Input"},
    {"source": "blur", "target": "saver", "source_output": "Output", "target_input": "Input"}
  ],
  comp_settings={"start_frame": 1, "end_frame": 48}
)
fusion_batch_set_inputs_tool(changes=[{"node_name": "BG", "input_name": "TopLeftRed", "value": 0.5}])
fusion_batch_set_keyframes_tool(keyframes=[{"node_name": "TX", "input_name": "Size", "frame": 1, "value": 1.0}])
fusion_batch_delete_nodes_tool(node_names=["Blur"], confirm=true)
fusion_get_saver_settings_tool(node_name="Saver")
fusion_set_saver_settings_tool(node_name="Saver", settings={"Clip": "/tmp/render.exr"})
fusion_validate_render_tool(saver_node="Saver", allow_overwrite=false)
fusion_render_tool(start_frame=1, end_frame=1, saver_node="Saver", confirm=true, allow_overwrite=false)
fusion_get_render_status_tool()
fusion_abort_render_tool(confirm=true)
fusion_validate_comp_tool()
fusion_find_broken_connections_tool()
fusion_find_missing_media_tool()
fusion_get_tool_catalog_tool(search="blur")
fusion_get_tool_schema_tool(tool_id="Blur")
fusion_export_graph_tool(node_names=["BG", "TX", "Saver"])
fusion_validate_graph_request_tool(nodes=[...], connections=[...], comp_settings={...})

来自实时空 Composition1 的示例紧凑摘要响应：

{
  "success": true,
  "operation": "fusion_summarize_comp",
  "agent_summary": {
    "composition_name": "Composition1",
    "node_count": 0,
    "selected_nodes": [],
    "tool_type_counts": {},
    "plain_english": "Composition Composition1 has 0 node(s); 0 selected."
  }
}

安全编辑工具

编辑操作在修改任何内容之前会验证活动合成、节点和输入。写入使用 Fusion 的 Lock()、StartUndo(...)、EndUndo(True) 和 Unlock()，并通过防御性清理包装器实现，以便失败的操作不会留下未关闭的撤销组。

已实现的编辑工具：

• fusion_select_nodes_tool(node_names)

• fusion_get_node_input_tool(node_name, input_name)

• fusion_set_node_input_tool(node_name, input_name, value)

• fusion_set_node_name_tool(node_name, new_name)

• fusion_set_node_position_tool(node_name, x, y)

• fusion_create_node_tool(tool_id, name=None, x=None, y=None)

• fusion_connect_nodes_tool(source_node, source_output, target_node, target_input, replace=False)

• fusion_disconnect_input_tool(node_name, input_name)

• fusion_get_connections_tool(node_name=None)

• fusion_delete_node_tool(node_name, confirm=False)

• fusion_set_keyframe_tool(node_name, input_name, frame, value, replace=False)

• fusion_get_keyframes_tool(node_name, input_name)

• fusion_delete_keyframe_tool(node_name, input_name, frame, confirm=False)

• fusion_clear_keyframes_tool(node_name, input_name, confirm=False)

• fusion_set_expression_tool(node_name, input_name, expression, replace=False)

• fusion_get_expression_tool(node_name, input_name)

• fusion_remove_expression_tool(node_name, input_name, confirm=False)

• fusion_get_comp_settings_tool()

• fusion_set_comp_range_tool(start_frame, end_frame)

• fusion_set_current_frame_tool(frame)

• fusion_get_current_frame_tool()

• fusion_save_comp_tool(path=None)

• fusion_get_comp_path_tool()

• fusion_create_graph_tool(nodes, connections, comp_settings=None)

• fusion_batch_set_inputs_tool(changes)

• fusion_batch_set_keyframes_tool(keyframes)

• fusion_batch_delete_nodes_tool(node_names, confirm=False)

• fusion_get_saver_settings_tool(node_name)

• fusion_set_saver_settings_tool(node_name, settings)

• fusion_validate_render_tool(saver_node=None, allow_overwrite=False)

• fusion_render_tool(start_frame=None, end_frame=None, saver_node=None, confirm=False, allow_overwrite=False)

• fusion_get_render_status_tool()

• fusion_abort_render_tool(confirm=False)

• fusion_validate_comp_tool()

• fusion_find_broken_connections_tool()

• fusion_find_missing_media_tool()

• fusion_get_tool_catalog_tool(search=None)

• fusion_get_tool_schema_tool(tool_id)

• fusion_export_graph_tool(node_names=None)

• fusion_validate_graph_request_tool(nodes, connections, comp_settings=None)

fusion_set_node_input_tool 支持常见的 Fusion 值类型：

• 有限标量数字

• 布尔值，对于数字型 Fusion 输入转换为 1 或 0

• 用于 Text 输入的字符串

• 用于 FuID 输入的字符串，当 Fusion 暴露时根据每个输入的选择进行验证

• 点作为 [x, y] 或 {"x": x, "y": y}

• 颜色作为 [r, g, b]、[r, g, b, a]，或当 Fusion 暴露真正的 Color 输入时使用匹配的字典键

不支持或模糊的值会返回结构化失败，并且不会尝试写入。图像输入会被值设置工具拒绝，因为它们必须作为连接而不是标量值进行编辑。

Fusion Studio 21.0.2 中内置的 Background 颜色控件暴露为单独的数值通道输入，例如 TopLeftRed、TopLeftGreen、TopLeftBlue 和 TopLeftAlpha，每个都使用 INPID_InputControl == "ColorControl" 和 INPS_DataType == "Number"。实时验证确认可以使用标量浮点数设置这些通道，例如 TopLeftRed = 0.25。

示例成功响应：

{
  "success": true,
  "operation": "fusion_set_node_input",
  "node_name": "FMC_Test_Transform",
  "input_id": "Size",
  "previous_value": 1.0,
  "requested_value": 0.8,
  "confirmed_value": 0.8,
  "summary": "Set FMC_Test_Transform.Size."
}

示例验证失败：

{
  "success": false,
  "operation": "fusion_set_node_input",
  "error_code": "UNSUPPORTED_INPUT_VALUE",
  "error_message": "Image inputs are connections, not scalar values.",
  "node_name": "FMC_Test_Transform",
  "input_id": "Input",
  "requested_value": 1
}

连接和节点工具

fusion_create_node_tool 接受可选的 settings，在节点创建并验证后应用。设置失败会产生部分结果：创建的节点保留在合成中，成功的设置会被报告，失败的设置包含每个输入的错误代码。Saver 可以通过 settings={"Clip": "/path/to/output.exr"} 接收其 Clip 路径，并且在提供该设置时不再需要占位符。

连接编辑目前仅限于图像流链接。工具层会拒绝修饰符、表达式、遮罩和标量链接，并返回明确的套接字元数据，而不是假装它们是普通的图像管道。

安全行为：

• 创建前会对照 Fusion 的本地注册表检查工具 ID

• 在独立版 Fusion 中拒绝 MediaOut，因为其注册表类在那里不可创建

• Saver 可以使用显式的占位 Clip 路径创建，以避免 Fusion 打开文件对话框

• 除非 replace=true，否则不会替换目标输入

• 拒绝自连接和明显的图像流循环

• 删除需要 confirm=true，并且每次调用只接受一个节点名称

• 所有创建/连接/断开/删除操作都使用 Fusion 撤销组

示例连接成功：

{
  "success": true,
  "operation": "fusion_connect_nodes",
  "previous_state": null,
  "requested_state": {
    "source_node": "Background1",
    "source_output": "Output",
    "target_node": "Transform1",
    "target_input": "Input",
    "replace": false
  },
  "confirmed_state": {
    "node": "Background1",
    "output": "Output",
    "data_type": "Image"
  }
}

示例删除保护：

{
  "success": false,
  "operation": "fusion_delete_node",
  "error_code": "DELETE_CONFIRMATION_REQUIRED",
  "error_message": "Deletion requires confirm=true."
}

合成与批处理工具

合成控制暴露帧范围、当前帧、保存路径以及显式的 .comp 保存。实时验证确认了在独立版 Fusion Studio 21.0.2 中 fusion_set_comp_range_tool(1, 48)、fusion_set_current_frame_tool(24) 和 fusion_save_comp_tool("/tmp/fusionmcp_batch_*.comp") 均可用。

fusion_create_graph_tool 接受：

• nodes：包含 id、tool_id 或 tool_type、可选 name、可选 x/y 以及可选 settings 的对象

• connections：在 source/target 中包含图节点 id 的对象，外加 source_output 和 target_input

• comp_settings：目前支持 start_frame/end_frame 或 global_start/global_end

图创建会在事务期间或之前验证重复名称、缺失的图引用、无效的工具 id、明显的循环以及不支持的值。它先创建节点，再应用设置，然后连接 Image 套接字。如果后续步骤失败，它会尝试断开该请求创建的链接，并仅删除该请求创建的节点，返回 status: "rolled_back" 以及逐项回滚结果。

批处理输入/关键帧/删除工具每个批次使用一个 Fusion 撤销组。批处理删除要求 confirm=true，并且只删除显式列出的节点。

渲染、诊断与导出

渲染执行要求 confirm=true。fusion_validate_render_tool 检查活动合成状态、Saver 是否存在/类型、绝对输出路径、支持的文件扩展名、缺失的输出目录、覆盖风险、有效的帧范围，以及 Saver 图像输入是否已连接，而不会有意渲染。现有输出返回 OUTPUT_ALREADY_EXISTS，除非显式提供 allow_overwrite=true。

带有特定 saver_node 的 fusion_render_tool 使用经过实时确认的规范 Saver 事务：它保留原始 Saver 对象，不重写 Clip，渲染前不轮询渲染状态，调用 comp.Render 一次并传入 Start、End、Wait 和 Tool，然后从磁盘上的 Saver Clip 路径确认输出文件。如果 Fusion 报告完成但预期的输出文件未出现，该工具返回 RENDER_OUTPUT_MISSING 并附带渲染跟踪详情。

诊断包括合成范围检查、断开连接的必要图像输入、缺失的 Loader 路径、无效的 Saver 路径、求值为 None 的表达式、未解析的工具 ID，以及可检测到的重复名称。

fusion_export_graph_tool 输出 fusionmcp.graph.v1，包含精确的工具 ID、输入 ID、安全设置、FlowView 位置、图像流连接，以及在可安全读取时的原生关键帧。

动画与表达式

原生关键帧使用 Fusion 自己的修改器：

• 标量输入使用 BezierSpline

• Point 输入使用 Path

• 表达式使用 input.SetExpression(...)

这些工具区分 static、keyframed、expression 和其他 modifier 状态。它们拒绝静默覆盖：在表达式输入上设置关键帧、在关键帧输入上设置表达式，或设置重复关键帧都会返回结构化错误。移除动画/表达式数据要求 confirm=true。

实时确认的示例：

{
  "success": true,
  "operation": "fusion_get_keyframes",
  "keyframes": [
    { "frame": 0.0, "value": 1.0 },
    { "frame": 20.0, "value": 3.0 }
  ],
  "state": {
    "state_type": "keyframed",
    "modifier_type": "BezierSpline"
  }
}

当 Fusion 接受表达式字符串但在当前帧求值为 None 时，坏表达式会被拒绝。

测试

运行单元测试和 lint：

cd /path/to/fusion-studio-mcp
.venv/bin/python -m pytest
.venv/bin/python -m ruff check src tests scripts

仅针对一次性的活动 Fusion 合成运行可选的实时测试：

RUN_FUSION_LIVE_TESTS=1 PYTHONPATH="/Applications/Blackmagic Fusion 21/Fusion.app/Contents/Libraries:src" .venv/bin/python -m pytest tests/test_live_editing.py tests/test_live_connections.py tests/test_live_animation.py -q

安全性

写入工具会故意修改活动合成。在添加更广泛的生产保护措施之前，仅对一次性或明确批准的合成使用它们。

只读检查有意不调用 Output.GetValue()，因为这可能触发上游渲染。输出检查仅读取输出属性和连接元数据。

生产合成不应用于集成测试。

独立版 Fusion Studio 21.0.2 在此项目中会将 MediaOut 视为 Resolve 专用。独立版 Fusion 不需要终端节点。Saver 在创建时不使用 AddTool 默认设置，并在创建后分配 Clip，即可作为普通独立工具受支持；创建或检查不会触发渲染。

渲染发布说明：2026-07-14 的实时隔离发现，Saver Clip 写入可以读回为有效字符串，而保存的 .comp 包含一个零跨度的内部 Clip 对象（Length = 0，GlobalStart/GlobalEnd = -2000000000）。在该状态下，comp.Render(...) 返回成功并报告帧已渲染，但不会写入文件。fusion_render_tool 不再在渲染前立即重写 Saver Clip；验证保持无副作用。

使用 scripts/diagnose_saver_initialization.py 进行实时 Saver 初始化探测。当前原始工作序列是：创建一个未锁定的新合成，在添加 Background/Saver 时锁定，创建后设置 Saver Clip，在锁定时连接，解锁，然后使用 Tool=saver 渲染。测试框架和公开的 fusion_render_tool 现在共享该事务；连续五个公开的图/验证/渲染周期成功写入了 EXR 文件。

故障排除

• Fusion 连接：确保独立版 Fusion Studio 已打开并具有活动合成。

• Python 路径：在 PYTHONPATH 中包含 Fusion 捆绑的库路径，后跟本仓库的 src。

• Saver 路径：使用绝对路径、受支持的扩展名、现有的输出文件夹，并且最好每次渲染使用唯一的文件夹。

• 权限：渲染输出目录必须可由当前 macOS 用户写入。

• 渲染被阻止：先用 fusion_validate_render_tool 验证；常见错误是 OUTPUT_DIRECTORY_MISSING、OUTPUT_ALREADY_EXISTS、SAVER_INPUT_DISCONNECTED 和 INVALID_RENDER_RANGE。

• MediaOut：独立版 Fusion Studio 在此项目中会将 MediaOut 视为 Resolve 专用；独立渲染请使用 Saver。

版本控制

项目使用语义化版本控制。当前补丁版本为 0.1.1：本地 Fusion Studio MCP 控制，带有受保护的编辑、图构建、诊断、图导出、经确认的 Saver 定向渲染，以及 macOS 干净机器验收说明。将 1.0.0 保留给在更多 Fusion/Resolve 版本和更大的真实合成上获得更广泛的生产信心。