PyClickerRPA 0.4.0__tar.gz → 0.5.0__tar.gz

{pyclickerrpa-0.4.0 → pyclickerrpa-0.5.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.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.
 Author: Equinox
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Equinox/PyClickerRPA
@@ -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
 ```
@@ -120,6 +121,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.5.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.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.
 Author: Equinox
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/Equinox/PyClickerRPA
@@ -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
 ```
@@ -120,6 +121,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.5.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,7 +57,10 @@ 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

{pyclickerrpa-0.4.0 → pyclickerrpa-0.5.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.5.0}/README.md

@@ -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
 ```
@@ -82,6 +83,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.5.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.5.0/autoclicker/gui/lint_dialog.py

@@ -0,0 +1,53 @@
+"""任务体检结果弹窗：按严重程度着色，双击一条直接跳到对应步骤。"""
+from __future__ import annotations
+
+from PySide6.QtCore import Qt, Signal
+from PySide6.QtGui import QColor
+from PySide6.QtWidgets import (
+    QDialog, QLabel, QListWidget, QListWidgetItem, QPushButton, QVBoxLayout,
+)
+
+from autoclicker.lint import ERROR, INFO, WARN, Finding, counts
+
+_COLORS = {ERROR: QColor("#c62828"), WARN: QColor("#ef6c00"), INFO: QColor("#546e7a")}
+_ICONS = {ERROR: "✖", WARN: "▲", INFO: "·"}
+
+
+class LintDialog(QDialog):
+    stepActivated = Signal(int)      # 双击某条 → 该跳到的步骤下标
+
+    def __init__(self, findings: list[Finding], step_count: int, parent=None):
+        super().__init__(parent)
+        self.setWindowTitle("任务体检")
+        self.resize(720, 420)
+        lay = QVBoxLayout(self)
+
+        c = counts(findings)
+        if not findings:
+            summary = f"没查出问题({step_count} 步)。"
+        else:
+            summary = (f"共 {step_count} 步: {c[ERROR]} 个错误(会导致跑错), "
+                       f"{c[WARN]} 处脆弱(能跑但不稳), {c[INFO]} 条提示 —— 双击可跳到该步骤")
+        lay.addWidget(QLabel(summary))
+
+        self.list = QListWidget()
+        self.list.itemDoubleClicked.connect(self._on_double)
+        for level in (ERROR, WARN, INFO):
+            for f in findings:
+                if f.level != level:
+                    continue
+                where = "整个任务" if f.index < 0 else f"步骤 {f.index + 1}"
+                it = QListWidgetItem(f"{_ICONS[level]} {where}  {f.message}")
+                it.setForeground(_COLORS[level])
+                it.setData(Qt.UserRole, f.index)
+                self.list.addItem(it)
+        lay.addWidget(self.list, 1)
+
+        close = QPushButton("关闭")
+        close.clicked.connect(self.accept)
+        lay.addWidget(close)
+
+    def _on_double(self, item: QListWidgetItem):
+        index = item.data(Qt.UserRole)
+        if index is not None and index >= 0:
+            self.stepActivated.emit(int(index))

{pyclickerrpa-0.4.0 → pyclickerrpa-0.5.0}/autoclicker/gui/main_window.py

@@ -9,6 +9,7 @@ from __future__ import annotations
 import os
 import shutil
 import tempfile
+import time
 import uuid
 import zipfile
 
@@ -64,6 +65,7 @@ class MainWindow(QMainWindow):
         self._runner = QtRunner(self)
         self._runner.logMessage.connect(self._append_log)
         self._runner.stepStarted.connect(self._on_step_started)
+        self._runner.stepCompleted.connect(self._on_step_completed)
         self._runner.matchFound.connect(
             lambda x, y, c: self._append_log(f"  → 命中 ({x},{y}) {c:.3f}"))
         self._runner.runFinished.connect(self._on_finished)
@@ -83,6 +85,7 @@ class MainWindow(QMainWindow):
         self._ocr_worker = None
         self._ocr_offset = (0, 0)  # ROI 左上角，用于把框坐标还原到全图
         self._roi_target = None    # (step, apply_fn) 框选 ROI 要写入的目标
+        self._first_fail = None    # 本次运行第一个失败的步骤下标，用于失败归因
 
         self.scheduler.runTaskRequested.connect(self._run_scheduled)
         self.snippets.insertRequested.connect(self._on_snippet_insert)
@@ -359,6 +362,12 @@ class MainWindow(QMainWindow):
         e.addAction(QAction("复制步骤到剪贴板(JSON)", self, triggered=self.copy_steps_json))
         e.addAction(QAction("从剪贴板粘贴步骤(JSON)", self, triggered=self.paste_steps_json))
 
+        d = self.menuBar().addMenu("诊断")
+        d.addAction(QAction("任务体检…", self, triggered=self.lint_current_task))
+        d.addSeparator()
+        d.addAction(QAction("用本次运行更新基准时间线", self, triggered=self.update_baseline))
+        d.addAction(QAction("打开基准目录", self, triggered=self.open_baseline_dir))
+
         mon = self.menuBar().addMenu("监视")
         mon.addAction(QAction("配置并开始监视…", self, triggered=self.monitor_configure))
         mon.addAction(QAction("停止监视", self, triggered=lambda: self._monitor.stop()))
@@ -424,12 +433,36 @@ class MainWindow(QMainWindow):
         if not task.steps:
             self._append_log("任务为空")
             return
+        if not self._lint_gate(task):
+            return
         self.log.clear()
         self._clear_vars()
         self.preview.clear_markers()
+        self._first_fail = None
         self._set_running(True)
         self._runner.start(task, target_hwnd=self._target_hwnd(),
-                           screenshot_on_fail=True, screenshot_dir=".failures")
+                           screenshot_on_fail=True, screenshot_dir=".failures",
+                           capture_timeline=True)
+
+    def _lint_gate(self, task) -> bool:
+        """致命问题(模板丢了、跳转越界…)才拦下来问一句；脆弱点只在日志提一行。"""
+        from autoclicker.lint import ERROR, counts, lint_task
+        findings = lint_task(task, base_dir=self._task_base_dir())
+        errors = [f for f in findings if f.level == ERROR]
+        c = counts(findings)
+        if errors:
+            detail = "\n".join("· " + f.format() for f in errors[:8])
+            more = f"\n…还有 {len(errors) - 8} 条" if len(errors) > 8 else ""
+            ans = QMessageBox.warning(
+                self, "体检发现致命问题",
+                f"这个任务有 {len(errors)} 个问题会导致跑错:\n\n{detail}{more}\n\n仍然运行吗?",
+                QMessageBox.Yes | QMessageBox.No, QMessageBox.No)
+            if ans != QMessageBox.Yes:
+                self._append_log(f"已取消运行: 体检有 {len(errors)} 个错误(诊断→任务体检 查看)")
+                return False
+        elif c["warn"]:
+            self._append_log(f"提示: {c['warn']} 处脆弱点(诊断→任务体检 查看)")
+        return True
 
     def debug_run(self):
         if self._runner.is_running():
@@ -478,9 +511,84 @@ class MainWindow(QMainWindow):
     def _on_step_started(self, index: int, desc: str):
         self._append_log(f"[{index + 1}] {desc}")
 
+    def _on_step_completed(self, index: int, ok: bool):
+        if not ok and self._first_fail is None:
+            self._first_fail = index
+
     def _on_finished(self):
         self._set_running(False)
         self.task_widget.clear_running_row()
+        self._diagnose_after_run()
+
+    # ---- 诊断 ----
+    def lint_current_task(self):
+        from autoclicker.lint import counts, lint_task
+        from autoclicker.gui.lint_dialog import LintDialog
+        task = self._current_task()
+        findings = lint_task(task, base_dir=self._task_base_dir())
+        dlg = LintDialog(findings, len(task.steps), self)
+        dlg.stepActivated.connect(self._goto_step)
+        c = counts(findings)
+        self._append_log(f"体检: {c['error']} 个错误, {c['warn']} 处脆弱, {c['info']} 条提示")
+        dlg.exec()
+
+    def _goto_step(self, index: int):
+        self.tabs.setCurrentWidget(self.task_widget)
+        self.task_widget.set_running_row(index)
+
+    def _task_base_dir(self) -> str:
+        """相对图片路径的解析基准：任务已保存则用它所在目录，否则用当前工作目录
+        (和 runner 把路径直接交给 cv2 的行为一致)。"""
+        return os.path.dirname(os.path.abspath(self._save_path)) if self._save_path else "."
+
+    def _baseline_dir(self) -> str:
+        from autoclicker import diagnose
+        return diagnose.baseline_dir(self._current_task().name)
+
+    def update_baseline(self):
+        from autoclicker import diagnose
+        tl = self._runner.timeline()
+        if not tl:
+            self._append_log("没有可用的时间线(先完整运行一次任务)")
+            return
+        d = self._baseline_dir()
+        n = diagnose.save_timeline(tl, d)
+        self._append_log(f"已用本次运行更新基准时间线: {d} ({n} 帧)")
+
+    def open_baseline_dir(self):
+        d = self._baseline_dir()
+        if not os.path.isdir(d):
+            self._append_log(f"基准目录还不存在: {d}(成功运行一次后会自动建立)")
+            return
+        os.startfile(d)  # noqa: S606 - Windows only tool
+
+    def _diagnose_after_run(self):
+        """成功 → 没基准就建一个；失败 → 拿基准比对，指出画面第一次偏离的步骤。"""
+        from autoclicker import diagnose
+        tl = self._runner.timeline()
+        if not tl:
+            return
+        d = self._baseline_dir()
+        if self._first_fail is None:
+            if diagnose.save_baseline_if_absent(tl, d):
+                self._append_log(f"已建立基准时间线: {d} ({len(tl)} 帧)")
+            return
+        baseline = diagnose.load_timeline(d)
+        if not baseline:
+            self._append_log("失败归因: 还没有基准时间线，成功运行一次后才能比对")
+            return
+        a = diagnose.attribute(baseline, tl, self._first_fail)
+        self._append_log(f"失败归因: {a.message}")
+        for sd in a.diffs:
+            if sd.diverged or sd.note:
+                self._append_log(f"    步骤 {sd.index + 1} 偏离 {sd.ratio:.4f} "
+                                 f"{sd.note} — {sd.desc}")
+        if a.triptych_png:
+            os.makedirs(".failures", exist_ok=True)
+            p = os.path.join(".failures", f"attribution_{int(time.time())}.png")
+            with open(p, "wb") as fh:
+                fh.write(a.triptych_png)
+            self._append_log(f"    对比图(基准|实际|热力图): {p}")
 
     def _append_log(self, msg: str):
         self.log.append(msg)
@@ -552,9 +660,11 @@ class MainWindow(QMainWindow):
         self._append_log(f"定时触发: {path}")
         self._clear_vars()
         self.preview.clear_markers()
+        self._first_fail = None
         self._set_running(True)
         self._runner.start(task, target_hwnd=self._target_hwnd(),
-                           screenshot_on_fail=True, screenshot_dir=".failures")
+                           screenshot_on_fail=True, screenshot_dir=".failures",
+                           capture_timeline=True)
 
     def _on_snippet_insert(self, steps):
         self.task_widget.insert_steps(list(steps))

{pyclickerrpa-0.4.0 → pyclickerrpa-0.5.0}/autoclicker/gui/qt_runner.py

@@ -53,9 +53,10 @@ class QtRunner(QObject):
         self._runner: TaskRunner | None = None
 
     def start(self, task: Task, target_hwnd=None, screenshot_on_fail=False, screenshot_dir=None,
-              breakpoints=None, step_mode=False) -> None:
+              breakpoints=None, step_mode=False, capture_timeline=False) -> None:
         self._runner = TaskRunner(task, target_hwnd=target_hwnd, callbacks=_SignalCallbacks(self))
         self._runner.screenshot_on_fail = screenshot_on_fail
+        self._runner.capture_timeline = capture_timeline
         if screenshot_dir:
             self._runner.screenshot_dir = screenshot_dir
         self._runner.set_breakpoints(breakpoints)
@@ -84,3 +85,7 @@ class QtRunner(QObject):
 
     def is_running(self) -> bool:
         return self._runner is not None and self._runner.is_alive()
+
+    def timeline(self) -> list[dict]:
+        """本次运行抓到的逐步截图帧（capture_timeline 开着才有）。供失败归因用。"""
+        return list(self._runner.timeline) if self._runner else []