Nuke Script 算子节点

通过后台无头模式 (nuke -t) 调度执行本地已有的 .nk 合成工程脚本，并将脚本内由 Annotator 标注的 Read/Write 节点直接投射为 Griptape 画布上的强类型输入输出端口。

算子所属分类：Foundry Nuke

核心速查 (TL;DR)

将 script_path 指向本地的 .nk 文件，并在 Nuke 内部通过随附的 Griptape Annotator 面板对输入/输出节点进行可视化标注，本节点便会自动“长出”与之对应的强类型连线端口；
输入端支持接收静态图片、连续视频或原始文件绝对路径；输出端支持自动打包输出为单帧图像、图片帧序列、连续视频文件乃至三维 3D 几何体资产；
面板上的 Open in Nuke 按钮可直接在图形界面中拉起该工程，并自动装载好 Annotator 标注面板；Refresh UI 则用于热重载最新的标注元数据并重新探测本机 Nuke 安装状态；
标注信息持久化保存在与 .nk 文件同级的 <script>.gt.json 伴生旁路文件中——若检测到伴生文件时间戳落后于脚本自身，节点会贴心弹出过期黄色警告。

(上游图像/视频生成算子) → [Nuke Script 节点] → (下游渲染消费/三维资产呈现算子)

在画布中拖入一个 Nuke Script 算子节点；
将 Script Path 设置为你本机真实的 .nk 工程文件路径；
点击节点上的 Open in Nuke 按钮——系统会自动启动带有图形界面的 Nuke，并自动在视窗中加载 Griptape Annotator 扩展面板；
在 Nuke 中依次打开 Panels > Griptape Annotator：
- 切换至 Annotate 标签页，将关键的 Read 节点勾选标记为输入端口，将渲染的 Write 节点标记为输出端口；
- 可选：在 Expose 标签页中勾选需要暴露给 Griptape 调参的旋钮属性 (Knobs)；
- 点击 Save Annotations 保存标注旁路文件；
回到 Griptape Nodes 编辑器中，点击节点上的 Refresh UI 按钮——节点会瞬间根据你的标注动态生成对应的输入/输出端口；
连接上游素材，指定渲染起止帧 Frame Start / Frame End，点击 Run 即可全自动在后台调起无头 Nuke 渲染！

端口名称	数据类型	是否必填	详细功能与业务规范说明
`script_path`	`str`	是	本地 `.nk` 合成工程文件的物理绝对路径。
`<已标注的 Read 节点>`	`str \\| ImageArtifact \\| ImageUrlArtifact \\| VideoUrlArtifact \\| BlobArtifact`	否	每一个在 Nuke 中被标记为输入的 Read 节点均会生成一个专属的输入端口。若传入的是远程 URL 图像/视频凭据，引擎会在触发渲染前自动将其下载为本地临时文件并喂给 Nuke。

在 Nuke 脚本中被标记为输出的 Write 节点，在无头渲染完成后会自动出现在节点的 Outputs 分组中。输出资产类型由你在标注时指定的类型决定：

标注输出类型	Griptape 最终输出的强类型资产
`ImageArtifact` / `ImageUrlArtifact`	`ImageUrlArtifact`（单张渲染成片）
`VideoUrlArtifact`	`VideoUrlArtifact`（渲染出的连续视频文件，如 `.mp4` / `.mov`）
`ImageSequenceArtifact`	`ListArtifact` 封装的 `ImageUrlArtifact` 列表（每一帧对应一个独立资产对象）
`ThreeDUrlArtifact` / `GLTFUrlArtifact`	`ThreeDUrlArtifact`（导出的 `.obj` 或 `.glb` 三维网格文件）

参数名称	数据类型	默认值	详细业务功能与调优说明
`nuke_installation`	下拉枚举	自动检测	Nuke Version 版本下拉选择器，由环境自发现逻辑动态填充。
`frame_start`	`int`	脚本出厂默认值	无头渲染管线的起始帧（例如 `1001`）。
`frame_end`	`int`	脚本出厂默认值	无头渲染管线的结束帧（例如 `1050`）。
`<暴露的旋钮 Knobs>`	动态类型	脚本预设值	在 Annotator 面板的 Expose 标签页中勾选的参数，按原节点名分组呈现。留空则沿用脚本内已有数值；填写数值则会在本次无头渲染前就地动态覆盖（Knob Override）。

参数名称	数据类型	默认值	详细功能说明
`nuke_executable`	`str`	`""`	显式指定特定的 Nuke 可执行文件绝对路径；仅覆盖当前节点的运行环境，超越全局设置。
`baked_script_path`	`str`	`""`	烘焙固化后的 `.nk` 脚本存储目标路径。
`save_baked_copy`	按钮	—	点击后，将当前所有被覆盖的旋钮参数硬编码持久化写入一份新的 `.nk` 副本中，便于归档备份或在离线排查时移交特效总监。

在 Nuke 中修改脚本后必须重新保存标注：若你在保存标注后又在 Nuke 中大幅修改了合成树，节点会弹出警告提示 <script>.gt.json 伴生文件可能已过时——请在 Nuke 中重新点击一次 Save Annotations 以刷新时间戳。
端口仅在完成标注后显现：刚拖入节点并填入路径时，由于尚未读取标注，节点表面是没有任何动态输入输出端口的；请务必在 Nuke 中完成标注并点击 Refresh UI。
渲染前确保许可证可通达：在 Griptape 的 Secrets 面板中妥善配置 foundry_LICENSE；无头后台执行如果无法连接 RLM 许可证服务器会导致进程静默退出或报错阻断。
显式锁定 Nuke 构建版本：在生产管线中，不要依赖操作系统的默认 PATH；在 nuke_installation 下拉框中精确锁定 Nuke 的版本（如 Nuke 15.1v2），以杜绝因合成算法微小升级带来的跨平台画面渲染抖动。