企业官网建设流程全解析

• 桌面应用
• RPA
• 计算机视觉

导读

本文聚焦于「绝区零 一条龙（ZenlessZoneZero-OneDragon）」自动化框架中的「兑换码输入」画面，深入剖析该模态弹窗的触发时机、状态流转、识别锚点与可交互元素，并结合仓库源码展开兑换码自动兑换应用（RedemptionCodeApp）的完整执行链路。读完本文，你将掌握该画面在 screen_info 体系中的收录现状、menu.yml中 area 的定义方式，以及如何从配置层（redemption_codes）到运行层（used_code_list记录）实现兑换码的自动领取。

一、画面定位：模态弹窗的触发与状态流转

「兑换码输入」是一个模态弹窗，并非独立的游戏主画面，其入口为「菜单-更多功能」页面中的「兑换码」按钮。其完整进入路径为：

游戏内打开菜单 → 底部点「更多」→ 在更多功能区域点「兑换码」→ 弹出「兑换码输入」模态框

对应的识别文档位于 docs/game/screens/兑换码输入.md，其中appears_in: [菜单-更多功能]明确记录了该弹窗的挂靠归属。

该画面的状态流转可归纳为下表：

其中「全部兑换完毕 → 返回大世界」由 redemption_code_app.py 中的back节点实现：当input_code节点检测到已无未使用兑换码时返回全部兑换完毕状态，随后创建BackToNormalWorld操作并执行，将游戏拉回大世界。

二、识别特征与稳定锚点

该弹窗的识别主要依赖以下稳定锚点（坐标为 1920×1080 分辨率下的像素位置）：

• 标题「兑换码」：位于屏幕约 (655, 357)，作为画面存在的首要文本锚点；
• 输入框（占位文本「请输入兑换码」）：位于约 (880, 555)，含粘贴按钮；
• 兑换按钮：位于约 (950, 697)，亮色可点，空输入状态下同样可点击；
• 关闭 X：位于约 (1222, 336)，右上角。

值得注意的是，该弹窗为半透明遮罩，背后透出的是「菜单-更多功能」页面，这一特性已通过 vision 确认。正因如此，该画面在匹配逻辑上存在特殊性——它没有独立的精确匹配，菜单 / 画面-通用 / 菜单-更多功能 三个候选画面在is_precise=False时均为模糊匹配。

三、screen_info 缺口：area 暂挂在 menu.yml 下

这是本文档标注的最核心工程问题（⚠️ screen_info 缺口）：「兑换码输入」画面目前无独立 screen 收录，相关 area 全部定义在菜单画面的配置文件中。

在 menu.yml 中可找到两个关键 area 定义：

此外，「关闭 X」按钮复用「画面-通用」的 template 匹配（conf 0.966，位置 1222,336），同样不归属本画面的独立 screen。

文档给出的改进建议是：可考虑新建独立 screen（例如兑换码输入）来提升识别精度，并把输入框、标题等锚点一并收录。这对后续维护者是一个明确的待办方向。

四、自动兑换应用的完整状态机

「兑换码输入」画面是 RedemptionCodeApp（APP_ID = "redemption_code"，见 redemption_code_const.py）的核心操作画面。该应用以装饰器定义状态机节点，完整链路如下：

检测新兑换码（start） → 打开菜单 → 点击更多 → 点击兑换码 → 输入兑换码 → 兑换后确认 → 返回大世界

4.1 检测新兑换码：运行记录的过滤逻辑

check_new_code节点调用运行记录获取未使用列表：

self.unused_code_list = self.run_record.get_unused_code_list(self.run_record.get_current_dt())

对应实现位于 redemption_code_run_record.py 的get_unused_code_list：先按end_dt >= 当前日期过滤出未过期的有效码，再从有效码中剔除used_code_list（已使用记录）中的码。若列表为空则返回无新的兑换码，直接结束本次运行。

4.2 菜单导航：OCR 限定区域点击

open_menu通过round_by_goto_screen(screen_name='菜单')进入菜单画面；click_more使用 OCR 在「底部列表」area（见 menu.yml，pc_rect 为 (200,924)~(1728,1058)）内查找文本「更多」并点击；click_code则在「更多功能区域」（(474,280)~(1440,904)）内 OCR 查找「兑换码」并点击，同时将code_idx重置为 0。

这印证了文档备注中的描述：打开菜单「更多」+ 点「兑换码」入口走 OCR（round_by_ocr_and_click+get_area限定区域），而点输入框走round_by_click_area直点 area（非 OCR）。

4.3 输入兑换码：keyboard.type 而非 MCP 输入

input_code节点是本文档备注中特别强调的实现细节，源码见 redemption_code_app.py：

self.round_by_click_area('菜单', '兑换码输入框') time.sleep(1) self.ctx.controller.keyboard_controller.keyboard.type(self.unused_code_list[self.code_idx]) time.sleep(6) return self.round_by_find_and_click_area(self.last_screenshot, '菜单', '兑换码兑换', success_wait=1, retry_wait=1)

要点拆解：

• 点击输入框直接使用 area（round_by_click_area('菜单', '兑换码输入框')），不经过 OCR；
• 文本输入使用keyboard_controller.keyboard.type()模拟键盘逐字输入，并非MCP 的input_text；
• 输入后sleep(6)等待界面响应（游戏内弹窗输入通常有聚焦与渲染延迟）；
• 随后round_by_find_and_click_area在「菜单 / 兑换码兑换」area 上查找并点击「兑换」按钮，成功等待 1 秒，失败重试等待 1 秒。

4.4 兑换后确认：统一二次点击并记账

confirm_code节点在兑换后再次执行round_by_find_and_click_area点击「兑换码兑换」按钮（用于消掉可能出现的兑换结果弹窗/重复点击）。只要点击成功，就将当前码写入used_code_list并推进code_idx：

self.run_record.add_used_code(self.unused_code_list[self.code_idx]) self.code_idx += 1

add_used_code实现见 redemption_code_run_record.py，将码追加进used_code_list并持久化。这也解释了文档中「appconfirm_code当前不区分成功/失败 UI，统一再次点 + 记used_code」的现状——兑换结果弹窗（成功「兑换成功」/ 失败「兑换码无效」）尚未覆盖，需有效兑换码才能触发采集，属于待补项。

4.5 循环与收尾

node_from装饰器将「输入兑换码」和「兑换后确认」连成循环：第一次兑换从「点击兑换码」进入，后续兑换从「兑换后确认」返回。当code_idx >= len(unused_code_list)时，input_code返回全部兑换完毕，状态机跳转至back节点执行BackToNormalWorld，回到大世界，一次自动兑换任务结束。

五、配置层：兑换码数据如何管理与合并

自动兑换的数据来源是redemption_codes配置，结构为codes: {兑换码: 过期时间(YYYYMMDD)}。仓库自带的示例见 config/redemption_codes.sample.yml：

codes: ZZZ888: 20990101 CLARET0909: 20260829

5.1 双配置合并：用户配置优先

RedemptionCodeConfig 管理两类 YamlConfig：

• user_config：用户配置文件（可读写，redemption_codes）；
• sample_config：示例配置文件（只读，read_sample_only=True始终读 sample 文件）。

读取时先加载 sample 配置，再用用户配置覆盖，实现「用户配置优先」；保存时只写入用户配置文件。该合并逻辑在codes_dict属性中实现，并同步应用于运行记录加载（见 redemption_code_run_record.py）。

5.2 配置的 CRUD 能力

RedemptionCodeConfig提供完整的管理接口：

• add_code(code, end_dt=20990101)：新增兑换码，end_dt默认 20990101（即默认长期有效）；
• update_code(old_code, new_code, end_dt)：修改码文本或过期日期，改名时先删除旧码；
• delete_code(code)：删除指定码；
• add_sample_code/delete_sample_code/clean_expired_sample_codes(today)：操作 sample 配置，供 CI 脚本使用——仓库的 tools/ci/update_redemption_code.py 与 .github/workflows/update-redemption-code.yml 即用于自动维护示例兑换码并清理过期项。

5.3 图形化配置界面

用户可在 GUI 中维护兑换码，对应界面为 redemption_code_setting_interface.py：

• CodeCard：每张卡片包含兑换码输入框、过期日期输入框（QIntValidator+ 最大 8 位）和删除按钮；
• sample 配置中的码以只读卡片展示（readonly=True，不可删除），用户自建码可编辑删除；
• 新增卡片默认过期日期为当前日期 + 30 天（datetime.now() + timedelta(days=30)）；
• 重复码会触发兑换码已存在的警告提示（InfoBar.warning）。

该界面的挂载通过 redemption_code_app_setting.py 的RedemptionCodeAppSetting（setting_type = SettingType.INTERFACE）注册，工厂类 redemption_code_factory.py 负责创建应用、运行记录与全局配置（配置不依赖instance_idx与group_id）。

六、兑换结果弹窗：已知缺口与待补说明

文档在「识别快照」中明确标注了两个待补项：

1. 兑换结果弹窗未覆盖：需要有效兑换码触发（成功「兑换成功」/ 失败「兑换码无效」），当前未截图采集，confirm_code采用不区分结果的二次点击策略作为临时方案；
2. 独立 screen 缺失：当前弹窗依赖菜单画面的 area 定义完成识别，OCR 快照中「兑换码兑换」（conf 0.963）与「关闭」（conf 0.966）均为跨 screen 的模糊命中。

这两项缺口的完整记录均保留在 docs/game/screens/兑换码输入.md 中，是后续开发者补充画面收录时最直接的参考起点。

七、画面识别实测快照（2026-07-11 核对）

文档记录的输入态识别快照如下：

• 匹配画面：无精准匹配（菜单 / 画面-通用 / 菜单-更多功能 均is_precise=False模糊）；
• 模糊命中 area（跨 screen）：

• OCR 结果：兑换码 / 请输入兑换码 / 兑换。

可见当前识别链路完全建立在「菜单画面 + 通用画面」的既有资源之上，这也再次呼应了文档备注中「新建独立 screen 提升识别精度」的工程建议。

结语

「兑换码输入」虽只是一个模态弹窗，却串联起了 OneDragon 中「画面识别 → 状态机编排 → OCR/area 点击 → 键盘输入 → 配置管理 → 运行记录持久化」的完整自动化链路。理解它的识别现状（无独立 screen、area 借挂 menu.yml）与RedemptionCodeApp的状态机实现，是继续完善兑换码模块（尤其是补全兑换结果弹窗与独立 screen 收录）的前提。

• 桌面应用
• RPA
• 计算机视觉