Kiến trúc OpenCLI: chuyển đổi web và Electron thành CLI

Tóm tắt nhanh:

• OpenCLI cung cấp giao diện tự động hóa dòng lệnh kết nối các phiên duyệt web trên Chrome và ứng dụng desktop Electron với terminal của lập trình viên và AI agent.
• Bằng cách ghép nối tiến trình daemon cục bộ trên cổng TCP 19825 với tiện ích Chrome Browser Bridge, công cụ điều khiển các lệnh Chrome DevTools Protocol bên trong cửa sổ tự động hóa riêng biệt, tận dụng phiên đăng nhập sẵn có trên máy trạm mà không cần trích xuất phiên lên đám mây.
• Đối với nhu cầu điều phối từ xa, kỹ thuật SSH reverse tunnel cho phép môi trường sandbox điều khiển trình duyệt tại máy trạm cục bộ qua giao diện loopback nội bộ.

Các AI agent hỗ trợ lập trình thường xuyên cần tương tác với các dịch vụ web chưa cung cấp API công khai hoặc yêu cầu xác thực đa yếu tố phức tạp. Những công cụ tự động hóa headless truyền thống như Puppeteer hay Selenium tiêu chuẩn thường khởi tạo profile trình duyệt hoàn toàn mới. Phương pháp này buộc kỹ sư phải duy trì kịch bản đăng nhập tự động dễ gãy hoặc lưu trữ secret dài hạn trong biến môi trường shell.

Mặt khác, nếu chia sẻ phiên làm việc cho agent xử lý, việc kiểm soát dữ liệu xác thực cần được tính toán kỹ lưỡng. Tiện ích Browser Bridge của OpenCLI giải quyết ranh giới này bằng cách giữ kênh điều khiển nối với daemon trên localhost. Cookie theo phạm vi domain có thể được trả về cho CLI khi có yêu cầu cụ thể, giúp thực hiện tác vụ tải tài nguyên mà không chuyển hướng toàn bộ profile người dùng ra dịch vụ đám mây bên thứ ba.

Mã nguồn dự án được phân phối theo giấy phép Apache-2.0 được quy định tại LICENSE L1-L30.

Cơ chế vận hành daemon loopback và giao thức Browser Bridge

Thành phần trọng tâm trong kiến trúc OpenCLI là một tiến trình daemon viết bằng Node.js, đóng vai trò điều phối giữa các câu lệnh trong terminal và tiện ích mở rộng Chrome.

Căn cứ vào mã nguồn tại src/constants.ts L1-L25, kênh giao tiếp này được gắn cố định vào một cổng xác định:

• DEFAULT_DAEMON_PORT = 19825: Daemon chỉ lắng nghe duy nhất trên địa chỉ loopback 127.0.0.1:19825.
• Vô hiệu hóa cấu hình cổng tùy biến: Dự án chủ động từ chối biến môi trường OPENCLI_DAEMON_PORT khác mặc định để ngăn ngừa tình trạng mất đồng bộ giữa tiện ích Chrome và các tiến trình CLI trên hệ điều hành.

[Terminal / AI Agent]
         │
         │ (HTTP / Các lệnh CLI con)
         ▼
[OpenCLI Daemon] ──(ws://localhost:19825/ext)
(Cổng 19825)                   │
                               │
                               ▼
                   [Chrome Extension Bridge]
                               │  
                               │  (Chrome DevTools Protocol)
                               ▼
                   [Cửa sổ trình duyệt độc lập]
                   (Tận dụng phiên đăng nhập sẵn)

Định nghĩa giao thức trong extension/src/protocol.ts L1-L30 bao gồm 15 loại hành động cụ thể:

• Điều hướng và quan sát: navigate, tabs, frames, screenshot, và close-window.
• Thực thi động: exec chạy mã JavaScript trực tiếp trong ngữ cảnh trang web.
• Tương tác nhập liệu: click, fill, hover, press, scroll, và upload.
• Quản lý phiên: eval, session-close, và ping.

Khi theo dõi mạng, tiện ích ghi nhận các sự kiện request và response trên tab đang kết nối thông qua phương thức Network.getResponseBody của CDP, như triển khai tại extension/src/cdp.ts L890-L930. Cơ chế ping định kỳ và exponential backoff (2 đến 5 giây) hỗ trợ tiện ích tự động kết nối lại khi daemon khởi động xong.

Đường ống trích xuất nội dung và hệ sinh thái adapter

Khi trích xuất nội dung web để làm đầu vào cho LLM, việc loại bỏ mã rác và thẻ định dạng cồng kềnh giúp giảm đáng kể lượng HTML không cần thiết gửi vào context window.

Quy trình xử lý nội dung trong lệnh browser extract được triển khai tại src/browser/extract.ts L33-L73. Quy trình tạo bản sao clone của DOM, loại bỏ các thẻ script, style, phần tử ẩn cùng thuộc tính dư thừa, sau đó sử dụng thư viện Turndown để chuyển đổi HTML sang Markdown phân đoạn theo khối văn bản. Đối với bài viết dài, OpenCLI tích hợp Readability để bóc tách phần thân chính, đồng thời hỗ trợ plugin GFM cho các bảng biểu dữ liệu.

Ngoài ra, OpenCLI mở rộng năng lực tự động hóa sang các ứng dụng desktop xây dựng trên nền tảng Electron như Slack, Discord hay VS Code. Nhờ cờ gỡ lỗi CDP từ xa, daemon có thể gắn trực tiếp vào các cửa sổ Electron và gửi lệnh thao tác tương tự như đối với tab trình duyệt.

Ranh giới bảo mật và kỹ thuật điều phối từ xa qua SSH Reverse Tunnel

Để đảm bảo tính minh bạch, tiện ích Chrome Browser Bridge khai báo chính xác các quyền hạn vận hành tại extension/manifest.json L6-L18. Manifest yêu cầu 8 quyền hệ thống (debugger, tabs, cookies, activeTab, alarms, storage, tabGroups, downloads) cùng quyền truy cập host <all_urls> để phục vụ CDP, quản lý tab và trích xuất cookie khi cần. Kênh điều khiển của extension chỉ kết nối với daemon trên localhost, không gửi telemetry đến bất kỳ dịch vụ phân tích bên ngoài nào.

Khi gọi các HTTP endpoint trên daemon, hệ thống yêu cầu header bảo vệ để phân biệt lệnh nội bộ. Căn cứ src/daemon.ts L271-L294, ngoại trừ /ping được miễn kiểm tra, các endpoint còn lại bắt buộc phải có header X-OpenCLI:

# Kiểm tra trạng thái daemon cục bộ với header định danh bắt buộc
curl -fsS -H 'X-OpenCLI: 1' http://127.0.0.1:19825/status

Khi vận hành trên máy chủ CI/CD hoặc container không có giao diện đồ họa, lập trình viên có thể kết nối với trình duyệt máy trạm thông qua SSH reverse tunnel theo hướng dẫn tại docs/guide/remote-orchestration.md L36-L44:

# Chuyển tiếp cổng daemon từ máy trạm lên máy chủ agent từ xa
ssh -N -o ExitOnForwardFailure=yes -R 127.0.0.1:19825:127.0.0.1:19825 user@remote-agent-server

Lưu ý rằng hành vi mở cổng trên máy chủ đích phụ thuộc vào chỉ thị GatewayPorts trong tệp cấu hình sshd_config. Khi thiết lập ở giá trị mặc định no, cổng 19825 trên máy chủ chỉ lắng nghe trên giao diện loopback cục bộ, giúp giới hạn quyền điều khiển trình duyệt trong phạm vi các tiến trình được cấp quyền trên máy chủ đó.

Cài đặt thực tế và kịch bản tự động hoá dòng lệnh

Để sử dụng OpenCLI, lập trình viên cần cài đặt gói CLI trên Node.js 18+ và cài đặt tiện ích mở rộng Chrome Browser Bridge từ Chrome Web Store. Sau khi kích hoạt tiện ích và mở sẵn trình duyệt Chrome, chạy lệnh kiểm tra môi trường:

# Kiểm tra trạng thái kết nối daemon và tiện ích trình duyệt
opencli doctor

Căn cứ vào cú pháp đăng ký lệnh tại src/cli.ts L840-L849, mọi thao tác trình duyệt yêu cầu tham số định danh phiên làm việc. Kịch bản dưới đây minh họa luồng mở tab, bóc tách dữ liệu và chụp ảnh màn hình:

# Khởi tạo định danh phiên làm việc
SESSION="audit-session"

# Mở trang đích trên cửa sổ tự động hoá
opencli browser "$SESSION" open "https://github.com/jackwener/opencli"

# Liệt kê các tab đang hoạt động trong phiên
opencli browser "$SESSION" tab list

# Trích xuất nội dung bài viết dưới dạng Markdown
opencli browser "$SESSION" extract --selector "article"

# Chụp ảnh toàn bộ trang màn hình theo cờ --full-page
opencli browser "$SESSION" screenshot ./repo-view.png --full-page

# Đóng phiên làm việc và giải phóng tài nguyên
opencli browser "$SESSION" close

Theo quy định tại src/cli.ts L1175-L1180, cờ --full-page cho phép chụp toàn bộ chiều dài trang thay vì chỉ vùng hiển thị khung nhìn hiện thời.

OpenCLI cung cấp giải pháp thực tế cho bài toán tự động hóa: thay vì duy trì các cụm headless browser phức tạp, việc tận dụng phiên Chrome sẵn có qua kênh điều khiển bảo mật giúp lập trình viên và AI agent dễ dàng khai thác các dịch vụ web nội bộ.