From 97a6105bffc5e3aa1309732107e853a923d9b46e Mon Sep 17 00:00:00 2001
From: JeffreyChen <zenxcvwait@gmail.com>
Date: Sat, 4 Apr 2026 17:56:57 +0800
Subject: [PATCH] Update READMEs

---
 .gitignore             |   1 +
 README.md              | 555 ++++++++++++++++++++++++++++++++++++++---
 README/README_zh-CN.md | 543 ++++++++++++++++++++++++++++++++++++++++
 README/README_zh-TW.md | 543 ++++++++++++++++++++++++++++++++++++++++
 4 files changed, 1608 insertions(+), 34 deletions(-)
 create mode 100644 README/README_zh-CN.md
 create mode 100644 README/README_zh-TW.md

diff --git a/.gitignore b/.gitignore
index a97cc1f..3e4b078 100644
--- a/.gitignore
+++ b/.gitignore
@@ -124,3 +124,4 @@ dmypy.json
 .claude/settings.local.json
 /.claude/
 /.claude
+/.idea
diff --git a/README.md b/README.md
index cb9efe4..5c678c9 100644
--- a/README.md
+++ b/README.md
@@ -1,56 +1,543 @@
 # AutoControl
 
-AutoControl is a cross‑platform GUI automation framework that provides powerful and efficient features for mouse, keyboard, and image‑based automation.
+[![PyPI](https://img.shields.io/pypi/v/je_auto_control)](https://pypi.org/project/je_auto_control/)
+[![Python](https://img.shields.io/pypi/pyversions/je_auto_control)](https://pypi.org/project/je_auto_control/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**AutoControl** is a cross-platform Python GUI automation framework providing mouse control, keyboard input, image recognition, screen capture, action scripting, and report generation — all through a unified API that works on Windows, macOS, and Linux (X11).
+
+**[繁體中文](README/README_zh-TW.md)** | **[简体中文](README/README_zh-CN.md)**
+
+---
+
+## Table of Contents
+
+- [Features](#features)
+- [Architecture](#architecture)
+- [Installation](#installation)
+- [Requirements](#requirements)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [Mouse Control](#mouse-control)
+  - [Keyboard Control](#keyboard-control)
+  - [Image Recognition](#image-recognition)
+  - [Screen Operations](#screen-operations)
+  - [Action Recording & Playback](#action-recording--playback)
+  - [Action Scripting (JSON Executor)](#action-scripting-json-executor)
+  - [Report Generation](#report-generation)
+  - [Remote Automation (Socket Server)](#remote-automation-socket-server)
+  - [Shell Command Execution](#shell-command-execution)
+  - [Screen Recording](#screen-recording)
+  - [Callback Executor](#callback-executor)
+  - [Package Manager](#package-manager)
+  - [Project Management](#project-management)
+  - [Window Management](#window-management)
+  - [GUI Application](#gui-application)
+- [Command-Line Interface](#command-line-interface)
+- [Platform Support](#platform-support)
+- [Development](#development)
+- [License](#license)
+
+---
 
 ## Features
 
-* Powerful and practical GUI automation.
-* Image recognition (template matching).
-* Coordinate‑based operations.
-* Mouse automation.
-* Keyboard automation.
-* Locate images.
-* AutoControl scripting support.
-* Generate JSON / HTML / XML reports.
-* Remote automation support.
-* Shell command integration.
-* Screenshot support.
-* OS‑independent design.
-* Project & template management.
-
-## ⚠️ Notice
-Currently Unix/Linux Wayland GUI is not supported.
-This may be added as a future feature.
+- **Mouse Automation** — move, click, press, release, drag, and scroll with precise coordinate control
+- **Keyboard Automation** — press/release individual keys, type strings, hotkey combinations, key state detection
+- **Image Recognition** — locate UI elements on screen using OpenCV template matching with configurable threshold
+- **Screenshot & Screen Recording** — capture full screen or regions as images, record screen to video (AVI/MP4)
+- **Action Recording & Playback** — record mouse/keyboard events and replay them
+- **JSON-Based Action Scripting** — define and execute automation flows using JSON action files
+- **Report Generation** — export test records as HTML, JSON, or XML reports with success/failure status
+- **Remote Automation** — start a TCP socket server to receive and execute automation commands from remote clients
+- **Shell Integration** — execute shell commands within automation workflows with async output capture
+- **Callback Executor** — trigger automation functions with callback hooks for chaining operations
+- **Dynamic Package Loading** — extend the executor at runtime by importing external Python packages
+- **Project & Template Management** — scaffold automation projects with keyword/executor directory structure
+- **Window Management** — send keyboard/mouse events directly to specific windows (Windows/Linux)
+- **GUI Application** — built-in PySide6 graphical interface for interactive automation
+- **Cross-Platform** — unified API across Windows, macOS, and Linux (X11)
 
-## Installation
+---
+
+## Architecture
 
 ```
-# make sure you have install cmake libssl-dev (on linux)
+je_auto_control/
+├── wrapper/                    # Platform-agnostic API layer
+│   ├── platform_wrapper.py     # Auto-detects OS and loads the correct backend
+│   ├── auto_control_mouse.py   # Mouse operations
+│   ├── auto_control_keyboard.py# Keyboard operations
+│   ├── auto_control_image.py   # Image recognition (OpenCV template matching)
+│   ├── auto_control_screen.py  # Screenshot, screen size, pixel color
+│   └── auto_control_record.py  # Action recording/playback
+├── windows/                    # Windows-specific backend (Win32 API / ctypes)
+├── osx/                        # macOS-specific backend (pyobjc / Quartz)
+├── linux_with_x11/             # Linux-specific backend (python-Xlib)
+├── gui/                        # PySide6 GUI application
+└── utils/
+    ├── executor/               # JSON action executor engine
+    ├── callback/               # Callback function executor
+    ├── cv2_utils/              # OpenCV screenshot, template matching, video recording
+    ├── socket_server/          # TCP socket server for remote automation
+    ├── shell_process/          # Shell command manager
+    ├── generate_report/        # HTML / JSON / XML report generators
+    ├── test_record/            # Test action recording
+    ├── json/                   # JSON action file read/write
+    ├── project/                # Project scaffolding & templates
+    ├── package_manager/        # Dynamic package loading
+    ├── logging/                # Logging
+    └── exception/              # Custom exception classes
+```
+
+The `platform_wrapper.py` module automatically detects the current operating system and imports the corresponding backend, so all wrapper functions work identically regardless of platform.
+
+---
+
+## Installation
+
+### Basic Installation
+
+```bash
 pip install je_auto_control
 ```
 
-##  Requirements
+### With GUI Support (PySide6)
+
+```bash
+pip install je_auto_control[gui]
+```
+
+### Linux Prerequisites
+
+On Linux, install the following system packages before installing:
+
+```bash
+sudo apt-get install cmake libssl-dev
+```
+
+---
+
+## Requirements
+
+- **Python** >= 3.10
+- **pip** >= 19.3
+
+### Dependencies
+
+| Package | Purpose |
+|---|---|
+| `je_open_cv` | Image recognition (OpenCV template matching) |
+| `pillow` | Screenshot capture |
+| `mss` | Fast multi-monitor screenshot |
+| `pyobjc` | macOS backend (auto-installed on macOS) |
+| `python-Xlib` | Linux X11 backend (auto-installed on Linux) |
+| `PySide6` | GUI application (optional, install with `[gui]`) |
+| `qt-material` | GUI theme (optional, install with `[gui]`) |
+
+---
+
+## Quick Start
+
+### Mouse Control
+
+```python
+import je_auto_control
+
+# Get current mouse position
+x, y = je_auto_control.get_mouse_position()
+print(f"Mouse at: ({x}, {y})")
+
+# Move mouse to coordinates
+je_auto_control.set_mouse_position(500, 300)
+
+# Left click at current position (use key name)
+je_auto_control.click_mouse("mouse_left")
+
+# Right click at specific coordinates
+je_auto_control.click_mouse("mouse_right", x=800, y=400)
+
+# Scroll down
+je_auto_control.mouse_scroll(scroll_value=5)
+```
+
+### Keyboard Control
+
+```python
+import je_auto_control
+
+# Press and release a single key
+je_auto_control.type_keyboard("a")
+
+# Type a whole string character by character
+je_auto_control.write("Hello World")
+
+# Hotkey combination (e.g., Ctrl+C)
+je_auto_control.hotkey(["ctrl_l", "c"])
+
+# Check if a key is currently pressed
+is_pressed = je_auto_control.check_key_is_press("shift_l")
+```
+
+### Image Recognition
+
+```python
+import je_auto_control
+
+# Find all occurrences of an image on screen
+positions = je_auto_control.locate_all_image("button.png", detect_threshold=0.9)
+# Returns: [[x1, y1, x2, y2], ...]
+
+# Find a single image and get its center coordinates
+cx, cy = je_auto_control.locate_image_center("icon.png", detect_threshold=0.85)
+print(f"Found at: ({cx}, {cy})")
+
+# Find an image and automatically click it
+je_auto_control.locate_and_click("submit_button.png", mouse_keycode="mouse_left")
+```
+
+### Screenshot
+
+```python
+import je_auto_control
+
+# Take a full-screen screenshot and save to file
+je_auto_control.pil_screenshot("screenshot.png")
+
+# Take a screenshot of a specific region [x1, y1, x2, y2]
+je_auto_control.pil_screenshot("region.png", screen_region=[100, 100, 500, 400])
+
+# Get screen resolution
+width, height = je_auto_control.screen_size()
+
+# Get pixel color at coordinates
+color = je_auto_control.get_pixel(500, 300)
+```
+
+### Action Recording & Playback
+
+```python
+import je_auto_control
+import time
+
+# Start recording mouse and keyboard events
+je_auto_control.record()
+
+time.sleep(10)  # Record for 10 seconds
+
+# Stop recording and get the action list
+actions = je_auto_control.stop_record()
+
+# Replay the recorded actions
+je_auto_control.execute_action(actions)
+```
+
+### JSON Action Scripting
+
+Create a JSON action file (`actions.json`):
+
+```json
+[
+    ["AC_set_mouse_position", {"x": 500, "y": 300}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}],
+    ["AC_write", {"write_string": "Hello from AutoControl"}],
+    ["AC_screenshot", {"file_path": "result.png"}],
+    ["AC_hotkey", {"key_code_list": ["ctrl_l", "s"]}]
+]
+```
+
+Execute it:
+
+```python
+import je_auto_control
+
+# Execute from file
+je_auto_control.execute_action(je_auto_control.read_action_json("actions.json"))
+
+# Or execute from a list directly
+je_auto_control.execute_action([
+    ["AC_set_mouse_position", {"x": 100, "y": 200}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
+])
+```
+
+**Available action commands:**
+
+| Category | Commands |
+|---|---|
+| Mouse | `AC_click_mouse`, `AC_set_mouse_position`, `AC_get_mouse_position`, `AC_press_mouse`, `AC_release_mouse`, `AC_mouse_scroll`, `AC_mouse_left`, `AC_mouse_right`, `AC_mouse_middle` |
+| Keyboard | `AC_type_keyboard`, `AC_press_keyboard_key`, `AC_release_keyboard_key`, `AC_write`, `AC_hotkey`, `AC_check_key_is_press` |
+| Image | `AC_locate_all_image`, `AC_locate_image_center`, `AC_locate_and_click` |
+| Screen | `AC_screen_size`, `AC_screenshot` |
+| Record | `AC_record`, `AC_stop_record` |
+| Report | `AC_generate_html`, `AC_generate_json`, `AC_generate_xml`, `AC_generate_html_report`, `AC_generate_json_report`, `AC_generate_xml_report` |
+| Project | `AC_create_project` |
+| Shell | `AC_shell_command` |
+| Process | `AC_execute_process` |
+| Executor | `AC_execute_action`, `AC_execute_files` |
+
+### Report Generation
+
+```python
+import je_auto_control
+
+# Enable test recording first
+je_auto_control.test_record_instance.set_record_enable(True)
+
+# ... perform automation actions ...
+je_auto_control.set_mouse_position(100, 200)
+je_auto_control.click_mouse("mouse_left")
+
+# Generate reports
+je_auto_control.generate_html_report("test_report")   # -> test_report.html
+je_auto_control.generate_json_report("test_report")   # -> test_report.json
+je_auto_control.generate_xml_report("test_report")    # -> test_report.xml
+
+# Or get report content as string
+html_string = je_auto_control.generate_html()
+json_string = je_auto_control.generate_json()
+xml_string = je_auto_control.generate_xml()
+```
+
+Reports include: function name, parameters, timestamp, and exception info (if any) for each recorded action. HTML reports display successful actions in cyan and failed actions in red.
+
+### Remote Automation (Socket Server)
+
+Start a TCP server to receive JSON automation commands from remote clients:
+
+```python
+import je_auto_control
+
+# Start the server (default: localhost:9938)
+server = je_auto_control.start_autocontrol_socket_server(host="localhost", port=9938)
+
+# The server runs in a background thread
+# Send JSON action commands via TCP to execute remotely
+# Send "quit_server" to shut down
+```
+
+Client example:
+
+```python
+import socket
+import json
+
+sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+sock.connect(("localhost", 9938))
+
+# Send an automation command
+command = json.dumps([
+    ["AC_set_mouse_position", {"x": 500, "y": 300}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
+])
+sock.sendall(command.encode("utf-8"))
+
+# Receive response
+response = sock.recv(8192).decode("utf-8")
+print(response)
+sock.close()
+```
+
+### Shell Command Execution
+
+```python
+import je_auto_control
+
+# Using the default shell manager
+je_auto_control.default_shell_manager.exec_shell("echo Hello")
+je_auto_control.default_shell_manager.pull_text()  # Print captured output
+
+# Or create a custom ShellManager
+shell = je_auto_control.ShellManager(shell_encoding="utf-8")
+shell.exec_shell("ls -la")
+shell.pull_text()
+shell.exit_program()
+```
+
+### Screen Recording
+
+```python
+import je_auto_control
+import time
+
+# Method 1: ScreenRecorder (manages multiple recordings)
+recorder = je_auto_control.ScreenRecorder()
+recorder.start_new_record(
+    recorder_name="my_recording",
+    path_and_filename="output.avi",
+    codec="XVID",
+    frame_per_sec=30,
+    resolution=(1920, 1080)
+)
+time.sleep(10)
+recorder.stop_record("my_recording")
+
+# Method 2: RecordingThread (simple single recording, outputs MP4)
+recording = je_auto_control.RecordingThread(video_name="my_video", fps=20)
+recording.start()
+time.sleep(10)
+recording.stop()
+```
+
+### Callback Executor
+
+Execute an automation function and trigger a callback upon completion:
+
+```python
+import je_auto_control
+
+def my_callback():
+    print("Action completed!")
+
+# Execute set_mouse_position then call my_callback
+je_auto_control.callback_executor.callback_function(
+    trigger_function_name="AC_set_mouse_position",
+    callback_function=my_callback,
+    x=500, y=300
+)
+
+# With callback parameters
+def on_done(message):
+    print(f"Done: {message}")
+
+je_auto_control.callback_executor.callback_function(
+    trigger_function_name="AC_click_mouse",
+    callback_function=on_done,
+    callback_function_param={"message": "Click finished"},
+    callback_param_method="kwargs",
+    mouse_keycode="mouse_left"
+)
+```
+
+### Package Manager
+
+Dynamically load external Python packages into the executor at runtime:
+
+```python
+import je_auto_control
+
+# Add all functions/classes from a package to the executor
+je_auto_control.package_manager.add_package_to_executor("os")
+
+# Now you can use os functions in JSON action scripts:
+# ["os_getcwd", {}]
+# ["os_listdir", {"path": "."}]
+```
+
+### Project Management
+
+Scaffold a project directory structure with template files:
+
+```python
+import je_auto_control
+
+# Create a project structure
+je_auto_control.create_project_dir(project_path="./my_project", parent_name="AutoControl")
+
+# This creates:
+# my_project/
+# └── AutoControl/
+#     ├── keyword/
+#     │   ├── keyword1.json        # Template action file
+#     │   ├── keyword2.json        # Template action file
+#     │   └── bad_keyword_1.json   # Error handling template
+#     └── executor/
+#         ├── executor_one_file.py  # Execute single file example
+#         ├── executor_folder.py    # Execute folder example
+#         └── executor_bad_file.py  # Error handling example
+```
+
+### Window Management
+
+Send events directly to specific windows (Windows and Linux only):
+
+```python
+import je_auto_control
+
+# Send keyboard event to a window by title
+je_auto_control.send_key_event_to_window("Notepad", keycode="a")
+
+# Send mouse event to a window handle
+je_auto_control.send_mouse_event_to_window(window_handle, mouse_keycode="mouse_left", x=100, y=50)
+```
+
+### GUI Application
+
+Launch the built-in graphical interface (requires `[gui]` extra):
+
+```python
+import je_auto_control
+je_auto_control.start_autocontrol_gui()
+```
+
+Or from the command line:
+
+```bash
+python -m je_auto_control
+```
+
+---
 
-* Python 3.9 or later
-* pip 19.3 or later
+## Command-Line Interface
 
+AutoControl can be used directly from the command line:
+
+```bash
+# Execute a single action file
+python -m je_auto_control -e actions.json
+
+# Execute all action files in a directory
+python -m je_auto_control -d ./action_files/
+
+# Execute a JSON string directly
+python -m je_auto_control --execute_str '[["AC_screenshot", {"file_path": "test.png"}]]'
+
+# Create a project template
+python -m je_auto_control -c ./my_project
+```
 
+---
 
-## Development Environment
-* Windows 11
-* macOS 11 Big Sur
-* Ubuntu 20.04
+## Platform Support
 
-## Tested On
-* Windows 10 ~ 11
-* macOS 10.15 ~ 11 Big Sur
-* Ubuntu 20.04
-* Raspberry Pi 3B / 4B
+| Platform | Status | Backend | Notes |
+|---|---|---|---|
+| Windows 10 / 11 | Supported | Win32 API (ctypes) | Full feature support |
+| macOS 10.15+ | Supported | pyobjc / Quartz | Action recording not available; `send_key_event_to_window` / `send_mouse_event_to_window` not supported |
+| Linux (X11) | Supported | python-Xlib | Full feature support |
+| Linux (Wayland) | Not supported | — | May be added in a future release |
+| Raspberry Pi 3B / 4B | Supported | python-Xlib | Runs on X11 |
 
-## Setting Up Development Environment
-```commandline
+---
+
+## Development
+
+### Setting Up
+
+```bash
+git clone https://github.com/Intergration-Automation-Testing/AutoControl.git
+cd AutoControl
 pip install -r dev_requirements.txt
 ```
 
+### Running Tests
+
+```bash
+# Unit tests
+python -m pytest test/unit_test/
+
+# Integration tests
+python -m pytest test/integrated_test/
+```
+
+### Project Links
+
+- **Homepage**: https://github.com/Intergration-Automation-Testing/AutoControl
+- **Documentation**: https://autocontrol.readthedocs.io/en/latest/
+- **PyPI**: https://pypi.org/project/je_auto_control/
+
+---
 
+## License
 
+[MIT License](LICENSE) © JE-Chen
diff --git a/README/README_zh-CN.md b/README/README_zh-CN.md
new file mode 100644
index 0000000..71f4fc0
--- /dev/null
+++ b/README/README_zh-CN.md
@@ -0,0 +1,543 @@
+# AutoControl
+
+[![PyPI](https://img.shields.io/pypi/v/je_auto_control)](https://pypi.org/project/je_auto_control/)
+[![Python](https://img.shields.io/pypi/pyversions/je_auto_control)](https://pypi.org/project/je_auto_control/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+
+**AutoControl** 是一个跨平台的 Python GUI 自动化框架，提供鼠标控制、键盘输入、图像识别、屏幕捕获、脚本执行与报告生成等功能 — 通过统一的 API 在 Windows、macOS 和 Linux (X11) 上运行。
+
+**[English](../README.md)** | **[繁體中文](README_zh-TW.md)**
+
+---
+
+## 目录
+
+- [功能特性](#功能特性)
+- [架构](#架构)
+- [安装](#安装)
+- [系统要求](#系统要求)
+- [快速开始](#快速开始)
+- [API 参考](#api-参考)
+  - [鼠标控制](#鼠标控制)
+  - [键盘控制](#键盘控制)
+  - [图像识别](#图像识别)
+  - [屏幕操作](#屏幕操作)
+  - [动作录制与回放](#动作录制与回放)
+  - [JSON 脚本执行器](#json-脚本执行器)
+  - [报告生成](#报告生成)
+  - [远程自动化（Socket 服务器）](#远程自动化socket-服务器)
+  - [Shell 命令执行](#shell-命令执行)
+  - [屏幕录制](#屏幕录制)
+  - [回调执行器](#回调执行器)
+  - [包管理器](#包管理器)
+  - [项目管理](#项目管理)
+  - [窗口管理](#窗口管理)
+  - [GUI 应用程序](#gui-应用程序)
+- [命令行界面](#命令行界面)
+- [平台支持](#平台支持)
+- [开发](#开发)
+- [许可证](#许可证)
+
+---
+
+## 功能特性
+
+- **鼠标自动化** — 移动、点击、按下、释放、拖拽、滚动，支持精确坐标控制
+- **键盘自动化** — 按下/释放单一按键、输入字符串、组合键、按键状态检测
+- **图像识别** — 使用 OpenCV 模板匹配在屏幕上定位 UI 元素，支持可配置的检测阈值
+- **截图与屏幕录制** — 捕获全屏或指定区域为图片，录制屏幕为视频（AVI/MP4）
+- **动作录制与回放** — 录制鼠标/键盘事件并重新播放
+- **JSON 脚本执行** — 使用 JSON 动作文件定义并执行自动化流程
+- **报告生成** — 将测试记录导出为 HTML、JSON 或 XML 报告，包含成功/失败状态
+- **远程自动化** — 启动 TCP Socket 服务器，接收并执行来自远程客户端的自动化命令
+- **Shell 集成** — 在自动化流程中执行 Shell 命令，支持异步输出捕获
+- **回调执行器** — 触发自动化函数后自动调用回调函数，实现操作串联
+- **动态包加载** — 在运行时导入外部 Python 包，扩展执行器功能
+- **项目与模板管理** — 快速创建包含 keyword/executor 目录结构的自动化项目
+- **窗口管理** — 直接将键盘/鼠标事件发送至指定窗口（Windows/Linux）
+- **GUI 应用程序** — 内置 PySide6 图形界面，支持交互式自动化操作
+- **跨平台** — 统一 API，支持 Windows、macOS、Linux（X11）
+
+---
+
+## 架构
+
+```
+je_auto_control/
+├── wrapper/                    # 平台无关 API 层
+│   ├── platform_wrapper.py     # 自动检测操作系统并加载对应后端
+│   ├── auto_control_mouse.py   # 鼠标操作
+│   ├── auto_control_keyboard.py# 键盘操作
+│   ├── auto_control_image.py   # 图像识别（OpenCV 模板匹配）
+│   ├── auto_control_screen.py  # 截图、屏幕大小、像素颜色
+│   └── auto_control_record.py  # 动作录制/回放
+├── windows/                    # Windows 专用后端（Win32 API / ctypes）
+├── osx/                        # macOS 专用后端（pyobjc / Quartz）
+├── linux_with_x11/             # Linux 专用后端（python-Xlib）
+├── gui/                        # PySide6 GUI 应用程序
+└── utils/
+    ├── executor/               # JSON 动作执行引擎
+    ├── callback/               # 回调函数执行器
+    ├── cv2_utils/              # OpenCV 截图、模板匹配、视频录制
+    ├── socket_server/          # TCP Socket 服务器（远程自动化）
+    ├── shell_process/          # Shell 命令管理器
+    ├── generate_report/        # HTML / JSON / XML 报告生成器
+    ├── test_record/            # 测试动作记录
+    ├── json/                   # JSON 动作文件读写
+    ├── project/                # 项目创建与模板
+    ├── package_manager/        # 动态包加载
+    ├── logging/                # 日志记录
+    └── exception/              # 自定义异常类
+```
+
+`platform_wrapper.py` 模块会自动检测当前的操作系统并导入对应的后端，因此所有 wrapper 函数在不同平台上的行为完全一致。
+
+---
+
+## 安装
+
+### 基本安装
+
+```bash
+pip install je_auto_control
+```
+
+### 安装 GUI 支持（PySide6）
+
+```bash
+pip install je_auto_control[gui]
+```
+
+### Linux 前置要求
+
+在 Linux 上安装前，请先安装以下系统包：
+
+```bash
+sudo apt-get install cmake libssl-dev
+```
+
+---
+
+## 系统要求
+
+- **Python** >= 3.10
+- **pip** >= 19.3
+
+### 依赖包
+
+| 包 | 用途 |
+|---|---|
+| `je_open_cv` | 图像识别（OpenCV 模板匹配） |
+| `pillow` | 截图捕获 |
+| `mss` | 快速多屏幕截图 |
+| `pyobjc` | macOS 后端（在 macOS 上自动安装） |
+| `python-Xlib` | Linux X11 后端（在 Linux 上自动安装） |
+| `PySide6` | GUI 应用程序（可选，使用 `[gui]` 安装） |
+| `qt-material` | GUI 主题（可选，使用 `[gui]` 安装） |
+
+---
+
+## 快速开始
+
+### 鼠标控制
+
+```python
+import je_auto_control
+
+# 获取当前鼠标位置
+x, y = je_auto_control.get_mouse_position()
+print(f"鼠标位置: ({x}, {y})")
+
+# 移动鼠标到指定坐标
+je_auto_control.set_mouse_position(500, 300)
+
+# 在当前位置左键点击（使用按键名称）
+je_auto_control.click_mouse("mouse_left")
+
+# 在指定坐标右键点击
+je_auto_control.click_mouse("mouse_right", x=800, y=400)
+
+# 向下滚动
+je_auto_control.mouse_scroll(scroll_value=5)
+```
+
+### 键盘控制
+
+```python
+import je_auto_control
+
+# 按下并释放单一按键
+je_auto_control.type_keyboard("a")
+
+# 逐字输入整个字符串
+je_auto_control.write("Hello World")
+
+# 组合键（例如 Ctrl+C）
+je_auto_control.hotkey(["ctrl_l", "c"])
+
+# 检查某个按键是否正在被按下
+is_pressed = je_auto_control.check_key_is_press("shift_l")
+```
+
+### 图像识别
+
+```python
+import je_auto_control
+
+# 在屏幕上找出所有匹配的图像
+positions = je_auto_control.locate_all_image("button.png", detect_threshold=0.9)
+# 返回: [[x1, y1, x2, y2], ...]
+
+# 找出单一图像并获取其中心坐标
+cx, cy = je_auto_control.locate_image_center("icon.png", detect_threshold=0.85)
+print(f"找到位置: ({cx}, {cy})")
+
+# 找出图像并自动点击
+je_auto_control.locate_and_click("submit_button.png", mouse_keycode="mouse_left")
+```
+
+### 截图
+
+```python
+import je_auto_control
+
+# 捕获全屏截图并保存
+je_auto_control.pil_screenshot("screenshot.png")
+
+# 捕获指定区域的截图 [x1, y1, x2, y2]
+je_auto_control.pil_screenshot("region.png", screen_region=[100, 100, 500, 400])
+
+# 获取屏幕分辨率
+width, height = je_auto_control.screen_size()
+
+# 获取指定坐标的像素颜色
+color = je_auto_control.get_pixel(500, 300)
+```
+
+### 动作录制与回放
+
+```python
+import je_auto_control
+import time
+
+# 开始录制鼠标和键盘事件
+je_auto_control.record()
+
+time.sleep(10)  # 录制 10 秒
+
+# 停止录制并获取动作列表
+actions = je_auto_control.stop_record()
+
+# 重新播放录制的动作
+je_auto_control.execute_action(actions)
+```
+
+### JSON 脚本执行器
+
+创建 JSON 动作文件（`actions.json`）：
+
+```json
+[
+    ["AC_set_mouse_position", {"x": 500, "y": 300}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}],
+    ["AC_write", {"write_string": "Hello from AutoControl"}],
+    ["AC_screenshot", {"file_path": "result.png"}],
+    ["AC_hotkey", {"key_code_list": ["ctrl_l", "s"]}]
+]
+```
+
+执行方式：
+
+```python
+import je_auto_control
+
+# 从文件执行
+je_auto_control.execute_action(je_auto_control.read_action_json("actions.json"))
+
+# 或直接从列表执行
+je_auto_control.execute_action([
+    ["AC_set_mouse_position", {"x": 100, "y": 200}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
+])
+```
+
+**可用的动作命令：**
+
+| 类别 | 命令 |
+|---|---|
+| 鼠标 | `AC_click_mouse`, `AC_set_mouse_position`, `AC_get_mouse_position`, `AC_press_mouse`, `AC_release_mouse`, `AC_mouse_scroll`, `AC_mouse_left`, `AC_mouse_right`, `AC_mouse_middle` |
+| 键盘 | `AC_type_keyboard`, `AC_press_keyboard_key`, `AC_release_keyboard_key`, `AC_write`, `AC_hotkey`, `AC_check_key_is_press` |
+| 图像 | `AC_locate_all_image`, `AC_locate_image_center`, `AC_locate_and_click` |
+| 屏幕 | `AC_screen_size`, `AC_screenshot` |
+| 录制 | `AC_record`, `AC_stop_record` |
+| 报告 | `AC_generate_html`, `AC_generate_json`, `AC_generate_xml`, `AC_generate_html_report`, `AC_generate_json_report`, `AC_generate_xml_report` |
+| 项目 | `AC_create_project` |
+| Shell | `AC_shell_command` |
+| 进程 | `AC_execute_process` |
+| 执行器 | `AC_execute_action`, `AC_execute_files` |
+
+### 报告生成
+
+```python
+import je_auto_control
+
+# 先启用测试记录
+je_auto_control.test_record_instance.set_record_enable(True)
+
+# ... 执行自动化动作 ...
+je_auto_control.set_mouse_position(100, 200)
+je_auto_control.click_mouse("mouse_left")
+
+# 生成报告
+je_auto_control.generate_html_report("test_report")   # -> test_report.html
+je_auto_control.generate_json_report("test_report")   # -> test_report.json
+je_auto_control.generate_xml_report("test_report")    # -> test_report.xml
+
+# 或获取报告内容为字符串
+html_string = je_auto_control.generate_html()
+json_string = je_auto_control.generate_json()
+xml_string = je_auto_control.generate_xml()
+```
+
+报告内容包含：每个记录动作的函数名称、参数、时间戳及异常信息（如有）。HTML 报告中成功的动作以青色显示，失败的动作以红色显示。
+
+### 远程自动化（Socket 服务器）
+
+启动 TCP 服务器，接收来自远程客户端的 JSON 自动化命令：
+
+```python
+import je_auto_control
+
+# 启动服务器（默认：localhost:9938）
+server = je_auto_control.start_autocontrol_socket_server(host="localhost", port=9938)
+
+# 服务器在后台线程中运行
+# 通过 TCP 发送 JSON 动作命令即可远程执行
+# 发送 "quit_server" 关闭服务器
+```
+
+客户端示例：
+
+```python
+import socket
+import json
+
+sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+sock.connect(("localhost", 9938))
+
+# 发送自动化命令
+command = json.dumps([
+    ["AC_set_mouse_position", {"x": 500, "y": 300}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
+])
+sock.sendall(command.encode("utf-8"))
+
+# 接收响应
+response = sock.recv(8192).decode("utf-8")
+print(response)
+sock.close()
+```
+
+### Shell 命令执行
+
+```python
+import je_auto_control
+
+# 使用默认的 Shell 管理器
+je_auto_control.default_shell_manager.exec_shell("echo Hello")
+je_auto_control.default_shell_manager.pull_text()  # 输出捕获的结果
+
+# 或创建自定义的 ShellManager
+shell = je_auto_control.ShellManager(shell_encoding="utf-8")
+shell.exec_shell("ls -la")
+shell.pull_text()
+shell.exit_program()
+```
+
+### 屏幕录制
+
+```python
+import je_auto_control
+import time
+
+# 方法一：ScreenRecorder（管理多个录像）
+recorder = je_auto_control.ScreenRecorder()
+recorder.start_new_record(
+    recorder_name="my_recording",
+    path_and_filename="output.avi",
+    codec="XVID",
+    frame_per_sec=30,
+    resolution=(1920, 1080)
+)
+time.sleep(10)
+recorder.stop_record("my_recording")
+
+# 方法二：RecordingThread（简易单一录像，输出 MP4）
+recording = je_auto_control.RecordingThread(video_name="my_video", fps=20)
+recording.start()
+time.sleep(10)
+recording.stop()
+```
+
+### 回调执行器
+
+执行自动化函数后自动触发回调函数：
+
+```python
+import je_auto_control
+
+def my_callback():
+    print("动作完成！")
+
+# 执行 set_mouse_position 后调用 my_callback
+je_auto_control.callback_executor.callback_function(
+    trigger_function_name="AC_set_mouse_position",
+    callback_function=my_callback,
+    x=500, y=300
+)
+
+# 带有参数的回调
+def on_done(message):
+    print(f"完成: {message}")
+
+je_auto_control.callback_executor.callback_function(
+    trigger_function_name="AC_click_mouse",
+    callback_function=on_done,
+    callback_function_param={"message": "点击完成"},
+    callback_param_method="kwargs",
+    mouse_keycode="mouse_left"
+)
+```
+
+### 包管理器
+
+在运行时动态加载外部 Python 包到执行器中：
+
+```python
+import je_auto_control
+
+# 将包的所有函数/类加入执行器
+je_auto_control.package_manager.add_package_to_executor("os")
+
+# 现在可以在 JSON 动作脚本中使用 os 函数：
+# ["os_getcwd", {}]
+# ["os_listdir", {"path": "."}]
+```
+
+### 项目管理
+
+快速创建包含模板文件的项目目录结构：
+
+```python
+import je_auto_control
+
+# 创建项目结构
+je_auto_control.create_project_dir(project_path="./my_project", parent_name="AutoControl")
+
+# 会创建以下结构：
+# my_project/
+# └── AutoControl/
+#     ├── keyword/
+#     │   ├── keyword1.json        # 模板动作文件
+#     │   ├── keyword2.json        # 模板动作文件
+#     │   └── bad_keyword_1.json   # 错误处理模板
+#     └── executor/
+#         ├── executor_one_file.py  # 执行单一文件示例
+#         ├── executor_folder.py    # 执行文件夹示例
+#         └── executor_bad_file.py  # 错误处理示例
+```
+
+### 窗口管理
+
+直接将事件发送至指定窗口（仅限 Windows 和 Linux）：
+
+```python
+import je_auto_control
+
+# 通过窗口标题发送键盘事件
+je_auto_control.send_key_event_to_window("Notepad", keycode="a")
+
+# 通过窗口 handle 发送鼠标事件
+je_auto_control.send_mouse_event_to_window(window_handle, mouse_keycode="mouse_left", x=100, y=50)
+```
+
+### GUI 应用程序
+
+启动内置图形界面（需安装 `[gui]` 扩展）：
+
+```python
+import je_auto_control
+je_auto_control.start_autocontrol_gui()
+```
+
+或通过命令行：
+
+```bash
+python -m je_auto_control
+```
+
+---
+
+## 命令行界面
+
+AutoControl 可直接从命令行使用：
+
+```bash
+# 执行单一动作文件
+python -m je_auto_control -e actions.json
+
+# 执行目录中所有动作文件
+python -m je_auto_control -d ./action_files/
+
+# 直接执行 JSON 字符串
+python -m je_auto_control --execute_str '[["AC_screenshot", {"file_path": "test.png"}]]'
+
+# 创建项目模板
+python -m je_auto_control -c ./my_project
+```
+
+---
+
+## 平台支持
+
+| 平台 | 状态 | 后端 | 备注 |
+|---|---|---|---|
+| Windows 10 / 11 | 支持 | Win32 API (ctypes) | 完整功能支持 |
+| macOS 10.15+ | 支持 | pyobjc / Quartz | 不支持动作录制；不支持 `send_key_event_to_window` / `send_mouse_event_to_window` |
+| Linux（X11） | 支持 | python-Xlib | 完整功能支持 |
+| Linux（Wayland） | 暂不支持 | — | 未来版本可能加入支持 |
+| Raspberry Pi 3B / 4B | 支持 | python-Xlib | 在 X11 上运行 |
+
+---
+
+## 开发
+
+### 环境配置
+
+```bash
+git clone https://github.com/Intergration-Automation-Testing/AutoControl.git
+cd AutoControl
+pip install -r dev_requirements.txt
+```
+
+### 运行测试
+
+```bash
+# 单元测试
+python -m pytest test/unit_test/
+
+# 集成测试
+python -m pytest test/integrated_test/
+```
+
+### 项目链接
+
+- **主页**: https://github.com/Intergration-Automation-Testing/AutoControl
+- **文档**: https://autocontrol.readthedocs.io/en/latest/
+- **PyPI**: https://pypi.org/project/je_auto_control/
+
+---
+
+## 许可证
+
+[MIT License](../LICENSE) © JE-Chen
diff --git a/README/README_zh-TW.md b/README/README_zh-TW.md
new file mode 100644
index 0000000..817235c
--- /dev/null
+++ b/README/README_zh-TW.md
@@ -0,0 +1,543 @@
+# AutoControl
+
+[![PyPI](https://img.shields.io/pypi/v/je_auto_control)](https://pypi.org/project/je_auto_control/)
+[![Python](https://img.shields.io/pypi/pyversions/je_auto_control)](https://pypi.org/project/je_auto_control/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](../LICENSE)
+
+**AutoControl** 是一個跨平台的 Python GUI 自動化框架，提供滑鼠控制、鍵盤輸入、圖像辨識、螢幕擷取、腳本執行與報告產生等功能 — 透過統一的 API 在 Windows、macOS 和 Linux (X11) 上運作。
+
+**[English](../README.md)** | **[简体中文](README_zh-CN.md)**
+
+---
+
+## 目錄
+
+- [功能特色](#功能特色)
+- [架構](#架構)
+- [安裝](#安裝)
+- [系統需求](#系統需求)
+- [快速開始](#快速開始)
+- [API 參考](#api-參考)
+  - [滑鼠控制](#滑鼠控制)
+  - [鍵盤控制](#鍵盤控制)
+  - [圖像辨識](#圖像辨識)
+  - [螢幕操作](#螢幕操作)
+  - [動作錄製與回放](#動作錄製與回放)
+  - [JSON 腳本執行器](#json-腳本執行器)
+  - [報告產生](#報告產生)
+  - [遠端自動化（Socket 伺服器）](#遠端自動化socket-伺服器)
+  - [Shell 命令執行](#shell-命令執行)
+  - [螢幕錄製](#螢幕錄製)
+  - [回呼執行器](#回呼執行器)
+  - [套件管理器](#套件管理器)
+  - [專案管理](#專案管理)
+  - [視窗管理](#視窗管理)
+  - [GUI 應用程式](#gui-應用程式)
+- [命令列介面](#命令列介面)
+- [平台支援](#平台支援)
+- [開發](#開發)
+- [授權條款](#授權條款)
+
+---
+
+## 功能特色
+
+- **滑鼠自動化** — 移動、點擊、按下、釋放、拖曳、滾動，支援精確座標控制
+- **鍵盤自動化** — 按下/釋放單一按鍵、輸入字串、組合鍵、按鍵狀態偵測
+- **圖像辨識** — 使用 OpenCV 模板匹配在螢幕上定位 UI 元素，支援可設定的偵測閾值
+- **截圖與螢幕錄製** — 擷取全螢幕或指定區域為圖片，錄製螢幕為影片（AVI/MP4）
+- **動作錄製與回放** — 錄製滑鼠/鍵盤事件並重新播放
+- **JSON 腳本執行** — 使用 JSON 動作檔案定義並執行自動化流程
+- **報告產生** — 將測試紀錄匯出為 HTML、JSON 或 XML 報告，包含成功/失敗狀態
+- **遠端自動化** — 啟動 TCP Socket 伺服器，接收並執行來自遠端客戶端的自動化命令
+- **Shell 整合** — 在自動化流程中執行 Shell 命令，支援非同步輸出擷取
+- **回呼執行器** — 觸發自動化函式後自動呼叫回呼函式，實現操作串接
+- **動態套件載入** — 在執行時匯入外部 Python 套件，擴充執行器功能
+- **專案與範本管理** — 快速建立包含 keyword/executor 目錄結構的自動化專案
+- **視窗管理** — 直接將鍵盤/滑鼠事件送至指定視窗（Windows/Linux）
+- **GUI 應用程式** — 內建 PySide6 圖形介面，支援互動式自動化操作
+- **跨平台** — 統一 API，支援 Windows、macOS、Linux（X11）
+
+---
+
+## 架構
+
+```
+je_auto_control/
+├── wrapper/                    # 平台無關 API 層
+│   ├── platform_wrapper.py     # 自動偵測作業系統並載入對應後端
+│   ├── auto_control_mouse.py   # 滑鼠操作
+│   ├── auto_control_keyboard.py# 鍵盤操作
+│   ├── auto_control_image.py   # 圖像辨識（OpenCV 模板匹配）
+│   ├── auto_control_screen.py  # 截圖、螢幕大小、像素顏色
+│   └── auto_control_record.py  # 動作錄製/回放
+├── windows/                    # Windows 專用後端（Win32 API / ctypes）
+├── osx/                        # macOS 專用後端（pyobjc / Quartz）
+├── linux_with_x11/             # Linux 專用後端（python-Xlib）
+├── gui/                        # PySide6 GUI 應用程式
+└── utils/
+    ├── executor/               # JSON 動作執行引擎
+    ├── callback/               # 回呼函式執行器
+    ├── cv2_utils/              # OpenCV 截圖、模板匹配、影片錄製
+    ├── socket_server/          # TCP Socket 伺服器（遠端自動化）
+    ├── shell_process/          # Shell 命令管理器
+    ├── generate_report/        # HTML / JSON / XML 報告產生器
+    ├── test_record/            # 測試動作紀錄
+    ├── json/                   # JSON 動作檔案讀寫
+    ├── project/                # 專案建立與範本
+    ├── package_manager/        # 動態套件載入
+    ├── logging/                # 日誌紀錄
+    └── exception/              # 自訂例外類別
+```
+
+`platform_wrapper.py` 模組會自動偵測目前的作業系統並匯入對應的後端，因此所有 wrapper 函式在不同平台上的行為完全一致。
+
+---
+
+## 安裝
+
+### 基本安裝
+
+```bash
+pip install je_auto_control
+```
+
+### 安裝 GUI 支援（PySide6）
+
+```bash
+pip install je_auto_control[gui]
+```
+
+### Linux 前置需求
+
+在 Linux 上安裝前，請先安裝以下系統套件：
+
+```bash
+sudo apt-get install cmake libssl-dev
+```
+
+---
+
+## 系統需求
+
+- **Python** >= 3.10
+- **pip** >= 19.3
+
+### 相依套件
+
+| 套件 | 用途 |
+|---|---|
+| `je_open_cv` | 圖像辨識（OpenCV 模板匹配） |
+| `pillow` | 截圖擷取 |
+| `mss` | 快速多螢幕截圖 |
+| `pyobjc` | macOS 後端（在 macOS 上自動安裝） |
+| `python-Xlib` | Linux X11 後端（在 Linux 上自動安裝） |
+| `PySide6` | GUI 應用程式（選用，使用 `[gui]` 安裝） |
+| `qt-material` | GUI 主題（選用，使用 `[gui]` 安裝） |
+
+---
+
+## 快速開始
+
+### 滑鼠控制
+
+```python
+import je_auto_control
+
+# 取得目前滑鼠位置
+x, y = je_auto_control.get_mouse_position()
+print(f"滑鼠位置: ({x}, {y})")
+
+# 移動滑鼠到指定座標
+je_auto_control.set_mouse_position(500, 300)
+
+# 在目前位置左鍵點擊（使用按鍵名稱）
+je_auto_control.click_mouse("mouse_left")
+
+# 在指定座標右鍵點擊
+je_auto_control.click_mouse("mouse_right", x=800, y=400)
+
+# 向下滾動
+je_auto_control.mouse_scroll(scroll_value=5)
+```
+
+### 鍵盤控制
+
+```python
+import je_auto_control
+
+# 按下並釋放單一按鍵
+je_auto_control.type_keyboard("a")
+
+# 逐字輸入整個字串
+je_auto_control.write("Hello World")
+
+# 組合鍵（例如 Ctrl+C）
+je_auto_control.hotkey(["ctrl_l", "c"])
+
+# 檢查某個按鍵是否正在被按下
+is_pressed = je_auto_control.check_key_is_press("shift_l")
+```
+
+### 圖像辨識
+
+```python
+import je_auto_control
+
+# 在螢幕上找出所有符合的圖像
+positions = je_auto_control.locate_all_image("button.png", detect_threshold=0.9)
+# 回傳: [[x1, y1, x2, y2], ...]
+
+# 找出單一圖像並取得其中心座標
+cx, cy = je_auto_control.locate_image_center("icon.png", detect_threshold=0.85)
+print(f"找到位置: ({cx}, {cy})")
+
+# 找出圖像並自動點擊
+je_auto_control.locate_and_click("submit_button.png", mouse_keycode="mouse_left")
+```
+
+### 截圖
+
+```python
+import je_auto_control
+
+# 擷取全螢幕截圖並儲存
+je_auto_control.pil_screenshot("screenshot.png")
+
+# 擷取指定區域的截圖 [x1, y1, x2, y2]
+je_auto_control.pil_screenshot("region.png", screen_region=[100, 100, 500, 400])
+
+# 取得螢幕解析度
+width, height = je_auto_control.screen_size()
+
+# 取得指定座標的像素顏色
+color = je_auto_control.get_pixel(500, 300)
+```
+
+### 動作錄製與回放
+
+```python
+import je_auto_control
+import time
+
+# 開始錄製滑鼠和鍵盤事件
+je_auto_control.record()
+
+time.sleep(10)  # 錄製 10 秒
+
+# 停止錄製並取得動作列表
+actions = je_auto_control.stop_record()
+
+# 重新播放錄製的動作
+je_auto_control.execute_action(actions)
+```
+
+### JSON 腳本執行器
+
+建立 JSON 動作檔案（`actions.json`）：
+
+```json
+[
+    ["AC_set_mouse_position", {"x": 500, "y": 300}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}],
+    ["AC_write", {"write_string": "Hello from AutoControl"}],
+    ["AC_screenshot", {"file_path": "result.png"}],
+    ["AC_hotkey", {"key_code_list": ["ctrl_l", "s"]}]
+]
+```
+
+執行方式：
+
+```python
+import je_auto_control
+
+# 從檔案執行
+je_auto_control.execute_action(je_auto_control.read_action_json("actions.json"))
+
+# 或直接從列表執行
+je_auto_control.execute_action([
+    ["AC_set_mouse_position", {"x": 100, "y": 200}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
+])
+```
+
+**可用的動作命令：**
+
+| 類別 | 命令 |
+|---|---|
+| 滑鼠 | `AC_click_mouse`, `AC_set_mouse_position`, `AC_get_mouse_position`, `AC_press_mouse`, `AC_release_mouse`, `AC_mouse_scroll`, `AC_mouse_left`, `AC_mouse_right`, `AC_mouse_middle` |
+| 鍵盤 | `AC_type_keyboard`, `AC_press_keyboard_key`, `AC_release_keyboard_key`, `AC_write`, `AC_hotkey`, `AC_check_key_is_press` |
+| 圖像 | `AC_locate_all_image`, `AC_locate_image_center`, `AC_locate_and_click` |
+| 螢幕 | `AC_screen_size`, `AC_screenshot` |
+| 錄製 | `AC_record`, `AC_stop_record` |
+| 報告 | `AC_generate_html`, `AC_generate_json`, `AC_generate_xml`, `AC_generate_html_report`, `AC_generate_json_report`, `AC_generate_xml_report` |
+| 專案 | `AC_create_project` |
+| Shell | `AC_shell_command` |
+| 程序 | `AC_execute_process` |
+| 執行器 | `AC_execute_action`, `AC_execute_files` |
+
+### 報告產生
+
+```python
+import je_auto_control
+
+# 先啟用測試紀錄
+je_auto_control.test_record_instance.set_record_enable(True)
+
+# ... 執行自動化動作 ...
+je_auto_control.set_mouse_position(100, 200)
+je_auto_control.click_mouse("mouse_left")
+
+# 產生報告
+je_auto_control.generate_html_report("test_report")   # -> test_report.html
+je_auto_control.generate_json_report("test_report")   # -> test_report.json
+je_auto_control.generate_xml_report("test_report")    # -> test_report.xml
+
+# 或取得報告內容為字串
+html_string = je_auto_control.generate_html()
+json_string = je_auto_control.generate_json()
+xml_string = je_auto_control.generate_xml()
+```
+
+報告內容包含：每個紀錄動作的函式名稱、參數、時間戳記及例外資訊（如有）。HTML 報告中成功的動作以青色顯示，失敗的動作以紅色顯示。
+
+### 遠端自動化（Socket 伺服器）
+
+啟動 TCP 伺服器，接收來自遠端客戶端的 JSON 自動化命令：
+
+```python
+import je_auto_control
+
+# 啟動伺服器（預設：localhost:9938）
+server = je_auto_control.start_autocontrol_socket_server(host="localhost", port=9938)
+
+# 伺服器在背景執行緒中運行
+# 透過 TCP 發送 JSON 動作命令即可遠端執行
+# 發送 "quit_server" 關閉伺服器
+```
+
+客戶端範例：
+
+```python
+import socket
+import json
+
+sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+sock.connect(("localhost", 9938))
+
+# 發送自動化命令
+command = json.dumps([
+    ["AC_set_mouse_position", {"x": 500, "y": 300}],
+    ["AC_click_mouse", {"mouse_keycode": "mouse_left"}]
+])
+sock.sendall(command.encode("utf-8"))
+
+# 接收回應
+response = sock.recv(8192).decode("utf-8")
+print(response)
+sock.close()
+```
+
+### Shell 命令執行
+
+```python
+import je_auto_control
+
+# 使用預設的 Shell 管理器
+je_auto_control.default_shell_manager.exec_shell("echo Hello")
+je_auto_control.default_shell_manager.pull_text()  # 輸出擷取的結果
+
+# 或建立自訂的 ShellManager
+shell = je_auto_control.ShellManager(shell_encoding="utf-8")
+shell.exec_shell("ls -la")
+shell.pull_text()
+shell.exit_program()
+```
+
+### 螢幕錄製
+
+```python
+import je_auto_control
+import time
+
+# 方法一：ScreenRecorder（管理多個錄影）
+recorder = je_auto_control.ScreenRecorder()
+recorder.start_new_record(
+    recorder_name="my_recording",
+    path_and_filename="output.avi",
+    codec="XVID",
+    frame_per_sec=30,
+    resolution=(1920, 1080)
+)
+time.sleep(10)
+recorder.stop_record("my_recording")
+
+# 方法二：RecordingThread（簡易單一錄影，輸出 MP4）
+recording = je_auto_control.RecordingThread(video_name="my_video", fps=20)
+recording.start()
+time.sleep(10)
+recording.stop()
+```
+
+### 回呼執行器
+
+執行自動化函式後自動觸發回呼函式：
+
+```python
+import je_auto_control
+
+def my_callback():
+    print("動作完成！")
+
+# 執行 set_mouse_position 後呼叫 my_callback
+je_auto_control.callback_executor.callback_function(
+    trigger_function_name="AC_set_mouse_position",
+    callback_function=my_callback,
+    x=500, y=300
+)
+
+# 帶有參數的回呼
+def on_done(message):
+    print(f"完成: {message}")
+
+je_auto_control.callback_executor.callback_function(
+    trigger_function_name="AC_click_mouse",
+    callback_function=on_done,
+    callback_function_param={"message": "點擊完成"},
+    callback_param_method="kwargs",
+    mouse_keycode="mouse_left"
+)
+```
+
+### 套件管理器
+
+在執行時動態載入外部 Python 套件到執行器中：
+
+```python
+import je_auto_control
+
+# 將套件的所有函式/類別加入執行器
+je_auto_control.package_manager.add_package_to_executor("os")
+
+# 現在可以在 JSON 動作腳本中使用 os 函式：
+# ["os_getcwd", {}]
+# ["os_listdir", {"path": "."}]
+```
+
+### 專案管理
+
+快速建立包含範本檔案的專案目錄結構：
+
+```python
+import je_auto_control
+
+# 建立專案結構
+je_auto_control.create_project_dir(project_path="./my_project", parent_name="AutoControl")
+
+# 會建立以下結構：
+# my_project/
+# └── AutoControl/
+#     ├── keyword/
+#     │   ├── keyword1.json        # 範本動作檔案
+#     │   ├── keyword2.json        # 範本動作檔案
+#     │   └── bad_keyword_1.json   # 錯誤處理範本
+#     └── executor/
+#         ├── executor_one_file.py  # 執行單一檔案範例
+#         ├── executor_folder.py    # 執行資料夾範例
+#         └── executor_bad_file.py  # 錯誤處理範例
+```
+
+### 視窗管理
+
+直接將事件送至指定視窗（僅限 Windows 和 Linux）：
+
+```python
+import je_auto_control
+
+# 透過視窗標題送出鍵盤事件
+je_auto_control.send_key_event_to_window("Notepad", keycode="a")
+
+# 透過視窗 handle 送出滑鼠事件
+je_auto_control.send_mouse_event_to_window(window_handle, mouse_keycode="mouse_left", x=100, y=50)
+```
+
+### GUI 應用程式
+
+啟動內建圖形介面（需安裝 `[gui]` 擴充）：
+
+```python
+import je_auto_control
+je_auto_control.start_autocontrol_gui()
+```
+
+或透過命令列：
+
+```bash
+python -m je_auto_control
+```
+
+---
+
+## 命令列介面
+
+AutoControl 可直接從命令列使用：
+
+```bash
+# 執行單一動作檔案
+python -m je_auto_control -e actions.json
+
+# 執行目錄中所有動作檔案
+python -m je_auto_control -d ./action_files/
+
+# 直接執行 JSON 字串
+python -m je_auto_control --execute_str '[["AC_screenshot", {"file_path": "test.png"}]]'
+
+# 建立專案範本
+python -m je_auto_control -c ./my_project
+```
+
+---
+
+## 平台支援
+
+| 平台 | 狀態 | 後端 | 備註 |
+|---|---|---|---|
+| Windows 10 / 11 | 支援 | Win32 API (ctypes) | 完整功能支援 |
+| macOS 10.15+ | 支援 | pyobjc / Quartz | 不支援動作錄製；不支援 `send_key_event_to_window` / `send_mouse_event_to_window` |
+| Linux（X11） | 支援 | python-Xlib | 完整功能支援 |
+| Linux（Wayland） | 尚未支援 | — | 未來版本可能加入支援 |
+| Raspberry Pi 3B / 4B | 支援 | python-Xlib | 在 X11 上運行 |
+
+---
+
+## 開發
+
+### 環境設定
+
+```bash
+git clone https://github.com/Intergration-Automation-Testing/AutoControl.git
+cd AutoControl
+pip install -r dev_requirements.txt
+```
+
+### 執行測試
+
+```bash
+# 單元測試
+python -m pytest test/unit_test/
+
+# 整合測試
+python -m pytest test/integrated_test/
+```
+
+### 專案連結
+
+- **首頁**: https://github.com/Intergration-Automation-Testing/AutoControl
+- **文件**: https://autocontrol.readthedocs.io/en/latest/
+- **PyPI**: https://pypi.org/project/je_auto_control/
+
+---
+
+## 授權條款
+
+[MIT License](../LICENSE) © JE-Chen