ok-script 2.0.0b1__tar.gz → 2.0.0b3__tar.gz

{ok_script-2.0.0b1/ok_script.egg-info → ok_script-2.0.0b3}/PKG-INFO

@@ -1,17 +1,16 @@
 Metadata-Version: 2.4
 Name: ok-script
-Version: 2.0.0b1
+Version: 2.0.0b3
 Summary: Automation with Computer Vision for Python
-Home-page: https://github.com/ok-oldking/ok-script
-Author: ok-oldking
-Author-email: firedcto@gmail.com
+Author-email: ok-oldking <firedcto@gmail.com>
+Project-URL: Homepage, https://github.com/ok-oldking/ok-script
+Project-URL: Repository, https://github.com/ok-oldking/ok-script
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -24,28 +23,35 @@ Requires-Dist: psutil>=6.0.0
 Requires-Dist: pydirectinput==1.0.4
 Requires-Dist: pycaw==20240210
 Requires-Dist: mouse==0.7.1
-Provides-Extra: qt
-Requires-Dist: PySide6-Fluent-Widgets>=1.8.3; extra == "qt"
+Requires-Dist: pynput>=1.8.1
+Provides-Extra: default
+Requires-Dist: numpy>=1.26.4; extra == "default"
+Requires-Dist: Pillow>=10.0; extra == "default"
+Requires-Dist: ok-d3dshot>=0.1.5; extra == "default"
+Requires-Dist: OpenCC==1.2.0; extra == "default"
 Provides-Extra: web
 Requires-Dist: fastapi>=0.115.0; extra == "web"
 Requires-Dist: uvicorn[standard]>=0.30.0; extra == "web"
 Requires-Dist: pywebview>=5.4; extra == "web"
-Provides-Extra: all
-Requires-Dist: PySide6-Fluent-Widgets>=1.8.3; extra == "all"
-Requires-Dist: fastapi>=0.115.0; extra == "all"
-Requires-Dist: uvicorn[standard]>=0.30.0; extra == "all"
-Requires-Dist: pywebview>=5.4; extra == "all"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
+Provides-Extra: qt
+Requires-Dist: PySide6-Essentials>=6.7.0; extra == "qt"
+Requires-Dist: PySideSix-Frameless-Window>=0.3.12; extra == "qt"
+Requires-Dist: darkdetect>=0.8.0; extra == "qt"
+Requires-Dist: PySide6-Fluent-Widgets>=1.8.3; extra == "qt"
+Provides-Extra: adb
+Requires-Dist: adbutils>=2.2.1; extra == "adb"
+Provides-Extra: ocr
+Requires-Dist: onnxocr-ppocrv5; extra == "ocr"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: setuptools>=77; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: get-pypi-latest-version; extra == "dev"
+Requires-Dist: mkdocs-material==9.7.7; extra == "dev"
 Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
 
 # ok-script
 
@@ -82,6 +88,29 @@ ok-script 支持 Python 3.11 及以上版本，推荐使用 Python 3.12。
 python -m pip install ok-script
 ```
 
+只安装应用所需的依赖配置。`default` 为无界面模式，Web、Qt、ADB 和 OCR
+能力分别按需安装：
+
+```powershell
+python -m pip install "ok-script[default]"
+python -m pip install "ok-script[qt]"
+python -m pip install "ok-script[web]"
+python -m pip install "ok-script[adb]"
+python -m pip install "ok-script[ocr]"
+```
+
+ok-script 不会自动选择 OpenCV。用户必须根据自己的应用选择版本，并且只安装
+一个变体：`opencv-python`、`opencv-contrib-python`、`opencv-python-headless`
+或 `opencv-contrib-python-headless`。
+
+以无界面模式开发本仓库时，同时安装 `pyproject.toml` 中的 `default` 和 `dev`
+依赖组；再根据需要添加 `--group web`、`--group qt`、`--group adb` 或
+`--group ocr`：
+
+```powershell
+python -m pip install --editable . --group default --group dev
+```
+
 如果要创建完整的自动化项目，建议从 [`ok-script-app`](https://github.com/ok-oldking/ok-script-app) 模板开始，而不是直接在本仓库中编写业务脚本。
 
 ## 文档

{ok_script-2.0.0b1 → ok_script-2.0.0b3}/README.md

@@ -33,6 +33,29 @@ ok-script 支持 Python 3.11 及以上版本，推荐使用 Python 3.12。
 python -m pip install ok-script
 ```
 
+只安装应用所需的依赖配置。`default` 为无界面模式，Web、Qt、ADB 和 OCR
+能力分别按需安装：
+
+```powershell
+python -m pip install "ok-script[default]"
+python -m pip install "ok-script[qt]"
+python -m pip install "ok-script[web]"
+python -m pip install "ok-script[adb]"
+python -m pip install "ok-script[ocr]"
+```
+
+ok-script 不会自动选择 OpenCV。用户必须根据自己的应用选择版本，并且只安装
+一个变体：`opencv-python`、`opencv-contrib-python`、`opencv-python-headless`
+或 `opencv-contrib-python-headless`。
+
+以无界面模式开发本仓库时，同时安装 `pyproject.toml` 中的 `default` 和 `dev`
+依赖组；再根据需要添加 `--group web`、`--group qt`、`--group adb` 或
+`--group ocr`：
+
+```powershell
+python -m pip install --editable . --group default --group dev
+```
+
 如果要创建完整的自动化项目，建议从 [`ok-script-app`](https://github.com/ok-oldking/ok-script-app) 模板开始，而不是直接在本仓库中编写业务脚本。
 
 ## 文档

ok_script-2.0.0b3/diagnostics/qq_trace.py

@@ -0,0 +1,101 @@
+"""Trace QQ notification navigation without sending a message.
+
+Usage: .venv\\Scripts\\python.exe diagnostics\\qq_trace.py [nickname]
+"""
+from __future__ import annotations
+
+import logging
+import sys
+import time
+from pathlib import Path
+
+import cv2
+import numpy as np
+from types import SimpleNamespace
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+from ok.notification.windows_messenger import MessengerAutomation
+
+
+OUT = Path(__file__).resolve().parents[1] / "logs" / "qq_trace"
+OUT.mkdir(parents=True, exist_ok=True)
+logging.basicConfig(
+    filename=OUT / "trace.log",
+    level=logging.INFO,
+    format="%(asctime)s.%(msecs)03d %(levelname)s %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+log = logging.getLogger("qq_trace")
+
+
+def snap(automation: MessengerAutomation, hwnd: int, label: str) -> None:
+    try:
+        frame = automation._capture(hwnd)
+        path = OUT / f"{time.time_ns()}_{label}.png"
+        cv2.imwrite(str(path), frame)
+        log.info("screenshot label=%s path=%s shape=%s", label, path, frame.shape)
+    except Exception:
+        log.exception("screenshot_failed label=%s", label)
+
+
+def main() -> int:
+    nickname = (sys.argv[1] if len(sys.argv) > 1 else "文件传输助手").strip()
+    log.info("START nickname=%r", nickname)
+    automation = MessengerAutomation(
+        ("QQ.exe",), SimpleNamespace(), window_titles=("QQ",),
+        dismiss_search_after_contact=True, post_activate=False,
+    )
+    hwnd = automation._find_hwnd()
+    log.info("find_hwnd hwnd=%s foreground=%s", hwnd, __import__("win32gui").GetForegroundWindow())
+    if not hwnd:
+        log.error("QQ window not found")
+        return 2
+    snap(automation, hwnd, "01_initial")
+    if not automation._wait_until_background(hwnd):
+        log.warning("wait_until_background returned false")
+        return 3
+    log.info("background_ready foreground=%s", __import__("win32gui").GetForegroundWindow())
+    snap(automation, hwnd, "02_background_ready")
+    search_region, contact_region, send_region = automation._layout_regions(hwnd)
+    log.info("layout search=%s contact=%s send=%s", search_region, contact_region, send_region)
+    search = automation._wait_text(hwnd, {"Search", "搜索"}, region=search_region, timeout=1.5)
+    log.info("search_ocr point=%s", search)
+    if search is None:
+        search = automation._search_field_point(hwnd)
+        log.info("search_fallback point=%s", search)
+    snap(automation, hwnd, "03_before_search_click")
+    target = automation._click(hwnd, search)
+    log.info("click search target=%s point=%s", target, search)
+    snap(automation, hwnd, "04_after_search_click")
+    time.sleep(1)
+    automation._clear_text(target)
+    log.info("clear search")
+    time.sleep(1)
+    automation._type_text(target, nickname)
+    log.info("type nickname=%r", nickname)
+    time.sleep(1)
+    snap(automation, hwnd, "05_after_typing")
+    contact_hwnd, contact = automation._wait_contact(hwnd, nickname, contact_region, timeout=8)
+    log.info("contact_result hwnd=%s point=%s", contact_hwnd, contact)
+    if contact is None:
+        log.error("contact not found")
+        automation._send_key(hwnd, 0x1B)
+        snap(automation, hwnd, "06_contact_not_found_escape")
+        return 4
+    automation._click(contact_hwnd, contact, focus=contact_hwnd == hwnd)
+    log.info("click contact target=%s point=%s", contact_hwnd, contact)
+    snap(automation, hwnd, "06_after_contact_click")
+    time.sleep(1)
+    automation._send_key(hwnd, 0x1B)
+    log.info("send escape to dismiss search overlay")
+    time.sleep(1)
+    snap(automation, hwnd, "07_after_escape")
+    send_box = automation._wait_text(hwnd, {"Send", "发送"}, region=send_region, timeout=3)
+    log.info("send_box=%s (dry-run; no message sent)", send_box)
+    snap(automation, hwnd, "08_final_dry_run")
+    log.info("END")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{ok_script-2.0.0b1 → ok_script-2.0.0b3}/ok/__init__.py

@@ -66,6 +66,7 @@ if TYPE_CHECKING:
         WaitFailedException,
     )
     from ok.task.task import BaseTask, FindFeature, OCR, TriggerTask
+    from ok.task.web import WebCustomTab, WebTabConfig, task_tab_action, task_tab_query
     from ok.util.Analytics import Analytics
     from ok.util.GlobalConfig import (GlobalConfig, register_app_launcher_options,
                                       register_basic_options, register_notification_options)
@@ -131,6 +132,10 @@ _LAZY_IMPORTS = {
     'DiagnosisTask': ('ok.task.DiagnosisTask', 'DiagnosisTask'),
     'BaseTask': ('ok.task.task', 'BaseTask'),
     'TriggerTask': ('ok.task.task', 'TriggerTask'),
+    'WebTabConfig': ('ok.task.web', 'WebTabConfig'),
+    'WebCustomTab': ('ok.task.web', 'WebCustomTab'),
+    'task_tab_action': ('ok.task.web', 'task_tab_action'),
+    'task_tab_query': ('ok.task.web', 'task_tab_query'),
     'FindFeature': ('ok.task.task', 'FindFeature'),
     'OCR': ('ok.task.task', 'OCR'),
     'Feature': ('ok.feature.Feature', 'Feature'),
@@ -947,13 +952,24 @@ class OK:
                                           config_folder=self.config.get("config_folder"), debug=self.debug,
                                           global_config=self.global_config, ocr_target_height=ocr_target_height,
                                           config=self.config)
+        onetime_tasks = list(self.config.get('onetime_tasks', []))
+        ui_config = resolve_ui_config(self.config)
+        if ((ui_config is not None and ui_config["type"] == "web")
+                or self.config.get("web_runtime", False)):
+            from ok.task.web import configured_web_custom_tabs
+            existing = {tuple(task[:2]) for task in onetime_tasks
+                        if isinstance(task, (list, tuple)) and len(task) >= 2}
+            for web_task in configured_web_custom_tabs(self.config.get('web_tabs', [])):
+                if tuple(web_task) not in existing:
+                    onetime_tasks.append(web_task)
+                    existing.add(tuple(web_task))
         if self.should_init_task_manager_headless():
             from ok.core.task_manager import TaskManager
         else:
             from ok.ui.qt.tasks.TaskManger import TaskManager
         task_app = self.headless_app if self.should_init_task_manager_headless() else self.app
         og.task_manager = TaskManager(task_executor=self.task_executor, app=task_app,
-                                      onetime_tasks=self.config.get('onetime_tasks', []),
+                                      onetime_tasks=onetime_tasks,
                                       trigger_tasks=self.config.get('trigger_tasks', []),
                                       scene=self.config.get('scene'))
         og.executor = self.task_executor

{ok_script-2.0.0b1 → ok_script-2.0.0b3}/ok/core/events.py

@@ -80,7 +80,7 @@ class EventBus:
         "blur_overlay", "clear_blur_overlay", "adb_devices",
         "config_validation", "tab", "capture_error", "starting_emulator",
         "quit", "start_success", "act", "copyright", "global_config",
-        "restart_admin",
+        "restart_admin", "task_tab",
     )
 
     def __init__(self):

ok_script-2.0.0b3/ok/gui/__init__.py

@@ -0,0 +1,50 @@
+"""Compatibility namespace for the Qt UI moved to :mod:`ok.ui.qt`.
+
+New code should import ``ok.ui.qt``. Existing ``ok.gui`` imports are redirected
+to the same module objects so classes are not defined twice under the legacy
+and current package names.
+"""
+
+from importlib import import_module
+from importlib.abc import Loader, MetaPathFinder
+from importlib.util import find_spec, spec_from_loader
+from pathlib import Path
+import sys
+
+
+class _QtAliasLoader(Loader):
+    def __init__(self, alias_name, target_name):
+        self.alias_name = alias_name
+        self.target_name = target_name
+
+    def create_module(self, spec):
+        return import_module(self.target_name)
+
+    def exec_module(self, module):
+        sys.modules[self.alias_name] = module
+
+
+class _QtAliasFinder(MetaPathFinder):
+    legacy_prefix = f"{__name__}."
+    current_prefix = "ok.ui.qt."
+
+    def find_spec(self, fullname, path=None, target=None):
+        if not fullname.startswith(self.legacy_prefix):
+            return None
+        target_name = self.current_prefix + fullname[len(self.legacy_prefix):]
+        target_spec = find_spec(target_name)
+        if target_spec is None:
+            return None
+        return spec_from_loader(
+            fullname,
+            _QtAliasLoader(fullname, target_name),
+            origin=target_spec.origin,
+            is_package=target_spec.submodule_search_locations is not None,
+        )
+
+
+if not any(isinstance(finder, _QtAliasFinder) for finder in sys.meta_path):
+    sys.meta_path.insert(0, _QtAliasFinder())
+
+_compat = Path(__file__).resolve().parent
+__path__ = [str(_compat), str(_compat.parent / "ui" / "qt")]

{ok_script-2.0.0b1 → ok_script-2.0.0b3}/ok/task/task.py

@@ -83,6 +83,10 @@ class ExecutorOperation:
         """
         return self.executor.get_task_by_class(cls)
 
+    def get_tasks(self):
+        """Return registered tasks without exposing the executor to extensions."""
+        return list(self.executor.get_all_tasks())
+
     def box_in_horizontal_center(self, box, off_percent=0.02):
         """
         Checks if a box is in the horizontal center.
@@ -1282,6 +1286,13 @@ class BaseTask(OCR):
             communicate.screenshot.emit(frame, f'notification/notification_{index + 1}', False, None)
         communicate.notification.emit(message, title, error, tray, show_tab, params, frames)
 
+    def emit_web_event(self, event, payload=None):
+        """Publish a serializable event to this task's optional browser tab."""
+        tab = getattr(self, "web_tab", None)
+        if tab is None:
+            raise RuntimeError(f"{self.__class__.__name__} does not declare web_tab")
+        communicate.task_tab.emit(tab.id, str(event), payload)
+
     @property
     def enabled(self):
         return self._enabled

ok_script-2.0.0b3/ok/task/web.py

@@ -0,0 +1,162 @@
+"""Framework-neutral task-backed web tab declarations.
+
+This module deliberately has no FastAPI or browser dependencies. Tasks can
+declare a web tab without making the headless or Qt installations depend on
+the web UI stack.
+"""
+
+from __future__ import annotations
+
+import inspect
+import importlib
+import importlib.util
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Callable, Literal
+
+from ok.task.task import BaseTask
+
+
+_TAB_ID = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+_OPERATION_NAME = re.compile(r"^[a-z][a-z0-9_-]*$")
+
+
+@dataclass(frozen=True)
+class WebTabConfig:
+    """Metadata for a browser page owned by a task instance."""
+
+    id: str
+    name: str
+    asset_dir: str | Path
+    entrypoint: str = "index.js"
+    icon: str = "code"
+    position: Literal["scroll", "bottom"] = "scroll"
+    add_after_default_tabs: bool = True
+    task_controls: bool = True
+
+    def __post_init__(self) -> None:
+        if not _TAB_ID.fullmatch(self.id):
+            raise ValueError(
+                "WebTabConfig id must contain lowercase letters, digits, and single hyphens"
+            )
+        if not self.name.strip():
+            raise ValueError("WebTabConfig name is required")
+        if self.position not in {"scroll", "bottom"}:
+            raise ValueError(f"Unsupported WebTabConfig position: {self.position}")
+        entrypoint = Path(self.entrypoint)
+        if entrypoint.is_absolute() or ".." in entrypoint.parts:
+            raise ValueError("WebTabConfig entrypoint must stay inside asset_dir")
+
+    @property
+    def resolved_asset_dir(self) -> Path:
+        return Path(self.asset_dir).resolve()
+
+    @property
+    def resolved_entrypoint(self) -> Path:
+        return (self.resolved_asset_dir / self.entrypoint).resolve()
+
+
+def _task_tab_operation(kind: Literal["query", "action"], name: str):
+    if not _OPERATION_NAME.fullmatch(name):
+        raise ValueError(f"Invalid task tab operation name: {name}")
+
+    def decorate(function: Callable[..., Any]) -> Callable[..., Any]:
+        setattr(function, "__task_tab_operation__", (kind, name))
+        return function
+
+    return decorate
+
+
+def task_tab_query(name: str):
+    """Expose a read-only, explicitly named task method to its web tab."""
+
+    return _task_tab_operation("query", name)
+
+
+def task_tab_action(name: str):
+    """Expose a mutating, explicitly named task method to its web tab."""
+
+    return _task_tab_operation("action", name)
+
+
+def task_tab_operations(task: BaseTask) -> dict[tuple[str, str], Callable[..., Any]]:
+    """Return only methods explicitly allowlisted with the decorators above."""
+
+    operations: dict[tuple[str, str], Callable[..., Any]] = {}
+    # Static inspection is important here. BaseTask exposes properties such as
+    # ``frame`` whose getters wait for device capture; evaluating every member
+    # during web startup can therefore block before the server/window opens.
+    for attribute_name, descriptor in inspect.getmembers_static(task):
+        function = descriptor
+        if isinstance(function, (staticmethod, classmethod)):
+            function = function.__func__
+        function = getattr(function, "__func__", function)
+        operation = getattr(function, "__task_tab_operation__", None)
+        if operation is None:
+            continue
+        method = getattr(task, attribute_name)
+        if operation in operations:
+            raise ValueError(
+                f"Duplicate task tab operation {operation[0]}/{operation[1]} "
+                f"on {task.__class__.__name__}"
+            )
+        operations[operation] = method
+    return operations
+
+
+def call_task_tab_operation(
+    task: BaseTask,
+    kind: Literal["query", "action"],
+    name: str,
+    payload: dict[str, Any] | None = None,
+) -> Any:
+    """Invoke one allowlisted operation with either zero args or one payload."""
+
+    method = task_tab_operations(task).get((kind, name))
+    if method is None:
+        raise ValueError(f"Unknown task tab {kind}: {name}")
+    parameters = list(inspect.signature(method).parameters.values())
+    if not parameters:
+        return method()
+    if len(parameters) == 1:
+        return method(payload or {})
+    raise TypeError(
+        f"Task tab operation {task.__class__.__name__}.{method.__name__} "
+        "must accept zero arguments or one payload argument"
+    )
+
+
+class WebCustomTab(BaseTask):
+    """A non-runnable task-shaped service that owns a browser-only page."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.visible = False
+        self.support_schedule_task = False
+
+
+def configured_web_custom_tabs(web_tabs) -> list[list[str]]:
+    """Validate task-backed pages from the web-only ``web_tabs`` config."""
+
+    resolved: list[list[str]] = []
+    seen: set[tuple[str, str]] = set()
+    for entry in web_tabs or []:
+        if not isinstance(entry, (list, tuple)) or len(entry) != 2:
+            raise ValueError("Each web_tabs entry must be [module, class_name]")
+        task_module, task_class = entry
+        if not isinstance(task_module, str) or not isinstance(task_class, str):
+            raise TypeError("web_tabs module and class_name must be strings")
+        identity = (task_module, task_class)
+        if identity in seen:
+            continue
+        if importlib.util.find_spec(task_module) is None:
+            raise ModuleNotFoundError(f"Configured web tab module not found: {task_module}")
+        candidate = getattr(importlib.import_module(task_module), task_class, None)
+        if not isinstance(candidate, type) or not issubclass(candidate, WebCustomTab):
+            raise TypeError(
+                f"Configured web tab {task_module}.{task_class} must extend WebCustomTab"
+            )
+        seen.add(identity)
+        resolved.append([task_module, task_class])
+    return resolved

{ok_script-2.0.0b1 → ok_script-2.0.0b3}/ok/test/TaskTestCase.py

@@ -1,7 +1,7 @@
 import unittest
 
 from ok import Logger
-from ok.gui.common.config import Language, cfg
+from ok.ui.qt.common.config import Language, cfg
 from ok.test import init_ok, destroy_ok