PyClickerRPA 0.1.0__py3-none-any.whl

autoclicker/matcher.py

@@ -0,0 +1,152 @@
+"""Template matching + OCR text matching — port of matcher.cpp.
+
+Image matching uses OpenCV TM_CCOEFF_NORMED with greedy peak suppression
+(mirrors ``Matcher::findImage``); OCR goes through native PaddleOCR (see
+ocr.py) instead of the C++ socket daemon.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional
+
+import cv2
+import numpy as np
+
+
+@dataclass
+class MatchResult:
+    cx: int
+    cy: int
+    x: int
+    y: int
+    w: int
+    h: int
+    confidence: float
+
+
+@dataclass
+class TextResult:
+    text: str
+    cx: int
+    cy: int
+    x: int
+    y: int
+    w: int
+    h: int
+    confidence: float
+
+
+# ─────────────────── Image matching ───────────────────
+
+def find_image(screen: np.ndarray, templ: np.ndarray, threshold: float = 0.8) -> list[MatchResult]:
+    """Find up to 10 occurrences of *templ* in *screen* (TM_CCOEFF_NORMED)."""
+    results: list[MatchResult] = []
+    if screen is None or templ is None or screen.size == 0 or templ.size == 0:
+        return results
+    th, tw = templ.shape[:2]
+    sh, sw = screen.shape[:2]
+    if tw > sw or th > sh:
+        return results
+
+    result = cv2.matchTemplate(screen, templ, cv2.TM_CCOEFF_NORMED)
+    while True:
+        _, max_val, _, max_loc = cv2.minMaxLoc(result)
+        if max_val < threshold:
+            break
+        mx, my = max_loc
+        results.append(MatchResult(mx + tw // 2, my + th // 2, mx, my, tw, th, float(max_val)))
+        # Blank out the matched region so the next peak is a distinct hit
+        cv2.rectangle(result, (mx, my), (mx + tw, my + th), 0.0, -1)
+        if len(results) >= 10:
+            break
+    return results
+
+
+_SCALES = (1.0, 0.9, 1.1, 0.8, 1.2)
+
+
+def find_image_multiscale(screen: np.ndarray, templ: np.ndarray, threshold: float = 0.8) -> list[MatchResult]:
+    """Try several template scales; return the highest-confidence result set."""
+    best: list[MatchResult] = []
+    best_conf = 0.0
+    for scale in _SCALES:
+        scaled = templ if scale == 1.0 else cv2.resize(templ, None, fx=scale, fy=scale, interpolation=cv2.INTER_LINEAR)
+        if scaled.shape[1] > screen.shape[1] or scaled.shape[0] > screen.shape[0]:
+            continue
+        results = find_image(screen, scaled, threshold)
+        if results and results[0].confidence > best_conf:
+            best_conf = results[0].confidence
+            best = results
+    return best
+
+
+# ─────────────────── ROI helpers (from taskrunner.cpp) ───────────────────
+
+def apply_roi(screen: np.ndarray, roi: Optional[tuple[int, int, int, int]]) -> tuple[np.ndarray, int, int]:
+    """Return (sub_image, offset_x, offset_y). roi None/empty -> whole screen."""
+    if not roi:
+        return screen, 0, 0
+    rx, ry, rw, rh = roi
+    if rw <= 0 or rh <= 0:
+        return screen, 0, 0
+    x = max(0, rx)
+    y = max(0, ry)
+    w = min(rw, screen.shape[1] - x)
+    h = min(rh, screen.shape[0] - y)
+    if w <= 0 or h <= 0:
+        return screen, 0, 0
+    return screen[y:y + h, x:x + w], x, y
+
+
+def find_image_roi(screen, templ, threshold, roi, multi_scale=False) -> list[MatchResult]:
+    region, ox, oy = apply_roi(screen, roi)
+    results = (find_image_multiscale(region, templ, threshold) if multi_scale
+               else find_image(region, templ, threshold))
+    if ox or oy:
+        for r in results:
+            r.cx += ox
+            r.cy += oy
+            r.x += ox
+            r.y += oy
+    return results
+
+
+# ─────────────────── Text matching ───────────────────
+
+def fuzzy_match(text: str, target: str) -> bool:
+    """Port of Matcher::fuzzyMatch: substring, whitespace-stripped, 70% char overlap."""
+    if target.lower() in text.lower():
+        return True
+    ct = "".join(text.split())
+    tt = "".join(target.split())
+    if tt.lower() in ct.lower():
+        return True
+    if len(tt) >= 2 and len(ct) >= 2:
+        remaining = list(ct.lower())
+        matched = 0
+        for c in tt.lower():
+            if c in remaining:
+                remaining.remove(c)
+                matched += 1
+        if matched / len(tt) >= 0.7:
+            return True
+    return False
+
+
+def match_text(all_results: list[TextResult], target: str, fuzzy: bool = True) -> list[TextResult]:
+    if not target:
+        return list(all_results)
+    matched = [r for r in all_results
+               if (fuzzy_match(r.text, target) if fuzzy else target.lower() in r.text.lower())]
+    matched.sort(key=lambda r: r.confidence, reverse=True)
+    return matched
+
+
+def ocr_all(screen: np.ndarray) -> list[TextResult]:
+    """Run OCR on the screenshot (native PaddleOCR)."""
+    from autoclicker import ocr
+    return ocr.recognize(screen)
+
+
+def find_text(screen: np.ndarray, target: str) -> list[TextResult]:
+    return match_text(ocr_all(screen), target, fuzzy=True)

autoclicker/models.py

@@ -0,0 +1,468 @@
+"""Task / Step data model — a faithful Python port of the C++ task.h / task.cpp.
+
+The JSON schema is kept byte-compatible with the C++ AutoClicker so .json task
+files can be exchanged both ways: ``type`` is a string name (e.g. "click_image"),
+and fields at their default value are omitted on write, exactly like
+``Step::toJson`` / ``Step::fromJson``.
+"""
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class StepType(str, Enum):
+    ClickImage = "click_image"
+    ClickText = "click_text"
+    ClickPosition = "click_pos"
+    Wait = "wait"
+    Loop = "loop"
+    IfImageFound = "if_image"
+    IfTextFound = "if_text"
+    IfElse = "if_else"
+    CallSub = "call_sub"
+    SetVar = "set_var"
+    RandomWait = "random_wait"
+    KeyPress = "key_press"
+    TypeText = "type_text"
+    Hotkey = "hotkey"
+    LongPress = "long_press"
+    Drag = "drag"
+    Pinch = "pinch"
+    WaitImage = "wait_image"
+    WaitImageGone = "wait_image_gone"
+    Scroll = "scroll"
+    IfColorMatch = "if_color"
+    DoUntil = "do_until"
+    MergeImage = "merge_image"
+    MultiDrag = "multi_drag"
+    Goto = "goto"
+    IfImageCount = "if_image_count"
+    IfVar = "if_var"
+    ClickAll = "click_all"
+    GroupBegin = "group_begin"
+    GroupEnd = "group_end"
+    WhileCondition = "while_condition"
+    # Python-only extensions (C++ treats unknown types as Wait)
+    ReadText = "read_text"
+    ClickRelative = "click_relative"
+
+    @classmethod
+    def _missing_(cls, value):  # unknown name -> Wait, mirroring stepTypeFromName
+        return cls.Wait
+
+
+class UntilCondition(str, Enum):
+    NoneCond = "none"
+    ImageFound = "image_found"
+    ImageGone = "image_gone"
+    TextFound = "text_found"
+    ColorMatch = "color_match"
+
+    @classmethod
+    def _missing_(cls, value):
+        return cls.NoneCond
+
+
+class RetryPolicy(str, Enum):
+    NoneP = "none"
+    Retry = "retry"
+    Skip = "skip"
+    Abort = "abort"
+
+    @classmethod
+    def _missing_(cls, value):
+        return cls.NoneP
+
+
+@dataclass
+class RepeatConfig:
+    times: int = 1
+    delayMs: int = 500
+
+
+@dataclass
+class UntilConfig:
+    type: UntilCondition = UntilCondition.NoneCond
+    image: str = ""
+    text: str = ""
+    threshold: float = 0.8
+    color: str = ""
+    colorTolerance: int = 30
+    x: int = 0
+    y: int = 0
+    timeoutMs: int = 30000
+
+
+@dataclass
+class RetryConfig:
+    policy: RetryPolicy = RetryPolicy.NoneP
+    count: int = 3
+    delayMs: int = 1000
+
+
+@dataclass
+class Step:
+    type: StepType = StepType.Wait
+    imagePath: str = ""
+    imagePaths: list[str] = field(default_factory=list)
+    text: str = ""
+    x: int = 0
+    y: int = 0
+    waitMs: int = 1000
+    waitMsMax: int = 2000
+    loopTarget: int = 0
+    loopCount: int = -1
+    threshold: float = 0.8
+    timeoutMs: int = 5000
+    elseSkip: int = 1
+    subTaskPath: str = ""
+    varName: str = ""
+    varValue: str = ""
+    x2: int = 0
+    y2: int = 0
+    durationMs: int = 500
+    keyName: str = ""
+    modifierKey: str = ""
+    holdMs: int = 1000
+    pinchStartDist: int = 100
+    pinchEndDist: int = 50
+    scrollAmount: int = 3
+    mergeDelayMs: int = 1000
+    dragPoints: list[tuple[int, int]] = field(default_factory=list)
+    dragStepDelay: int = 500
+    gotoTarget: int = 0
+    minMatchCount: int = 2
+    compareOp: str = ""
+    compareValue: str = ""
+    clickDelayMs: int = 300
+    groupName: str = ""
+    disabled: bool = False
+    multiScale: bool = False
+    roiRect: Optional[tuple[int, int, int, int]] = None  # (x, y, w, h); None = full screen
+    randomOffset: int = 0
+    targetColor: str = ""
+    colorTolerance: int = 30
+    repeat: RepeatConfig = field(default_factory=RepeatConfig)
+    until: UntilConfig = field(default_factory=UntilConfig)
+    retry: RetryConfig = field(default_factory=RetryConfig)
+
+    # ------------------------------------------------------------------
+    # JSON (mirrors C++ Step::toJson / fromJson: string type, omit-at-default)
+    # ------------------------------------------------------------------
+    def to_json(self) -> dict:
+        obj: dict = {}
+        obj["type"] = self.type.value
+        if self.imagePath:
+            obj["image"] = self.imagePath
+        if self.imagePaths:
+            obj["images"] = list(self.imagePaths)
+        if self.text:
+            obj["text"] = self.text
+        if self.x != 0 or self.y != 0:
+            obj["x"] = self.x
+            obj["y"] = self.y
+        obj["wait_ms"] = self.waitMs
+        obj["wait_ms_max"] = self.waitMsMax
+        obj["loop_target"] = self.loopTarget
+        obj["loop_count"] = self.loopCount
+        obj["threshold"] = self.threshold
+        obj["timeout_ms"] = self.timeoutMs
+        obj["else_skip"] = self.elseSkip
+        if self.subTaskPath:
+            obj["sub_task"] = self.subTaskPath
+        if self.varName:
+            obj["var_name"] = self.varName
+            obj["var_value"] = self.varValue
+        obj["retry_policy"] = self.retry.policy.value
+        obj["retry_count"] = self.retry.count
+        obj["retry_delay_ms"] = self.retry.delayMs
+        if self.x2 != 0 or self.y2 != 0:
+            obj["x2"] = self.x2
+            obj["y2"] = self.y2
+        obj["duration_ms"] = self.durationMs
+        if self.keyName:
+            obj["key"] = self.keyName
+        if self.modifierKey:
+            obj["modifier"] = self.modifierKey
+        obj["hold_ms"] = self.holdMs
+        obj["pinch_start"] = self.pinchStartDist
+        obj["pinch_end"] = self.pinchEndDist
+        obj["scroll_amount"] = self.scrollAmount
+        if self.mergeDelayMs != 1000:
+            obj["merge_delay_ms"] = self.mergeDelayMs
+        if self.dragPoints:
+            obj["drag_points"] = [{"x": p[0], "y": p[1]} for p in self.dragPoints]
+        if self.dragStepDelay != 500:
+            obj["drag_step_delay"] = self.dragStepDelay
+        if self.gotoTarget != 0:
+            obj["goto_target"] = self.gotoTarget
+        if self.minMatchCount != 2:
+            obj["min_match_count"] = self.minMatchCount
+        if self.compareOp:
+            obj["compare_op"] = self.compareOp
+        if self.compareValue:
+            obj["compare_value"] = self.compareValue
+        if self.clickDelayMs != 300:
+            obj["click_delay_ms"] = self.clickDelayMs
+        if self.groupName:
+            obj["group_name"] = self.groupName
+        if self.disabled:
+            obj["disabled"] = True
+        if self.multiScale:
+            obj["multi_scale"] = True
+        if self.roiRect is not None:
+            rx, ry, rw, rh = self.roiRect
+            obj["roi"] = {"x": rx, "y": ry, "w": rw, "h": rh}
+        if self.randomOffset > 0:
+            obj["random_offset"] = self.randomOffset
+        if self.targetColor:
+            obj["target_color"] = self.targetColor
+        obj["color_tolerance"] = self.colorTolerance
+        if self.repeat.times != 1:
+            obj["repeat_times"] = self.repeat.times
+        if self.repeat.delayMs != 500:
+            obj["repeat_delay_ms"] = self.repeat.delayMs
+        if self.until.type != UntilCondition.NoneCond:
+            obj["until_type"] = self.until.type.value
+            if self.until.image:
+                obj["until_image"] = self.until.image
+            if self.until.text:
+                obj["until_text"] = self.until.text
+            obj["until_threshold"] = self.until.threshold
+            if self.until.color:
+                obj["until_color"] = self.until.color
+            obj["until_color_tolerance"] = self.until.colorTolerance
+            if self.until.x != 0 or self.until.y != 0:
+                obj["until_x"] = self.until.x
+                obj["until_y"] = self.until.y
+            obj["until_timeout_ms"] = self.until.timeoutMs
+        return obj
+
+    @staticmethod
+    def from_json(obj: dict) -> "Step":
+        s = Step()
+        s.type = StepType(obj.get("type", "wait"))
+        s.imagePath = obj.get("image", "")
+        s.imagePaths = list(obj.get("images", []))
+        s.text = obj.get("text", "")
+        s.x = int(obj.get("x", 0))
+        s.y = int(obj.get("y", 0))
+        s.waitMs = int(obj.get("wait_ms", 1000))
+        s.waitMsMax = int(obj.get("wait_ms_max", 2000))
+        s.loopTarget = int(obj.get("loop_target", 0))
+        s.loopCount = int(obj.get("loop_count", -1))
+        s.threshold = float(obj.get("threshold", 0.8))
+        s.timeoutMs = int(obj.get("timeout_ms", 5000))
+        s.elseSkip = int(obj.get("else_skip", 1))
+        s.subTaskPath = obj.get("sub_task", "")
+        s.varName = obj.get("var_name", "")
+        s.varValue = obj.get("var_value", "")
+        s.retry.policy = RetryPolicy(obj.get("retry_policy", "none"))
+        s.retry.count = int(obj.get("retry_count", 3))
+        s.retry.delayMs = int(obj.get("retry_delay_ms", 1000))
+        s.x2 = int(obj.get("x2", 0))
+        s.y2 = int(obj.get("y2", 0))
+        s.durationMs = int(obj.get("duration_ms", 500))
+        s.keyName = obj.get("key", "")
+        s.modifierKey = obj.get("modifier", "")
+        s.holdMs = int(obj.get("hold_ms", 1000))
+        s.pinchStartDist = int(obj.get("pinch_start", 100))
+        s.pinchEndDist = int(obj.get("pinch_end", 50))
+        s.scrollAmount = int(obj.get("scroll_amount", 3))
+        s.mergeDelayMs = int(obj.get("merge_delay_ms", 1000))
+        s.dragPoints = [(int(p["x"]), int(p["y"])) for p in obj.get("drag_points", [])]
+        s.dragStepDelay = int(obj.get("drag_step_delay", 500))
+        s.gotoTarget = int(obj.get("goto_target", 0))
+        s.minMatchCount = int(obj.get("min_match_count", 2))
+        s.compareOp = obj.get("compare_op", "")
+        s.compareValue = obj.get("compare_value", "")
+        s.clickDelayMs = int(obj.get("click_delay_ms", 300))
+        s.groupName = obj.get("group_name", "")
+        s.disabled = bool(obj.get("disabled", False))
+        s.multiScale = bool(obj.get("multi_scale", False))
+        if "roi" in obj:
+            r = obj["roi"]
+            s.roiRect = (int(r["x"]), int(r["y"]), int(r["w"]), int(r["h"]))
+        s.randomOffset = int(obj.get("random_offset", 0))
+        s.targetColor = obj.get("target_color", "")
+        s.colorTolerance = int(obj.get("color_tolerance", 30))
+        s.repeat.times = int(obj.get("repeat_times", 1))
+        s.repeat.delayMs = int(obj.get("repeat_delay_ms", 500))
+        s.until.type = UntilCondition(obj.get("until_type", "none"))
+        s.until.image = obj.get("until_image", "")
+        s.until.text = obj.get("until_text", "")
+        s.until.threshold = float(obj.get("until_threshold", 0.8))
+        s.until.color = obj.get("until_color", "")
+        s.until.colorTolerance = int(obj.get("until_color_tolerance", 30))
+        s.until.x = int(obj.get("until_x", 0))
+        s.until.y = int(obj.get("until_y", 0))
+        s.until.timeoutMs = int(obj.get("until_timeout_ms", 30000))
+        return s
+
+    # ------------------------------------------------------------------
+    # Human-readable label (mirrors Step::displayName for log/UI parity)
+    # ------------------------------------------------------------------
+    def display_name(self) -> str:
+        t = self.type
+
+        def fname(p: str) -> str:
+            return os.path.basename(p)
+
+        def stem(p: str) -> str:
+            return os.path.splitext(os.path.basename(p))[0]
+
+        if t == StepType.DoUntil:
+            cond = self._until_cond_text_dountil()
+            return f"循环直到 步骤{self.loopTarget + 1} ({cond})"
+
+        base = ""
+        if t == StepType.ClickImage:
+            base = (f"找图点击: [{len(self.imagePaths)}个模板]" if self.imagePaths
+                    else f"找图点击: {fname(self.imagePath)}")
+        elif t == StepType.ClickText:
+            base = f'找字点击: "{self.text}"'
+        elif t == StepType.ClickPosition:
+            base = f"坐标点击: ({self.x}, {self.y})"
+        elif t == StepType.Wait:
+            base = f"等待 {self.waitMs}ms"
+        elif t == StepType.RandomWait:
+            base = f"随机等待 {self.waitMs}~{self.waitMsMax}ms"
+        elif t == StepType.Loop:
+            base = (f"循环到步骤 {self.loopTarget + 1} (无限)" if self.loopCount < 0
+                    else f"循环到步骤 {self.loopTarget + 1} ({self.loopCount}次)")
+        elif t == StepType.IfImageFound:
+            base = (f"条件(图片): [{len(self.imagePaths)}个模板]" if self.imagePaths
+                    else f"条件(图片): {fname(self.imagePath)}")
+        elif t == StepType.IfTextFound:
+            base = f'条件(文字): "{self.text}"'
+        elif t == StepType.IfElse:
+            base = f"If/Else (否则跳过 {self.elseSkip} 步)"
+        elif t == StepType.CallSub:
+            base = f"调用子任务: {stem(self.subTaskPath)}"
+        elif t == StepType.SetVar:
+            base = f"设置变量: {self.varName} = {self.varValue}"
+        elif t == StepType.KeyPress:
+            base = f"按键: {self.keyName}"
+        elif t == StepType.TypeText:
+            base = f'输入文字: "{self.text}"'
+        elif t == StepType.Hotkey:
+            base = f"快捷键: {self.modifierKey}+{self.keyName}"
+        elif t == StepType.LongPress:
+            base = f"长按: ({self.x},{self.y}) {self.holdMs}ms"
+        elif t == StepType.Drag:
+            base = f"拖拽: ({self.x},{self.y})→({self.x2},{self.y2})"
+        elif t == StepType.Pinch:
+            base = f"捏合: {self.pinchStartDist}→{self.pinchEndDist}"
+        elif t == StepType.WaitImage:
+            base = (f"等待图片出现: [{len(self.imagePaths)}个模板]" if self.imagePaths
+                    else f"等待图片出现: {fname(self.imagePath)}")
+        elif t == StepType.WaitImageGone:
+            base = (f"等待图片消失: [{len(self.imagePaths)}个模板]" if self.imagePaths
+                    else f"等待图片消失: {fname(self.imagePath)}")
+        elif t == StepType.Scroll:
+            base = f"滚轮: ({self.x},{self.y}) {self.scrollAmount}格"
+        elif t == StepType.IfColorMatch:
+            base = f"条件(颜色): ({self.x},{self.y}) {self.targetColor}"
+        elif t == StepType.MergeImage:
+            base = (f"合成拖拽: [{len(self.imagePaths)}个模板]" if self.imagePaths
+                    else f"合成拖拽: {fname(self.imagePath)}")
+        elif t == StepType.MultiDrag:
+            base = f"多点拖拽: {len(self.dragPoints)}个点"
+        elif t == StepType.Goto:
+            base = f"跳转到步骤 {self.gotoTarget + 1}"
+        elif t == StepType.IfImageCount:
+            img = f"[{len(self.imagePaths)}个模板]" if self.imagePaths else fname(self.imagePath)
+            base = f"条件(图片数量≥{self.minMatchCount}): {img}"
+        elif t == StepType.IfVar:
+            base = f"条件(变量): {self.varName} {self.compareOp} {self.compareValue}"
+        elif t == StepType.ClickAll:
+            img = f"[{len(self.imagePaths)}个模板]" if self.imagePaths else fname(self.imagePath)
+            base = f"点击所有匹配: {img}"
+        elif t == StepType.GroupBegin:
+            base = f"┌ 分组: {self.groupName or '未命名'}"
+            if self.disabled:
+                base += " [已禁用]"
+        elif t == StepType.GroupEnd:
+            base = "└ 分组结束"
+        elif t == StepType.WhileCondition:
+            base = f"While({self._while_cond_text()}) →步骤{self.loopTarget + 1}"
+        elif t == StepType.ReadText:
+            mode = "数字" if self.varValue == "number" else "文字"
+            base = f"读取{mode}→变量: {self.varName}"
+        elif t == StepType.ClickRelative:
+            base = f"相对点击: last+({self.x},{self.y})"
+        else:
+            base = "Unknown"
+
+        if self.repeat.times > 1:
+            base += f" ×{self.repeat.times}"
+        elif self.repeat.times < 0:
+            base += " ×∞"
+        if self.until.type != UntilCondition.NoneCond:
+            u = self.until
+            if u.type == UntilCondition.ImageFound:
+                base += f" →直到出现:{fname(u.image)}"
+            elif u.type == UntilCondition.ImageGone:
+                base += f" →直到消失:{fname(u.image)}"
+            elif u.type == UntilCondition.TextFound:
+                base += f' →直到:"{u.text}"'
+            elif u.type == UntilCondition.ColorMatch:
+                base += f" →直到颜色:{u.color}"
+        return base
+
+    def _while_cond_text(self) -> str:
+        u = self.until
+        if u.type == UntilCondition.ImageFound:
+            return f"图片存在: {os.path.basename(u.image)}"
+        if u.type == UntilCondition.ImageGone:
+            return f"图片不存在: {os.path.basename(u.image)}"
+        if u.type == UntilCondition.TextFound:
+            return f'文字存在: "{u.text}"'
+        if u.type == UntilCondition.ColorMatch:
+            return f"颜色匹配: {u.color}"
+        return f"变量 {self.varName} {self.compareOp} {self.compareValue}"
+
+    def _until_cond_text_dountil(self) -> str:
+        u = self.until
+        if u.type == UntilCondition.ImageFound:
+            return f"图片出现: {os.path.basename(u.image)}"
+        if u.type == UntilCondition.ImageGone:
+            return f"图片消失: {os.path.basename(u.image)}"
+        if u.type == UntilCondition.TextFound:
+            return f'文字出现: "{u.text}"'
+        if u.type == UntilCondition.ColorMatch:
+            return f"颜色匹配: ({u.x},{u.y}) {u.color}"
+        return "无条件"
+
+
+@dataclass
+class Task:
+    name: str = "Untitled"
+    steps: list[Step] = field(default_factory=list)
+
+    def to_json(self) -> dict:
+        return {"name": self.name, "steps": [s.to_json() for s in self.steps]}
+
+    @staticmethod
+    def from_json(doc: dict) -> "Task":
+        task = Task()
+        task.name = doc.get("name", "Untitled")
+        task.steps = [Step.from_json(o) for o in doc.get("steps", [])]
+        return task
+
+    def save_to_file(self, path: str) -> bool:
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                json.dump(self.to_json(), f, ensure_ascii=False, indent=4, sort_keys=True)
+            return True
+        except OSError:
+            return False
+
+    @staticmethod
+    def load_from_file(path: str) -> "Task":
+        with open(path, "r", encoding="utf-8") as f:
+            return Task.from_json(json.load(f))

autoclicker/ocr.py

@@ -0,0 +1,63 @@
+"""Native PaddleOCR wrapper (lazy singleton).
+
+Replaces the C++ socket OCR daemon. Mirrors the preprocessing in matcher.cpp:
+images narrower than 800px are upscaled 2x before OCR and coordinates scaled
+back. PaddleOCR is imported lazily so the rest of the engine works without it.
+"""
+from __future__ import annotations
+
+import cv2
+import numpy as np
+
+_engine = None
+_import_failed = False
+
+
+def _get_engine():
+    global _engine, _import_failed
+    if _engine is not None:
+        return _engine
+    if _import_failed:
+        return None
+    try:
+        from paddleocr import PaddleOCR
+        _engine = PaddleOCR(use_angle_cls=True, lang="ch", show_log=False)
+    except Exception:
+        _import_failed = True
+        return None
+    return _engine
+
+
+def is_available() -> bool:
+    return _get_engine() is not None
+
+
+def recognize(screen: np.ndarray):
+    """Return list of TextResult for text in *screen* (empty if OCR unavailable)."""
+    from autoclicker.matcher import TextResult
+
+    engine = _get_engine()
+    if engine is None or screen is None or screen.size == 0:
+        return []
+
+    scale = 2.0 if screen.shape[1] < 800 else 1.0
+    img = (cv2.resize(screen, None, fx=scale, fy=scale, interpolation=cv2.INTER_CUBIC)
+           if scale > 1.0 else screen)
+
+    try:
+        raw = engine.ocr(img, cls=True)
+    except Exception:
+        return []
+
+    results: list[TextResult] = []
+    if not raw or raw[0] is None:
+        return results
+    for line in raw[0]:
+        box, (text, conf) = line[0], line[1]
+        xs = [p[0] for p in box]
+        ys = [p[1] for p in box]
+        x, y = min(xs), min(ys)
+        w, h = max(xs) - x, max(ys) - y
+        x, y, w, h = int(x / scale), int(y / scale), int(w / scale), int(h / scale)
+        results.append(TextResult(text, x + w // 2, y + h // 2, x, y, w, h, float(conf)))
+    return results