测试与故障排查/交互按键与地图测试

本文记录 Whimbox 后端中与“交互按键”和“地图”相关的测试与故障排查边界。当前可用资料仅包含项目 README 的模块划分与运行约束，未提供对应测试脚本、按键映射实现、截图识别实现、地图操作实现或日志样例。因此，本文严格区分已由仓库资料确认的事实与尚未在源代码中验证的实现细节。

Purpose and Scope

本页覆盖以下范围：

whimbox/interaction/ 交互核心模块在整体项目中的职责边界；
whimbox/map/ 地图模块在整体项目中的职责边界；
与交互按键、截图、地图识别和地图操作相关的运行前置条件；
面向测试人员和开发人员的排查顺序、证据收集方式与已知限制。

本页不臆测具体按键 API、坐标换算算法、地图识别模型、重试策略或异常类型，因为这些实现尚未在提供的源代码材料中出现。每日任务、自动采集、钓鱼、战斗、宏录制、RPC 和大模型调用属于相邻能力；这里只在说明故障边界时引用它们与交互、地图模块的关系。若需要验证具体任务脚本，应转到对应任务测试页面；若需要验证前端通信，应转到 RPC 或应用集成页面。

Overview

Whimbox 是面向《无限暖暖》的 AI 智能体后端，负责 RPC 服务、大模型调用和工具调用，当前不再提供 UI 界面。README 将项目拆分为多个模块，其中：

whimbox/interaction/ 被定义为“交互核心模块（截图、操作）”；
whimbox/map/ 被定义为“地图模块（小地图识别，大地图操作）”；
whimbox/view_and_move/ 负责视角和移动；
whimbox/ui/ 负责游戏 UI 的识别和操作；
whimbox/assets/ 存放地图、特征截图、配置文件和文件模板等资源；
whimbox/config/ 提供全局配置模块；
whimbox/common/ 提供日志和工具等公共能力。

从已确认的模块职责看，交互按键与地图测试不是单一接口测试，而是一个依赖运行环境的端到端能力：程序需要通过截图观察游戏状态，再通过鼠标键盘模拟执行操作；地图能力还涉及小地图识别与大地图操作。README 明确说明 Whimbox 不读写游戏内存、不修改游戏文件，只进行截图和鼠标键盘模拟，因此测试应以可观察的屏幕状态、实际输入效果和日志为主要证据。

测试边界与前置条件

运行环境

项目仅支持 Python 3.12。游戏需要以标准 16:9 分辨率运行；README 未声明其他分辨率下的坐标、识别模板或地图操作是否能够工作，因此非 16:9 环境不能作为已支持的测试基线。

图像识别会额外消耗 PC 性能，而游戏本身已经占用大量性能。测试时应记录游戏分辨率、窗口状态、机器性能和是否同时运行其他高负载程序，否则“按键无效”或“地图识别失败”可能实际是截图延迟或系统负载问题。

启动方式

当前项目是后端，不再提供 UI。README 建议通过 Whimbox app 运行；如果使用命令行方式运行一条龙，前置条件是先确认通过 Whimbox app 可以正常运行一条龙，再在一条龙配置中启用“启动奇想盒时，自动运行一条龙”，最后通过命令行启动 whimbox_app.exe。

这意味着交互与地图测试不能只验证后端进程是否启动。至少需要确认：

游戏进程已启动并位于预期画面；
Whimbox app 或其后端连接已建立；
测试动作的目标窗口处于前台；
截图能够捕获到游戏画面；
按键或鼠标操作确实作用于游戏，而不是其他窗口。

模块关系

根据 README 中的项目结构，交互和地图能力处于多个自动化能力的共同基础位置：交互模块提供截图和输入操作，地图模块提供小地图识别和大地图操作，上层的任务、自动跑图、宏和 AI 工具再调用这些能力。README 还明确列出自动跑图支持大世界和星海，并支持路线录制、编辑及自动采集、捕虫、清洁和钓鱼；这些功能因此是地图与交互测试的重要实际使用场景。

由于当前资料只提供模块职责，没有提供类、函数、注册代码或调用关系，无法进一步确认具体依赖方向、对象生命周期、线程模型或异步边界。以下关系是 README 明确支持的模块职责关系，而不是对未提供实现的 API 推断：

whimbox/interaction/：截图与操作；
whimbox/map/：小地图识别与大地图操作；
whimbox/view_and_move/：视角与移动；
whimbox/task/：供 agent 调用的功能脚本；
whimbox/assets/：地图和特征截图等识别资源；
whimbox/common/：日志与公共工具；
whimbox/config/：全局配置；
whimbox/rpc_server.py：与前端通信的 RPC 服务器；
whimbox/agent.py：大模型 agent。

交互按键测试

测试目标

交互按键测试的目标不是只确认“程序发送了一个输入”，而是确认完整的可见结果链路：输入被发出、游戏窗口收到输入、角色或 UI 发生预期变化、后续截图能够观察到该变化。由于源码中没有提供具体按键名称、按键持续时间、释放策略或动作结果判定函数，具体用例必须以仓库实际测试脚本和运行日志为准；当前资料不足以给出可执行的按键 API 示例。

基础测试矩阵

测试项	前置条件	观察结果	资料状态
单次键盘输入	游戏前台、16:9 分辨率	游戏出现与输入对应的可见变化	具体按键映射未提供
组合键输入	游戏前台、无其他窗口抢占	组合操作完成且无残留按键状态	组合键实现未提供
鼠标操作	游戏画面可见	光标或游戏 UI 发生预期变化	坐标与接口未提供
截图验证	游戏画面处于稳定状态	截图包含目标游戏画面	截图实现未提供
连续动作	运行负载可接受	动作顺序正确，无明显丢失	调度与重试未提供
中断与恢复	允许停止当前动作	游戏和后端回到可继续测试的状态	停止机制未提供

排查顺序

先排除环境问题：确认 Python 版本为 3.12、游戏为标准 16:9、目标窗口在前台，并记录机器负载。
再确认截图问题：检查截图是否来自游戏窗口，而不是桌面、黑屏或其他应用。README 只确认系统会截图，未提供截图 API 或保存位置，因此具体检查方式需要依据实现补充。
再确认输入问题：观察输入发生时游戏是否有任何可见反馈。若截图正常但没有反馈，应进一步检查窗口焦点、权限和输入目标。
最后检查上层流程：如果基础输入有效而自动跑图、任务或宏失败，应将问题拆分为路线、识别、移动、任务脚本或 RPC 调用问题，而不要直接归因于按键模块。
保留复现证据：记录分辨率、窗口状态、操作序列、失败前后截图、日志时间点和是否能稳定复现。当前资料确认项目存在 logs/ 目录，但未提供日志格式或字段定义。

地图测试

地图能力边界

README 对地图模块给出了两个明确职责：小地图识别和大地图操作。README 同时指出 whimbox/assets/ 存放地图和特征截图等资源，因此地图测试还应检查资源版本、资源路径和运行时加载结果。当前没有提供地图实体、坐标系、识别阈值、地图缩放规则、路线文件格式或具体操作函数，不能据此生成具体坐标或调用示例。

小地图识别测试

小地图识别的最小验证闭环应包括：

游戏处于可识别的小地图画面；
截图分辨率和比例符合支持条件；
识别结果与画面中的位置或标记一致；
连续截图中位置变化方向与角色实际移动方向一致；
识别失败时有可定位的日志或可保存的图像证据。

其中最后一项是测试可诊断性的关键。README 只确认有日志目录和地图资源目录，没有说明识别失败是否自动保存截图、是否重试或是否降级，因此这些行为必须通过实际源代码确认，不能作为现有保证记录。

大地图操作测试

大地图操作应与小地图识别分开验证。大地图操作至少需要检查打开地图、定位目标、移动视图、选择目标和退出地图等阶段是否按预期完成；但这些阶段的真实按键与鼠标调用未在当前资料中提供。测试报告应明确区分“地图没有打开”“地图打开但目标未定位”“目标定位成功但视图操作失败”和“地图操作完成但返回游戏后的移动失败”，以便分别归因于交互、地图识别或视角移动模块。

自动跑图联调

README 明确列出跑图路线录制、编辑和自动跑图，并说明暂时只支持大世界和星海。联调测试建议至少覆盖以下场景：

在支持的大世界场景录制一条短路线并回放；
在星海场景验证同样的路线生命周期；
在路线中加入自动采集、捕虫、清洁或钓鱼等已列出的自动化动作；
在中途出现无法识别或窗口失焦时停止并保留证据；
验证路线编辑后的结果与回放使用的路线一致。

路线文件的存储位置、格式、版本兼容性和编辑规则未在 README 中给出，因此不能在本页声明具体文件名或字段。

Core Flow

交互与地图测试应采用“输入—观察—判定—留证”的闭环。当前源材料没有足够信息验证具体函数调用顺序、异常分支或重试次数；以下是测试层面的验证流程，不代表未提供的内部实现。

准备 Python 3.12、标准 16:9 游戏窗口及可用的 Whimbox app/后端连接。
确认目标游戏画面可被截图获取。
执行一个最小交互动作，观察游戏是否产生可见反馈。
若动作涉及地图，分别记录小地图识别结果与大地图操作结果。
若结果异常，保存截图、日志和操作序列，并先排查窗口焦点、分辨率与性能。
确认基础交互后，再进入自动跑图或任务脚本联调。

故障分类与处理建议

现象	优先检查项	当前资料能确认的结论	尚待源码确认的内容
按键无效	游戏是否前台、分辨率、窗口状态	系统通过模拟鼠标键盘工作	具体输入后端、权限和焦点处理
截图异常	目标窗口、系统负载、16:9 条件	交互模块负责截图	截图格式、区域和失败异常
小地图识别失败	地图资源、画面比例、图像质量	地图模块负责小地图识别	模型、模板、阈值和重试
大地图无法操作	地图是否打开、输入是否送达	地图模块负责大地图操作	坐标换算和操作步骤
自动跑图偏离	路线版本、识别、视角和移动	当前只支持大世界和星海	路线格式、纠偏和恢复策略
运行卡顿	游戏与图像识别的资源占用	图像识别会额外消耗性能	采样频率、线程和限流策略
RPC 场景下无动作	app 与后端连接、RPC 请求	后端提供 RPC 服务	方法名、协议和错误码

配置、日志与运维证据

README 确认项目存在 configs/config.json、configs/agent_workspace/ 和 logs/，并将 whimbox/config/ 定义为全局配置模块。但当前资料没有列出配置键、默认值、环境变量覆盖方式或日志字段，因此本页不能提供配置表，也不能假设某个配置项控制按键、地图或截图行为。

排障记录至少应包含：

Python 版本；
游戏是否使用标准 16:9 分辨率；
游戏窗口是否前台且未被遮挡；
启动入口（Whimbox app 或命令行）；
测试场景（大世界、星海或其他场景）；
操作开始和失败时间；
操作步骤及预期结果；
失败前后截图；
logs/ 中对应时间段的日志；
是否可以重复失败，以及在降低系统负载后是否仍失败。

已知限制

以下限制由 README 明确说明：

仅支持 Python 3.12；
当前仅支持标准 16:9 分辨率；
图像识别会增加性能消耗，建议使用中高配 PC；
项目不修改游戏文件、不读写游戏内存，只截图并模拟鼠标键盘；
自动跑图暂时只支持大世界和星海。

以下内容在当前源材料中没有找到实现依据：具体按键名称、按键接口签名、鼠标坐标接口、截图 API、地图识别模型、地图坐标系、路线文件格式、异常类型、重试机制、并发模型、超时配置和自动恢复策略。对这些问题的测试结论应标记为“实现细节未在源代码资料中找到”，并在取得相应源文件后补充。

测试覆盖与扩展点

当前材料没有提供测试目录、测试用例、断言或 CI 配置，因此无法确认已有自动化测试覆盖率，也不能声明某个边界已经被测试保证。后续补充测试时，建议优先建立以下层次：

交互适配层的输入发送与释放行为测试；
截图区域、分辨率和窗口焦点的诊断测试；
小地图识别的固定截图回归测试；
大地图操作的可观察状态测试；
路线录制、编辑和回放的文件兼容性测试；
大世界与星海的端到端冒烟测试；
RPC 调用触发交互动作的集成测试。

这些是基于已知模块边界提出的测试规划，不是仓库中已经存在的测试实现。

项目入口与运行说明：README 中的“如何运行”与“注意事项”章节。
自动跑图与路线能力：README 中的“已有功能 / 自动跑图”章节。
模块边界：README 中的“项目结构”章节。
运行日志：项目中的 logs/ 目录；具体日志格式需以实际文件为准。
配置：项目中的 configs/config.json 与 whimbox/config/；具体配置键需以实际源代码为准。

资料完整性说明

本页依据当前提供的 README 内容编写。由于运行时未提供交互、地图及测试实现文件，也未提供可用于构造源码引用的文件引用基础 URL，因此没有虚构代码示例、API 签名、配置默认值或源码链接。要把本页扩展为可执行的接口级测试参考，需要补充读取 whimbox/interaction/、whimbox/map/、whimbox/view_and_move/、相关测试目录、配置文件和日志样例。