绝区零一条龙「委托助手」深度解析：对话/剧情/钓鱼辅助循环器的工作原理与配置指南

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

导读

委托助手（commission_assistant）是绝区零一条龙（ZenlessZoneZero-OneDragon）中一个定位特殊的辅助循环器：它不像其他 app 那样替你自动跑完一整条流程，而是在你手动推进剧情、钓鱼、战斗时，由 app 在一旁「打辅助」——自动点对话选项、跳过剧情、执行钓鱼指令、按需开启闪避与自动战斗。本文将以 docs/game/screens/委托助手.md 为骨架，结合 核心实现、screen_info 配置 与 配置类，完整讲解其三种运行模式、画面识别区域、多态辅助逻辑、全部可配置项与源码级实现原理。读完你可以完全理解该模块的运作机制，并能正确配置和使用它。

定位：它不是普通 app，而是「辅助循环器」

在绝区零一条龙的应用体系里，大多数 app（如空洞挑战、防卫战）会从进入界面开始，自动完成一整段玩法流程。而委托助手不是自动跑流程的 app，官方文档明确将其定义为辅助循环器：

用户手动推进剧情/钓鱼/战斗，app 监听键盘（dodge_switch/auto_battle_switch切模式）+ 自动点对话选项/跳过剧情/钓鱼指令/自动战斗。

因此commission_assistant的 screen_info 是非固定画面（source_image: 待补），它不是在等待某一个静态游戏画面出现，而是在一段不确定的多态循环中持续识别、持续辅助。这一点从代码注释也能得到印证（commission_assistant_app.py）：

"""委托助手:辅助工具,剧情/委托/钓鱼等画面自动推进。非玩法、无独立消耗。"""

从仓库元数据看，commission_assistant_const.py 定义了该模块的注册信息：APP_ID = "commission_assistant"、APP_NAME = "委托助手"、DEFAULT_GROUP = False、NEED_NOTIFY = False——「无独立消耗、无需通知」恰好印证了其纯辅助、不产出的定位。

三种运行模式：对话 / 闪避 / 自动战斗

CommissionAssistantApp通过run_mode字段维护当前辅助模式（源码 L55）：

模式切换完全依靠键盘监听。handle_init时注册键盘事件监听（_listen_btn），_on_key_press中根据按键切换模式（源码 L78-91）：

key = event.data if key == self.config.dodge_switch: if self.run_mode == 0: self.run_mode = 1 else: # 防止并发有问题导致值错乱 最后兜底成初始值 self.run_mode = 0 elif key == self.config.auto_battle_switch: if self.run_mode == 0: self.run_mode = 2 else: # 防止并发有问题导致值错乱 最后兜底成初始值 self.run_mode = 0

两个开关按键默认值分别为dodge_switch='5'、auto_battle_switch='6'（配置类 L71-L93），即按下数字键 5 切换闪避模式、数字键 6 切换自动战斗模式，再按一次回到对话模式。切换动作是无状态覆盖式的，代码注释明确写到「防止并发有问题导致值错乱，最后兜底成初始值」，可见模式状态机刻意保持了简单与健壮。

画面识别基础：委托助手 screen_info 的 14 个识别区域

辅助循环器识别画面依赖 assets/game_data/screen_info/commission_assistant.yml 中定义的识别区域。文档称其为 12 area，实际配置中共有14 个 area，可分为五组：

对话辅助（run_mode=0 的核心区域）

剧情辅助

剧情模式的判定入口是check_main_story()（源码 L383-L396）：对右上角区域做 OCR，若命中关键词['菜单', '跳过', '自动']中的任意一个，即判定进入剧情模式。

短信（knock knock）

玩法引导

通用区域

这些区域全部由screen_loader.get_area('委托助手', area_name)统一加载，在round_by_find_area/round_by_find_and_click_area/round_by_ocr_and_click等基础操作节点中复用——这也是整个 OneDragon 框架「screen_info 驱动」设计的一致体现。

核心辅助逻辑：CommissionAssistantApp多态循环

整个辅助器是一个由@operation_node装饰的多态状态机（commission_assistant_app.py），起始节点委托助手（dialog_mode）会根据画面状态流转到剧情模式、自动战斗模式、钓鱼、未知画面等节点。

主循环dialog_mode的判定优先级

入口节点dialog_mode（源码 L96-L147）每轮按固定优先级逐级判断当前画面：

1. 后台暂停检查：若配置了pause_in_background且游戏窗口不在前台，等待切回前台；
2. 模式切换：run_mode为 1/2 时加载战斗指令并跳转自动战斗模式；
3. 对话框确认：找到并点击对话框确认区域；
4. 战斗交互画面：识别到战斗画面的按键-交互，等待用户操作；
5. 大世界场景：识别大世界-普通/大世界-勘域，不干预；
6. 二级菜单：识别到左上角返回，等待用户操作；
7. 空洞处理：通过hollow_event_utils.check_in_hollow判断是否在零号空洞内，进入_handle_hollow；
8. 空洞通关弹窗：识别零号空洞-事件的通关-完成并点击；
9. 以上都不是 → 返回「检测剧情模式」，进入剧情处理。

从代码结构可以推断，这是一个保守优先的设计：凡是可能属于用户正在手动操作的界面（战斗交互、大世界、二级菜单），app 一律只等待不抢鼠标，只有明确的对话框、选项、确认按钮才主动点击。

对话辅助：黑白判定 + 白色选项 OCR + 点击保护

对话识别与点击是_do_dialog_click/_check_dialog/_click_dialog_options三组方法协作完成的：

1. 对话框内容判定（_check_dialog，源码 L187-L205）

area = self.ctx.screen_loader.get_area('委托助手', '对话框内容') if not cv2_utils.is_in_gray_mask(screen, rect=area.rect): return False # 字刚蹦出来的时候是灰色 所以不能加 rgb 颜色蒙版 ocr_result_list = self.ctx.ocr_service.get_ocr_result_list(image=screen, rect=area.rect) for ocr_result in ocr_result_list: if str_utils.with_chinese(ocr_result.data): return True return False

对话识别的两个关键手段（与文档备注一致）：

• 黑白蒙版判定：对话框内容区域使用is_in_gray_mask判断是否为黑白配色——非黑白的画面不算对话，避免误点击；
• 中文 OCR：对区域做 OCR 并检测中文文本；文字刚弹出时是灰色，因此不加颜色蒙版，保证字出现的瞬间就能被识别。

2. 选项点击（_click_dialog_options，源码 L207-L254）

选项区域（右侧/中间）使用color_range=[[240,240,240],[255,255,255]]的白色蒙版 OCR——选项文字是白色，颜色蒙版可大幅降低非选项文字的干扰。选中策略由配置dialog_option决定：

• LAST（最后一个，默认）：选 Y 轴最大的选项；
• FIRST（第一个）：选 Y 轴最小的选项。

3. 点击保护与误识别兜底（核心防呆机制）

文档中强调的CHOSEN_OPT_HOLD_SEC/CHOSEN_OPT_MAX_SEC在源码中有精确定义（L43-L44）：

self.CHOSEN_OPT_HOLD_SEC: float = 0.5 # 点击右侧选项之后的保护时间 self.CHOSEN_OPT_MAX_SEC: float = 2 # 一个按钮连续存在2s则大概率是误识别

• 保护时间（0.5s）：绝区零的按钮经常点了没反应且按钮变透明，即使 OCR 识别不到该选项也要「一直逮着选」，因此在点击后的 0.5s 保护期内会持续重复点击同一目标；
• 误识别兜底（2s）：若某个选项被选中后连续存在超过 2s，则认为该选项是误识别（用户想选别的但一直没变），配合check_same_opts（比较上次与本次选项集合是否完全一致）跳过这个「选不中」的选项；
• 最小点击间隔：OPTION_CLICK_INTERVAL_MIN = 0.1，与pyautogui.click()自带的 0.1s 相加约 0.2s 一次，最终取max(0.1, config.dialog_click_interval)。

此外dialog_clicked标志位处理「对话框内容为......导致 OCR 识别不到」的情况：一旦之前识别到对话框并点击过，之后连续几帧识别不到任何内容时仍会继续点击屏幕，直到未知画面节点重置该标志（源码 L181-L185、L499-L504）。

剧情模式：自动播放 / 跳过剧情的完整流程

story_mode节点（源码 L398-L497，node_max_retry_times=5）根据配置的story_mode分两套策略：

AUTO（等待剧情自动播放）状态机按顺序尝试：

1. 通过中间选项区域模板定位 Y 轴后点击中间选项（模板位置点击无反应，仅用模板定位坐标）；
2. 右上角区域 OCR 到「自动」→ 剧情正在自动播放，每秒检测一次；
3. OCR 到「菜单」→ 点击展开剧情菜单，等待 1s 动画结束；
4. 点击按钮-自动切换到自动播放模式。

SKIP（跳过剧情）状态机：

1. 右上角区域 OCR「跳过」并点击（白色蒙版[[240,240,240],[255,255,255]]），成功等待 0.4s；
2. 若未识别到「跳过」（主线场景），按优先级依次 OCR「菜单」「自动」并点击，同时记录main_story_click_time；
3. 识别跳过后的确认框（对话框确认）并点击；
4. 关键防误点：点击菜单后的 5 秒内不处理对话框与黑屏（if now - self.main_story_click_time <= 5），因为菜单展开有动画，期间点击容易误触。

同时_do_dialog_click在 SKIP 模式下传入check_center_words=False，此时中间选项区域不再做文字 OCR，而是用cv2_utils.is_colorful判断是否为黑屏——黑屏（饱和度阈值 1、色彩比例阈值 0.01）就点击翻页。这种「黑屏点击」方式不会在花色画面抢鼠标，用户仍可手动操作。

剧情模式之后还有一批易与剧情穿插的界面需要排除：二级菜单（等待用户）、勘域菜单（不自动点击）、空洞自由行动（战斗-菜单，不自动点击）、玩法引导（等待用户点击）、短信、钓鱼。这一顺序保证了辅助器只在自己能处理的画面上行动。

闪避与自动战斗：auto_mode边界处理

当run_mode为 1/2 时，_load_auto_op（源码 L348-L356）按子目录加载战斗指令：

self.ctx.auto_battle_context.init_auto_op( sub_dir='auto_battle' if self.run_mode == 2 else 'dodge', op_name=self.config.auto_battle if self.run_mode == 2 else self.config.dodge_config ) self.ctx.auto_battle_context.start_auto_battle()

auto_mode节点（源码 L337-L346）每轮调用auto_battle_context.check_battle_state检测战斗状态，按battle_assistant_config.screenshot_interval的节奏循环；切回对话模式（run_mode == 0）时立即stop_auto_battle()。handle_pause/handle_resume中也会对称地停止/恢复自动战斗，与暂停状态保持一致。文档将 auto_battle 称为「边界 app」——它属于「含战斗辅助」而非「不含战斗」，因此委托助手里自动战斗是可选的边界能力。

钓鱼辅助：抛竿/等待/上鱼/连点/长按

钓鱼是委托助手最完整的子模块之一，进入条件在check_fishing（源码 L358-L381）：左上角出现钓鱼的按键-返回，且指令文本区域OCR 命中「点击按键抛竿」，即切换到钓鱼节点（node_max_retry_times=50，约 5s 未识别到指令自动退出）。

钓鱼指令的执行在on_finishing（源码 L506-L598），对指令文本区做 OCR 后与五类目标指令做 difflib 相似度匹配：

指令结束后的收尾也做了完整处理：点击空白处关闭、识别标题-挑战结果后点确定、等待回到大世界（WaitNormalWorld检测一次）。钓鱼画面在 assets/game_data/screen_info/fishing.yml 中单独建档，共 10 个区域：指令文本区域、按键-时机上鱼、按键-左/右、按键-返回、按键-强力-左/右、按钮-点击空白处关闭、标题-挑战结果、按钮-确定——与文档「钓鱼画面单独建档，指令文本区域 + 按键-左/右/时机上鱼」的描述一致且更完整。

短信（knock knock）自动翻页与关闭

check_knock_knock（源码 L311-L335）先识别标题-短信确认短信界面，再对区域-短信-文本框做 OCR，找出 Y 轴最大的文本并点击（模拟人往下翻短信）；当最下方文本命中「以上为最新」时，点击按钮-短信-关闭关闭界面。

空洞内事件处理

_handle_hollow（源码 L277-L297）在检测到身处零号空洞时启用，先初始化空洞地图服务，判断当前邦布位置（cal_current_map_by_screen），若在地图走格子则等待；否则调用hollow_event_utils.check_event_text_and_run处理空洞对话事件（hollow_event_utils.py）。事件处理的核心逻辑是：对事件文本区域裁图，用cv2.inRange((230,230,230),(255,255,255))提取白色文字后 OCR，再与事件处理器（handlers）的候选文本做双向 difflib 匹配（选项与识别文本多对多时需双向一致才算匹配成功），从而选中正确的事件选项。

配置项详解：默认值与源码依据

委托助手的全部配置由CommissionAssistantConfig（commission_assistant_config.py）管理，均带默认值，未配置时可直接运行：

两点值得注意的实现细节：

• story_mode的枚举实际是三态的（StoryMode：CLICK自动点击 /AUTO等待剧情自动播放 /SKIP跳过剧情），文档只强调了 AUTO 与 SKIP 两种，默认值其实是 CLICK——自动点击模式下_do_dialog_click会走「对话中点击」逻辑，兼顾普通对话与剧情点击；
• dialog_option的枚举（DialogOptionEnum：第一个/最后一个）直接决定_click_dialog_options中按 Y 轴最大值还是最小值选选项（源码 L239-L246）。

GUI 设置界面与模块装配

在 GUI 中，CommissionAssistantRunInterface（commission_assistant_interface.py）提供完整的配置界面（导航名「委托助手」），包含：后台暂停开关、对话选项优先级下拉框、对话点击间隔（步长 0.05s）、剧情模式下拉框、无内容等待时间（步长 0.5s）、自动闪避配置下拉框 + 开关按键、自动战斗配置下拉框 + 开关按键。闪避与自动战斗的选项列表分别来自get_auto_battle_op_config_list('dodge')和get_auto_battle_op_config_list('auto_battle')，即从config/auto_battle、config/dodge目录下扫描现有指令配置填充。

模块的装配遵循 OneDragon 的工厂模式：CommissionAssistantAppFactory（commission_assistant_app_factory.py）提供create_application创建应用实例、create_config创建配置实例，由框架统一注册与调度。

使用场景与实战建议

综合文档与源码，委托助手适合以下场景：

1. 手动过剧情/委托：开对话模式，用户只看剧情，app 自动点选项、翻页、处理确认框；右上角剧情控制（跳过/自动）也由 app 接管；
2. 钓鱼：进入钓鱼画面后自动识别指令并执行抛竿/等待/连点/长按，比赛类钓鱼的挑战结果弹窗也能自动关闭；
3. 战斗辅助：按键 5 切闪避、按键 6 切自动战斗，临时接管战斗，再按一次回到对话模式；
4. 短信/玩法引导：knock knock 短信自动翻到底并关闭；战斗/玩法引导弹窗 app 不做处理、等待用户点击，避免抢鼠标。

实战注意事项（均有源码依据）：

• 需要把游戏窗口保持前台（pause_in_background=True时后台会暂停）；若想后台运行需手动关闭该开关；
• 对话选项的「最后一个/第一个」策略对主线多选有实际影响，默认选最后一个更符合「推进剧情」的诉求；
• 跳过剧情时点击菜单后 5 秒内不会处理对话框与黑屏，这是有意为之的防动画误点设计，不要误以为 app 卡住；
• 钓鱼节点的node_max_retry_times=50意味着约 5 秒识别不到任何指令就会自动退出钓鱼状态。

小结

委托助手（commission_assistant）是绝区零一条龙中「人机协同」的典型模块：人以手动方式主导剧情、钓鱼与战斗，app 通过 14 个画面识别区域、多态循环状态机 与完整配置体系 提供对话自动点击、剧情跳过/自动播放、钓鱼指令执行、短信翻页、空洞事件处理以及可选的闪避/自动战斗辅助。它的实现同时展示了 OneDragon 框架的三项核心能力：screen_info 驱动的区域化画面识别、operation_node 状态机编排、以及「识别-点击」过程中对游戏按钮特性（透明、无反馈、动画）的工程化容错。对该模块的设计思路（保护时间、误识别兜底、黑白蒙版判定、黑屏点击等）感兴趣的开发者，可以直接阅读 commission_assistant_app.py 的完整实现。

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