PyClickerRPA 0.6.0__tar.gz → 0.11.0__tar.gz

{pyclickerrpa-0.6.0 → pyclickerrpa-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.6.0
+Version: 0.11.0
 Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, structured conditions and loops with array iteration, node flow editor, smart recorder, task health checks and failure attribution, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
 Author: Equinox
 License-Expression: MIT
@@ -89,6 +89,39 @@ autoclicker-web --suites-dir examples          # web console at http://127.0.0.1
   activate-window, HTTP request, run-Python-script, call sub-task, groups, and a
   **stop** step to end a run — with retry / repeat / until policies.
 
+### Black-box automation runtime
+
+- **Recognition-driven dispatch** (MAA-style): a step's `next` list is scanned
+  in order and the first candidate whose recognition gate hits is executed.
+  Set `next_timeout_ms` (>0, or -1 for unbounded) with `rate_limit_ms` to wait
+  and rescan instead of failing immediately — `next_timeout_ms: 0` (default)
+  keeps the classic single-pass behavior.
+- **Resource bundles**: `Task.resource_paths` lists bundle root directories;
+  template names that aren't real paths resolve as `<root>/image/<name>` with
+  later roots overriding earlier ones (overlay). `Task.load_bundle(dir)`
+  assembles a task from `interface.json` (`resource` roots + `pipeline` entry)
+  or a plain `task.json`. Hot reload rides the signature-checked template cache.
+- **Configurable capture/input channels**: controllers accept
+  `screencap_method` / `input_method`. Win32: `gdi_bitblt` (default),
+  `printwindow`, input `sendinput` (default) or `postmessage` (background,
+  needs a window handle; continuous gestures unsupported). ADB: `screencap`
+  (default) or `raw_gzip` (device-side gzip, steadier on slow links), input
+  `adb_input`. `minicap` / `minitouch` / `maatouch` / `desktop_dup` are
+  registered placeholders that fall back to the default with a
+  `strategy_fallback` warning — they require extra device components that are
+  not bundled (real-device behavior unverified).
+- **Target resolution** (MAA-style): an action's `target` param can be a fixed
+  region `[x, y, w, h]` (clicks its center) or a **node name** — it then clicks
+  the center of that node's latest recognition box, enabling "recognize A, then
+  click next to A". `target: true` / absent keeps the step's own targeting.
+- **Post-action freeze wait**: `post_wait_freezes: {time, target}` on any action
+  waits until the watched region stops changing before moving on — the standard
+  remedy for loading screens and animations. Unlike a standalone `wait_stable`
+  step it never fails the run; it waits up to `time` and proceeds.
+- **Human-like jitter**: click coordinates are sampled from a truncated Gaussian
+  (sigma = `randomOffset`/2, clamped to the bound) instead of a uniform spread,
+  which looks more like a real hand and is friendlier to anti-automation checks.
+
 ## Authoring (desktop GUI)
 
 Drag-and-drop **node flow graph** and an interoperable **step list**, with

{pyclickerrpa-0.6.0 → pyclickerrpa-0.11.0}/PyClickerRPA.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.6.0
+Version: 0.11.0
 Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, structured conditions and loops with array iteration, node flow editor, smart recorder, task health checks and failure attribution, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
 Author: Equinox
 License-Expression: MIT
@@ -89,6 +89,39 @@ autoclicker-web --suites-dir examples          # web console at http://127.0.0.1
   activate-window, HTTP request, run-Python-script, call sub-task, groups, and a
   **stop** step to end a run — with retry / repeat / until policies.
 
+### Black-box automation runtime
+
+- **Recognition-driven dispatch** (MAA-style): a step's `next` list is scanned
+  in order and the first candidate whose recognition gate hits is executed.
+  Set `next_timeout_ms` (>0, or -1 for unbounded) with `rate_limit_ms` to wait
+  and rescan instead of failing immediately — `next_timeout_ms: 0` (default)
+  keeps the classic single-pass behavior.
+- **Resource bundles**: `Task.resource_paths` lists bundle root directories;
+  template names that aren't real paths resolve as `<root>/image/<name>` with
+  later roots overriding earlier ones (overlay). `Task.load_bundle(dir)`
+  assembles a task from `interface.json` (`resource` roots + `pipeline` entry)
+  or a plain `task.json`. Hot reload rides the signature-checked template cache.
+- **Configurable capture/input channels**: controllers accept
+  `screencap_method` / `input_method`. Win32: `gdi_bitblt` (default),
+  `printwindow`, input `sendinput` (default) or `postmessage` (background,
+  needs a window handle; continuous gestures unsupported). ADB: `screencap`
+  (default) or `raw_gzip` (device-side gzip, steadier on slow links), input
+  `adb_input`. `minicap` / `minitouch` / `maatouch` / `desktop_dup` are
+  registered placeholders that fall back to the default with a
+  `strategy_fallback` warning — they require extra device components that are
+  not bundled (real-device behavior unverified).
+- **Target resolution** (MAA-style): an action's `target` param can be a fixed
+  region `[x, y, w, h]` (clicks its center) or a **node name** — it then clicks
+  the center of that node's latest recognition box, enabling "recognize A, then
+  click next to A". `target: true` / absent keeps the step's own targeting.
+- **Post-action freeze wait**: `post_wait_freezes: {time, target}` on any action
+  waits until the watched region stops changing before moving on — the standard
+  remedy for loading screens and animations. Unlike a standalone `wait_stable`
+  step it never fails the run; it waits up to `time` and proceeds.
+- **Human-like jitter**: click coordinates are sampled from a truncated Gaussian
+  (sigma = `randomOffset`/2, clamped to the bound) instead of a uniform spread,
+  which looks more like a real hand and is friendlier to anti-automation checks.
+
 ## Authoring (desktop GUI)
 
 Drag-and-drop **node flow graph** and an interoperable **step list**, with

{pyclickerrpa-0.6.0 → pyclickerrpa-0.11.0}/PyClickerRPA.egg-info/SOURCES.txt

@@ -8,19 +8,27 @@ PyClickerRPA.egg-info/entry_points.txt
 PyClickerRPA.egg-info/requires.txt
 PyClickerRPA.egg-info/top_level.txt
 autoclicker/__init__.py
+autoclicker/actions.py
 autoclicker/adb.py
 autoclicker/app.py
 autoclicker/capture.py
 autoclicker/clicker.py
+autoclicker/controllers.py
 autoclicker/diagnose.py
 autoclicker/dpi.py
 autoclicker/expr.py
 autoclicker/lint.py
 autoclicker/matcher.py
+autoclicker/migrations.py
 autoclicker/models.py
 autoclicker/ocr.py
+autoclicker/recognizers.py
+autoclicker/reports.py
+autoclicker/resources.py
 autoclicker/run.py
 autoclicker/runner.py
+autoclicker/sandbox.py
+autoclicker/task_queue.py
 autoclicker/templatize.py
 autoclicker/windows.py
 autoclicker/gui/__init__.py
@@ -29,15 +37,20 @@ autoclicker/gui/flow_editor.py
 autoclicker/gui/flow_node.py
 autoclicker/gui/hotkeys.py
 autoclicker/gui/lint_dialog.py
+autoclicker/gui/log_panel.py
 autoclicker/gui/main_window.py
 autoclicker/gui/monitor.py
 autoclicker/gui/preview_label.py
+autoclicker/gui/property_panel.py
 autoclicker/gui/qt_runner.py
+autoclicker/gui/queue_panel.py
 autoclicker/gui/recorder.py
 autoclicker/gui/scheduler_widget.py
 autoclicker/gui/snippet_library.py
+autoclicker/gui/step_list_widget.py
 autoclicker/gui/task_widget.py
 autoclicker/gui/testkit_widget.py
+autoclicker/gui/var_panel.py
 autoclicker/testkit/__init__.py
 autoclicker/testkit/__main__.py
 autoclicker/testkit/assertions.py
@@ -56,18 +69,32 @@ autoclicker/web/server.py
 autoclicker/web/static/app.js
 autoclicker/web/static/index.html
 autoclicker/web/static/style.css
+tests/test_actions.py
 tests/test_adb.py
+tests/test_controller_strategies.py
 tests/test_diagnose.py
 tests/test_diagnose_gui.py
+tests/test_engine_integration.py
+tests/test_engine_services.py
 tests/test_flow_branch.py
 tests/test_lint.py
+tests/test_listener_lifecycle.py
 tests/test_matcher.py
+tests/test_migrations.py
 tests/test_models.py
+tests/test_p1_blackbox.py
+tests/test_phase4_integration.py
+tests/test_platform_recognition.py
+tests/test_queue_entrypoints.py
+tests/test_recognition_dispatch.py
 tests/test_recorder_gui.py
+tests/test_resource_bundle.py
 tests/test_runner.py
+tests/test_sandbox.py
 tests/test_structured_flow.py
 tests/test_structured_gui.py
 tests/test_templatize.py
 tests/test_testkit.py
+tests/test_testkit_contracts.py
 tests/test_testkit_gui.py
 tests/test_web.py

{pyclickerrpa-0.6.0 → pyclickerrpa-0.11.0}/README.md

@@ -51,6 +51,39 @@ autoclicker-web --suites-dir examples          # web console at http://127.0.0.1
   activate-window, HTTP request, run-Python-script, call sub-task, groups, and a
   **stop** step to end a run — with retry / repeat / until policies.
 
+### Black-box automation runtime
+
+- **Recognition-driven dispatch** (MAA-style): a step's `next` list is scanned
+  in order and the first candidate whose recognition gate hits is executed.
+  Set `next_timeout_ms` (>0, or -1 for unbounded) with `rate_limit_ms` to wait
+  and rescan instead of failing immediately — `next_timeout_ms: 0` (default)
+  keeps the classic single-pass behavior.
+- **Resource bundles**: `Task.resource_paths` lists bundle root directories;
+  template names that aren't real paths resolve as `<root>/image/<name>` with
+  later roots overriding earlier ones (overlay). `Task.load_bundle(dir)`
+  assembles a task from `interface.json` (`resource` roots + `pipeline` entry)
+  or a plain `task.json`. Hot reload rides the signature-checked template cache.
+- **Configurable capture/input channels**: controllers accept
+  `screencap_method` / `input_method`. Win32: `gdi_bitblt` (default),
+  `printwindow`, input `sendinput` (default) or `postmessage` (background,
+  needs a window handle; continuous gestures unsupported). ADB: `screencap`
+  (default) or `raw_gzip` (device-side gzip, steadier on slow links), input
+  `adb_input`. `minicap` / `minitouch` / `maatouch` / `desktop_dup` are
+  registered placeholders that fall back to the default with a
+  `strategy_fallback` warning — they require extra device components that are
+  not bundled (real-device behavior unverified).
+- **Target resolution** (MAA-style): an action's `target` param can be a fixed
+  region `[x, y, w, h]` (clicks its center) or a **node name** — it then clicks
+  the center of that node's latest recognition box, enabling "recognize A, then
+  click next to A". `target: true` / absent keeps the step's own targeting.
+- **Post-action freeze wait**: `post_wait_freezes: {time, target}` on any action
+  waits until the watched region stops changing before moving on — the standard
+  remedy for loading screens and animations. Unlike a standalone `wait_stable`
+  step it never fails the run; it waits up to `time` and proceeds.
+- **Human-like jitter**: click coordinates are sampled from a truncated Gaussian
+  (sigma = `randomOffset`/2, clamped to the bound) instead of a uniform spread,
+  which looks more like a real hand and is friendlier to anti-automation checks.
+
 ## Authoring (desktop GUI)
 
 Drag-and-drop **node flow graph** and an interoperable **step list**, with

pyclickerrpa-0.11.0/autoclicker/actions.py

@@ -0,0 +1,455 @@
+"""Action registry for the task engine.
+
+Every built-in step has its own handler. Structured flow and recognition helpers
+remain on the runner; handlers lazily import its result enum to avoid a cycle.
+Third-party handlers can use enum values or custom strings, and replacing an
+existing handler requires ``replace=True``.
+"""
+from __future__ import annotations
+
+import random
+import threading
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from autoclicker.models import Step, StepType
+
+if TYPE_CHECKING:
+    from autoclicker.runner import StepResult
+
+
+@dataclass
+class ExecutionContext:
+    """Shared backends and runner helpers available to an action."""
+    runner: Any
+    screenshot: Optional[Callable] = None
+    clicker: Any = None
+    matcher: Any = None
+    vars: dict[str, str] = field(default_factory=dict)
+    log: Callable[[str], None] = lambda msg: None
+    stop_event: Any = None
+    allow_unsafe_scripts: bool = False
+    load_template: Optional[Callable] = None
+
+    def sleep_ms(self, ms: int) -> None:
+        self.runner._sleep_ms(ms)
+
+    def interp(self, template: str) -> str:
+        return self.runner._interp_required(template)
+
+
+ActionHandler = Callable[[ExecutionContext, Step], "StepResult"]
+_ACTION_REGISTRY: dict[StepType | str, ActionHandler] = {}
+_registry_lock = threading.RLock()
+_installed = False
+
+
+def _action_key(step_type: StepType | str) -> StepType | str:
+    if isinstance(step_type, StepType):
+        return step_type
+    if not isinstance(step_type, str):
+        raise TypeError("step_type must be a StepType or str")
+    # Do not call StepType(value): its legacy _missing_ maps unknowns to Wait.
+    return StepType._value2member_map_.get(step_type, step_type)
+
+
+def register_action(step_type: StepType | str, *, replace: bool = False):
+    """Register a handler; reject duplicates unless explicitly replacing them."""
+    key = _action_key(step_type)
+
+    def decorator(fn: ActionHandler) -> ActionHandler:
+        if not callable(fn):
+            raise TypeError("action handler must be callable")
+        _install()
+        with _registry_lock:
+            if key in _ACTION_REGISTRY and not replace:
+                raise ValueError(f"Action already registered: {key}")
+            _ACTION_REGISTRY[key] = fn
+        return fn
+
+    return decorator
+
+
+def registered_actions() -> list[StepType | str]:
+    """Return installed built-in and custom types in deterministic value order."""
+    _install()
+    with _registry_lock:
+        return sorted(_ACTION_REGISTRY,
+                      key=lambda t: t.value if isinstance(t, StepType) else t)
+
+
+def get_action(step_type: StepType | str) -> Optional[ActionHandler]:
+    """Return a handler, or None for an unknown type (never a Wait fallback)."""
+    key = _action_key(step_type)
+    _install()
+    with _registry_lock:
+        return _ACTION_REGISTRY.get(key)
+
+
+def exec_click_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.ClickImage)
+
+
+def exec_click_text(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_click_text(step)
+
+
+def exec_click_position(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    cx, cy = step.x, step.y
+    if step.varName == "use_var":
+        cx = int(ctx.vars.get("last_x", "0"))
+        cy = int(ctx.vars.get("last_y", "0"))
+    # P1-4: an explicit target (fixed region or another node's recognition box)
+    # overrides the literal coordinates.
+    override = ctx.runner._resolve_target(step)
+    if override is not None:
+        cx, cy = override
+    cx = ctx.runner._rand_offset(cx, step.randomOffset)
+    cy = ctx.runner._rand_offset(cy, step.randomOffset)
+    ctx.log(f"  点击 ({cx}, {cy})")
+    ctx.clicker.click(ctx.runner.target_hwnd, cx, cy)
+    return StepResult.Success
+
+
+def exec_wait(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  等待 {step.waitMs}ms")
+    ctx.sleep_ms(step.waitMs)
+    return StepResult.Success
+
+
+def exec_loop(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_if_image_found(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_if_image(step)
+
+
+def exec_if_text_found(ctx: ExecutionContext, step: Step) -> StepResult:
+    result, ctx.runner._last_condition = ctx.runner._evaluate_condition(step, StepType.IfTextFound)
+    return result
+
+
+def exec_if_else(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  If/Else 分支 (上次条件: {'true' if ctx.runner._last_condition else 'false'})")
+    return StepResult.Success
+
+
+def exec_call_sub(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    if not step.subTaskPath:
+        ctx.log("  错误: 未指定子任务路径")
+        return StepResult.Fail
+    # T1-4: the outputs mapping belongs to THIS CallSub step; the runner must
+    # not scan the task for "the first CallSub" (wrong for multiple/nested subs).
+    return ctx.runner._run_subtask(step.subTaskPath, step.params.get("outputs"))
+
+
+def exec_set_var(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    value = step.varValue
+    typed = getattr(ctx.runner.task, "variable_mode", "legacy") == "typed"
+    if typed and isinstance(value, (bool, int, float, list)):
+        pass  # native value assigned as-is
+    elif value.startswith("++"):
+        value = int(ctx.vars.get(step.varName, 0)) + 1
+        if not typed:
+            value = str(value)
+    elif value.startswith("--"):
+        value = int(ctx.vars.get(step.varName, 0)) - 1
+        if not typed:
+            value = str(value)
+    elif value.startswith("="):
+        from autoclicker import expr
+        try:
+            value = expr.safe_eval(value[1:], ctx.vars, typed=typed)
+        except Exception as e:  # noqa: BLE001 - recoverable step failure
+            ctx.log(f"  表达式错误: {e}")
+            return StepResult.Fail
+    else:
+        value = ctx.interp(value)
+    ctx.vars[step.varName] = value
+    ctx.runner.cb.var_changed(step.varName, value)
+    ctx.log(f"  变量 {step.varName} = {value}")
+    return StepResult.Success
+
+
+def exec_random_wait(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    lo, hi = step.waitMs, step.waitMsMax
+    if hi <= lo:
+        hi = lo + 1
+    actual = random.randint(lo, hi - 1)
+    ctx.log(f"  随机等待 {actual}ms (范围 {lo}~{hi})")
+    ctx.sleep_ms(actual)
+    return StepResult.Success
+
+
+def exec_key_press(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    from autoclicker.clicker import parse_vk
+    vk = parse_vk(step.keyName)
+    if vk == 0:
+        ctx.log(f'  错误: 无效按键 "{step.keyName}"')
+        return StepResult.Fail
+    ctx.log(f"  按键: {step.keyName}")
+    ctx.clicker.key_press(vk)
+    return StepResult.Success
+
+
+def exec_type_text(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    text = ctx.interp(step.text)
+    ctx.log(f'  输入文字: "{text}"')
+    ctx.clicker.type_text(text)
+    return StepResult.Success
+
+
+def exec_hotkey(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    from autoclicker.clicker import parse_vk
+    mod, vk = parse_vk(step.modifierKey), parse_vk(step.keyName)
+    if vk == 0:
+        ctx.log("  错误: 无效按键")
+        return StepResult.Fail
+    ctx.log(f"  快捷键: {step.modifierKey}+{step.keyName}")
+    ctx.clicker.hotkey(mod, vk)
+    return StepResult.Success
+
+
+def exec_long_press(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  长按 ({step.x}, {step.y}) {step.holdMs}ms")
+    ctx.clicker.long_press(ctx.runner.target_hwnd, step.x, step.y, step.holdMs)
+    return StepResult.Success
+
+
+def exec_drag(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  拖拽 ({step.x},{step.y}) → ({step.x2},{step.y2}) {step.durationMs}ms")
+    ctx.clicker.drag(ctx.runner.target_hwnd, step.x, step.y, step.x2, step.y2, step.durationMs)
+    return StepResult.Success
+
+
+def exec_pinch(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  捏合 中心({step.x},{step.y}) {step.pinchStartDist}→{step.pinchEndDist}")
+    ctx.clicker.pinch(ctx.runner.target_hwnd, step.x, step.y,
+                      step.pinchStartDist, step.pinchEndDist, step.durationMs)
+    return StepResult.Success
+
+
+def exec_wait_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.WaitImage)
+
+
+def exec_wait_image_gone(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.WaitImageGone)
+
+
+def exec_scroll(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log(f"  滚轮 ({step.x},{step.y}) {step.scrollAmount}格")
+    ctx.clicker.scroll(ctx.runner.target_hwnd, step.x, step.y, step.scrollAmount)
+    return StepResult.Success
+
+
+def exec_if_color_match(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    screen = ctx.screenshot()
+    if screen.size == 0 or step.x >= screen.shape[1] or step.y >= screen.shape[0]:
+        ctx.runner._last_condition = False
+        return StepResult.Success
+    ctx.runner._last_condition = ctx.runner._color_at_matches(
+        screen, step.x, step.y, step.targetColor, step.colorTolerance)
+    ctx.log(f"  条件(颜色): ({step.x},{step.y}) vs {step.targetColor} → "
+            f"{'true' if ctx.runner._last_condition else 'false'}")
+    return StepResult.Success
+
+
+def exec_do_until(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_merge_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_image_poll(step, StepType.MergeImage)
+
+
+def exec_multi_drag(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_multidrag(step)
+
+
+def exec_goto(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_if_image_count(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_if_image_count(step)
+
+
+def exec_if_var(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    val = ctx.vars.get(step.varName, "0")
+    ctx.runner._last_condition = ctx.runner._compare(val, step.compareOp, ctx.interp(step.compareValue))
+    ctx.log(f"  条件(变量): {step.varName}={val} {step.compareOp} {step.compareValue} → "
+            f"{'true' if ctx.runner._last_condition else 'false'}")
+    return StepResult.Success
+
+
+def exec_click_all(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_click_all(step)
+
+
+def exec_group_begin(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_group_end(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_while_condition(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    return StepResult.Success
+
+
+def exec_read_text(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_read_text(step)
+
+
+def exec_click_relative(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    bx = int(ctx.vars.get("last_x", "0")) + step.x
+    by = int(ctx.vars.get("last_y", "0")) + step.y
+    cx = ctx.runner._rand_offset(bx, step.randomOffset)
+    cy = ctx.runner._rand_offset(by, step.randomOffset)
+    ctx.log(f"  相对点击 last+({step.x},{step.y}) = ({cx}, {cy})")
+    ctx.clicker.click(ctx.runner.target_hwnd, cx, cy)
+    return StepResult.Success
+
+
+def exec_http_request(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_http(step)
+
+
+def exec_run_script(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_script(step)
+
+
+def exec_drag_image(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_drag_image(step)
+
+
+def exec_wait_stable(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_wait_stable(step)
+
+
+def exec_activate_window(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_activate_window(step)
+
+
+def exec_stop(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    ctx.log("  结束任务")
+    ctx.runner._running = False
+    return StepResult.Success
+
+
+def exec_if_block(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_repeat_block(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_while_block(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_for_each(ctx: ExecutionContext, step: Step) -> StepResult:
+    return ctx.runner._exec_block(step)
+
+
+def exec_break(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    if ctx.runner._loop_depth == 0:
+        ctx.log("  退出循环 / 下一轮只能放在循环体内")
+        return StepResult.Abort
+    return StepResult.Break
+
+
+def exec_continue(ctx: ExecutionContext, step: Step) -> StepResult:
+    from autoclicker.runner import StepResult
+    if ctx.runner._loop_depth == 0:
+        ctx.log("  退出循环 / 下一轮只能放在循环体内")
+        return StepResult.Abort
+    return StepResult.Continue
+
+
+_BUILTIN_ACTIONS: dict[StepType, ActionHandler] = {
+    StepType.ClickImage: exec_click_image,
+    StepType.ClickText: exec_click_text,
+    StepType.ClickPosition: exec_click_position,
+    StepType.Wait: exec_wait,
+    StepType.Loop: exec_loop,
+    StepType.IfImageFound: exec_if_image_found,
+    StepType.IfTextFound: exec_if_text_found,
+    StepType.IfElse: exec_if_else,
+    StepType.CallSub: exec_call_sub,
+    StepType.SetVar: exec_set_var,
+    StepType.RandomWait: exec_random_wait,
+    StepType.KeyPress: exec_key_press,
+    StepType.TypeText: exec_type_text,
+    StepType.Hotkey: exec_hotkey,
+    StepType.LongPress: exec_long_press,
+    StepType.Drag: exec_drag,
+    StepType.Pinch: exec_pinch,
+    StepType.WaitImage: exec_wait_image,
+    StepType.WaitImageGone: exec_wait_image_gone,
+    StepType.Scroll: exec_scroll,
+    StepType.IfColorMatch: exec_if_color_match,
+    StepType.DoUntil: exec_do_until,
+    StepType.MergeImage: exec_merge_image,
+    StepType.MultiDrag: exec_multi_drag,
+    StepType.Goto: exec_goto,
+    StepType.IfImageCount: exec_if_image_count,
+    StepType.IfVar: exec_if_var,
+    StepType.ClickAll: exec_click_all,
+    StepType.GroupBegin: exec_group_begin,
+    StepType.GroupEnd: exec_group_end,
+    StepType.WhileCondition: exec_while_condition,
+    StepType.ReadText: exec_read_text,
+    StepType.ClickRelative: exec_click_relative,
+    StepType.HttpRequest: exec_http_request,
+    StepType.RunScript: exec_run_script,
+    StepType.DragImage: exec_drag_image,
+    StepType.WaitStable: exec_wait_stable,
+    StepType.ActivateWindow: exec_activate_window,
+    StepType.Stop: exec_stop,
+    StepType.IfBlock: exec_if_block,
+    StepType.RepeatBlock: exec_repeat_block,
+    StepType.WhileBlock: exec_while_block,
+    StepType.ForEach: exec_for_each,
+    StepType.Break: exec_break,
+    StepType.Continue: exec_continue,
+}
+
+
+def _install() -> None:
+    """Install built-ins once, atomically, without overwriting user handlers."""
+    global _installed
+    with _registry_lock:
+        if _installed:
+            return
+        for step_type, handler in _BUILTIN_ACTIONS.items():
+            _ACTION_REGISTRY.setdefault(step_type, handler)
+        _installed = True