Triết lý của Orbz

Orbz bắt đầu từ một ý tưởng nhỏ có chủ đích: không nên phải dựng lại diện mạo trực quan của trợ lý mỗi khi ứng dụng đổi framework.

Trình duyệt đã có mô hình thành phần dùng chung và Orbz sử dụng nó. <orb-z> cung cấp cùng trạng thái, điều khiển giao diện và chuyển động trong HTML thuần, Vue, Svelte, Angular, React, Next.js hoặc trang kết hợp nhiều microfrontend.

Một hợp đồng, nhiều môi trường chủ

Tích hợp theo framework thường lệch nhau: lớp bọc React có tính năng Vue chưa có, Angular chọn mặc định khác, bản JavaScript thuần bị bỏ quên. Orbz giữ một triển khai gốc và cho framework liên kết vào thuộc tính công khai.

Nhờ đó mọi môi trường chủ có cùng bộ khái niệm:

năm trạng thái: idle, listening, thinking, speaking, asleep
một thuộc tính preset hoặc năm thuộc tính màu tùy chỉnh
size, speed, paused, elevated và reduced-motion
phương thức play(), pause() và restart()

Sáu sandbox chủ ý có cùng giao diện. Mã framework khác nhau, còn hợp đồng thành phần và trải nghiệm người dùng thì giống nhau.

Thành phần trực quan cơ bản với giao diện giọng nói tùy chọn

Orbz quản lý biểu đạt trực quan và cung cấp luồng hội thoại tùy chọn với adapter trình duyệt và tương thích OpenAI. Ứng dụng quản lý quyết định và ranh giới bảo mật tạo ý nghĩa cho biểu đạt đó:

lúc bắt đầu, dừng giọng nói và cách người dùng chủ động đồng ý
quyền micrô, thu âm và nhận dạng giọng nói
chọn bộ máy giọng nói, endpoint được bảo vệ và thông tin xác thực
yêu cầu mô hình, gọi công cụ và truyền luồng
luân phiên lượt, hủy, lỗi và thử lại
bản chép lời, nút, nhãn và UI có ngữ nghĩa khác

Ranh giới này giúp gói phù hợp với mọi nhà cung cấp giọng nói, AI SDK, bộ quản lý trạng thái hoặc backend. Ứng dụng ánh xạ sự kiện miền sang một trong năm trạng thái và chủ động chạy runtime hội thoại khi cần; Orbz hiển thị tương ứng.

Xem ánh xạ trạng thái thực tế trong Xây dựng trợ lý giọng nói.

Chặt chẽ ngay từ thiết kế

Giao diện được hỗ trợ chủ ý dựa trên thuộc tính. Orbz không công khai phần Shadow DOM, biến CSS hoặc adapter thành phần riêng cho framework.

Tính chặt chẽ phục vụ ba mục đích:

Tính di động. Cùng cấu hình có cùng ý nghĩa trong mọi môi trường chủ.
Tính ổn định. Lớp và hoạt ảnh nội bộ phát triển mà không vô tình thành API công khai.
Tính nhất quán. Nhóm sản phẩm tùy chỉnh token dự kiến thay vì thay thế thành phần qua từng selector.

Để có bản sắc trực quan riêng, chọn preset hoặc cung cấp năm màu được ghi trong tài liệu. Ngữ nghĩa hay tương tác khác thuộc về ứng dụng xung quanh quả cầu.

Cách ly là cam kết của triển khai

Mỗi thể hiện của thành phần tạo một Shadow DOM đóng. Mã đánh dấu, kiểu và lớp hoạt ảnh là riêng tư. CSS của trang không thể sửa chúng và Orbz không làm lộ selector nội bộ ra trang.

Đóng không có nghĩa là không tiếp cận được. Orbz mang tính trang trí nên hình ảnh nội bộ được ẩn khỏi công nghệ hỗ trợ. Ứng dụng chủ cung cấp nhãn trợ năng hoặc tốt hơn là văn bản trạng thái trực tiếp gần đó mô tả trợ lý.

An toàn trên máy chủ, nguyên bản trên trình duyệt

Có thể import gói khi kết xuất máy chủ mà không đánh giá lớp con HTMLElement ở phạm vi mô-đun. Đăng ký có bảo vệ và lũy đẳng: không làm gì trên máy chủ, chỉ định nghĩa orb-z trong trình duyệt nếu chưa đăng ký.

Cách này tương thích với khung trang kết xuất máy chủ và giữ runtime gốc của trình duyệt. Máy chủ xuất phần tử, máy khách nâng cấp sau khi đăng ký. Điểm vào react-types tùy chọn thêm kiểu JSX mà không tạo lớp bọc React hay adapter runtime.

Xem cách làm được khuyến nghị tại SSR và hydration.

Kho mã tuân theo ranh giới công khai

Gói Orbz, trang tài liệu này và Orbz Sandbox là các dự án độc lập. Ứng dụng Sandbox dùng @neongate-ai/orbz@0.3.1 từ npm; tài liệu và Sandbox đều không import workspace gói bên cạnh hoặc đường dẫn nguồn riêng tư.

Mỗi sandbox có thể triển khai thành dự án Vercel độc lập. Khung microfrontend dùng cùng gói. Ranh giới bền vững là gói đã phát hành và hợp đồng <orb-z>, không phải cấu trúc kho mã dùng chung.

Tiêu chí cho tính năng mới

Trước khi mở rộng giao diện công khai, hãy hỏi:

Đây có phải nhu cầu trực quan chung của mọi framework?
Có thể biểu đạt bằng thuộc tính nhỏ, tuần tự hóa được hoặc có kiểu?
Hành vi có thể xác định nhất quán trong HTML gốc và adapter?
Có giữ ranh giới đóng, chặt chẽ của thành phần?
Ứng dụng vẫn có thể truyền đạt ý nghĩa dễ tiếp cận bên ngoài quả cầu?

Nếu không, tính năng có lẽ thuộc ứng dụng chủ. Hợp đồng nhỏ không phải hạn chế; nó giúp một thành phần vẫn là chính nó ở mọi nơi.