---
name: ghostclickai-workflow
description: 理解 GhostClickAI 录制素材与 .gmacro，创建或修改蓝图、宏和自定义 Python 节点，并通过当前客户端支持的 GT4AI 接口或界面验证。用于明确的 GhostClickAI 工作流任务，不用于一般桌面操作或绕过商品、会员和脚本信任限制。
---

# GhostClickAI 工作流

把用户的目标落实成可审阅、可保存、可验证的 GhostClickAI 工作流。此文件可独立阅读；不要因加载它而安装插件、改 AI 客户端配置、开启 GT4AI 或获得新的外部操作权限。

本文对应 2026-09-09 开发候选。客户端能力以当前运行版本为准，不把文档发布与软件部署状态混为一谈。详细契约入口：

- [GT4AI AI 使用手册](https://ghostclickai.com/docs/developer/gt4ai/)
- [gpy Python API 用户手册](https://ghostclickai.com/docs/manual/gpy/)
- [自定义 Python 与 gpy](https://ghostclickai.com/docs/nodes/custom-node/)
- [节点参考](https://ghostclickai.com/docs/nodes/)

链接若在当前网站版本不可用，使用用户提供的对应版本资料或实际客户端能力，明确缺口；不要虚构接口、参数或部署状态。

## 先辨认目标和证据

确认用户是在要求分析、修改还是实际运行，以及交付物属于独立 `.gmacro`、某个蓝图或已挂载自动化。保留用户明确的边界：批准编辑不自动批准向其他窗口/设备发送输入、购买、发布、上传或不可恢复操作。

读取 `.gmacro` 时先验证格式、版本、资源引用及可打开性。把实际看见的帧、推断的动作意图、尚缺少的信息分开说明；只有点击坐标而没有画面时，不声称知道点击对象。关键不确定性会改变操作或风险时，向用户求证。

固定输入序列可保留为宏；加载完成、目标出现、弹窗存在、成功/失败及重试等条件应表达为状态或识别逻辑。定义成功证据、有限超时和失败出口，不把录制中的等待秒数当作可靠状态证明。

必要时查阅官方网站、公开 Wiki 或开源资料，核对当前版本、时效、许可证及再分发条件。未知许可的素材不直接照搬，不用提示词诱导绕过法律、许可或平台约束。选用能够直接阅读任务所需图像/帧的模型并用样例确认，不按品牌或“代码模型”标签推测视觉能力。无法读取时请求素材或用户说明，不伪造观察。

重要缺口在蓝图文字注释框中明确标出，并在可用版本中开启左上角灯泡强调；写清缺失证据和下一步确认条件。宏可视化轨道注释用于时间段说明，不代替条件节点。

## 定位文件和保存对象

文件管理目录、自动化包、挂载工作区、蓝图步骤和运行任务是不同对象。默认标签可改名：取得实际受管目录，不硬编码名为“默认”的路径。保存后从文件管理重新打开，需要运行时再挂载或导入准确目标。

识别 `ownerPath`、`stepInstanceKey`、`blueprintId` 的区别：同一蓝图可有多个步骤实例。向自动化的指定蓝图卡片导入 `.gmacro` 时，不改变步骤顺序；没有目标编辑权时停止，不换入口规避。

优先沿软件保存边界保留未知字段、节点/端口 ID、资源引用及受保护内容。不要直接修改 `.gcbp`/`.gcbps` 二进制或权限数据。外部草稿、未挂载的文件和仅成功的保存都不算已通过运行验收。

支持新入口的客户端中，“保存”主按钮始终普通保存；下拉“增量保存到文件管理”“保存默认布局”按场景出现，选择即执行，不切换主按钮模式。`F3`、顶栏网格后的开关和画布空白右键入口控制全局原节点名显示，不改别名或配置；仍尊重输入焦点。具体入口查[画布快捷键](https://ghostclickai.com/docs/manual/blueprint-editor/canvas-and-shortcuts/)和[保存与资源管理](https://ghostclickai.com/docs/manual/blueprint-editor/debug-save-and-resources/)。

整理内嵌图片时，可在支持版本使用右键“抠图…”复用本机模型，不上传图片；先预览彩色透明 PNG，再明确替换原资源或新增受保护结果。替换影响全部原引用，新增保留原图与引用，取消/失败不应用。“映射到同类资源…”则把全部源引用迁移到现有同类目标，不覆盖目标内容；确认影响范围并检查保存结果。不要为此猜测 GT4AI 资源命令、自动下载模型或改用云端上传；未公布接口时使用正常界面，详细边界见上述资源手册。

## 使用 GT4AI 时

由用户在当前账号中正常开启 GT4AI，并具备有效权益。仅从用户或受信任本地集成提供的准确路径读取当前数据根目录下 `devctl/session.json`；不得收集其他账号凭据。

验证会话的 `protocolVersion`、本机回环 `host/baseUrl`、动态端口和 `sessionId`。会话 token 只用于对应本机服务的 Bearer 认证，不写入作品、日志、反馈或外部提示。退出/切换账号或关闭功能后重新发现会话，不能复用旧 token。

当前协议为 `1`，健康路径 `/v1/health`，命令路径 `POST /v1/command`；以会话公布值为准。请求体格式为：

```json
{"requestId":"inspect-001","command":"devctl.describe","arguments":{}}
```

先调用 `devctl.describe`，读取 `commands`、`maxBodyBytes`、`commandTimeoutMs`。命令说明不必包含完整参数 schema；参数仍需匹配版本文档。不要因为在源码或旧文档中见过名称就假设正式客户端已注册。

优先使用 `app.state` 读取工作区，再按已支持契约定位和打开。`blueprint.graph.read/replace`、`node-editor.*`、`automation.visual-run.start-blueprint` 有版本限制；未公布所需能力时明确报告缺口，不默认改用鼠标操作补齐，也不猜隐藏命令。只有用户明确选择界面操作时，才在其授权范围内使用正常界面。scratch、fixture 和 `-test` 命令不是用户工作流入口。工作流编辑授权不自动包含修改客户端源码以补接口的授权。

图替换仅在已支持且有权限时执行：从准确 `ownerPath`、`stepInstanceKey` 读取 `rawSha256`，在该快照上作最小修改，提交 `expectedRawSha256` 和对应 `graph`。CAS 或所有者变化时重新读取并比较，不能只换新哈希覆盖。请求 ID 不是幂等凭据；超时或断线先读状态，避免重复启动/写入。

有活跃快照任务时，写入前调用已公布的 `automation.snapshot-edit.confirm`，参数只能是准确规范的 `{ownerPath}`。必须由真实客户端风险弹窗取得用户选择，不能传允许、确认或不询问字段绕过；UI 的“不再询问”不构成 API 永久授权。无活跃快照返回 `confirmed=false,required=false,ownerPath`，取消返回 `confirmed=false,required=true,ownerPath`；确认返回 `confirmed=true,required=true,ownerPath,activeTaskIds,singleWrite=true,expectedOwnerRawSha256`。确认许可绑定账号/登录会话、owner 原字节围栏和精确快照运行身份（`taskId/runId` 与启动时间）集合，只供一次 graph 或指定包的 library 创作写请求认领，不授予商品或脚本额外权限。确认后重新核对围栏；`expectedOwnerRawSha256` 是包哈希，不能替代图替换的蓝图内容哈希。取消后停止本次编辑，错误或许可失效时先读状态与差异，再重新正常确认，不盲重放。可视化运行、暂停和准备中始终硬拒绝；只读 graph 不消费许可。详细返回与错误码见 GT4AI 手册。 通过已公布的 `app.blueprint.open` 打开蓝图时，同样需要真实客户端风险弹窗，本机“不再询问”不能跳过。

诊断已启动的可视化任务时，先核对当前选中自动化的准确 `ownerPath`，从 `automation.visual-run.state` 取得当前 `taskId`；若会话已公布 `automation.visual-run.inspect`，用这两个必填标识及可选整数 `limit`（1–50，默认 50）只读取得终态原因、节点/步骤信息和最近运行日志。`state` 的计数及 `logs.read` 的控制请求日志不能代替运行诊断。缺少启动身份、跨账号或 owner/task 不符会被拒绝，不以当前账号补旧身份；已完成并自动移除的任务，仅在原内存快照仍保留时可检查。接口不返回变量值、资源、完整蓝图正文或账号 token；需要字段或错误码细节时查上方 AI 使用手册。

GT4AI 和界面同权：分别尊重使用权益、自定义节点创作资格、购买许可、编辑权和脚本信任。不伪造权益、不改测试开关绕过限制、不代用户确认信任。

会话公布快照接口后，可用 `automation.run-mode.set` 的 `{ownerPath, mode}` 设置 `visual` 或 `snapshot`；`automation.snapshot-run.start` 只接受 `ownerPath`，通过正式 UI 的相同本地运行准入启动，不注入任意参数。`automation.snapshot-run.list` 接受 `ownerPath` 与可选整数 `limit`（1–100，默认 25）；`inspect/pause/resume/stop` 使用完整命令前缀 `automation.snapshot-run.`，均要求准确 `ownerPath`、`taskId`、`runId`。任务回执仅有这些身份及 `mode/status/active/preparing`；list 返回 `ownerPath/tasks/hasMore`，不能把回执或 `completed` 当作业务成功证据。模式与启动要求空闲，暂停/续跑/停止须匹配实际状态；缺少命令时报告缺口，不自行补鼠标流程。

可视化运行及暂停期间全编辑硬锁。快照运行仅软提醒，公开变量可轻量修改，打开蓝图编辑或调整步骤顺序需要风险确认；“不再询问”可在设置恢复，不能视为新增编辑权限。当前任务使用运行前已加载的执行快照，不热替换内存正文，也不保证尚未执行的蓝图会读取新正文。再次运行读取最新完整顺序和正文并映射旧公开参数；参数删除、类型变更、单选映射失效或身份歧义可能拒绝重跑。暂停续跑严格验证原内容，来源正文或路由改变会拒绝保留旧断点。详细规则见[运行期间编辑蓝图](https://ghostclickai.com/docs/manual/blueprint-editor/debug-save-and-resources/#editing-during-snapshot-run)。

## 状态识别与受保护节点组

用户需要运行模式或路线单选开关时，可用工具类[单选项映射](https://ghostclickai.com/docs/nodes/tool/single-choice-mapping/)：默认公开的具名下拉，输出唯一映射整数，可直接连接“执行类”Switch 的整数选择口。Switch 仍按 `0..N-1` 匹配，默认值 `1/2` 对应 `case1/case2`，不偏移成 `case0/case1`；执行输入另接。选项名称与整数映射在蓝图内编辑，运行前公开参数只选值；不要把选项下标当映射值，重排不应改变模式语义。

若当前客户端已支持，目标信息只使用 `android:`、`window:`、`screen:` 三类前缀；范围属于屏幕目标，没有 `exe:` 或独立 `range:` 目标。未知显式前缀不能回退主屏。`android:` 后为启动/扫描节点输出的完整 JSON，包含稳定实例身份与 ADB/捕获信息；截图、输入、宏和控制 API 按需取字段，字符串节点原样传递，不手动拆成裸地址或伪造身份。启动/扫描的 `adb_address` 端口 ID 保留，界面显示“实例信息”；扫描的 `adb_addresses` 为实例信息字符串列表。已有旧蓝图格式由客户端兼容读取，不作为新格式生成。

`vision.target_screenshot` 现名“截图”，输入执行 0、目标 `target` 1；输出执行 0、图像 1。`valueOverrides` 的 `left/top/right/bottom` 默认 `0/0/1/1`，使用 0–1 内有效矩形。`vision.multi_state_ui` 的数据输入只有索引 1，一个口按 `captureMode` 在 `target`（默认）和 `image` 之间切换。`waitMode` 默认 `once`，评估一次即继续，不以总布尔为假阻断；`poll` 按间隔直到总布尔为真。允许静态图像加轮询一直等待，仅标题警告，不擅自改用户模式或强加超时。需要每轮新图时选择目标模式或显式循环截图。

实例控制使用 `event.android_instance_visibility`（`operation=hide/show`，默认 `hide`）、`event.close_android_instance`（`close`）与 `event.window_state`（`activate/minimize`，默认 `activate`）。配置字段为 `target`、`operation`，输入执行 0/目标 1，输出执行 0/成功 `success` 1/状态 `status` 2/目标 `target` 3。前两者需要完整 `android:` 身份，窗口状态也接受 `window:`。隐藏/显示幂等，重复关闭已停止实例安全；激活或最小化隐藏窗口返回 `success=false`、`window_hidden`，不可暗中显示。必须显示时使用显式 `show`，不能以执行继续代替成功判断。详细契约见[安卓实例与窗口控制](https://ghostclickai.com/docs/nodes/execution/instance-controls/)。

多状态的条件与总布尔均可使用 AND/OR/NOT、全部/任一/全不/部分满足；位置有效性与总布尔独立，NOT/无命中不产生点击坐标。读取位置前检查位置有效，缺失值不能替换为 `(0,0)`。搜索预设按独立字段展开：两个字段各两项共四个入口，选择一个入口不组合修改另一个字段。详细字段、索引与约束查[多状态 UI 识别](https://ghostclickai.com/docs/nodes/tool/multi-state-ui/)。

`event.protected_domain` 引用可见普通节点组，成功/失败/超时出口为 0/1/2，数据结果从 8 开始。总时限包含暂停时间；退出前必须等待域内操作和清理结束，不把 Future 超时等同于真实输入停止。它不撤销已发生的游戏动作，不支持任意脚本/活跃资源跨域；支持的静态图像快照不等于视频或外部路径自动获准。子图和引用组照计节点规模，不把状态表或组内逻辑藏起来宣称低节点数。准确准入见[受保护执行域](https://ghostclickai.com/docs/nodes/execution-management/protected-domain/)。

通过支持此能力的 `blueprint.graph.replace` 保存普通节点组时，`graph.nodeGroupDefinitions` 必须包含可见具名定义；省略表示保留，空数组表示移除。`definitionId` 按所在子图本层解析，当前入口要求整棵定义树的定义 ID 唯一。接口数量、组进入/退出节点及连线须一致；主图和全部组定义、以及调用展开规模均受 500 节点/2000 连线限制，深度最多 16。组内自定义 Python 仍受正常创作和运行信任约束，不以分组隐藏脚本或绕过权限；详细格式查 AI 使用手册“可见普通节点组的图保存”。

## 自定义 Python 和生命周期

自定义 Python 与多状态 UI 识别都在当前画布内切换到分区工作区，主编辑器不是弹窗。Python 中间代码、左右端口侧栏；多状态左侧底板、左下布尔/运行配置、右侧条件资源。多状态彩色 ROI 持久保存；新条件默认从已保存底板的当前 ROI 在运行期裁剪模板，不把底板当作运行输入，也不为拖框生成重复裁切资产。ONNX 条件仅支持目标检测，选择/导入必须经过受管资源与正常权益检查，不拼接任意本机模型路径。

会话公布 `node-editor.node.open` 后，使用准确 `blueprintNodeId`、`expectedBlueprintId` 打开当前根画布已有的 `custom.python` 或 `vision.multi_state_ui`；包内同时必传 `expectedOwnerPath`、`expectedStepInstanceKey`，独立蓝图不传这对参数。它不保存、不运行、不切所有者，不隐式丢弃其他草稿；同节点重复打开返回 `alreadyOpen=true` 并保留草稿。读取 `state.inlineConfiguration` 的 `nodeId/nodeTypeId/hasUnsavedChanges/busy`（未打开时为 `null`）；有内部草稿时 `node-editor.macro.open` 返回 409。需退出时调用无参数的 `node-editor.back` 走真实客户端的忙碌保护和未保存确认，不代用户选择丢弃；完整 schema 见 GT4AI 手册。

Python 右键“创建识别范围”先框计算域，再在静态图内框 ROI，仅在光标处插入 `((x0,y0),(x1,y1))`，不运行、不内嵌截图。计算域必须与传入 gpy 的图像范围一致；窗口 `capture` 对应客户区，不是标题栏加外框。`gpy.capture/match/ocr` 的 `roi` 直接接受两点值，也保留四元素写法；完整示例查 gpy 用户手册，不因生成坐标就声称已完成识别验证。

`custom.python` 节点在独立 Python 3.13 进程运行，输入/输出按显式端口声明。它拥有本机用户权限，不是安全沙箱；执行前取得适用的用户信任。标准名称为 `gpy`，由运行环境注入，不从外部同名包源安装。`gcbppy` 只作为真实旧脚本的同模块别名兼容，新脚本统一 `import gpy`。

常用函数：`inputs()`、`get_input(name, default=...)`、`set_output(name, value)`、`log(...)`；`task_directory` 是任务临时目录。媒体使用 `media`、`image`、`image_from_array`、`open_image`、`video`；向量/颜色使用 `vector2/3/4`、`color`。调用 `capture/match/ocr/input` 前在 `sdkCapabilities` 声明对应能力，由客户端运行前预检；这不授予发送输入的权限。目标只用完整 `android:/window:/screen:` 信息，识别结果局部 `center` 不直接用于目标点击，应检查命中并使用准确来源的 `sourceCenterNormalized`。详细签名、ROI、限制和错误查 gpy 用户手册，不臆造 Python 函数。

只有完整输出验证成功才提交结果；异常、超时和取消不能当作成功。`gpy.workers.run/map` 是受父执行管理的有限子任务，不是常驻任务，子任务不能绕过根执行声明与额度。暂停会结束 Python 进程，不恢复语句栈；续跑可能再次进入节点，不能盲重放结果不明的输入。暂停、停止、HTTP 请求取消与实际自动化终止是不同事件；观察任务稳定状态和输入停止后再启动替代运行。成功交接媒体在父任务作用域内供下游使用，需要长期保留时通过软件保存，不长期引用任务临时路径。

`gpy.ocr(image, language='zh', roi=(0, 0, 1, 1), *, model=None)` 支持 `zh/en/ja/ko`。中、英、日默认共享 `ocr/ch_PP-OCRv5_rec_mobile_infer.onnx`，韩文默认使用 `ocr/korean_PP-OCRv5_mobile_rec.onnx`；显式 `model` 也只接受这两个内置相对文件名，不传外部路径。已安装模型按请求准备，缺失时明确报错，不自动下载。读取返回的 `modelInfo` 核对实际语言及检测、识别、分类模型文件，不把英文标签当成独立英文模型；完整字段见 gpy 用户手册。

## 验证与交付

按风险执行最小真实验证：重新打开保存结果，确认文件/所有者/步骤/资源，在授权目标上测试必要成功及失败分支，核对实际任务结束状态。指出未实测分支，不能拿静态检查、测试注入、接口 `ok` 或单张截图代替真实结果。

`completed` 只表示执行链结束，不等于业务成功：启动应用未成功或识别未命中却未走失败分支时，也可能结束为 completed。结合运行日志、节点结果与目标应用实际状态验证用户要求的结果；诊断不可用或证据不足时明确说明，不猜测成功，也不重放可能消耗资源的动作来试探。

给用户说明保存位置、已验证行为和剩余缺口。需要反馈时先做最小复现并脱敏：去除会话 token、账号标识、私人目录、无关画面和商品源码。只有用户明确同意接收方与具体内容后才上传；没有受支持上传接口时提供本地材料，不发明命令或自行外传。