Thư viện: C12_N8N_MQTT_PyAutoGUI_Web · Node n8n: greatLotusPyAutoWeb · Bản tài liệu bám phiên bản đang chạy thật.

Chương 0 — Lời nói đầu

0.1 Tài liệu này viết cho ai

0.2 Kỷ luật nguồn

Mỗi con số, mỗi tên thành phần trong sách này truy được về một trong ba nguồn: (1) mã nguồn đang chạy — đọc thẳng bundle GreatLotus.node.js phiên bản 0.1.51 đang cài trong container lotus_n8n; (2) tài liệu kỹ thuật nội bộ trong Library/C12_.../Agent_*.md và bộ nhớ dự án; (3) ảnh chụp hệ thống sống — chụp trực tiếp trên n8n qua Chrome thật (B35) tại thời điểm biên soạn. Chỗ nào không truy được về ba nguồn đó thì bỏ, không suy đoán.

LƯU Ý · ĐÃ SỬA SO VỚI HIỂU BIẾT CŨ

Kho mã trong repo local (bản 0.1.33) đã lạc hậu so với bản đang chạy thật (0.1.51). Bản chạy thật đã: (a) BỎ action manager.gpm_connect; (b) THÊM manager.pull_profile và manager.push_profile (luồng kho NAS2); (c) thêm tham số AUTO-ARGS (Load Chrome Args from config.json) và định tuyến đa phiên (Remote Port, profile_id). Sách này bám bản 0.1.51, không bám repo cũ.

0.3 Trạng thái hệ thống lúc chụp ảnh

Hạng mục	Giá trị lúc biên soạn
Phiên bản node C12	n8n-nodes-c12_pyautogui_web@0.1.51 (bundle trong container lotus_n8n)
Phiên bản n8n	2.36.8
Số Action Group	10
Tổng số Action	59
Tổng số trường tham số riêng	273 (chưa kể các trường dùng chung)
Hằng số giao thức (payload.version)	great-lotus-pyauto-v1
Broker MQTT	128.199.200.17:1883 (VPS ngoài)
Máy chụp	n8n https://n8n.lotus1104.synology.me qua Chrome thật trên B35

Chương 1 — Node C12 là gì và giải quyết vấn đề gì

1.1 Một câu định nghĩa

GREAT LOTUS PYAUTO WEB là một MQTT command emitter: nó biến các lựa chọn trên giao diện n8n thành một bản tin JSON có cấu trúc chuẩn, publish lên một topic MQTT, và (tùy chọn) chờ phản hồi trên topic RES_<topic>. Node không tự động hóa gì cả — nó không mở trình duyệt, không import PyAutoGUI. Bên thực sự điều khiển chuột/bàn phím/Chrome là thư viện Python A13 chạy trên máy worker.

GHI CHÚ · NODE CHỈ PHÁT LỆNH

Phần 'PyAutoGUI' và 'Web' trong tên chỉ mô tả NĂNG LỰC của bên Client mà node điều khiển từ xa. Bản thân node là TypeScript chạy trong tiến trình n8n (Node.js), phụ thuộc runtime duy nhất là gói mqtt.

1.2 Vấn đề nó giải quyết

Nhiều tác vụ web (đăng ký tài khoản, đọc OTP, thao tác trang có chống bot) cần thao tác giống người thật trên một desktop thật: di chuột theo quỹ đạo tự nhiên, gõ theo tốc độ WPM, có xác suất gõ nhầm. C12 cho phép điều phối các thao tác đó từ n8n mà không cần viết code Python trên từng máy — chỉ cần kéo node, chọn action, điền tham số.

1.3 Ranh giới trách nhiệm

Thành phần	Chịu trách nhiệm	KHÔNG làm
Node C12 (n8n)	Sinh UI, gom payload JSON, publish MQTT, chờ/khớp phản hồi	Không mở trình duyệt, không chạy PyAutoGUI
Broker MQTT	Chuyển bản tin giữa node và worker	Không xử lý nghiệp vụ
Client A13 (Python)	Thực thi thật: chuột, bàn phím, Chrome/CDP, GPM, NAS	Không quyết định workflow

Chương 2 — Vị trí trong họ node Great Lotus

C12 không đứng một mình. Nó là một mắt xích trong họ node MQTT của dự án Great Lotus.

Hình 2.1. Vị trí của C12 trong hệ sinh thái Great Lotus và quan hệ với C10, C11, A13.

Thư viện	Vai trò	Cơ chế điều khiển
A13_PyAutoGUI_Web	Client Python (bên nhận) — thật sự chạy PyAutoGUI + tự động hóa web	Subscribe MQTT, thực thi trên máy đích
C10_N8N_MQTT_PlayWright	Node n8n điều khiển bằng Playwright (DOM thuần)	MQTT request/response
C11_N8N_GPM_Login_Man	Node n8n quản lý profile GPM-Login	MQTT / HTTP bridge
C12 (tài liệu này)	Node n8n gửi lệnh cho A13 — desktop thật, chuột/bàn phím vật lý	MQTT request/response

Chương 3 — Luồng end-to-end và giao thức MQTT

3.1 Một lần chạy node

1. Người dùng chọn Action Group, Action và điền tham số trong n8n; node gom thành payload JSON.

2. Node publish payload lên topic người dùng nhập (ví dụ WP2_PC176) qua broker MQTT.

3. Máy Client đang subscribe topic đó nhận payload, dispatch theo action.function, chạy thao tác thật.

4. Nếu bật Wait For Response: Client publish kết quả lên RES_<topic> kèm meta.requestId; node khớp và trả output.

3.2 Kênh và quy tắc topic

Vai trò	Topic	Ai publish	Ai subscribe
Request	<topic> (người dùng nhập)	Node C12	Client A13
Response	RES_<topic> (tự suy ra)	Client A13	Node C12 (chỉ khi Wait For Response)

LƯU Ý · TOPIC PHẢN HỒI CỐ ĐỊNH

Response topic = tiền tố 'RES_' + đúng chuỗi topic request, KHÔNG cấu hình được. Client PHẢI publish kết quả lên RES_<topic> và echo lại meta.requestId thì node mới nhận và khớp đúng.

3.3 Cấu trúc bản tin request

Hình 3.2. Schema payload JSON node gửi đi (version / action / inputs / meta).

{

"version": "great-lotus-pyauto-v1",

"action": { "key": "mouse.click", "group": "MouseAction", "function": "click" },

"inputs": { "x": {"type":"number","value":320}, "button": {"type":"options","value":"left"} },

"meta": { "requestId":"a1b2...", "requestTopic":"WP2_PC176",

"responseTopic":"RES_WP2_PC176", "waitForResponse":true, "responseTimeoutSec":60 }

}

Chương 4 — Kiến trúc sinh giao diện tự động (data-driven)

Toàn bộ UI của node + validation + schema payload đều suy ra tự động từ một mảng khai báo duy nhất tên ACTION_SPECS. Người phát triển chỉ mô tả action muốn có; UI, mô tả tiếng Việt, ví dụ, placeholder và schema payload tự sinh ra.

Hình 4.1. Bộ sinh buildActionArtifacts biến ACTION_SPECS thành mọi thành phần UI và payload.

MẸO · THÊM ACTION RẤT RẺ

Thêm một action mới chỉ là thêm một dòng vào ACTION_SPECS — toàn bộ giao diện, mô tả và schema payload tự có. Đây là lý do node có 59 action mà mã nguồn vẫn gọn.

Chương 5 — Quản lý profile trình duyệt

5.1 Vòng đời Local Test Profile

Nhóm Manager có ba action bổ trợ nhau để chạy trình duyệt bằng một bản sao profile, không đụng profile thật.

Hình 5.1. Copy Master Profile tạo bản sao; Open Test Profile dùng; Clear huỷ.

GHI CHÚ · VÌ SAO CẦN BẢN SAO

Chrome khóa một --user-data-dir bằng SingletonLock: profile đang mở tay thì tiến trình thứ hai không dùng được, và mọi thao tác tự động sẽ làm bẩn/hỏng profile thật. Bản sao giải quyết cả hai. sync = nạp trạng thái; connect = dùng; clear = huỷ. Ba bước bổ trợ nhau, không thay thế nhau.

5.2 Luồng profile qua kho NAS2 (Pull / Push)

Hai action pull_profile (BƯỚC 3) và push_profile (BƯỚC 10) đồng bộ profile qua kho NAS2, do docs/tools/profile_store.py lo, KHÔNG chạm GPM API.

Hình 5.2. Luồng profile qua NAS2: Pull về trước khi mở, Push lên sau khi đóng.

5.3 Nối phiên qua remote_port (session chaining)

Hình 5.3. Open Profile trả remote_port; các node sau nối theo cổng đó; Close/Quit đóng đúng phiên.

LƯU Ý · CỔNG ẢO 127001

Open Local/Test Profile trả về remote_port = 127001 — cổng ẢO báo 'đây là session local'. Mọi chỗ dò cổng CDP phải LOẠI nó ra. Đổi giữa GPM và local chỉ cần thay đúng node Open; các node phía dưới cứ nối remote_port như thường.

Chương 6 — Giải phẫu bảng cấu hình node (NDV)

Khi bấm đúp vào node trên canvas, n8n mở Node Detail View (NDV) — bảng cấu hình chia ba cột: INPUT (trái), tham số (giữa), OUTPUT (phải). Hình dưới đánh số 13 thành phần dùng chung cho MỌI action.

Hình 6.1. Giải phẫu NDV của node C12 — 13 thành phần dùng chung.

#	Thành phần	Công dụng
1	Tên node	Nhãn node đang mở; đổi tên bằng cách bấm vào đây.
2	Docs	Mở tài liệu tổng của node trên trình duyệt (nút tĩnh cho cả node).
3	Tab Parameters	Khu nhập tham số nghiệp vụ (đang xem).
4	Tab Settings	Cấu hình chung của node: ghi chú, retry, continue-on-fail, always output data...
5	Execute step	Chạy thử riêng node này với dữ liệu hiện có.
6	Cột INPUT	Dữ liệu từ node trước đổ vào; 'No input connected' khi chưa nối.
7	Credential	Chọn thông tin đăng nhập MQTT (broker/username/password) để publish.
8	Action Group	Chọn 1 trong 10 nhóm hành động.
9	Action	Chọn action cụ thể trong nhóm; ngay dưới tên có câu tóm tắt.
10	Hộp hướng dẫn	Notice tóm tắt chức năng action + link 'Hướng dẫn chi tiết' và 'Mục lục tài liệu C12'.
11	Topic	Topic MQTT gửi request tới máy Client (bắt buộc).
12	QoS	Mức đảm bảo gửi của MQTT: 0 / 1 / 2.
13	Cột OUTPUT	Kết quả sau khi chạy; 'No output data' khi chưa chạy.

Chương 7 — Các trường dùng chung cho mọi action

Ngoài Action Group và Action, mỗi lần chạy đều có một số trường điều khiển chung. Bảng sau giải thích từng trường.

Trường	Kiểu	Ý nghĩa
Credential (MQTT)	chọn	Broker + tài khoản để publish. Bắt buộc có credential kiểu 'mqtt'.
Topic	chuỗi (bắt buộc)	Địa chỉ kênh gửi request, ví dụ WP2_PC176. Không có thì node báo lỗi.
QoS	chọn 0/1/2	0 = nhanh, có thể mất gói; 1 = có xác nhận (mặc định); 2 = đảm bảo cao nhất.
Include Input Items	bật/tắt	Bật để đính kèm dữ liệu node trước vào payload.inputItems (chọn field cần gửi).
Wait For Response	bật/tắt	Bật để chờ Client trả lời trên RES_<topic> rồi mới đi tiếp.
Response Timeout (sec)	số	Thời gian chờ tối đa; chỉ hiện khi Wait For Response bật.
Delay Next Step (ms)	chuỗi	Trễ trước bước kế tiếp; hỗ trợ rand(a,b) để giống người thật.

7.1 Trường hiện theo ngữ cảnh

Nhiều trường chỉ hiện khi một trường khác bật — n8n dùng cơ chế displayOptions. Hai ví dụ điển hình:

Hình 7.1. Bật Wait For Response thì trường Response Timeout (sec) mới xuất hiện.

Hình 7.2. Bật Include Input Items thì trường Include Input Fields mới xuất hiện.

7.2 Tooltip mỗi ô nhập

Mỗi ô nhập có một biểu tượng thông tin; rê chuột vào sẽ hiện tooltip theo cùng một khuôn: một câu Chức năng nói ô đó là gì, rồi 3 ví dụ mỗi ví dụ kèm câu Giải nghĩa cho biết chọn giá trị đó thì điều gì xảy ra.

Hình 7.3. Tooltip của ô 'Central Click' — Chức năng + 3 ví dụ có giải nghĩa.

7.3 Chọn Credential MQTT

7.4 Tab Settings

Hình 7.5. Tab Settings — cấu hình chung do n8n cung cấp cho mọi node.

Chương 8 — Nhóm 1. Manager

Nhóm quản lý phiên và profile: mở/đóng trình duyệt (GPM hoặc local), đồng bộ profile qua kho NAS2, tạo/huỷ profile thử nghiệm.

Hình 8.1. Danh sách action nhóm Manager trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 7 action. Từng action và bảng tham số đầy đủ như dưới đây.

Pull_Profile_from_NAS (manager.pull_profile)

BƯỚC 3 của luồng NAS: tải bản .tar mới nhất của profile từ kho NAS2 về thư mục profile cục bộ trên máy worker rồi xả nén, để Open GPM Profile mở đúng trạng thái duyệt gần nhất. KHÔNG chạm GPM API — chỉ thao tác kho + file, do docs/tools/profile_store.py lo. Mặc định GIÀNH LEASE (khoá phiên) trước khi tải và bật heartbeat tự gia hạn để máy khác không cùng ghi đè; node Push Profile sẽ nhả lease. Bỏ trống Dest Dir để dùng LOTUS_GPM_PROFILE_DIR. Output trả về dest_dir + addination_args (suy từ config.json) để tiện nối xuống. Điều kiện: máy worker đã có profile_store.py + đã mount kho NAS2 (WP2_GPM_Profile_RW).

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Profile ID *	profile_id	string	—	Mã định danh profile trong GPM Login. Lấy được từ giao diện GPM hoặc từ action List Profiles. Bạn cần nhập mục này để action chạy đúng.
Dest Dir	dest_dir	string	—	Thư mục GỐC trên máy worker để xả nén profile vào (mỗi profile một thư mục con). Bỏ trống để dùng biến môi trường LOTUS_GPM_PROFILE_DIR đã cấu hình sẵn.
Acquire Lease	acquire_lease	boolean	true	Bật (mặc định): giành khoá phiên (lease) TRƯỚC khi tải + tự gia hạn (heartbeat) để máy khác không cùng ghi đè; node Push Profile sẽ nhả lease. Tắt: chỉ đọc bản mới nhất, không khoá.
Host (lease/audit)	host	string	—	Giá trị cho "Host (lease/audit)" của action "Pull_Profile_from_NAS". Bạn có thể để trống nếu không cần dùng.
Lease TTL (sec)	lease_ttl	string	—	Nhập số cho "Lease TTL (sec)". Bạn có thể để trống nếu không cần dùng.
Store (UNC/mount)	store	string	—	Giá trị cho "Store (UNC/mount)" của action "Pull_Profile_from_NAS". Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Push_Profile_to_NAS (manager.push_profile)

BƯỚC 10 của luồng NAS: đóng gói thư mục profile cục bộ (đã đo cache → tính AIMD → ghi config.json) thành .tar không nén rồi UPLOAD NGUYÊN TỬ lên NAS2 (ghi incoming/ rồi rename) và nhả lease. Chạy SAU khi đã đóng profile GPM (Close Profile) để Chrome flush xong. KHÔNG chạm GPM API. Bỏ trống Profile Dir để tự dò theo LOTUS_GPM_PROFILE_DIR + glob. Điều kiện: như Pull Profile (cần quyền GHI vào kho).

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Profile ID *	profile_id	string	—	Mã định danh profile trong GPM Login. Lấy được từ giao diện GPM hoặc từ action List Profiles. Bạn cần nhập mục này để action chạy đúng.
Profile Dir	profile_dir	string	—	Thư mục profile cục bộ cần đóng gói + upload. Bỏ trống để tự dò (khớp <base>/<id> rồi glob {id}-*).
Host (audit)	host	string	—	Giá trị cho "Host (audit)" của action "Push_Profile_to_NAS". Bạn có thể để trống nếu không cần dùng.
Run Duration (sec)	duration	string	—	Nhập số cho "Run Duration (sec)". Bạn có thể để trống nếu không cần dùng.
Actual Cache (MB)	actual_cache_mb	string	—	Nhập số cho "Actual Cache (MB)". Bạn có thể để trống nếu không cần dùng.
Release Lease	release_lease	boolean	true	Bật (mặc định): nhả lease sau khi push xong. Tắt: giữ lease (chạy tiếp phiên khác).
Store (UNC/mount)	store	string	—	Giá trị cho "Store (UNC/mount)" của action "Push_Profile_to_NAS". Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

PyAutoGUI_Open_Test/Local_Profile (manager.local_browser_connect)

Tự khởi chạy Chrome/Edge/Firefox/Brave trên máy Client bằng dòng lệnh, mở sẵn URL, rồi ghi nhớ cửa sổ đó làm mục tiêu cho mọi action sau. Mặc định dùng profile sandbox %TEMP%\great_lotus_local_test_profiles_in_C12_pyAutoGUI\chromium\default (bản sao do Copy Master Profile tạo ra); tắt Use Local Test Profile để tự chỉ định Profile Location. Node tự mở sẵn cổng CDP cho browser nên các action cần CDP (Close Others Tab, Switch Tab, New Tab...) dùng được ngay. Trả về remote_port = 127001 — cổng ảo báo "đây là session local" — nên các node phía dưới cứ nối remote_port như bình thường: đổi giữa GPM và local chỉ cần thay đúng node này.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Browser Type	browser_type	chọn: Chrome / Edge / Firefox / Brave	Chrome	Trình duyệt mà Client sẽ khởi chạy trên máy thật. Bạn có thể để trống nếu không cần dùng.
URL	url	string	about:blank	Địa chỉ trang web cần mở. Nên ghi đủ cả http:// hoặc https://. Bạn có thể để trống nếu không cần dùng.
Proxy	Proxy	string	—	Máy chủ proxy để trình duyệt đi ra internet qua đó. Ghi đủ giao thức và cổng. Để trống nếu đi thẳng. Bạn có thể để trống nếu không cần dùng.
Use Local Test Profile	use_local_test_profile	boolean	true	Bật thì mở trình duyệt bằng bản sao profile đã tạo bởi Sync Master Profile, thay vì profile thật. Nhờ vậy thao tác tự động không làm bẩn và không khóa profile bạn đang dùng hằng ngày. Bạn có thể để trống nếu không cần dùng.
Profile Location *	profile	string	—	Đường dẫn thư mục dữ liệu trình duyệt sẽ dùng. Trỏ vào thư mục User Data để giữ nguyên cookie và trạng thái đăng nhập sẵn có. Bạn cần nhập mục này để action chạy đúng. [Chỉ hiện khi: use_local_test_profile=false]
Additional Args	addination_args	string	—	Tham số dòng lệnh bổ sung khi khởi chạy trình duyệt, cách nhau bằng khoảng trắng. Dùng để bật những cờ mà node chưa có ô riêng. Bạn có thể để trống nếu không cần dùng.
Win Pos	win_pos	string	—	Vị trí góc trên-trái của cửa sổ trên màn hình, viết dạng X,Y tính bằng pixel. Bạn có thể để trống nếu không cần dùng.
Win Size	win_size	string	—	Kích thước cửa sổ viết dạng Rộng,Cao tính bằng pixel. Bạn có thể để trống nếu không cần dùng.
Incognito	incognito	boolean	false	Bật thì mở ở chế độ ẩn danh: không dùng và không lưu cookie, lịch sử của phiên trước. Mỗi lần chạy là một phiên trắng. Bạn có thể để trống nếu không cần dùng.
DEBUG	DEBUG	boolean	false	Bật để Client ghi thêm nhật ký chi tiết cho bước này, phục vụ dò lỗi. Bạn có thể để trống nếu không cần dùng.
Headless	headless	boolean	false	Bật thì trình duyệt chạy ẩn không hiện cửa sổ. Lưu ý: các action dựa vào ảnh và tọa độ màn hình sẽ KHÔNG hoạt động ở chế độ này. Bạn có thể để trống nếu không cần dùng.
Virtual Mouse	vmouse	boolean	false	Bật lớp chuột ảo vẽ đè lên màn hình để nhìn thấy con trỏ đang ở đâu. Chủ yếu dùng khi quan sát và dò lỗi. Bạn có thể để trống nếu không cần dùng.
Zoom (%)	zoom	string	100	Mức phóng to nội dung trang tính theo phần trăm, áp dụng bằng tổ hợp Ctrl +/- sau khi mở. Ảnh hưởng trực tiếp tới tọa độ và tới việc ảnh mẫu có khớp hay không. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

PyAutoGUI_Open_GPM_Profile (manager.open_profile)

Nhờ GPM Login mở một profile theo Profile ID (gọi GET /profiles/start/<id>), sau đó bám lấy cửa sổ vừa hiện và gắn vào cổng CDP mà GPM báo về, để các action DOM/CDP dùng được ngay. Cửa sổ được khoá theo tiến trình giữ cổng CDP nên thao tác chuột/bàn phím đi đúng browser kể cả khi máy đang mở nhiều profile. Trả về remote_port ở output để nối thẳng xuống các node sau. Dùng khi cần chống fingerprint bằng profile GPM thay vì trình duyệt local. LƯU Ý PROXY: /profiles/start KHÔNG nhận proxy — profile chạy bằng proxy ĐÃ LƯU sẵn trên nó (đặt bằng Create/Update Profile qua raw_proxy); muốn đổi proxy mới thì Update Profile TRƯỚC rồi mới Open. AUTO-ARGS: bật "Load Chrome Args from config.json" (mặc định) thì worker tự đọc config.json trong thư mục profile (do Pull Profile tải về) và nhét --disk-cache-size (theo hạn mức cache), --media-cache-size=1, --disable-pdf-viewer + additional_args vào addination_args.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Profile ID *	profile_id	string	—	Mã định danh profile trong GPM Login. Lấy được từ giao diện GPM hoặc từ action List Profiles. Bạn cần nhập mục này để action chạy đúng.
Additional Args	addination_args	string	—	Tham số dòng lệnh bổ sung khi khởi chạy trình duyệt, cách nhau bằng khoảng trắng. Dùng để bật những cờ mà node chưa có ô riêng. Bạn có thể để trống nếu không cần dùng.
Load Chrome Args from config.json	load_args_from_config	boolean	true	Bật (mặc định): worker đọc config.json của profile để tự thêm --disk-cache-size... vào addination_args. Tắt: chỉ dùng đúng những gì gõ ở ô Additional Args.
Profile Folder (for config.json)	profile_config_dir	string	—	Thư mục profile chứa config.json. Bỏ trống để worker tự dò (cùng chỗ Pull Profile xả nén). Chỉ dùng khi Load Chrome Args from config.json đang bật.
Win Scale	win_scale	string	—	Tỉ lệ phóng to/thu nhỏ cửa sổ, 1 là 100%. Bạn có thể để trống nếu không cần dùng.
Win Pos	win_pos	string	—	Vị trí góc trên-trái của cửa sổ trên màn hình, viết dạng X,Y tính bằng pixel. Bạn có thể để trống nếu không cần dùng.
Win Size	win_size	string	—	Kích thước cửa sổ viết dạng Rộng,Cao tính bằng pixel. Bạn có thể để trống nếu không cần dùng.
Start Maximized	start_maximized	boolean	true	Bật thì cửa sổ mở ra ở trạng thái phóng to hết màn hình, bỏ qua Win Size. Bạn có thể để trống nếu không cần dùng.
Kill Idel Timeout (Sec)	kill_idle_timeout_sec	string	300	Số giây không có hoạt động thì Client tự đóng profile để giải phóng máy. Đặt 0 nghĩa là không bao giờ tự đóng. Bạn có thể để trống nếu không cần dùng.
Close Profile when error	close_profile_when_error	boolean	true	Bật thì gặp lỗi là đóng profile ngay; tắt thì để nguyên cửa sổ cho bạn vào xem hiện trường. Bạn có thể để trống nếu không cần dùng.
One Frame Mode	one_frame_mode	boolean	true	Bật chế độ một frame giống C10: các node Element như wait_element/get_text/get_attribute/count_element sẽ tìm cả trong iframe của trang hiện tại.
DEBUG	DEBUG	boolean	false	Bật để Client ghi thêm nhật ký chi tiết cho bước này, phục vụ dò lỗi. Bạn có thể để trống nếu không cần dùng.
Incognito-like Context	incognito	boolean	false	Bật thì mở ở chế độ ẩn danh: không dùng và không lưu cookie, lịch sử của phiên trước. Mỗi lần chạy là một phiên trắng. Bạn có thể để trống nếu không cần dùng.
Headless	headless	boolean	false	Bật thì trình duyệt chạy ẩn không hiện cửa sổ. Lưu ý: các action dựa vào ảnh và tọa độ màn hình sẽ KHÔNG hoạt động ở chế độ này. Bạn có thể để trống nếu không cần dùng.
Virtual Mouse	vmouse	boolean	false	Bật lớp chuột ảo vẽ đè lên màn hình để nhìn thấy con trỏ đang ở đâu. Chủ yếu dùng khi quan sát và dò lỗi. Bạn có thể để trống nếu không cần dùng.
Follow Controller Mouse	listen_mouse	boolean	false	Bật thì chuột ảo bám theo chuột thật của người điều khiển. Chỉ hiện khi đã bật Virtual Mouse. Bạn có thể để trống nếu không cần dùng. [Chỉ hiện khi: vmouse=true]
Show Info	show_info	boolean	false	Bật để Client hiện bảng thông tin phiên làm việc đè lên màn hình khi mở profile. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Copy Master Profile to Test Profile (manager.sync_master_profile_to_local_test_profile)

Nhân bản profile Chrome thật của máy Client (cookie, đăng nhập, extension) sang thư mục sandbox %TEMP%\great_lotus_local_test_profiles_in_C12_pyAutoGUI\chromium\default để Open Test/Local Profile chạy bằng bản sao, không đụng vào profile gốc. Các file SQLite (Cookies, Login Data, Web Data...) được chép bằng backup API của SQLite nên KHÔNG cần đóng Chrome gốc trước khi chạy. Field "Master Profile Path" là NGUỒN; nên trỏ vào thư mục "User Data" (bỏ trống = tự dò) chứ đừng trỏ thẳng vào "Profile 1", vì khoá giải mã cookie nằm ở User Data\Local State. Output có sqlite_fallback: rỗng nghĩa là chụp nhất quán toàn bộ. LƯU Ý: C10 dùng thư mục RIÊNG (..._in_C10_GPM) — sync bằng node C10 rồi mở bằng node C12 sẽ trỏ nhầm thư mục; hãy sync và mở trong cùng một bộ node.

Hàm phía Client A13: sync_master_profile_to_local_test_profile. Số tham số riêng: 2.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Master Profile is Window Chrome Profile	use_window_chrome_profile	boolean	true	Bật (mặc định): tự động dò profile Chrome mặc định trên máy GPM Windows để làm Master (bỏ qua "Master Profile Path"). Tắt: dùng đường dẫn nhập ở "Master Profile Path" làm Master Profile.
Master Profile Path	profile	string	—	Đường dẫn tới MASTER profile NGUỒN (profile Chrome/Chromium thật đã đăng nhập sẵn) sẽ được COPY (nhân bản) sang thư mục sandbox local_test_profile (dữ liệu tạm) để test — không đụng vào master gốc. Đây là NGUỒN, không phải đích; đích do hệ thống tự quản lý (runtime_profiles/local_test_profile). Path phải là user-data root (chứa file "Local State") HOẶC một profile dir (chứa file "Preferences", ví dụ .../User Data/Default). Chỉ dùng khi tắt "Master Profile is Window Chrome Profile". [Chỉ hiện khi: use_window_chrome_profile=false]

Clear Local Test Profile (manager.clear_local_test_profile)

Xóa sạch thư mục sandbox %TEMP%\great_lotus_local_test_profiles_in_C12_pyAutoGUI\chromium\default (tự đóng browser đang dùng nó trước khi xóa). Dùng để reset về profile trắng khi cần test lại luồng đăng nhập từ đầu, thu hồi dung lượng, hoặc dọn cookie/session còn sót. Không đụng tới profile gốc.

Action này không có tham số riêng — chỉ dùng các trường dùng chung (Topic, QoS...).

Quit/Quit_All (manager.quit)

Đóng tiến trình trình duyệt mà A13 đã tự mở và reset state phiên (cửa sổ mục tiêu, tab, frame). Mặc định chỉ đóng ĐÚNG session ứng với Remote Port đã nhập (nhập 127001 để đóng session local); bật Quit All để đóng sạch mọi session trên máy đó. Lưu ý: KHÔNG đóng profile GPM đã mở bằng Open GPM Profile.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Quit All	quit_all	boolean	false	Bật = đóng SẠCH mọi session trên máy Client (bỏ qua Remote Port). Tắt = chỉ đóng đúng session ứng với Remote Port bên dưới — dùng khi máy đang chạy nhiều session song song.
Remote Port *	remote_port	string	={{$json.remote_port}}	Session cần đóng, nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 để đóng session local. [Chỉ hiện khi: quit_all=false]
Close External Pages	close_external_pages	boolean	false	Bật thì đóng luôn những cửa sổ trình duyệt không do phiên tự động này mở ra. Cẩn thận: có thể đóng nhầm cửa sổ bạn đang mở tay. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 9 — Nhóm 2. Mouse

Nhóm chuột vật lý: click, di chuyển theo quỹ đạo giống người, kéo-thả, cuộn. Nhiều action nhận cả tọa độ X/Y lẫn XPath.

Hình 9.1. Danh sách action nhóm Mouse trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 9 action. Từng action và bảng tham số đầy đủ như dưới đây.

click (mouse.click)

Click chuột vật lý một lần (hoặc N lần liên tiếp) tại tọa độ X,Y hoặc tại phần tử chỉ định bằng XPath. Chuột di chuyển theo quỹ đạo giống người thật trước khi bấm.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
X	x	string	—	Tọa độ ngang tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
Y	y	string	—	Tọa độ dọc tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Button	button	chọn: left / middle / right	left	Nút chuột dùng cho thao tác này. Bạn có thể để trống nếu không cần dùng.
Clicks	clicks	string	1	Số lần bấm liên tiếp tại cùng một điểm. Bạn có thể để trống nếu không cần dùng.
Delay Between Clicks (ms)	delay_between_clicks	string	—	Khoảng nghỉ giữa hai lần bấm liên tiếp, tính bằng mili-giây. Để trống thì Client tự chọn khoảng ngẫu nhiên giống người thật. Bạn có thể để trống nếu không cần dùng.
Central Click	central_click_flag	boolean	false	Bật thì thao tác vào đúng tâm phần tử; tắt thì chọn ngẫu nhiên một điểm trong vùng an toàn của phần tử. Tắt trông giống người thật hơn, bật thì chắc ăn hơn với phần tử nhỏ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

many_click (mouse.many_click)

Click lặp đi lặp lại cho tới khi ảnh dừng xuất hiện trên màn hình hoặc hết timeout. Dùng cho nút "Tiếp tục/Next/Skip" phải bấm nhiều lần mà không biết trước bao nhiêu lần.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
X	x	string	—	Tọa độ ngang tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
Y	y	string	—	Tọa độ dọc tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Stop Image Input	stop_condition	string	—	Ảnh mẫu báo hiệu "đủ rồi, dừng bấm". Client bấm lặp cho tới khi thấy ảnh này xuất hiện hoặc hết thời gian chờ. Bạn có thể để trống nếu không cần dùng.
Interval (sec)	interval_sec	string	1	Nhịp kiểm tra lại điều kiện, tính bằng giây. Số nhỏ thì phát hiện nhanh nhưng tốn CPU của máy Client. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	30	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.
Button	button	chọn: left / middle / right	left	Nút chuột dùng cho thao tác này. Bạn có thể để trống nếu không cần dùng.
Clicks	clicks	string	1	Số lần bấm liên tiếp tại cùng một điểm. Bạn có thể để trống nếu không cần dùng.
Central Click	central_click_flag	boolean	false	Bật thì thao tác vào đúng tâm phần tử; tắt thì chọn ngẫu nhiên một điểm trong vùng an toàn của phần tử. Tắt trông giống người thật hơn, bật thì chắc ăn hơn với phần tử nhỏ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

move (mouse.move)

Chỉ di chuyển con trỏ tới tọa độ hoặc phần tử, không bấm. Chọn được kiểu di chuyển natural/linear/hesitant để mô phỏng người thật — hữu ích khi cần kích hoạt hiệu ứng hover hoặc "làm ấm" hành vi chuột trước thao tác quan trọng.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
X	x	string	—	Tọa độ ngang tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
Y	y	string	—	Tọa độ dọc tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Duration (ms)	duration_ms	string	—	Thời gian thực hiện chuyển động, tính bằng mili-giây. Số càng lớn thì chuột di/cuộn càng chậm và càng giống người thật. Bạn có thể để trống nếu không cần dùng.
Movement Type	movement_type	chọn: natural / linear / hesitant	natural	Kiểu quỹ đạo di chuyển chuột. Ảnh hưởng trực tiếp tới việc trang có nhận ra đây là bot hay không. Bạn có thể để trống nếu không cần dùng.
Central Click	central_click_flag	boolean	false	Bật thì thao tác vào đúng tâm phần tử; tắt thì chọn ngẫu nhiên một điểm trong vùng an toàn của phần tử. Tắt trông giống người thật hơn, bật thì chắc ăn hơn với phần tử nhỏ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

mouse_click_and_hold (mouse.mouse_click_and_hold)

Nhấn giữ nút chuột và KHÔNG nhả ra. Là nửa đầu của thao tác kéo-thả hoặc bôi đen; phải gọi Mouse Release sau đó để kết thúc.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
X	x	string	—	Tọa độ ngang tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
Y	y	string	—	Tọa độ dọc tính bằng pixel trên MÀN HÌNH thật (không phải trong trang). Góc trên-trái màn hình là 0. Bỏ trống nếu đã chỉ định XPath. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Button	button	chọn: left / middle / right	left	Nút chuột dùng cho thao tác này. Bạn có thể để trống nếu không cần dùng.
Central Click	central_click_flag	boolean	false	Bật thì thao tác vào đúng tâm phần tử; tắt thì chọn ngẫu nhiên một điểm trong vùng an toàn của phần tử. Tắt trông giống người thật hơn, bật thì chắc ăn hơn với phần tử nhỏ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

mouse_release (mouse.mouse_release)

Nhả nút chuột đang được giữ. Là nửa sau của cặp mouse_click_and_hold → (move) → mouse_release.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Button	button	chọn: left / middle / right	left	Nút chuột dùng cho thao tác này. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

mouse_scroll (mouse.mouse_scroll)

Cuộn trang theo số pixel chỉ định, lên hoặc xuống. Có thể cuộn tại vị trí một phần tử cụ thể (đưa chuột tới đó trước khi cuộn) để cuộn đúng vùng scroll lồng nhau.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Pixels	pixels	string	300	Quãng đường cuộn tính bằng pixel cho mỗi lần thực hiện. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Direction	direction	chọn: down / up	down	Chiều cuộn trang. Bạn có thể để trống nếu không cần dùng.
Duration (ms)	duration_ms	string	—	Thời gian thực hiện chuyển động, tính bằng mili-giây. Số càng lớn thì chuột di/cuộn càng chậm và càng giống người thật. Bạn có thể để trống nếu không cần dùng.
Central Click	central_click_flag	boolean	false	Bật thì thao tác vào đúng tâm phần tử; tắt thì chọn ngẫu nhiên một điểm trong vùng an toàn của phần tử. Tắt trông giống người thật hơn, bật thì chắc ăn hơn với phần tử nhỏ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

mouse_scroll_top (mouse.mouse_scroll_top)

Cuộn thẳng lên đầu trang. Tiện để đưa trang về mốc xác định trước khi đo tọa độ hoặc chụp ảnh.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Duration (ms)	duration_ms	string	—	Thời gian thực hiện chuyển động, tính bằng mili-giây. Số càng lớn thì chuột di/cuộn càng chậm và càng giống người thật. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

mouse_scroll_bottom (mouse.mouse_scroll_bottom)

Cuộn thẳng xuống cuối trang. Hay dùng để kích hoạt lazy-load hoặc infinite scroll.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Duration (ms)	duration_ms	string	—	Thời gian thực hiện chuyển động, tính bằng mili-giây. Số càng lớn thì chuột di/cuộn càng chậm và càng giống người thật. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

mouse_scroll_object (mouse.mouse_scroll_object)

Cuộn cho tới khi phần tử theo XPath lọt vào vùng nhìn thấy, tối đa trong timeout_sec giây. Dùng khi nút cần bấm nằm ngoài màn hình và không biết phải cuộn bao nhiêu.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Duration (ms)	duration_ms	string	—	Thời gian thực hiện chuyển động, tính bằng mili-giây. Số càng lớn thì chuột di/cuộn càng chậm và càng giống người thật. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	5	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.
Central Click	central_click_flag	boolean	false	Bật thì thao tác vào đúng tâm phần tử; tắt thì chọn ngẫu nhiên một điểm trong vùng an toàn của phần tử. Tắt trông giống người thật hơn, bật thì chắc ăn hơn với phần tử nhỏ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 10 — Nhóm 3. Keyboard

Nhóm bàn phím: gõ văn bản theo WPM có xác suất gõ nhầm, bấm phím/tổ hợp phím, và clipboard ảo nhiều ô nhớ.

Hình 10.1. Danh sách action nhóm Keyboard trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 5 action. Từng action và bảng tham số đầy đủ như dưới đây.

type (keyboard.type)

Gõ văn bản vào ô nhập đang focus (hoặc vào phần tử theo XPath) bằng bàn phím vật lý, có tốc độ WPM và xác suất gõ nhầm để giống người thật. Bật Just Paste Text để dán bằng clipboard khi cần nhanh, nhập nội dung dài, hoặc tránh lỗi bộ gõ tiếng Việt.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Text	text	string	—	Nội dung chữ sẽ được gõ vào ô nhập đang được chọn. Bạn có thể để trống nếu không cần dùng.
Just Paste Text (Not Type)	just_paste_text	boolean	false	Bật thì dán cả khối bằng clipboard trong một nhịp; tắt thì mô phỏng gõ từng phím. Bật khi nội dung dài hoặc có tiếng Việt; tắt khi trang yêu cầu sự kiện gõ từng ký tự. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
WPM	wpm	string	—	Tốc độ gõ tính bằng số từ mỗi phút. Để trống thì Client dùng tốc độ ngẫu nhiên tự nhiên. Bạn có thể để trống nếu không cần dùng.
Error Probability	error_probability	string	—	Xác suất gõ sai rồi tự xóa sửa lại, giá trị 0 đến 1. Làm thao tác giống người thật hơn nhưng chậm hơn. Bạn có thể để trống nếu không cần dùng.
Central Click	central_click_flag	boolean	false	Bật thì thao tác vào đúng tâm phần tử; tắt thì chọn ngẫu nhiên một điểm trong vùng an toàn của phần tử. Tắt trông giống người thật hơn, bật thì chắc ăn hơn với phần tử nhỏ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

press_key (keyboard.press_key)

Bấm một phím đơn (Enter, Tab, Escape...) N lần, cách nhau delay_ms. Chọn được press (bấm-nhả), down (giữ) hay up (nhả) để dựng thao tác giữ phím phức tạp.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Key *	key	string	Enter	Tên một phím đơn cần bấm. Viết đúng tên phím, không phân biệt hoa thường. Bạn cần nhập mục này để action chạy đúng.
Key Type	key_type	chọn: press / down / up	press	Kiểu tác động lên phím: bấm-nhả trọn vẹn, chỉ nhấn giữ, hay chỉ nhả ra. Dùng down/up khi cần giữ phím qua nhiều bước. Bạn có thể để trống nếu không cần dùng.
Press Count	count	string	1	Số lần bấm phím lặp lại. Phải là số nguyên từ 1 trở lên. Bạn có thể để trống nếu không cần dùng.
Delay Between Presses (ms)	delay_ms	string	500	Khoảng nghỉ giữa hai lần bấm phím, tính bằng mili-giây. Phải từ 0 trở lên. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

combo_key (keyboard.combo_key)

Bấm một tổ hợp phím dạng Ctrl+A, Ctrl+Shift+P, Alt+Tab — nhấn theo thứ tự rồi nhả ngược lại. Dùng cho copy/paste, mở DevTools, chuyển cửa sổ.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Keys	keys	string	Ctrl+A	Tổ hợp phím, các phím nối bằng dấu +. Client nhấn theo thứ tự rồi nhả ngược lại. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

vcopy (keyboard.vcopy)

Lưu một chuỗi vào clipboard ảo của A13 theo số slot (index), không đụng clipboard thật của Windows. Cho phép giữ nhiều mẩu dữ liệu song song trong cùng workflow.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Value	value	string	—	Nội dung cần lưu vào clipboard ảo. Clipboard ảo nằm trong Client, không đụng tới clipboard thật của Windows. Bạn có thể để trống nếu không cần dùng.
Index	index	string	0	Số hiệu ô nhớ của clipboard ảo để lưu giá trị. Dùng nhiều ô để giữ song song nhiều mẩu dữ liệu. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

vpaste (keyboard.vpaste)

Dán nội dung từ slot clipboard ảo đã lưu bằng vcopy vào ô nhập hiện tại hoặc phần tử theo XPath.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Index	index	string	0	Số hiệu ô nhớ clipboard ảo cần dán ra. Phải trùng với ô đã lưu bằng vcopy. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 11 — Nhóm 4. Browser Control

Nhóm điều hướng trình duyệt: tiến/lùi/tải lại, mở URL, và quản lý tab (mở, đóng, đóng tab khác, chuyển).

Hình 11.1. Danh sách action nhóm Browser Control trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 8 action. Từng action và bảng tham số đầy đủ như dưới đây.

Next (browser.next)

Đi tới trang kế tiếp trong lịch sử duyệt web (tương đương nút Forward).

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Previous (browser.previous)

Quay lại trang trước trong lịch sử duyệt web (tương đương nút Back).

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Refresh (browser.refresh)

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

URL (browser.url)

Điều hướng tab hiện tại tới một URL và chờ tới trạng thái tải chỉ định (load / domcontentloaded / networkidle / commit). Chọn networkidle khi trang render bằng JS và cần chờ dữ liệu về.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
URL	url	string	—	Địa chỉ trang web cần mở. Nên ghi đủ cả http:// hoặc https://. Bạn có thể để trống nếu không cần dùng.
Wait Until	wait_until	chọn: load / domcontentloaded / networkidle / commit	load	Mốc coi như trang đã tải xong trước khi node đi tiếp. Chọn sai mốc là nguyên nhân phổ biến khiến bước sau "không thấy phần tử". Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	60	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

NewTab (browser.new_tab)

Mở một tab mới với URL cho trước; tùy chọn chuyển focus sang tab đó luôn hay giữ nguyên tab đang làm việc.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
URL	url	string	—	Địa chỉ trang web cần mở. Nên ghi đủ cả http:// hoặc https://. Bạn có thể để trống nếu không cần dùng.
Switch	switch	boolean	true	Bật thì chuyển ngay sang tab vừa mở; tắt thì tab mới chạy nền, thao tác vẫn ở tab cũ. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

CloseTab (browser.close_tab)

Đóng một tab theo chỉ số; bỏ trống thì đóng tab đang hoạt động.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Index	index	string	—	Số thứ tự tab cần đóng, tab đầu tiên là 0. Để trống thì đóng tab đang hoạt động. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

CloseOthersTab (browser.close_others_tab)

Đóng tất cả tab trừ tab được giữ lại. Dùng để dọn cửa sổ về trạng thái sạch giữa hai vòng lặp workflow.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Keep Index	keep_index	string	—	Số thứ tự tab được giữ lại; mọi tab khác sẽ bị đóng. Tab đầu tiên là 0. Để trống thì giữ tab đang hoạt động. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

SwitchTab (browser.switch_tab)

Chuyển focus sang tab theo chỉ số (0 là tab đầu tiên). Mọi action sau đó tác động lên tab này.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Index	index	string	0	Số thứ tự tab cần chuyển sang, tab đầu tiên là 0. Mọi action sau đó tác động lên tab này. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 12 — Nhóm 5. Element

Nhóm đọc/chờ DOM theo selector và XPath — chốt đồng bộ trước mỗi thao tác và đọc dữ liệu ra output.

Hình 12.1. Danh sách action nhóm Element trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 4 action. Từng action và bảng tham số đầy đủ như dưới đây.

wait_element (element.wait_element)

Chờ tới khi phần tử đạt trạng thái mong muốn: present / visible / editable, hoặc phủ định của chúng. Đây là "chốt đồng bộ" nên đặt trước mỗi thao tác click/gõ để tránh thao tác vào trang chưa render xong.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Target	target	string	—	Selector trỏ tới phần tử cần thao tác. Chấp nhận tiền tố css=, id=, text= để chọn theo kiểu tương ứng. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Wait Type	wait_type	chọn: present / visible / editable / not present / not visible / not editable	present	Trạng thái của phần tử mà bạn muốn chờ đạt tới. Các lựa chọn "not ..." dùng để chờ phần tử biến mất. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	30	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

get_text (element.get_text)

Đọc nội dung văn bản của phần tử theo selector/XPath và trả về trong output của node — dùng để lấy giá trị hiển thị trên trang cho các bước sau.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Target	target	string	—	Selector trỏ tới phần tử cần thao tác. Chấp nhận tiền tố css=, id=, text= để chọn theo kiểu tương ứng. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	30	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

get_attribute (element.get_attribute)

Đọc một thuộc tính DOM của phần tử (href, value, data-*, class...) và trả về. Dùng khi thông tin cần lấy nằm trong attribute chứ không phải text hiển thị.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Target	target	string	—	Selector trỏ tới phần tử cần thao tác. Chấp nhận tiền tố css=, id=, text= để chọn theo kiểu tương ứng. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.
Attribute *	attribute	string	—	Tên thuộc tính DOM cần đọc giá trị. Ghi text để lấy nội dung chữ hiển thị. Bạn cần nhập mục này để action chạy đúng.
Timeout (sec)	timeout_sec	string	30	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

count_element (element.count_element)

Đếm số phần tử khớp selector/XPath. Dùng để kiểm tra danh sách đã load đủ chưa, hoặc rẽ nhánh workflow theo số kết quả tìm được.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Target	target	string	—	Selector trỏ tới phần tử cần thao tác. Chấp nhận tiền tố css=, id=, text= để chọn theo kiểu tương ứng. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 13 — Nhóm 6. Image

Nhóm nhận diện ảnh/màu trên màn hình — dùng khi phần tử không có DOM ổn định để bám.

Hình 13.1. Danh sách action nhóm Image trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 10 action. Từng action và bảng tham số đầy đủ như dưới đây.

ImageClick (image.image_click)

Tìm ảnh mẫu trên màn hình rồi click vào đó. Dùng khi phần tử không có DOM ổn định để bám (canvas, ảnh, popup native, iframe chéo miền).

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image URL *	image_url	string	—	Ảnh mẫu mà Client sẽ dò tìm trên màn hình. Nhận link http(s) để tải về, hoặc đường dẫn file có sẵn trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Temperature	temperature	string	0.7	Độ giống nhau tối thiểu giữa ảnh mẫu và vùng trên màn hình, từ 0.01 đến 1. Càng gần 1 càng khắt khe, giảm nhận nhầm nhưng dễ trượt khi màn hình đổi độ sáng hoặc tỉ lệ. Bạn có thể để trống nếu không cần dùng.
Interval (sec)	interval_sec	string	0.1	Nhịp kiểm tra lại điều kiện, tính bằng giây. Số nhỏ thì phát hiện nhanh nhưng tốn CPU của máy Client. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	60	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.
Button	button	chọn: left / middle / right	left	Nút chuột dùng cho thao tác này. Bạn có thể để trống nếu không cần dùng.
Clicks	clicks	string	1	Số lần bấm liên tiếp tại cùng một điểm. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

ImageMove (image.image_move)

Tìm ảnh mẫu trên màn hình rồi chỉ di chuyển chuột tới đó, không click — để hover hiển thị tooltip/menu.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image URL *	image_url	string	—	Ảnh mẫu mà Client sẽ dò tìm trên màn hình. Nhận link http(s) để tải về, hoặc đường dẫn file có sẵn trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Temperature	temperature	string	0.7	Độ giống nhau tối thiểu giữa ảnh mẫu và vùng trên màn hình, từ 0.01 đến 1. Càng gần 1 càng khắt khe, giảm nhận nhầm nhưng dễ trượt khi màn hình đổi độ sáng hoặc tỉ lệ. Bạn có thể để trống nếu không cần dùng.
Interval (sec)	interval_sec	string	0.1	Nhịp kiểm tra lại điều kiện, tính bằng giây. Số nhỏ thì phát hiện nhanh nhưng tốn CPU của máy Client. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	60	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.
Duration (ms)	duration_ms	string	—	Thời gian thực hiện chuyển động, tính bằng mili-giây. Số càng lớn thì chuột di/cuộn càng chậm và càng giống người thật. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

ImageType (image.image_type)

Tìm ảnh mẫu (thường là một ô nhập), click vào rồi gõ văn bản vào đó. Gộp image_click + type thành một bước.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image URL *	image_url	string	—	Ảnh mẫu mà Client sẽ dò tìm trên màn hình. Nhận link http(s) để tải về, hoặc đường dẫn file có sẵn trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Text *	text	string	—	Nội dung chữ sẽ được gõ vào ô nhập đang được chọn. Bạn cần nhập mục này để action chạy đúng.
Temperature	temperature	string	0.7	Độ giống nhau tối thiểu giữa ảnh mẫu và vùng trên màn hình, từ 0.01 đến 1. Càng gần 1 càng khắt khe, giảm nhận nhầm nhưng dễ trượt khi màn hình đổi độ sáng hoặc tỉ lệ. Bạn có thể để trống nếu không cần dùng.
Interval (sec)	interval_sec	string	0.1	Nhịp kiểm tra lại điều kiện, tính bằng giây. Số nhỏ thì phát hiện nhanh nhưng tốn CPU của máy Client. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	60	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.
WPM	wpm	string	—	Tốc độ gõ tính bằng số từ mỗi phút. Để trống thì Client dùng tốc độ ngẫu nhiên tự nhiên. Bạn có thể để trống nếu không cần dùng.
Error Probability	error_probability	string	—	Xác suất gõ sai rồi tự xóa sửa lại, giá trị 0 đến 1. Làm thao tác giống người thật hơn nhưng chậm hơn. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

ImageWait (image.image_wait)

Chờ tới khi ảnh mẫu XUẤT HIỆN trên màn hình hoặc hết timeout. Dùng làm chốt đồng bộ khi không có DOM để chờ.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image URL *	image_url	string	—	Ảnh mẫu mà Client sẽ dò tìm trên màn hình. Nhận link http(s) để tải về, hoặc đường dẫn file có sẵn trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Temperature	temperature	string	0.7	Độ giống nhau tối thiểu giữa ảnh mẫu và vùng trên màn hình, từ 0.01 đến 1. Càng gần 1 càng khắt khe, giảm nhận nhầm nhưng dễ trượt khi màn hình đổi độ sáng hoặc tỉ lệ. Bạn có thể để trống nếu không cần dùng.
Interval (sec)	interval_sec	string	0.1	Nhịp kiểm tra lại điều kiện, tính bằng giây. Số nhỏ thì phát hiện nhanh nhưng tốn CPU của máy Client. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	60	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

NotImageWait (image.not_image_wait)

Ngược lại image_wait: chờ tới khi ảnh mẫu BIẾN MẤT. Điển hình là chờ spinner/màn hình loading tắt đi.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image URL *	image_url	string	—	Ảnh mẫu mà Client sẽ dò tìm trên màn hình. Nhận link http(s) để tải về, hoặc đường dẫn file có sẵn trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Temperature	temperature	string	0.7	Độ giống nhau tối thiểu giữa ảnh mẫu và vùng trên màn hình, từ 0.01 đến 1. Càng gần 1 càng khắt khe, giảm nhận nhầm nhưng dễ trượt khi màn hình đổi độ sáng hoặc tỉ lệ. Bạn có thể để trống nếu không cần dùng.
Interval (sec)	interval_sec	string	0.1	Nhịp kiểm tra lại điều kiện, tính bằng giây. Số nhỏ thì phát hiện nhanh nhưng tốn CPU của máy Client. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	60	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

WaitColor (image.wait_color)

Chờ tới khi TẤT CẢ các điểm tọa độ chỉ định cùng mang đúng màu mong muốn (sai số ±tolerant mỗi kênh RGB). Cách kiểm tra trạng thái nhẹ và nhanh hơn so khớp ảnh. Action này luôn chạy đồng bộ; hết giờ mà chưa khớp thì node báo lỗi.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Color Conditions	wait_color_points	fixedCollection	{}	Danh sách các điểm màu cần kiểm tra. Mỗi điểm gồm tọa độ X, Y trên màn hình và mã màu mong đợi dạng #RRGGBB. Điều kiện chỉ đạt khi TẤT CẢ các điểm cùng khớp. Bạn có thể để trống nếu không cần dùng.
Tolerant (±RGB)	tolerant	string	5	Sai số màu cho phép trên từng kênh R, G, B — từ 0 đến 255. Số 0 đòi màu trùng khít tuyệt đối; nới rộng khi màn hình có khử răng cưa hoặc nén màu. Bạn có thể để trống nếu không cần dùng.
Timeout (sec)	timeout_sec	string	60	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Clean ImageStorage (image.clean_image_storage)

Dọn kho ảnh tạm mà các action image đã tải/cắt về trên máy Client. Chạy cuối workflow để không phình ổ đĩa.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

wait_to_image (image.wait_to_image)

Chờ ảnh mẫu xuất hiện theo cơ chế so khớp confidence (PyAutoGUI locate) và trả về vị trí tìm được. Khác nhóm temperature ở thuật toán so khớp và ở việc trả về danh sách kết quả.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image Input *	image_input	string	—	Ảnh mẫu cho nhóm tìm kiếm theo độ tin cậy (confidence). Nhận link http(s) hoặc đường dẫn file trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Timeout (sec)	timeout_sec	string	30	Thời gian chờ tối đa tính bằng giây trước khi báo lỗi. Đặt quá ngắn thì workflow gãy oan khi mạng chậm; quá dài thì lỗi thật cũng phải đợi lâu mới biết. Bạn có thể để trống nếu không cần dùng.
Interval (sec)	interval_sec	string	1	Nhịp kiểm tra lại điều kiện, tính bằng giây. Số nhỏ thì phát hiện nhanh nhưng tốn CPU của máy Client. Bạn có thể để trống nếu không cần dùng.
Confidence	confidence	string	0.9	Ngưỡng tin cậy của thuật toán dò ảnh, từ 0.01 đến 1. Hạ ngưỡng nếu hay không tìm thấy, nâng ngưỡng nếu hay bấm nhầm chỗ. Bạn có thể để trống nếu không cần dùng.
Workflow	workflow	string	workflow	Nhãn dùng để đặt tên thư mục/file mà Client lưu ảnh. Đặt tên có ý nghĩa để sau này tìm lại bằng chứng cho đúng luồng. Bạn có thể để trống nếu không cần dùng.
Full Page	full_page	boolean	false	Bật thì xử lý toàn bộ chiều dài trang bằng cách cuộn và ghép lại; tắt thì chỉ xử lý phần đang hiển thị trên màn hình. Bạn có thể để trống nếu không cần dùng.
Max Results	max_results	string	20	Số vị trí khớp tối đa được trả về. Giới hạn để tránh trả về hàng trăm kết quả khi ảnh mẫu quá phổ biến. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

check_image_exist (image.check_image_exist)

Kiểm tra NGAY một lần xem ảnh mẫu có trên màn hình không rồi trả kết quả, không chờ. Dùng để rẽ nhánh if/else trong workflow.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image Input *	image_input	string	—	Ảnh mẫu cho nhóm tìm kiếm theo độ tin cậy (confidence). Nhận link http(s) hoặc đường dẫn file trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Confidence	confidence	string	0.9	Ngưỡng tin cậy của thuật toán dò ảnh, từ 0.01 đến 1. Hạ ngưỡng nếu hay không tìm thấy, nâng ngưỡng nếu hay bấm nhầm chỗ. Bạn có thể để trống nếu không cần dùng.
Workflow	workflow	string	workflow	Nhãn dùng để đặt tên thư mục/file mà Client lưu ảnh. Đặt tên có ý nghĩa để sau này tìm lại bằng chứng cho đúng luồng. Bạn có thể để trống nếu không cần dùng.
Full Page	full_page	boolean	false	Bật thì xử lý toàn bộ chiều dài trang bằng cách cuộn và ghép lại; tắt thì chỉ xử lý phần đang hiển thị trên màn hình. Bạn có thể để trống nếu không cần dùng.
Max Results	max_results	string	20	Số vị trí khớp tối đa được trả về. Giới hạn để tránh trả về hàng trăm kết quả khi ảnh mẫu quá phổ biến. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

image_search (image.image_search)

Tìm tất cả vị trí khớp ảnh mẫu trên màn hình (tối đa max_results) và trả về danh sách tọa độ. Dùng khi cần lặp qua nhiều mục giống nhau.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Image Input *	image_input	string	—	Ảnh mẫu cho nhóm tìm kiếm theo độ tin cậy (confidence). Nhận link http(s) hoặc đường dẫn file trên máy Client. Bạn cần nhập mục này để action chạy đúng.
Confidence	confidence	string	0.9	Ngưỡng tin cậy của thuật toán dò ảnh, từ 0.01 đến 1. Hạ ngưỡng nếu hay không tìm thấy, nâng ngưỡng nếu hay bấm nhầm chỗ. Bạn có thể để trống nếu không cần dùng.
Workflow	workflow	string	workflow	Nhãn dùng để đặt tên thư mục/file mà Client lưu ảnh. Đặt tên có ý nghĩa để sau này tìm lại bằng chứng cho đúng luồng. Bạn có thể để trống nếu không cần dùng.
Full Page	full_page	boolean	false	Bật thì xử lý toàn bộ chiều dài trang bằng cách cuộn và ghép lại; tắt thì chỉ xử lý phần đang hiển thị trên màn hình. Bạn có thể để trống nếu không cần dùng.
Max Results	max_results	string	20	Số vị trí khớp tối đa được trả về. Giới hạn để tránh trả về hàng trăm kết quả khi ảnh mẫu quá phổ biến. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 14 — Nhóm 7. Others

Nhóm tiện ích: sinh giá trị ngẫu nhiên, chuyển popup/iframe, xử lý hộp thoại alert, chạy JavaScript trong trang.

Hình 14.1. Danh sách action nhóm Others trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 8 action. Từng action và bảng tham số đầy đủ như dưới đây.

random (others.random)

Nhờ máy Client sinh giá trị ngẫu nhiên (số, mật khẩu, màu RGB/HEX, hoặc tọa độ chuột) và trả về ngay cho các bước sau. Node tự ép chạy đồng bộ với timeout 10s và ẩn các trường chung.

Hình 14.2. Action random ẩn các trường chung, ép chạy đồng bộ.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Random Type	random_type	chọn: number / password / rgb / mouse_position	number	Loại giá trị ngẫu nhiên cần sinh. Các ô cấu hình bên dưới đổi theo lựa chọn này. Bạn có thể để trống nếu không cần dùng.
Result Count	result_count	string	1	Số lượng giá trị sinh ra trong một lần gọi. Bạn có thể để trống nếu không cần dùng.
Number From	number_from	string	0	Cận dưới của khoảng sinh số, tính cả giá trị này. Bạn có thể để trống nếu không cần dùng.
Number To	number_to	string	1000	Cận trên của khoảng sinh số. Bạn có thể để trống nếu không cần dùng.
Allow Float	allow_float	boolean	false	Bật thì cho phép kết quả có phần thập phân; tắt thì chỉ sinh số nguyên. Bạn có thể để trống nếu không cần dùng.
Step	step	string	1	Bước nhảy giữa các giá trị hợp lệ. Kết quả luôn là bội của bước tính từ cận dưới. Bạn có thể để trống nếu không cần dùng.
Password Length	password_length	string	12	Số ký tự của mật khẩu được sinh ra. Bạn có thể để trống nếu không cần dùng.
Include Number	include_number	boolean	true	Cho phép dùng chữ số 0-9 trong mật khẩu. Bạn có thể để trống nếu không cần dùng.
Include Lowercase	include_lowercase	boolean	true	Cho phép dùng chữ thường a-z trong mật khẩu. Bạn có thể để trống nếu không cần dùng.
Include Uppercase	include_uppercase	boolean	true	Cho phép dùng chữ hoa A-Z trong mật khẩu. Bạn có thể để trống nếu không cần dùng.
Include Symbol	include_symbol	boolean	true	Cho phép dùng ký tự đặc biệt như !@#$ trong mật khẩu. Bạn có thể để trống nếu không cần dùng.
Exclude Similar Chars	exclude_similar_chars	boolean	true	Bật thì loại các ký tự dễ nhìn nhầm nhau như số 1 với chữ l, số 0 với chữ O. Nên bật khi mật khẩu phải đọc hoặc gõ tay. Bạn có thể để trống nếu không cần dùng.
Exclude Ambiguous Chars	exclude_ambiguous_chars	boolean	true	Bật thì loại các ký tự hay gây lỗi khi copy-paste hoặc khi đưa vào dòng lệnh, ví dụ dấu nháy và ngoặc. Bạn có thể để trống nếu không cần dùng.
Avoid Repeating Chars	avoid_repeating_chars	boolean	false	Bật thì không cho hai ký tự giống nhau đứng cạnh nhau trong mật khẩu. Bạn có thể để trống nếu không cần dùng.
Color Format	color_format	chọn: rgb / hex	rgb	Định dạng chuỗi màu trả về. Bạn có thể để trống nếu không cần dùng.
Add Hex Prefix	hex_use_prefix	boolean	false	Bật thì thêm dấu # vào đầu mã màu HEX. Chỉ có tác dụng khi định dạng là hex. Bạn có thể để trống nếu không cần dùng.
Hex Prefix	hex_prefix	string	#	Ký tự đứng trước mã HEX khi bật tùy chọn trên. Bạn có thể để trống nếu không cần dùng.
From (x1,y1)	position_from	string	0,0	Góc trên-trái của vùng sinh tọa độ ngẫu nhiên, viết dạng X,Y. Bạn có thể để trống nếu không cần dùng.
To (x2,y2)	position_to	string	1920,1080	Góc dưới-phải của vùng sinh tọa độ ngẫu nhiên, viết dạng X,Y. Bạn có thể để trống nếu không cần dùng.

check_popup_and_frame (others.check_popup_and_frame)

Quét và liệt kê các popup/cửa sổ con và iframe đang có. Chạy trước khi switch để biết chính xác cần chuyển vào đâu.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

switch_to_popup (others.switch_to_popup)

Chuyển ngữ cảnh làm việc sang cửa sổ popup có tiêu đề khớp. Bắt buộc trước khi thao tác trong cửa sổ đăng nhập OAuth/thanh toán.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Title	title	string	—	Tiêu đề (hoặc một phần tiêu đề) của cửa sổ popup cần chuyển sang. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

switch_to_frame (others.switch_to_frame)

Chuyển ngữ cảnh vào một iframe (chọn theo index=, name=, css= hoặc default). Không làm bước này thì mọi selector bên trong iframe đều không tìm thấy.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Frame	frame	string	—	Cách chỉ định iframe cần vào. Dùng tiền tố index=, name=, css= tùy theo thông tin bạn có; ghi default để quay về trang gốc. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

switch_to_default (others.switch_to_default)

Quay về ngữ cảnh trang gốc sau khi đã vào iframe/popup. Quên bước này là nguyên nhân phổ biến khiến các action tiếp theo "không thấy phần tử".

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

accept_alert (others.accept_alert)

Đồng ý hộp thoại alert/confirm/prompt của trình duyệt (bấm OK), có thể điền sẵn nội dung cho prompt.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Prompt Text	prompt_text	string	—	Nội dung điền sẵn vào hộp thoại prompt trước khi bấm OK. Để trống nếu hộp thoại chỉ có nút xác nhận. Bạn có thể để trống nếu không cần dùng.
Show (sec)	show_sec	string	0	Thời gian để hộp thoại hiện trên màn hình trước khi Client bấm nút, tính bằng giây. Đặt lớn hơn 0 khi muốn kịp nhìn thấy nội dung lúc debug. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

cancel_alert (others.cancel_alert)

Từ chối hộp thoại alert/confirm/prompt của trình duyệt (bấm Cancel).

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Show (sec)	show_sec	string	0	Thời gian để hộp thoại hiện trên màn hình trước khi Client bấm nút, tính bằng giây. Đặt lớn hơn 0 khi muốn kịp nhìn thấy nội dung lúc debug. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

execute_javascript (others.execute_javascript)

Chạy một đoạn JavaScript ngay trong trang và trả kết quả về workflow. Lối thoát cho những việc UI không làm được: đọc biến JS, sửa DOM, gọi hàm nội bộ của trang.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Script *	script	string	() => document.title	Đoạn JavaScript chạy trong ngữ cảnh trang. Viết dạng hàm mũi tên; giá trị hàm trả về sẽ thành output của node. Bạn cần nhập mục này để action chạy đúng.
Arg (JSON)	arg	json	—	Dữ liệu JSON truyền vào làm tham số cho đoạn script ở trên. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 15 — Nhóm 8. Email

Hình 15.1. Danh sách action nhóm Email trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 1 action. Từng action và bảng tham số đầy đủ như dưới đây.

read_mail_code (email.read_mail_code)

Đăng nhập IMAP vào hòm thư, lọc thư mới theo người nhận/thời gian, rồi bóc mã xác thực ra — theo độ dài + kiểu ký tự, hoặc theo XPath của phần tử chứa mã. Dùng cho luồng OTP/2FA khi đăng ký hoặc đăng nhập.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Email *	Email	string	—	Địa chỉ hộp thư dùng để đăng nhập IMAP và đọc mã xác thực. Bạn cần nhập mục này để action chạy đúng.
Password *	Password	string	—	Mật khẩu đăng nhập IMAP. Với Gmail và Outlook phải dùng App Password chứ không phải mật khẩu thường. Bạn cần nhập mục này để action chạy đúng.
Mail Server	Mail_server	string	imap.gmail.com	Địa chỉ máy chủ IMAP của nhà cung cấp email. Bạn có thể để trống nếu không cần dùng.
Email Sent To Contains	Email_sent_to_contains	string	—	Chỉ xét những thư có địa chỉ người nhận chứa chuỗi này. Rất hữu ích khi dùng địa chỉ dạng cộng (alias) cho nhiều tài khoản. Bạn có thể để trống nếu không cần dùng.
Code Type	Code_type	chọn: number / alphanumeric	number	Loại ký tự của mã xác thực cần bóc ra khỏi nội dung thư. Bạn có thể để trống nếu không cần dùng.
Code Length	Code_length	string	6	Số ký tự của mã xác thực. Dùng để nhặt đúng chuỗi giữa nhiều con số trong thư. Bạn có thể để trống nếu không cần dùng.
Code Element XPath	Code_element_xpath	string	—	Cách lấy mã theo cấu trúc HTML của thư thay vì dò theo độ dài. Dùng khi trong thư có nhiều số dễ gây nhầm. Bạn có thể để trống nếu không cần dùng.
Code Element Attribute	Code_element_attribute	string	text	Thuộc tính của phần tử ở trên chứa mã. Ghi text nếu mã là chữ hiển thị. Bạn có thể để trống nếu không cần dùng.
Folder	folder	string	INBOX	Hộp thư IMAP cần quét để tìm mã xác thực. Bạn có thể để trống nếu không cần dùng.
Unread Only	unread_only	boolean	true	Bật thì chỉ xét thư chưa đọc — tránh lấy nhầm mã cũ đã dùng. Tắt khi cần đọc lại thư đã mở. Bạn có thể để trống nếu không cần dùng.
Max Mails	max_mails	string	30	Số thư gần nhất được quét. Số lớn thì chắc chắn tìm ra nhưng chậm hơn. Bạn có thể để trống nếu không cần dùng.
Debug	debug	boolean	false	Bật để in nhật ký chi tiết quá trình đọc thư: kết nối, lọc, chuỗi khớp được. Bạn có thể để trống nếu không cần dùng.
Debug Prefix	debug_prefix	string	[MAIL]	Chuỗi đứng đầu mỗi dòng log để dễ lọc khi nhiều node cùng ghi nhật ký. Bạn có thể để trống nếu không cần dùng.
Max Age Minutes	max_age_minutes	string	—	Chỉ chấp nhận thư đến trong khoảng phút gần đây. Đây là chốt chặn quan trọng để không lấy nhầm mã OTP cũ đã hết hạn. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 16 — Nhóm 9. Developer

Nhóm nội soi trang và chụp ảnh phục vụ dò lỗi và dựng selector.

Hình 16.1. Danh sách action nhóm Developer trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 6 action. Từng action và bảng tham số đầy đủ như dưới đây.

get_active_code (developer.getcode)

Lấy HTML của frame đang hoạt động. Dùng khi dựng selector: xem chính xác trang đang render gì.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

get_iframe_code (developer.get_iframe_code)

Lấy HTML của một iframe theo chỉ số, không cần switch vào nó trước.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Index	index	string	0	Số thứ tự iframe cần lấy mã nguồn, iframe đầu tiên là 0. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

get_full_code (developer.get_full_code)

Gom HTML của trang chính + tất cả iframe (tùy chọn kèm bản pierce shadow DOM qua CDP) thành một khối. Nặng nhất nhưng đầy đủ nhất — node tự nới timeout thêm 15s. Dùng khi không rõ phần tử nằm ở frame nào.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Timeout (sec)	timeout_sec	string	25	Maximum total time to collect main frame and iframe HTML. Increase this for large pages with many iframes.
Frame Timeout (sec)	frame_timeout_sec	string	2	Maximum time spent reading each frame. Slow or blocked iframes are returned as IFRAME:ERROR instead of blocking the whole action.
Max Chars	max_chars	string	0	0 means no truncation. Set a limit when the page HTML is too large for MQTT/n8n response handling.
Include Pierced DOM	include_pierced_dom	boolean	true	Append a CDP DOM.getDocument(pierce=true) section so nodes visible in DevTools inside open shadow DOM/iframe trees can appear in Get Full Code.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

get_info (developer.get_info)

Trả về trạng thái máy Client: kích thước màn hình, vị trí chuột, tiêu đề cửa sổ đang focus, số tiến trình trình duyệt, profile GPM đang mở... Bước đầu tiên nên chạy khi debug "sao không thấy gì".

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

capture (developer.capture)

Chụp màn hình máy Client và lưu thành file PNG trên máy đó. Dùng để lưu bằng chứng hoặc soi lại lỗi sau khi workflow chạy đêm.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Workflow	workflow	string	workflow	Nhãn dùng để đặt tên thư mục/file mà Client lưu ảnh. Đặt tên có ý nghĩa để sau này tìm lại bằng chứng cho đúng luồng. Bạn có thể để trống nếu không cần dùng.
Folder	folder	string	.	Thư mục trên máy Client để lưu ảnh chụp màn hình. Bạn có thể để trống nếu không cần dùng.
Full Page	full_page	boolean	true	Bật thì xử lý toàn bộ chiều dài trang bằng cách cuộn và ghép lại; tắt thì chỉ xử lý phần đang hiển thị trên màn hình. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

count_element (developer.count_element)

Đếm phần tử khớp selector/XPath (bản dành cho debug, tương đương Element → count_element).

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Remote Port *	remote_port	string	={{$json.remote_port}}	Cổng CDP dùng để định tuyến lệnh tới ĐÚNG session trên máy worker. Nối thẳng từ node mở profile: {{ $json.remote_port }}. Dùng 127001 cho session local (node PyAutoGUI_Local_browser_connect tự trả về giá trị này).
Target	target	string	—	Selector trỏ tới phần tử cần thao tác. Chấp nhận tiền tố css=, id=, text= để chọn theo kiểu tương ứng. Bạn có thể để trống nếu không cần dùng.
XPath	xpath	string	—	Đường dẫn XPath tới phần tử. Dùng khi CSS selector không đủ, ví dụ cần lọc theo nội dung chữ hoặc đi ngược lên phần tử cha. Bạn có thể để trống nếu không cần dùng.

Dấu = trường bắt buộc. Ô rỗng của trường tùy chọn sẽ bị loại khỏi payload; Client tự áp mặc định.

Chương 17 — Nhóm 10. General Debug

Hình 17.1. Danh sách action nhóm General Debug trong dropdown, mỗi action kèm câu tóm tắt.

Nhóm này có 1 action. Từng action và bảng tham số đầy đủ như dưới đây.

debug_publish (general.debug_publish)

Bắn một bản tin tùy ý (text/JSON/số/cờ) qua MQTT để kiểm tra đường truyền node ↔ broker ↔ Client. Dùng khi nghi ngờ sai topic, sai credential hoặc Client không subscribe.

Tên trên UI	Khóa payload	Kiểu	Mặc định	Ý nghĩa
Debug Text	text	string	—	Chuỗi tùy ý gửi kèm bản tin debug để nhận diện ở phía Client. Bạn có thể để trống nếu không cần dùng.
Debug JSON	json	json	—	Khối JSON tùy ý gửi kèm để kiểm tra đường truyền MQTT. Bạn có thể để trống nếu không cần dùng.
Debug Switch	switch	boolean	false	Một cờ boolean tùy ý gửi kèm để kiểm tra Client đọc đúng kiểu dữ liệu. Bạn có thể để trống nếu không cần dùng.
Debug Number	number	string	10	Một số tùy ý gửi kèm bản tin debug. Bạn có thể để trống nếu không cần dùng.

Chương 18 — Ví dụ thật: workflow RegHotMail

Node C12 hiếm khi đứng một mình; nó nối thành chuỗi dài. Workflow thật '02_RegHotMail_WEB_PyAutoGUI_TEST_MCP' dùng 37 node C12 để tự động đăng ký hộp thư.

Hình 18.1. Workflow thật RegHotMail — nhiều node C12 nối tiếp thành một luồng đăng ký.

Hình 18.2. Một node C12 đã cấu hình trong ngữ cảnh workflow thật.

Chương 19 — Thực thi và đọc kết quả

Bấm Execute step để chạy thử riêng node. Node publish payload lên topic; nếu bật Wait For Response, node chờ RES_<topic>. Với action không cần máy thật (ví dụ debug_publish, waitForResponse tắt), node publish xong trả ngay payload đã gửi.

Hình 19.1. Trước khi chạy: cột OUTPUT hiển thị 'No output data'.

Hình 19.2. Sau khi Execute: cột OUTPUT hiển thị kết quả node trả về.

NGUY HIỂM · EXECUTE CHẠM MÁY THẬT

Execute một action Manager/Mouse/Keyboard với topic của một máy worker THẬT sẽ điều khiển máy đó ngay lập tức (mở profile, di chuột...). Khi chỉ muốn thử giao diện, hãy dùng topic nháp không có worker nào subscribe, hoặc dùng debug_publish với Wait For Response tắt.

Chương 20 — Đồng bộ, QoS và nhịp giống người

20.1 Chờ phản hồi hay không

Wait For Response quyết định node có chờ kết quả không. Bật khi bước sau cần dữ liệu/kết quả của bước này (đọc text, đọc OTP, mở profile lấy remote_port). Tắt khi chỉ 'bắn rồi đi' (ví dụ publish debug).

20.2 QoS chọn mức nào

QoS	Ý nghĩa	Dùng khi
0	At most once — nhanh, có thể mất gói	Tác vụ không quan trọng, chấp nhận mất
1	At least once — có xác nhận (mặc định)	Phần lớn trường hợp
2	Exactly once — đảm bảo cao nhất	Lệnh không được phép lặp

20.3 Nhịp giống người

Delay Next Step (ms) hỗ trợ cú pháp rand(a,b) để mỗi lần chạy trễ một khoảng ngẫu nhiên, cùng với chuyển động chuột tự nhiên và gõ theo WPM ở bên Client, giúp thao tác khó bị nhận diện là máy.

Chương 21 — Sao lưu và khôi phục profile

Trạng thái đăng nhập (cookie, session) nằm trong thư mục profile. Kho NAS2 (WP2_GPM_Profile_RW) là nơi sao lưu tập trung; mỗi profile là một bản .tar.

Thành phần	Sao lưu ở đâu	Cách khôi phục
Profile GPM/local	Kho NAS2 dạng .tar (qua push_profile)	pull_profile tải bản mới nhất về worker rồi Open
Local Test Profile	Bản sao trong %TEMP% trên worker	Copy Master Profile to Test Profile tạo lại
Credential MQTT	Trong n8n (mã hóa)	Khai báo lại trong n8n nếu mất

GHI CHÚ · LEASE CHỐNG GHI ĐÈ

pull_profile giành lease + bật heartbeat tự gia hạn trước khi tải; push_profile nhả lease sau khi upload. Nhờ vậy hai máy không cùng ghi đè một profile. Đây là điều kiện để chạy nhiều worker song song an toàn.

Chương 22 — Các thao tác không hoàn tác được

NGUY HIỂM · QUIT / QUIT_ALL

quit đóng trình duyệt theo remote_port; Quit_All giết luôn browser của CÁC NHÁNH SONG SONG. Trong workflow chạy nhiều phiên cùng lúc, Quit_All có thể giết nhầm phiên đang chạy dở. Dùng quit + remote_port chính xác.

NGUY HIỂM · CLEAR LOCAL TEST PROFILE

Xóa sạch thư mục bản sao. Không hoàn tác — muốn có lại cookie/đăng nhập phải Copy Master Profile lại từ đầu.

NGUY HIỂM · DELETE PROFILE PHÍA GPM / MODE 2

Ở các node quản lý profile GPM (C11), xóa mode 2 xóa cả dữ liệu trên đĩa. C12 không xóa profile GPM, nhưng khi phối hợp cần nhớ ranh giới này.

Chương 23 — Bảng tra triệu chứng — nguyên nhân — cách chữa

Triệu chứng	Nguyên nhân thường gặp	Cách chữa
Node báo lỗi 'Topic is required'	Ô Topic để trống	Điền topic của máy worker
Chờ mãi không có phản hồi	Client không subscribe đúng topic, hoặc không echo requestId	Kiểm topic; kiểm Client publish lên RES_<topic> kèm meta.requestId
Node trả lỗi return NG	Client thực thi thất bại	Đọc field error/message trong output; xem log Client
wait_color luôn fail	Điểm màu/tolerant sai, hoặc màn hình đổi độ sáng	Chỉnh tọa độ, nới tolerant, kiểm zoom=100
Action ảnh không chạy	Trình duyệt đang headless	Tắt headless — nhóm Image cần cửa sổ thật
Không thấy phần tử trong iframe	Chưa switch_to_frame hoặc quên switch_to_default	Vào đúng frame; xong quay về default
Dò cổng CDP ra 127001	Đó là cổng ẢO của session local	Loại 127001 ra khi dò cổng thật

Chương 24 — Bài thực hành

24.1 Lab 1 — Gửi một bản tin debug

3. Đặt Topic = một chuỗi nháp (ví dụ ZZZ_DOC_TEST), tắt Wait For Response.

Tiêu chí đạt: OUTPUT có khối mqtt với payload đúng version/action/inputs/meta.

24.2 Lab 2 — Mở profile rồi click

1. Node 1: Manager -> Open Test/Local Profile, Topic = topic worker của bạn, bật Wait For Response.

2. Node 2: Mouse -> click, nối remote_port từ node 1, điền X/Y hoặc XPath.

3. Chạy lần lượt; quan sát remote_port truyền từ node 1 sang node 2.

Tiêu chí đạt: trình duyệt mở đúng profile và con trỏ click đúng vị trí.

Phụ lục A — Bảng tra toàn bộ 59 action

1. Manager

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
Pull_Profile_from_NAS	manager.pull_profile	pull_profile	6
Push_Profile_to_NAS	manager.push_profile	push_profile	7
PyAutoGUI_Open_Test/Local_Profile	manager.local_browser_connect	local_browser_connect	13
PyAutoGUI_Open_GPM_Profile	manager.open_profile	open_profile	17
Copy Master Profile to Test Profile	manager.sync_master_profile_to_local_test_profile	sync_master_profile_to_local_test_profile	2
Clear Local Test Profile	manager.clear_local_test_profile	clear_local_test_profile	0
Quit/Quit_All	manager.quit	quit	3

2. Mouse

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
click	mouse.click	click	8
many_click	mouse.many_click	many_click	10
move	mouse.move	move	7
mouse_click_and_hold	mouse.mouse_click_and_hold	mouse_click_and_hold	6
mouse_release	mouse.mouse_release	mouse_release	2
mouse_scroll	mouse.mouse_scroll	mouse_scroll	6
mouse_scroll_top	mouse.mouse_scroll_top	mouse_scroll_top	2
mouse_scroll_bottom	mouse.mouse_scroll_bottom	mouse_scroll_bottom	2
mouse_scroll_object	mouse.mouse_scroll_object	mouse_scroll_object	5

3. Keyboard

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
type	keyboard.type	type	7
press_key	keyboard.press_key	press_key	5
combo_key	keyboard.combo_key	combo_key	2
vcopy	keyboard.vcopy	vcopy	3
vpaste	keyboard.vpaste	vpaste	3

4. Browser Control

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
Next	browser.next	Next	1
Previous	browser.previous	Previous	1
Refresh	browser.refresh	Refresh	1
URL	browser.url	URL	4
NewTab	browser.new_tab	NewTab	3
CloseTab	browser.close_tab	CloseTab	2
CloseOthersTab	browser.close_others_tab	CloseOthersTab	2
SwitchTab	browser.switch_tab	SwitchTab	2

5. Element

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
wait_element	element.wait_element	wait_element	5
get_text	element.get_text	get_text	4
get_attribute	element.get_attribute	get_attribute	5
count_element	element.count_element	count_element	3

6. Image

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
ImageClick	image.image_click	image_click	7
ImageMove	image.image_move	image_move	6
ImageType	image.image_type	image_type	8
ImageWait	image.image_wait	image_wait	5
NotImageWait	image.not_image_wait	not_image_wait	5
WaitColor	image.wait_color	wait_color	4
Clean ImageStorage	image.clean_image_storage	clean_image_storage	1
wait_to_image	image.wait_to_image	wait_to_image	8
check_image_exist	image.check_image_exist	check_image_exist	6
image_search	image.image_search	image_search	6

7. Others

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
random	others.random	random_value	19
check_popup_and_frame	others.check_popup_and_frame	check_popup_and_frame	1
switch_to_popup	others.switch_to_popup	switch_to_popup	2
switch_to_frame	others.switch_to_frame	switch_to_frame	2
switch_to_default	others.switch_to_default	switch_to_default	1
accept_alert	others.accept_alert	accept_alert	3
cancel_alert	others.cancel_alert	cancel_alert	2
execute_javascript	others.execute_javascript	execute_javascript	3

8. Email

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
read_mail_code	email.read_mail_code	read_mail_code	15

9. Developer

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
get_active_code	developer.getcode	get_active_code	1
get_iframe_code	developer.get_iframe_code	get_iframe_code	2
get_full_code	developer.get_full_code	get_full_code	5
get_info	developer.get_info	get_info	1
capture	developer.capture	capture	4
count_element	developer.count_element	count_element	3

10. General Debug

Action (nhãn)	Khóa (key)	Hàm Client	Số tham số
debug_publish	general.debug_publish	debug_publish	4

Phụ lục B — Sự cố đã trả giá (đúc kết từ bộ nhớ dự án)

B.1 Định tuyến đa phiên C12

Khi một worker mở nhiều profile song song, node phải mang theo remote_port/profile_id để mỗi action bám đúng phiên. Đã thêm remote_port/profile_id vào phần lớn các node điều khiển. Bên A12/Playwright không cần mutex như PyAutoGUI vì thao tác ở tầng DOM.

B.2 Đua tiến trình khi Clear/Sync/Open Local Profile

Workflow TEST_Clear_Sync_Open_LocalProfile từng lỗi WinError 5/6 do spawn trùng khóa profile. Cách chữa: serialize theo từng khóa profile (không cho hai tiến trình cùng khóa chạy song song).

B.3 raw_proxy chỉ ở create/update, không ở open

/profiles/start KHÔNG nhận proxy. Muốn đổi proxy phải Update Profile (raw_proxy) TRƯỚC rồi mới Open. open_profile chạy bằng proxy đã lưu sẵn trên profile.

B.4 Kho profile NAS2

docs/tools/profile_store.py đã kiểm trên SMB thật; lease + heartbeat + upload nguyên tử (incoming/ + rename) là bất biến để nhiều worker không ghi đè nhau.

Phụ lục C — Bảng thuật ngữ

Thuật ngữ	Nghĩa
NDV	Node Detail View — bảng cấu hình mở ra khi bấm đúp node.
payload	Bản tin JSON node gửi qua MQTT.
topic / RES_topic	Kênh gửi request / kênh nhận phản hồi (tự suy ra bằng tiền tố RES_).
requestId	Mã 16 hex để khớp request với response.
CDP	Chrome DevTools Protocol — giao thức điều khiển Chrome; remote_port là cổng CDP.
remote_port 127001	Cổng ẢO báo 'session local' (không phải cổng CDP thật).
GPM	GPM-Login — phần mềm quản lý profile chống fingerprint.
lease	Khóa phiên trên kho NAS2 để một profile chỉ một máy ghi tại một thời điểm.
AUTO-ARGS	Cơ chế worker tự đọc config.json để thêm cờ Chrome khi mở profile.

Phụ lục D — Nguồn và cách dựng tài liệu

Tài liệu dựng bằng quy trình UID_04: đọc bundle node đang chạy trong container lotus_n8n để lấy cấu trúc 59 action / 273 tham số; chụp giao diện n8n bằng Chrome thật trên B35; đánh số ảnh bằng vòng tròn chỉ viền; vẽ sơ đồ phẳng bằng matplotlib; dựng .docx bằng bộ docs/tools/docgen với Heading style thật để sinh mục lục.

Mã nguồn node: Library/C12_N8N_MQTT_PyAutoGUI_Web/. Tài liệu kỹ thuật kèm theo: Agent_Readme.md, Agent_Actions_Reference.md, Agent_MQTT_Protocol.md, Agent_Codegen_Architecture.md.

GREAT LOTUS PYAUTO WEB (node C12)

Giáo trình kỹ thuật & vận hành — tự động hóa web trên desktop thật qua MQTT

Chương 0 — Lời nói đầu

0.1 Tài liệu này viết cho ai

0.2 Kỷ luật nguồn

0.3 Trạng thái hệ thống lúc chụp ảnh

Chương 1 — Node C12 là gì và giải quyết vấn đề gì

1.1 Một câu định nghĩa

1.2 Vấn đề nó giải quyết

1.3 Ranh giới trách nhiệm

Chương 2 — Vị trí trong họ node Great Lotus

Chương 3 — Luồng end-to-end và giao thức MQTT

3.1 Một lần chạy node

3.2 Kênh và quy tắc topic

3.3 Cấu trúc bản tin request

Chương 4 — Kiến trúc sinh giao diện tự động (data-driven)

Chương 5 — Quản lý profile trình duyệt

5.1 Vòng đời Local Test Profile

5.2 Luồng profile qua kho NAS2 (Pull / Push)

5.3 Nối phiên qua remote_port (session chaining)

Chương 6 — Giải phẫu bảng cấu hình node (NDV)

Chương 7 — Các trường dùng chung cho mọi action

7.1 Trường hiện theo ngữ cảnh

7.2 Tooltip mỗi ô nhập

7.3 Chọn Credential MQTT

7.4 Tab Settings

Chương 8 — Nhóm 1. Manager

Pull_Profile_from_NAS (manager.pull_profile)

Push_Profile_to_NAS (manager.push_profile)

PyAutoGUI_Open_Test/Local_Profile (manager.local_browser_connect)

PyAutoGUI_Open_GPM_Profile (manager.open_profile)

Copy Master Profile to Test Profile (manager.sync_master_profile_to_local_test_profile)

Clear Local Test Profile (manager.clear_local_test_profile)

Quit/Quit_All (manager.quit)

Chương 9 — Nhóm 2. Mouse

click (mouse.click)

many_click (mouse.many_click)

move (mouse.move)

mouse_click_and_hold (mouse.mouse_click_and_hold)

mouse_release (mouse.mouse_release)

mouse_scroll (mouse.mouse_scroll)

mouse_scroll_top (mouse.mouse_scroll_top)

mouse_scroll_bottom (mouse.mouse_scroll_bottom)

mouse_scroll_object (mouse.mouse_scroll_object)

Chương 10 — Nhóm 3. Keyboard

type (keyboard.type)

press_key (keyboard.press_key)

combo_key (keyboard.combo_key)

vcopy (keyboard.vcopy)

vpaste (keyboard.vpaste)

Chương 11 — Nhóm 4. Browser Control

Next (browser.next)

Previous (browser.previous)

Refresh (browser.refresh)

URL (browser.url)

NewTab (browser.new_tab)

CloseTab (browser.close_tab)

CloseOthersTab (browser.close_others_tab)

SwitchTab (browser.switch_tab)

Chương 12 — Nhóm 5. Element

wait_element (element.wait_element)

get_text (element.get_text)

get_attribute (element.get_attribute)

count_element (element.count_element)

Chương 13 — Nhóm 6. Image

ImageClick (image.image_click)

ImageMove (image.image_move)

ImageType (image.image_type)

ImageWait (image.image_wait)

NotImageWait (image.not_image_wait)

WaitColor (image.wait_color)

Clean ImageStorage (image.clean_image_storage)

wait_to_image (image.wait_to_image)

check_image_exist (image.check_image_exist)

image_search (image.image_search)

Chương 14 — Nhóm 7. Others

random (others.random)

check_popup_and_frame (others.check_popup_and_frame)

switch_to_popup (others.switch_to_popup)

switch_to_frame (others.switch_to_frame)