Giải phẫu Flow

Flow là một tài liệu được lưu. Biết bên trong nó có gì khiến trình soạn thảo trở nên dự đoán được, giải thích vì sao có thứ tái dùng được có thứ không, và cho bạn biết cái gì thực sự di chuyển khi bạn export một flow sang máy khác.

Mục đích

Trang này mô tả các bộ phận của một flow và quan hệ giữa chúng. Đọc nó trước flow phức tạp đầu tiên của bạn, và đọc lại khi bạn bắt đầu tách việc thành các Sub Flow.

Các bộ phận

Mọi thứ trên sơ đồ đều được lưu trong flow. Flow bạn export mang theo tất cả.

Node

Node là một bước có kiểu. Mỗi node có:

Trường	Ý nghĩa
id	Định danh ổn định — không bao giờ đổi, sống qua đổi tên
type	Loại node (action.click, detect.image, …)
name	Nhãn bạn thấy trên canvas — chữ tự do, đổi thoải mái
params	Thiết lập của node, riêng theo loại
retryPolicy	Retry theo node (tùy chọn), hoặc không có
outputMappings	Ghi từ output của node vào biến (tùy chọn)
ui	Vị trí canvas, màu, trạng thái thu gọn

Hệ quả quan trọng: id là định danh, name là nhãn. Đổi tên node không bao giờ đứt kết nối, và hai node có thể trùng tên.

Node không sở hữu việc định tuyến của nó. Node báo nó rời qua port nào; các edge của flow quyết định điều đó dẫn tới đâu. Vì vậy bạn nối lại dây một flow mà không đụng thiết lập của node nào.

Port

Port là lối ra có tên trên node. Phần lớn loại node có bộ cố định:

• success, failure, timeout, cancelled, fatal cho đa số node
• true / false cho If đơn giản
• matched / notMatched cho Memory Match
• solved / unsolved / failure cho Captcha

Có những node tính port từ chính thiết lập của chúng:

Node	Port phụ thuộc vào
If chế độ Multiple Branches	một case1…caseN mỗi nhánh, cộng default
If chế độ Text-match	match / noMatch
Find Image chế độ Branch-by-template	một port mỗi template được chọn, cộng notFound
Branch (Random Branch)	branch1…branchN từ số nhánh

Khi bạn giảm số nhánh, các port cuối biến mất và trình soạn thảo tự cắt các edge mồ côi cho bạn.

Port bắt buộc và port tùy chọn

Có port phải nối thì flow mới hợp lệ; có port được phép bỏ ngỏ có chủ đích.

• Bắt buộc — bỏ trống là lỗi kiểm tra. success trên đa số node.
• Tùy chọn (khoan dung) — bỏ trống là lựa chọn "dừng ở đây" hợp lệ. Lần chạy kết thúc nhẹ nhàng nếu đi vào.

Branch là ca nghiêm ngặt: mọi port nhánh phải được nối, vì runtime có thể chọn bất kỳ nhánh nào và một nhánh bỏ trống sẽ ngẫu nhiên làm cụt đường lần chạy.

Edge

Edge nối port của node này vào node khác. Edge mang:

Trường	Ý nghĩa
fromNodeId + fromPort	Rời từ đâu
toNodeId	Đi đến đâu
priority	Thứ tự khi nhiều edge chung một port
condition	Điều kiện gác tùy chọn, định giá lúc phân giải

Nhiều edge có thể rời cùng một port. Chúng được thử theo thứ tự priority; xem Phân giải edge.

Region

Region là hình chữ nhật có tên, lưu theo phần trăm màn hình, không phải pixel.

Chính cách lưu phần trăm đó là lý do flow xây trên một độ phân giải vẫn chạy trên độ phân giải khác. Region che một phần tư trên-phải của màn 1280×720 cũng che một phần tư trên-phải của màn 1920×1080.

Region có id (định danh) và name (nhãn). Node gắn vào id, nên đổi tên region không đứt các node đang dùng nó.

Region lưu được vào Region Library để tái dùng giữa các flow.

Asset — ảnh template

Asset là ảnh template đã chụp mà node Find Image so khớp. Mỗi asset ghi:

• file ảnh và checksum của nó,
• kích thước pixel,
• độ phân giải nơi chụp,
• một đánh giá chất lượng — entropy, mật độ cạnh, tỉ lệ màu trội, và có được khuyến nghị không.

Đánh giá chất lượng là lý do ứng dụng cảnh báo được template quá trơn hoặc quá rối để so khớp ổn định.

Chất lượng template là thiết lập thật, không phải trang trí

Template gần như một màu phẳng có entropy thấp và sẽ khớp nhiều chỗ trên màn hình. Template dính nhiều nền sẽ ngừng khớp ngay khi thứ gì phía sau thay đổi. Hãy chụp cắt sát phần đặc trưng.

Group

Group là khung có tên vẽ quanh một phần canvas, tùy chọn kèm ghi chú, tùy chọn thu gọn.

Group là đồ nội thất soạn thảo thuần túy. Không port, không thiết lập, không bao giờ thực thi. Tư cách thành viên là hình học — group chứa những thẻ mà khung của nó bao — nên kéo node vào/ra group chỉ là một cú kéo, và không node nào lưu id cha có thể mốc meo.

Group không thành viên chỉ có ghi chú chính là hộp comment của bạn. Không có khái niệm comment thứ hai phải học.

Settings

Settings của flow chia bốn khối.

Target

Flow này kỳ vọng giả lập nào: tên instance ưu tiên, ADB serial, độ phân giải và hướng màn kỳ vọng.

Defaults

Giá trị dự phòng các node dùng khi không tự chỉ định:

Thiết lập	Khoảng	Bao trùm
timeoutMs	100–120000	Timeout node mặc định
pollIntervalMs	50–5000	Chu kỳ poll phát hiện mặc định
waitAfterActionMs	0–60000	Thời gian ổn định sau hành động mặc định
imageThreshold	0.5–0.99	Độ tin cậy khớp mặc định

Runtime

Rào chắn và chính sách thực thi:

Thiết lập	Khoảng	Hiệu ứng
maxNodeExecutions	1–100000	Trần cứng tổng số node thực thi
maxRuntimeDurationMs	1000–86400000	Trần cứng thời gian chạy
maxConsecutiveFailures	1–1000	Trần cứng lỗi liên tiếp
captureFailureScreenshots	boolean	Lưu ảnh chụp khi node hỏng
inputMode	adb / native	Cách input được gửi
frameSync	object	Quy tắc độ tươi khung hình (dưới đây)

Features

Cổng tính năng theo flow: ocrEnabled, nativeInputEnabled, multiScaleImageDetectionEnabled.

OCR gác theo flow

Read Text không chạy trong flow có cổng ocrEnabled tắt. Node Read Text hỏng ngay không output? Kiểm thiết lập này trước khi gỡ vùng đọc.

Đồng bộ khung hình

Phát hiện phải đọc bức ảnh hiện tại của màn hình, không phải ảnh cũ. Các thiết lập frameSync điều khiển điều đó:

Thiết lập	Khoảng	Ý nghĩa
requireFreshFrameAfterInput	boolean	Sau khi gửi input, chờ khung hình mới thực sự
maxFrameAgeMs	16–5000	Khung hình được phép cũ bao nhiêu mà vẫn dùng được
freshFrameTimeoutMs	100–30000	Chờ khung hình tươi đó bao lâu
visualStabilityFrames	0–10	Cần bao nhiêu khung liên tiếp ổn định

Khung hình dùng được khi now - frame.capturedAt <= maxFrameAgeMs.

Đây là thứ chặn con bug automation kinh điển: bạn chạm nút rồi lập tức "nhìn thấy" màn hình trước cú chạm.

Định danh nghĩa là gì cho việc tái dùng

Vì nhiều thứ định danh bằng id ổn định thay vì tên, những việc sau đều an toàn:

• Đổi tên node, region, hay template.
• Di chuyển node trên canvas.
• Sắp lại nhánh (port theo vị trí nhưng edge bám theo).

Và những việc sau thì không:

• Xóa template mà một Find Image branch-by-template đang rẽ theo — port của nó biến mất cùng.
• Giảm số nhánh xuống dưới nhánh đã nối — edge cuối bị cắt.

Best practices

• Đặt tên node theo ý định, đánh số theo thứ tự đọc. 1. Find a gem on screen, 2. Swipe it to the centre. Automation tham chiếu trong bộ tài liệu này làm đúng vậy, và nó khiến một flow 13 node đọc được trong một cái liếc.
• Dùng group đánh dấu các pha, rồi thu gọn pha bạn không làm việc.
• Đưa hình chữ nhật tái dùng vào Region Library thay vì vẽ lại.
• Đặt mặc định flow một lần thay vì đặt cùng timeout trên hai mươi node.
• Mỗi flow một việc. Không mô tả được flow trong một câu thì nó muốn được tách thành Sub Flow.

Ghi chú hiệu năng

• Phát hiện giới hạn vùng nhanh hơn hẳn phát hiện toàn màn, vì bộ so khớp làm việc trên mảnh cắt. Đặt search region là cú tăng tốc rẻ nhất hiện có.
• Số template nhân chi phí so khớp. Find Image đa template với 16 template làm việc gấp ~16 lần một template trên cùng khung hình.
• Mặc định flow không tốn gì lúc chạy — chúng được phân giải lúc biên dịch.

Ghi chú bộ nhớ

• Asset template được nạp và cache để so khớp. Flow nhiều template lớn có working set lớn hơn flow vài mảnh cắt sát.
• Group, region và dữ liệu ui của node chỉ phục vụ soạn thảo. Chúng lưu trong flow nhưng không bao giờ vào đường nóng của runtime.

Lỗi thường gặp

Lỗi	Hậu quả	Cách sửa
Nhớ tọa độ theo pixel	Flow vỡ trên độ phân giải khác	Dùng region — chúng theo phần trăm
Chụp template kèm nền	Ngừng khớp khi nền đổi	Cắt sát phần đặc trưng
Dựa vào tên node để nối dây	Vô hiệu — tên là nhãn	Nối port; id là định danh
Để ocrEnabled tắt	Read Text không làm gì	Bật trong flow settings
Một flow khổng lồ	Không đọc nổi, không test nổi	Tách thành Sub Flow

Khắc phục sự cố

Flow hợp lệ nhưng một nhánh mờ đi hoặc biến mất. Bộ port được tính từ thiết lập với If (multi-branch / text-match), Find Image (branch-by-template) và Branch. Kiểm số nhánh hoặc lựa chọn template.

Template ngừng khớp sau khi tôi đổi độ phân giải giả lập. So khớp template theo pixel. Chụp lại template, hoặc bật phát hiện đa tỉ lệ trong cổng tính năng của flow.

Read Text không trả gì cả. Kiểm features.ocrEnabled trong flow settings trước tiên.

FAQ

Đổi tên flow có đứt các lời gọi Sub Flow đến nó? Không. Lời gọi gắn với id flow; tên là cache hiển thị.

Group có được export cùng flow? Có. Chúng là một phần tài liệu flow.

Hai node trùng tên được không? Được. Tên là nhãn, không phải định danh.

Region sống ở flow hay ở library? Cả hai đều có thể. Hình chữ nhật vẽ tại chỗ thuộc flow; lưu vào Region Library thì tái dùng được giữa các flow.

Trang liên quan

• Mô hình thực thi — các bộ phận này chạy ra sao
• Biến và bộ nhớ — khối khai báo
• Sub Flows — tách flow lớn
• Tra cứu Node — mọi loại node