Debug、保存与内嵌资源¶

Debug 用于验证当前蓝图或单个支持调试的节点。它会实际操作所选目标，因此开始前应确认目标、范围、账号状态和数据影响。

需要目标的 Debug 可选目标¶

ADB 专用节点只允许选择 ADB 目标。需要外部目标的 Debug 选择器提供四种目标；宏录制模式只有屏幕、范围和 ADB 三种，不能把两者混写。

选择与复用临时目标¶

启动需要目标的局部 Debug 时，若当前没有有效目标，编辑器会打开目标选择流程。选定后：

• 同一蓝图编辑会话中的录制、实时映射及需要目标的 Debug 共用该目标。
• 再次 Debug 前会验证目标仍然存在。
• 原目标消失时会清空并要求重新选择，不会自动换成另一个相似目标。
• 离开当前蓝图或切换到其他蓝图后，临时目标会被清空。
• 临时目标不会写入蓝图保存内容、导出文件或局部 Debug 快照。

首次保存尚未落盘的新蓝图不会因此清空当前目标。

完整蓝图与局部 Debug¶

完整蓝图 Debug¶

右上播放按钮会先静默保存当前蓝图，再运行完整执行路线。保存失败时不会继续。再次启动其他 Debug 前，软件会停止当前 Debug。

局部 Debug¶

部分节点、宏节点和专用编辑器提供自己的 Debug 入口。局部 Debug 会构造该节点和必要输入的临时执行数据，不等同于从开始节点运行完整蓝图，也不能证明前后路线都正确。

运行前检查与资源准备¶

开始 Debug 前，软件会检查当前已实现的基础条件，例如：

• 使用权限和蓝图是否存在。
• 蓝图是否与当前软件版本兼容。
• 是否存在可执行路线。
• 部分明显的配置问题。
• 实际引用的图像、视频和 ONNX 数据是否存在。

随后只准备当前蓝图需要的运行资源和依赖。该检查不是完整的静态分析，不能保证提前发现所有端口类型、目标状态或节点参数错误。执行失败时应按照通知中的阶段和具体原因继续排查。

Debug 与录制互斥¶

局部 Debug 按资源冲突限制操作；自动化的可视化运行与快照运行另有下节的编辑规则：

• 连续点击启动只会建立一次启动流程。
• 录制准备中或录制中不能启动 Debug。
• Debug 启动或运行中不能开始录制，也不能重新选择目标。
• 离开蓝图会取消尚未完成的启动，并停止当前 Debug。
• 录制期间，顶部操作、变量条和内嵌资源面板等会暂时禁止交互。

Debug 完成、失败或被停止时会显示通知。部分专用节点会在自己的控制区域保留最近一次状态；不要依赖顶部区域始终显示所有详细阶段。

运行期间编辑蓝图¶

本节对应 2026-09-09 开发候选源码；实际入口以当前客户端为准。

快照编辑提示为“检测到有快照正在运行中，此时修改蓝图有运行失败风险”。选择“无视风险继续编辑”继续本次操作，或“取消编辑”放弃；可勾选“不再询问”。需要恢复提示时，在设置中重新开启“快照运行中编辑时询问风险”。关闭询问只改变本机提醒偏好，编辑权与运行准入检查仍然有效。

通过 GT4AI 在快照运行期间写入时，automation.snapshot-edit.confirm 会请求你在真实客户端弹窗中作出选择。即使普通 UI 已选择“不再询问”，API 也不会自动获得永久许可；调用方不能提交“允许风险”或“不再询问”参数替你确认。一次确认仅允许对当时准确包的一次写请求；账号、登录会话、包内容或活动快照运行身份（taskId/runId 与启动时间）变化会使许可失效。取消不会执行本次编辑；写入失败或许可失效后需核对变化并重新确认，可视化运行仍禁止编辑。具体接口和版本边界见 GT4AI 使用手册。 通过 GT4AI 的 app.blueprint.open 打开蓝图时，也会要求真实风险弹窗，不受普通 UI 的“不再询问”设置影响。

运行前已加载执行快照，保存修改不会热替换正在内存中执行的正文。即使某个蓝图尚未执行，也不能据此认为它会自动读取新正文；运行期间修改公开变量同样不表示已改写当前任务快照。

从任务发起“再次运行”时，会读取最新的完整步骤顺序与蓝图正文，并把旧任务保存的公开参数映射到当前内容。公开参数删除、类型变更、单选映射值失效或步骤/参数身份歧义，都可能使重跑被拒绝；先修正不兼容项，再通过正常入口运行。

“暂停后续跑”继续原任务断点，严格验证原内容；来源正文或步骤路由改变时，会拒绝保留旧断点继续，不把它当作自动加载新内容的重跑。需要使用新版本时，应明确停止原任务并通过正常准入重新运行。再次运行的参数映射与暂停续跑的内容校验是不同规则。

保存当前蓝图¶

点击左上“保存”会写入节点内容、连线、变量、节点组、画布标注、节点位置与宽度、视口、文件名和应保留的内嵌资源。

支持新入口的客户端采用“保存”主按钮（图标在左、文字在右）及右侧下拉。主按钮始终执行普通保存；下拉按当前场景提供“增量保存到文件管理”和“保存默认布局”，选择一项就立即触发该操作，不会切换主按钮的保存模式。独立 .gmacro 等没有可用下拉项的场景不显示下拉。具体功能仍以当前客户端版本和可用状态为准。

下列情况会阻止保存：

• 正在准备录制或正在录制。
• 蓝图包含当前版本无法加载的未知节点；这是为了避免保存时覆盖未知数据。
• 宏路径、识别模板或 OCR 等存在会破坏保存结果的已知错误。
• 内嵌资源在保存期间发生冲突。

保存失败时先按界面提示定位具体节点、片段或资源，不要反复点击覆盖。

返回与未保存修改¶

从根蓝图返回时，如果检测到节点内容、连线、变量、节点组、画布标注或资源等内容修改，会提供：

• 取消
• 不保存
• 保存

仅移动节点、调整节点宽度、平移或缩放视图、修改顶部文件名时，返回提示不一定出现；这些内容在手动保存时又会正常写入。因此完成布局或改名后，应主动点击保存。

位于节点组或宏内部时，返回按钮先退出当前内部层级。录制准备或录制中不能退出宏编辑器。

保存默认布局¶

从“保存”右侧下拉选择“保存默认布局”，会立即触发把当前整张蓝图保存为以后新建蓝图使用的用户模板的操作，其中可包含节点、连线、变量、节点组、画布标注、视口和资源。

它不会代替保存当前蓝图。更新默认模板后，仍需点击“保存”写入当前文件。

打开内嵌资源管理器¶

点击左上“内嵌管理”，或按默认快捷键 N。面板显示整个蓝图实际管理的 Image、Video 和 ONNX 数据块，并按蓝图、节点组和宏等使用范围分组。

每条资源会显示：

• 名称、类型和大小。
• 引用数量与具体使用位置。
• 已使用、未使用或受保护状态。

资源可按名称或大小排序。顶部“打包导出所有内嵌资源”会把可导出的资源复制到外部文件夹；右键单条资源可执行受支持的导出、替换、映射到同类资源、保护或删除。支持新功能的客户端还会为图片显示“抠图…”；视频和 ONNX 不显示此项。操作是否可用仍受编辑权、资源状态及当前任务占用限制。

资源状态¶

图标、画布图片和宏截图都是 Image 数据块的不同使用位置，不是互相隔离的资源类型。同一张图可以被多个位置共同引用。

替换、抠图、映射、保护与删除¶

替换¶

替换会保留资源 ID 和已有引用关系，使所有使用位置继续指向新数据。替换类型必须符合资源要求。若新图片不满足蓝图图标条件，只会清空图标使用位置并回退默认图标，其他合法引用仍保留。

图片本机抠图¶

在图片上右键选择“抠图…”，复用软件已有的本机智能抠图能力，不上传图片。完成后先预览原图与彩色透明 PNG，再选择：

• 替换原资源：更新原资源数据，影响它的所有使用位置。
• 新增内嵌资源：保留原图和现有引用，另增结果图片；新结果默认受保护，避免尚未引用就被保存清理。

输出保留原图颜色，透明度由原透明度与模型遮罩共同决定。取消、推理失败或预览后未确认时不应用结果；本机缺少模型或运行依赖时按错误提示处理，不自动改用云端上传或下载新模型。细小图标、边缘和复杂背景需要检查预览，不能只因推理结束就认定质量合格。

映射到同类资源¶

右键选择“映射到同类资源…”，将源资源的全部使用位置迁移到另一条符合要求的同类资源；不是只改当前节点，也不是把目标资源的内容覆盖成源文件。确认前查看来源、目标和影响的引用范围，图片、视频与 ONNX 不可跨类型映射。

这与“替换”不同：替换保留原 ID 并更新内容，映射改变引用指向以复用现有资源。源资源不再被引用后的保留由资源状态和保护规则决定。抠图应用与映射均进入正常编辑历史；需要恢复时可撤销，完成后仍需保存并检查全部使用位置。

保护¶

保护用于保留暂时未使用、但之后还要重新分配的资源。取消保护后，如果资源仍未使用，它会在下次保存投影中被清理。

删除¶

删除会清空节点、变量、片段等使用位置的引用，并从资源列表移除数据。资源删除后不会留下可以右键“替换”的幽灵条目；需要到原使用位置重新选择资源。

删除实际被运行依赖的资源后，保存或 Debug 可能失败。先查看“使用位置”，确认影响范围。

排查顺序¶

1. 若当前局部 Debug 需要目标，确认其目标入口显示的对象与预期一致。
2. 打开内嵌管理，保护仍需保留的未使用资源；空引用则回到实际节点、变量或片段重新选择资源。
3. 检查执行路线能否从开始节点到达结束节点。
4. 保存当前蓝图，处理所有阻断通知。
5. 先局部 Debug 高风险节点，再运行完整蓝图。

更多错误处理见故障排查。