自定义 Python 节点与 gpy¶

节点类型 ID：custom.python。以下内容按 2026-09-09 开发候选源码编写；使用前确认当前客户端存在该节点、所需 Python 运行时可用且账号允许相关创作操作。这里不承诺所有已安装版本均已提供此节点。

它用于把输入值交给 Python，完整执行后提交输出值。已有节点能直接表达的逻辑，通常不需要改成脚本。脚本可以导入模块并拥有本机用户权限，不是安全沙箱；只运行用户已审阅并信任的内容。

编辑与执行¶

完整 API 见用户手册中的 gpy Python API，包括截图、匹配、OCR、目标输入、坐标映射和限额。旧脚本的 gcbppy 是同一模块的兼容别名；新脚本使用 gpy。

在节点画布中添加“自定义 Python”；具体菜单分类随当前节点目录展示。双击后，当前画布切换为内部分区编辑工作区，不是承载整个编辑器的弹窗：中间是代码，左右是可收起的端口声明侧栏，端口 API 提示按需展开。通过顶栏返回或保存，保存本身不执行脚本。
输入和输出的名字是节点内私有变量名，不是蓝图公共变量名。每侧最多 64 个数据端口。
每个端口有稳定 id、name、typeId 和可选默认值。不要仅凭界面行号重新生成 ID，以免破坏连线。
执行输入触发一次脚本运行。输入从数据连线/默认值取得；脚本结束且所有输出验证成功后，整体提交结果并继续执行输出。
脚本报错、类型错误、输出过大、超时或取消时不提交半份输出。没有显式设置的已声明输出保留其默认值。
每次调用创建独立 Python 3.13 进程；不要假设上次调用的全局变量仍存在。通过蓝图变量或显式文件持久化的行为，应在用户授权范围内另行设计。

代码区右键“创建识别范围”先框选计算域，再在静态截图中框选 ROI，插入 ((x0, y0), (x1, y1))，不执行脚本、不内嵌截图。计算域要与实际传入 gpy 的图像一致；窗口截图对应客户区，不含标题栏与外框。生成的两点值可直接传给 gpy.capture/match/ocr 的 roi 参数，完整步骤和示例见创建识别范围。

声明限制¶

端口 ID 使用 1–64 个字母、数字、下划线或连字符，每侧不得重复，且不得使用执行端口保留 ID exec_in、exec_out。私有变量名不得为空、不得含控制字符，同侧不得重复，最长 128 个字符。输入与输出可以分别声明同名变量，但读取和写入仍由不同函数区分。

配置键为 customPythonConfig，内含 inputs、outputs、script、timeoutMillis、可选 sdkCapabilities。默认超时 30,000 毫秒，可配置范围是 100–3,600,000 毫秒。脚本 UTF-8 内容最多 1 MiB，单个 JSON 默认值最多 1 MiB；顶层请求和响应有 16 MiB 传输上限。不要把这些上限用满作为设计目标。

数据类型¶

编辑器中的截图、匹配、OCR、输入勾选项对应 sdkCapabilities 的 capture/match/ocr/input。省略或空列表不声明宿主能力；该列表用于运行前预检，不是安全沙箱或新的操作授权。详细准备条件见 gpy 能力声明。

`typeId`	Python 值与注意事项
`string`	`str`；默认空字符串
`integer`	`int`，布尔值不是整数输入的替代品
`number`	有限数值；不要输出 NaN 或无穷大
`bool`	`bool`
`vector2` / `vector3` / `vector4`	`gpy.vector2/3/4` 构造的带类型值；字段为 `x/y/z/w`
`color`	`gpy.color`，`r/g/b/a` 为 0–255 整数
`vector2_array`	二维点集，携带 `points`、`coordinateSpace` 和 `metadata`；保留坐标空间
`array`	支持的可序列化数组；需要保留类型的向量/颜色元素用 gpy 构造函数
`visual_media`	gpy 媒体描述值或 `None`；不是任意 Python 对象或裸路径字符串

类型桥有明确校验，不会把不兼容值自动转成字符串。输入返回独立拷贝，修改输入对象不会自动写回蓝图；要调用 set_output。

基础函数¶

函数 / 属性	含义
`gpy.inputs()`	取得全部声明输入的深拷贝字典
`gpy.get_input(name, default=...)`	读取输入；未知名字无显式默认值时抛出 `KeyError`
`gpy.set_output(name, value)`	设置已声明输出并检查类型；未知名字抛出 `KeyError`
`gpy.log(...)`	输出可见日志；不要写入凭据或私人素材
`gpy.task_directory`	本次执行的临时工作目录字符串；不是永久保存位置
`gpy.vector2(x=0, y=0)`	构造二维带类型值
`gpy.vector3(x=0, y=0, z=0)`	构造三维带类型值
`gpy.vector4(x=0, y=0, z=0, w=0)`	构造四维带类型值
`gpy.color(r=0, g=0, b=0, a=255)`	构造带类型颜色

以下例子要求先声明整数输入 count 和整数输出 next_count：

import gpy

count = gpy.get_input("count")
gpy.set_output("next_count", count + 1)

gpy 由节点执行环境注入，不是要求用户从名称相同的外部包源安装的依赖。不要随意 pip install gpy。

图像与视频函数¶

函数	输入与返回
`gpy.media(path, kind=None)`	验证真实文件并返回媒体描述；`kind` 为 `image` 或 `video`，省略时探测
`gpy.image(width, height, color=(0, 0, 0, 0))`	创建 RGBA 图像，返回媒体描述
`gpy.image_from_array(array)`	从 NumPy `uint8` 灰度、RGB 或 RGBA 数组创建图像
`gpy.open_image(value)`	从图像媒体取得独立 Pillow 图像对象，调用方负责关闭
`gpy.video(frames, fps=30)`	从同尺寸 RGB/RGBA 数组或图像媒体生成视频，返回媒体描述

图像单帧不超过 6,400 万像素。视频帧率大于 0 且不高于 240，最多 100,000 帧，至少一帧；受总超时、内存、编码器及传输限制，不代表这些边界组合一定能在本机完成。Pillow、NumPy、OpenCV 由当前组件环境决定，缺失时先按软件提示处理依赖。

示例要求图像输入 source 和 visual_media 输出 result：

import gpy

with gpy.open_image(gpy.get_input("source")) as image:
    image.thumbnail((640, 640))
    output_path = gpy.task_directory + "/thumbnail.png"
    image.save(output_path)

gpy.set_output("result", gpy.media(output_path, "image"))

输出媒体要通过类型桥交还客户端，不把临时路径写成外部长期引用。需要长期使用时，通过软件资源保存/导出功能复制到用户授权的有效目录。输入中的缺失文件、错误媒体类型或无效图像都应作为错误处理，而不是伪造一个已成功的输出描述。

受管 worker¶

gpy.workers 适合有界子任务。它继承父节点剩余时限，生命周期属于父执行，不是常驻后台服务。

import gpy

result = gpy.workers.run(
    script='import gpy\ngpy.set_output("answer", gpy.get_input("n") * 2)',
    inputs={"n": 5},
    outputs={"answer": "integer"},
    input_types={"n": "integer"},
    timeout_millis=1000,
)
gpy.log(result["answer"])

真实函数签名：

# 下面是签名说明，不是可独立执行的函数定义。
# workers.run(script, inputs=None, outputs=None,
#             input_types=None, timeout_millis=None)
# workers.map(script, items, outputs, input_types=None, max_workers=4)

run 返回按输出名称组织的字典；outputs 的值可以是类型 ID，也可以是含 typeId、defaultValue 的声明字典。
map 的 items 是输入字典序列，按输入顺序返回结果，单批最多 64 项，并发范围 1–4。
每个父 worker 同时最多 4 个直接子 worker，嵌套最多 2 层；这不是整棵进程树最多 4 个进程的承诺。普通数字、字符串等可推断输入类型，歧义值应显式传 input_types。
子 worker 失败或超时会抛出异常；不要忽略它再宣称整个节点成功。
父节点结束、取消或控制通道断开后，受管子 worker 会被停止。程序主动绕开 gpy.workers 自行创建后台进程不属于此受支持的生命周期契约。

停止、资源和安全¶

客户端为本次执行注册进程与临时目录清理，取消和超时会终止相关进程并回收其拥有的资源。不要依赖 finally 一定能完成所有外部副作用：进程被强制终止时，已写出的外部文件、已经发送的网络请求或目标操作不会自动回滚。

不要让脚本访问账号 token、擅自上传输入素材、修改系统安全设置或读取任务无关文件。运行信任与创作会员权益分别处理；购买许可也不等于用户批准执行任意脚本。GT4AI 手册适用于 AI 辅助编写、保存及验证这些节点。