AutoControl 是一套開源、跨平台的 computer-use 與 GUI 自動化框架，面向 AI agent、Python 應用程式與自動化測試。它能驅動滑鼠與鍵盤、透過樣板比對、OCR、作業系統無障礙樹或視覺模型找到 UI 目標、錄製與重播流程，並以 JSON 動作檔執行——支援 Windows、macOS、Linux（X11 與 Wayland）、BSD、Android 與 iOS。
每項能力都以三種形式提供：Python API、可在 JSON 檔／CLI／伺服器使用的 AC_* 動作指令，
以及 GUI 分頁。沒有任何功能只存在於 GUI。
- 一套 API，七個平台。
wrapper/platform_wrapper.py在匯入時挑選後端；同一份腳本在 Windows、macOS、X11 與 Wayland 上都不需要改寫。 - 不寫 Python 也能腳本化。 852 個
AC_*指令涵蓋全部功能，因此一個 JSON 檔能做到函式庫 能做的任何事——包含迴圈、分支、try/catch、巨集與變數。 - 預設無頭執行。
import je_auto_control絕不會載入 Qt。GUI 是選用套件，包在同一個無頭核心之外。 - 四種定位方式。 樣板比對、OCR、無障礙樹、視覺語言模型——可透過錨點定位器與自癒後備串接組合。
- 相依基線輕薄。 REST 伺服器、JSON Schema 驗證、JWT、TOTP、WebSocket 框架、ACME 用戶端、 USB/IP 協定與 Prometheus 指標全部以標準庫實作；較重的相依都是選用。
AutoControl 是開源、跨平台的 computer-use 與 GUI 自動化框架。
當 AI agent 需要操作真實桌面、原生應用程式、真正的瀏覽器視窗、遠端桌面或行動裝置，而不只是操作瀏覽器 DOM/API 時，使用 AutoControl。
- 真實滑鼠與鍵盤輸入
- 螢幕擷取與座標操作
- OCR 與原生無障礙樹
- 影像／樣板比對
- Vision-Language Model UI 定位
- Anchor 與 self-healing locator
- 跨平台桌面／行動裝置自動化
- JSON 動作檔
- MCP computer use
建議的 agent loop：
observe → identify → act → wait → verify → recover
完整的 AI Agent 指南 提供 MCP 設定、工具選擇、OpenAI 整合、安全性與 computer-use 關鍵字。
pip install je_auto_control
je_auto_control_mcpMCP 提供完整的 ac_* 工具，以及 click、type、screenshot、find_text、click_text、drag、focus_window、wait_image 等短名稱 alias。
只做檢查：
je_auto_control_mcp --read-only只需要 canonical ac_* 名稱：
JE_AUTOCONTROL_MCP_ALIASES=0 je_auto_control_mcpOpenAI agent 請使用 export_openai_tools(only=[...]) 提供聚焦工具集，不要一次提供整個 AutoControl 命令目錄。
專案： AutoControl
Repository： Integration-Automation/AutoControlGUI
Python package / PyPI： je_auto_control
MCP command： je_auto_control_mcp
AutoControl 不需要取代所有自動化工具；應該選擇最符合介面的那一層：
| 需求 | 適合工具 |
|---|---|
| 穩定的瀏覽器 DOM／API 自動化 | Playwright／Selenium |
| 簡單的 Python 滑鼠鍵盤腳本 | PyAutoGUI 或 AutoControl |
| 原生桌面應用程式自動化 | AutoControl |
| 無障礙樹 GUI 自動化 | AutoControl |
| OCR GUI 自動化 | AutoControl |
| 截圖／視覺模型 GUI 定位 | AutoControl |
| Self-healing 跨平台 GUI locator | AutoControl |
| AI agent 操作真實桌面 | AutoControl + MCP |
| 確定性的 JSON GUI workflow | AutoControl |
AutoControl 的差異在於把 真實電腦輸入 + 語意／視覺定位 + self-healing + agent/MCP 整合 放在同一個跨平台自動化介面。
pip install je_auto_control # 核心
pip install je_auto_control[gui] # 加上 PySide6 桌面應用程式需要時才安裝的選用套件：
| Extra | 啟用的功能 |
|---|---|
gui |
PySide6 桌面應用程式（50 個分頁）：左側可搜尋的導覽面板（Ctrl+K）依分類列出全部功能，分頁在第一次開啟時才建立，View → Theme 切換深色／淺色 |
webrtc |
WebRTC 遠端桌面、USB 直通（aiortc、av） |
signaling |
獨立的訊令／rendezvous 伺服器（fastapi、uvicorn） |
discovery |
mDNS / Zeroconf 區網主機探索 |
pdf / office |
PDF 與 Excel／Word／PowerPoint 讀取 |
fuzzy / locale |
rapidfuzz 模糊比對、babel 地區解析 |
s3 / audio |
S3 產出物儲存、系統音量控制 |
Windows arm64 裝得起來也跑得起來，少的是上游在那裡發不出來的那些：
opencv-python 與 cryptography 都沒發 win_arm64 wheel。所以 find_image*、
screenshot()（OpenCV／BGR 那一支——Pillow 截圖仍可用）、秘密金庫、動作檔加密、
ACME／TLS 與加密錄影會拋出指名缺哪個 wheel 的錯誤，而不是難以追查的失敗。
滑鼠、鍵盤、螢幕尺寸、視窗管理、無障礙樹、動作執行器、MCP／REST／TCP 伺服器
與 GUI 都正常——這是實測的，不是推論的。其他平台不受影響。
系統需求： Python ≥ 3.10（Windows arm64≥ 3.11，CPython 官方建置從那裡開始）。 Linux 請先安裝建置前置套件：
sudo apt-get install cmake libssl-devOCR、VLM 與 LLM 後端（pytesseract、easyocr、paddleocr、anthropic、openai）
都是按需載入——只裝你實際會用到的。Tesseract 的部分，find_tesseract_cmd() 找出執行檔
（依序是 $TESSERACT_CMD、PATH、安裝程式的預設資料夾），set_tessdata_dir() 把它指到
語言資料夾，ocr_status()／ocr_languages() 在第一次 OCR 之前就說出缺了什麼。
記錄檔： 函式庫寫到 ~/.je_auto_control/logs/AutoControlGUI.log，第一筆記錄時
才建立（只 import 不會寫任何檔），同一個帳號的所有行程共用（附加寫入、每行帶行程 ID，
超過 10 MB 就改名成 .1）。要寫到別處就設定
JE_AUTOCONTROL_LOG_FILE，設成 os.devnull 則不寫檔。
1. 當成 Python 函式庫
import je_auto_control as ac
ac.set_mouse_position(500, 300)
ac.click_mouse("mouse_left")
ac.write("Hello World")
ac.hotkey(["ctrl_l", "s"])
x, y = ac.locate_image_center("save_button.png", detect_threshold=0.9)
ac.click_text("Submit") # OCR
ac.click_accessibility_element(name="OK") # 無障礙樹
ac.click_by_description("the green Submit button") # 視覺模型
ac.screenshot("shot.png", screen_region=[0, 0, 800, 600])2. 當成 JSON 動作檔 — flow.json
[
["AC_set_var", {"name": "user", "value": "alice"}],
["AC_locate_and_click", {"image": "login.png", "mouse_keycode": "mouse_left"}],
["AC_write", {"write_string": "${user}"}],
["AC_retry", {"max_attempts": 3, "body": [
["AC_wait_text", {"target": "Welcome", "timeout": 10}]
]}],
["AC_assert_text", {"text": "Welcome"}],
["AC_generate_html_report", {"html_name": "report"}]
]je_auto_control run flow.json --var user=bob
je_auto_control run flow.json --dry-run # 只列出步驟，不會真的動滑鼠3. 當成桌面應用程式
pip install je_auto_control[gui]
python -c "import je_auto_control; je_auto_control.start_autocontrol_gui()"錄製一段流程、在視覺化 Script Builder 裡編輯，然後存成 CLI 能直接執行的同一種 JSON 格式。
（python -m je_auto_control 是舊式的動作檔執行器——-e、-d、-c、--execute_str——不會開 GUI。）
每一列都能無頭執行。「GUI 分頁」是同一功能在桌面應用中的位置；分頁的指令都放在視窗的 Actions 選單裡。
| 能力 | Python API | AC_* 指令 |
GUI 分頁 |
|---|---|---|---|
| 滑鼠 | click_mouse（clicks=2 就是雙擊）、set_mouse_position、mouse_scroll、tween_drag／drag_path（以 step_delay_s、settle_s 控制節奏） |
AC_click_mouse、AC_tween_drag、AC_drag_path |
Auto Click |
| 鍵盤 | write、write_secret、hotkey、type_keyboard、keyboard_key_name（鍵碼 → 標準鍵名；Windows 也收 ctrl、esc、enter 等別名） |
AC_write、AC_write_secret、AC_hotkey |
Auto Click |
| 螢幕與像素 | screenshot、screen_size、get_pixel |
AC_screenshot |
Screenshot |
| 影像比對 | locate_image_center、locate_and_click |
AC_locate_and_click |
Image Detect |
| OCR 文字 | click_text、wait_for_text、read_text_in_region、ocr_status |
AC_click_text、AC_wait_text、AC_ocr_status |
OCR Reader |
| 無障礙樹 | find_accessibility_element、click_accessibility_element |
AC_a11y_find、AC_a11y_click |
Accessibility |
| 視覺模型定位 | locate_by_description、click_by_description |
AC_vlm_locate、AC_vlm_click |
VLM |
| 錨點定位 | — | AC_anchor_click、AC_anchor_locate |
— |
| 自癒定位器 | self_heal_click、self_heal_locate |
AC_self_heal_click |
Self-Healing |
| 自然語言規劃 | plan_actions、run_from_description |
AC_llm_plan |
LLM Planner |
| Computer-use agent | AgentLoop、run_agent |
AC_run_agent |
Computer Use |
| 錄製與重播 | record、stop_record |
AC_record、AC_stop_record |
Record |
| JSON 腳本 | execute_action、execute_files |
全部 852 個指令 | Script、Script Builder |
| 變數與流程控制 | execute_action_with_vars |
AC_set_var、AC_loop、AC_for_each、AC_try、AC_retry |
Variables |
| 資料驅動執行 | — | AC_for_each_row（CSV／JSON／SQLite／Excel） |
Data Sources |
| 斷言 | assert_text、assert_image |
AC_assert_text 等 21 個 |
Assertions |
| 測試套件 | run_suite |
AC_run_suite |
Test Suites |
| 排程（間隔 + cron） | default_scheduler |
— | Scheduler |
| 全域熱鍵 | default_hotkey_daemon |
— | Hotkeys |
| 事件觸發 | default_trigger_engine |
AC_email_trigger_add |
Triggers、Webhooks、Email |
| 視窗管理 (Windows、macOS、X11) | list_windows、focus_window |
AC_focus_window、AC_snap_window |
Window Manager |
| 剪貼簿（文字 + 影像） | get_clipboard、set_clipboard、get_clipboard_image、set_clipboard_image |
AC_clipboard_get、AC_clipboard_set、AC_clipboard_get_image、AC_clipboard_set_image |
— |
| 遠端桌面 | RemoteDesktopHost、RemoteDesktopViewer |
AC_start_remote_host、AC_remote_connect |
Remote Desktop |
| USB 列舉與直通 | list_usb_devices、enable_usb_passthrough |
AC_usb_*（16 個指令） |
USB Devices、USB Share |
| 機密保險庫 | default_secret_manager |
AC_secret_set + ${secrets.NAME} |
Secrets |
| 報表（HTML／JSON／XML） | generate_html_report |
AC_generate_html_report |
Report |
| 執行歷史 | — | — | Run History |
| 指標與追蹤 | default_metric_registry、render_metrics_text |
— | — |
| 系統診斷 | run_diagnostics |
AC_diagnose |
Diagnostics |
| 測試碼產生 | generate_code |
— | — |
除了這張表，utils/ 底下還有 311 個無頭套件，涵蓋斷言、韌性、資料品質、i18n 稽核、遮蔽、
治理、可觀測性等等。完整的逐模組地圖在 architecture_explore.md。
je_auto_control run script.json [--var name=value] [--dry-run] [--allow-package NAME]
je_auto_control validate script.json # 別名：lint
je_auto_control fmt script.json [--check]
je_auto_control list-commands [--filter mouse] [--json]
je_auto_control record out.json [--duration 5]
je_auto_control codegen script.json --target pytest -o test_flow.py
je_auto_control failure-bundle failure.zip --error "login timed out"
je_auto_control list-jobs
je_auto_control start-server --port 9938 # TCP socket 伺服器
je_auto_control start-rest --port 9939 # REST API
je_auto_control version--var name=value 會盡量以 JSON 解析（count=10 會變成整數），否則視為字串。
run 只要有任何動作失敗就以 1 結束（仍會跑完整份腳本），CI 步驟會跟著失敗。舊版 python -m je_auto_control -e file.json 進入點仍然可用，它的 -e、-d 與 --execute_str 旗標也同樣在有動作失敗時以 1 結束。由 TestPioneer 啟動時（它會設定 TEST_PIONEER_ARTIFACT_DIR），以相對名稱要求的 HTML、JSON、XML 報告會寫到該目錄底下。
| 介面 | 啟動方式 | 說明 |
|---|---|---|
| MCP 伺服器 | je_auto_control_mcp（stdio）或 AC_start_mcp_http_server |
757 個工具，供 Claude Desktop／Claude Code／自訂 tool loop 使用：完整的 ac_* 工具介面，以及常用 GUI 操作的短名稱 alias。除了以 initialize 握手的各版協定，也支援無狀態的 MCP 2026-07-28。Bearer 驗證、TLS、稽核記錄、限流、外掛熱重載、CI 假後端。 |
| REST API | je_auto_control start-rest |
Bearer token、逐 IP 限流與鎖定、SQLite 稽核 hook、/metrics、/openapi.json、/docs Swagger UI、/dashboard。 |
| TCP socket 伺服器 | je_auto_control start-server |
以換行分隔的 JSON 動作清單。預設綁 127.0.0.1。 |
| pytest 外掛 | 安裝後自動生效 | 提供 fixture 與供 pytest-bdd／behave 使用的 Gherkin step library。 |
| 語言伺服器 | python -m autocontrol_lsp.server |
為 AC_* 動作 JSON 提供補全與診斷，指令清單直接取自執行期的指令表。 |
| 遠端桌面 | RemoteDesktopHost 或 GUI |
TCP、WebSocket 或 WebRTC；TOTP、信任清單、TURN 設定、檔案／剪貼簿／音訊同步。 |
除非明確指定，所有伺服器都綁在 127.0.0.1。
套件閘門。 AC_add_package_to_executor 與 AC_add_package_to_callback_executor 會匯入 Python 套件並把成員註冊成命令，所以從上面任何一個入口送來的動作清單都可能載入 os 或 subprocess。沒有被放行的套件不會載入：不在允許清單上的套件在匯入前就被拒絕，該動作以 AutoControlExecuteActionException 失敗。放行套件（含子模組）的方式：在 Python 裡呼叫 executor.allow_packages("name", …)；對所有入口——兩個 CLI、socket／REST／MCP 伺服器與排程器——設定環境變數 JE_AUTOCONTROL_ALLOWED_PACKAGES（以逗號分隔的名稱，行程啟動時讀取）；或只對一次 CLI 執行使用 je_auto_control run script.json --allow-package NAME（可重複）。executor.set_allow_arbitrary_packages(True) 會對所有套件打開閘門，也就是先前版本的預設行為（當時會發 DeprecationWarning）。這些都不是 AC_* 命令，所以動作清單不能自己打開閘門。
選用的強化設定。 下列各項在設定之前都是關閉的，沒設定的伺服器行為與先前相同。JE_AUTOCONTROL_RBAC_USERS=<使用者檔> 讓 REST API 與 MCP HTTP 傳輸把 bearer token 對到使用者，並依角色（viewer／operator／admin）授權每一個路由、工具與特權 AC_* 命令；此時共用 token 會被拒絕。JE_AUTOCONTROL_MCP_PATH_ROOTS（以作業系統的路徑分隔字元分開的目錄）把每一個屬於檔案路徑的 MCP 工具參數限制在這些目錄裡，JE_AUTOCONTROL_MCP_PATH_ROOTS_FROM_CLIENT=1 再加上 client 的 roots/list，JE_AUTOCONTROL_MCP_ENV_REF_ALLOW 限制 ac_resolve_ref 可以讀哪些 env:// 名稱。JE_AUTOCONTROL_ACTION_SIGNING_PUBLIC_KEY 讓端點只能驗證 Ed25519 簽章的動作檔而不能簽章（create_signing_keypair；私鑰留在簽章的機器上）。遠端桌面的 viewer 只把 host 推來的檔案寫在 ~/Downloads/AutoControl 底下（JE_AUTOCONTROL_REMOTE_DOWNLOAD_DIR）；這一項預設就是開的。
其他可設定的項目。 JE_AUTOCONTROL_MCP_TOOL_MODE=progressive（或 je_auto_control_mcp --tool-mode）讓 MCP session 從五個核心工具開始，再搜尋、查詢與啟用其他工具；static 提供固定的工具組（JE_AUTOCONTROL_MCP_TOOL_PROFILE）；預設的 full 模式不變。RBAC 的使用者以 je_auto_control users add|remove|set-role|rotate-token|list、AC_user_* 命令或 REST API 分頁管理。JE_AUTOCONTROL_ACTION_SIGNING_PASSPHRASE 用來解開有通行碼保護的簽章私鑰。動作日誌（start_action_journal、AC_journal_*）記錄執行過的動作並先遮蔽秘密，je_auto_control codegen --from-log 把一次執行轉成候選腳本。設定同步把資料存在 SQLite 並檢查版本（--config-db、AC_SIGNALING_CONFIG_DB；舊版 client 需要 --allow-blind-config-writes）。Android 與 iOS 裝置各有自己的 session（open_device、AC_android_*、AC_ios_*）；行動裝置的程式還沒有在任何裝置上跑過。Wayland 上 probe_capabilities／AC_probe_capabilities 回報輸入與擷取能做什麼、為什麼，JE_AUTOCONTROL_WAYLAND_EI_WORKER=1 把 libei 移到輔助行程。GUI 會把主題、字級、面板與視窗位置記在 ~/.je_auto_control/gui_settings.ini（JE_AUTOCONTROL_GUI_SETTINGS）。
把主機開出去之前值得先知道，而且這段在其他文件裡都沒有寫。預設傳輸是裸 TCP 上的長度前綴分幀（不需要額外相依），連線一開始就是 HMAC-SHA256 的 challenge／response 握手：驗證沒過的觀看端在拿到任何一張畫面之前就會被斷掉。 JPEG 影格依設定的 FPS 與品質編碼，再透過一個共用的最新影格槽發給已驗證的 觀看端——所以慢的觀看端是掉影格，不會把其他人一起卡住。觀看端送來的輸入是 JSON，會先比對動作允許清單才交給既有的輸入包裝層執行，觀看端無法自己發明 新的操作。
# 讓別人連進來——開一個主機，把 token 與 port 給對方
from je_auto_control import RemoteDesktopHost
host = RemoteDesktopHost(token="hunter2", bind="127.0.0.1",
port=0, fps=10, quality=70)
host.start()
print("listening on", host.port, "viewers:", host.connected_clients)# 控制另一台機器——連上去並送輸入
from je_auto_control import RemoteDesktopViewer
viewer = RemoteDesktopViewer(host="10.0.0.5", port=51234, token="hunter2",
on_frame=lambda jpeg: ...)
viewer.connect()
viewer.send_input({"action": "mouse_move", "x": 100, "y": 200})
viewer.disconnect()也可以用 IP 允許清單（CIDR 網段或個別位址）限制誰連得進來，清單外的對端在握手 階段就會被拒絕：
RemoteDesktopHost(token="tok", ip_allowlist=["10.0.0.0/8", "192.168.1.100"])| 平台 | 後端 | 輸入 | 螢幕擷取 | 錄製 | 視窗管理 |
|---|---|---|---|---|---|
| Windows 10 / 11 | Win32 ctypes（可選 Interception 驅動） | ✅ | ✅ | ✅ | ✅ |
| macOS 10.15+ | pyobjc / Quartz | ✅ | ✅ | ✅¹ | ✅ |
| Linux X11 | python-Xlib（可選 uinput） |
✅ | ✅ | ✅ | ✅ |
| Linux Wayland | 經桌面 portal 的 libei，或 ydotool／wtype ＋ 擷取工具 | ✅ | ✅ | ❌ | ❌ |
| FreeBSD／OpenBSD／NetBSD | python-Xlib，與 Linux 同一套 X11 後端 | ✅² | ✅² | ✅² | |
| Android | adb + uiautomator2 | ✅ | ✅ | — | — |
| iOS | WebDriverAgent / facebook-wda | ✅ | ✅ | — | — |
¹ macOS 的錄製走 Quartz event tap，需要輔助使用權限 （系統設定 → 隱私權與安全性 → 輔助使用）。沒有授權時會直接拋出並指名 缺的是哪個權限，而不是安靜地錄到一個空的 session。
² BSD 直接跑同一套 X11 後端——同一個 X server、同一個 python-Xlib，而輸入、
錄製與視窗管理就只相依這一個套件。freebsd CI job 在真的 FreeBSD 14 上驅動真的
輸入，再從 X server 讀回來；OpenBSD 與 NetBSD 走同一條程式路徑，只是沒有 CI
runner。唯一的例外是螢幕擷取，而卡的是打包不是平台：它走 Pillow／mss 與 OpenCV，
而 opencv-python、pillow、cryptography 都沒有發 FreeBSD wheel。從 ports
建起來之後，擷取、影像比對、OCR 與動作加密也都能用——import je_auto_control
本身已經不需要它們任何一個。
Wayland 的輸入在 libei 走不通時會退回 ydotool CLI，而這條退路需要
ydotool 1.0 以上。AutoControl 送的每一個參數都是那一版才有的；0.1.x
（Debian bookworm 與目前所有 Ubuntu 仍以這個名字提供，Debian trixie 則根本沒有）
對同一批參數回傳 0 卻不送出任何事件。AutoControl 會偵測並直接拒絕，
而不是為根本沒送出的輸入回報成功。Arch、Fedora 與 Debian unstable 提供的是 1.0。
這條退路要能準確定位，還有一個前提:合成器的指標加速度必須是關的。
ydotool mousemove --absolute 並不送任何絕對事件——它先把游標推到合成器夾取的
那個角落，再送相對位移，所以這段位移會被合成器加速。對真的 wlroots session 量到的是:
libinput 的預設 profile 讓游標走的距離正好是要求的兩倍。ydotool 自己的 --help
也是這樣寫的；AutoControl 每個行程會記一次警告，而不是安靜地把點擊放到錯的地方。
請對 ydotoold 的裝置關掉加速度（sway:input type:pointer accel_profile flat
加上 pointer_accel 0），或是裝上 liboeffis，改走協定層本來就是絕對座標的 libei。
倍率是合成器自己的設定，用戶端讀不回來，所以只有你知道它關了沒有：
JE_AUTOCONTROL_WAYLAND_POINTER_ACCEL=flat 表示已經關掉，移動就不再出聲；
=strict 則寧可拒絕這次移動，也不讓點擊落在別的地方；不設定就維持
「警告一次後照樣移動」的預設。
Wayland 的螢幕擷取需要合成器對應的工具，因為沒有單一工具能涵蓋全部：wlroots 系
（sway、Hyprland、river）用 grim，GNOME 用 gnome-screenshot，KDE 用 spectacle。
裝好其中一個之後，所有擷取路徑——截圖、影像與錨點定位、OCR、螢幕錄影、遠端桌面——都會
經由它。三個都沒裝也還有 gdbus：最後會嘗試 xdg-desktop-portal，只是第一次可能會跳
同意對話框。再不行，擷取會帶著安裝提示明確失敗，而不是回傳空白的 XWayland root；
je_auto_control.api.run_diagnostics()（以及 GUI 的 Diagnostics 分頁）的 screen_capture
檢查會回報目前使用哪一層。
有一件只在 Wayland 出現、需要事先規劃的事：擷取回來的圖裡可能有滑鼠游標。
這裡沒有任何一條擷取要求游標，但只要 backend 沒有游標平面（包含任何以
WLR_NO_HARDWARE_CURSORS=1 執行的 session），wlroots 就會畫軟體游標並把它
合成進輸出緩衝區，而擷取交回來的正是那一份。Windows 與 X11 都不含游標，所以
「定位器、樣板比對或 OCR 在目標中間看到一個游標形狀的洞」只會在這裡發生。
Wayland 不讓用戶端讀游標位置，所以沒有東西可以可靠地遮或閃避：請在擷取之前
把指標移離要拍的區域。screen_capture 檢查會以 cursor_may_be_captured 回報這件事。
如果以上都不適用你的環境，可以直接指定自己的指令——它優先於所有偵測，{output} 會被
換成暫存 PNG 路徑：
export JE_AUTOCONTROL_WAYLAND_CAPTURE_COMMAND="mycapture --png {output}"Wayland 禁止非特權用戶端進行全域輸入錄製——若要錄製，請設定
JE_AUTOCONTROL_LINUX_DISPLAY_SERVER=x11 並在 X11 session 下執行。視窗管理支援
Windows、macOS（pyobjc）與 X11（含 XWayland）；純 Wayland session 的協定不讓用戶端看到別的程式的視窗，
所以 list_windows() 回傳空清單，其餘視窗操作一律拋出帶原因的 AutoControlUnsupportedOperationException。對於會忽略合成輸入的應用程式，
可選用驅動層後端（JE_AUTOCONTROL_WIN32_BACKEND=interception、
JE_AUTOCONTROL_LINUX_BACKEND=uinput、ViGEm 虛擬手把）；驅動未安裝時會自動退回原本行為。
AutoControl 讀取的每一個環境變數。這裡沒有任何一項是必填的：完全不設定時，AutoControl 會自行選擇平台後端，伺服器只綁定 127.0.0.1，所有需要主動開啟的功能（簽章強制、RBAC、USB 直通、工具路徑限制）都是關閉的。設定參考（原始檔）列出完整的可接受值，並把每個變數連到說明該功能的頁面；CI 會拿它以及下面的表格和程式碼比對。
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_WIN32_BACKEND |
sendinput |
設成 interception 時鍵盤與滑鼠改走 Interception 驅動程式；找不到驅動或 DLL 時會警告並退回 SendInput。 |
JE_AUTOCONTROL_LINUX_BACKEND |
x11 |
設成 uinput 時直接寫入核心輸入事件；/dev/uinput 無法寫入時會警告並退回 XTest。 |
JE_AUTOCONTROL_LINUX_DISPLAY_SERVER |
auto |
決定載入哪一個 Linux 後端：auto 讀取 XDG_SESSION_TYPE 與 WAYLAND_DISPLAY；wayland 或 x11 則強制指定（在 Wayland 工作階段設成 x11 只能操作 XWayland 視窗）。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_INTERCEPTION_DLL |
未設定：先找 PATH，再找套件旁邊 |
interception.dll 的完整路徑。 |
JE_AUTOCONTROL_INTERCEPTION_KEYBOARD |
1 |
鍵盤事件要送往的 Interception 裝置編號（1–10）。 |
JE_AUTOCONTROL_INTERCEPTION_MOUSE |
11 |
滑鼠事件要送往的 Interception 裝置編號（11–20）。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_WAYLAND_INPUT_BACKEND |
auto |
設成 cli 時透過 ydotool 送出輸入，完全不向桌面 portal 提出要求。這是啟動前就做好的選擇：使用者拒絕授權後，AutoControl 不會自行切換過去。 |
JE_AUTOCONTROL_WAYLAND_EI_WORKER |
未設定 | 設成 1 時把 libei 工作階段放到輔助行程裡執行，而不是放在本行程。 |
JE_AUTOCONTROL_WAYLAND_POINTER_ACCEL |
warn |
只影響 ydotool 路徑的絕對移動（那其實是會被合成器加速的相對位移）：warn 警告一次後照樣移動，flat 表示加速已關閉、不再警告，strict 直接拒絕移動。 |
JE_AUTOCONTROL_WAYLAND_CAPTURE_COMMAND |
未設定 | 自訂的截圖指令列，以 {output} 表示 PNG 的輸出路徑。優先於 grim、gnome-screenshot、spectacle 與 portal。 |
JE_AUTOCONTROL_WAYLAND_RECORD_DEVICES |
未設定：一個都不讀 | PhysicalRecorder 可以讀取的 /dev/input/event* 裝置（以逗號分隔）；實體輸入錄製必須逐一指定裝置才會啟用。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_MCP_READONLY |
未設定 | 設成 1 時只提供、也只能呼叫標示為唯讀的工具。 |
JE_AUTOCONTROL_MCP_TOOL_MODE |
full |
tools/list 要提供登錄表的多少內容：full、progressive 或 static。未知的值會報錯，不會被當成 full。 |
JE_AUTOCONTROL_MCP_TOOL_PROFILE |
未設定 | static 模式的工具清單：以逗號分隔的工具名稱與 category:<名稱>。 |
JE_AUTOCONTROL_MCP_ALIASES |
1 |
設成 0 時不註冊 ac_* 工具之外的簡短別名（click、screenshot …）。 |
JE_AUTOCONTROL_MCP_TOKEN |
未設定 | HTTP 傳輸的 Bearer 權杖。啟用 RBAC 之後不再接受。 |
JE_AUTOCONTROL_MCP_ALLOWED_ORIGINS |
未設定：只接受本機來源 | HTTP 傳輸額外接受的瀏覽器來源（以逗號分隔，須完全相符，例如 https://example.test:8443）。 |
JE_AUTOCONTROL_MCP_CONFIRM_DESTRUCTIVE |
未設定 | 設成 1 時具破壞性的工具在執行前先向用戶端要求確認（MCP elicitation）。 |
JE_AUTOCONTROL_MCP_PATH_ROOTS |
未設定：不限制 | 工具的每一個檔案參數都必須落在這些目錄內（以作業系統的路徑分隔字元分隔）。 |
JE_AUTOCONTROL_MCP_PATH_ROOTS_FROM_CLIENT |
未設定 | 設成 1 時同時接受 MCP 用戶端透過 roots/list 回報的根目錄。 |
JE_AUTOCONTROL_MCP_ENV_REF_ALLOW |
未設定：不限制 | ac_resolve_ref 可以讀取的環境變數名稱（以逗號分隔，可用 fnmatch 樣式）；設了卻沒有指名任何變數時，一個都不允許。 |
JE_AUTOCONTROL_MCP_AUDIT |
未設定 | JSON-lines 檔案的路徑，每一次 tools/call 寫入一筆記錄。 |
JE_AUTOCONTROL_MCP_ERROR_SHOTS |
未設定 | 工具每次失敗時存放截圖的目錄。 |
JE_AUTOCONTROL_FAKE_BACKEND |
未設定 | 設成 1 時 MCP 伺服器只在記憶體中記錄滑鼠、鍵盤與剪貼簿呼叫而不實際執行，供沒有顯示器的 CI 使用。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_RBAC_USERS |
未設定：沿用共用權杖 | 使用者檔案的路徑。設定它就等於為 REST API 與 MCP HTTP 傳輸啟用角色。 |
JE_AUTOCONTROL_CHATOPS_SCRIPT_ROOT |
未設定：run 會被拒絕 |
chat-ops 的 run 指令唯一可以載入動作檔的目錄。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_ALLOWED_PACKAGES |
未設定：一個都不允許 | AC_add_package_to_executor 可以載入的套件（以逗號分隔，含子模組），對所有進入點生效。只在行程啟動時讀取一次。 |
JE_AUTOCONTROL_REQUIRE_SIGNED_ACTIONS |
未設定 | 設成 1 時所有會執行動作檔的路徑，都拒絕沒有有效簽章檔的動作檔。 |
JE_AUTOCONTROL_ACTION_SIGNING_PRIVATE_KEY |
未設定 | Ed25519 私鑰（PEM）的路徑。只在負責簽署的機器上設定；設定後簽署會寫出第 2 版的簽章檔。 |
JE_AUTOCONTROL_ACTION_SIGNING_PUBLIC_KEY |
未設定 | 對應公鑰的路徑。在每一台執行端設定：它只能驗證，不能簽署。 |
JE_AUTOCONTROL_ACTION_SIGNING_PASSPHRASE |
未設定 | 私鑰建立時若有設定通行碼，在這裡提供。 |
JE_AUTOCONTROL_ACCEPT_LEGACY_ACTION_SIGNATURES |
未設定 | 設成 1 是遷移模式：設定公鑰之後，第 2 版之前寫出的 HMAC 簽章檔會被拒絕，除非設定了這個變數。所有檔案重新簽署後請再關掉。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_REMOTE_DOWNLOAD_DIR |
~/Downloads/AutoControl |
遠端桌面檢視端存放主機傳來檔案的目錄。收到的路徑一律限制在這個目錄內。 |
JE_AUTOCONTROL_USB_PASSTHROUGH |
未設定 | 設成 1 時在遠端桌面通道上啟用 USB 直通指令。 |
AC_SIGNALING_SECRET |
未設定 | 信令／設定同步伺服器的共用密鑰（X-Signaling-Secret）。伺服器在沒有 --shared-secret 時讀取它，config_sync_run 在沒有 secret 時也讀取它。 |
AC_SIGNALING_CONFIG_DB |
~/.je_auto_control/config_sync.sqlite3 |
信令伺服器存放設定同步資料的 SQLite 檔案。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_GUI_SETTINGS |
~/.je_auto_control/gui_settings.ini |
主視窗保存佈景主題、文字大小、導覽面板與視窗位置的檔案。設成 off、0、none、false 或空字串時，不讀也不寫。 |
| 變數 | 預設 | 作用 |
|---|---|---|
JE_AUTOCONTROL_LOG_FILE |
~/.je_auto_control/logs/AutoControlGUI.log |
記錄檔寫入的位置。指定空裝置（/dev/null、NUL）即可關閉檔案輸出。在寫入第一筆記錄時才讀取，而不是在 import 時。 |
JE_AUTOCONTROL_ENV |
default |
資產庫目前使用的環境（active_environment()），讓同一份腳本在 dev 與 prod 讀到不同的值。 |
JE_AUTOCONTROL_REDACTION |
off |
截圖遮蔽的預設政策：off、moderate 或 strict。未知的名稱會報錯，不會被當成 off。 |
JE_AUTOCONTROL_PYTEST_ARTIFACTS |
./autocontrol_screenshots |
測試沒有使用 autocontrol_screenshot_dir fixture 時，pytest 外掛寫入失敗截圖的目錄。 |
| 資源 | 內容 |
|---|---|
examples/ |
33 個自足腳本：截圖點擊、OCR、排程器、遠端桌面、agent loop、可觀測性、錄製、變數、熱鍵、觸發器、報表、MCP、REST、機密、外掛、computer use、Wayland、跨主機 DAG、chat-ops、pytest/BDD、錨點定位。 |
| Read the Docs | 完整 API 參考，含英文與中文。 |
| architecture_explore.md | 逐層記錄每個模組的職責。 |
| docs/CAPABILITY_MATRIX.md | 能力 × 平台對照矩陣。 |
| docs/API_LIFECYCLE.md | 穩定 API 與棄用政策。 |
| docs/updates/ | 更新紀錄：各版本說明與完成的工作，每月一個檔（原 WHATS_NEW.md）。 |
| CHANGELOG.md | 相容性變更記錄。 |
| SECURITY.md | 安全政策與回報方式。 |
git clone https://github.com/Integration-Automation/AutoControlGUI.git
cd AutoControl
pip install -r dev_requirements.txt
uv sync # 或：以已提交的 uv.lock 做可重現安裝python -m pytest test/unit_test/headless # 無頭單元測試
python -m pytest test/integrated_test/ # 跨模組流程測試
ruff check je_auto_control/
pylint je_auto_control/
bandit -c pyproject.toml -r je_auto_control/
python test/verify/typing_contract_verify.py # mypy，整個套件，三個目標平台
python test/verify/typing_contract_verify.py --extras # 同一項檢查，改用真正的 PySide6／aiortc 型別
python -m sphinx -b html -W docs/source docs/_build/html # 文件，警告視為錯誤歡迎貢獻——請見 CONTRIBUTING.md 與
CODE_OF_CONDUCT.md。CI 會強制兩條規則：import je_auto_control
絕不能載入 PySide6；每個功能都必須同時具備無頭 API 與 GUI 介面。
MIT License © JE-Chen。 內含與選用第三方元件的授權請見 Third_Party_License.md。