企业官网建设流程全解析

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

摘要导读：本篇以《绝区零 一条龙》（ZenlessZoneZero-OneDragon）自动化框架中的「快捷手册」屏幕识别文档为核心，深入拆解这一"玩法总入口"的界面结构、TAB 状态流转、基于 OCR 与模板匹配的屏幕识别方案，并结合仓库源码剖析TransportByCompendium的完整传送调用链，以及ChargePlanApp.check_battery_charge的「电量检测」图像分析流水线。读完本文，你将掌握快捷手册在自动化流程中的定位、源码级传送实现细节与资源栏数字识别的底层原理，可直接在调试、二次开发或文档贡献中复用这些知识。

快捷手册：绝大多数周期与常驻玩法的统一入口

在绝区零中，「快捷手册」是大世界右上角可随时打开的游戏内玩法总入口。绝大多数周期玩法与常驻玩法——包括式舆防卫战、迷失之地、零号空洞、危局强袭战、咖啡店、影像店等——的入口都集中在此，因此它也是自动化框架中高频使用的关键屏幕。框架中几乎所有"传送到某个玩法"的路径都会经过这里，其通用传送接口即TransportByCompendium(tab_name, category_name, mission_type_name)（见 tp_by_compendium.py）。

界面按5 个 TAB组织：目标 / 日常 / 训练 / 作战 / 战术。每个 TAB 下以"玩法卡片"形式罗列对应玩法，卡片包含玩法名、奖励进度以及「前往」传送按钮，点击「前往」会弹出传送确认框，确认后直接传送至该玩法入口。该屏幕的详细识别文档见 docs/game/screens/快捷手册.md。

何时出现与状态流转

入口与退出

• 入口：在大世界点击右上角「快捷手册」按钮（屏幕坐标约(1531, 60)，需通过pc_alt键触发鼠标指针显示后才能点击），随后进入快捷手册界面。
• 退出：按Esc或点击左上角返回按钮回到大世界。在 screen_info 配置中，各 TAB 屏的「按钮-关闭」区域（1721,229,1799,307）的goto_list指向菜单与大世界-普通，即关闭按钮同时处理了回菜单与回大世界两条去向。

完整流转链

大世界 → 点「快捷手册」按钮 → 快捷手册界面 → 选择 TAB（目标/日常/训练/作战/战术） → 点击玩法卡片「前往」→ 弹出「是否立即传送?」确认框 → 点击「确认」→ 传送到该玩法入口

TAB 切换坐标

顶部 TAB 栏位于y ≈ 161，五个 TAB 的横向点击锚点依次为：目标x=769、日常x=955、训练x=1142、作战x=1330、战术x=1514。各 TAB 屏配置中，TAB 区域统一为708,140,1636,220，当前所在 TAB 以id_mark: true标记，并附带金黄色的color_range（(200,160,0)至(255,210,60)），供画面状态判断区分当前激活的 TAB（可对照 compendium_training.yml 与 compendium_primer.yml）。

识别特征与稳定锚点

自动化识别依赖以下稳定特征：

1. TAB 文字：顶部「目标 / 日常 / 训练 / 作战 / 战术」五个文字区域，位置固定，是画面状态判定的首要锚点。
2. 左上标题：界面左上角显示 "QUICK ... HANDBOOK" 英文标题，用于确认当前确为快捷手册界面。
3. 右上资源栏：三段右对齐数字——电量（3 位，如240/240）、储蓄电量（4 位，上限 2400）、以太电池数（3 位，有上限）。该栏是框架"体力计划"（ChargePlanApp）读取当前体力的关键数据源，识别逻辑详见下文"电量识别流水线"。

从 screen_info 配置看，资源栏区域1220,35,1770,110同时被定义为两套识别方式：资源栏area 采用color_range（(208,208,208)至(255,255,255)）做灰度过滤；以太电池area 则采用模板匹配（template_sub_dir: compendium、template_id: battery），用于定位电池图标。

可交互元素一览

其中"前往"按钮的点击存在一个实测细节：OCR 返回的是文字框左上角坐标，但实际可点击中心略偏右下，直接点文字框坐标可能不触发，必须点击中心附近才会弹出确认框。源码中handle_go_button对 OCR 框使用mr.center作为点击点（见下文），正是对这一偏移的规避。

TransportByCompendium：源码级传送链路

TransportByCompendium是框架内通过快捷手册完成玩法传送的标准操作，完整实现位于 tp_by_compendium.py。它继承ZOperation，构造参数为(ctx, tab_name, category_name, mission_type_name=None)；其中若mission_type_name == '自定义模板'，会自动替换为'基础材料'（因为自定义模板无法直接传送，源码注释明确说明这一限制）。该操作最后不会等待加载完毕，由调用方自行决定是否等待。

其节点流程为：

返回大世界（BackToNormalWorld，若已在快捷手册-XX 屏则跳过） → 快捷手册（round_by_goto_screen 切换到 '快捷手册-<tab>'） → 选择分类（CompendiumChooseCategory） → 选择副本分类（CompendiumChooseMissionType）

第一步：返回大世界

起始节点back_to_world先调用check_screen_with_can_go判断当前画面是否为快捷手册-{tab_name}，若已是目标 TAB 屏则直接成功，否则先执行BackToNormalWorld(ctx, ensure_normal_world=True)确保回到大世界，为后续"从大世界打开快捷手册"做准备。

第二步：切换 TAB

节点choose_tab通过round_by_goto_screen(screen_name=f'快捷手册-{self.tab_name}')完成屏幕状态切换。这里依赖的是上文提到的各 TAB 屏配置：每个 TAB 区域带goto_list，指向对应的快捷手册-训练/目标/日常/作战/战术屏幕，点击后画面状态随之迁移。

第三步：选择分类

CompendiumChooseCategory（见 compendium_choose_category.py）在已打开的快捷手册中定位左侧「分类列表」区域（164,287,429,870），对该区域执行crop_and_run_ocr（merge_line_distance=40合并相近行），用str_utils.find_by_lcs(gt(category_name), ocr_result, percent=0.5)做最长公共子序列（LCS）模糊匹配，命中后点击该文字框中心。找不到分类时返回round_retry(status=f'找不到 {category_name}')。

第四步：选择副本并传送

CompendiumChooseMissionType（见 compendium_choose_mission_type.py）是整个链路最复杂的部分，按副本类型分两条路径：

• 常规副本：先通过compendium_service.get_same_category_mission_type_list取得同分类下所有副本及其别名，对「副本列表」区域（498,308,848,884）做 OCR，用difflib.get_close_matches模糊匹配目标副本名。若目标尚未出现在可视区（识别到的副本序号小于目标序号），则调用handle_scroll向下滑动后重试（节点node_max_retry_times=20）。
• 代理人方案培养：当mission_type.is_agent_plan为真时走专门路径——对「目标列表-训练」区域做头像识别（find_character_avatar_center_with_offset），点击偏移(0, -80)上移以命中「前往」按钮。特别注意：恶名狩猎页顶部有暗色分层条会干扰头像识别，因此该类使用收窄后的专用取景区域「目标列表-训练-恶名狩猎」（1254,552,1312,894）。

随后handle_go_button对「前往列表」区域（1312,334,1646,890）做 OCR，逐个匹配文字「前往」，取位于目标副本下方且距离最近的前往按钮中心点击——这正是规避文字框偏移问题的关键实现。若副本名已出现但「前往」尚未出现，则向下固定滑动 200 像素重试。

最后节点confirm调用round_by_find_and_click_area点击「传送确认」区域（1030,602,1230,650），成功等待 5 秒完成传送。

实际调用方

从源码检索看，TransportByCompendium被多个玩法模块复用，是框架通用的"开局传送"手段：

• charge_plan_app.py（体力计划，传送至训练类副本）
• shiyu_defense_app.py（式舆防卫战）
• lost_void_app.py（迷失之地）
• withered_domain_app.py（零号空洞-枯萎域）
• notorious_hunt_app.py（恶名狩猎）

电量识别：ChargePlanApp.check_battery_charge 与「电量检测」流水线

为什么在快捷手册读电量

体力计划（ChargePlanApp）在执行刷取计划前必须知道当前剩余电量，而快捷手册右上角资源栏恰好集中展示电量 / 储蓄电量 / 以太电池三项数据，因此框架选择在这里统一读取。完整实现位于 charge_plan_app.py。

图像分析流水线

check_battery_charge节点调用self.ctx.cv_service.run_pipeline('电量检测', self.last_screenshot)运行「电量检测」流水线，其定义见 电量检测.yml，共三步：

- step: 按区域裁剪 # screen_name: 快捷手册, area_name: 以太电池 - step: HSV 范围过滤 # hsv_color: [160, 0, 255], hsv_diff: [20, 10, 100] - step: OCR识别 # draw_text_box: true

即：先按「快捷手册->以太电池」区域裁剪出资源栏局部图，再做 HSV 颜色过滤以强化数字前景、压制背景干扰，最后对整栏执行 OCR。

OCR 结果的字段归位解析

OCR 拿到的是若干文本项及检测框，_parse_battery_charge_ocr（charge_plan_app.py）负责把散落的数字归位到三个字段：

• 取数：每个识别文本以/为分界取左段数字（如129/240 -> 129），纯数字直接用，无数字跳过——这样"电量 129/240"只取当前值 129。
• 归位：三个字段的检测框中心固定锚点为field_centers = (173, 348, 485)（相对裁剪区域，来自测试样例统计）；每个识别项按框中心与三个锚点的横向距离就近归入一个字段，同一字段多个候选时保留离锚点更近的。
• 兜底：某字段无候选时补 0；即使全部识别失败也返回(0, 0, 0)而不抛异常，保证流程鲁棒性。

识别结果写入self.battery_charge / self.backup_battery_charge / self.ether_battery并记录到运行记录run_record，随后据此判断是否执行计划、是否补体（_can_restore_charge支持用储蓄电量或以太电池折算补体）、以及是否跳过电量不足的计划。

合成电池计划

当计划分类为「合成电池」时，check_before_transport直接返回合成电池状态，转入exchange_ether_battery节点执行ExchangeEtherBattery操作（见 exchange_ether_battery.py）。该路径对应快捷手册界面中点击资源栏「以太电池」图标 → 资源详情 → 「[获取] 合成」进入道具处理的完整交互链，是体力计划中"电量不足时用以太电池合成补充"的入口。

screen_info 配置体系：按 TAB 分文件

快捷手册的屏幕配置采用"主屏 + 分 TAB 屏"的组织方式，全部位于 assets/game_data/screen_info/：

各分 TAB 屏结构高度一致：五个TAB-XXarea（含id_mark与金色color_range标记当前激活 TAB）、一个「按钮-关闭」area，以及各 TAB 特有的内容区。compendium.yml主屏还定义了「活跃度奖励」系列区域（奖励-4、确认、奖励预览、今日最大活跃度）与「每日怪物卡双倍掉落次数」区域，后者被 ChargePlanApp 的check_double_reward_event用于 OCR 识别实战模拟室双倍活动的剩余次数。

识别快照与内容清单

目标 TAB

• 匹配画面：快捷手册-目标，is_precise=true
• TAB：目标 / 日常 / 训练 / 作战 / 战术
• 内容（目标 / 进度类玩法）：运算中枢修复计划（阶段 319）、绳匠传奇、数域特训、高压测试、集训效率、「布连邦」/「好棒邦」奖章 等。

作战 TAB

• 匹配画面：快捷手册-作战，is_precise=true
• 内容（作战玩法，各带「前往」+ 周限倒计时）：
  • 零号空洞、迷失之地、式舆防卫战（倒计时示例：04 天 13 时）、危局强袭战（09 天）、溯影行动、临界推演、拟真鏖战试炼、断层之谜、区域探索、结局收集。
  • 顶部：悬赏委托进度（如 8000/8000）与剩余时间。

实践要点与已知限制

1. 前往按钮偏移：OCR 返回文字框左上角，实际可点中心略偏右下；务必使用检测框中心（源码handle_go_button的做法）而非左上角坐标点击。
2. TAB 快照缺口：日常 / 训练 / 战术三个 TAB 的内容快照在当前文档中尚未采集，对应的玩法卡片细节有待补充（screen_info 配置已就绪）。
3. 传送确认：点击「前往」后必然弹出「是否立即传送?」通用确认框，需等待确认 area 出现后再点击「确认」。
4. 自定义模板不可直达：mission_type_name == '自定义模板'会被自动替换为基础材料，这是TransportByCompendium源码中明确给出的行为约束。
5. 电量读取是流程前置依赖：体力计划在快捷手册内先读电量再决定是否传送，识别失败以(0,0,0)兜底，避免异常中断但可能误判为电量耗尽，调试时应关注电量检测流水线的 OCR 输出。

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