Hướng dẫn Jev GUI Delegate: Để Codex ủy quyền thao tác GUI trên Windows và Chrome

Tổng quan dự án

Jev GUI Delegate là một nguyên mẫu ủy quyền GUI trên Windows và Chrome dành cho Codex. Mô hình chính chịu trách nhiệm đưa ra mục tiêu nhiệm vụ và điều kiện nghiệm thu; bộ điều khiển cục bộ chịu trách nhiệm quan sát giao diện, khớp với các điều khiển, thực hiện thao tác và kiểm tra kết quả thực tế sau mỗi bước. Bộ điều khiển chỉ gọi TypeSafe Jev khi gặp lựa chọn ngữ nghĩa không thể xử lý bằng các quy tắc xác định.

Vấn đề cốt lõi mà dự án giải quyết là: nếu mô hình chính thao tác từng bước trên trang web hoặc ứng dụng máy tính, mô hình phải liên tục đọc giao diện, chọn điều khiển và xử lý phản hồi từ công cụ, tạo thành một vòng lặp thao tác có chi phí cao. Jev GUI Delegate giao một chuỗi thao tác có thể nghiệm thu rõ ràng cho bộ điều khiển cục bộ thực hiện liên tục, đồng thời vẫn giữ khả năng kiểm tra trạng thái, khôi phục ngoại lệ và để người dùng tiếp quản.

Dự án này là một nguyên mẫu do cá nhân thiết kế, dùng AI để triển khai và liên tục nghiệm thu. Đóng góp của dự án bao gồm hợp đồng nhiệm vụ, điều phối công cụ, cơ chế khôi phục, kiểm tra quyền, kiểm thử và lặp lại dựa trên phản hồi; mô hình Jev, TypeSafe SDK, Codex và tiện ích trình duyệt là các sản phẩm thượng nguồn.

Quy trình hoạt động

1. Mô hình chính Codex gửi mục tiêu và điều kiện nghiệm thu.

2. Nhiệm vụ được chuyển thành một hợp đồng nhiệm vụ cục bộ có thể kiểm tra.

3. Bộ điều khiển quan sát giao diện hiện tại và thử khớp điều khiển theo cách xác định.

4. Khi không thể phán đoán trực tiếp, bộ điều khiển gọi Jev để lựa chọn theo ngữ nghĩa.

5. Thao tác trên Chrome được thực hiện thông qua phiên trình duyệt chính thức tương thích do máy chủ cung cấp; thao tác trên Windows được thực hiện thông qua UI Automation.

6. Bộ điều khiển xác minh kết quả thực tế, lưu tiến độ và quyết định tiếp tục, khôi phục, tạm dừng hoặc yêu cầu mô hình chính bổ sung thông tin.

Quy trình này không sao chép cấu hình trình duyệt cá nhân và không trích xuất Cookie. Luồng Chrome phụ thuộc vào API phiên trình duyệt chính thức tương thích do máy chủ Codex cung cấp; bản thân kho mã không thể tạo hoặc thay thế phiên này.

Tính năng chính

Hai luồng thực thi GUI

• Chrome: sử dụng lại phiên trình duyệt chính thức do máy chủ cung cấp.

• Windows: sử dụng Windows UI Automation để thao tác các điều khiển máy tính có thể truy cập.

Hợp đồng nhiệm vụ tường minh

Hợp đồng nhiệm vụ mô tả rõ mục tiêu, thao tác được phép, phạm vi thao tác, dữ liệu đầu vào cần thiết, các bước thực hiện và điều kiện thành công. Nhờ đó, bộ điều khiển có thể kiểm tra quyền và phạm vi trước khi thực hiện, đồng thời dựa trên điều kiện thành công để xác định nhiệm vụ đã thực sự hoàn tất hay chưa.

Gọi Jev khi cần

Các điều khiển có thể xác định bằng quy tắc cục bộ sẽ được mã trực tiếp khớp; Jev chỉ được gọi khi cần hiểu ý nghĩa văn bản hoặc ngữ nghĩa của các lựa chọn. Dự án ghi nhận riêng trường hợp không gọi mô hình theo thực tế, không tính nhầm trường hợp này là một lần suy luận Jev thành công.

Thực thi liên tục và khôi phục

Bộ điều khiển có thể lưu tiến độ thực hiện và xử lý các tình huống như thiếu dữ liệu đầu vào, chọn sai cục bộ, tạm dừng, hủy và người dùng tiếp quản. Nếu không thể xác nhận thao tác gửi đã thành công hay chưa, bộ điều khiển sẽ không tự động phát lại thao tác gửi để giảm rủi ro gửi trùng.

Kiểm tra kết quả và an toàn

Hệ thống kiểm tra danh tính, quyền hạn và phạm vi trước khi thao tác, sau đó kiểm tra giá trị thực tế hoặc trạng thái trang. Mức sử dụng mô hình và nguyên nhân thất bại được ghi nhận riêng để thuận tiện phân biệt vấn đề chi phí với vấn đề thực thi.

Môi trường chạy và điều kiện tiên quyết

Dự án hướng đến các môi trường sau:

• Windows x64

• Python 3.12

• Node.js

• Môi trường máy tính tương tác để thao tác GUI gốc

• Nếu sử dụng luồng Chrome, cần có API phiên trình duyệt chính thức tương thích do máy chủ Codex cung cấp

Khuyến nghị cài đặt dự án vào C:\jev\jev-bridge. Một số lệnh lịch sử và ví dụ Codex skill mặc định sử dụng vị trí này. Nếu chọn thư mục khác, cần đồng thời sửa các ví dụ và cấu hình liên quan.

Cài đặt dự án

Bước 1: Sao chép kho mã và tạo môi trường ảo

git clone https://github.com/YUTA-fywoo/jev-gui-delegate.git C:\jev\jev-bridge
cd C:\jev\jev-bridge
py -3.12 -m venv .venv

Bước 2: Cài đặt các phụ thuộc đã khóa

.\.venv\Scripts\python.exe -m pip install --require-hashes -r requirements.lock

--require-hashes cài đặt các phụ thuộc dựa trên mã băm trong tệp khóa, giúp bảo đảm nội dung cài đặt nhất quán với bản ghi của dự án. Thư mục phụ thuộc bên thứ ba không được công khai cùng kho mã và phải được cài đặt từ kênh phát hành chính thức.

Bước 3: Chuẩn bị môi trường chạy

.\.venv\Scripts\python.exe scripts/setup-runtime.py

Bước 4: Chạy kiểm thử ngoại tuyến

.\.venv\Scripts\python.exe -m unittest discover -s gui_delegate/tests -p "test_*.py"

Các bài kiểm thử này bao phủ bộ điều khiển, quy trình khôi phục và các điều kiện biên. Hồi quy ngoại tuyến sử dụng dữ liệu tổng hợp và đối tượng thay thế được kiểm soát, không tương đương với thao tác GUI thực tế và không giả mạo yêu cầu Jev theo thời gian thực. Để xem kết quả đầy đủ hơn, hãy tham khảo tài liệu xác thực bản phát hành trong kho mã.

Cấu hình khóa Jev

Khóa có thể được cung cấp thông qua biến môi trường cục bộ TYPESAFE_API_KEY hoặc Trình quản lý thông tin xác thực của Windows. Dự án khuyến nghị sử dụng cửa sổ nhập cục bộ được mở bằng set-key.cmd để thiết lập.

set-key.cmd

Không ghi khóa vào kho Git, hợp đồng nhiệm vụ hoặc nội dung trò chuyện. chrome-runtime.json do máy cài đặt tạo đã được bỏ qua; kho mã không chứa đường dẫn môi trường trên máy của tác giả ban đầu.

Đăng ký với Codex

Khi cần kết nối dự án với Codex, hãy chạy các tập lệnh cài đặt sau trong thư mục dự án:

install.cmd
gui-install.cmd

Trình cài đặt sẽ sửa đổi cấu hình MCP, skill và định tuyến ở cấp người dùng, đồng thời giữ bản sao lưu và kiểm tra xung đột. Nếu máy đã có thư mục cùng tên, trước tiên cần kiểm tra mục đích sử dụng; trình cài đặt sẽ không trực tiếp ghi đè dự án đang được sử dụng trên máy.

Codex skill cá nhân có thể cài đặt nằm tại gui_delegate/skill/SKILL.md. Nếu dự án không được cài đặt trong thư mục mặc định, cũng cần kiểm tra các ví dụ có đề cập đến đường dẫn trong tệp này.

Sử dụng và xác thực cơ bản

Kiểm tra trạng thái sẵn sàng cục bộ

Sau khi cài đặt, có thể chạy:

health.cmd

health.cmd chỉ kiểm tra các thành phần đã sẵn sàng hay chưa, không có nghĩa là đã thực hiện xác thực Jev theo thời gian thực và cũng không có nghĩa là máy hiện tại đã vượt qua nghiệm thu trong các tình huống GUI thực tế.

Thực hiện xác thực theo thời gian thực

Các quy trình xác thực theo thời gian thực như verify.cmd do dự án cung cấp sẽ gọi dịch vụ Jev:

verify.cmd

Trước khi chạy, cần xác nhận khóa đã được cấu hình chính xác và phân biệt kết quả hồi quy ngoại tuyến với kết quả dịch vụ theo thời gian thực. README không coi kết luận “đã xác thực trên máy cục bộ” trong môi trường phát triển lịch sử là kết luận mà mọi người cài đặt đều có thể trực tiếp kế thừa.

Thiết kế nhiệm vụ phù hợp để ủy quyền

Nguyên mẫu này phù hợp với các thao tác GUI có ranh giới rõ ràng, các bước có thể giới hạn và kết quả có thể kiểm tra. Khi giao nhiệm vụ cho bộ điều khiển, ít nhất cần nêu rõ các nội dung sau:

• Mục tiêu: trạng thái cuối cùng cần đạt được.

• Phạm vi: được phép thao tác trong những trang, cửa sổ hoặc đối tượng nào.

• Thao tác được phép: bộ điều khiển có thể thực hiện những loại tương tác nào.

• Đầu vào: dữ liệu cần thiết và được phép sử dụng để thực hiện nhiệm vụ.

• Các bước: những giai đoạn thao tác có thể thực hiện liên tục.

• Điều kiện thành công: giá trị thực tế hoặc trạng thái trang cần quan sát được sau khi hoàn tất.

Ví dụ, một nhiệm vụ có thể yêu cầu bộ điều khiển tìm điều khiển mục tiêu trong phạm vi trang được chỉ định, điền dữ liệu đầu vào đã được cấp quyền và xác nhận kết quả thông qua trạng thái trang. Các trường hợp đồng cụ thể và mô hình kết quả phải tuân theo triển khai trong gui_delegate/schema.py; không nên tự giả định định dạng mà README chưa định nghĩa.

Lộ trình đọc mã nguồn

Nếu cần hiểu cơ chế thực thi hoặc phát triển tiếp, có thể đọc theo thứ tự sau:

1. gui_delegate/schema.py: tìm hiểu hợp đồng nhiệm vụ, trạng thái và mô hình kết quả.

2. gui_delegate/controller.py: xem cách bộ điều khiển tổ chức vòng lặp thực thi.

3. gui_delegate/drivers.py: tìm hiểu trình điều khiển và cách quan sát giao diện có cấu trúc.

4. gui_delegate/security.py: xem việc kiểm tra phạm vi, quyền hạn và dữ liệu đầu vào.

5. gui_delegate/chrome_gateway.mjs: tìm hiểu điểm vào của phiên trình duyệt chính thức.

6. jev_client.py: xem lớp bao bọc Jev SDK, kiểm tra phiên bản và ghi nhận mức sử dụng.

7. gui_delegate/tests: tìm hiểu logic khôi phục và hành vi biên thông qua các bài kiểm thử.

Khuyến nghị sử dụng nâng cao

Ưu tiên khớp xác định

Nếu có thể nhận diện điều khiển thông qua thuộc tính ổn định hoặc thông tin có cấu trúc, nên ưu tiên để mã cục bộ thực hiện việc khớp. Chỉ gọi Jev khi cần phán đoán ngữ nghĩa; điều này vừa phù hợp với thiết kế dự án, vừa giúp ghi nhận chính xác mức sử dụng mô hình.

Thiết lập kết quả có thể quan sát cho từng bước

Không nên chỉ định nghĩa các thao tác như “nhấp nút”, mà còn cần định nghĩa giá trị, trạng thái điều khiển hoặc thay đổi trang dự kiến xuất hiện sau khi nhấp. Dự án nhấn mạnh việc kiểm tra kết quả thực tế, thay vì coi việc gọi công cụ thành công trực tiếp là nhiệm vụ thành công.

Xử lý thận trọng các thao tác gửi

Nếu kết quả sau khi gửi không rõ ràng, không nên giả định thất bại và tự động lặp lại thao tác. Dự án này chủ động tránh phát lại thao tác gửi khi kết quả chưa rõ. Trong tình huống như vậy, phù hợp hơn là tạm dừng, lưu tiến độ và giao cho người dùng hoặc mô hình chính xác nhận.

Tách riêng việc thiếu dữ liệu đầu vào và lỗi lựa chọn

Khi thiếu dữ liệu đầu vào cần thiết, nên bổ sung dữ liệu rồi tiếp tục; chỉ khi lựa chọn ngữ nghĩa cục bộ bị sai mới sửa lựa chọn đó. Cách này giúp tránh chạy lại nhiệm vụ từ đầu và vẫn giữ được tiến độ đã xác minh.

Xác thực lại sau khi nâng cấp phiên bản Jev

settings.json hiện cố định ở jev-1.13.0, phiên bản được sử dụng trong các bài kiểm thử lịch sử. Sau khi phiên bản máy chủ thay đổi, cần kiểm tra lại và cập nhật cấu hình; không thể coi kết quả kiểm thử của phiên bản cũ là bảo đảm chất lượng cho phiên bản mới. Chiến lược ví dụ cũng không có nghĩa là máy hiện tại đã hoàn tất hiệu chuẩn.

Hiểu đúng về kiểm thử chuẩn

README ghi nhận hai vòng kiểm thử nhiệm vụ tổng hợp vào ngày 23 tháng 9 năm 2026. Mỗi vòng bao gồm cùng 4 nhiệm vụ và 24 thao tác; cả hai nhóm nhiệm vụ đều hoàn thành 4/4.

• Trong vòng đầu tiên, Astra token giảm từ 2,266,693 xuống 236,295, giảm 89.6%; tốc độ nhiệm vụ đầu-cuối đạt 3.05 lần so với đường cơ sở.

• Trong vòng thứ hai, Astra token giảm từ 2,256,091 xuống 192,752, giảm 91.5%; tốc độ nhiệm vụ đầu-cuối đạt 3.53 lần so với đường cơ sở.

Astra token ở đây bao gồm đầu vào được lưu vào bộ nhớ đệm; mức sử dụng bổ sung của Jev được thống kê riêng. Hai vòng lặp lại cùng bốn nhiệm vụ, không đại diện cho tám tình huống độc lập; các con số này cũng không phải tỷ lệ tiết kiệm trên hóa đơn và càng không chứng minh rằng mọi ứng dụng, nhiệm vụ bất kỳ hoặc môi trường triển khai đều đạt kết quả tương tự. Kết quả token không lưu vào bộ nhớ đệm của phiên bản ba nhiệm vụ ban đầu không được cải thiện; để biết phạm vi chi tiết, hãy xem tài liệu kiểm thử.

Giới hạn đã biết

• Nguyên mẫu phụ thuộc vào DOM hoặc thông tin trợ năng có thể đọc được.

• Canvas, việc hiểu hình ảnh, màn hình bảo mật và một số điều khiển liên khung có thể không được xử lý trực tiếp.

• Các chức năng không được máy chủ cung cấp có thể cần mô hình chính xử lý bổ sung.

• Luồng Chrome không thể chạy độc lập nếu không có phiên chính thức tương thích do máy chủ cung cấp.

• Bản ghi xác thực trên máy trong quá khứ không có nghĩa là môi trường cài đặt mới đã vượt qua nghiệm thu.

• Nhật ký chạy, cấu hình trình duyệt, khóa, tài liệu nhiệm vụ cá nhân, trạng thái cài đặt trên máy và gói hoàn tác không được công khai.

Tóm tắt

Jev GUI Delegate tách các thao tác GUI có thể nghiệm thu khỏi vòng lặp từng bước của mô hình chính và để bộ điều khiển cục bộ thực hiện khớp xác định, lựa chọn ngữ nghĩa khi cần, xác minh trạng thái và khôi phục lỗi. Khi cài đặt, trước tiên cần hoàn tất việc cài đặt phụ thuộc đã khóa, thiết lập môi trường chạy và kiểm thử ngoại tuyến, sau đó cấu hình khóa và kết nối với Codex. Trong sử dụng thực tế, phạm vi nhiệm vụ rõ ràng, điều kiện thành công có thể quan sát, chiến lược khôi phục thao tác gửi thận trọng và việc xác thực lại sau khi thay đổi phiên bản là những yếu tố then chốt để đạt kết quả đáng tin cậy.

Để tìm hiểu thêm về các thành phần nguồn, hãy truy cập tài liệu TypeSafe, MCP Python SDK và pywinauto.