Cách sử dụng qz-browser-agent để nghiên cứu web ưu tiên cục bộ và tự động hóa trình duyệt

qz-browser-agent là gì?

qz-browser-agent, còn được gọi là 轻舟 hay “con thuyền nhẹ”, là một tiện ích Chrome ưu tiên xử lý cục bộ dành cho nghiên cứu web, tự động hóa trình duyệt và trích xuất dữ liệu có cấu trúc. Tiện ích cho phép bạn sử dụng nhà cung cấp mô hình của riêng mình, tương tác với các website thông qua bảng điều khiển bên của trình duyệt và mở rộng tác nhân bằng các Skill hoặc khả năng TypeScript có thể tái sử dụng.

Các phiên, Skill và dữ liệu đã thu thập được lưu trong trình duyệt của bạn. Yêu cầu mô hình có thể bao gồm lời nhắc của bạn cùng mọi nội dung trang hoặc tệp mà bạn thêm vào ngữ cảnh tác vụ. Skill và kết nối MCP có thể trao đổi dữ liệu với các dịch vụ do bạn cấu hình, vì vậy hãy xem tài liệu về quyền và luồng dữ liệu của dự án trước khi sử dụng các dịch vụ bên ngoài.

Tính năng chính

• Tự động hóa trình duyệt: tương tác với các phần tử DOM hoặc ảnh chụp màn hình, điền biểu mẫu và làm việc trên nhiều thẻ trong chế độ xem máy tính hoặc thiết bị di động.
• Tác vụ con song song: chạy các tác vụ đồng thời và ngắt, chuyển hướng hoặc thêm ngữ cảnh trong khi công việc đang diễn ra.
• Dữ liệu có cấu trúc: trích xuất bảng, phương tiện và nội dung trang vào các bộ sưu tập cục bộ, sau đó xem trước, chỉnh sửa và xuất kết quả từ bảng điều khiển bên.
• Skill: đóng gói hướng dẫn, tập lệnh, công cụ và giao diện tùy chỉnh của bảng điều khiển bên thành các quy trình có thể tái sử dụng, với tùy chọn tự động kích hoạt trên các website phù hợp.
• Lựa chọn mô hình: kết nối với các nhà cung cấp hỗ trợ giao thức API tương thích và gọi công cụ, bao gồm cả máy chủ mô hình cục bộ.
• Khả năng TypeScript: thêm công cụ cho tác nhân, chế độ xem bảng điều khiển, trang cài đặt hoặc nhà cung cấp mô hình.
• Cầu nối MCP: tùy chọn cung cấp các công cụ trình duyệt và quyền điều khiển tác vụ cho các tác nhân bên ngoài thông qua cầu nối MCP cục bộ.

Cài đặt tiện ích Chrome

Sử dụng bản phát hành mới nhất

1. Tải xuống bản phát hành qz-browser-agent mới nhất.
2. Giải nén tệp lưu trữ ZIP đã tải xuống.
3. Mở chrome://extensions trong Chrome.
4. Bật Chế độ nhà phát triển.
5. Nhấp vào Tải tiện ích đã giải nén và chọn thư mục qz-browser-agent-extension đã giải nén.

Xây dựng từ mã nguồn

Để xây dựng qz cục bộ, hãy cài đặt Node.js 24 LTS và npm, sau đó sao chép hoặc tải xuống kho lưu trữ. Từ thư mục dự án, cài đặt các phần phụ thuộc và tạo bản dựng tiện ích:

npm ci
npm run build

Khi quá trình xây dựng hoàn tất, quay lại chrome://extensions, chọn Tải tiện ích đã giải nén và chọn thư mục dist/extension/ được tạo ra.

Cấu hình nhà cung cấp mô hình

1. Mở bảng điều khiển bên qz từ thanh công cụ tiện ích.
2. Mở Cài đặt.
3. Chọn nhà cung cấp mô hình và nhập thông tin xác thực.
4. Nếu sử dụng điểm cuối tùy chỉnh, hãy cung cấp cả URL và giao thức được hỗ trợ.
5. Chọn một mô hình và lưu cấu hình.

qz được thiết kế để hoạt động với các nhà cung cấp cung cấp giao thức API được hỗ trợ và khả năng gọi công cụ. Tùy vào thiết lập, bạn có thể sử dụng nhà cung cấp lưu trữ tương thích hoặc máy chủ mô hình cục bộ.

Chạy tác vụ trình duyệt đầu tiên

Sau khi cấu hình nhà cung cấp, hãy bắt đầu bằng một yêu cầu nghiên cứu và trích xuất đơn giản:

Mở example.com và trích xuất tiêu đề chính vào một bảng.

Tác nhân có thể điều hướng đến trang được yêu cầu, kiểm tra nội dung và đưa kết quả đã trích xuất vào một bộ sưu tập cục bộ. Sử dụng bảng điều khiển bên để xem trước hoặc chỉnh sửa dữ liệu đã thu thập và xuất dữ liệu khi bộ sưu tập đã sẵn sàng.

Đối với các nghiên cứu phức tạp hơn, hãy yêu cầu qz làm việc trên nhiều trang hoặc thẻ. Khi một tác vụ gồm các phần việc độc lập, các tác vụ con song song có thể giúp xử lý chúng đồng thời. Bạn cũng có thể ngắt tác vụ đang chạy, chuyển hướng hoặc cung cấp thêm ngữ cảnh.

Mở rộng qz bằng Skill

Skill là các gói có thể tái sử dụng dành cho những quy trình lặp lại. Một Skill có thể kết hợp hướng dẫn, tự động hóa JavaScript, công cụ và các tiện ích tương tác tùy chỉnh trong bảng điều khiển bên. Site Skill cũng có thể được cấu hình để kích hoạt trên các website phù hợp.

Quản lý Skill từ giao diện qz hoặc cài đặt chúng từ các kho Git. Sử dụng Skill khi một quy trình cần hành vi nhất quán trong các tác vụ nghiên cứu lặp lại, chẳng hạn như thu thập thông tin từ một website cụ thể hoặc trình bày kết quả thông qua một thành phần bảng điều khiển tùy chỉnh.

Thêm khả năng TypeScript

Khả năng TypeScript cho phép các nhà phát triển đóng góp chức năng mới cho tiện ích. Chúng có thể cung cấp công cụ cho tác nhân, trình kết xuất kết quả công cụ, trang cài đặt, chế độ xem bảng điều khiển hoặc nhà cung cấp mô hình.

Để bắt đầu, hãy sao chép ví dụ về khả năng của dự án vào src/capabilities/, đổi tên các đăng ký và chỉ giữ lại những phần đóng góp mà tính năng của bạn cần. Một tệp đầu vào tối thiểu có thể xuất các công cụ và trình kết xuất như sau:

// src/capabilities/<your-feature>/index.ts
export { default as tools } from "./tools.js";
export { default as renderers } from "./renderers.js";

Bản dựng sẽ tự động phát hiện các khai báo này. Trình xử lý công cụ chạy trong service worker nền và có thể ủy quyền hành động hoặc thực thi tập lệnh cho các thẻ đang hoạt động. Trình kết xuất sẽ gắn các thẻ kết quả tương tác vào bảng điều khiển bên.

Để biết chi tiết về SDK và các hợp đồng mở rộng hiện tại, hãy tham khảo hướng dẫn về capability và tài liệu dành cho người đóng góp của dự án. Các API này đang ở giai đoạn thử nghiệm, vì vậy hãy tính đến khả năng chúng có thể thay đổi khi xây dựng extension.

Quy trình phát triển

Thiết lập môi trường kiểm thử của dự án bằng cách làm theo tài liệu về các lệnh và tùy chọn build. Các lệnh phát triển chính gồm:

npm run dev       # Build lại khi mã nguồn thay đổi
npm test          # Chạy các bộ kiểm thử mặc định
npm run verify    # Kiểm tra kiểu và chạy các bộ kiểm thử tự động kèm độ bao phủ

Sau khi build lại, hãy tải lại extension từ chrome://extensions và mở lại bảng điều khiển bên qz. Thao tác này đảm bảo Chrome đang chạy các tệp extension được tạo mới nhất.

Mẹo sử dụng nâng cao

• Sử dụng prompt có cấu trúc: mô tả các trang đích, trường cần thu thập và định dạng đầu ra mong muốn để dữ liệu trích xuất có thể được tổ chức thành một bộ sưu tập hữu ích.
• Chọn đúng chế độ tương tác: tương tác dựa trên DOM hữu ích cho các phần tử và biểu mẫu trên trang, trong khi tương tác dựa trên ảnh chụp màn hình có thể hỗ trợ khi ngữ cảnh trực quan quan trọng.
• Tách các quy trình có thể lặp lại: chuyển các hướng dẫn và tập lệnh thường dùng thành Skills thay vì lặp lại chúng trong mọi prompt.
• Sử dụng công việc song song một cách thận trọng: giao đồng thời các nhiệm vụ nghiên cứu độc lập, sau đó xem xét kết quả tổng hợp trong bảng điều khiển bên.
• Ưu tiên dịch vụ cục bộ khi phù hợp: qz hỗ trợ các máy chủ mô hình cục bộ, giúp lưu lượng mô hình nằm trong hạ tầng do bạn kiểm soát.
• Xem xét các kết nối dữ liệu: nội dung trang, tệp, Skills và các tích hợp MCP có thể được đưa vào yêu cầu hoặc trao đổi với các dịch vụ đã cấu hình. Hãy kiểm tra quyền trước khi xử lý thông tin nhạy cảm.
• Tải lại sau khi mã nguồn thay đổi: build thành công không tự động làm mới extension; hãy tải lại extension trong Chrome trước khi kiểm thử.

Tích hợp MCP tùy chọn

MCP bridge cục bộ tùy chọn cung cấp các công cụ trình duyệt và quyền điều khiển tác vụ cho các agent bên ngoài. Sử dụng bridge khi bạn cần một agent hoặc ứng dụng tương thích với MCP khác điều khiển qz. Vì các kết nối MCP có thể trao đổi dữ liệu với những dịch vụ đã cấu hình, hãy xem xét tài liệu về bridge và các tác động của luồng dữ liệu trước khi bật tính năng này.

Kết luận

qz-browser-agent kết hợp bảng điều khiển bên Chrome, tự động hóa trình duyệt dựa trên mô hình, các bộ sưu tập cục bộ có cấu trúc, nhiệm vụ song song và khả năng mở rộng thông qua Skills và TypeScript. Hãy cài đặt bản phát hành để bắt đầu nhanh, cấu hình một nhà cung cấp mô hình tương thích và thử một prompt trích xuất tập trung. Nếu cần các quy trình hoặc tích hợp tùy chỉnh, hãy build từ mã nguồn và mở rộng dự án bằng Skills, capabilities hoặc MCP bridge tùy chọn.