Chuyển đến nội dung
OrbZLịch sử thay đổi

Lịch sử thay đổi

Trang này ghi lại các thay đổi dành cho người dùng của gói công khai @neongate-ai/orbz, hợp đồng phần tử tùy chỉnh <orb-z> và các cách tích hợp được hỗ trợ.

Kho GitHub  là nguồn chuẩn của phần triển khai. Các bản phát hành có trên npm , còn tài liệu đầy đủ có tại orbz.site .

1.0.2 — 2026-09-08

Sửa bộ thiết lập Neongate

  • Khôi phục neongate làm tên chuẩn của bộ thiết lập mặc định, gồm DEFAULT_ORBZ_PRESET, ORBZ_PRESET_NAMES và getter trả về preset đã chuẩn hóa của phần tử. Màu Neongate không đổi.
  • Giữ tên vô tình lấy từ tài khoản trong 1.0.1 làm bí danh đầu vào đã lỗi thời. Thuộc tính HTML, phép gán thuộc tính, đầu vào có kiểu và hàm kiểm tra hiện có vẫn chấp nhận tên đó; chuẩn hóa và phản chiếu thuộc tính dùng neongate.
  • Giữ khóa bảng màu đã lỗi thời làm bí danh bất biến, không liệt kê được của ORBZ_PRESETS.neongate. Danh sách chuẩn vẫn có sáu bộ thiết lập.
  • Chuẩn hóa đối tượng cấu hình rút gọn và đầy đủ kiểu cũ mà không sửa đầu vào của bên gọi, đồng thời giữ màu được cung cấp và kiểm tra nghiêm ngặt.

Nâng cấp từ 1.0.1

Cài bản vá đã phát hành và cập nhật URL CDN đã ghim phiên bản:

npm install @neongate-ai/orbz@1.0.2

Dùng neongate cho các giá trị preset được chỉ định mới. Đầu vào dùng khóa cũ lấy từ tài khoản vẫn tương thích; có thể chuyển đổi khi thuận tiện. Mã đọc tên preset đã chuẩn hóa cần nhận neongate. Xem Cách đặt tên preset Neongate để biết ví dụ mặc định và cách truy cập bảng màu.

Bản sửa này thay thế hướng dẫn đặt tên của 1.0.1, được giữ bên dưới làm lịch sử phát hành. Phạm vi npm vẫn là @neongate-ai/orbz; kho mã đang được duy trì hiện thuộc jonatassales.

Xem 1.0.2 trên npm · Xem mã nguồn thẻ v1.0.2 · So sánh mã nguồn các thẻ 

1.0.1 — 2026-09-08

Dọn dẹp và cấu hình rút gọn

  • Sửa orb cleanup (bí danh orb clean) trong bản sao mã nguồn Orbz để mặc định xóa các thư mục node_modules không được theo dõi ở gốc và cấp con cùng đầu ra được tạo. --dry-run xem trước mục tiêu; --keep-dependencies giữ phần phụ thuộc. Nội dung được theo dõi, mã/tài nguyên, siêu dữ liệu harness và kho lồng nhau được giữ nguyên; quá trình dọn dẹp không đi theo liên kết tượng trưng của thư mục.
  • Đơn giản hóa JSON cấu hình do người dùng viết. Bộ chuyển đổi điền các nhóm nội bộ về giao diện, chuyển động và giọng nói bị bỏ qua bằng giá trị mặc định có kiểu, rồi kiểm tra, sao chép và đóng băng cấu hình lúc chạy. Vẫn hỗ trợ ghi đè tường minh các nhóm này.
  • Cập nhật liên kết chủ sở hữu GitHub sang tài khoản cá nhân tại thời điểm đó, đồng thời cập nhật README, hướng dẫn CLI và kiểm tra kỹ thuật. Gói npm vẫn là @neongate-ai/orbz.

Nâng cấp từ 1.0.0

Cài bản vá và cập nhật URL CDN đã ghim:

npm install @neongate-ai/orbz@1.0.1

Bản này tạm đổi tên preset mặc định thành tên tài khoản cá nhân nhưng giữ màu neongate cũ. Phiên bản 1.0.2 khôi phục tên chuẩn neongate; dùng <orb-z preset="neongate"></orb-z> cho tích hợp mới. Nếu duy trì bản sao mã nguồn Orbz, dùng orb cleanup --keep-dependencies để giữ node_modules; riêng orb cleanup giờ sẽ xóa thư mục đó. Các chi tiết chuyển đổi này vẫn áp dụng dù đây là bản vá.

Xem 1.0.1 trên npm · So sánh mã nguồn các thẻ 

1.0.0 — 2026-09-06

Mô hình giọng nói và hội thoại Realtime

  • Thêm thuộc tính JavaScript có kiểu voiceModel cho web-speech, openai-speech và openai-realtime. Chọn nhà cung cấp vẫn không phát âm thanh; ứng dụng chủ động bắt đầu giọng nói hoặc hội thoại sau thao tác của người dùng.
  • Thêm OpenAIRealtimeAdapter và âm thanh WebRTC trực tiếp từ trình duyệt đến nhà cung cấp. Ứng dụng cấp phép thiết lập phiên qua realtimeSession, dùng endpoint riêng hoặc callback bất đồng bộ trả về SDP answer.
  • Thêm startConversation(), stopConversation(), interruptConversation(), conversationState chỉ đọc, cùng sự kiện orbz-conversation-state-change và orbz-transcript để ứng dụng sở hữu các điều khiển và giao diện bản chép lời.
  • Khóa nhà cung cấp nằm ở backend của ứng dụng. Cài đặt mô hình chỉ chứa cấu hình công khai; đối tượng endpoint từ chối trường lạ như apiKey, token và headers. Không đặt bí mật hoặc token phiên trong thuộc tính HTML, thuộc tính thành phần hay JSON cấu hình.

Cấu hình chuẩn và CLI

  • Người duy trì bản fork chỉnh sửa src/orbz.config.json cho mặc định về thành phần, giao diện, chuyển động, giọng nói và Realtime, rồi xây dựng lại gói. Gói đã cài dùng mặc định đi kèm, không tải cấu hình lúc chạy.
  • Thêm orbzConfiguration chỉ đọc và hàm thuần transformOrbzConfiguration() để kiểm tra, sao chép, chuyển đổi và đóng băng đối tượng cấu hình đầy đủ mà không thay đổi singleton của gói.
  • Hợp nhất xử lý lệnh và trợ giúp của Orb CLI. Các export công khai, thuộc tính hình ảnh, đăng ký gốc và tích hợp voiceEngine tường minh hiện có vẫn khả dụng.

Nâng cấp từ 0.4.3

Cài bản phát hành và cập nhật mọi URL CDN đã ghim:

npm install @neongate-ai/orbz@1.0.0

Các ví dụ trực quan hiện có giữ nguyên thẻ <orb-z> và điểm vào trình duyệt. Tùy chọn cấu trúc mới dùng thuộc tính JavaScript; không có thuộc tính HTML voice-model. Realtime cần ứng dụng cấp phép phiên và thao tác kích hoạt tường minh; nâng cấp gói không bắt đầu âm thanh hay yêu cầu micrô. voiceEngine được gán tường minh ưu tiên hơn voiceModel.

Xem 1.0.0 trên npm

0.4.3 — 2026-09-04

Điểm nổi bật từ 0.3.1

  • Thêm CLI POSIX shell orb đã phát hành làm chương trình thực thi của gói. Chạy tạm bằng npx -y --package=@neongate-ai/orbz@latest orb.
  • Thiết lập dự án Orb nhận diện npm, pnpm, Yarn hoặc Bun từ siêu dữ liệu và lockfile, cài phiên bản Orbz đang chạy, không tạo hay ghi đè mã nguồn ứng dụng.
  • WebSpeechAdapter mặc định dùng tiếng Bồ Đào Nha Brazil (pt-BR). Ứng dụng có thể ghi đè language, gồm en-US, khi cần ngôn ngữ khác.
  • Orbz không còn lời chào soạn sẵn, nhân vật hay luồng hội thoại mặc định. Bên dùng cung cấp speech hoặc talkFlow, cấu hình voiceEngine và gọi startTalking() tường minh.

Xem 0.4.3 trên npm

0.3.1 — 2026-08-25

Chủ động bật giọng nói

  • Kết nối hoặc nâng cấp <orb-z> không còn tạo bộ máy giọng nói mặc định hay bắt đầu hội thoại.
  • voiceEngine mặc định là undefined. Ứng dụng cung cấp bộ máy và gọi startTalking() sau khi khách truy cập chọn bật.
  • Gán bộ máy giọng nói vẫn im lặng; stopTalking() dừng luồng đang chạy, còn gán undefined xóa bộ máy đã cấu hình.
  • Chuỗi số qua HTML hoặc mã đánh dấu kết xuất phía máy chủ được chuẩn hóa thành độ dài pixel nhất quán với giá trị thuộc tính dạng số.

Xem 0.3.1 trên npm

0.3.0 — 2026-08-23

Kiểu dữ liệu cho React và Next.js

  • Thêm điểm vào tùy chọn @neongate-ai/orbz/react-types cho dự án TypeScript dùng React và Next.js.
  • Điểm vào mở rộng JSX để định kiểu <orb-z> mà không cần thành phần bọc theo framework.
  • React vẫn không thuộc phụ thuộc lúc chạy của Orbz; kiểu React chỉ dùng để xây dựng điểm vào khai báo tùy chọn.

0.2.0 — 2026-08-22

Orbz 0.2.0 mở rộng thành phần trợ lý trực quan ban đầu thành phần tử tùy chỉnh có giọng nói, độc lập với framework. Bản này giới thiệu runtime hội thoại, cổng giọng nói và trí tuệ có thể thay thế, điều khiển giao diện nghiêm ngặt hơn, đóng gói chặt hơn và một mô hình tích hợp gốc chung cho mọi framework được hỗ trợ.

Bản trước 1.0 có thay đổi không tương thích: ứng dụng dùng colors của 0.1.0, biến CSS công khai, Shadow Parts, Shadow DOM mở hoặc @neongate-ai/orbz/react phải chuyển đổi.

Runtime giọng nói và hội thoại

  • Thêm luồng hội thoại tự động, xác định, bắt đầu sau lần kết xuất đầu tiên khi phần tử đã kết nối.
  • Thêm các bước welcoming, askName, help, answer qua đối tượng công khai talk và DEFAULT_TALK_FLOW.
  • Thêm bộ nhớ hội thoại chỉ tồn tại lúc chạy. Luồng mặc định ghi nhận tên khách qua talkContext, không ghi cookie, bộ nhớ cục bộ, IndexedDB hay backend.
  • Thêm startTalking() để đặt lại ngữ cảnh lúc chạy và khởi động lại luồng đã cấu hình.
  • Thêm receive(input) để ứng dụng tiếp tục bước hỏi hoặc đáp bằng văn bản từ giao diện của mình.
  • Thêm stopTalking() để dừng luồng và đầu ra giọng nói.
  • Thêm thuộc tính có thể cấu hình voiceEngine, talkFlow, intelligence.
  • Thêm hợp đồng TypeScript công khai OrbzTalkStep, OrbzTalkContext, OrbzVoiceOptions.
  • Thêm OrbzVoiceEnginePort để thay đầu ra giọng nói mà không đổi thành phần.
  • Thêm OrbzIntelligencePort để kết nối tác nhân hoặc nhà cung cấp trả lời, giữ logic sản phẩm và thông tin xác thực ngoài Orbz.
  • Thêm phản hồi dự phòng cục bộ khi chưa có nhà cung cấp trí tuệ hoặc khi nhà cung cấp lỗi.
  • Thêm sự kiện orbz-speaking-change với chi tiết { speaking: boolean }.
  • Thêm sự kiện orbz-talk-error chứa lỗi gốc trong { error: unknown }.
  • Tạm chuyển Orbz sang trạng thái trực quan speaking khi phát âm thanh và khôi phục trạng thái trước đó khi xong.
  • Ứng dụng chủ vẫn sở hữu thu micrô, nhận dạng giọng nói, quyền, bản chép lời và nhập văn bản. Orbz chỉ nhận văn bản qua receive().

Giọng nói trình duyệt

  • Thêm WebSpeechAdapter làm bộ máy mặc định không cần cấu hình.
  • Đổi ngôn ngữ giọng nói mặc định thành en-US.
  • Chờ danh sách giọng đọc tải bất đồng bộ trước khi chọn giọng.
  • Thêm bộ lọc tiếng Anh tường minh thay vì chấp nhận giọng mặc định không liên quan của hệ điều hành.
  • Thêm lựa chọn giọng ưu tiên đã cấu hình và giọng Google, Microsoft, tự nhiên, neural, premium, enhanced hoặc trực tuyến chất lượng cao khi trình duyệt cung cấp.
  • Cho phép cấu hình ngôn ngữ, giọng ưu tiên, tốc độ, cao độ, âm lượng và thời gian chờ tải giọng.
  • Phát hiện giọng nói không khởi động được, tránh để luồng chờ vô hạn.
  • Nếu trình duyệt chặn âm thanh tự động bằng NotAllowedError, giọng nói ở lần kết xuất đầu sẽ thử lại sau thao tác con trỏ, bàn phím hoặc chạm đầu tiên.
  • Bỏ hành vi ví dụ phải gắn lại phần tử qua Đặt lại tất cả trước khi bắt đầu giọng nói.
  • Làm rõ rằng giọng đọc vẫn do trình duyệt và hệ điều hành của khách cung cấp. Cải thiện lựa chọn không biến giọng hệ thống thành giọng do OpenAI tạo.

Giọng nói OpenAI

  • Thêm OpenAISpeechAdapter để chuyển văn bản thành giọng nói OpenAI qua proxy của ứng dụng.
  • Mặc định dùng gpt-4o-mini-tts, giọng marin, đầu ra MP3 và chỉ dẫn đọc tiếng Anh Mỹ tự nhiên.
  • Cho phép cấu hình mô hình, giọng, định dạng phản hồi, chỉ dẫn, thông tin xác thực, header và triển khai fetch.
  • Tương thích với tts-1 và tts-1-hd cũ, gồm giọng mặc định tương thích và bỏ chỉ dẫn không hỗ trợ.
  • Giữ khóa OpenAI API ngoài trình duyệt và gói Orbz. Bộ chuyển tiếp gọi endpoint do bên triển khai sở hữu để nhận âm thanh được tạo.
  • Hủy yêu cầu giọng nói đang chờ khi dừng hoặc thay đầu ra.
  • Dọn URL đối tượng âm thanh sau phát, hủy hoặc lỗi.
  • Xử lý lỗi kích hoạt trình duyệt để âm thanh được tạo tham gia cùng chu kỳ thử lại ở lần tương tác đầu như giọng nói trình duyệt.

Giao diện và API thành phần

  • Thay thuộc tính mở colors bằng hai chế độ giao diện nghiêm ngặt, loại trừ nhau:

    • thuộc tính HTML hoặc JavaScript preset;
    • năm thuộc tính color-primary, color-secondary, color-accent, color-highlight, color-background.

  • Thêm sáu preset: neongate, periwinkle, magenta, peach, mocha, ivory.

  • Preset và màu tùy chỉnh loại trừ nhau. Khi có cả hai, Orbz báo xung đột, áp dụng preset và bỏ qua màu riêng đến khi gỡ thuộc tính preset.

  • Thêm thuộc tính boolean elevated cho bóng đổ căn giữa tùy chọn.

  • Giữ năm trạng thái công khai idle, listening, thinking, speaking, asleep.

  • Giữ hệ số tốc độ dương, chuẩn hóa kích thước, tạm dừng/phát, khởi động lại chuyển động và chính sách giảm chuyển động system, always, never.

  • Giữ hằng số, hàm kiểm tra và chuẩn hóa công khai cho trạng thái, preset, giảm chuyển động, kích thước, tốc độ và màu.

  • Đổi Shadow DOM từ mở sang đóng.

  • Bỏ Shadow Parts công khai và định kiểu bên ngoài qua ::part(...).

  • Bỏ tùy chỉnh bằng biến CSS công khai --orbz-*. Bộ chọn và biến nội bộ trở thành chi tiết triển khai riêng.

  • Chuyển kiểu nguồn thành phần đến src/element/index.css, giữ trong shadow root đóng và xuất cùng nội dung thành dist/index.css.

Tích hợp framework và điểm vào gói

  • Bỏ thành phần React riêng và điểm vào @neongate-ai/orbz/react.
  • Bỏ React khỏi peer dependency và phụ thuộc phát triển của gói runtime Orbz.
  • Thống nhất mọi tích hợp trên phần tử nguyên bản <orb-z>.
  • Cập nhật React và Next.js để đăng ký điểm vào trình duyệt và kết xuất <orb-z> trực tiếp.
  • Thêm khai báo JSX intrinsic-element cục bộ trong ví dụ React và Next.js cho TypeScript mà không thêm thành phần bọc.
  • Giữ @neongate-ai/orbz làm điểm vào không tác dụng phụ cho kiểu, hằng số, bộ chuyển tiếp, cổng, factory và hàm đăng ký tường minh.
  • Giữ @neongate-ai/orbz/browser làm điểm vào đăng ký <orb-z>.
  • Giữ @neongate-ai/orbz/standalone làm bundle trình duyệt độc lập tự đăng ký cho CDN và script trực tiếp.
  • Giữ bảo vệ tạo lớp và đăng ký phần tử trong môi trường kết xuất phía máy chủ.
  • Giữ defineOrbz() lũy đẳng khi nhiều bundle hoặc microfrontend cùng đăng ký.
  • Đổi tên hàm tạo lớp nâng cao thành orbzElementClassFactory().
  • Chuyển tác dụng phụ đăng ký trình duyệt vào điểm vào tường minh thay vì thực thi ở gốc gói.

Xây dựng, đóng gói và tổ chức nội bộ

  • Thêm vòng đời prepack kiểm tra TypeScript nghiêm ngặt và xây dựng mới trước npm pack hoặc npm publish.
  • Giới hạn gói npm ở đầu ra dist và các tệp npm tự đưa vào như package.json, README.md, LICENSE.
  • Giữ tài liệu, ví dụ, chỉ dẫn tác nhân nội bộ, mã nguồn và cấu hình workspace ngoài tarball npm.
  • Thêm đuôi .ts tường minh cho import cấu hình tsdown dùng chung để hỗ trợ tải cấu hình TypeScript gốc của Node.
  • Tổ chức lại mô-đun nội bộ quanh core, element, factories, ports, services, talk.
  • Đổi vùng nguồn voice cũ thành talk.
  • Hợp nhất khai báo kiểu liên quan vào mô-đun .types.ts.
  • Bỏ tiền tố orbz thừa trong tên tệp nội bộ, giữ tên ký hiệu công khai Orbz*.
  • Làm phẳng thư mục một tệp không cần thiết.
  • Bỏ hoàn toàn triển khai runtime React khỏi mã nguồn gói.

Ví dụ và tài liệu

  • Thêm ví dụ đồng bộ Vanilla, React, Vue, Svelte, Angular và Next.js trên cùng giao diện <orb-z>.
  • Cập nhật điều khiển đặt lại để khôi phục trạng thái mà không gắn lại phần tử.
  • Thay khung VitePress ban đầu bằng trang tài liệu Nextra.
  • Thêm tài liệu bắt đầu cho tích hợp gốc, framework và CDN.
  • Thêm khái niệm về triết lý, trạng thái, giao diện, chuyển động và khả năng tiếp cận.
  • Thêm hướng dẫn framework, microfrontend, SSR và trợ lý giọng nói.
  • Thêm tham chiếu API đầy đủ cho phần tử và export gói.
  • Thêm ví dụ, xử lý sự cố và hướng dẫn chuyển đổi.
  • Chọn orbz.site  làm địa chỉ tài liệu chính.
  • Chọn miền con theo framework làm địa chỉ triển khai các ví dụ đồng bộ.

Xem 0.2.0 trên npm

Chuyển đổi từ 0.1.0

Thay bộ chuyển tiếp React

Xóa import từ điểm vào React cũ:

import { Orbz } from "@neongate-ai/orbz/react";
 
export function Assistant() {
  return <Orbz state="idle" />;
}

Đăng ký điểm vào trình duyệt và kết xuất phần tử tùy chỉnh gốc:

import "@neongate-ai/orbz/browser";
 
export function Assistant() {
  return <orb-z state="idle"></orb-z>;
}

Thêm khai báo JSX intrinsic-element cục bộ khi TypeScript chưa nhận ra orb-z. Khai báo chỉ cung cấp thông tin kiểu lúc biên dịch; không tạo thành phần React.

Thay API màu

Xóa đối tượng colors cũ:

orb.colors = {
  primary: "#7C3AED",
  secondary: "#22D3EE"
};

Dùng preset tích hợp:

<orb-z preset="neongate"></orb-z>

Hoặc dùng năm thuộc tính màu tùy chỉnh được hỗ trợ mà không có preset:

<orb-z
  color-primary="#7C3AED"
  color-secondary="#22D3EE"
  color-accent="#F472B6"
  color-highlight="#FDE68A"
  color-background="#09090B"
></orb-z>

Không kết hợp preset tường minh với màu tùy chỉnh trừ khi cố ý để preset ưu tiên.

Bỏ tùy chỉnh Shadow DOM từ bên ngoài

Xóa các tích hợp phụ thuộc vào:

  • element.shadowRoot;
  • bộ chọn nội bộ;
  • ::part(...);
  • biến CSS công khai --orbz-*;
  • giả định về cấu trúc DOM nội bộ.

Thay bằng thuộc tính, phương thức, cổng, bộ chuyển tiếp, sự kiện và export đã được mô tả.

Đăng ký phần tử tùy chỉnh tường minh

Dùng điểm vào trình duyệt khi mô-đun hiện tại cần đăng ký <orb-z>:

import "@neongate-ai/orbz/browser";

Dùng gốc gói khi import kiểu hoặc tiện ích không có tác dụng phụ trình duyệt:

import {
  defineOrbz,
  type OrbzElement
} from "@neongate-ai/orbz";

Gọi defineOrbz() tường minh khi ứng dụng chủ cần kiểm soát việc đăng ký.

Chủ động bật giọng nói

0.2.0 và 0.3.0 lên lịch hội thoại sau lần kết xuất kết nối đầu tiên. 0.3.1 bỏ hành vi này: ứng dụng hiện tại gán voiceEngine, talkFlow, intelligence, rồi gọi startTalking() tường minh sau khi khách chọn bật.

import '@neongate-ai/orbz/browser'
import {
  OpenAISpeechAdapter,
  type OrbzElement
} from "@neongate-ai/orbz";
 
const orb = document.createElement("orb-z") as OrbzElement;
 
orb.voiceEngine = new OpenAISpeechAdapter({
  endpoint: "/api/orbz/speech"
});
 
document.body.append(orb);
 
const startVoiceButton = document.querySelector<HTMLButtonElement>("[data-start-voice]");
 
startVoiceButton?.addEventListener("click", async () => {
  await orb.startTalking();
});

Nếu trình duyệt vẫn từ chối âm thanh dù đã có thao tác rõ ràng, Orbz thử lại luồng đã yêu cầu ở lần tương tác tiếp theo.

0.1.0 — Bản phát hành công khai đầu tiên

  • Phát hành gói @neongate-ai/orbz đầu tiên trên npm.
  • Xác lập Orbz là phần hiển thị giọng nói AI độc lập framework, xây bằng Web Components.
  • Cung cấp năm trạng thái idle, listening, thinking, speaking, asleep.
  • Cung cấp kích thước, tốc độ, tạm dừng/phát, khởi động lại và cấu hình giảm chuyển động có thể điều chỉnh.
  • Thêm tạo và đăng ký phần tử an toàn cho SSR.
  • Thêm điểm vào đăng ký và bundle trình duyệt độc lập.
  • Thêm bộ chuyển tiếp React ban đầu.
  • Cho phép ghi đè màu bằng thuộc tính JavaScript colors.
  • Công khai biến CSS --orbz-*.
  • Dùng Shadow DOM mở và Shadow Parts có tên để tùy chỉnh bên ngoài.

Xem 0.1.0 trên npm

Quy ước phiên bản

Các thuộc tính, phương thức, sự kiện, cổng, bộ chuyển tiếp, kiểu, hằng số và export được mô tả đều là API công khai.

Từ Orbz 1.0.0:

  • thay đổi API công khai không tương thích tăng phiên bản chính;
  • tính năng tương thích ngược tăng phiên bản phụ;
  • sửa lỗi tương thích ngược tăng phiên bản vá.

Ví dụ, tài liệu, cấu hình triển khai và tổ chức mã nội bộ có thể thay đổi mà không tạo thêm hợp đồng runtime công khai. Chúng minh họa và giải thích gói đã phát hành, nhưng chỉ thuộc API npm nếu được export tường minh hoặc nằm trong hợp đồng thành phần được mô tả.

Cập nhật lần cuối vào
Khắc phục sự cốBản demo