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 会话下运行。窗口管理支持
Windows、macOS（pyobjc）与 X11（含 XWayland）；纯 Wayland 会话的协议不让客户端看到其他程序的窗口，
所以 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。