卡迴圈守衛(Agent Loop 進度偵測)

電腦操作最主要的失敗模式,是 agent 不斷重複一個沒有效果的動作而耗盡預算 —— 而模型通常看不到自己的迴圈,因此必須從外部以**機械方式**偵測,藉由觀察 (tool, args, result) 三元組串流。LoopGuard 會標記三種模式:

repeat —— 相同的 (tool, args) 連續觸發多次;
ping_pong —— 兩個動作以 A-B-A-B 交替而毫無進展;
no_op —— 觀察結果(截圖/狀態摘要)從未改變。

它與步數/時間預算(無法分辨有進展的迴圈與卡住的迴圈)以及離線軌跡評估互補。純標準函式庫(collections + hashlib)、具確定性;不匯入 PySide6。

無頭 API

from je_auto_control import LoopGuard, digest_result

guard = LoopGuard(warn=8, critical=15)
for step in agent_steps:
    verdict = guard.observe(step.tool, step.args,
                            digest_result(step.screenshot))
    if verdict.level == "critical":
        break                       # 中止:卡住的迴圈
    if verdict.level == "warn":
        nudge_the_model(verdict.pattern)

observe 回傳 {pattern, level, count},其中 level 在執行長度跨過門檻後為 ok / warn / critical。count 為偵測到的執行長度。digest_result 為截圖/觀察結果(位元組或任何可 JSON 化的值)產生穩定的短雜湊。reset 清除歷史。

執行器指令

模組層級的預設守衛支撐 executor/MCP 介面,讓流程可跨步驟追蹤進度:

指令	效果
`AC_loop_guard_observe`	餵入一步;回傳 `{pattern, level, count}`。
`AC_loop_guard_reset`	清除預設守衛的歷史。

相同操作亦提供為 MCP 工具(ac_loop_guard_observe / ac_loop_guard_reset),以及 Script Builder 中 Agent 分類下的指令。