失敗 / 無效果動作的修復策略引擎

當動作沒有效果或落點錯誤時,代理需要一個*策略*決定下一步該試什麼——重新定位重試、微調座標、 把目標捲入視野、等待重試,或放棄並升級。self_healing / locator_repair 只修復*無法 解析*的定位器(找不到元素);當元素找到並點擊了卻無效果時,它們無能為力。loop_guard 只 *偵測*卡住的迴圈——沒有戰術選擇或退避。step_repair 正是缺少的控制器:它消費一個效果判定 (例如來自 action_effect),並驅動有界的重試迴圈,每輪選擇下一個尚未嘗試的戰術。

純標準函式庫狀態機;每個副作用——執行動作、驗證、套用戰術、睡眠——都是注入的可呼叫物件, 因此迴圈完全確定性、可在無裝置下單元測試。不匯入 PySide6。

無頭 API

from je_auto_control import (plan_repair, run_with_repair, RepairPolicy,
                             classify_effect)

# 只要規劃
plan_repair("no_op")              # ['wait_retry', 'relocate', 'nudge']
plan_repair("changed_elsewhere")  # ['escalate']

# 以注入接縫驅動迴圈
outcome = run_with_repair(
    act=lambda: click(*target),
    verify=lambda: not is_no_op(before(), after()),
    apply_tactic=apply,                 # 例如 relocate / nudge 目標
    verdict_for=lambda: classify_effect(before(), after(), action).effect,
    policy=RepairPolicy(max_attempts=3))
print(outcome.ok, outcome.tactics_used)

plan_repair 回傳某判定(字串如 no_op / changed_elsewhere 或 EffectVerdict 字典)的有序戰術,截到 max_attempts;``next_tactic`` 回傳下一個尚未試過的。 run_with_repair 執行 act 然後 verify;失敗時套用戰術直到成功或耗盡,回傳 RepairOutcome``(``ok / attempts / tactics_used / detail)。RepairPolicy 限制嘗試次數並列出允許的戰術。

執行器指令

AC_plan_repair``(``verdict / max_attempts → {count, tactics})以 MCP 工具 ac_plan_repair``(唯讀)及 Script Builder 指令 **Plan Repair Tactics**(位於 **Native UI** 分類下)形式提供。(實際的 ``run_with_repair 迴圈因接受注入可呼叫物件,由 Python 驅動。)