Wand-Enhancer 远程协议参考WebSocket消息、IPC通道与web-contract.json完整解读【免费下载链接】Wand-EnhancerAdvanced UX and interoperability extension for Wand (WeMod) app项目地址: https://gitcode.com/GitHub_Trending/we/Wand-EnhancerWand-Enhancer 是 WandWeMod应用的增强扩展其核心亮点之一是远程访问让手机或同局域网的浏览器通过 WebSocket 与桌面端实时通信远程查看游戏状态、操作游戏修改器Trainer。本文将带你完整解读 Wand-Enhancer 远程协议的三大组成部分——web-contract.json 端点契约、WebSocket 消息类型与IPC 通道命名帮助你快速上手或二次开发远程面板。Wand-Enhancer 是什么Wand-Enhancer 通过修补 Wand 应用扩展出 Web 面板web-panel、游戏库管理、修改器预设、多语言界面等功能。其中web-panel/目录承载了整套远程访问能力Node 桥接服务bridge、TypeScript 前端src以及协议定义protocol。 关键目录协议契约web-panel/protocol/桥接服务web-panel/bridge/src/前端会话web-panel/src/remote-session/默认注入脚本web-panel/scripts/default/架构总览浏览器如何连上 Wand整个远程链路由三端协作完成理解这条链路是读懂协议的前提角色位置职责桌面端 Wand主进程 渲染进程游戏状态、修改器数据的唯一来源Bridge 桥接服务web-panel/bridge/托管 Web 面板、暴露 WebSocket 端口默认 3223Web 客户端web-panel/src/浏览器/手机页面通过/remote/ws收发 JSON 消息浏览器 (mobile-web) │ WebSocket: ws://host:3223/remote/ws ▼ Bridge (Node.js) ◄──IPC 通道 (wand-remote-*)──► Wand 桌面端客户端首帧消息必须声明client: mobile-web握手hello→hello_ack成功后才能发送命令否则会被协议路由器拒绝。web-contract.json 完整字段解读web-contract.json 是整套远程协议的唯一配置源桥接服务与前端都从这里读取常量。逐字段说明如下字段示例值含义protocolVersion1协议版本握手时双方比对不一致直接断开clientVersion0.2.0Web 客户端版本serverVersion0.2.0-wand桥接服务Wand 侧版本defaultRemoteHost0.0.0.0默认监听地址0.0.0.0 即对局域网开放defaultRemotePort3223默认远程端口portScanRange30端口被占用时的扫描偏移范围basePath/remote/远程页面基础路径assetsPath/remote/assets/静态资源路径webSocketPath/remote/wsWebSocket 端点healthPath/remote/api/health健康检查接口installedAppsPath/remote/api/installed-apps已安装游戏列表 API 小技巧URL 中可用?wsws://host:port/remote/ws手动覆盖桥接地址方便调试多实例环境见 web-panel/README.md 的开发说明。WebSocket 消息协议统一信封 类型字段所有消息共享一个信封结构见 messages.ts字段类型说明typestring消息类型决定载荷结构versionnumber协议版本必须与protocolVersion一致requestIdstring | null请求关联 ID用于请求-响应配对payloadobject具体业务载荷握手消息hello 与 hello_ackhello客户端 → 服务携带client固定mobile-web、clientVersion、可选pairingToken以及能力声明capabilities是否支持增量值supportsDeltaValues、是否支持切换修改器supportsTrainerSwitch。hello_ack服务 → 客户端返回sessionId、accepted、服务端版本号以及可访问的remoteUrl/advertisedUrls用于发现局域网地址。修改器数据同步消息类型方向用途trainer_meta服务 → 客户端修改器元数据分类列表 完整cheats模式含 uuid、target、type、args 等trainer_values服务 → 客户端当前所有修改项的值快照value_changed服务 → 客户端单项值变化增量推送含新旧值与来源trainer_changed服务 → 客户端活跃修改器切换事件trainer类型支持—slider、number、toggle、button、selection、scalar、incremental共 7 种控件客户端可发送的命令消息set_value修改某项数值。payload含trainerId、target、value、可选cheatId。服务端会校验target是否属于当前活跃修改器toggle类型的值会被强制转布尔。remote_command远程启停游戏action仅允许launch/stop可附带gameId/titleId。对应响应set_value_result与remote_command_result结构统一为{ ok, ..., error? }。其他状态类消息game_status游戏会话状态idle/running、进程 ID、会话时长 当前运行中的 Trainer 状态。installed_apps本机已安装游戏清单含平台、SKU、封面图、游戏时长。error错误通知含code、message与可选details。传输层细节见 websocket-codec.ts服务端仅支持 TEXT(1)、BINARY(2)、CLOSE(8)、PING(9)、PONG(10) 帧操作码且不支持超大帧握手采用标准 RFC 6455 的 SHA-1 Base64 Accept-Key 校验。IPC 通道清单Bridge 与 Wand 的“内线”Bridge 与 Wand 桌面端之间不走 WebSocket而是使用固定的 IPC 通道名定义于 constants.tsIPC 通道用途wand-remote-set-handler-bind绑定消息处理器wand-remote-syncTrainer 全量快照同步wand-remote-value-changed单项值变更广播wand-remote-set-value设置修改项值wand-remote-command/wand-remote-command-response远程命令请求/响应响应超时 15 秒wand-remote-game-status游戏状态推送wand-remote-installed-apps已安装游戏数据wand-remote-url远程访问地址通知常见错误码与排查协议路由器 protocol-router.ts 对每条入站消息做严格校验遇到error消息时可对照以下错误码错误码原因解决思路protocol_mismatch版本不一致确认双方使用同一protocolVersionhandshake_required未握手就发命令先发送hello并等待hello_ackinvalid_hellohello 载荷不完整补齐clientVersion与capabilitiestrainer_mismatch目标修改器不活跃等trainer_changed或重新选择游戏invalid_target未知修改项检查trainer_meta中的 target 列表unknown_message未知消息类型检查type拼写快速开始本地跑通远程面板按 web-panel/README.md 的步骤三步即可体验pnpm install安装依赖pnpm dev启动开发面板访问http://localhost:4173/局域网访问执行pnpm run dev:host手机打开电脑 IP 的 4173 端口即可 调试建议桥接日志写入wand-remote-bridge.log测试消息校验逻辑可参考web-panel/bridge/src/protocol-router.test.ts与web-panel/protocol/validation.test.ts中的用例。小结Wand-Enhancer 的远程协议设计简洁而完整一份 JSON 契约管端点一套信封管消息一组 IPC 通道管桌面通信。掌握 web-contract.json 的字段、12 种 WebSocket 消息类型和 9 个 IPC 通道名你基本就读懂了它的远程能力全貌——无论是排查连接问题还是基于桥接服务扩展自己的控制面板本文的清单都可以作为速查手册使用。【免费下载链接】Wand-EnhancerAdvanced UX and interoperability extension for Wand (WeMod) app项目地址: https://gitcode.com/GitHub_Trending/we/Wand-Enhancer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
