Runtime GUI 使用教程

概述

Wingman Runtime GUI 是基于 Tauri 2.0 + Svelte 5 构建的本地桌面控制界面，通过本地 IPC（Named Pipe / Unix Domain Socket）直接控制 Runtime，无需经过远程服务器。

架构关系

┌─────────────────┐     Local IPC      ┌─────────────────┐
│  Tauri GUI      │ ◄────────────────► │  Runtime        │
│  (Svelte)       │  Named Pipe / UDS  │  (C++ Agent)    │
└─────────────────┘                    └─────────────────┘

重要：GUI 通过本地 IPC 控制 Runtime，不使用 HTTP/WebSocket Server。

安装与启动

前置条件

已编译 Runtime：build-msvc-ninja-vcpkg/apps/agent/wingman-agent.exe
Node.js 18+（用于开发模式）

启动 Runtime

bash

# 启动 Runtime 并启用本地 IPC
.\build-msvc-ninja-vcpkg\apps\agent\wingman-agent.exe start

# 或以独立模式启动（不连接远程服务器）
.\build-msvc-ninja-vcpkg\apps\agent\wingman-agent.exe start --standalone

启动 GUI

开发模式

bash

cd apps/gui
pnpm install
pnpm tauri dev

生产模式

编译后运行 apps/gui/src-tauri/target/release/wingman-gui.exe

界面总览

主界面布局

┌──────────────────────────────────────────────────────────────┐
│  🎮 Wingman                        [连接状态] [设置] [主题]  │
├──────────────────────────────────────────────────────────────┤
│  [Dashboard] [脚本] [触发器] [宏] [屏幕] [日志] [设置]       │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│                      页面内容区域                             │
│                                                              │
└──────────────────────────────────────────────────────────────┘

连接状态指示

状态	图标	说明
已连接	🟢 绿色	GUI 与 Runtime IPC 连接正常
连接中	🟡 黄色	正在尝试连接
断开	🔴 红色	未连接到 Runtime

页面功能

1. Dashboard（仪表盘）

显示系统概览和快速操作入口。

功能

连接状态：显示 Runtime IPC 连接状态
运行统计：正在运行的脚本数量、触发器状态
快速入口：常用功能快捷方式
远程连接状态：显示是否已连接到远程 Go Server

2. Scripts（脚本管理）

管理本地脚本文件，支持启动、停止和状态监控。

功能列表

脚本列表：显示已加载的脚本及其运行状态
按路径启动：输入脚本路径直接启动
快速脚本：预设的常用脚本快捷入口
运行状态：实时显示脚本运行/停止状态
运行统计：查看脚本运行概览

启动脚本

在「自定义路径」输入框输入脚本路径
点击「启动」按钮
或点击预设的快速脚本卡片

脚本状态说明

状态	颜色	说明
运行中	🟢 绿色	脚本正在执行
已停止	⚪ 灰色	脚本未运行
错误	🔴 红色	脚本执行出错

注意：脚本编辑推荐使用 VS Code + EmmyLua 插件，GUI 定位为启动器和状态监控

3. Triggers（触发器管理）

配置条件触发器，实现自动化检测和响应。

功能列表

触发器列表：显示所有已配置的触发器
创建触发器：新建条件触发规则
编辑触发器：修改触发条件和动作
启用/禁用：控制触发器是否生效
触发记录：查看触发历史

创建触发器

点击「新建触发器」按钮
配置触发条件：

条件类型	说明
color_found	检测到指定颜色
color_lost	指定颜色消失
image_found	图像匹配成功
image_lost	图像消失
time_elapsed	定时触发
hotkey_pressed	热键按下

配置执行动作：

动作类型	说明
run_script	运行指定脚本
click	鼠标点击指定位置
key_press	按下指定按键
type	输入文本
delay	延时等待
log	输出日志

设置冷却时间（毫秒）
点击「保存」

条件配置示例

颜色检测：

类型：color_found
颜色值：#ff0000（红色）
区域：{x: 100, y: 100, width: 50, height: 50}
容差：10

图像匹配：

类型：image_found
图像路径：images/target.png
匹配阈值：0.9

4. Macros（宏录制）

录制和回放鼠标键盘操作。

功能列表

录制：录制鼠标移动、点击、键盘操作
回放：按录制的操作序列回放
保存/加载：保存宏到文件、从文件加载
速度控制：调整回放速度
重复次数：设置回放重复次数

录制宏

点击「录制」按钮
执行要录制的鼠标键盘操作
点击「停止」结束录制

回放宏

选择要回放的宏
设置回放速度（数字输入，10%-500%，默认 100%）
设置重复次数（1-100 次）
点击「回放」按钮

保存宏

点击「保存」将宏保存为 JSON 文件
点击「加载」从文件导入宏

5. Screen（屏幕工具）

屏幕捕获和区域选择工具。

功能列表

截图：捕获全屏或指定区域
区域选择：可视化选择屏幕区域
颜色拾取：获取屏幕上指定位置的颜色值
预览：查看截图结果

截图操作

点击「截图」按钮
截图结果显示在预览区域
可选择保存到文件

区域选择

点击「选择区域」按钮
在屏幕上拖拽选择矩形区域
区域坐标自动填入配置

颜色拾取

点击「拾取颜色」按钮
点击屏幕上的目标位置
颜色值（HEX/RGB）自动显示

6. Logs（系统日志）

查看系统运行日志和事件流。

功能列表

日志列表：显示所有日志条目
级别筛选：按 info/success/warning/error 筛选
关键词搜索：搜索日志内容
自动滚动：新日志自动滚动到底部
导出日志：导出为文本文件
清空日志：清除当前显示的日志

日志级别

级别	颜色	说明
info	🔵 蓝色	一般信息
success	🟢 绿色	操作成功
warning	🟡 黄色	警告信息
error	🔴 红色	错误信息

日志来源

GUI 事件：GUI 操作产生的日志
Runtime 事件：通过 IPC 接收的 Runtime 日志
触发器事件：触发器触发记录
脚本输出：脚本的标准输出

7. Settings（设置）

配置 GUI 和 Runtime 连接参数。

连接设置

设置项	默认值	说明
IPC 端点	`wingman`	本地 IPC 端点名称（Windows Named Pipe）
Orchestrator URL	`http://localhost:9527`	远程 Go Server 地址
自动重连	✅ 启用	断线后自动重连
自动启动	❌ 禁用	GUI 启动时自动连接 Runtime

运行设置

设置项	默认值	说明
启动时最小化	❌ 禁用	启动后最小化到系统托盘
日志级别	`info`	日志输出详细程度

配置管理（Game Profiles）

配置列表：查看所有游戏配置
创建配置：新建游戏专属配置
导入/导出：JSON 格式导入导出配置
激活配置：选择当前使用的配置

热键设置

默认热键（均为全局热键，可在 game profile 中改键）：

热键	动作
F5	start（启动当前脚本）
F6	stop（停止当前脚本）
F7	pause（暂停/继续）
F12	emergencyStop（紧急停止所有脚本）

系统托盘

GUI 启动后会在系统托盘显示图标。

托盘菜单

左键点击：显示/隐藏主窗口
右键菜单：
- 显示/隐藏窗口
- 退出程序

快捷键

全局热键仅上一节的 F5 / F6 / F7 / F12 四个（经 tauri-plugin-global-shortcut 注册，动作映射 startActiveScripts / stopActiveScripts / togglePause / stopAll，均可在 game profile 中改键）。Ctrl+N / Ctrl+S / Ctrl+Q 等编辑类快捷键未绑定全局行为。

常见问题

Q: GUI 显示「未连接到 Runtime」？

确认 Runtime 已启动
检查 IPC 端点名称是否正确（默认 wingman）
Windows 检查 Named Pipe 是否可用：\\.\pipe\wingman
查看日志获取详细错误信息

Q: 触发器不触发？

确认触发器已启用（绿色开关）
检查条件配置是否正确
确认屏幕区域/颜色值设置准确
查看日志是否有触发记录

Q: 宏录制没有反应？

确认已点击「录制」按钮开始录制
检查是否有其他程序拦截了输入
尝试以管理员权限运行 GUI

Q: 截图功能不工作？

确认 Runtime 已连接
检查屏幕权限（macOS 需要屏幕录制权限）
查看日志获取错误信息

Q: 如何修改 IPC 端点名称？

打开设置页面
修改「IPC 端点」字段
重启 Runtime 和 GUI 使配置生效

Q: 如何连接远程 Go Server？

打开设置页面
填写「Orchestrator URL」为 Go Server 地址
在 Runtime 启动时不要使用 --standalone 参数
Runtime 会自动连接到指定的 Go Server

开发者信息

技术栈

前端框架：Svelte 5
桌面框架：Tauri 2.0
构建工具：Vite
样式：CSS 变量 + 响应式设计

项目结构

apps/gui/
├── src/
│   ├── lib/
│   │   ├── stores/          # Svelte stores
│   │   ├── components/      # 共享组件
│   │   └── ...
│   ├── routes/              # 页面路由
│   │   ├── dashboard/
│   │   ├── scripts/
│   │   ├── triggers/
│   │   ├── macros/
│   │   ├── screen/
│   │   ├── logs/
│   │   └── settings/
│   └── app.css              # 全局样式
├── src-tauri/               # Rust 后端
│   ├── src/
│   │   ├── main.rs
│   │   ├── commands/        # Tauri 命令
│   │   └── ...
│   └── Cargo.toml
└── package.json

Runtime GUI 使用教程 ​

概述 ​

架构关系 ​

安装与启动 ​

前置条件 ​

启动 Runtime ​

启动 GUI ​

开发模式 ​

生产模式 ​

界面总览 ​

主界面布局 ​

连接状态指示 ​

页面功能 ​

1. Dashboard（仪表盘） ​

功能 ​

2. Scripts（脚本管理） ​

功能列表 ​

启动脚本 ​

脚本状态说明 ​

3. Triggers（触发器管理） ​

功能列表 ​

创建触发器 ​

条件配置示例 ​

4. Macros（宏录制） ​

功能列表 ​

录制宏 ​

回放宏 ​

保存宏 ​

5. Screen（屏幕工具） ​

功能列表 ​

截图操作 ​

区域选择 ​

颜色拾取 ​

6. Logs（系统日志） ​

功能列表 ​

日志级别 ​

日志来源 ​

7. Settings（设置） ​

连接设置 ​

运行设置 ​

配置管理（Game Profiles） ​

热键设置 ​

系统托盘 ​

托盘菜单 ​

快捷键 ​

常见问题 ​

Q: GUI 显示「未连接到 Runtime」？ ​

Q: 触发器不触发？ ​

Q: 宏录制没有反应？ ​

Q: 截图功能不工作？ ​

Q: 如何修改 IPC 端点名称？ ​

Q: 如何连接远程 Go Server？ ​

开发者信息 ​

技术栈 ​

项目结构 ​

Runtime GUI 使用教程

概述

架构关系

安装与启动

前置条件

启动 Runtime

启动 GUI

开发模式

生产模式

界面总览

主界面布局

连接状态指示

页面功能

1. Dashboard（仪表盘）

功能

2. Scripts（脚本管理）

功能列表

启动脚本

脚本状态说明

3. Triggers（触发器管理）

功能列表

创建触发器

条件配置示例

4. Macros（宏录制）

功能列表

录制宏

回放宏

保存宏

5. Screen（屏幕工具）

功能列表

截图操作

区域选择

颜色拾取

6. Logs（系统日志）

功能列表

日志级别

日志来源

7. Settings（设置）

连接设置

运行设置

配置管理（Game Profiles）

热键设置

系统托盘

托盘菜单

快捷键

常见问题

Q: GUI 显示「未连接到 Runtime」？

Q: 触发器不触发？

Q: 宏录制没有反应？

Q: 截图功能不工作？

Q: 如何修改 IPC 端点名称？

Q: 如何连接远程 Go Server？

开发者信息

技术栈

项目结构