ascript 1.3.27__py3-none-win_amd64.whl

ascript/windows/tools/tool_api.py

@@ -0,0 +1,906 @@
+import base64
+import io
+import os
+import re
+import shutil
+import subprocess
+import sys
+import uuid
+from datetime import datetime
+from functools import lru_cache
+from typing import Any, Dict, Optional
+
+from ..screen import (
+    Canny, CodeScanner, Colors, CompareColors, FindBlock, FindColors, FindImages,
+    Ocr, OcrX, Screen,
+)
+from ..screen.as_cv import AsCv
+from ..window import Window
+
+
+class ToolApi:
+    """UI-independent API used by the SDK's WebView2 tools."""
+
+    def __init__(self, tool: str, initial_hwnd: Optional[int] = None):
+        self.tool = tool
+        self.initial_hwnd = int(initial_hwnd) if initial_hwnd else None
+        self._last_image = None
+        self._last_image_bytes = None
+        self._active_image_path = None
+        project_root = os.environ.get("ASCRIPT_PROJECT_ROOT", "").strip()
+        self._project_root = os.path.realpath(project_root) if project_root else ""
+        self._project_name = os.environ.get("ASCRIPT_PROJECT_NAME", "")
+        self._workspace_root = os.path.realpath(os.path.dirname(self._project_root)) if self._project_root else ""
+        self._image_templates = {}
+        data_root = os.environ.get("LOCALAPPDATA") or os.path.expanduser("~")
+        self._capture_dir = os.path.join(data_root, "AScript", "captures")
+        os.makedirs(self._capture_dir, exist_ok=True)
+        self._working_dir = os.path.join(self._capture_dir, "working")
+        os.makedirs(self._working_dir, exist_ok=True)
+        self._template_dir = os.path.join(self._working_dir, f"templates-{os.getpid()}")
+        os.makedirs(self._template_dir, exist_ok=True)
+
+    def get_context(self) -> Dict[str, Any]:
+        return {
+            "tool": self.tool,
+            "initialHwnd": self.initial_hwnd,
+            "captureDir": self._capture_dir,
+            "projectRoot": self._project_root or None,
+            "projectName": self._project_name or None,
+            "projects": self._workspace_projects(),
+        }
+
+    def _workspace_projects(self):
+        if not self._workspace_root or not os.path.isdir(self._workspace_root):
+            return []
+        projects = []
+        try:
+            for name in sorted(os.listdir(self._workspace_root), key=str.casefold):
+                if not re.fullmatch(r"[\w\u4e00-\u9fff-]{1,64}", name, re.UNICODE):
+                    continue
+                path = os.path.realpath(os.path.join(self._workspace_root, name))
+                if os.path.dirname(path) != self._workspace_root or not os.path.isdir(path):
+                    continue
+                if os.path.isfile(os.path.join(path, "__init__.py")):
+                    projects.append({"name": name, "path": path})
+        except OSError:
+            return []
+        return projects
+
+    def _resolve_project_root(self, project_name=None):
+        name = str(project_name or self._project_name).strip()
+        if not name:
+            raise ValueError("请选择要保存到的工程")
+        if not self._workspace_root or not re.fullmatch(r"[\w\u4e00-\u9fff-]{1,64}", name, re.UNICODE):
+            raise ValueError("工程名称无效")
+        root = os.path.realpath(os.path.join(self._workspace_root, name))
+        if os.path.dirname(root) != self._workspace_root or not os.path.isfile(os.path.join(root, "__init__.py")):
+            raise ValueError("所选工程不存在或不在当前工作区")
+        return root, name
+
+    @staticmethod
+    @lru_cache(maxsize=256)
+    def _product_name(process_path: str) -> str:
+        """Read the executable's localized ProductName from Windows version info."""
+        if not process_path or process_path == "Unknown":
+            return ""
+        try:
+            import win32api
+
+            raw = win32api.GetFileVersionInfo(process_path, "\\VarFileInfo\\Translation")
+            if isinstance(raw, str):
+                values = [ord(char) for char in raw]
+                translations = list(zip(values[0::2], values[1::2]))
+            elif isinstance(raw, (bytes, bytearray)):
+                translations = [
+                    (int.from_bytes(raw[index:index + 2], "little"),
+                     int.from_bytes(raw[index + 2:index + 4], "little"))
+                    for index in range(0, len(raw) - 3, 4)
+                ]
+            else:
+                translations = list(raw or [])
+            for language, codepage in translations:
+                if not (0 <= int(language) <= 0xFFFF and 0 <= int(codepage) <= 0xFFFF):
+                    continue
+                path = f"\\StringFileInfo\\{language:04x}{codepage:04x}\\ProductName"
+                value = str(win32api.GetFileVersionInfo(process_path, path) or "").strip()
+                if value:
+                    return value
+        except Exception:
+            pass
+        return ""
+
+    @classmethod
+    def _application_name(cls, window: Window, process_path: str) -> str:
+        product_name = cls._product_name(process_path)
+        if product_name:
+            return product_name
+        process_name = window.process_name or ""
+        stem = os.path.splitext(process_name)[0].strip()
+        known_apps = {
+            "chrome": "Google Chrome",
+            "msedge": "Microsoft Edge",
+            "firefox": "Mozilla Firefox",
+            "notepad": "Notepad",
+            "explorer": "File Explorer",
+        }
+        if stem.casefold() in known_apps:
+            return known_apps[stem.casefold()]
+        generic_hosts = {"applicationframehost", "shellexperiencehost", "systemsettings"}
+        if stem.casefold() in generic_hosts and window.title:
+            return window.title.split(" - ", 1)[0].strip()
+        return stem or window.title or "未知应用"
+
+    def get_windows(self) -> Dict[str, Any]:
+        try:
+            items = []
+            for window in Window.find_all(visible_only=True):
+                if window.title:
+                    process_path = window.process_path
+                    app_name = self._application_name(window, process_path)
+                    items.append({
+                        "display": f"{window.title} [{window.hwnd}]",
+                        "hwnd": window.hwnd,
+                        "title": window.title,
+                        "app_name": app_name,
+                        "process_name": window.process_name,
+                        "process_path": process_path,
+                        "class_name": window.class_name,
+                    })
+            items.sort(key=lambda item: (
+                item["app_name"].casefold(), item["title"].casefold(), item["hwnd"]
+            ))
+            return {"status": "success", "data": items}
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    def inspect_window(self, hwnd: int, max_depth: int = 0) -> Dict[str, Any]:
+        try:
+            target = Window(int(hwnd))
+            if not target.title:
+                return {"status": "error", "message": "窗口已关闭或句柄无效"}
+            depth = max(1, min(int(max_depth or 12), 30))
+            result = self._run_uia_worker(
+                ["inspect", "--hwnd", str(target.hwnd), "--depth", str(depth)],
+                timeout=25,
+            )
+            if result.get("status") == "success":
+                return result
+            fallback = self._native_window_tree(
+                target, result.get("message") or "目标窗口未暴露 UIA 控件"
+            )
+            return fallback if fallback.get("status") == "success" else result
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    @staticmethod
+    def _run_uia_worker(arguments, timeout: int, input_text: str = ""):
+        command = [sys.executable, "-u", "-m", "ascript.windows.tools.uia_worker", *arguments]
+        try:
+            completed = subprocess.run(
+                command, input=input_text, capture_output=True, text=True,
+                encoding="utf-8", errors="replace", timeout=timeout,
+                creationflags=getattr(subprocess, "CREATE_NO_WINDOW", 0),
+            )
+        except subprocess.TimeoutExpired:
+            return {"status": "error", "message": f"UI Automation 探测超过 {timeout} 秒，已终止隔离进程"}
+        prefix = "ASCRIPT_UIA_RESULT="
+        for line in reversed(completed.stdout.splitlines()):
+            if line.startswith(prefix):
+                try:
+                    import json
+                    return json.loads(line[len(prefix):])
+                except Exception as exc:
+                    return {"status": "error", "message": f"UIA 结果解析失败: {exc}"}
+        message = completed.stderr.strip() or completed.stdout.strip()
+        return {"status": "error", "message": message or "UIA 隔离进程异常退出"}
+
+    @staticmethod
+    def _count_nodes(node: Dict[str, Any]) -> int:
+        return 1 + sum(ToolApi._count_nodes(child) for child in node.get("children", []))
+
+    @staticmethod
+    def _native_window_tree(target: Window, reason: str) -> Dict[str, Any]:
+        """Fallback to real child HWNDs when the application exposes no useful UIA tree."""
+        import win32gui
+
+        root_hwnd = int(target.hwnd)
+        client = target.client_rect
+        handles = []
+        win32gui.EnumChildWindows(root_hwnd, lambda hwnd, output: output.append(hwnd), handles)
+        elements = {}
+        for hwnd in handles:
+            try:
+                rect = win32gui.GetWindowRect(hwnd)
+                elements[hwnd] = {
+                    "name": win32gui.GetWindowText(hwnd) or "",
+                    "type": "NativeWindow",
+                    "res_id": "",
+                    "memory_id": int(hwnd),
+                    "class_name": win32gui.GetClassName(hwnd),
+                    "handle": int(hwnd),
+                    "rect": {
+                        "left": rect[0] - client.left,
+                        "top": rect[1] - client.top,
+                        "right": rect[2] - client.left,
+                        "bottom": rect[3] - client.top,
+                    },
+                    "enabled": bool(win32gui.IsWindowEnabled(hwnd)),
+                    "visible": bool(win32gui.IsWindowVisible(hwnd)),
+                    "clickable": False,
+                    "value": "",
+                    "description": "",
+                    "password": False,
+                    "checkable": False,
+                    "checked": False,
+                    "editable": False,
+                    "focusable": False,
+                    "focused": False,
+                    "selected": False,
+                    "depth": 1,
+                    "child_count": 0,
+                    "children": [],
+                }
+            except Exception:
+                continue
+
+        root = {
+            "name": target.title or "",
+            "type": "Window",
+            "res_id": "",
+            "memory_id": root_hwnd,
+            "class_name": target.class_name or "",
+            "handle": root_hwnd,
+            "rect": {"left": 0, "top": 0, "right": client.width, "bottom": client.height},
+            "enabled": True,
+            "visible": target.is_visible,
+            "clickable": False,
+            "value": "",
+            "description": reason,
+            "password": False,
+            "checkable": False,
+            "checked": False,
+            "editable": False,
+            "focusable": False,
+            "focused": False,
+            "selected": False,
+            "depth": 0,
+            "child_count": 0,
+            "children": [],
+        }
+        for hwnd, element in elements.items():
+            parent_hwnd = win32gui.GetParent(hwnd)
+            while parent_hwnd not in elements and parent_hwnd != root_hwnd:
+                parent_hwnd = win32gui.GetParent(parent_hwnd)
+                if not parent_hwnd:
+                    break
+            parent = elements.get(parent_hwnd, root)
+            element["depth"] = parent["depth"] + 1
+            parent["children"].append(element)
+            parent["child_count"] += 1
+        count = ToolApi._count_nodes(root)
+        if count == 1:
+            return {"status": "empty", "message": f"{reason}；Win32 子窗口树也为空"}
+        return {
+            "status": "success", "backend": "Win32 HWND fallback",
+            "node_count": count, "message": reason, "data": root,
+        }
+
+    def capture(self, hwnd: Optional[int] = None) -> Dict[str, Any]:
+        try:
+            if hwnd:
+                image = Window(int(hwnd)).capture()
+            else:
+                image = Screen.capture()
+            if image is None:
+                return {"status": "error", "message": "截图失败"}
+            result = self._set_image(image)
+            if result.get("status") == "success":
+                result["cache_name"] = os.path.basename(self._cache_current_image("capture"))
+            return result
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    def _set_image(self, image) -> Dict[str, Any]:
+        if image.mode != "RGB":
+            image = image.convert("RGB")
+        # Keep the lossless source for color algorithms. JPEG is only the
+        # transport/preview format and must not change sampled RGB values.
+        self._last_image = image.copy()
+        image_bytes = Screen.encode_image(image, "JPEG")
+        self._last_image_bytes = image_bytes
+        self._active_image_path = os.path.join(self._working_dir, "current.jpg")
+        with open(self._active_image_path, "wb") as active_file:
+            active_file.write(image_bytes)
+        encoded = base64.b64encode(image_bytes).decode("ascii")
+        return {
+            "status": "success",
+            "data": f"data:image/jpeg;base64,{encoded}",
+            "width": image.width,
+            "height": image.height,
+            "cache_path": self._active_image_path,
+        }
+
+    def get_pixel_color(self, x: int, y: int) -> Dict[str, Any]:
+        if self._last_image is None:
+            return {"status": "error", "message": "请先截图"}
+        x, y = int(x), int(y)
+        if x < 0 or y < 0 or x >= self._last_image.width or y >= self._last_image.height:
+            return {"status": "error", "message": "取色坐标超出图片范围"}
+        red, green, blue = self._last_image.getpixel((x, y))[:3]
+        return {
+            "status": "success",
+            "data": f"#{red:02X}{green:02X}{blue:02X}",
+            "x": x,
+            "y": y,
+        }
+
+    def load_image(self, data_url: str) -> Dict[str, Any]:
+        try:
+            if not isinstance(data_url, str) or not data_url.startswith("data:image/"):
+                return {"status": "error", "message": "请选择图片文件"}
+            header, encoded = data_url.split(",", 1)
+            if not header.endswith(";base64") or len(encoded) > 28_000_000:
+                return {"status": "error", "message": "图片格式不支持或文件过大（上限 20 MB）"}
+            from PIL import Image
+
+            with Image.open(io.BytesIO(base64.b64decode(encoded, validate=True))) as image:
+                if image.width * image.height > 80_000_000:
+                    return {"status": "error", "message": "图片像素过大"}
+                image.load()
+                result = self._set_image(image)
+                if result.get("status") == "success":
+                    result["cache_name"] = os.path.basename(self._cache_current_image("upload"))
+                return result
+        except Exception as exc:
+            return {"status": "error", "message": f"图片打开失败：{exc}"}
+
+    def test_selector(self, expression: str) -> Dict[str, Any]:
+        result = self._run_uia_worker(["test"], timeout=15, input_text=expression)
+        result.setdefault("data", [])
+        return result
+
+    def test_selector_spec(self, spec: Dict[str, Any]) -> Dict[str, Any]:
+        import json
+
+        result = self._run_uia_worker(
+            ["test-spec"], timeout=15,
+            input_text=json.dumps(spec, ensure_ascii=False, separators=(",", ":")),
+        )
+        result.setdefault("data", [])
+        return result
+
+    def find_colors(self, pattern: str, threshold: float = 0.95, max_results: int = 50,
+                    rect=None, ori: int = 2, space: int = 5, mode: int = 0,
+                    find_one: bool = False) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图", "data": []}
+            results = FindColors.find_all(
+                pattern,
+                rect=self._rect(rect),
+                threshold=float(threshold),
+                ori=int(ori),
+                exclusion_radius=max(0, int(space)),
+                im_source=self._last_image,
+                max_res=1 if find_one else max(1, min(int(max_results), 500)),
+                mode=int(mode),
+            )
+            return {"status": "success", "data": [{"x": x, "y": y} for x, y in results]}
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    @staticmethod
+    def _rect(rect):
+        if not rect or len(rect) != 4:
+            return None
+        return [int(value) for value in rect]
+
+    @staticmethod
+    def _encode_cv_image(image) -> str:
+        import cv2
+
+        ok, encoded = cv2.imencode(".png", image)
+        if not ok:
+            raise RuntimeError("图像编码失败")
+        return "data:image/png;base64," + base64.b64encode(encoded.tobytes()).decode("ascii")
+
+    def _full_preview(self, output, rect=None):
+        """Composite a cropped algorithm preview back into capture coordinates."""
+        import cv2
+
+        source = AsCv.to_numpy(self._last_image).copy()
+        if output.ndim == 2:
+            output = cv2.cvtColor(output, cv2.COLOR_GRAY2BGR)
+        if rect is None:
+            return output
+        left, top, right, bottom = rect
+        target_width = max(1, right - left)
+        target_height = max(1, bottom - top)
+        if output.shape[1] != target_width or output.shape[0] != target_height:
+            output = cv2.resize(output, (target_width, target_height), interpolation=cv2.INTER_NEAREST)
+        source[top:bottom, left:right] = output
+        return source
+
+    def compare_colors(self, pattern: str, threshold: float = 0.95, required: float = 1.0,
+                       mode: int = 0, tolerance=None) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图"}
+            diff = tolerance if tolerance is not None else float(threshold)
+            data = CompareColors.compare_detail(
+                pattern, diff=diff, sim=float(required), mode=int(mode), image=self._last_image
+            )
+            return {"status": "success", "data": data}
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    def count_colors(self, colors: str, threshold: float = 0.95, rect=None,
+                     draw_mode: int = Colors.DRAW_THRESHOLD, mode: int = 0) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图"}
+            search_rect = self._rect(rect)
+            output, count, offset = Colors.filter(
+                colors, rect=search_rect, sim=float(threshold), image=self._last_image,
+                draw_mode=int(draw_mode), mode=int(mode),
+            )
+            return {
+                "status": "success",
+                "data": {
+                    "count": count,
+                    "offset": list(offset),
+                    "preview": self._encode_cv_image(self._full_preview(output, search_rect)),
+                },
+            }
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    def find_blocks(self, colors: str, width: int = 50, height: int = 50, count: int = 100,
+                    threshold: float = 0.9, rect=None, min_area: int = 10,
+                    max_results: int = 100, mode: int = 0, space: int = 0) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图", "data": []}
+            search_rect = self._rect(rect)
+            points = FindBlock.find_all(
+                colors, int(width), int(height), int(count), search_rect, float(threshold),
+                mode=int(mode), space=int(space), image=self._last_image,
+                max_results=int(max_results),
+            )
+            ranges = FindBlock.get_range(
+                colors, search_rect, float(threshold), mode=int(mode),
+                min_area=int(min_area), image=self._last_image
+            )
+            return {
+                "status": "success",
+                "data": {
+                    "points": [{"x": x, "y": y} for x, y in points],
+                    "ranges": ranges,
+                    "count": len(ranges),
+                },
+            }
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    @staticmethod
+    def _safe_image_name(filename: str) -> str:
+        name = str(filename or "").strip()
+        if not name:
+            raise ValueError("请输入模板名称")
+        if os.path.basename(name) != name or not re.fullmatch(r"[^\\/:*?\"<>|\x00-\x1f]{1,120}", name):
+            raise ValueError("模板名称包含无效字符")
+        stem, extension = os.path.splitext(name)
+        if not stem:
+            raise ValueError("模板名称无效")
+        if extension.lower() != ".png":
+            name = stem + ".png"
+        return name
+
+    def _next_template_name(self) -> str:
+        used = {item["name"].casefold() for item in self._image_templates.values()}
+        index = 1
+        while f"{index}.png".casefold() in used:
+            index += 1
+        return f"{index}.png"
+
+    @staticmethod
+    def _template_payload(template_id: str, item: Dict[str, Any]) -> Dict[str, Any]:
+        return {
+            "id": template_id,
+            "name": item["name"],
+            "width": item["width"],
+            "height": item["height"],
+            "thumbnail": item["thumbnail"],
+        }
+
+    @staticmethod
+    def _template_image(image):
+        has_alpha = image.mode in {"RGBA", "LA"} or (
+            image.mode == "P" and "transparency" in image.info
+        )
+        return image.convert("RGBA" if has_alpha else "RGB")
+
+    @staticmethod
+    def _image_thumbnail(image, maximum=(240, 140)) -> str:
+        thumbnail = image.copy()
+        thumbnail.thumbnail(maximum)
+        preview = io.BytesIO()
+        thumbnail.save(preview, format="PNG")
+        return "data:image/png;base64," + base64.b64encode(preview.getvalue()).decode("ascii")
+
+    def _store_image_template(self, image, filename: str = "") -> Dict[str, Any]:
+        name = self._safe_image_name(filename or self._next_template_name())
+        if any(item["name"].casefold() == name.casefold()
+               for item in self._image_templates.values()):
+            return {"status": "error", "message": f"模板名称已存在: {name}"}
+        image = self._template_image(image)
+        template_id = uuid.uuid4().hex
+        path = os.path.join(self._template_dir, template_id + ".png")
+        image.save(path, format="PNG")
+        item = {
+            "name": name,
+            "path": path,
+            "width": image.width,
+            "height": image.height,
+            "thumbnail": self._image_thumbnail(image),
+        }
+        self._image_templates[template_id] = item
+        return {
+            "status": "success",
+            "data": self._template_payload(template_id, item),
+            "next_name": self._next_template_name(),
+        }
+
+    def _project_image_dir(self, create: bool = False, project_name=None) -> str:
+        project_root, _ = self._resolve_project_root(project_name)
+        destination = os.path.realpath(os.path.join(project_root, "res", "img"))
+        if os.path.commonpath([project_root, destination]) != project_root:
+            raise ValueError("工程资源目录无效")
+        if create:
+            os.makedirs(destination, exist_ok=True)
+        return destination
+
+    def list_image_templates(self) -> Dict[str, Any]:
+        return {
+            "status": "success",
+            "data": [self._template_payload(template_id, item)
+                     for template_id, item in self._image_templates.items()],
+            "next_name": self._next_template_name(),
+        }
+
+    def add_image_template(self, rect, filename: str = "") -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图"}
+            crop_rect = self._rect(rect)
+            if crop_rect is None:
+                return {"status": "error", "message": "请先框选要查找的子图"}
+            left, top, right, bottom = crop_rect
+            left = max(0, min(left, self._last_image.width))
+            right = max(0, min(right, self._last_image.width))
+            top = max(0, min(top, self._last_image.height))
+            bottom = max(0, min(bottom, self._last_image.height))
+            if right <= left or bottom <= top:
+                return {"status": "error", "message": "模板选区为空"}
+            image = self._last_image.crop((left, top, right, bottom))
+            return self._store_image_template(image, filename)
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    def import_image_template(self, data_url: str, filename: str = "") -> Dict[str, Any]:
+        try:
+            header, encoded = str(data_url).split(",", 1)
+            if not header.startswith("data:image/") or not header.endswith(";base64"):
+                return {"status": "error", "message": "小图格式不支持"}
+            if len(encoded) > 28_000_000:
+                return {"status": "error", "message": "小图文件过大（上限 20 MB）"}
+            from PIL import Image
+
+            with Image.open(io.BytesIO(base64.b64decode(encoded, validate=True))) as image:
+                if image.width * image.height > 80_000_000:
+                    return {"status": "error", "message": "小图像素过大"}
+                image.load()
+                return self._store_image_template(image, filename)
+        except Exception as exc:
+            return {"status": "error", "message": f"小图导入失败：{exc}"}
+
+    def list_project_images(self) -> Dict[str, Any]:
+        try:
+            root = self._project_image_dir()
+        except ValueError as exc:
+            return {"status": "success", "data": [], "available": False, "message": str(exc)}
+        if not os.path.isdir(root):
+            return {"status": "success", "data": [], "available": True}
+        items = []
+        from PIL import Image
+
+        for name in sorted(os.listdir(root), key=str.casefold):
+            if not name.lower().endswith((".png", ".jpg", ".jpeg", ".bmp", ".webp")):
+                continue
+            path = os.path.realpath(os.path.join(root, name))
+            if os.path.commonpath([root, path]) != root or not os.path.isfile(path):
+                continue
+            try:
+                with Image.open(path) as image:
+                    image.load()
+                    items.append({
+                        "name": name,
+                        "width": image.width,
+                        "height": image.height,
+                        "thumbnail": self._image_thumbnail(self._template_image(image), (120, 80)),
+                    })
+            except (OSError, ValueError):
+                continue
+        return {"status": "success", "data": items, "available": True}
+
+    def add_project_image_template(self, filename: str) -> Dict[str, Any]:
+        try:
+            root = self._project_image_dir()
+            name = os.path.basename(str(filename))
+            if name != filename or not name.lower().endswith((".png", ".jpg", ".jpeg", ".bmp", ".webp")):
+                return {"status": "error", "message": "工程图片名称无效"}
+            path = os.path.realpath(os.path.join(root, name))
+            if os.path.commonpath([root, path]) != root or not os.path.isfile(path):
+                return {"status": "error", "message": f"工程图片不存在: {name}"}
+            from PIL import Image
+
+            with Image.open(path) as image:
+                image.load()
+                return self._store_image_template(image, name)
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    def clear_image_templates(self) -> Dict[str, Any]:
+        removed = len(self._image_templates)
+        for item in self._image_templates.values():
+            try:
+                os.remove(item["path"])
+            except FileNotFoundError:
+                pass
+        self._image_templates.clear()
+        return {"status": "success", "removed": removed, "next_name": self._next_template_name()}
+
+    def rename_image_template(self, template_id: str, filename: str) -> Dict[str, Any]:
+        try:
+            item = self._image_templates.get(str(template_id))
+            if item is None:
+                return {"status": "error", "message": "模板不存在"}
+            name = self._safe_image_name(filename)
+            if any(key != template_id and value["name"].casefold() == name.casefold()
+                   for key, value in self._image_templates.items()):
+                return {"status": "error", "message": f"模板名称已存在: {name}"}
+            item["name"] = name
+            return {"status": "success", "data": self._template_payload(template_id, item)}
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    def delete_image_template(self, template_id: str) -> Dict[str, Any]:
+        item = self._image_templates.pop(str(template_id), None)
+        if item is None:
+            return {"status": "error", "message": "模板不存在"}
+        try:
+            os.remove(item["path"])
+        except FileNotFoundError:
+            pass
+        return {"status": "success", "next_name": self._next_template_name()}
+
+    def save_image_templates(self, project_name=None, overwrite: bool = False) -> Dict[str, Any]:
+        try:
+            destination = self._project_image_dir(create=True, project_name=project_name)
+            conflicts = [item["name"] for item in self._image_templates.values()
+                         if os.path.exists(os.path.join(destination, item["name"]))]
+            if conflicts and not overwrite:
+                return {"status": "conflict", "message": "工程中已存在同名图片", "conflicts": conflicts}
+            saved = []
+            for item in self._image_templates.values():
+                target = os.path.join(destination, item["name"])
+                shutil.copyfile(item["path"], target)
+                saved.append(target)
+            return {"status": "success", "data": saved, "project": str(project_name or self._project_name)}
+        except Exception as exc:
+            return {"status": "error", "message": str(exc)}
+
+    def find_images(self, template_ids, search_rect=None, confidence: float = 0.9,
+                    max_results: int = 50, algorithm: str = "template",
+                    rgb: bool = False, find_one: bool = False, ori: int = 2,
+                    scale_range=None) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图", "data": []}
+            ids = [str(value) for value in (template_ids or [])]
+            templates = [self._image_templates[value]["path"] for value in ids
+                         if value in self._image_templates]
+            if not templates:
+                return {"status": "error", "message": "请先添加要查找的子图", "data": []}
+            method = str(algorithm or "template").lower()
+            function = {
+                "template": FindImages.find_template if find_one else FindImages.find_all_template,
+                "sift": FindImages.find_sift if find_one else FindImages.find_all_sift,
+                "mixed": FindImages.find if find_one else FindImages.find_all,
+            }.get(method)
+            if function is None:
+                return {"status": "error", "message": f"不支持的找图模式: {algorithm}", "data": []}
+            kwargs = {
+                "rect": self._rect(search_rect),
+                "confidence": float(confidence),
+                "rgb": bool(rgb),
+                "source_img": self._last_image,
+                "ori": int(ori),
+                "scale_range": scale_range,
+            }
+            if not find_one:
+                kwargs["maxcnt"] = max(1, min(int(max_results), 500))
+            matches = function(templates, **kwargs)
+            if find_one:
+                matches = [matches] if matches is not None else []
+            data = [match.to_dict() if hasattr(match, "to_dict") else dict(match) for match in matches]
+            return {"status": "success", "data": data}
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    def run_ocr(self, rect=None, confidence: float = 0.1, pattern: str = "", binary: int = -1,
+                operation: str = "recognize") -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图", "data": []}
+            kwargs = {
+                "rect": self._rect(rect), "confidence": float(confidence),
+                "image": self._last_image, "binary": int(binary),
+            }
+            if operation == "recognize":
+                data = [item.to_dict() for item in Ocr.recognize(pattern=pattern or None, **kwargs)]
+            elif operation == "find_all":
+                items = Ocr.find_all(text=pattern or None, **kwargs)
+                data = [item.to_dict() for item in items] or None
+            elif operation == "find":
+                item = Ocr.find(text=pattern or None, **kwargs)
+                data = item.to_dict() if item else None
+            elif operation == "exists":
+                data = Ocr.exists(text=pattern or None, **kwargs)
+            else:
+                raise ValueError(f"不支持的 OCR 操作: {operation}")
+            return {
+                "status": "success", "backend": Ocr.backend_info(),
+                "data": data,
+            }
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    def run_ocrx(self, font_lib: str, rect=None, confidence: float = 0.9) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图", "data": []}
+            result = OcrX.recognize(
+                font_lib, rect=self._rect(rect), region=float(confidence), image=self._last_image
+            )
+            return {"status": "success", "data": result.to_dict()}
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    def run_canny(self, rect=None, low: int = 50, high: int = 150, algorithm: str = "canny",
+                  min_area: int = 10) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图", "data": []}
+            search_rect = self._rect(rect)
+            results, output, edges = Canny.detect(
+                int(low), int(high), image=self._last_image, rect=search_rect,
+                algo=algorithm, area_range=[int(min_area), 0], draw=Canny.DRAW_RECT,
+                return_image=True,
+            )
+            return {
+                "status": "success",
+                "data": {
+                    "items": results,
+                    "preview": self._encode_cv_image(self._full_preview(output, search_rect)),
+                    "edges": self._encode_cv_image(edges),
+                },
+            }
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    def scan_codes(self, rect=None) -> Dict[str, Any]:
+        try:
+            if self._last_image is None:
+                return {"status": "error", "message": "请先截图", "data": []}
+            return {
+                "status": "success",
+                "data": CodeScanner.scan(rect=self._rect(rect), image=self._last_image),
+            }
+        except Exception as exc:
+            return {"status": "error", "message": str(exc), "data": []}
+
+    def save_capture(self, filename: str = "capture.png") -> Dict[str, Any]:
+        if self._last_image is None:
+            return {"status": "error", "message": "没有可保存的截图"}
+        safe_name = os.path.basename(filename) or "capture.png"
+        if not safe_name.lower().endswith((".png", ".jpg", ".jpeg")):
+            safe_name += ".png"
+        path = os.path.join(self._capture_dir, safe_name)
+        self._last_image.save(path)
+        return {"status": "success", "path": path}
+
+    def _cache_current_image(self, source: str) -> str:
+        stamp = datetime.now().strftime("%Y%m%d-%H%M%S-%f")
+        path = os.path.join(self._capture_dir, f"{source}-{stamp}.jpg")
+        with open(path, "wb") as cache_file:
+            cache_file.write(self._last_image_bytes)
+        return path
+
+    def list_capture_cache(self) -> Dict[str, Any]:
+        items = []
+        for name in os.listdir(self._capture_dir):
+            path = os.path.join(self._capture_dir, name)
+            if not os.path.isfile(path) or not name.lower().endswith((".png", ".jpg", ".jpeg")):
+                continue
+            try:
+                stat = os.stat(path)
+                from PIL import Image
+
+                with Image.open(path) as image:
+                    width, height = image.size
+                    thumbnail = image.copy()
+                    thumbnail.thumbnail((150, 90))
+                    preview = io.BytesIO()
+                    thumbnail.save(preview, format="JPEG", quality=75)
+                items.append({
+                    "name": name,
+                    "path": path,
+                    "width": width,
+                    "height": height,
+                    "size": stat.st_size,
+                    "modified": stat.st_mtime,
+                    "thumbnail": "data:image/jpeg;base64," + base64.b64encode(preview.getvalue()).decode("ascii"),
+                })
+            except (OSError, ValueError):
+                continue
+        items.sort(key=lambda item: item["modified"], reverse=True)
+        return {"status": "success", "data": items}
+
+    def load_cached_capture(self, name: str) -> Dict[str, Any]:
+        try:
+            safe_name = os.path.basename(str(name))
+            if safe_name != name or not safe_name.lower().endswith((".png", ".jpg", ".jpeg")):
+                return {"status": "error", "message": "缓存图片名称无效"}
+            root = os.path.realpath(self._capture_dir)
+            path = os.path.realpath(os.path.join(root, safe_name))
+            if os.path.commonpath([root, path]) != root:
+                return {"status": "error", "message": "缓存图片路径无效"}
+            from PIL import Image
+
+            with Image.open(path) as image:
+                image.load()
+                result = self._set_image(image)
+                result["cache_name"] = safe_name
+                return result
+        except Exception as exc:
+            return {"status": "error", "message": f"缓存图片读取失败：{exc}"}
+
+    def delete_capture_cache(self, name: str) -> Dict[str, Any]:
+        safe_name = os.path.basename(str(name))
+        if safe_name != name or not safe_name.lower().endswith((".png", ".jpg", ".jpeg")):
+            return {"status": "error", "message": "缓存图片名称无效"}
+        root = os.path.realpath(self._capture_dir)
+        path = os.path.realpath(os.path.join(root, safe_name))
+        if os.path.commonpath([root, path]) != root:
+            return {"status": "error", "message": "缓存图片路径无效"}
+        try:
+            os.remove(path)
+            return {"status": "success"}
+        except Exception as exc:
+            return {"status": "error", "message": f"删除缓存失败：{exc}"}
+
+    def clear_capture_cache(self) -> Dict[str, Any]:
+        removed = 0
+        for item in self.list_capture_cache().get("data", []):
+            try:
+                os.remove(item["path"])
+                removed += 1
+            except OSError:
+                pass
+        return {"status": "success", "removed": removed}
+
+    def open_capture_folder(self) -> bool:
+        subprocess.Popen(["explorer.exe", self._capture_dir])
+        return True