安装与首次启动¶

Windows 版提供官网小安装包和完整便携版两种使用方式。安装版首次运行时下载基础资源；完整便携版已带齐基础资源，整体解压后即可使用。下面以 1.0.4 版文件名为例。

前置条件¶

• 从官方提供的下载位置取得安装包或完整便携版 ZIP。
• 选择一个能够写入本地数据的目录，并以管理员身份运行软件。
• 安装版首次下载基础资源需要联网；完整便携版和已取得的离线插件包不需要重新下载这些资源。登录、检查更新和使用云端内容仍需要网络；本地编辑不以登录为前提。

操作步骤¶

1. 选择安装方式¶

官网小安装包：运行安装包，按向导选择目录并完成安装。它先安装主程序和维护组件，基础资源在首次打开软件时下载。保留程序和随附文件，不要只移动 ghostclickai.exe。

完整便携版：将 GhostClickAI_1.0.4_便携版.zip 整体解压，打开解压后的 GhostClickAI 文件夹，右键 ghostclickai.exe，选择“以管理员身份运行”。保留整个目录结构，不能只从压缩包内打开或取出主程序。完整便携版无需再下载基础资源。

安装版和便携版都把本地工作区、蓝图库和任务数据保存在各自主程序旁边的 data 中。软件管理的安卓 9 实例位于该份软件的 data/android_instances/ghostclick_android9。不同安装目录、另一份便携版和开发环境的数据相互独立，不会因当前工作目录不同而切换数据。目录不可写时，应处理权限或路径问题。

2. 首次打开与基础资源准备¶

安装版首次打开时按模块下载基础资源 ZIP。每个压缩包下载完成后校验一次，随后正常解压安装，不再对解压后的每个文件重复做完整校验。中断后可继续有效的下载进度，取消或失败不会显示为准备完成。

准备成功后，软件会自动清理已用完的下载包。基础资源的就绪状态与当前要求匹配时，重新打开直接进入主界面，不会重复下载或再逐文件完整校验。失败或取消时保留可恢复的缓存，按界面提示继续即可。

完整便携版会直接使用随包提供的基础资源，进入工作区初始化，无需经过基础资源下载页。

3. 初始化工作区¶

启动 GhostClickAI 后，主窗口会居中打开。第一次初始化会准备软件管理的数据目录，并确保以下基础数据存在：

• 当前用户资料；
• 与系统语言对应的默认语言；
• 默认蓝图分类；
• 新蓝图模板；
• 至少一个基础 App 工作区；
• 保存界面选择、快捷键、任务记录和资源缓存所需的位置。

首次安装不会导入另一份开发构建中的实例、蓝图或任务历史。系统通用偏好和 GT4AI 的会话发现记录不等同于这份安装的工作区数据。

4. 等待初始状态加载¶

主界面出现后，软件会依次读取用户资料、界面选择、自动运行预设、App 与自动化列表，以及通过启动参数传入的 .gcbp 或 .gcbps 文件。

部分可选功能会在界面出现后继续检查运行环境。如果初始化失败，界面会提示“运行环境加载失败，请重启软件后重试”。遇到该提示时，先保存能够保存的内容，再关闭并重新启动一次；不要反复点击尚未就绪的功能。

5. 按需调整使用偏好¶

首次进入后，可以在设置页选择语言、主题和快捷键。是否开启“自动运行预设列表”、删除蓝图时是否弹窗，以及是否使用“截图与录屏 HDR 模式”，按自己的使用习惯和显示环境设置。

接下来可按创建第一个自动化完成第一次编辑和运行。

“登录 Windows 后自启”已接入 Windows 启动项（仅安装版可用），登录系统后会自动打开软件；登录后是否执行自动化由“自动运行预设列表”决定。“启动后自动后台运行”仍属于开发中界面项，不能作为可靠后台启动策略。

6. 可选：关联蓝图文件¶

设置页提供“关联 gcbps/gcbp 文件”。该功能只在 Windows 上可用，用于把当前程序与两种文件格式建立关联。

完成关联后，通过文件参数启动软件时，.gcbp 和 .gcbps 会被导入文件管理。文件关联不是首次启动的必要步骤；也可以直接在文件管理中导入。

7. 按需安装离线插件¶

三个可选插件分别为安卓 9、本地大模型、音频文本互转。音频文本互转是一个插件包，内部资源由软件一起安装。

1. 退出软件，将需要的插件 ZIP 解压，取得表中的整个插件目录。
2. 将该目录放到主程序同级的 plugins 中，作为直接子目录，例如 plugins/GhostClickAI-AudioText。插件目录里的内部 ZIP 保持原样，不要自行解压。
3. 重新以管理员身份打开软件。软件会自动从本地安装插件，无需再次下载这些安装包；在设置页的组件中心查看安装进度和结果。

plugins 是离线安装的投放入口，不是插件运行文件的最终存放位置。启动后软件会把运行环境和模型分配到本安装 data/components 下的对应目录，例如安卓运行环境的 android_instance_runtime、大模型的 ollama、音频的 qwen3tts 和 whisper。

安装成功后，软件会自动清理已经用完的内部安装 ZIP，所以投放目录中只剩 plugin.json 和 installation.json 是正常结果。分发给其他用户时，使用原来的插件外包，不要复制这个已安装后只剩 JSON 的目录。安装失败时保留界面提示和本地安装内容，按提示处理后继续。GT4AI 已内置，无需重新绑定；正常安装这些插件也不需要打开 GT4AI 开发者开关。

结果¶

首次准备完成后，你应该能看到主工作区，可以打开文件管理和设置页，并能创建测试自动化。此时还不代表所有可选组件都已安装，也不代表外部操作目标已经配置。

退出与卸载¶

便携版退出软件后即可删除整个目录；其中的 data 也会一并删除，需要保留的蓝图、实例和其他本地数据应先另行保存。

安装版请通过 Windows 的“已安装的应用”正常卸载。卸载程序会自动关闭本应用，移除程序和随程序提供的基础资源，并保留用户数据。

常见问题¶

程序能打开，但功能提示组件缺失¶

安装版先确认基础资源准备已完成，再到设置页的组件中心查看可选插件状态。完整便携版若提示随包文件缺失，请重新完整解压主程序包；可选插件按上面的离线安装步骤处理。

重新打开软件会再次下载基础资源吗¶

已完成且匹配的基础资源会直接复用，不会每次启动重新下载。完整便携版本身已包含基础资源，也不需要执行首次下载。

插件解压后没有自动安装¶

检查插件目录是否直接位于主程序旁边的 plugins 中，例如 plugins/GhostClickAI-Android9，并保留其中的内部 ZIP。重新打开软件后，在组件中心查看具体状态；无需为此打开 GT4AI 开发者开关。

程序旁边没有出现 data 目录¶

安装版和便携版都使用各自主程序旁边的 data。检查实际程序路径和写入权限；不要用另一份开发数据覆盖，也不要在软件运行期间移动或删除正在使用的数据目录。

启动后自动执行了自动化¶

设置页的“自动运行预设列表”可能已经启用，并选中了自动化。先在任务管理中停止任务，再回到设置页关闭该功能或取消对应自动化。

双击蓝图文件没有打开软件¶

文件关联不是默认安装前提。可以先从文件管理导入，或在设置页手动执行“关联 gcbps/gcbp 文件”。

首次启动后界面显示为空¶

先等待基础资源与初始化完成并观察通知。如果本地数据曾被移动或清空，确认当前用户能写入实际安装目录中的 data，并保留具体错误信息。

相关链接¶

• 创建第一个自动化
• 设置
• 任务管理
• 故障排查