PyClickerRPA 0.4.0__tar.gz → 0.6.0__tar.gz

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.4.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, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
+Version: 0.6.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
 
@@ -66,6 +66,7 @@ pip install "PyClickerRPA[web]"   # FastAPI + uvicorn — web console
 autoclicker                          # desktop GUI (flow editor / list editor / test tab)
 autoclicker-run task.json --window "Notepad"   # headless run against a window
 autoclicker-run task.json --adb                # run against an Android device (adb)
+autoclicker-lint task.json                     # health-check a task (exit code = error count)
 autoclicker-testkit suite.json --report out.html --junit out.xml   # run a test suite
 autoclicker-web --suites-dir examples          # web console at http://127.0.0.1:8000
 ```
@@ -90,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
 
@@ -120,6 +131,30 @@ like* instead of where they *were*:
 Anything that can't be made robust falls back to the plain coordinate/fixed-wait
 step and says why in the log.
 
+## Diagnostics
+
+**Task health check** (`autoclicker-lint task.json`, or 诊断 → 任务体检 in the GUI)
+statically scans a task and separates *will definitely break* from *works but
+fragile*:
+
+- **errors** — missing template / sub-task file, image step with no template,
+  loop / goto / fail-jump target out of range, unbalanced groups. The GUI asks
+  for confirmation before running a task with errors; the CLI exit code is the
+  error count.
+- **warnings** — steps that depend on absolute coordinates, long fixed waits,
+  a match threshold low enough to hit the wrong thing, templates too small to be
+  unique. These are exactly the things the smart recorder now avoids, so the
+  check doubles as a "what should I re-record?" list.
+
+**Failure attribution.** A run captures a screenshot per step; the first
+successful run becomes the baseline timeline (`.timelines/<task>/`). When a later
+run fails, the frames are compared step by step and the report names the step
+where the screen **first diverged** from the successful run — which is usually
+*earlier* than the step that failed (step 7 can't find its button because a popup
+appeared at step 4). You get the diverging step, the per-step changed-pixel
+ratios, and a baseline|actual|heatmap image. If the screens match, it says so —
+that points at timing/flakiness rather than a UI change.
+
 ## Visual test framework (`autoclicker.testkit`)
 
 Turn automation into tests:

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PyClickerRPA
-Version: 0.4.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, a visual test framework (assertions, visual regression, HTML/JUnit reports) and a web console.
+Version: 0.6.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
 
@@ -66,6 +66,7 @@ pip install "PyClickerRPA[web]"   # FastAPI + uvicorn — web console
 autoclicker                          # desktop GUI (flow editor / list editor / test tab)
 autoclicker-run task.json --window "Notepad"   # headless run against a window
 autoclicker-run task.json --adb                # run against an Android device (adb)
+autoclicker-lint task.json                     # health-check a task (exit code = error count)
 autoclicker-testkit suite.json --report out.html --junit out.xml   # run a test suite
 autoclicker-web --suites-dir examples          # web console at http://127.0.0.1:8000
 ```
@@ -90,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
 
@@ -120,6 +131,30 @@ like* instead of where they *were*:
 Anything that can't be made robust falls back to the plain coordinate/fixed-wait
 step and says why in the log.
 
+## Diagnostics
+
+**Task health check** (`autoclicker-lint task.json`, or 诊断 → 任务体检 in the GUI)
+statically scans a task and separates *will definitely break* from *works but
+fragile*:
+
+- **errors** — missing template / sub-task file, image step with no template,
+  loop / goto / fail-jump target out of range, unbalanced groups. The GUI asks
+  for confirmation before running a task with errors; the CLI exit code is the
+  error count.
+- **warnings** — steps that depend on absolute coordinates, long fixed waits,
+  a match threshold low enough to hit the wrong thing, templates too small to be
+  unique. These are exactly the things the smart recorder now avoids, so the
+  check doubles as a "what should I re-record?" list.
+
+**Failure attribution.** A run captures a screenshot per step; the first
+successful run becomes the baseline timeline (`.timelines/<task>/`). When a later
+run fails, the frames are compared step by step and the report names the step
+where the screen **first diverged** from the successful run — which is usually
+*earlier* than the step that failed (step 7 can't find its button because a popup
+appeared at step 4). You get the diverging step, the per-step changed-pixel
+ratios, and a baseline|actual|heatmap image. If the screens match, it says so —
+that points at timing/flakiness rather than a UI change.
+
 ## Visual test framework (`autoclicker.testkit`)
 
 Turn automation into tests:

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

@@ -12,8 +12,10 @@ autoclicker/adb.py
 autoclicker/app.py
 autoclicker/capture.py
 autoclicker/clicker.py
+autoclicker/diagnose.py
 autoclicker/dpi.py
 autoclicker/expr.py
+autoclicker/lint.py
 autoclicker/matcher.py
 autoclicker/models.py
 autoclicker/ocr.py
@@ -26,6 +28,7 @@ autoclicker/gui/flow_connection.py
 autoclicker/gui/flow_editor.py
 autoclicker/gui/flow_node.py
 autoclicker/gui/hotkeys.py
+autoclicker/gui/lint_dialog.py
 autoclicker/gui/main_window.py
 autoclicker/gui/monitor.py
 autoclicker/gui/preview_label.py
@@ -54,11 +57,16 @@ autoclicker/web/static/app.js
 autoclicker/web/static/index.html
 autoclicker/web/static/style.css
 tests/test_adb.py
+tests/test_diagnose.py
+tests/test_diagnose_gui.py
 tests/test_flow_branch.py
+tests/test_lint.py
 tests/test_matcher.py
 tests/test_models.py
 tests/test_recorder_gui.py
 tests/test_runner.py
+tests/test_structured_flow.py
+tests/test_structured_gui.py
 tests/test_templatize.py
 tests/test_testkit.py
 tests/test_testkit_gui.py

{pyclickerrpa-0.4.0 → pyclickerrpa-0.6.0}/PyClickerRPA.egg-info/entry_points.txt

@@ -1,4 +1,5 @@
 [console_scripts]
+autoclicker-lint = autoclicker.lint:main
 autoclicker-run = autoclicker.run:main
 autoclicker-testkit = autoclicker.testkit.__main__:main
 autoclicker-web = autoclicker.web.__main__:main

{pyclickerrpa-0.4.0 → pyclickerrpa-0.6.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
 
@@ -28,6 +28,7 @@ pip install "PyClickerRPA[web]"   # FastAPI + uvicorn — web console
 autoclicker                          # desktop GUI (flow editor / list editor / test tab)
 autoclicker-run task.json --window "Notepad"   # headless run against a window
 autoclicker-run task.json --adb                # run against an Android device (adb)
+autoclicker-lint task.json                     # health-check a task (exit code = error count)
 autoclicker-testkit suite.json --report out.html --junit out.xml   # run a test suite
 autoclicker-web --suites-dir examples          # web console at http://127.0.0.1:8000
 ```
@@ -52,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
 
@@ -82,6 +93,30 @@ like* instead of where they *were*:
 Anything that can't be made robust falls back to the plain coordinate/fixed-wait
 step and says why in the log.
 
+## Diagnostics
+
+**Task health check** (`autoclicker-lint task.json`, or 诊断 → 任务体检 in the GUI)
+statically scans a task and separates *will definitely break* from *works but
+fragile*:
+
+- **errors** — missing template / sub-task file, image step with no template,
+  loop / goto / fail-jump target out of range, unbalanced groups. The GUI asks
+  for confirmation before running a task with errors; the CLI exit code is the
+  error count.
+- **warnings** — steps that depend on absolute coordinates, long fixed waits,
+  a match threshold low enough to hit the wrong thing, templates too small to be
+  unique. These are exactly the things the smart recorder now avoids, so the
+  check doubles as a "what should I re-record?" list.
+
+**Failure attribution.** A run captures a screenshot per step; the first
+successful run becomes the baseline timeline (`.timelines/<task>/`). When a later
+run fails, the frames are compared step by step and the report names the step
+where the screen **first diverged** from the successful run — which is usually
+*earlier* than the step that failed (step 7 can't find its button because a popup
+appeared at step 4). You get the diverging step, the per-step changed-pixel
+ratios, and a baseline|actual|heatmap image. If the screens match, it says so —
+that points at timing/flakiness rather than a UI change.
+
 ## Visual test framework (`autoclicker.testkit`)
 
 Turn automation into tests:

pyclickerrpa-0.6.0/autoclicker/diagnose.py

@@ -0,0 +1,179 @@
+"""失败归因：拿上一次成功运行的逐步截图当基准，指出画面**第一次**偏离发生在哪一步。
+
+动机：失败的步骤往往不是出问题的步骤。第 7 步找不到图，真正的原因可能是第 4 步弹出了
+公告框。日志只会告诉你"第 7 步失败"，于是排查全靠人肉翻截图。
+
+timeline 帧结构沿用 TaskRunner 的 `{"index": int, "desc": str, "png": bytes}`。
+Qt-free。
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+from dataclasses import dataclass, field
+
+import cv2
+import numpy as np
+
+from autoclicker import matcher
+
+BASELINE_ROOT = ".timelines"
+DEFAULT_TOL = 0.02      # 变化像素比例超过这个就算"画面不一样了"
+INDEX_FILE = "index.json"
+
+
+@dataclass
+class StepDiff:
+    index: int
+    desc: str
+    ratio: float        # 变化像素比例；1.0 也可能表示尺寸不一致
+    note: str = ""
+
+    @property
+    def diverged(self) -> bool:
+        return self.ratio > DEFAULT_TOL
+
+
+@dataclass
+class Attribution:
+    failed_index: int
+    diverged_index: int | None          # 画面第一次偏离的步骤；None = 没查出偏离
+    diffs: list[StepDiff] = field(default_factory=list)
+    triptych_png: bytes | None = None   # 偏离那一步的 基准|实际|热力图
+    message: str = ""
+
+
+def safe_name(name: str) -> str:
+    s = re.sub(r'[<>:"/\\|?*\s]+', "_", (name or "task").strip())
+    return s[:60] or "task"
+
+
+def baseline_dir(task_name: str, root: str = BASELINE_ROOT) -> str:
+    return os.path.join(root, safe_name(task_name))
+
+
+# ─────────────────── 持久化 ───────────────────
+
+def save_timeline(timeline: list[dict], dirname: str) -> int:
+    os.makedirs(dirname, exist_ok=True)
+    meta = []
+    for pos, f in enumerate(timeline):
+        fname = f"frame_{pos:03d}_step_{int(f['index']):03d}.png"
+        with open(os.path.join(dirname, fname), "wb") as fh:
+            fh.write(f["png"])
+        meta.append({"file": fname, "index": int(f["index"]), "desc": f.get("desc", "")})
+    with open(os.path.join(dirname, INDEX_FILE), "w", encoding="utf-8") as fh:
+        json.dump(meta, fh, ensure_ascii=False, indent=2)
+    return len(meta)
+
+
+def load_timeline(dirname: str) -> list[dict]:
+    idx = os.path.join(dirname, INDEX_FILE)
+    if not os.path.isfile(idx):
+        return []
+    with open(idx, "r", encoding="utf-8") as fh:
+        meta = json.load(fh)
+    out = []
+    for m in meta:
+        p = os.path.join(dirname, m["file"])
+        if not os.path.isfile(p):
+            continue
+        with open(p, "rb") as fh:
+            out.append({"index": int(m["index"]), "desc": m.get("desc", ""), "png": fh.read()})
+    return out
+
+
+def has_baseline(dirname: str) -> bool:
+    return os.path.isfile(os.path.join(dirname, INDEX_FILE))
+
+
+def save_baseline_if_absent(timeline: list[dict], dirname: str) -> bool:
+    """只在还没有基准时写。沿用 visual.compare_region 的"无基准就创建"惯例。
+    返回是否真的写了。"""
+    if not timeline or has_baseline(dirname):
+        return False
+    save_timeline(timeline, dirname)
+    return True
+
+
+# ─────────────────── 比对 ───────────────────
+
+def _decode(png: bytes):
+    img = cv2.imdecode(np.frombuffer(png, dtype=np.uint8), cv2.IMREAD_COLOR)
+    return None if img is None or img.size == 0 else img
+
+
+def _by_step(timeline: list[dict]) -> dict[int, dict]:
+    """按步骤下标取**首帧**。循环会让同一步出现多次，比对时只认第一次进入那一帧。"""
+    out: dict[int, dict] = {}
+    for f in timeline:
+        out.setdefault(int(f["index"]), f)
+    return out
+
+
+def compare_timelines(baseline: list[dict], actual: list[dict],
+                      tol: float = DEFAULT_TOL) -> list[StepDiff]:
+    """按步骤下标对齐两条 timeline，逐步算变化像素比例。"""
+    base_map = _by_step(baseline)
+    diffs: list[StepDiff] = []
+    for f in _by_step(actual).values():
+        i = int(f["index"])
+        desc = f.get("desc", "")
+        b = base_map.get(i)
+        if b is None:
+            diffs.append(StepDiff(i, desc, 0.0, "基准里没有这一步(流程走了不同分支?)"))
+            continue
+        a_img, b_img = _decode(f["png"]), _decode(b["png"])
+        if a_img is None or b_img is None:
+            diffs.append(StepDiff(i, desc, 0.0, "截图无法解码"))
+            continue
+        if a_img.shape != b_img.shape:
+            diffs.append(StepDiff(i, desc, 1.0,
+                                  f"画面尺寸变了 基准{b_img.shape[1]}x{b_img.shape[0]} "
+                                  f"vs 实际{a_img.shape[1]}x{a_img.shape[0]}"))
+            continue
+        diffs.append(StepDiff(i, desc, matcher.diff_ratio(a_img, b_img)))
+    diffs.sort(key=lambda d: d.index)
+    return diffs
+
+
+def _triptych_for(baseline: list[dict], actual: list[dict], index: int) -> bytes | None:
+    from autoclicker.testkit.visual import heatmap, triptych
+    b = _by_step(baseline).get(index)
+    a = _by_step(actual).get(index)
+    if b is None or a is None:
+        return None
+    b_img, a_img = _decode(b["png"]), _decode(a["png"])
+    if b_img is None or a_img is None:
+        return None
+    if b_img.shape != a_img.shape:
+        return triptych(b_img, a_img, np.zeros_like(a_img))
+    per_pixel_max = cv2.absdiff(b_img, a_img).max(axis=2)
+    return triptych(b_img, a_img, heatmap(per_pixel_max))
+
+
+def attribute(baseline: list[dict], actual: list[dict], failed_index: int,
+              tol: float = DEFAULT_TOL) -> Attribution:
+    """归因。重点在 diverged_index：画面第一次和成功那次不一样是在哪一步。"""
+    if not baseline:
+        return Attribution(failed_index, None, [], None,
+                           "没有基准时间线可比对(成功跑一次后会自动建立)")
+    diffs = compare_timelines(baseline, actual, tol)
+    diverged = next((d for d in diffs if d.ratio > tol), None)
+    if diverged is None:
+        return Attribution(failed_index, None, diffs, None,
+                           f"第 {failed_index + 1} 步失败，但逐步画面和成功那次基本一致"
+                           f"(最大偏离 {max((d.ratio for d in diffs), default=0.0):.4f})；"
+                           f"可能是时序/随机性问题，而不是界面变了")
+    png = _triptych_for(baseline, actual, diverged.index)
+    if diverged.index < failed_index:
+        msg = (f"第 {failed_index + 1} 步失败，但画面从**第 {diverged.index + 1} 步**"
+               f"就开始和成功那次不一样了(偏离 {diverged.ratio:.4f})"
+               f"{' — ' + diverged.note if diverged.note else ''}。"
+               f"先查这一步: {diverged.desc}")
+    else:
+        msg = (f"第 {failed_index + 1} 步失败，画面偏离也正是从这一步开始"
+               f"(偏离 {diverged.ratio:.4f})"
+               f"{' — ' + diverged.note if diverged.note else ''}")
+    return Attribution(failed_index, diverged.index, diffs, png, msg)

{pyclickerrpa-0.4.0 → pyclickerrpa-0.6.0}/autoclicker/gui/flow_editor.py

@@ -13,10 +13,10 @@ from collections import deque
 from PySide6.QtCore import QLineF, QPointF, Qt, Signal
 from PySide6.QtGui import QColor, QKeySequence, QPainter, QPen
 from PySide6.QtWidgets import (
-    QDialog, QGraphicsScene, QGraphicsView, QInputDialog, QMenu,
+    QDialog, QGraphicsScene, QGraphicsView, QInputDialog, QMenu, QMessageBox,
 )
 
-from autoclicker.models import Step, StepType, Task
+from autoclicker.models import Step, StepType, Task, BLOCK_TYPES, iter_steps
 from autoclicker.gui.flow_node import FlowNode, FlowPort
 from autoclicker.gui.flow_connection import FlowConnection
 
@@ -29,16 +29,13 @@ _ADD_MENU = {
     "手势": [("拖拽", StepType.Drag), ("多点拖拽", StepType.MultiDrag),
              ("捏合", StepType.Pinch), ("滚轮", StepType.Scroll)],
     "识别/变量": [("读取文字→变量", StepType.ReadText), ("设置变量", StepType.SetVar)],
-    "条件": [("条件(图片)", StepType.IfImageFound), ("条件(文字)", StepType.IfTextFound),
-             ("条件(颜色)", StepType.IfColorMatch), ("条件(图片数量)", StepType.IfImageCount),
-             ("条件(变量)", StepType.IfVar), ("If/Else", StepType.IfElse)],
+    "条件/循环": [("如果 / 否则", StepType.IfBlock), ("遍历数组", StepType.ForEach),
+                  ("重复指定次数", StepType.RepeatBlock), ("条件循环 (While)", StepType.WhileBlock),
+                  ("退出当前循环", StepType.Break), ("进入下一轮", StepType.Continue)],
     "流程": [("等待", StepType.Wait), ("随机等待", StepType.RandomWait),
              ("等待画面稳定", StepType.WaitStable),
              ("等待图片出现", StepType.WaitImage), ("等待图片消失", StepType.WaitImageGone),
-             ("循环直到", StepType.DoUntil), ("While 条件", StepType.WhileCondition),
-             ("跳转", StepType.Goto), ("调用子任务", StepType.CallSub),
-             ("分组开始", StepType.GroupBegin), ("分组结束", StepType.GroupEnd),
-             ("结束任务", StepType.Stop)],
+             ("调用子任务", StepType.CallSub), ("结束任务", StepType.Stop)],
     "窗口/高级": [("刷新/激活窗口", StepType.ActivateWindow), ("合成拖拽", StepType.MergeImage),
                   ("HTTP 请求", StepType.HttpRequest), ("运行脚本(Python)", StepType.RunScript)],
 }
@@ -143,14 +140,12 @@ class FlowEditor(QGraphicsView):
                 self._drag_line = None
             item = self.itemAt(event.position().toPoint())
             if isinstance(item, FlowPort) and item.port_type == FlowPort.INPUT and item is not self._drag_start_port:
-                conn = self.connect_nodes(self._drag_start_port, item)
-                if conn:
-                    from_node = self._drag_start_port.parentItem()
-                    to_node = item.parentItem()
-                    if to_node.pos().y() < from_node.pos().y():  # back-edge
-                        count, ok = QInputDialog.getInt(self, "循环次数", "重复次数 (-1 = 无限):", -1, -1, 99999, 1)
-                        if ok:
-                            conn.set_repeat_count(count)
+                from_node = self._drag_start_port.parentItem()
+                to_node = item.parentItem()
+                if from_node in self._reachable(to_node, set()):
+                    QMessageBox.information(self, "使用循环块", "无需连接回线：选中需要重复的步骤，右键选择「将选中步骤包进…」。")
+                else:
+                    self.connect_nodes(self._drag_start_port, item)
             self._drag_start_port = None
             return
         super().mouseReleaseEvent(event)
@@ -237,6 +232,10 @@ class FlowEditor(QGraphicsView):
             menu.addAction("删除", self._delete_selected)
         if self.selected_nodes():
             menu.addAction("复制选中节点 (Ctrl+C)", self._copy_selected)
+            wrap_menu = menu.addMenu("将选中步骤包进…")
+            for label, st in [("遍历数组", StepType.ForEach), ("重复指定次数", StepType.RepeatBlock),
+                              ("条件循环", StepType.WhileBlock), ("如果 / 否则", StepType.IfBlock)]:
+                wrap_menu.addAction(label, lambda st=st: self.wrap_selection(st))
         if self._clip and self._clip["steps"]:
             menu.addAction("粘贴 (Ctrl+V)", self._paste_clip)
         if node or conn or self.selected_nodes() or self._clip:
@@ -246,9 +245,68 @@ class FlowEditor(QGraphicsView):
         for group, items in _ADD_MENU.items():
             sub = add_menu.addMenu(group)
             for label, st in items:
-                sub.addAction(label, lambda st=st, p=scene_pos: self.add_node(Step(type=st), p))
+                sub.addAction(label, lambda st=st, p=scene_pos: self._add_configured_node(st, p))
         menu.exec(event.globalPos())
 
+    def _add_configured_node(self, step_type, pos):
+        from autoclicker.gui.task_widget import StepEditorDialog, new_step
+        dlg = StepEditorDialog(new_step(step_type), self)
+        if dlg.exec() == QDialog.Accepted:
+            self.add_node(dlg.result_step(), pos)
+
+    def wrap_selection(self, step_type):
+        from autoclicker.gui.task_widget import StepEditorDialog, new_step
+        selected = set(self.selected_nodes())
+        if not selected or step_type not in BLOCK_TYPES:
+            return
+        starts = [n for n in selected if not any(
+            c.from_port.parentItem() in selected for c in n.input_port.connections)]
+        ordered = []
+        node = starts[0] if len(starts) == 1 else None
+        while node is not None and node not in ordered:
+            ordered.append(node)
+            edges = [c for p in node.output_ports() for c in p.connections
+                     if c.to_port.parentItem() in selected]
+            node = edges[0].to_port.parentItem() if len(edges) == 1 else None
+        incoming = [c for n in selected for c in n.input_port.connections
+                    if c.from_port.parentItem() not in selected]
+        outgoing = [c for n in selected for p in n.output_ports() for c in p.connections
+                    if c.to_port.parentItem() not in selected]
+        internal = [c for n in selected for p in n.output_ports() for c in p.connections
+                    if c.to_port.parentItem() in selected]
+        linear = (len(ordered) == len(selected) and len(internal) == len(selected) - 1
+                  and all(c.to_port.parentItem() is ordered[0] for c in incoming)
+                  and all(c.from_port.parentItem() is ordered[-1] for c in outgoing)
+                  and all(c.repeat_count == 1 for c in internal + incoming + outgoing)
+                  and not any(n.is_condition() for n in selected))
+        legacy = {StepType.Loop, StepType.Goto, StepType.DoUntil, StepType.WhileCondition,
+                  StepType.IfImageFound, StepType.IfTextFound, StepType.IfColorMatch,
+                  StepType.IfImageCount, StepType.IfVar, StepType.IfElse,
+                  StepType.GroupBegin, StepType.GroupEnd}
+        if not linear or any(s.type in legacy or s.failGoto >= 0
+                             for s in iter_steps([n.step() for n in self.nodes])):
+            QMessageBox.warning(self, "无法包进块", "请选择连续、无分叉的步骤；流程中的旧式步骤号跳转须先改为条件/循环块。")
+            return
+        block = new_step(step_type)
+        block.body = [copy.deepcopy(n.step()) for n in ordered]
+        dlg = StepEditorDialog(block, self)
+        if dlg.exec() != QDialog.Accepted:
+            return
+        block = dlg.result_step()
+        pos = ordered[0].pos()
+        sources = [c.from_port for c in incoming]
+        targets = [c.to_port for c in outgoing]
+        self._scene.clearSelection()
+        for n in selected:
+            n.setSelected(True)
+        self._delete_selected()
+        wrapped = self.add_node(block, pos)
+        for source in sources:
+            self.connect_nodes(source, wrapped.input_port)
+        for target in targets:
+            self.connect_nodes(wrapped.output_port, target)
+        wrapped.setSelected(True)
+
     # ---- helpers ----
     def _node_at(self, view_pos) -> FlowNode | None:
         item = self.itemAt(view_pos)