PyClickerRPA 0.5.0__tar.gz → 0.9.0__tar.gz

{pyclickerrpa-0.5.0 → pyclickerrpa-0.9.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.5.0
-Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, node flow editor, a smart recorder that records images instead of coordinates, task health checks and failure attribution, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
+Version: 0.9.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
 Project-URL: Homepage, https://github.com/Equinox/PyClickerRPA
@@ -44,8 +44,8 @@ ADB) input — then turn those flows into a **visual test framework** with
 assertions, visual-regression baselines, HTML/JUnit reports, and a **web console**
 for remote runs.
 
-Python/PySide6, started as a port of a Qt/C++ AutoClicker (still reads/writes the
-same `.json` task format).
+Python/PySide6, started as a port of a Qt/C++ AutoClicker. Legacy `.json` tasks
+remain supported; structured control-flow blocks are a Python-only extension.
 
 ## Install
 
@@ -91,14 +91,24 @@ autoclicker-web --suites-dir examples          # web console at http://127.0.0.1
 
 ## Authoring (desktop GUI)
 
-Drag-and-drop **node flow graph** (condition nodes have **true/false branch
-ports** for visual if-else; a terminal **stop** node ends the flow) and an
-interoperable **step list** with a full
-per-step dialog; snippet library, task
-packages (`.zip` with templates), on-preview coordinate/color picking, template
-crop, single-step test run; global hotkeys (F6 run/stop, ESC stop), scheduler,
-and an image/color **monitor/trigger** with tray icon; a **Test** tab to load and
-run visual test suites.
+Drag-and-drop **node flow graph** and an interoperable **step list**, with
+nested **If/Else**, **While**, fixed-count loops, **ForEach** arrays, and
+**Break/Continue** — no step numbers required. Double-click a block to edit its
+body or branches. Legacy condition nodes retain their true/false ports.
+
+Select consecutive steps and choose **包进… → 遍历数组** to reuse them for each
+item. Enter a custom JSON array or generate a numeric range, then reference the
+current item in text actions, assignments, and conditions. For example, iterate
+`[1,2,3,4,5,6,7,8,9,10]` with variable `server`, click **`{server}服`**, perform
+the actions, and return to the server-selection screen inside the same body.
+Enable exact text matching so `1服` does not also match `11服`. A failed action
+inside a block stops execution unless its failure policy explicitly skips it.
+
+Also includes a snippet library, task packages (`.zip` with nested templates),
+on-preview coordinate/color picking, template crop, single-step test run;
+global hotkeys (F6 run/stop, ESC stop), scheduler, and an image/color
+**monitor/trigger** with tray icon; a **Test** tab to load and run visual test
+suites.
 
 ### Smart recorder
 

{pyclickerrpa-0.5.0 → pyclickerrpa-0.9.0}/PyClickerRPA.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.5.0
-Summary: Visual UI automation & testing tool: Windows + Android(ADB) automation, robust/self-healing image matching, OCR, node flow editor, a smart recorder that records images instead of coordinates, task health checks and failure attribution, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
+Version: 0.9.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
 Project-URL: Homepage, https://github.com/Equinox/PyClickerRPA
@@ -44,8 +44,8 @@ ADB) input — then turn those flows into a **visual test framework** with
 assertions, visual-regression baselines, HTML/JUnit reports, and a **web console**
 for remote runs.
 
-Python/PySide6, started as a port of a Qt/C++ AutoClicker (still reads/writes the
-same `.json` task format).
+Python/PySide6, started as a port of a Qt/C++ AutoClicker. Legacy `.json` tasks
+remain supported; structured control-flow blocks are a Python-only extension.
 
 ## Install
 
@@ -91,14 +91,24 @@ autoclicker-web --suites-dir examples          # web console at http://127.0.0.1
 
 ## Authoring (desktop GUI)
 
-Drag-and-drop **node flow graph** (condition nodes have **true/false branch
-ports** for visual if-else; a terminal **stop** node ends the flow) and an
-interoperable **step list** with a full
-per-step dialog; snippet library, task
-packages (`.zip` with templates), on-preview coordinate/color picking, template
-crop, single-step test run; global hotkeys (F6 run/stop, ESC stop), scheduler,
-and an image/color **monitor/trigger** with tray icon; a **Test** tab to load and
-run visual test suites.
+Drag-and-drop **node flow graph** and an interoperable **step list**, with
+nested **If/Else**, **While**, fixed-count loops, **ForEach** arrays, and
+**Break/Continue** — no step numbers required. Double-click a block to edit its
+body or branches. Legacy condition nodes retain their true/false ports.
+
+Select consecutive steps and choose **包进… → 遍历数组** to reuse them for each
+item. Enter a custom JSON array or generate a numeric range, then reference the
+current item in text actions, assignments, and conditions. For example, iterate
+`[1,2,3,4,5,6,7,8,9,10]` with variable `server`, click **`{server}服`**, perform
+the actions, and return to the server-selection screen inside the same body.
+Enable exact text matching so `1服` does not also match `11服`. A failed action
+inside a block stops execution unless its failure policy explicitly skips it.
+
+Also includes a snippet library, task packages (`.zip` with nested templates),
+on-preview coordinate/color picking, template crop, single-step test run;
+global hotkeys (F6 run/stop, ESC stop), scheduler, and an image/color
+**monitor/trigger** with tray icon; a **Test** tab to load and run visual test
+suites.
 
 ### Smart recorder
 

{pyclickerrpa-0.5.0 → pyclickerrpa-0.9.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,16 +69,28 @@ 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_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_phase4_integration.py
+tests/test_platform_recognition.py
+tests/test_queue_entrypoints.py
 tests/test_recorder_gui.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.5.0 → pyclickerrpa-0.9.0}/README.md

@@ -6,8 +6,8 @@ ADB) input — then turn those flows into a **visual test framework** with
 assertions, visual-regression baselines, HTML/JUnit reports, and a **web console**
 for remote runs.
 
-Python/PySide6, started as a port of a Qt/C++ AutoClicker (still reads/writes the
-same `.json` task format).
+Python/PySide6, started as a port of a Qt/C++ AutoClicker. Legacy `.json` tasks
+remain supported; structured control-flow blocks are a Python-only extension.
 
 ## Install
 
@@ -53,14 +53,24 @@ autoclicker-web --suites-dir examples          # web console at http://127.0.0.1
 
 ## Authoring (desktop GUI)
 
-Drag-and-drop **node flow graph** (condition nodes have **true/false branch
-ports** for visual if-else; a terminal **stop** node ends the flow) and an
-interoperable **step list** with a full
-per-step dialog; snippet library, task
-packages (`.zip` with templates), on-preview coordinate/color picking, template
-crop, single-step test run; global hotkeys (F6 run/stop, ESC stop), scheduler,
-and an image/color **monitor/trigger** with tray icon; a **Test** tab to load and
-run visual test suites.
+Drag-and-drop **node flow graph** and an interoperable **step list**, with
+nested **If/Else**, **While**, fixed-count loops, **ForEach** arrays, and
+**Break/Continue** — no step numbers required. Double-click a block to edit its
+body or branches. Legacy condition nodes retain their true/false ports.
+
+Select consecutive steps and choose **包进… → 遍历数组** to reuse them for each
+item. Enter a custom JSON array or generate a numeric range, then reference the
+current item in text actions, assignments, and conditions. For example, iterate
+`[1,2,3,4,5,6,7,8,9,10]` with variable `server`, click **`{server}服`**, perform
+the actions, and return to the server-selection screen inside the same body.
+Enable exact text matching so `1服` does not also match `11服`. A failed action
+inside a block stops execution unless its failure policy explicitly skips it.
+
+Also includes a snippet library, task packages (`.zip` with nested templates),
+on-preview coordinate/color picking, template crop, single-step test run;
+global hotkeys (F6 run/stop, ESC stop), scheduler, and an image/color
+**monitor/trigger** with tray icon; a **Test** tab to load and run visual test
+suites.
 
 ### Smart recorder
 

pyclickerrpa-0.9.0/autoclicker/actions.py

@@ -0,0 +1,450 @@
+"""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"))
+    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