ok-script API 文件

本文件是任務開發時的 API 參考。第一次使用 ok-script 時，請先完成快速開始；查詢具體方法時，可以使用瀏覽器的頁面搜尋功能按方法名定位。

Box

Box 類用於表示螢幕上的一個矩形區域，通常用於標識UI元素、影像特徵等。

Box.init

def __init__(self, x, y, width=0, height=0, confidence=1.0, name=None, to_x=-1, to_y=-1)

初始化一個 Box 物件。

引數:
- x (int): 矩形左上角的 x 座標。
- y (int): 矩形左上角的 y 座標。
- width (int): 矩形的寬度。如果提供了 to_x，則會自動計算。
- height (int): 矩形的高度。如果提供了 to_y，則會自動計算。
- confidence (float): 置信度，預設為 1.0。
- name (any): 矩形的名稱或識別符號。
- to_x (int): 矩形右下角的 x 座標，用於計算寬度。
- to_y (int): 矩形右下角的 y 座標，用於計算高度。

Box.area

def area(self) -> int

計算並返回矩形的面積。

返回:
- int: 矩形的面積 (width * height)。

Box.in_boundary

def in_boundary(self, boxes) -> list[Box]

返回一個列表，其中包含傳入引數 boxes 中所有位於當前 Box 邊界內的 Box 物件。

引數:
- boxes (list[Box]): 要檢查的 Box 物件列表。
返回:
- list[Box]: 位於邊界內的 Box 列表。

Box.scale

def scale(self, width_ratio: float, height_ratio: float = None)

按給定的寬高比縮放矩形，保持中心點不變。

引數:
- width_ratio (float): 寬度的縮放比例。
- height_ratio (float): 高度的縮放比例，如果為 None 則使用 width_ratio。
返回:
- Box: 一個新的、經過縮放的 Box 物件。

Box.center

def center(self)

計算並返回矩形的中心點座標。

返回:
- tuple: 包含中心點 (x, y) 座標的元組。

Box.copy

def copy(self, x_offset=0, y_offset=0, width_offset=0, height_offset=0, name=None)

建立一個帶有偏移量的新 Box 副本。

引數:
- x_offset (int): x 座標的偏移量。
- y_offset (int): y 座標的偏移量。
- width_offset (int): 寬度的偏移量。
- height_offset (int): 高度的偏移量。
- name (any): 新矩形的名稱。
返回:
- Box: 一個新的 Box 物件。

Box.crop_frame

def crop_frame(self, frame)

從給定的影像幀中裁剪出矩形區域。

引數:
- frame (numpy.ndarray): 要裁剪的影像幀。
返回:
- numpy.ndarray: 裁剪後的影像區域。

Box.center_distance

def center_distance(self, other) -> float

計算當前矩形與另一個矩形中心點之間的距離。

引數:
- other (Box): 另一個 Box 物件。
返回:
- float: 兩個矩形中心點之間的歐幾里得距離。

Box.closest_distance

def closest_distance(self, other) -> float

計算兩個矩形邊界之間的最短距離。如果兩個矩形相交，則距離為 0。

引數:
- other (Box): 另一個 Box 物件。
返回:
- float: 兩個矩形之間的最短距離。

Box.relative_with_variance

def relative_with_variance(self, relative_x=0.5, relative_y=0.5) -> tuple[int, int]

返回矩形內的一個座標點。支援相對位置並帶有微小的隨機偏移，模擬真實的人工點選。

引數:
- relative_x (float): 相對 x 座標 (0.0 - 1.0)。
- relative_y (float): 相對 y 座標 (0.0 - 1.0)。
返回:
- tuple[int, int]: 計算出的 (x, y) 座標。

Box.find_closest_box

def find_closest_box(self, direction, boxes, condition=None)

在給定方向上查詢並返回距離最近的 Box 物件。

引數:
- direction (str): 查詢方向 ('up', 'down', 'left', 'right', 'all')。
- boxes (list[Box]): 要在其中搜索的 Box 物件列表。
- condition (callable, optional): 一個可選的過濾函式，用於篩選 Box。
返回:
- Box 或 None: 找到的最近的 Box 物件，如果未找到則返回 None。

BaseTask

BaseTask 是所有任務類的基類，它提供了任務執行所需的基礎功能，如截圖、輸入、日誌記錄等。它繼承自 OCR、FindFeature 和 ExecutorOperation，因此包含了這些父類的所有方法。

名稱匹配規則 (match / names)

多個 API 會用 match 或 names 引數過濾 Box.name，例如 ocr、wait_ocr、wait_click_ocr、find_boxes 和 click_box_if_name_match。

str: 精確匹配，只有 box.name == match 才算匹配。
re.Pattern: 正則匹配，使用 re.search(pattern, box.name)，所以可以匹配文本中的任意一段。
list[str | re.Pattern]: 可以把字串和正則任意組合在一個列表裡，命中其中任意一個就會保留該 Box。
匹配預設區分大小寫；需要忽略大小寫時，用 re.compile(..., re.IGNORECASE)。
這不是模糊匹配，也不會自動做 contains。如果要匹配包含某段文字，請用正則，例如 re.compile("开始|Start")。

示例：

import re

self.ocr(match="确定")                         # 只匹配 name 正好是 "确定" 的 OCR 结果
self.ocr(match=re.compile(r"确定|OK"))         # 匹配包含 "确定" 或 "OK" 的结果
self.ocr(match=["确定", re.compile(r"^OK$")])  # 字符串和正则可以混用

在需要檢測多個字串或多個正則時，優先使用 match=[...] 一次 OCR 後統一過濾，通常比多次呼叫 ocr 更高效。

幀重新整理與等待

frame 是當前快取的螢幕幀。next_frame() 和 sleep() 都會重置場景並清空當前快取幀；帶有 after_sleep 引數的方法也會在動作後呼叫 sleep，因此同樣會清空當前幀。

當迴圈檢測介面，或點選、滑動、按鍵後介面可能發生變化時，通常需要等待一下再讀取新介面，例如：

self.click_box(button, after_sleep=0)
self.sleep(0.5)
boxes = self.ocr(match="确认")

更推薦的寫法是優先使用 wait_ 開頭的方法，例如 wait_ocr、wait_click_ocr、wait_feature 和 wait_click_feature。這些方法會自動迴圈獲取新的 frame，呼叫前通常不需要額外 sleep。編寫或生成指令碼程式碼時，能用 wait_ 方法表達的等待邏輯，儘量使用 wait_ 方法。

截圖 (Screenshot) { #截圖-screenshot }

frame

@property
def frame(self)

獲取當前有效的螢幕幀。此屬性會確保返回的是最新的、可用的影像幀。如果指令碼暫停，它會等待直到指令碼恢復。

返回:
- numpy.ndarray: 當前的螢幕影像幀。

next_frame

def next_frame(self)

強制獲取並返回一個新的螢幕幀。這會先重置場景並清空當前快取幀，然後觸發一次截圖操作，而不是直接使用舊快取。

返回:
- numpy.ndarray: 新捕獲的螢幕影像幀。

screenshot

def screenshot(self, name=None, frame=None, show_box=False, frame_box=None)

將當前螢幕或指定幀的影像儲存到 screenshots 目錄中，主要用於除錯。儲存的截圖會顯示在軟體的UI介面中。

引數:
- name (str): 截圖的名稱，必須提供。
- frame (numpy.ndarray, optional): 如果提供，則儲存該幀，否則儲存當前螢幕幀。
- show_box (bool): 是否在截圖上顯示一個預設的框。
- frame_box (Box, optional): 在截圖上顯示的特定 Box 區域。

adb_ui_dump

def adb_ui_dump(self) -> str

通過 ADB 獲取當前螢幕的 UI 層級結構 XML 字串（僅限安卓/模擬器模式）。

返回:
- str: UI 結構的 XML 字串。

輸入 (Input) { #輸入-input }

click

def click(self, x: int | Box | List[Box] = -1, y=-1, move_back=False, name=None, interval=-1, move=True, down_time=0.02,
          after_sleep=0, key='left', hcenter=False, vcenter=False)

在指定座標或 Box 位置執行滑鼠點選。座標可以是絕對座標（整數），也可以是相對於螢幕寬高的相對座標（0.0到1.0之間的小數）。如果只提供了 x 引數且其型別為 Box，則會點選該 Box 的中心點。如果 x 是一個 Box 列表，則會點選列表中第一個 Box 的中心點。

引數:
- x (int | float | Box | list[Box]): x 座標、相對 x 座標或一個 Box 物件（或列表）。
- y (int | float): y 座標或相對 y 座標。
- move_back (bool): 點選後是否將滑鼠移回原位。
- name (str, optional): 點選操作的名稱，用於日誌記錄。
- interval (float): 距離上次點選的最小時間間隔（秒）。
- move (bool): 是否在點選前移動滑鼠。
- down_time (float): 滑鼠按下的持續時間（秒）。
- after_sleep (float): 點選後等待的時間（秒）；會呼叫 sleep，因此會清空當前快取幀。
- key (str): 要點選的滑鼠按鍵 ('left', 'right', 'middle')。
- hcenter, vcenter (bool): 如果點選相對座標且設為 True，則以螢幕中心為原點。
返回:
- bool: 如果操作成功執行，返回 True。

click_box

def click_box(self, box: Box | List[Box] = None, relative_x=0.5, relative_y=0.5, raise_if_not_found=False,
              move_back=False, move=True, down_time=0.01, after_sleep=1)

點選一個 Box 物件的相對位置。box 也可以傳入 Box 列表（點選第一個）或預定義區域/特徵名稱字串。

引數:
- box (Box | list[Box] | str): 要點選的 Box 物件、Box 列表（預設點選第一個）或可通過 get_box_by_name 找到的名稱。
- relative_x (float): 相對於 Box 寬度的 x 座標比例 (0.0 - 1.0)。
- relative_y (float): 相對於 Box 高度的 y 座標比例 (0.0 - 1.0)。
- raise_if_not_found (bool): 如果 box 為 None 是否丟擲異常。
- move_back (bool): 點選後是否將滑鼠移回原位。
- move (bool): 是否在點選前移動滑鼠。
- down_time (float): 滑鼠按下的持續時間（秒）。
- after_sleep (float): 點選後等待的時間（秒）；會呼叫 sleep，因此會清空當前快取幀。

click_box_if_name_match

def click_box_if_name_match(self, boxes, names, relative_x=0.5, relative_y=0.5)

在 Box 列表中查詢名稱匹配的 Box 並點選。匹配規則見名稱匹配規則。當 names 是列表時，列表越靠前優先順序越高；如果多個框匹配，會返回並點選優先順序最高的匹配項。

引數:
- boxes (list[Box]): Box 列表。
- names (str | re.Pattern | list[str | re.Pattern]): 要匹配的名稱或正則模式，可以混用。
- relative_x (float): 相對於匹配 Box 寬度的 x 座標比例。
- relative_y (float): 相對於匹配 Box 高度的 y 座標比例。
返回:
- Box 或 None: 匹配並點選的 Box，未找到時返回 None。

click_relative

def click_relative(self, x, y, move_back=False, hcenter=False, vcenter=False, move=True, after_sleep=0, name=None, interval=-1,
                   down_time=0.02, key="left")

在螢幕的相對位置執行點選。

引數:
- x (float): 相對於螢幕寬度的 x 座標比例 (0.0 - 1.0)。
- y (float): 相對於螢幕高度的 y 座標比例 (0.0 - 1.0)。

wait_click_box

def wait_click_box(self, condition, time_out=0, pre_action=None, post_action=None, raise_if_not_found=False)

等待一個返回 Box 的條件函式成立，並點選該 Box。

引數:
- condition (callable): 返回 Box 或 list[Box] 的函式。

right_click

def right_click(self, *args, **kwargs)

執行滑鼠右鍵點選。引數與 click 方法相同，但 key 固定為 'right'。

middle_click

def middle_click(self, *args, **kwargs)

執行滑鼠中鍵點選。引數與 click 方法相同，但 key 固定為 'middle'。

swipe

def swipe(self, from_x, from_y, to_x, to_y, duration=0.5, after_sleep=0.1, settle_time=0)

執行滑動操作。

引數:
- from_x, from_y (int): 滑動起點的絕對座標。
- to_x, to_y (int): 滑動終點的絕對座標。
- duration (float): 滑動持續時間（秒）。
- after_sleep (float): 滑動後等待的時間（秒）；會呼叫 sleep，因此會清空當前快取幀。
- settle_time (float): 到達終點後，在鬆開手指前停留的時間（秒）。

swipe_relative

def swipe_relative(self, from_x, from_y, to_x, to_y, duration=0.5, settle_time=0)

在螢幕的相對位置之間執行滑動操作。

引數:
- from_x, from_y (float): 滑動起點的相對座標 (0.0 - 1.0)。
- to_x, to_y (float): 滑動終點的相對座標 (0.0 - 1.0)。

input_text

def input_text(self, text)

輸入指定的文本。

引數:
- text (str): 要輸入的字串。

send_key

def send_key(self, key, down_time=0.02, interval=-1, after_sleep=0)

模擬按下並釋放一個鍵盤按鍵。

引數:
- key (str): 要傳送的按鍵（例如 'a', 'enter', 'f1'）。

send_key_down

def send_key_down(self, key, after_sleep=0)

模擬按下鍵盤按鍵（不釋放）。

send_key_up

def send_key_up(self, key, after_sleep=0)

模擬釋放鍵盤按鍵。

scroll

def scroll(self, x, y, count)

在指定座標位置執行滑鼠滾輪滾動。

引數:
- x, y (int): 滾動的絕對座標。
- count (int): 滾動量，正數向上，負數向下。

scroll_relative

def scroll_relative(self, x, y, count)

在螢幕的相對位置執行滑鼠滾輪滾動。

引數:
- x, y (float): 滾動的相對座標 (0.0 - 1.0)。

mouse_down

def mouse_down(self, x=-1, y=-1, name=None, key="left")

在指定位置按下滑鼠按鍵（不釋放）。

mouse_up

def mouse_up(self, name=None, key="left")

釋放滑鼠按鍵。

move

def move(self, x, y)

將滑鼠移動到指定的絕對座標。

move_relative

def move_relative(self, x, y)

將滑鼠移動到指定的相對座標。

back

def back(self, *args, after_sleep=0, **kwargs)

模擬返回操作，通常是傳送 'esc' 鍵（PC）或返回鍵（Android）。支援 after_sleep 引數。

Config 相關 { #config-相關 }

load_config

def load_config(self)

載入當前任務的配置檔案。通常在任務初始化時自動呼叫。

validate_config

def validate_config(self, key, value)

驗證一個配置項是否合法。子類可以重寫此方法以實現自定義驗證邏輯。

返回:
- str 或 None: 如果驗證失敗，返回錯誤資訊字串；否則返回 None。

get_global_config

def get_global_config(self, option)

獲取一個全域性配置物件的值。

引數:
- option (ConfigOption): 全域性配置選項的定義。

get_global_config_desc

def get_global_config_desc(self, option) -> str

獲取一個全域性配置選項的描述。

任務配置 (Task Configuration) { #任務配置-task-configuration }

BaseTask 允許通過 default_config 和 config_type 來定義任務在 GUI 介面中的配置表單。

預設配置 (self.default_config)

在 __init__ 中定義 self.default_config。框架會根據值的 Python 型別自動推斷 GUI 控制元件：

bool: 開關按鈕 (SwitchButton)
int: 整數輸入框 (SpinBox)
float: 浮點數輸入框 (DoubleSpinBox)
list: 列表修改項 (ModifyListItem)
- 可通過 config_type 提供 options_available (list[str])，限制列表可新增的選項。
- 配合 options_available 使用 allow_duplication (bool, 預設 False) 時，可允許重複新增相同選項。
str:
- 長度 > 16 或包含 \n: 多行文本框 (TextEdit)
- 其他情況: 單行文本框 (LineEdit)

顯示指定配置型別 (self.config_type)

如果需要更復雜的控制元件（如下拉選單、多選框或按鈕），可以使用 self.config_type 進行顯式定義。 type 是可選的；當配置項提供 options 時，會根據預設值自動推斷為下拉框或多選框。

目前支援以下型別：

drop_down: 下拉選擇框。
- 引數: options (list[str]): 選項列表。
multi_selection: 多選列表。
- 引數: options (list[str]): 選項列表。
text_edit: 強制使用多行文本框。
file_selector: 檔案或資料夾選擇器。配置值必須是 str，介面會以只讀文本顯示當前值並提供按鈕開啟選擇器。
- 引數: selector_type (str, 可選): 選擇器型別，"file" 或 "folder"，預設 "file"。
- 引數: dialog_title (str, 可選): 選擇器視窗標題。
- 引數: filter (str, 可選): 檔案選擇器過濾器，例如 "Images (*.png *.jpg);;All Files (*)"，僅在 selector_type 為 "file" 時生效。
global: 引用全域性配置項。
button (NEW): 在配置區域顯示一個或多個按鈕，用於觸發特定方法。
- 引數:
  - text (str): 按鈕上顯示的文本（該文本會參與 og.app.tr 翻譯）。
  - icon (FluentIcon): 可選圖示。
  - callback (callable): 點選按鈕時觸發的函式或方法。
  - buttons (list[dict]): 如果需要顯示多個按鈕，可以提供一個按鈕配置列表，每個元素包含上述 text, icon, callback。
- 注意: button 型別的配置項其 key 和 value 只用於 GUI 渲染展示，不會被儲存到本地配置檔案中。

通用可選引數：

sub_configs: 可用於下拉選擇框、布林開關或多選列表，根據當前值控制其他配置項是否顯示。key 是選項值或 True/False，value 是需要顯示的配置項名稱列表。對於多選列表，所有已選選項對應的配置項會按選項順序合併，重複項只顯示一次；未選擇任何選項時，所有關聯配置項都會隱藏。

示例程式碼:

class MyTask(BaseTask):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.default_config = {
            'Run Count': 1,
            'Mode': 'Default',
            'Features': ['Logging'],
            'Log Level': 'Info',
            'Output Path': '',
            'Input Path': '',
            'Advanced Tool': 'Action' # 占位符
        }
        self.config_type = {
            'Mode': {
                'options': ['Default', 'Fast'],
                'sub_configs': {
                    'Fast': ['Advanced Tool']
                }
            },
            'Features': {
                'type': 'multi_selection',
                'options': ['Logging', 'Export'],
                'sub_configs': {
                    'Logging': ['Log Level'],
                    'Export': ['Output Path']
                }
            },
            'Input Path': {
                'type': 'file_selector',
                'selector_type': 'folder',
                'dialog_title': 'Select Input'
            },
            'Advanced Tool': {
                'type': 'button',
                'buttons': [
                    {
                        'text': 'Run Diagnosis',
                        'icon': FluentIcon.SEARCH,
                        'callback': self.run_diagnosis
                    },
                    {
                        'text': 'Clean Cache',
                        'icon': FluentIcon.DELETE,
                        'callback': self.clean_cache
                    }
                ]
            }
        }
        self.config_description = {
            'Advanced Tool': 'Click to run advanced operations'
        }

    def run_diagnosis(self):
        self.log_info("Starting diagnosis...")

螢幕畫圖 (Screen drawing) { #螢幕畫圖-screen-drawing }

draw_boxes

def draw_boxes(feature_name=None, boxes=None, color="red", debug=True)

在螢幕上繪製一個或多個 Box，用於除錯。

引數:
- feature_name (str, optional): 繪製的圖層名稱。
- boxes (list[Box] | Box): 要繪製的 Box 物件或列表。

clear_box

def clear_box(self)

清除螢幕上由 draw_boxes 繪製的所有框。

get_overlay_view

def get_overlay_view(self)

返回覆蓋在捕獲視窗上的原始 Qt overlay widget。BaseTask 和 CustomTab 可直接呼叫此方法；配置的 my_app 例項也會獲得同名方法。無介面執行時返回 None。

任務執行緒需要通過 overlay_view.draw(key, callback, duration=None) 註冊自定義繪製。回撥會在 Qt 繪製執行緒中執行，引數為 (painter, overlay_view)，可使用 QPainter 繪製任意內容。存在自定義繪製內容時 overlay 會自動顯示，不受 Enable Boxes 開關影響。duration 為秒數；不傳時持續顯示，直到呼叫 overlay_view.clear_draw(key) 或 overlay_view.clear_draw()：

from PySide6.QtGui import QColor, QFont, QPen
from ok import TriggerTask


class StatusOverlayTask(TriggerTask):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.default_config = {'_enabled': True}
        self.trigger_interval = 0.5

    def run(self):
        overlay = self.get_overlay_view()
        if overlay is None:
            return

        status = "Tracking"

        def paint(painter, view):
            painter.setPen(QPen(QColor(0, 255, 120), 2))
            painter.drawRect(30, 30, 240, 64)
            painter.setFont(QFont("Arial", 16))
            painter.drawText(48, 70, status)

        overlay.draw("status", paint, duration=1)

    def on_destroy(self):
        overlay = self.get_overlay_view()
        if overlay is not None:
            overlay.clear_draw("status")

應用配置可提供 blur_area(width, height) 回撥，返回一個 Box 或 list[Box]，用於遮擋遊戲 UID 等靜態區域：

from ok import Box

def blur_area(width, height):
    return Box(width - 240, height - 42, 240, 42)

config = {
    'blur_area': blur_area,
}

配置後，基本設定中會出現 Enable Blur 開關，啟用後可通過子配置 Blur Algorithm 選擇 Inpaint（預設）或 Blur。Inpaint 會使用區域周圍的畫素重建內容，適用於從較簡單背景上移除 UID。開啟時只在遊戲視窗位於前臺時顯示處理後的區域；按 Blur Interval 檢查變化，預設為 1 秒，設為 0 時每個 next_frame 均檢查。儲存截圖時始終應用所選演算法，與該開關無關。若還配置了 screenshot_processor，它會在處理完成後執行。除錯面板中的 Enable Boxes 僅啟用框繪製；overlay 只在有框、處理區域或自定義繪製內容需要顯示時出現。

OCR

ocr

def ocr(self, x=0, y=0, to_x=1, to_y=1, match=None, width=0, height=0, box=None, name=None,
        threshold=0, frame=None, target_height=0, use_grayscale=False, log=False,
        screenshot=False, frame_processor=None, lib='default')

對螢幕指定區域進行光學字元識別（OCR）。如果不傳 match，返回識別出的全部文本框；如果傳了 match，只返回名稱匹配的文本框。

引數:
- x, y, to_x, to_y (float): 識別區域的相對座標；未傳 box 時使用。
- match (str | re.Pattern | list[str | re.Pattern] | None): 用於過濾識別結果的名稱匹配條件，見名稱匹配規則。
- width, height (float): 識別區域的相對寬高；為 0 時使用 to_x - x、to_y - y。
- box (Box | str, optional): 指定一個 Box 或預定義區域/特徵名稱作為識別區域，優先順序高於相對座標。
- name (str, optional): 給識別區域命名，主要用於日誌和除錯繪製。
- threshold (float): OCR 結果的置信度閾值；為 0 時使用 self.ocr_default_threshold。
- frame (numpy.ndarray, optional): 指定影像幀；不傳時使用當前螢幕幀。
- target_height (int): 識別前將影像縮放到的目標高度，可以提高識別準確率或速度。
- use_grayscale (bool): 識別前是否轉為灰度圖。
- log (bool): 是否輸出 OCR 結果日誌。
- screenshot (bool): 是否儲存 OCR 除錯截圖。
- frame_processor (callable, optional): OCR 前對裁剪影像做自定義處理。
- lib (str): 使用 config['ocr'] 中哪個 OCR 配置，預設 "default"。
返回:
- list[Box]: 包含識別結果的 Box 物件列表，Box.name 為識別出的文本。

wait_ocr

def wait_ocr(self, x=0, y=0, to_x=1, to_y=1, width=0, height=0, name=None, box=None, match=None,
             threshold=0, frame=None, target_height=0, time_out=0, post_action=None,
             raise_if_not_found=False, log=False, screenshot=False, settle_time=-1, lib="default")

等待直到在指定區域內 OCR 識別到文本。大多數引數與 ocr 相同；match 支援字串、正則以及兩者混合列表，見名稱匹配規則。

返回:
- list[Box] 或 None: 找到的文本 Box 列表；超時且未拋異常時返回 None。

wait_click_ocr

def wait_click_ocr(self, x=0, y=0, to_x=1, to_y=1, width=0, height=0, box=None, name=None, match=None,
                   threshold=0, frame=None, target_height=0, time_out=0, raise_if_not_found=False,
                   recheck_time=0, after_sleep=0, post_action=None, log=False, screenshot=False,
                   settle_time=-1, lib="default")

等待直到 OCR 識別到匹配的文本，並點選找到的結果中的第一個框。引數與 ocr 類似；recheck_time > 0 時會在等待命中後短暫等待並再 OCR 一次。

返回:
- list[Box] 或 None: 被點選前得到的 OCR Box 列表；未找到時返回 None。

add_text_fix

def add_text_fix(self, fix)

新增 OCR 文本修正規則。用於修正 OCR 引擎常見的識別錯誤。

引數:
- fix (dict): 一個字典，鍵為錯誤文本，值為正確文本。

找圖 (Image finding) { #找圖-image-finding }

find_feature

def find_feature(self, feature_name=None, horizontal_variance=0, vertical_variance=0, threshold=0,
                 use_gray_scale=False, x=-1, y=-1, to_x=-1, to_y=-1, width=-1, height=-1, box=None,
                 canny_lower=0, canny_higher=0, frame_processor=None, template=None,
                 match_method=cv2.TM_CCOEFF_NORMED, screenshot=False, mask_function=None,
                 frame=None, limit=0, target_height=0) -> List[Box]

在指定區域內查詢一個或多個影像特徵。

引數:
- feature_name (str | list[str]): 要查詢的特徵名稱。
- box (Box | str, optional): 在該 Box 區域內進行搜尋；字串會通過 get_box_by_name 轉為區域。
- threshold (float): 匹配的置信度閾值。
- limit (int): 限制返回數量；0 表示不限制。
- frame (numpy.ndarray, optional): 指定搜尋幀；不傳時使用當前螢幕幀。
返回:
- list[Box]: 找到的所有匹配特徵的 Box 物件列表。

find_one

def find_one(self, feature_name=None, horizontal_variance=0, vertical_variance=0, threshold=0,
             use_gray_scale=False, box=None, canny_lower=0, canny_higher=0,
             frame_processor=None, template=None, mask_function=None, frame=None,
             match_method=cv2.TM_CCOEFF_NORMED, screenshot=False, limit=1, target_height=0) -> Box

查詢單個影像特徵，並返回置信度最高的一個。引數與 find_feature 相同。

返回:
- Box 或 None: 找到的置信度最高的 Box 物件，如果未找到則返回 None。

wait_feature

def wait_feature(self, feature, horizontal_variance=0, vertical_variance=0, threshold=0,
                 time_out=0, pre_action=None, post_action=None, use_gray_scale=False, box=None,
                 raise_if_not_found=False, canny_lower=0, canny_higher=0, settle_time=-1,
                 frame_processor=None, target_height=0)

等待直到在螢幕上找到指定的影像特徵。

引數:
- feature (str): 要等待的特徵名稱。
- time_out (int): 等待的超時時間（秒）。
返回:
- Box 或 None: 找到的 Box 物件。

wait_click_feature

def wait_click_feature(self, feature, horizontal_variance=0, vertical_variance=0, threshold=0,
                       relative_x=0.5, relative_y=0.5, time_out=0, pre_action=None,
                       post_action=None, box=None, raise_if_not_found=True, use_gray_scale=False,
                       canny_lower=0, canny_higher=0, click_after_delay=0, settle_time=-1,
                       after_sleep=0, target_height=0)

等待直到找到指定的影像特徵，並對其進行點選。

返回:
- bool: 如果成功找到並點選，返回 True。

get_box_by_name

def get_box_by_name(self, name) -> Box

根據名稱獲取一個預定義的 Box。名稱可以是定義的特徵名，也可以是內建預設區域。

可選預設名稱:
- full_screen
- top, bottom, left, right
- top_left, top_right, bottom_left, bottom_right
返回:
- Box: 對應的 Box 物件。

get_feature_by_name

def get_feature_by_name(self, name)

根據名稱獲取特性的詳細定義和原始影像。

feature_exists

def feature_exists(self, feature_name: str) -> bool

檢查指定的特徵名稱是否在已載入的任務特徵集中。

find_feature_and_set

def find_feature_and_set(self, features, horizontal_variance=0, vertical_variance=0, threshold=0) -> bool

查詢多個特徵並將結果作為同名屬性設定到當前任務物件中。

引數:
- features (str | list[str]): 要查詢的特徵名稱。
返回:
- bool: 是否所有指定的特徵都找到了。

find_best_match_in_box

def find_best_match_in_box(self, box, to_find, threshold, use_gray_scale=False,
                           canny_lower=0, canny_higher=0,
                           frame_processor=None, mask_function=None) -> Box

在給定的 Box 內尋找 to_find 列表中置信度最高的一個特徵。to_find 應為特徵名稱列表。

find_first_match_in_box

def find_first_match_in_box(self, box, to_find, threshold, use_gray_scale=False,
                            canny_lower=0, canny_higher=0,
                            frame_processor=None, mask_function=None) -> Box

在給定的 Box 內按 to_find 順序查詢，第一個找到的特徵會被立即返回。

找色 (Color finding) { #找色-color-finding }

calculate_color_percentage

def calculate_color_percentage(self, color, box: Box | str) -> float

計算指定 Box 區域內特定顏色的畫素百分比。

引數:
- color (dict): 顏色範圍字典，格式為 {'r': (min, max), 'g': (min, max), 'b': (min, max)}。
- box (Box | str): 要計算的 Box 物件或其名稱。
返回:
- float: 顏色畫素所佔的百分比 (0.0 - 1.0)。

顯示資訊 (Display information) { #顯示資訊-display-information }

notification

def notification(self, message, title=None, error=False, tray=False, show_tab=None, params=None)

在主介面顯示一個通知資訊條或系統托盤通知。

引數:
- message (str): 通知內容。
- tray (bool): 是否同時顯示系統托盤通知。
- show_tab (str): 點選通知時跳轉到的 UI 選項卡。
- params (any): 隨通知一起傳遞給 UI 的附加引數。

info_set

def info_set(self, key, value)

在任務的監控資訊中設定一個鍵值對（會顯示在 UI 的任務卡片中）。

info_get

def info_get(self, key, default=None)

從任務的監控資訊中獲取一個值。

info_incr

def info_incr(self, key, inc=1)

增加監控資訊中的數值。

info_add

def info_add(self, key, count=1)

同 info_incr。

info_add_to_list

def info_add_to_list(self, key, item)

將一個項新增到監控資訊中的列表（如果鍵不存在則建立列表）。

info_clear

def info_clear(self)

清除當前任務的所有監控資訊。

日誌 (Logging) { #日誌-logging }

log_info

def log_info(self, message, notify=False)

記錄一條資訊級別的日誌。

log_debug

def log_debug(self, message, notify=False)

記錄一條除錯級別的日誌。

log_error

def log_error(self, message, exception=None, notify=False)

記錄一條錯誤級別的日誌。

其他 (Other) { #其他-other }

is_adb

def is_adb(self) -> bool

判斷當前是否連線的是 ADB 裝置（安卓/模擬器）。

is_browser

def is_browser(self) -> bool

判斷當前是否正在控制瀏覽器裝置。

adb_shell

def adb_shell(self, *args, **kwargs) -> str

執行一條 ADB shell 指令並返回輸出字串。

ensure_in_front

def ensure_in_front(self)

確保遊戲視窗或 ADB 模擬器處於前臺顯示狀態。只有目標應用或遊戲必須在前臺才能接收輸入時，才需要主動呼叫此方法；大部分支援後臺輸入的裝置或視窗互動方式不需要呼叫。

box_of_screen

def box_of_screen(self, x, y, to_x=1.0, to_y=1.0, width=0.0, height=0.0, name=None,
                  hcenter=False, vcenter=False, confidence=1.0) -> Box

根據相對比例建立一個相對於當前螢幕尺寸的 Box 物件。

引數:
- x, y (float): 相對於螢幕的相對座標 (0.0 - 1.0)。
- to_x, to_y (float): 右下角相對座標；未顯式指定 width/height 時用於計算大小。
- width, height (float): 相對寬高；為 0 時根據 to_x/to_y 計算。
- name (str, optional): 生成的 Box 名稱。
- hcenter, vcenter (bool): 在非標準螢幕比例下按水平/垂直居中規則縮放座標。
- confidence (float): 寫入返回 Box.confidence 的置信度。

box_of_screen_scaled

def box_of_screen_scaled(self, original_screen_width, original_screen_height, x_original, y_original,
                         to_x=0, to_y=0, width_original=0, height_original=0,
                         name=None, hcenter=False, vcenter=False, confidence=1.0) -> Box

根據原始參考螢幕的解析度，將座標縮放到當前螢幕解析度並建立一個 Box。

screen_width

@property
def screen_width(self) -> int

獲取當前螢幕的畫素寬度。

screen_height

@property
def screen_height(self) -> int

獲取當前螢幕的畫素高度。

width_of_screen

def width_of_screen(self, percent) -> int

根據傳入的百分比計算並返回對應的螢幕畫素寬度。

wait_until

def wait_until(self, condition, time_out=0, pre_action=None, post_action=None, settle_time=-1, raise_if_not_found=False)

等待直到 condition 函式返回一個真值（或非空值）。

引數:
- condition (callable): 無引數的可呼叫函式。
- time_out (int): 超時時間（秒），0 表示無限等待。

wait_scene

def wait_scene(self, scene_type=None, time_out=0, pre_action=None, post_action=None)

等待當前場景變為指定的 scene_type。

sleep

def sleep(self, timeout)

讓當前任務休眠指定秒數。呼叫時會重置場景並清空當前快取幀；休眠期間會處理指令碼暫停和 sleep_check。如果剛執行了會改變介面的操作，常用 sleep(0.5) 等待介面穩定後再讀取新的 frame；如果使用 wait_ 開頭的方法，則通常不需要在呼叫前手動 sleep。

sleep_check

def sleep_check(self)

當指令碼休眠時，若設定了 sleep_check_interval，會定期呼叫此方法執行背景檢查邏輯。

run_task_by_class

def run_task_by_class(self, cls)

在當前任務上下文中例項化並執行指定的另一個任務類。

tr

def tr(self, message) -> str

翻譯指定的字串訊息（使用應用級的 i18n 系統）。

should_trigger

def should_trigger(self) -> bool

根據配置的 trigger_interval 判斷當前是否應該觸發任務執行。

go_to_tab

def go_to_tab(self, tab)

通知 UI 介面跳轉到指定的選項卡。

find_boxes

def find_boxes(self, boxes, match=None, boundary=None) -> list[Box]

對 Box 列表進行過濾，支援名稱匹配和邊界篩選。

引數:
- boxes (list[Box]): 待過濾的 Box 列表。
- match (str | re.Pattern | list[str | re.Pattern] | None): 名稱匹配條件，見名稱匹配規則。
- boundary (Box | str | None): 只保留完全位於該邊界內的 Box；字串會通過 get_box_by_name 轉為邊界。
返回:
- list[Box]: 過濾後的 Box 列表。