feat(avatar): MAA 完整流程——点击槽位+OCR 干员名+截取头像存盘

locate_oper: 有缓存→TemplateMatch；无缓存→逐个点击槽位→OCR 干员名(BattleOperName roi)→存头像→关闭。

OCR ROI [5,177,191,37] 从 MAA tasks.json BattleOperName 获取。

executor._locate_oper 简化为调用 avatar.locate_oper(context, ctrl, name)。

ruff/pyright 全过。

Author: Windsland52

custom/core/avatar.py

@@ -1,32 +1,33 @@
 """头像定位 + 运行时自学习（MAA 方案）。
 
-流程（移植自 MAA BattlefieldMatcher::deployment_analyze）：
-1. detect_slots: 用 BattleOpersFlag 模板在待部署区找到所有干员槽位
-2. locate_avatar: 从每个槽位提取头像，和缓存做 TemplateMatch
-3. learn_avatar: 点击未知干员 → OCR 名字 → 截取头像存盘
-
-模板来源：MaaAssistantArknights/resource/template/Battle/BattleFlag/BattleOpersFlag.png
-偏移量来源：tasks.json BattleOperAvatar.rectMove = [7, 32, 60, 60]
+完整流程（移植自 MAA BattlefieldMatcher + BattleHelper::update_deployment_）：
+1. detect_slots: BattleOpersFlag 模板匹配 → 所有干员槽位
+2. locate_oper: 遍历槽位 → 有缓存则 TemplateMatch → 无缓存则点击+OCR+存头像
+3. OCR ROI 来自 MAA BattleOperName task: [5, 177, 191, 37]
 """
 
 from __future__ import annotations
 
 import json
 import logging
+import time
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 import numpy as np
 
 if TYPE_CHECKING:
     from maa.context import Context
+    from maa.controller import Controller
 
 logger = logging.getLogger(__name__)
 
-# MAA 常量（1280×720 坐标）
-_FLAG_ROI = [33, 600, 1245, 18]  # BattleOpersFlag roi
+# MAA 常量（1280×720）
+_FLAG_ROI = [33, 600, 1245, 18]
 _FLAG_THRESHOLD = 0.65
-_AVATAR_OFFSET = [7, 32, 60, 60]  # BattleOperAvatar rectMove（相对 flag）
+_AVATAR_OFFSET = [7, 32, 60, 60]  # BattleOperAvatar rectMove
+_NAME_ROI = [5, 177, 191, 37]  # BattleOperName OCR roi
+_DETAIL_WAIT = 0.5  # 等详情页打开
 
 
 def _avatar_dir() -> Path:
@@ -52,11 +53,7 @@ def detect_slots(
     image: np.ndarray,
     threshold: float = _FLAG_THRESHOLD,
 ) -> list[dict]:
-    """用 MAA TemplateMatch 检测待部署区所有干员槽位。
-
-    Returns:
-        [{"rect": [x, y, w, h], "avatar_rect": [ax, ay, aw, ah]}, ...]
-    """
+    """用 TemplateMatch 检测待部署区所有干员槽位。"""
     reco_detail = context.run_recognition(
         "DetectSlots",
         image,
@@ -66,15 +63,14 @@ def detect_slots(
                 "template": "BattleOpersFlag.png",
                 "threshold": threshold,
                 "roi": _FLAG_ROI,
-                "method": 5,  # TM_CCOEFF_NORMED
-                "green_mask": True,  # 模板黑色区域已转绿，green_mask 忽略
+                "method": 5,
+                "green_mask": True,
                 "order_by": "Horizontal",
             }
         },
     )
 
     if not reco_detail or not reco_detail.hit:
-        logger.debug("未检测到干员槽位")
         return []
 
     slots = []
@@ -83,124 +79,179 @@ def detect_slots(
         if box is None:
             continue
         fx, fy, fw, fh = box
-        # 头像区域 = flag 位置 + avatar offset
         ax = int(fx + _AVATAR_OFFSET[0])
         ay = int(fy + _AVATAR_OFFSET[1])
         aw = _AVATAR_OFFSET[2]
         ah = _AVATAR_OFFSET[3]
+        click_x = int(fx - 45 + 75 // 2)
+        click_y = int(fy + 6 + 120 // 2)
         slots.append(
             {
                 "flag_rect": (int(fx), int(fy), int(fw), int(fh)),
                 "avatar_rect": (ax, ay, aw, ah),
-                "click_rect": (
-                    int(fx - 45),
-                    int(fy + 6),
-                    75,
-                    120,
-                ),  # BattleOperClickRange
+                "click_pos": (click_x, click_y),
             }
         )
 
     logger.info("检测到 %d 个干员槽位", len(slots))
     return slots
 
 
-def locate_avatar(
+def has_avatar(oper_name: str) -> bool:
+    char_id = _get_char_id(oper_name)
+    if not char_id:
+        return False
+    return (_avatar_dir() / f"{char_id}.png").exists()
+
+
+def locate_oper(
     context: Context,
-    image: np.ndarray,
+    ctrl: Controller,
     oper_name: str,
-    threshold: float = 0.7,
 ) -> tuple[float, float] | None:
-    """在待部署区定位指定干员。
+    """定位指定干员在待部署区的位置。
 
-    1. detect_slots 找所有槽位
-    2. 用缓存的干员头像在每个槽位做 TemplateMatch
+    MAA 方案：
+    1. 检测所有槽位
+    2. 有缓存 → TemplateMatch 匹配
+    3. 无缓存/匹配失败 → 逐个点击槽位 → OCR 干员名 → 截取头像存盘
     """
-    char_id = _get_char_id(oper_name)
-    if not char_id:
-        logger.warning("干员 %s 不在 operator_mapping", oper_name)
-        return None
-
+    image = ctrl.post_screencap().wait().get()
     slots = detect_slots(context, image)
     if not slots:
+        logger.error("未检测到干员槽位")
         return None
 
-    # 在每个槽位的头像区域做 TemplateMatch
+    char_id = _get_char_id(oper_name)
+    h, w = image.shape[:2]
+
+    # Step 1: 有缓存 → 在每个槽位做 TemplateMatch
+    if char_id and (_avatar_dir() / f"{char_id}.png").exists():
+        for i, slot in enumerate(slots):
+            ax, ay, aw, ah = slot["avatar_rect"]
+            roi = [max(0, ax - 5), max(0, ay - 5), aw + 10, ah + 10]
+
+            reco = context.run_recognition(
+                f"MatchAvatar_{char_id}_{i}",
+                image,
+                pipeline_override={
+                    f"MatchAvatar_{char_id}_{i}": {
+                        "recognition": "TemplateMatch",
+                        "template": f"avatar/{char_id}.png",
+                        "threshold": 0.7,
+                        "roi": roi,
+                        "method": 5,
+                    }
+                },
+            )
+
+            if reco and reco.hit:
+                cx = ax + aw // 2
+                cy = ay + ah // 2
+                logger.info("干员 %s 在槽位 %d", oper_name, i)
+                return (cx / w, cy / h)
+
+        logger.info("干员 %s 有缓存但未匹配，转入 OCR 学习", oper_name)
+
+    # Step 2: 无缓存或匹配失败 → 点击每个未识别槽位 → OCR → 存头像
     for i, slot in enumerate(slots):
-        ax, ay, aw, ah = slot["avatar_rect"]
-        # 扩大 ROI 略大于 avatar，给匹配留余量
-        roi = [max(0, ax - 5), max(0, ay - 5), aw + 10, ah + 10]
-
-        reco_detail = context.run_recognition(
-            f"MatchAvatar_{char_id}_slot{i}",
-            image,
-            pipeline_override={
-                f"MatchAvatar_{char_id}_slot{i}": {
-                    "recognition": "TemplateMatch",
-                    "template": f"avatar/{char_id}.png",
-                    "threshold": threshold,
-                    "roi": roi,
-                    "method": 5,
-                }
-            },
-        )
+        click_x, click_y = slot["click_pos"]
+
+        # 点击打开详情页
+        logger.debug("点击槽位 %d (%d, %d)", i, click_x, click_y)
+        ctrl.post_click(click_x, click_y).wait()
+        time.sleep(_DETAIL_WAIT)
+
+        # 截图详情页
+        detail_img = ctrl.post_screencap().wait().get()
+
+        # OCR 干员名
+        name = _ocr_oper_name(context, detail_img)
+        logger.info("槽位 %d OCR: %s", i, name or "(空)")
 
-        if reco_detail and reco_detail.hit:
-            # 返回干员的点击位置（相对全屏比例）
-            cx, cy = ax + aw // 2, ay + ah // 2
-            h, w = image.shape[:2]
-            logger.info("干员 %s 在槽位 %d: (%d, %d)", oper_name, i, cx, cy)
-            return (cx / w, cy / h)
+        # 关闭详情页（再点一次）
+        ctrl.post_click(click_x, click_y).wait()
+        time.sleep(0.3)
 
-    logger.warning("干员 %s 在 %d 个槽位中均未匹配", oper_name, len(slots))
+        if name:
+            # 存头像（从原始 deployment 截图截取，不是详情页）
+            _save_avatar_from_image(image, slot, name)
+
+            if name == oper_name:
+                cx = click_x
+                cy = click_y
+                logger.info("找到目标干员 %s 在槽位 %d", oper_name, i)
+                return (cx / w, cy / h)
+
+    logger.error("未找到干员 %s", oper_name)
     return None
 
 
-def has_avatar(oper_name: str) -> bool:
-    """检查干员是否有缓存头像。"""
-    char_id = _get_char_id(oper_name)
-    if not char_id:
-        return False
-    return (_avatar_dir() / f"{char_id}.png").exists()
+def _ocr_oper_name(context: Context, detail_img: np.ndarray) -> str | None:
+    """OCR 读取详情页干员名。"""
+    reco = context.run_recognition(
+        "OcrOperName",
+        detail_img,
+        pipeline_override={
+            "OcrOperName": {
+                "recognition": "OCR",
+                "roi": _NAME_ROI,
+                "threshold": 0.3,
+                "order_by": "Horizontal",
+            }
+        },
+    )
+
+    if not reco or not reco.hit:
+        return None
+
+    # 取最高分结果
+    detail = getattr(reco, "raw_detail", None)
+
+    # OCR 结果的文字在 raw_detail 里
+    if detail and isinstance(detail, dict):
+        text = detail.get("text", "")
+        if text:
+            return text.strip()
 
+    # 尝试从 all_results 获取
+    for result in reco.all_results if hasattr(reco, "all_results") else []:
+        detail_r = getattr(result, "detail", None) or getattr(result, "raw_detail", None)
+        if detail_r and isinstance(detail_r, dict):
+            text = detail_r.get("text", "")
+            if text:
+                return text.strip()
 
-def learn_avatar_from_slot(
+    return None
+
+
+def _save_avatar_from_image(
     image: np.ndarray,
     slot: dict,
     oper_name: str,
 ) -> bool:
-    """从指定槽位截取头像并存盘。
-
-    Args:
-        image: 全屏截图。
-        slot: detect_slots 返回的槽位 dict。
-        oper_name: 干员名。
-    """
+    """从截图截取槽位头像并存盘。"""
     char_id = _get_char_id(oper_name)
     if not char_id:
-        logger.error("干员 %s 不在 operator_mapping", oper_name)
         return False
 
     ax, ay, aw, ah = slot["avatar_rect"]
     h, w = image.shape[:2]
-    # 边界检查
     x1, y1 = max(0, ax), max(0, ay)
     x2, y2 = min(w, ax + aw), min(h, ay + ah)
 
     avatar = image[y1:y2, x1:x2]
     if avatar.size == 0:
-        logger.error("头像区域为空")
         return False
 
     from PIL import Image
 
     out_path = _avatar_dir() / f"{char_id}.png"
-    avatar_rgb = avatar[..., ::-1].copy()  # BGR → RGB
+    avatar_rgb = avatar[..., ::-1].copy()
     Image.fromarray(avatar_rgb).save(out_path)
     logger.info("头像已缓存: %s → %s", oper_name, out_path)
     return True
 
 
 def list_cached() -> list[str]:
-    """列出已缓存的头像文件名。"""
     return sorted(p.name for p in _avatar_dir().glob("*.png"))

custom/maa/action/executor.py

@@ -26,12 +26,7 @@
 from maa.custom_action import CustomAction
 
 from custom import config
-from custom.core.avatar import (
-    detect_slots,
-    has_avatar,
-    learn_avatar_from_slot,
-    locate_avatar,
-)
+from custom.core.avatar import locate_oper
 from custom.core.battle.action import Action, ActionType, DirectionType
 from custom.core.battle.game_time import GameTime
 from custom.core.geometry.convert_pos import convert_position
@@ -147,35 +142,11 @@ def _parse_actions(self, raw: list[dict], map_data: dict) -> list[Action]:
 
         return actions
 
-    def _locate_oper(self, context: Context, oper_name: str) -> tuple[float, float] | None:
-        """定位干员头像。MAA 方案：检测槽位 → TemplateMatch 匹配。
-
-        无缓存头像时：检测槽位 → 从 LAST_OPER_RATIO 最近槽位学习。
-        """
-        img = context.tasker.controller.post_screencap().wait().get()
-
-        # 有缓存 → 直接匹配
-        if has_avatar(oper_name):
-            pos = locate_avatar(context, img, oper_name)
-            if pos is not None:
-                return pos
-            logger.warning("干员 %s 有缓存但未匹配，尝试重新学习", oper_name)
-
-        # 无缓存或匹配失败 → 检测槽位 → 从最近槽位学习
-        logger.info("干员 %s 学习头像...", oper_name)
-        slots = detect_slots(context, img)
-        if not slots:
-            logger.error("未检测到干员槽位")
-            return None
-
-        # 选择最右边的槽位（LAST_OPER_RATIO 附近）学习
-        last_slot = slots[-1]
-        if learn_avatar_from_slot(img, last_slot, oper_name):
-            logger.info("头像学习成功，重新定位")
-            return locate_avatar(context, img, oper_name)
-
-        logger.error("头像学习失败")
-        return None
+    def _locate_oper(
+        self, context: Context, ctrl: Controller, oper_name: str
+    ) -> tuple[float, float] | None:
+        """定位干员头像。MAA 方案：检测槽位 → 有缓存 TemplateMatch → 无缓存 点击+OCR+存头像。"""
+        return locate_oper(context, ctrl, oper_name)
 
     def _detect_platform(self, ctrl: Controller) -> bool:
         """检测是否 PC 客户端（Win32）。"""
@@ -297,7 +268,7 @@ def _deploy(self, context: Context, ctrl: Controller, action: Action, is_pc: boo
         logger.info("部署 %s at %s", action.oper, action.pos)
 
         # 定位干员头像（MAA TemplateMatch，回退到 LAST_OPER_RATIO）
-        avatar_pos = self._locate_oper(context, action.oper)
+        avatar_pos = self._locate_oper(context, ctrl, action.oper)
         if avatar_pos is not None:
             avatar_x = int(avatar_pos[0] * 1280)
             avatar_y = int(avatar_pos[1] * 720)