新功能 (2026-06-17) — 自動化工具箱

三十多個自動化原語,涵蓋輸入擬真、視覺、流程控制、觸發器、視窗管理與 檔案安全——另加「可還原(資源回收桶)刪除」與「錄製編輯器 Undo」。每項 功能都附帶 headless Python API、AC_* 執行器指令,以及視覺化 Script Builder 項目。視覺與視窗功能的 geometry / IO 操作皆可注入,因此邏輯無需 真實螢幕或視窗即可完整單元測試。

擬人化輸入

像真人一樣移動游標與打字——適合 demo、擬真自動化,以及會偵測機械式時序 的應用。路徑與延遲產生器在給定 seed 時為純函式且可重現:

from je_auto_control import move_mouse_humanized, type_text_humanized

# 曲線、eased Bezier 路徑,含 overshoot 與 jitter。
move_mouse_humanized(800, 400, duration_s=0.5,
                     motion=None, seed=None)

# 逐字打字,每字隨機微延遲。
type_text_humanized("Hello, world", base_delay=0.05,
                    jitter=0.04, pause_chance=0.1, seed=1)

執行器指令:AC_human_move、AC_human_type。

視覺

  • VLM 自然語言斷言 — assert_by_description("a green success toast") 以視覺語言模型判斷畫面是否符合描述(locate_by_description 的 verify() 搭檔)。AC_assert_vlm。

  • 捲動找元素 — scroll_until_visible(target, kind="image", direction="down", max_scrolls=10) 往某方向捲動直到樣板圖或 OCR 文字 出現,回傳 {found, coords, scrolls}。AC_scroll_to_find。

  • 區域顏色統計 — region_color_stats(source, region) 回傳區域的 average_rgb、dominant_rgb 及該色的像素占比(量化色彩空間 → 取 最多的 bucket → 平均其真實像素)。AC_region_color_stats。

  • 讀取 QR code — read_qr_codes(source, region) 以 OpenCV 的 QRCodeDetector 解碼 QR(不需新相依)。AC_read_qr。

流程控制與變數

  • 可重用巨集 — AC_define_macro 註冊具名、帶參數的動作子程序; AC_call_macro 以 ${arg} 綁定呼叫它——補上 loop / if 原語表達 不了的「可呼叫函式」。

  • 同進程平行 — AC_parallel 讓多個分支動作清單並行執行,各自在 獨立的全新 executor 上,因此分支不會在共享變數上互相 race(跨主機 DAG 的同進程版)。

  • 效能預算斷言 — assert_duration(action, max_ms) / AC_assert_duration 在區塊耗時超過預算時判失敗——銜接 profiler 與 斷言 DSL 的延遲回歸守門。

  • 讀進變數 — 把外部資料綁進流程範圍供後續 ${var} 使用: AC_ocr_to_var``(區域文字)、``AC_shell_to_var``(命令 stdout)、 ``AC_read_file_to_var``(檔案文字)、``AC_http_to_var``(GET body 或 dotted JSON path)、``AC_now_to_var``(strftime)、``AC_random_to_var (seeded int / float / choice)。

  • 變數轉換 — AC_transform_var 套用 upper / lower / strip / title / replace / regex 取出 / slice,可就地或寫入新變數——與「讀進變數」系列 搭配,在使用前清理原始文字。

  • 斷言變數 — assert_variable(value, op, expected) / AC_assert_var 在變數不滿足 eq / ne / lt / gt / contains / regex 時 判失敗(分支 if_var 的斷言 DSL 搭檔)。

觸發器與智慧等待

  • 複合觸發器 — AllOfTrigger / AnyOfTrigger / SequenceTrigger 以布林 AND、OR 或有序序列組合任何現有觸發器;子項重用各觸發器的 is_fired(),因此任何型別都能自由巢狀。

  • Cron 觸發器 — CronTrigger("0 9 * * *") 以五欄 cron 運算式觸發, 每個符合的分鐘最多一次,並可與布林觸發器組合(例如 在 09:00 且只在 圖片可見時)。

  • 更多智慧等待 — wait_until_clipboard_changes``(changed / equals / contains,``AC_wait_clipboard_change)與 wait_until_window_closed (AC_wait_window_closed)補齊 screen / pixel / region 等待。

視窗管理

  • 單一視窗擷取 — capture_window(title, output_path) 以標題解析視窗 geometry(Win32 GetWindowRect)並精確擷取其範圍。AC_capture_window。

  • 版面儲存 / 還原 — save_window_layout(path) 把每個視窗的位置快照 成 JSON;``restore_window_layout(path)`` 再把它們全部移回(方便測試 setup / teardown)。AC_save_window_layout / AC_restore_window_layout。

  • 貼齊 / 平鋪 — snap_window(title, "left") 把視窗移到螢幕一半 (left / right / top / bottom)、四分之一(四個角)或 "max"。 AC_snap_window。

檔案安全

  • 動作檔簽章 — sign_action_file 寫出 HMAC-SHA256 的 .sig sidecar;``verify_action_file`` 以常數時間驗證。設定 JE_AUTOCONTROL_REQUIRE_SIGNED_ACTIONS 時,``execute_files`` 會強制 簽章(opt-in)。AC_sign_action_file / AC_verify_action_file。

  • 動作檔加密 — encrypt_action_file / decrypt_action_file 以 Fernet(AES-128-CBC + HMAC)讓腳本內容在靜態時保密,金鑰來自通行碼或 每位使用者的 0600 金鑰。AC_encrypt_action_file / AC_decrypt_action_file。

  • 可還原刪除 — move_to_trash(path) 把檔案送進 OS 資源回收桶 (Win32 SHFileOperation undo flag / macOS Trash / Linux XDG trash, 優先使用 send2trash),讓「刪除」的檔案能還原。AC_move_to_trash。

報告與通知

  • 截圖標註 — annotate_screenshot(source, annotations, output_path) 在截圖上畫出帶標籤的方框、半透明高亮、箭頭與文字(redaction 模糊化的 標記版搭檔)。AC_annotate_screenshot。

  • 桌面通知 — notify(title, message) 顯示跨平台通知 (notify-send / osascript / PowerShell);防注入(Linux 用 argv, macOS / Windows 用從環境變數讀字串的固定腳本)。AC_notify。

GUI

  • 錄製編輯器 Undo — 每次編輯(刪步驟、trim、rescale、調整延遲、 filter)都會快照進 undo stack;**Ctrl+Z** 與 Undo 按鈕可還原前一狀態。

  • 觸發器分頁 — Combine selected 把選取的觸發器包成 AllOf / AnyOf / Sequence 複合觸發器;新增 Cron 觸發器型別。

  • 斷言分頁 — 新增 **VLM**(「畫面符合描述」)斷言型別。

  • 每個新的 AC_* 指令都可在視覺化 Script Builder 中建構。