新功能 (2026-04)

本頁說明 2026 年 4 月加入的新功能。每一項新功能都同時提供 無 GUI 的 Python API 與 對應的 GUI 介面，並已連接到 executor，可從 JSON 腳本、socket server、REST API 及 CLI 直接使用，無需撰寫額外 Python 程式碼。

剪貼簿 (Clipboard)

程式碼呼叫:

import je_auto_control as ac
ac.set_clipboard("hello")
text = ac.get_clipboard()

Action-JSON 指令:

[["AC_clipboard_set", {"text": "hello"}]]
[["AC_clipboard_get", {}]]

平台後端：Windows (ctypes + Win32)、macOS (pbcopy / pbpaste)、 Linux (xclip 或 xsel)。若無可用後端會拋出 RuntimeError。

試跑 / 逐步除錯 (Dry-run / Step Debug)

無副作用執行 action 列表，方便驗證 JSON 腳本:

from je_auto_control.utils.executor.action_executor import executor
record = executor.execute_action(actions, dry_run=True)

step_callback 可在每一條 action 執行前收到通知:

executor.execute_action(actions, step_callback=lambda a: print(a))

CLI:

python -m je_auto_control.cli run script.json --dry-run

全域熱鍵 (Windows)

綁定系統級熱鍵到 action-JSON 腳本:

from je_auto_control import default_hotkey_daemon
default_hotkey_daemon.bind("ctrl+alt+1", "scripts/greet.json")
default_hotkey_daemon.start()

支援的修飾鍵：ctrl、alt、shift、win / super / meta。按鍵：英文字母、數字、f1–f12、方向鍵、space、 enter、tab、escape 等。

macOS 與 Linux 目前在 start() 會拋出 NotImplementedError ── 採 Strategy pattern，未來可擴充對應後端。

GUI：全域熱鍵 分頁。

事件觸發器 (Triggers)

輪詢式觸發器，偵測到畫面或狀態變化時執行腳本:

from je_auto_control import default_trigger_engine, ImageAppearsTrigger
default_trigger_engine.add(ImageAppearsTrigger(
    trigger_id="", script_path="scripts/click_ok.json",
    image_path="templates/ok_button.png", threshold=0.85,
    repeat=True,
))
default_trigger_engine.start()

可用類型：

ImageAppearsTrigger — 螢幕上偵測模板影像
WindowAppearsTrigger — 視窗標題包含子字串
PixelColorTrigger — 某座標像素顏色在容差內
FilePathTrigger — 監看檔案 mtime 變化

GUI：事件觸發器 分頁。

Cron 排程 

五欄位 cron (minute hour day-of-month month day-of-week)，支援 *、逗號列表、*/step 步進、start-stop 範圍:

from je_auto_control import default_scheduler
job = default_scheduler.add_cron_job(
    script_path="scripts/daily.json",
    cron_expression="0 9 * * 1-5",   # 週一到週五 09:00
)
default_scheduler.start()

interval 與 cron 排程可同時存在，可由 job.is_cron 判斷類型。 GUI：排程器 分頁新增 cron/interval 切換。

外掛載入器 (Plugin Loader)

外掛檔案為任何定義頂層 AC_* callable 的 .py，每個都會成為新的 executor 指令:

# my_plugins/greeting.py
def AC_greet(args=None):
    return f"hello, {args['name']}"

from je_auto_control import (
    load_plugin_directory, register_plugin_commands,
)
commands = load_plugin_directory("my_plugins/")
register_plugin_commands(commands)

GUI：外掛分頁，可選擇目錄一鍵載入。

Warning

外掛檔案會直接執行任意 Python 程式。請務必只載入自己信任的目錄。

REST API 伺服器 

純 stdlib HTTP server，公開 executor 與 scheduler:

from je_auto_control import start_rest_api_server
server = start_rest_api_server(host="127.0.0.1", port=9939)

端點：

GET /health
GET /jobs
POST /execute (body: {"actions": [...]})

GUI：Socket 伺服器 分頁新增獨立的 REST 區塊。

Note

預設綁定 127.0.0.1 (符合 CLAUDE.md 規範)。只有在網路邊界已做好身分驗證時才綁定 0.0.0.0。

CLI 子指令介面 

以 headless API 為基礎的輕量 CLI:

python -m je_auto_control.cli run script.json
python -m je_auto_control.cli run script.json --var name=alice --dry-run
python -m je_auto_control.cli list-jobs
python -m je_auto_control.cli start-server --port 9938
python -m je_auto_control.cli start-rest --port 9939

--var name=value 優先以 JSON 解析 (count=10 會變 int)，失敗時當作字串。

可關閉分頁 + 選單列 

主視窗改為 QMainWindow + 選單列：

File → 開啟腳本 / 結束
View → Tabs → 每個分頁可勾選顯示或隱藏
Tools → 啟動熱鍵 / 排程 / 觸發器服務
Language → 切換語言
Help → 關於

點擊分頁的 ✕ 即可關閉，之後可從 View → Tabs 恢復。

OCR 螢幕文字辨識 

以 Tesseract 為後端的文字定位。適用於沒有穩定 Accessibility 名稱、也不方便擷取模板影像的按鈕或標籤:

import je_auto_control as ac

matches = ac.find_text_matches("Submit")
cx, cy = ac.locate_text_center("Submit")
ac.click_text("Submit")
ac.wait_for_text("載入完成", timeout=15.0)

若 Tesseract 不在 PATH 中:

ac.set_tesseract_cmd(r"C:\Program Files\Tesseract-OCR\tesseract.exe")

Action-JSON 指令：AC_locate_text、AC_click_text、 AC_wait_text。

Accessibility 元件搜尋 

透過作業系統無障礙樹查詢控制項（Windows UIA 透過 uiautomation； macOS AX），支援依名稱 / 角色 / 應用程式過濾:

import je_auto_control as ac

elements = ac.list_accessibility_elements(app_name="Calculator")
ok = ac.find_accessibility_element(name="OK", role="Button")
ac.click_accessibility_element(name="OK", app_name="Calculator")

當前平台若沒有可用後端會拋出 AccessibilityNotAvailableError。 Action-JSON 指令：AC_a11y_list、AC_a11y_find、 AC_a11y_click。GUI：Accessibility 分頁。

VLM（AI）元件定位 

當模板匹配與 Accessibility 都無法找到目標時，可用自然語言描述元件，交給視覺語言模型回傳像素座標:

import je_auto_control as ac

x, y = ac.locate_by_description("綠色的 Submit 按鈕")
ac.click_by_description(
    "Cookie 橫幅中的『全部接受』按鈕",
    screen_region=[0, 800, 1920, 1080],   # 可選：只在此區域搜尋
)

後端（延遲載入，import je_auto_control 時不會引入）：

Anthropic (anthropic SDK，ANTHROPIC_API_KEY)
OpenAI (openai SDK，OPENAI_API_KEY)

環境變數（金鑰不會被記錄或寫入磁碟）：

ANTHROPIC_API_KEY / OPENAI_API_KEY
AUTOCONTROL_VLM_BACKEND=anthropic|openai
AUTOCONTROL_VLM_MODEL=<model-id>

Action-JSON 指令：AC_vlm_locate、AC_vlm_click。GUI： AI Locator 分頁。

執行歷史 + 錯誤截圖附件 

排程器、觸發器、熱鍵守護程序、REST API 與 GUI 手動回放的每一次執行都會被寫入 ``~/.je_auto_control/history.db``（SQLite）。失敗時會自動擷取螢幕截圖並附到該筆紀錄上:

from je_auto_control import default_history_store

for run in default_history_store.list_runs(limit=20):
    print(run.id, run.source, run.status, run.artifact_path)

截圖檔存於 ~/.je_auto_control/artifacts/，相關紀錄被 prune 或整個歷史被清除時會一併刪除。GUI：Run History 分頁 — 雙擊截圖欄位可開啟 OS 預覽。

OCR — 區域 dump 與 regex 搜尋 

原本 OCR 模組只支援字串／精確比對，新增兩個 API 補強其他常見場景:

import je_auto_control as ac

# 把區域（或整個螢幕）內辨識到的所有文字傾倒出來
for match in ac.read_text_in_region(region=[0, 0, 800, 600]):
    print(match.text, match.center, match.confidence)

# Regex 搜尋 — 適合內容會變的文字（訂單編號、錯誤代碼）
for match in ac.find_text_regex(r"Order#\d+"):
    print(match.text, match.center)

# 也接受 compiled pattern 與 flags
import re
ac.find_text_regex(re.compile(r"foo", re.IGNORECASE))

Action-JSON 指令:

[["AC_read_text_in_region", {"region": [0, 0, 800, 600]}]]
[["AC_find_text_regex", {"pattern": "Order#\\d+"}]]

GUI：OCR Reader 分頁。可用既有的選取 overlay 圈出區域（留空則整螢幕），設定語言／最低信心度後按 抓取區域全部文字 或 用 regex 搜尋。結果以 JSON 列出，含文字、邊界框、信心度。

執行期變數與資料驅動流程控制 

過去 script_vars.interpolate 只能在執行前一次性把 ${var} 取代成靜態 mapping 中的值，腳本沒辦法在執行時修改狀態。VariableScope 是 executor 暴露給流程控制指令的執行期 mapping，讓它們能讀寫與 runtime interpolator 相同的容器。

executor 現在改成「每次呼叫」才解析 ${var} placeholder（不會事先攤平），所以巢狀的 body / then / else 清單會保留 placeholder，每次重複執行時重新繫結 — 因此 AC_for_each 走訪 list 時，body 內看到的就是當前的元素。

import je_auto_control as ac
from je_auto_control.utils.executor.action_executor import executor

executor.execute_action([
    ["AC_set_var", {"name": "items", "value": ["alpha", "beta"]}],
    ["AC_set_var", {"name": "i", "value": 0}],
    ["AC_for_each", {
        "items": "${items}", "as": "name",
        "body": [
            ["AC_inc_var", {"name": "i"}],
            ["AC_if_var", {
                "name": "i", "op": "ge", "value": 2,
                "then": [["AC_break"]], "else": [],
            }],
        ],
    }],
])

AC_if_var``(與 ``AC_while_var)的比較運算子：eq、ne、lt、 le、gt、ge、contains、startswith、endswith。

AC_while_var 在變數比較成立時持續執行 body。每輪迭代前都會對當前 scope 重新判斷條件,因此會變動該變數的 body(例如 AC_inc_var)能讓迴圈終止;``max_iter``(預設 1000)為條件永不為假時的安全上限。AC_break / AC_continue 與一般迴圈相同:

executor.execute_action([
    ["AC_set_var", {"name": "i", "value": 0}],
    ["AC_while_var", {
        "name": "i", "op": "lt", "value": 5,
        "body": [["AC_inc_var", {"name": "i"}]],
    }],
])

AC_try 提供 try / catch / finally。body 失敗時改走 catch 分支而非中止腳本;``finally`` 一律執行(成功、捕捉到錯誤,或在 reraise / 迴圈 break、continue 穿透時皆然)。錯誤文字會暴露到 error_var 供 catch 分支檢視,``reraise=true`` 會在清理後重新拋出:

executor.execute_action([
    ["AC_try", {
        "body": [["AC_click_image", {"image": "dialog_ok.png"}]],
        "catch": [["AC_set_var", {"name": "dismissed", "value": False}]],
        "finally": [["AC_screenshot", {"file_path": "after.png"}]],
        "error_var": "err",
    }],
])

Action-JSON 指令：AC_set_var、AC_get_var、AC_inc_var、 AC_if_var、AC_for_each、AC_while_var、AC_try。

GUI：Variables 分頁 — 即時檢視 executor.variables，可單筆設定、JSON 整批 seed、清空，反映 AC_set_var / AC_for_each 在執行期的變動。

LLM 動作規劃器 

把一段中／英文描述交給 LLM（預設 Anthropic Claude），生成驗證過的 AC_* 動作清單。輸出採寬鬆解析（會剝 code fence、從散文中抽出第一個 JSON array），再用 executor 同樣的 schema 驗證，所以結果可以直接餵給 execute_action:

import je_auto_control as ac
from je_auto_control.utils.executor.action_executor import executor

actions = ac.plan_actions(
    "點擊 Submit 按鈕，然後輸入 'done' 並儲存",
    known_commands=executor.known_commands(),
)
executor.execute_action(actions)

# 或者一行做完：
ac.run_from_description("開記事本，輸入 hello", executor=executor)

後端選擇對齊 vision.backends：

Anthropic（anthropic SDK，ANTHROPIC_API_KEY）— 預設
用 AUTOCONTROL_LLM_BACKEND、AUTOCONTROL_LLM_MODEL 覆寫

Action-JSON 指令：AC_llm_plan、AC_llm_run。

GUI：LLM Planner 分頁。描述輸入框、QThread 背景執行的 Plan 按鈕、預覽指令清單、以及 Run plan 按鈕 — 長時間呼叫不會卡 UI。

遠端桌面（Host + Viewer）

把本機畫面串流給別人看／控制，或觀看並控制別人的機器 — 雙向都有 headless API 與 GUI 分頁。

協定是 raw TCP 上的長度前綴框架（沒有額外相依），先做一輪 HMAC-SHA256 challenge/response 認證；認證失敗的 viewer 在看到任何畫面前就被踢掉。 JPEG frame 依設定的 FPS／品質產生，透過共享 latest-frame slot 廣播給通過認證的 viewers，慢的 viewer 只會掉 frame 而不會卡其他人。Viewer 輸入訊息是 JSON，host 端用允許清單驗證後才透過既有 mouse／keyboard wrapper 派送。

Headless host（被別人遠端）:

from je_auto_control import RemoteDesktopHost

host = RemoteDesktopHost(
    token="hunter2",          # 共用密鑰（HMAC key）
    bind="127.0.0.1",         # 預設值；要對外請走 SSH tunnel
                              # 或可信的 VPN
    port=0,                   # 0 = 自動指派
    fps=10, quality=70,
)
host.start()
print("listening on", host.port, "viewers:", host.connected_clients)
# ...
host.stop()

Headless viewer（控制別人）:

from je_auto_control import RemoteDesktopViewer

viewer = RemoteDesktopViewer(
    host="10.0.0.5", port=51234, token="hunter2",
    on_frame=lambda jpeg_bytes: ...,   # 顯示或存檔
)
viewer.connect()
viewer.send_input({"action": "mouse_move", "x": 100, "y": 200})
viewer.send_input({"action": "type", "text": "hello"})
viewer.disconnect()

輸入訊息允許清單（host 派送前驗證）：

mouse_move {x, y}
mouse_click {x?, y?, button}
mouse_press / mouse_release {button}
mouse_scroll {x?, y?, amount}
key_press / key_release {keycode}
type {text}
ping

Action-JSON 指令（使用 utils.remote_desktop.registry 的單例）:

AC_start_remote_host       # token, bind, port, fps, quality, region
AC_stop_remote_host
AC_remote_host_status      # → {running, port, connected_clients}

AC_remote_connect          # host, port, token, timeout
AC_remote_disconnect
AC_remote_viewer_status    # → {connected}
AC_remote_send_input       # action: {...}

GUI：Remote Desktop分頁預設打開的是 快速連線 （AnyDesk 風格）— 一邊是超大本機 Host ID，另一邊一個輸入框接受 host:port、 ws://、wss:// 或 9 位數 Host ID，搭配連線與 開始被遠端 兩個主要按鈕。近期連線會跨 session 記住。進階的逐傳輸子分頁（既有 TCP / WS host + viewer、WebRTC host + viewer 含手動 SDP / 自訂編碼器 / TLS pinning）仍只差一個 click。WebRTC 子分頁採延遲載入,沒裝 [webrtc] extra 也能正常開啟整個分頁。

Warning

取得 host:port 與 token 的人，等同擁有本機完整滑鼠／鍵盤控制權。預設只綁 127.0.0.1；要對外暴露請務必搭配 SSH tunnel 或 TLS 前端。Token 是唯一防線 — 請當作密碼來保管。

遠端桌面 — 快速連線 + Phase 4／5 強化 

快速連線的 headless API 

撐起 GUI 輸入框的 transport coordinator 也對外開放，腳本可以走同樣的解析路徑:

from je_auto_control import parse_remote_desktop_target
parse_remote_desktop_target("192.168.1.10:5555")
# ConnectTarget(kind='tcp', host='192.168.1.10', port=5555, ...)
parse_remote_desktop_target("ws://hub:8765/desk")
# ConnectTarget(kind='ws', host='hub', port=8765, path='/desk')
parse_remote_desktop_target("123-456-789")
# ConnectTarget(kind='webrtc_id', host_id='123456789')

連線審批 + 僅檢視模式 

可選的 callback 守住每一個 incoming session，AnyDesk 風格。回傳 "view_only" admit 但丟掉 viewer 的 INPUT；回傳 falsy（或 raise）就送 AUTH_FAIL "rejected by host":

from je_auto_control import RemoteDesktopHost, PendingViewer

def gate(p: PendingViewer) -> str:
    if p.address[0].startswith("10."):
        return "view_only"
    return "full"  # 或 True

host = RemoteDesktopHost(token="tok", on_pending_viewer=gate)

IP 白名單（CIDR + 單一 IP）

在 TLS / auth 之前就拒絕範圍外的對端，攻擊者連探測都不行:

host = RemoteDesktopHost(
    token="tok",
    ip_allowlist=["10.0.0.0/8", "192.168.1.100"],
)

一次性分享碼 

額外的 token，認證成功一次後自毀；客服支援流程很好用:

host = RemoteDesktopHost(token="tok", single_use_tokens=["abc123"])
host.add_single_use_token("9k4ndx")    # 運行時加
host.revoke_single_use_token("abc123") # 還沒被用就先撤銷

TOTP 2FA（RFC 6238，純 stdlib）

在 token 之上加一層 6 位數 OTP；host 接受 ±1 時間步的 clock drift:

from je_auto_control.utils.remote_desktop.totp import (
    generate_secret, generate_code, provisioning_uri,
)
secret = generate_secret()
# 給 Google Authenticator / Authy / 1Password QR code 用的 otpauth:// URI
print(provisioning_uri(secret, account="alice"))

host = RemoteDesktopHost(token="tok", totp_secret=secret)
viewer = RemoteDesktopViewer(
    host=..., token="tok", totp_code=generate_code(secret),
)

多螢幕選擇 

指定某一個螢幕擷取，而非合併虛擬桌面:

from je_auto_control import list_host_monitors, RemoteDesktopHost
print(list_host_monitors())
# [{'index': 0, 'is_combined': True, ...},
#  {'index': 1, 'left': 0,   'top': 0, ...},
#  {'index': 2, 'left': 1920, ...}]
host = RemoteDesktopHost(token="tok", monitor_index=1)

遠端游標 overlay 

host 每秒 30 Hz 廣播 cursor 位置（靜止桌面去重）；viewer 的彈出視窗會在 JPEG 串流上疊一個箭頭，看得到 host 滑鼠位置。可用 enable_cursor_broadcast=False 關掉。

多 viewer 協作游標 + 文字 chat 

兩個新 message type（CHAT 與 CURSOR 帶 viewer_id）。搭配 MultiViewerHost 把一個 viewer 的指標 echo 給其他人；chat channel 給操作者之間臨時對話用:

host = RemoteDesktopHost(
    token="tok",
    on_chat=lambda sender, text: print(sender, ":", text),
)
host.broadcast_chat("session starts in 30s")
host.broadcast_viewer_cursor("alice", 200, 300)

viewer = RemoteDesktopViewer(
    host=...,
    on_chat=lambda s, t: ...,
    on_viewer_cursor=lambda vid, x, y: ...,
)
viewer.send_chat("ack")

相對滑鼠模式（FPS / CAD）

新輸入 action 送 delta 而非絕對座標:

viewer.send_input(
    {"action": "mouse_move_relative", "dx": 5, "dy": -3},
)

動態擷取 

capture loop 會 hash 每張編碼後的 JPEG；重複 frame 直接跳過，所以靜止桌面幾乎零頻寬。新 viewer 在 auth 後立即拿到最新 frame，不會看到一片黑。

即時統計 

FPS / kbps / 累計 — 3 秒滑動視窗:

viewer.stats()
# {'fps': 24.3, 'kbps': 4801.2, 'frames': 720.0,
#  'bytes': 1.8e7, 'uptime': 30.2}

JPEG 序列錄影（不需要 PyAV）

TCP path 的 session 錄影：每張 frame 寫到磁碟，再加一份 manifest.json 讓播放器可以原速重放:

from je_auto_control.utils.remote_desktop.jpeg_recorder import (
    JpegSequenceRecorder,
)
rec = JpegSequenceRecorder("~/recordings/2026-05-23")
rec.start()
viewer = RemoteDesktopViewer(host=..., on_frame=rec.record_frame)
# ... session ...
rec.stop()  # 在 .jpg 旁邊寫出 manifest.json

TCP relay（WebRTC fallback）

當 P2P 失敗（嚴格 NAT、行動電信 CGNAT、旅館 Wi-Fi）兩端都向 relay 主動連線、交換一個 32-byte session ID，relay 在中間互轉 bytes。同一模組附 encode_handshake(role, session_id) 給 client 用:

from je_auto_control.utils.remote_desktop.relay import RelayServer
relay = RelayServer(bind="0.0.0.0", port=9000)
relay.start()

服務安裝器（無人值守 host）

python -m je_auto_control.utils.remote_desktop.host_service ... 提供 configure / init / run，以及每個平台的安裝指令： install-windows-service / uninstall-windows-service``（需 pywin32）、``generate-launchd / uninstall-launchd、 generate-systemd / uninstall-systemd。

遠端桌面 — 加密傳輸、音訊、剪貼簿、檔案傳輸 

Host ID 握手 

每台 host 現在都有一個穩定的 9 位數字 ID，存在 ~/.je_auto_control/remote_host_id，重啟後仍是同一個。ID 在 AUTH_OK 訊息內回傳（只有通過認證的 viewer 才看得到），viewer 可以指定 expected_host_id 驗證，避免「同樣位址但是別的程序」的冒充攻擊:

from je_auto_control import RemoteDesktopHost, RemoteDesktopViewer
host = RemoteDesktopHost(token="tok")
print(host.host_id)        # 例如 "123456789"

viewer = RemoteDesktopViewer(
    host="10.0.0.5", port=51234, token="tok",
    expected_host_id="123456789",
)
viewer.connect()           # 不一致就拋 AuthenticationError

另外提供 format_host_id("123456789") == "123 456 789" 與 parse_host_id("123 456 789") == "123456789" 助手。GUI 會顯示分組過的 ID 並有複製按鈕；viewer 端的輸入欄接受常見的空白／破折號。

TLS 

RemoteDesktopHost 與 RemoteDesktopViewer 都接受 ssl.SSLContext 參數。設定後，host 會把每條接受的連線在伺服器側套上 TLS；viewer 在客戶端側套上。失敗的握手會被記錄並關閉，不會進到 connected client 計數:

import ssl
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ctx.load_cert_chain("cert.pem", "key.pem")
host = RemoteDesktopHost(token="tok", ssl_context=ctx)

client_ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
client_ctx.load_verify_locations("cert.pem")
viewer = RemoteDesktopViewer(host=..., ssl_context=client_ctx)

自簽憑證 loopback 測試時，把 ctx.check_hostname = False 與 ctx.verify_mode = ssl.CERT_NONE 設在 client context 上。GUI host 分頁有 TLS 憑證／私鑰的檔案選擇器；viewer 分頁有 忽略憑證驗證 的 checkbox 配自簽用。

WebSocket 傳輸 

新增 WebSocketDesktopHost / WebSocketDesktopViewer，用 RFC 6455 BINARY frame 傳同樣的 typed message。實作放在 in-tree（沒有額外相依）；每個 application message 對應一個完整的 WS frame，所以不需要重組機制。同一個 ssl_context 也是 wss:// 的開關:

from je_auto_control import (
    WebSocketDesktopHost, WebSocketDesktopViewer,
)
host = WebSocketDesktopHost(token="tok", ssl_context=ctx)   # wss://
viewer = WebSocketDesktopViewer(
    host="example.com", port=443, token="tok",
    ssl_context=client_ctx, path="/rd",
)

為什麼用 WS：穿牆友善、容易接反向代理、跟瀏覽器 viewer 相容。GUI viewer 的傳輸下拉（TCP / WebSocket / TLS / WSS）會自動選對應的 class。

音訊串流 

新增 AUDIO 訊息類型，攜帶 16-bit signed PCM 區塊（預設 16 kHz mono，每塊 50 ms / 1600 bytes）。sounddevice 為 optional 相依，延遲載入；沒裝就 host 端音訊回報停用且整個 host 仍能運作:

from je_auto_control.utils.remote_desktop import AudioCaptureConfig
host = RemoteDesktopHost(
    token="tok",
    audio_config=AudioCaptureConfig(
        enabled=True, device=None,             # 預設 mic
        sample_rate=16000, channels=1,
    ),
)

from je_auto_control.utils.remote_desktop import AudioPlayer
player = AudioPlayer(); player.start()
viewer = RemoteDesktopViewer(host=..., on_audio=player.play)

Host 把每塊抓到的音訊透過每個 client 一個有上限的 deque（~2.5 秒緩衝）廣播出去；慢的 viewer 只會丟掉舊的音訊塊，不會卡到大家的擷取執行緒。如果要抓系統聲音（而非 mic），用 device index 指定 — Win 是 WASAPI loopback、Linux 是 PulseAudio monitor source、macOS 要 BlackHole 之類。GUI：Host 分頁的 串流系統音訊，Viewer 分頁的 播放接收的音訊。

剪貼簿同步（文字 + 圖片）

新增 CLIPBOARD 訊息類型，payload 是 JSON envelope，方便日後加新類別不用動到 framing：

{"kind": "text", "text": "..."}
{"kind": "image", "format": "png", "data_b64": "..."}

utils/clipboard/clipboard.py 補上 get_clipboard_image / set_clipboard_image；Windows 用 ctypes 寫 CF_DIB（Pillow 把 PNG 轉成 BMP 再去掉 14 byte file header 變成 DIB），Linux 走 xclip -t image/png，macOS get 走 Pillow ImageGrab、set 暫時拋 NotImplemented 等 PyObjC backend。同步是「明確呼叫」的（避免雙向 auto-poll 造成 paste 迴圈）:

# Viewer 把本機剪貼簿送到 host
viewer.send_clipboard_text("hello")
viewer.send_clipboard_image(open("logo.png", "rb").read())

# Host 把本機剪貼簿送到所有 viewers
host.broadcast_clipboard_text("greetings")
host.broadcast_clipboard_image(png_bytes)

# Viewer 接收回 callback，自己決定要不要 paste
viewer = RemoteDesktopViewer(
    host=..., on_clipboard=lambda kind, data: ...,
)

GUI：Viewer 分頁有 把本機剪貼簿文字送到 Host 按鈕；host 收到後透過上述 helpers 套用到本機剪貼簿。

檔案傳輸 + 進度 

三個新訊息組成一次傳輸：

FILE_BEGIN — JSON {transfer_id, dest_path, size}
FILE_CHUNK — 36-byte ASCII transfer id + 原始 payload
FILE_END — JSON {transfer_id, status, error?}

雙向、分塊（256 KiB / chunk）、沒有總大小上限、**沒有目的路徑限制**（拿到 token 就視為信任使用者）。進度由兩端各自本地計算，不需要額外的 wire 訊息:

from je_auto_control.utils.remote_desktop import (
    FileReceiver, RemoteDesktopHost, RemoteDesktopViewer, send_file,
)

# Viewer 上傳到 host
viewer.send_file("local.bin", "/tmp/uploaded.bin",
                 on_progress=lambda tid, done, total: print(done, total))

# Host 下發到所有 viewer（viewer 需要設一個 FileReceiver 來收）
viewer.set_file_receiver(FileReceiver(
    on_progress=..., on_complete=...,
))
host.send_file_to_viewers("local.bin", "/tmp/from_host.bin")

GUI：傳送檔案… 按鈕開啟檔案選擇器 + 目的路徑提示，上傳跑在 QThread 上，底下 QProgressBar 綁到 sender 的 progress 事件。Frame display widget 也接受 dragEnter／drop 拖放本機檔案，丟進去就走同一個流程上傳。

Warning

路徑無限制、大小無上限。任何拿到 token 的人都能把任意檔案寫到任意位置（覆蓋 C:\\Windows\\System32\\*.dll 都可能），也能塞滿磁碟。Token 持有者必須等同信任使用者；要更嚴格的話請自行繼承 FileReceiver 在 handle_begin 內驗證 dest_path。

遠端桌面 — AnyDesk 風格彈出視窗 

Viewer 分頁不再把遠端畫面內嵌在面板裡 — viewer 認證成功後,會另外開啟一個獨立的 RemoteScreenWindow 顯示遠端桌面, 面板本身只剩下連線卡片 + 控制元件。關閉 popup 視窗的 ✕ 按鈕會自動斷線,跟 AnyDesk 的 session 視窗體驗一致。

新增模組:je_auto_control/gui/remote_desktop/remote_screen_window.py
內部包一個 _FrameDisplay 並重新發送其 mouse / keyboard / drag-and-drop / annotation signals,所以面板仍然只需要訂閱單一 signal source。
視窗底部保留檔案傳輸進度條 / 標籤,沒有傳輸時隱藏。
TCP _ViewerPanel 與 WebRTC _WebRTCViewerPanel 都會在 connect / auth_ok 時開啟此視窗,在 disconnect / stop 時關閉。

設計動機: 原先的版面在垂直方向擠得很滿:畫面顯示 + 連線卡 + 折疊區 + action row + stats + sparkline + 傳輸進度 + 狀態列全部往下堆。把遠端畫面拉到獨立視窗後,操作者多了一個真正的工作區,控制面板也不用再跟畫面爭空間。

遠端桌面 — 自適應的子分頁尺寸 

每一個 Remote Desktop 子分頁外面都改包了一層 QScrollArea 並設 setWidgetResizable(True)。包裝邏輯放在 gui/remote_desktop/tab.py``(``_wrap_in_scroll_area helper)。

視窗縮小時:出現垂直捲軸,WebRTC 那種密集分頁不會被切到。
視窗放大(4K)時:內部 panel 會跟著 viewport 橫向延展,連線卡與 session 表格會撐滿到右邊緣,不再縮成左上角一坨。
各 panel 底部仍有 addStretch(1),額外空間時內容會被推到上方,版面不會下垂。

WebRTC viewer 分頁裡比較少用的群組(Manual SDP、Remote Files、 Sync)也透過新的 _wrap_collapsed 包成預設摺疊的 _CollapsibleSection,初次顯示高度大約砍半。

WebRTC host 的 session 表格原本固定為 setMaximumHeight(140) ,改成 setMinimumHeight(140) — 維持原本 140 px 的起始高度, 但在大螢幕上不再被卡住。

遠端桌面 — MCP 工具 

MCP server 現在把 GUI 用的 process-global remote-desktop registry 包成工具,工廠函式為 je_auto_control/utils/mcp_server/tools/_factories.py 內的 remote_desktop_tools():

ac_remote_host_start: 啟動(或重啟)singleton TCP host,參數 token、 bind、port、fps、quality、max_clients、 host_id,回傳 {running, port, host_id, connected_clients}。
ac_remote_host_stop: 關閉 host(沒在跑時為 no-op)。
ac_remote_host_status: 唯讀的 host 狀態快照,在 --readonly 模式下仍然可用。
ac_remote_viewer_connect: 把 singleton viewer 連到遠端 host,可選 expected_host_id 驗證 9 位數 ID。
ac_remote_viewer_disconnect / ac_remote_viewer_status: 關閉 / 觀察 viewer(status 為唯讀)。
ac_remote_viewer_send_input: 透過已連線的 viewer 把輸入動作 dict(mouse_move、 mouse_press、mouse_release、mouse_scroll、 key_press、key_release、type、hotkey)轉送到遠端 host。屬於 destructive,在 --readonly 模式下會被剔除。

這樣一來模型就能在不開 GUI 的情況下完成完整的遠端控制流程:

ac_remote_host_start(token="tok", bind="127.0.0.1", port=0)
  → {"running": true, "port": 51234, "host_id": "123456789",
     "connected_clients": 0}

# … 切到另一台機器 …
ac_remote_viewer_connect(host="10.0.0.5", port=51234, token="tok",
                         expected_host_id="123456789")
  → {"connected": true, "host_id": "123456789"}

ac_remote_viewer_send_input(action={
    "action": "mouse_move", "x": 100, "y": 200,
})
ac_remote_viewer_send_input(action={
    "action": "type", "text": "hello",
})

狀態類工具(ac_remote_host_status、 ac_remote_viewer_status)為唯讀,可以通過 MCP server 的 --readonly 過濾;會修改狀態的工具都正確帶上 destructiveHint: true,MCP client 端可以據此跳出使用者確認。

驅動層輸入後端 — 驅動不接受 SendInput / XTest 的遊戲 

預設的 Windows(SendInput)與 Linux(XTest)輸入路徑落在 user-mode / X-server 那一層;會用 GetRawInputData``(Win)或 ``evdev (Linux)直接讀 raw input 的遊戲會跳過這些層,完全忽略合成事件。新增三個可選的後端可以解決這個問題。

Interception(Windows)

Oblita 的 WHQL-signed Interception driver (https://github.com/oblitum/Interception)在 HID 層注入鍵鼠事件, OS 看到的就是「真實裝置」事件。

新增子套件:je_auto_control/windows/interception/ (_dll.py ctypes bindings + keyboard.py + mouse.py)。
與 win32_ctype_keyboard_control / win32_ctype_mouse_control 公開介面完全一致 — wrapper 在啟動時直接換模組,呼叫端不需要任何修改。
透過 JE_AUTOCONTROL_WIN32_BACKEND=interception 啟用;若 driver 沒裝,wrapper 會打 warning 並回到 SendInput,所以可以分階段佈署。
用 JE_AUTOCONTROL_INTERCEPTION_KEYBOARD / JE_AUTOCONTROL_INTERCEPTION_MOUSE 覆寫 device id(預設 1 / 11)。

操作步驟:

# 1. 以系統管理員身份安裝 driver(一次性,需要重開機)
install-interception.exe /install

# 2. 告訴 AutoControl 走這條路
setx JE_AUTOCONTROL_WIN32_BACKEND interception

uinput(Linux)

kernel 自帶的合成輸入閘道。透過 /dev/uinput 送出的事件會被建立成一個全新的 HID 裝置,任何讀 evdev 的程式(包含大部分遊戲與 SDL2 app)都會視為真實輸入。

新增子套件:je_auto_control/linux_with_x11/uinput/ (_device.py 直接用 ctypes + ioctl 包 /dev/uinput + keyboard.py + mouse.py)。
無第三方依賴 — 全程 ctypes + ioctl。
透過 JE_AUTOCONTROL_LINUX_BACKEND=uinput 啟用;若 /dev/uinput 沒寫入權限,會 warning 後回退到 XTest。

操作步驟:

# 載入 kernel module
sudo modprobe uinput

# 一次性測試:直接放寬權限
sudo chmod 666 /dev/uinput

# 持續性權限,寫一個 udev rule:
echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' \
  | sudo tee /etc/udev/rules.d/99-autocontrol-uinput.rules
sudo udevadm control --reload && sudo udevadm trigger
sudo usermod -aG input $USER  # 重新登入後生效

# 啟用後端
export JE_AUTOCONTROL_LINUX_BACKEND=uinput

ViGEm 虛擬手把(Windows)

針對「完全不吃鍵鼠、只認手把」的遊戲,可以用 ViGEmBus 建立一個虛擬 Xbox 360 / DualShock 4 控制器;AutoControl 透過第三方 vgamepad 套件來驅動它。

新增模組:je_auto_control/utils/gamepad/ 提供友善的 VirtualGamepad API(字串名稱的 button / dpad / stick / trigger,支援 context manager)。

Headless:

from je_auto_control import VirtualGamepad
with VirtualGamepad() as pad:
    pad.click_button("a")               # A 鍵
    pad.set_left_stick(16000, 0)        # int16 stick 偏移
    pad.set_right_trigger(255)          # 0..255 力度
    pad.set_dpad("up")                  # 按住方向鍵上
    pad.update()                        # 把狀態 flush 給 driver

Executor 指令:AC_gamepad_press、AC_gamepad_release、 AC_gamepad_click、AC_gamepad_dpad、 AC_gamepad_left_stick / _right_stick、 AC_gamepad_left_trigger / _right_trigger,以及 AC_gamepad_reset。
MCP 工具:同名加上 ac_ 前綴(ac_gamepad_press、 ac_gamepad_left_stick …),所以模型可以透過 MCP 玩只支援手把的遊戲。

操作步驟:

# 1. 安裝 ViGEmBus driver(一次性,需要重開機)
#    https://github.com/nefarius/ViGEmBus/releases
# 2. 安裝 Python wrapper:
pip install vgamepad

反作弊注意事項 

驅動層注入比 SendInput / XTest 更難偵測,但帶 kernel-mode driver 的反作弊(Vanguard、有 kernel module 的 Easy Anti-Cheat、 BattlEye)依然可以列舉 Interception / ViGEmBus / 新建立的 uinput 裝置然後拒絕啟動。

這三個後端針對的是合法用途 — 輔助科技、遊戲 GUI 測試、從 headless 環境控制執行遊戲的遠端機器 — 不是通用反作弊繞過工具。

效能分析器(Profiler)

針對每個 AC_* 動作記錄執行時間,讓你不用外部工具就能回答「哪一步是腳本的瓶頸?」分析是 opt-in 的,關閉時 executor 包裝層零開銷:

import je_auto_control as ac
ac.default_profiler.enable()
ac.execute_action([["AC_locate_image_center", {"image": "btn.png"}],
                   ["AC_click_mouse"]])
for row in ac.default_profiler.hot_spots(limit=5):
    print(row.name, row.calls, row.average_seconds)

Action JSON 指令:

[["AC_profiler_enable"]]
[["AC_profiler_stats", {"limit": 10}]]
[["AC_profiler_hot_spots", {"limit": 5}]]
[["AC_profiler_reset"]]
[["AC_profiler_disable"]]

GUI: Profiler 分頁 — 每秒重新整理熱點表(次數 / 總時間 / 平均 / 最短 / 最長 / 佔比),支援開關記錄、清除統計,或透過 headless API 匯出快照。

執行紀錄時間軸 + 失敗截圖 

Run History 分頁在篩選列下方多了一條 Gantt 風格的時間軸:每筆 scheduler / trigger / hotkey / webhook / email 觸發都繪成橫向時間軸上的色條(綠 = ok、紅 = error、琥珀 = 進行中)。點選色條會同步表格列,右側預覽面板顯示由 artifact manager 已捕捉的失敗截圖。

Headless 端讀取相同資料用既有的 run history store:

import je_auto_control as ac
for row in ac.default_history_store.list_runs(limit=20):
    print(row.id, row.status, row.duration_seconds, row.artifact_path)

沒有新增指令 — store API 維持不變,GUI 只是 runs 表的薄殼可視化。

密鑰管理器(Secret Manager)

需要 API token、IMAP 密碼等敏感資訊的腳本,絕不該明文嵌入。新的密鑰庫把 Fernet 加密過的條目存在 ~/.je_auto_control/secrets/vault.json; 通行碼透過 PBKDF2-HMAC-SHA256(60 萬次迭代,16 byte 鹽值)推導出金鑰:

import je_auto_control as ac
ac.default_secret_manager.initialize("my-vault-passphrase")
ac.default_secret_manager.set("github_token", "ghp_xxxxx")
ac.default_secret_manager.lock()

# 之後 — 在同一個程序或新的 run:
ac.default_secret_manager.unlock("my-vault-passphrase")

Action JSON 指令:

[["AC_secret_init",   {"passphrase": "..."}]]
[["AC_secret_unlock", {"passphrase": "..."}]]
[["AC_secret_set",    {"name": "github_token", "value": "ghp_xxx"}]]
[["AC_secret_list"]]
[["AC_secret_remove", {"name": "github_token"}]]
[["AC_secret_lock"]]
[["AC_secret_status"]]

腳本透過 ${secrets.NAME} 佔位符引用 vault 條目。插補器會把 secrets. 命名空間導向 vault,而不是普通變數作用域,所以明文值永遠不會進到變數袋裡:

[["AC_shell_command",
  {"command": "curl -H \"Authorization: Bearer ${secrets.github_token}\" ..."}]]

GUI: Secrets 分頁 — 建立 vault、解鎖、新增 / 移除條目、變更通行碼。POSIX 系統上 vault 檔以 0o600 建立;Windows 預設 ACL 已限制只有擁有者能讀取。

Webhook(HTTP push)觸發 

內建的 http.server dispatcher 在外部服務 POST 到註冊路徑時觸發腳本。可設定路徑、允許的方法、可選 bearer token;請求方法、路徑、query、headers、原始 body、解析後 JSON 都會種到變數作用域:

import je_auto_control as ac
ac.default_webhook_server.add(
    path="/jobs/build", script_path="hooks/on_build.json",
    methods=["POST"], token="topsecret",
)
host, port = ac.default_webhook_server.start("127.0.0.1", 0)
print("listening on", host, port)

綁定的腳本透過 ${webhook.*} 佔位符讀取請求:

[
  ["AC_set_var", {"name": "branch", "value": "${webhook.query.ref}"}],
  ["AC_shell_command",
   {"command": "echo received build for ${webhook.body}"}]
]

Action JSON 指令:

[["AC_webhook_start", {"host": "127.0.0.1", "port": 8765}]]
[["AC_webhook_add",   {"path": "/jobs", "script_path": "...",
                       "methods": ["POST"], "token": "..."}]]
[["AC_webhook_list"]]
[["AC_webhook_remove", {"webhook_id": "abcd1234"}]]
[["AC_webhook_status"]]
[["AC_webhook_stop"]]

每次觸發以 trigger 來源寫入 run history,source id 為 webhook:<id>,讓 dashboard 把 webhook 活動和其他 trigger 並排顯示。Body 上限 1 MiB,bearer token 比對用 hmac.compare_digest()。除非你真的需要從網路其他地方連入, 否則綁定 127.0.0.1。

GUI: Webhooks 分頁 — 啟動 / 停止伺服器、註冊路徑、檢視每條路由的觸發次數與驗證狀態。

IMAP Email 觸發 

輪詢式 watcher,依設定週期登入信箱,每封符合條件的郵件執行一次腳本:

import je_auto_control as ac
ac.default_email_trigger_watcher.add(
    host="imap.gmail.com", username="user@example.com",
    password="app-specific-password",
    script_path="hooks/on_alert.json",
    mailbox="INBOX", search_criteria='UNSEEN FROM "alerts@..."',
    poll_seconds=120, mark_seen=True,
)
ac.default_email_trigger_watcher.start()

腳本透過 ${email.*} 看到郵件中繼資料:

[
  ["AC_if_var", {
    "name": "email.subject", "op": "contains", "value": "CRITICAL",
    "then": [["AC_hotkey", {"keys": ["ctrl", "alt", "p"]}]]
  }]
]

每次觸發種入的變數: email.uid、email.from、email.to、 email.subject、email.message_id、email.date、email.body。

Action JSON 指令:

[["AC_email_trigger_add",       {"host": "...", "username": "...",
                                 "password": "${secrets.imap_pw}",
                                 "script_path": "...",
                                 "mailbox": "INBOX",
                                 "search_criteria": "UNSEEN",
                                 "poll_seconds": 120,
                                 "mark_seen": true,
                                 "use_ssl": true}]]
[["AC_email_trigger_start"]]
[["AC_email_trigger_poll_once"]]
[["AC_email_trigger_list"]]
[["AC_email_trigger_remove", {"trigger_id": "abcd1234"}]]
[["AC_email_trigger_stop"]]

Watcher 在 process 記憶體中追蹤已觸發的 UID,可選擇把訊息標為 \\Seen 確保跨重啟不會重複觸發。TLS 強制最低 1.2 版。把 AC_email_trigger_add 跟 ${secrets.NAME} 搭配使用, 密碼就不會出現在 JSON 裡。

GUI: Email Triggers 分頁 — 註冊 IMAP 觸發、啟動 / 停止 watcher、手動觸發一次輪詢、檢視最近錯誤與觸發次數。