GT4AI：AI 使用手册¶

GT4AI 是 GhostClickAI 的本地 AI 协作入口。它帮助外部 AI 读取当前工作区、理解录制素材，并在与用户界面相同的权限边界内操作。它不是云端 API Key，也不会自动赋予购买内容的编辑权、会员功能或脚本运行信任。

本页按 2026-09-08 开发候选源码编写。已安装客户端可能尚未包含部分功能；命令能否调用必须先查询当前会话的 devctl.describe。文档构建或源码实现完成不等于网站已部署，也不等于所有命令已进入正式版。

下载单文件 ghostclickai-workflow/SKILL.md

下载内容是带 YAML 元信息的原始 UTF-8 Markdown，可交给支持技能文件的 AI 客户端或作为任务上下文阅读。下载不会安装插件，不会修改 AI 客户端配置，也不会开启 GT4AI。先审阅内容，再由用户选择如何使用。

1. 先明确交付物和操作范围¶

接到“把录制改成可靠自动化”时，先确认目标、完成条件和可操作对象，而不是直接增加延迟或堆叠点击。通常需要区分：

• 用户只要求分析，还是允许修改宏、节点图及运行测试。
• 目标是独立 .gmacro、某个蓝图，还是一个已经挂载的自动化。
• 是否允许向真实窗口或设备发送输入；是否涉及支付、购买、发布、删除或上传。
• 失败后应停止、等待用户，还是在限定次数内重试。

正常保存和已授权范围内的小规模验证可以继续执行；新外部目标、上传、购买或不可恢复的操作需要单独的明确授权。不要把“完成自动化”理解成可以自动扩大操作范围。

2. 文件和工作区不是同一层¶

独立宏可在文件管理中创建并双击编辑。把受管宏拖到自动化的指定蓝图步骤卡片时，宏内容导入该目标蓝图，不应改变自动化顺序。目标没有编辑权时必须停止；“导入失败：无编辑权”不是应该绕过的格式错误。

保存到实际有效的受管目录后，重新从文件管理打开；需要在自动化中运行时再挂载或导入准确的目标步骤。只把文件写到临时目录或外部下载目录，不算已经接入用户工作区。目录、文件和步骤标识分别记录，不根据名称猜测它们之间的关系。

在支持新入口的客户端，左上“保存”主按钮始终普通保存；右侧下拉按场景提供“增量保存到文件管理”和“保存默认布局”，选中即执行，不把主按钮切换成另一种保存模式。默认 F3、网格按钮后的开关和画布空白右键入口控制同一个全局原节点名显示选项，不改用户别名或节点配置。入口及焦点边界见画布快捷键和保存说明。

相关操作见文件管理、宏导入与导出和运行任务管理。

3. 判断录制信息是否足够¶

先检查文件，再解释含义¶

.gmacro 有格式与版本校验，包含时间线、内部节点图及可能的图像、视频、ONNX 资源。不要只看扩展名就执行，也不要仅凭操作坐标声称看见了按钮。检查文件能否由当前客户端打开、资源引用是否完整、录制的目标与分辨率是否明确。

区分三类信息：

1. 直接观察：实际帧中出现了什么、何时收到输入、哪个条件确实成立。
2. 推断：某个点击可能用于关闭弹窗、某段等待可能是在加载。
3. 缺口：缺少关键帧、失败状态、成功条件，或目标应用版本不明。

把关键推断向用户简短说明。若不同解释会改变后续操作、识别条件或风险，先求证；不要把低置信度猜测保存成无条件动作。

区分固定动作与状态逻辑¶

固定路径、按键组合和已知时序适合保留在宏中。页面是否加载完成、弹窗是否存在、目标是否出现、是否应重试，通常需要蓝图条件、识别和有界循环。一次录制的等待时间不是稳定的状态判断。

为识别明确目标区域、候选内容、成功证据、超时与失败出口；不要只用“等几秒再继续”掩盖未知状态。把超时设为失败或人工接管，不无限重复可能产生外部副作用的动作。

运行模式单选可用工具类单选项映射，将整数输出直接连接“执行类”切换整型的选择值输入。Switch 仍按 0..N-1 匹配，默认单选值 1/2 对应 case1/case2，不自动偏移成 case0/case1；选项名称不参与分支编号，执行输入仍须另接。

用可复核的素材补齐缺口¶

当前开发候选新增多状态 UI 识别、截图和受保护执行域。前两者可将统一目标字符串与静态图像值分开组合；多状态识别默认一次性，轮询直到总布尔为真。静态图片加轮询是允许的等待设计，不擅自拒绝或改写用户模式。受保护域为可见节点组设置总时限，但不回滚已经发生的外部动作。类型和端口必须按当前客户端确认，不能把旧候选的两个独立输入口或普通组端口偏移套用到新节点。

目标信息使用 android:、window:、screen: 三类前缀。android: 是启动/扫描输出的完整 JSON 实例身份与连接信息，读取 API 自动取所需字段；字符串节点原样传递。范围属于屏幕目标，没有 exe: 或独立 range: 目标，未知显式前缀不能回退主屏。截图默认归一化范围为 (0,0) 到 (1,1)。新增安卓实例与窗口控制包含幂等隐藏/显示、安全重复关闭、激活/最小化；隐藏窗口返回 window_hidden，必须显式显示后才可激活。准确类型 ID、参数和端口见该页与节点目录。

• 可补充官方网站、公开 Wiki 或开源示例；记录来源、版本或访问时间，并与当前目标界面核对。
• 使用外部代码、图像、模型或数据前核对许可证和再分发条件；不照搬来源或许可不明的素材，不用提示词诱导 AI 绕开法律、许可或平台约束。
• 选择能直接读取所需图像或视频帧的模型，并用实际样例确认能力。不按品牌、产品名称或“代码模型”标签臆断视觉能力。
• 纯文本模型只能依据已有描述推理；无法查看素材时，应要求补充图片、逐帧观察或用户说明，不能伪造识别结果。

对尚未确认的重要步骤，在蓝图上添加文字注释框并开启左上角灯泡强调，写清“缺少什么证据、需要谁确认、满足什么条件才继续”。宏可视化轨道中的注释适合标注某个时间段，显示在预览画面外侧；不要用它替代真正的条件逻辑。

在内嵌资源中整理图片和引用¶

支持此功能的客户端可从图片右键“抠图…”调用已有本机智能抠图能力，不上传图片。先预览彩色透明 PNG，再选择替换原资源或新增受保护的内嵌图片；取消、失败或未确认不修改资源。替换影响原图全部使用处，新增保留原图与现有引用。不要把本机模型能力描述成已部署云端逐字节相同的输出，也不为补齐依赖自动上传或下载模型。

“映射到同类资源…”将全部源引用迁移到现有同类目标，与保留原 ID、更新内容的“替换”不同。确认影响范围，完成后检查使用位置并保存，必要时沿编辑历史撤销。详细步骤见资源管理。这些是编辑器入口，不表示新增了 GT4AI 资源命令；仍先查询当前 devctl.describe，不猜测抠图或映射接口。

4. GT4AI 会话和能力探测¶

开启和发现¶

用户须在当前账号下开启客户端的 GT4AI 设置，并具备有效使用权益。退出账号、切换账号或关闭设置后，不应继续使用旧会话。

客户端会在其当前数据根目录下写入 devctl/session.json。根目录由实际安装及数据配置决定，不能根据本页示例猜测。由用户或受信任的本地集成提供准确文件位置；不要搜索、导出其他账号的凭据。

会话文件包含 protocolVersion、sessionId、pid、host、port、baseUrl、token、startedAt、healthPath 和 commandPath。当前服务只绑定 127.0.0.1，使用动态端口。令牌属于这次本机会话，不应写进宏、脚本、日志、反馈或网页。

连接前检查 host 与 baseUrl 是本机回环地址、协议版本可识别、端口及进程属于预期客户端。先用会话声明的健康地址确认 sessionId，再探测命令。令牌失效时让用户恢复正常登录或开启状态，不伪造权益、不改开发环境变量来绕过门禁。

请求与响应¶

当前协议版本为 1，命令入口为 POST /v1/command。请求使用 Content-Type: application/json 和 Authorization: Bearer <当前会话 token>。下面是请求体示例，不含真实凭据：

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

requestId 是 1–128 个允许的 ASCII 字符，字符集为字母、数字、点、下划线、冒号和连字符。它用于关联响应与日志，不构成幂等性承诺。请求超时或断线后，先读取当前状态，再判断是否应重试写入或运行。

成功响应包含 version、requestId、ok: true 和 result；失败响应为 ok: false，并包含 error.code、error.message 及可选 error.details。在请求体无法识别等情况下，响应中的 requestId 可以为空。必须同时检查 HTTP 状态和 ok，不能把收到响应等同于执行成功。

devctl.describe 返回 protocolVersion、路径、maxBodyBytes、commandTimeoutMs 以及 commands；命令项只有 name、description、mutating 等当前实现公布的信息，不能假设它包含完整参数 schema。遵守当前客户端返回的容量与超时，不把大媒体文件塞进控制请求。

已有命令族与版本边界¶

以下名称存在于开发候选源码中；先确认它出现在当前 commands 列表，再按对应版本契约调用。某些正式构建仍未注册写接口，不得通过自行替换命令名或调用测试入口绕过。

app.test-scratch-blueprint.*、带 -test 的命令及 fixture 输入属于验收测试设施，不是用户工作流集成入口。command_not_found 表示该命令未注册，应换用已支持界面或停止请求升级版本，不应猜测隐藏接口。

在当前画布打开节点内部编辑器¶

当前会话公布 node-editor.node.open 后，可以打开当前根画布中已有的 custom.python 或 vision.multi_state_ui 节点。它不打开另一份蓝图、不切换所有者、不保存、不运行，也不会隐式丢弃其他节点草稿；仍检查正常工作区编辑准入、资源门禁及 Python 自定义节点创作资格。

四个值都是非空字符串，不接受首尾空白或控制字符；owner 与 step 必须同时提供，不能只凭相同 blueprintId 猜测当前包内步骤。身份来自已读取的当前工作区与蓝图，不使用显示名称代替。以下为包内节点示例，所有占位值须替换成实际身份；独立蓝图省略最后两个参数：

{
  "command": "node-editor.node.open",
  "arguments": {
    "blueprintNodeId": "python-node-id",
    "expectedBlueprintId": "current-blueprint-id",
    "expectedOwnerPath": "D:/authorized/workflow.gcbps",
    "expectedStepInstanceKey": "current-step-instance-key"
  }
}

成功 result 包含 opened、alreadyOpen、blueprintNodeId 和 state。相同身份的节点已经打开时返回 opened=true,alreadyOpen=true，保留原草稿，不重新初始化编辑器。首次打开为 alreadyOpen=false。命令响应后仍核对返回的当前状态，不把打开成功当作保存或执行成功。

node-editor.state（参数 {}）及上述返回的 state 增加 inlineConfiguration：未打开内部节点编辑器时为 null，打开时含 nodeId、nodeTypeId、hasUnsavedChanges、busy。其中 nodeId 对应蓝图节点 ID；hasUnsavedChanges 包括尚未保存的表单草稿，busy 表示正在框选、导入等操作。

嵌套宏、节点组或其他内部编辑上下文中，先正常返回根画布再请求打开；身份变化或已有另一节点草稿等冲突会拒绝，不自动换目标。当前有内部节点草稿时，node-editor.macro.open 返回 HTTP 409、node_editor_another_node_open。使用 node-editor.back（参数 {}）走与界面一致的返回流程：忙碌时保留当前编辑器；有未保存修改时由真实客户端询问保存、不保存或取消。调用方不能传入“丢弃草稿”或“代为确认”参数绕过该流程。

5. 所有者、步骤与 CAS 保存¶

ownerPath 是自动化包的准确受管路径，不是蓝图显示名；stepInstanceKey 是该包内某次蓝图使用的实例标识。即使两个步骤的 blueprintId 相同，也不能省略步骤定位。

创建、挂载、选中，再编辑¶

以下六个正式库命令只接受表中参数，不接受任意磁盘路径、template、来源蓝图、overwrite 或插入位置。先探测命令可用性，再从 library.state 的当前清单取得准确 groupName（分组的 directoryName）和 appDirectoryName；不要硬编码默认目录或悄悄选择另一个 app。

创建使用普通空白内容；蓝图不读取用户自定义模板，包内新步骤仅追加到末尾。同名目标不会被覆盖，客户端可能分配不同文件名，必须使用实际回执。已有包必须通过普通本地内容及准确字节围栏检查；此入口不把商品、受保护资源或审核副本转换成普通库内容。

最小生产操作链：

1. library.state → 选定用户授权的分组及 app。
2. library.automation.create → 保存空包回执；这时文件已在文件管理中，但尚未挂载或选中。
3. library.blueprint.create → 用上一步 packageOwnerPath，把包的 rawSha256、byteLength 分别传为 expectedRawSha256、expectedByteLength，追加一个空白步骤。记录其 stepInstanceKey 和新包围栏；继续追加时使用最新 committedRawSha256、committedByteLength，不能复用旧围栏。
4. library.automation.mount → 用最新包围栏挂到准确 app。它只追加挂载，不复制、搬迁、重排或清理其他记录；同 app 已挂载返回 inserted: false，其他 app 已挂载则拒绝，满页也拒绝。挂载不会选中或运行。
5. library.automation.select → 显式选中这对准确 app/包。必须已有唯一挂载关系；打开的编辑器、未完成的页面写入、拖拽或重命名应先正常完成。此命令不打开节点编辑器，也不运行。
6. app.state 核对选择，再用 blueprint.graph.read 的 ownerPath（值取 packageOwnerPath）及准确 stepInstanceKey 读取目标蓝图；之后按下面的 CAS 流程调用 blueprint.graph.replace。

app.navigate 只切换页面，不代替第 5 步；app.blueprint.open 打开的是当前自动化中的步骤，也不能代替自动化选择。独立 .gcbp、.gmacro 的创建回执可供文件管理正常打开，但这些创建命令本身不承诺完整的 GT4AI 内部编辑链。

若返回 created: true 或已插入的挂载回执，同时带有 refreshWarning，说明持久化已提交、后续刷新或清理未完成：保留回执并刷新定位，不要重复创建。若超时或断线导致没有回执，先读取 library.state 与实际文件/步骤状态，确认是否已经完成；请求 ID 不是幂等键，禁止盲重试。无法唯一判断时停下来核对，不通过删除新文件或覆盖同名文件“恢复”。

创建后界面可能短暂加载派生状态。若明确收到 HTTP 409 且 error.code 为 library_workspace_busy，这是本次操作写入前的拒绝，可以等界面空闲后重试；它不同于超时、断线或结果未知，不能把所有失败都按“忙碌”重试。

已选中自动化的图读写¶

当客户端确实提供图读写能力时：

1. 用 app.state 核对当前挂载对象，调用 blueprint.graph.read 并传入准确 ownerPath，读取步骤列表。
2. 选择用户授权的 stepInstanceKey，再次读取得到目标 blueprint 和 rawSha256。保留未知字段及所有资源、端口和节点身份。
3. 在这个快照上生成最小修改。替换请求使用同一 ownerPath、stepInstanceKey，把蓝图读取结果的 rawSha256 传为 expectedRawSha256；graph 是对应版本允许编辑的图对象，不能推断为任意磁盘文件写接口。
4. 写入前确认编辑器已退出、没有可视化运行（含暂停和准备中）、所有者与步骤未变、账号仍有编辑和所需创作权限。有活跃快照任务时，须先取得下述一次写入风险确认许可。
5. 若内容哈希或所有者围栏变化，重新读取并比较差异，不能用新哈希盲目覆盖他人的修改。
6. 保存后重新读取，再从文件管理或工作区正常打开并测试。接口返回 saved 只证明保存完成，不证明逻辑正确。

CAS 指“比较读取时的版本后再替换”。它与权限检查是两回事：哈希匹配不授予编辑权，会员权益也不允许覆盖并发修改。商品蓝图、禁止编辑的内容和信任确认必须沿正常产品流程处理。

包创建/追加/挂载使用的整个包字节围栏，与 blueprint.graph.read 返回的目标蓝图内容哈希不是同一个值。字段名称相似也不能替换使用；图保存后若还要追加步骤或挂载，重新获取最新包围栏。

快照运行期间的一次写入确认¶

通过已公布的 app.blueprint.open 打开蓝图编辑器时，同样强制走真实客户端风险弹窗，本机“不再询问”不适用于该 API。打开编辑器不会因此获得下述图替换或库创作的单次写许可。

当前会话公布 automation.snapshot-edit.confirm 后，只能传 { "ownerPath": "准确的规范包路径" }。必须在客户端选中这个准确自动化。命令打开真实客户端风险弹窗，由用户选择继续或取消；调用方不能传 allowRisk、confirmed、noask 等字段代替用户决定，也不能模拟同意。本机“不再询问”只是普通 UI 提醒偏好，此 API 仍会要求真实弹窗确认。

只有第三种结果建立一次写请求许可；第一种不建立许可，后续写入仍须满足当前正常准入。许可仅保存在客户端，绑定当前账号、登录会话 token、准确 owner 的原字节围栏，以及精确快照运行身份（taskId、runId 与启动时间）的集合。接口不返回 token，也不接受调用方构造许可。它可供 blueprint.graph.replace 或指定 packageOwnerPath 的库创作写入（例如 library.blueprint.create、library.automation.mount）认领一次；同一写请求内多次提交检查可重入，另一请求不可复用。成功后许可删除，失败也应重新正常确认，不能因相同请求 ID 就盲目重放。

确认后，重新核对内容与围栏，再按原写接口提交。返回的 expectedOwnerRawSha256 是确认所绑定的包字节哈希，不是图替换的 expectedRawSha256：图替换仍使用 blueprint.graph.read 的蓝图内容哈希，包追加/挂载仍需准确包哈希和 expectedByteLength。若最新包围栏与确认结果不符，比较变更并重新确认，不能只换哈希继续覆盖。风险许可不替代 CAS、商品编辑限制、自定义节点创作资格或脚本信任。

未确认、许可失效或跨请求复用会以 409 snapshot_edit_confirmation_required 拒绝；可视化运行、暂停或准备中仍以 409 automation_visual_edit_locked 硬拒绝。确认期间账号、owner 或活动任务集合变化可返回 409 snapshot_edit_scope_changed；当前选择的 owner 不符可返回 409 blueprint_graph_workspace_changed。用户取消后停止该次编辑；出错或许可失效时先重新读取实际状态与差异，再发起正常确认。快照期间的 blueprint.graph.read 只读操作不消费写许可。

.gmacro 的独立编辑同样应防止覆盖磁盘外部修改；优先使用客户端保存边界。不要直接修改 .gcbp/.gcbps 的二进制或权限数据。若当前版本没有受支持的自动写入入口，交付可审阅草稿或让用户用界面导入，不声称已完成保存。

可见普通节点组的图保存¶

当前候选的 graph 只允许 nodes、connections、variables、viewport、canvasLabels 和可选 nodeGroupDefinitions，前两项必须是数组。省略组定义表示保留原定义；显式空数组表示移除全部定义，仍有引用则拒绝保存。它不是修改文档身份、作者、资源清单或权限的入口。

组定义数组的每项为具名对象，字段如下：

每个组恰有一个 event.node_group_entry 和一个 event.node_group_exit，其 executionPortCount、payloadPortCount 分别与定义的进入/退出接口数量一致。调用节点使用 valueOverrides.definitionId 引用所在子图本层的定义；根层定义不自动向所有嵌套层继承。普通 event.node_group 的执行端口排在数据端口之前；不能把固定的“数据从 1 开始”套到多执行接口组。

event.protected_domain 也引用同一可见定义，但要求组只有一个执行入口、一个或两个执行出口，数据接口数量与节点配置一致；其自身成功/失败/超时出口固定为 0/½，结果数据从 8 开始。普通组的出口偏移不适用于保护域。

接口在 JSON 规范化前校验整棵定义树：重复 ID、缺失本层引用、端口越界/类型不符或不匹配的组终端直接拒绝，不静默丢弃连线。最大嵌套深度为 16；主图加全部定义共不超过 500 节点、2000 连线，调用展开后也不能超限，未使用定义仍计入存储数量。已有子图的额外文档元数据只能原样保留，新组不能借此注入身份或权限字段。

组内新增或修改自定义 Python 仍经过正常创作权限检查，未使用的组也不例外；把脚本移入组不授予创作资格，也不绕过运行信任。嵌入图片沿正常保存边界提升为根资源引用，不能通过图请求直接替换资源清单。节点组保存只证明结构可恢复，不证明组内业务已经运行成功。

core 商品审核工作副本¶

这组命令同时要求 GT4AI 使用权与当前 core 审核权限。它打开隔离的 marketplaceReviewWorkcopy，不授予买家编辑权，不覆盖商品源文件；canRun、canSaveAsNew、canPublish 均为 false。普通创作任务不要调用此入口，也不要把审核副本转存为普通 .gcbp、.gcbps 或 .gmacro。

先 open 或 reopen，再用 state、graph.read 确认准确副本。修改时保留身份及受保护内容，把读取到的 draftSha256 传入 expectedDraftSha256；不要替换成 sourceRawSha256 或普通库包/蓝图哈希。画布、来源或权限变化时停止并重新核对；重新授权不能绕过撤销权限或来源变化。保存/替换的返回结果含更新后的副本状态、图和草稿哈希，不能假设存在普通图接口的 saved 字段。断线后先核对副本状态与内容，不盲目重放保存或重新创建审核副本。

6. 任务、worker 与停止语义¶

自动化提交后形成运行快照，任务执行 worker 按快照执行，并通过应用持有的输入、设备、叠层等服务访问外部目标。运行 ID 与可复用的任务记录不同；不能只凭文件名或旧任务缓存判断当前运行。

任务可以处于准备、运行、停止过渡、暂停或终止状态。暂停/停止请求到达不代表外部输入已经排空，应观察到稳定状态后再修改工作区或启动替代任务。工作区在对应任务仍运行或暂停时可能保持锁定。

GT4AI 请求生命周期也不等于任务生命周期：HTTP 请求取消会撤销本次请求的后续授权并清理其拥有的资源，但不能据此假设用户已启动的自动化已经停止。停止实际任务必须走任务管理及当前版本支持的正常操作，并核对最终状态。

本地快照运行与模式设置¶

以下契约对应 2026-09-09 开发候选源码。必须先从 devctl.describe.commands 确认当前客户端公布了所需命令，再用 app.state 核对当前选中的准确 ownerPath。mode.set 不是独立命令，完整名称为 automation.run-mode.set。

任务回执仅包含 ownerPath、taskId、runId、mode（snapshot）、status、active、preparing。不返回正文、变量值、资源、账号凭据或任意任务内部字段。list 仅列出当前账号、准确所有者下可在任务管理器显示的快照任务，排除可视化和 Debug 任务；按启动时间倒序，hasMore 表示结果被 limit 截断。inspect 是状态读取，不是可视化诊断日志接口。

例如，取得准确所有者后设置模式：

{
  "requestId": "snapshot-mode-001",
  "command": "automation.run-mode.set",
  "arguments": {"ownerPath": "用户实际选中的自动化.gcbps", "mode": "snapshot"}
}

模式切换与启动要求当前自动化空闲。start 要求选择本地执行，会选择快照模式并通过正式界面的相同启动准入；权限、依赖、脚本信任或其他准入被拒绝时不能伪造成功回执。参数只接受表内字段，不支持注入任意公开变量、图正文、路由或测试选项。控制身份必须使用刚取得的实际回执，不能由当前选中任务猜测 taskId/runId。

会话、账号或所有者变化、任务身份被替换、任务状态不允许操作时会拒绝。常见拒绝码为 snapshot_run_wrong_owner、snapshot_run_account_changed、snapshot_run_unavailable、snapshot_run_busy、snapshot_run_local_required、snapshot_run_start_rejected、snapshot_run_identity_changed、snapshot_run_invalid_status、snapshot_run_resume_rejected。收到拒绝或请求超时后先核对当前任务状态，不盲目重复启动或补写身份。

可视化运行及暂停期间全编辑锁定；快照运行允许轻量修改公开变量，打开编辑与调整步骤顺序需风险确认。当前执行沿已加载快照运行，修改不会热替换内存正文；再次运行读取最新完整顺序与正文并映射旧公开参数，暂停续跑则严格验证原正文与路由。完整规则与提示设置见运行期间编辑蓝图。

只读检查当前可视化运行¶

先在正常自动化页面选中用户授权的准确包，用 app.state 核对所有者，再调用 automation.visual-run.state（参数 {}）取得当前 taskId。state 只给出状态标识和计数；logs.read 的控制请求日志不能代替任务内部运行日志。当前会话公布了 automation.visual-run.inspect 时，可用以下请求读取对应运行的诊断。示例中的路径和任务 ID 必须替换为刚取得的实际值：

{
  "requestId": "visual-inspect-001",
  "command": "automation.visual-run.inspect",
  "arguments": {
    "ownerPath": "apps/example/daily.gcbps",
    "taskId": "current-visual-task-id",
    "limit": 50
  }
}

此命令为只读（mutating: false），不会启动、恢复或停止任务。只接受必填的准确 ownerPath、taskId，以及可选整数 limit（1–50，省略为 50）；不接受变量展开、资源读取或其他附加参数。两个标识必须同时匹配当前账号、当前选中的自动化及其可视化运行，不是任意任务或历史记录查询接口。

result 包含 status、statusText、terminalReason、active、paused、preparing、taskSnapshotAvailable，以及 stepId、零起始的 stepIndex、blueprintId / blueprintName、nodeId / nodeName。尚未进入节点或步骤时相关字段可以为空。logs 返回最近最多 limit 条运行日志，按原顺序排列，每条只有 sequence、time、kind、message；logCount 是现有缓冲区条数，omittedLogCount 是本次因 limit 未返回的条数，不代表完整历史日志量。还可用返回的 taskId、runId、revision 核对观察对象。

任务已经结束，甚至完成后被自动移除时，只要当前内存中的可视化快照仍保留，仍可检查：此时 taskSnapshotAvailable 可为 false，终态来自原快照，不推测或补写成功。它不是持久日志归档；新运行、清理或客户端重启后，旧快照可能不再可用。

completed 不等于业务成功。 它只表示任务执行链结束；例如启动应用节点返回未启动、识别结果为未命中，而蓝图未连接失败分支，也可能走到完成。必须同时核对节点结果、运行日志及目标应用的实际画面/状态，不能凭 HTTP ok、active: false 或 status: completed 宣称登录、领取或刷图成功。

检查结果不返回变量值、变量变化、资源或完整蓝图正文，也不返回账号 token；文本会有长度限制和凭据脱敏，但仍可能含用户命名或业务诊断信息。不要把结果直接当成可公开上传的脱敏包。缺少关键业务证据时，在用户已授权范围内补充观察，而不是绕过只读接口索取私密内容。

自定义 Python 的 worker 是另一层：单次节点执行启动 Python 子进程，gpy.workers 产生受该执行生命周期管理的子 worker；它们不是独立的常驻自动化任务。暂停会结束 Python 进程，不保留语句栈；超时、取消和父进程结束会触发清理。成功交接的受管媒体可在父任务作用域内供下游使用，但临时路径不是持久资源路径。完整签名、sdkCapabilities、截图/匹配/OCR/输入与坐标契约见用户手册 gpy Python API；端口编辑见自定义 Python 节点。

7. 权限与脚本信任¶

GT4AI 与界面使用同一账号权益、购买状态、内容编辑权和脚本信任边界。当前账号能否使用 GT4AI，与能否创建或修改自定义节点应分别检查；能运行已购内容也不意味着能修改其中的 Python。

自定义 Python 具有本机用户权限，不是安全沙箱。不要把有限协议、独立进程、超时或自动清理描述为安全隔离。运行来源不明的脚本前让用户审阅并明确确认；脚本内容或来源变化后重新核对信任，不代替用户点击信任确认。

不要请求用户把登录令牌、商品内容密钥或内部认证材料放进脚本。不要为满足一次任务修改授权状态、规避会员要求、复制禁止编辑的商品，或伪造测试通过。

8. 最小真实验证与反馈¶

按风险选择最小验证，而不是靠一张截图或一次接口 ok 宣称整条自动化通过：

• 重新打开保存结果，核对目标包、步骤、资源和注释。
• 用已获授权的真实目标执行必要片段，分别验证成功、未识别和超时等直接相关分支。
• 记录实际开始/结束状态及与目标一致的成功证据；明确哪些只做了静态检查，哪些尚未实测。
• 停止后确认任务和受管 worker 不再向目标发送输入，临时资源按生命周期回收。
• 报告缺口和下一步，不把尚未跑过的分支写成“全部通过”。

向开发者反馈时，先整理能复现问题的最小信息：客户端版本、相关命令名称、去标识化请求 ID、错误码、必要步骤和裁剪后的证据。移除会话 token、账号标识、私人目录、窗口中的私人内容及无关商品源码。用户明确同意具体接收方和上传内容后才上传；没有反馈命令时，提供本地脱敏材料让用户选择正常反馈入口，不发明 feedback.upload 等命令。

反馈请求契约¶

feedback.preview 接收 description（10～8000 字符）、tags（最多 8 个，每个 1～32 字符）及 images（最多 3 张）。每张图片只能是 {"dataBase64":"..."}，支持有效 PNG、JPEG、WebP，每图不超过 1 MiB、1600 万像素。不接受文件路径、日志采集指令或自行指定来源。

预览只保存在本机内存，返回 previewId、接收地址 destination 和 summary（原文、标签、图片尺寸／大小／哈希）。向用户展示实际图片及摘要，确认脱敏并获得明确上传同意后，再调用 feedback.submit，参数为 {"previewId":"反馈预览返回值","userConsent":true}。预览 10 分钟内有效，绑定当前账号与 GT4AI 会话，只能提交一次。

提交来源固定为 GT4AI，不能伪装成人工 Web 反馈。服务按请求标识去重；若网络错误提示可能已经提交，不自动生成新预览重传，应先核对结果。接口中的同意字段不能代替用户的真实同意。

新导出的 .gmacro 顶层包含 websiteUrl、aiManualUrl 和 skillUrl 三个 HTTPS 元数据字段；它们是合法 JSON 字段，不是注释。导入文件中的链接仅视作不可信数据，不自动访问或执行；再次导出时写入官方固定链接。

9. 继续查阅¶

• 节点参考目录：按已有分类查找节点。
• gpy Python API：输入输出、媒体、截图、匹配、OCR、输入控制、worker 和生命周期。
• 自定义 Python 与 gpy：节点端口、配置与编辑。
• 区域像素状态判断：多区域遮罩、指标、逻辑组合和等待语义。
• 宏轨道与片段：不要把时间线控制与蓝图执行连线混为一谈。
• GCBPS 云端 API：与 GT4AI 本机端口不同，不可混用认证材料。

当前开发候选完整节点目录和机器可读 JSON直接从客户端 catalog/schema 生成，包含节点用途、默认端口、配置及搜索预设。它们不是所有节点的运行验收清单；动态端口以实际配置为准，安装版本仍须通过当前会话确认能力。