视觉识别与游戏交互/游戏ui识别与界面操作

本页面描述 Whimbox 后端中与游戏画面识别、游戏 UI 识别以及界面操作相关的职责边界与已知运行约束。根据当前可用的项目说明，Whimbox 通过截图和模拟鼠标键盘辅助游玩《无限暖暖》，后端负责 RPC 服务、大模型调用和工具调用；具体 UI 识别算法、类、函数和调用链的实现细节在当前源材料中未提供。

Purpose and Scope

本页面聚焦于以下能力：

• 通过截图获取游戏画面，并以视觉识别结果支持自动化操作；
• 识别游戏 UI，为自动对话、自动采集、自动钓鱼、清洁跳过、任务执行和自动跑图等功能提供交互基础；
• 通过模拟鼠标和键盘完成界面操作；
• 说明该能力与 interaction、ui、action、task、map、view_and_move 等项目模块的边界关系；
• 说明运行环境、分辨率和性能方面的已知限制。

当前材料不足以确认具体识别模型、模板匹配策略、OCR/YOLO 调用方式、点击坐标换算规则、重试策略、线程模型或异常类型。因此，本文不会推测未被源材料证实的 API、配置键或算法行为。实现细节未在当前源材料中找到的部分，会明确标注为“Implementation details not found in source”。

关于前端应用、RPC 协议和大语言模型 Agent 的完整实现，应分别参考对应的前端项目及 Agent/RPC 主题页面；本页面只描述它们与视觉识别和界面交互能力之间的边界。

Overview

Whimbox 是一个基于大语言模型和图像识别技术的 AI 智能体，用于辅助游玩《无限暖暖》。项目说明明确指出，当前后端不再提供 UI 界面，而是负责 RPC 服务、大模型调用和工具调用；因此，游戏 UI 识别与界面操作属于后端自动化能力的一部分，而不是 Whimbox 自身的桌面窗口 UI。

从项目结构说明可以确认，相关职责分布在以下模块：

• whimbox/interaction/：交互核心模块，负责“截图、操作”；
• whimbox/ui/：游戏 UI 的识别和操作；
• whimbox/api/：OCR、YOLO 等第三方模型；
• whimbox/action/：动作模块，例如拾取、钓鱼、战斗等；
• whimbox/task/：任务模块，提供各种功能脚本并供 Agent 调用；
• whimbox/map/：地图模块，包括小地图识别和大地图操作；
• whimbox/view_and_move/：视角和移动模块；
• whimbox/agent.py：大模型 Agent；
• whimbox/rpc_server.py：与前端通信的 RPC 服务端。

这些目录名称足以表明视觉识别与交互能力是一个跨模块基础能力：底层交互模块提供画面采集和输入操作，UI 模块面向游戏界面语义进行识别和操作，动作与任务模块消费这些能力完成具体功能，Agent 和 RPC 层则负责从自然语言或前端请求触发任务。由于没有实际源文件内容，以上关系只能作为项目结构说明中明确列出的模块边界，不能进一步推导具体依赖方向或方法调用顺序。

Architecture

根据项目说明可以建立如下职责分层：

1. 外部触发层包括奇想盒 App、命令行启动方式以及 Agent 的自然语言控制；
2. rpc_server.py 负责与前端通信；
3. agent.py 负责大模型 Agent 能力；
4. task/ 和 action/ 组织具体自动化任务与游戏动作；
5. ui/、interaction/、api/、map/ 与 view_and_move/ 提供识别、输入、地图、移动和视角相关能力；
6. 游戏客户端是被截图和模拟输入作用的外部系统。

项目说明还明确表示，Whimbox 不修改游戏文件、不读写游戏内存，只会截图和模拟鼠标键盘。由此可以确认，本能力采用屏幕级自动化边界，而不是进程内注入或内存读写方式。

具体架构图、类之间的调用关系和生命周期需要以实际源文件为依据；Implementation details not found in source。

识别与交互职责边界

屏幕采集与输入操作

whimbox/interaction/ 被项目结构直接描述为“交互核心模块（截图、操作）”。因此它应当承担屏幕截图以及鼠标、键盘等外部输入操作的基础职责。但当前材料没有提供模块内的文件、函数或配置，以下细节无法确认：

• 截图是全屏截图还是窗口区域截图；
• 是否存在统一的坐标系或缩放适配；
• 鼠标点击、拖拽和键盘输入的具体 API；
• 输入操作是否支持延迟、节流、重试或取消；
• 操作前是否自动截图或校验当前画面。

游戏 UI 识别与操作

whimbox/ui/ 被描述为“游戏 UI 的识别和操作”，说明该模块位于底层截图/输入能力与上层任务之间，面向游戏界面元素提供更高层的识别或操作封装。当前源材料没有列出具体 UI 元素、识别器、状态对象或操作方法，因此不能可靠列出诸如按钮名称、控件坐标、识别阈值或返回类型。

OCR 与目标检测

whimbox/api/ 的职责说明包含 OCR、YOLO 等第三方模型。这表明项目可能将文字识别和目标检测作为视觉能力的组成部分，但当前材料没有证明哪些 UI 由 OCR 识别、哪些 UI 由 YOLO 识别，也没有提供模型加载、推理输入输出、设备选择或错误处理实现。相关实现细节未在当前源材料中找到。

上层动作与任务

项目已列出的自动化功能包括自动对话、自动采集、自动钓鱼、自动清洁跳过、每日任务、自动跑图、录制宏和自动弹琴等。这些功能说明 UI 识别和输入操作需要服务于多个交互场景，而不是单一页面：

• 任务脚本可能通过 UI 状态判断下一步动作；
• 动作模块可能组合识别结果与鼠标键盘操作；
• 地图和移动模块可能同时使用小地图识别、大地图操作、视角与移动；
• Agent 可以通过自然语言触发这些任务或工具。

但当前材料未提供各任务到 UI 模块的实际调用代码，因此无法确认具体调用链、同步方式或任务完成判定。

已知运行约束

分辨率约束

项目说明明确指出，Whimbox 目前仅支持标准 16:9 分辨率运行的游戏。对 UI 识别而言，这意味着当前实现至少存在与画面尺寸或宽高比相关的前置假设。源材料没有说明是否允许不同的 16:9 分辨率，也没有说明是否支持窗口化、缩放显示或 DPI 适配。

在未看到实际坐标换算和图像预处理代码前，不能假设任意分辨率都能工作，也不能假设非 16:9 画面会被自动裁剪或缩放。

性能约束

项目说明指出，游戏本身已经消耗 PC 大量性能，图像识别会额外消耗性能，因此当前仅支持中高配 PC 运行。该限制直接影响截图频率、模型推理频率和任务并发，但源材料没有提供基准数据、显存要求、CPU/GPU 选择或可调节参数。

交互安全边界

项目说明明确强调：Whimbox 不修改游戏文件、不读写游戏内存，只截图并模拟鼠标键盘；同时，使用该工具产生的后果由用户自行承担。该边界应被视为本能力的运行前提，而不是对游戏服务条款的保证。

Core Flow

从现有项目说明可以确认的抽象流程是：外部客户端或 Agent 触发任务，任务和动作模块调用视觉识别与交互能力，系统读取游戏画面并通过模拟鼠标键盘推进游戏操作。具体步骤、分支、状态转移和失败恢复逻辑未在当前源材料中提供。

一个可由现有材料支持的端到端描述如下：

1. 用户通过奇想盒 App、命令行方式或自然语言提出操作需求；
2. 前端请求由 RPC 服务进入后端，或由 Agent 将自然语言转换为工具/任务调用；
3. task/ 或 action/ 负责组织目标功能；
4. ui/、interaction/、api/、map/ 或 view_and_move/ 提供识别和交互支持；
5. 系统对游戏进行截图和模拟鼠标键盘操作；
6. 上层任务根据识别结果继续执行，或将结果返回给 Agent/前端。

步骤 2 至步骤 6 的具体方法、返回值和异常处理需要源代码验证，当前无法进一步展开。

功能覆盖

项目说明列出的已实现或已支持功能，为 UI 识别和界面操作提供了实际使用场景：

• 每日任务：美鸭梨挖掘、素材激化幻境、闪光祝福幻境、魔物试炼幻境、周本、朝夕心愿、星海拾光、收集星光结晶、领取大月卡、奇迹之冠巅峰赛；
• 自动小功能：自动对话、自动采集、自动钓鱼、自动清洁跳过；
• 自动跑图：路线录制与编辑、自动跑图、自动采集、捕虫、清洁、钓鱼；
• 录制宏：录制和播放操作，但不支持视角转动的操作；
• 自动弹琴：将 MIDI 乐谱转换为奇想盒脚本；
• AI 对话：通过自然语言执行上述功能，并在一定程度上支持 SKILL 以及微信远程控制。

这些功能是产品说明中的能力清单，不等价于具体 UI API 文档。每项功能的识别目标、操作顺序和完成条件仍需对应任务实现源代码确认。

配置与部署

当前材料只明确了以下运行信息：

如果要在一条龙结束后自动关闭游戏和奇想盒，需要在一条龙配置中勾选“ 一条龙结束后，关闭游戏和奇想盒”；如果要在启动奇想盒时自动运行一条龙，需要勾选“启动奇想盒时，自动运行一条龙”。这些选项属于产品运行配置，当前材料未说明其配置文件字段名。

API Reference

当前没有可验证的源代码文件，因此不能提供具体函数签名、类签名、参数类型、返回类型或异常列表。虽然项目结构列出了 rpc_server.py，但仅凭文件名和项目说明无法推断 RPC 方法、请求格式或响应格式。

Implementation details not found in source。要补充本节，需要读取至少以下内容：交互核心的截图与输入函数、UI 识别器与操作器、OCR/YOLO 封装、任务调用方、RPC 注册代码以及相关测试。

Failure Modes and Edge Cases

已由项目说明明确的限制和风险包括：

• 非标准 16:9 分辨率不在当前支持范围内；
• 低性能设备可能无法承担游戏与图像识别的共同负载；
• 宏录制和播放不支持视角转动操作；
• 使用自动化工具可能产生账号或使用条款风险，相关后果由用户自行承担；
• 游戏、图像识别或外部输入状态异常时，项目说明未提供统一的错误恢复保证。

以下重要行为在当前源材料中没有说明：

• UI 元素未识别时是否重试；
• 识别置信度不足时是否停止操作；
• 游戏窗口失焦、遮挡或关闭时如何处理；
• 截图失败或模型加载失败时如何报告；
• 鼠标键盘操作失败时是否回滚；
• 多个任务并发执行时如何进行互斥；
• 任务取消和超时如何传播。

不能在缺乏实现代码的情况下为这些场景指定行为。

Extension Points

从目录划分可以看出潜在的扩展边界：新增第三方视觉模型可归入 api/，新增游戏 UI 识别和操作能力可归入 ui/，新增底层截图或输入适配可归入 interaction/，新增游戏行为可归入 action/，新增完整自动化流程可归入 task/。这是基于项目结构注释的模块归类，不代表已经存在统一接口或插件机制。

如果需要扩展视觉识别能力，应首先确认以下现有约束，而不是直接依赖目录名称推断接口：输入截图格式、坐标系、模型生命周期、识别结果结构、线程安全要求、操作节奏以及任务完成判定。相关扩展接口未在当前源材料中找到。

Tests and Observability

项目结构列出了 logs/ 日志目录，但当前材料没有给出日志格式、日志级别、关键事件或诊断字段。也没有提供测试目录或测试文件，因此无法确认 UI 识别、截图、输入操作、分辨率适配和失败恢复是否有自动化测试覆盖。

开发者可从项目说明确认的开发前提是：项目仅支持 Python 3.12。更细的本地调试流程、模型测试方法和截图回放机制未在当前源材料中提供。

Related Links

• 前端运行入口：奇想盒 App 项目（项目说明中的外部链接）：https://github.com/nikkigallery/whimbox_app
• 产品主页：https://nikkigallery.vip/whimbox/
• 相关项目模块：whimbox/interaction/、whimbox/ui/、whimbox/api/、whimbox/action/、whimbox/task/、whimbox/map/、whimbox/view_and_move/
• 相关后端入口：whimbox/main.py、whimbox/agent.py、whimbox/rpc_server.py

本文严格基于当前提供的项目说明。由于没有可读取的实际源文件，未提供代码示例、Mermaid 图或未经验证的 API 签名；补充这些内容前需要先获取并读取对应仓库源文件。