跳转到正文
OrbZ更新日志

更新日志

本页记录公开软件包 @neongate-ai/orbz、自定义元素 <orb-z> 的契约及其受支持集成方式中面向用户的变更。

实现以 GitHub 仓库 为准。已发布版本可在 npm  获取，完整文档位于 orbz.site 。

1.0.2 — 2026-09-08

Neongate 预设修正

  • 将 neongate 恢复为默认预设的规范名称，涵盖 DEFAULT_ORBZ_PRESET、ORBZ_PRESET_NAMES 以及元素的规范化预设 getter。Neongate 的颜色未变。
  • 保留 1.0.1 中意外采用的账号名称，作为已弃用的输入别名。现有属性、属性赋值、类型化输入和校验函数仍接受它；规范化与属性反射使用 neongate。
  • 保留已弃用的调色板键，作为 ORBZ_PRESETS.neongate 的不可变、不可枚举别名。规范预设列表仍有六项。
  • 规范化旧版精简和完整配置对象，不修改调用方输入，并保留提供的颜色与严格校验。

从 1.0.1 升级

安装已发布的补丁，并更新固定版本的 CDN URL：

npm install @neongate-ai/orbz@1.0.2

新的显式预设值请使用 neongate。使用旧账号键的输入仍兼容，可在方便时迁移。读取规范化预设名称的代码应预期 neongate。默认示例与调色板访问方式见 Neongate 预设命名。

此修正取代 1.0.1 的命名指导；下方仍保留其历史记录。npm 作用域仍为 @neongate-ai/orbz；维护中的源码仓库现归 jonatassales 所有。

在 npm 查看 1.0.2 · 浏览 v1.0.2 源码标签 · 比较标签源码 

1.0.1 — 2026-09-08

清理与精简配置

  • 修复 Orbz 源码检出目录中的 orb cleanup（别名 orb clean），默认删除根目录和子目录中未跟踪的 node_modules 及生成产物。--dry-run 预览目标，--keep-dependencies 保留依赖。受跟踪内容、源码/资源、harness 元数据及嵌套仓库会保留，清理不跟随目录符号链接。
  • 简化编写的配置 JSON。转换器用类型化默认值补齐省略的内部外观、动画和语音分组，再校验、克隆并冻结运行时配置。仍支持显式覆盖这些分组。
  • 将 GitHub 所有权链接更新为当时的个人账号，并更新 README、CLI 指南及工程检查。npm 包仍为 @neongate-ai/orbz。

从 1.0.0 升级

安装补丁，并更新固定版本的 CDN URL：

npm install @neongate-ai/orbz@1.0.1

此版本曾暂时将默认预设改为个人账号名，同时保留原有 neongate 颜色。1.0.2 恢复了规范名称 neongate；新集成请使用 <orb-z preset="neongate"></orb-z>。维护 Orbz 源码检出目录时，可用 orb cleanup --keep-dependencies 保留 node_modules；单独运行 orb cleanup 现在会删除它。即使这是补丁版本，这些迁移细节也适用。

在 npm 查看 1.0.1 · 比较标签源码 

1.0.0 — 2026-09-06

语音模型与 Realtime 对话

  • 为 web-speech、openai-speech 和 openai-realtime 添加类型化 JavaScript 属性 voiceModel。选择提供商不会发声；宿主在用户激活后显式启动语音或对话。
  • 添加 OpenAIRealtimeAdapter 和浏览器直连提供商的 WebRTC 音频。应用通过 realtimeSession 授权会话建立，可使用自己的端点或返回 SDP answer 的异步回调。
  • 添加 startConversation()、stopConversation()、interruptConversation()、只读 conversationState，以及 orbz-conversation-state-change 和 orbz-transcript 事件，由应用实现控制和转录界面。
  • 提供商密钥保留在应用后端。模型设置仅含公开配置；端点对象拒绝 apiKey、token、headers 等未知字段。密钥和会话令牌都不应放入 HTML 属性、组件属性或配置 JSON。

规范配置与 CLI

  • 分支维护者现在编辑 src/orbz.config.json 中的组件、外观、动画、语音和 Realtime 默认值，然后重新构建。安装的包使用内置默认值，不在运行时获取配置。
  • 添加只读 orbzConfiguration 和纯函数工具 transformOrbzConfiguration()，可校验、克隆、转换和冻结完整配置，不改变包的单例。
  • 整合 Orb CLI 的命令处理与帮助。现有公开导出、视觉属性、原生注册和显式 voiceEngine 集成仍可使用。

从 0.4.3 升级

安装已发布版本，并更新所有固定版本的 CDN URL：

npm install @neongate-ai/orbz@1.0.0

现有视觉示例仍使用 <orb-z> 标签和同一浏览器入口。新的结构化选项通过 JavaScript 属性设置；没有 voice-model HTML 属性。Realtime 需要应用负责会话授权并显式激活；升级包不会启动音频或请求麦克风。显式指定的 voiceEngine 优先于 voiceModel。

在 npm 查看 1.0.0

0.4.3 — 2026-09-04

自 0.3.1 以来的重点变更

  • 将已发布的 POSIX shell CLI orb 添加为包的可执行程序。可通过 npx -y --package=@neongate-ai/orbz@latest orb 临时运行。
  • Orb 项目设置根据项目元数据与锁文件识别 npm、pnpm、Yarn 或 Bun，安装正在执行的 Orbz 版本，不生成或覆盖应用源码。
  • WebSpeechAdapter 现在默认使用巴西葡萄牙语（pt-BR）。应用可覆盖 language，包括使用 en-US。
  • Orbz 不再内置固定问候语、角色或默认对话流程。使用方提供 speech 或 talkFlow，配置 voiceEngine，并显式调用 startTalking()。

在 npm 查看 0.4.3

0.3.1 — 2026-08-25

显式启用语音

  • 连接或升级 <orb-z> 不再创建默认语音引擎或启动对话流程。
  • voiceEngine 现在默认为 undefined。应用明确提供引擎，并在访客选择启用后调用 startTalking()。
  • 设置语音引擎仍不会发声；stopTalking() 停止活动流程，设置 undefined 则移除配置的引擎。
  • 通过 HTML 或服务端渲染标记传入的数字字符串现在会统一规范化为像素长度，与数值属性一致。

在 npm 查看 0.3.1

0.3.0 — 2026-08-23

React 与 Next.js 类型支持

  • 为 React 和 Next.js TypeScript 项目添加可选入口 @neongate-ai/orbz/react-types。
  • 此入口扩展 JSX，为 <orb-z> 提供类型，无需框架包装组件。
  • Orbz 的运行时依赖仍不包含 React；React 类型仅用于构建可选声明入口。

0.2.0 — 2026-08-22

Orbz 0.2.0 将原有视觉助手组件扩展为支持语音、独立于框架的自定义元素。此版本引入对话运行时、可替换的语音与智能接口、更严格的外观控制、更强的封装，以及适用于所有支持框架的统一原生集成方式。

1.0 之前的不兼容版本： 使用 0.1.0 的 colors 属性、公开 CSS 变量、Shadow Parts、开放 Shadow DOM 或 @neongate-ai/orbz/react 的应用必须迁移。

语音与对话运行时

  • 添加自动且确定性的对话流程，在元素首次连接渲染后启动。
  • 通过公开 talk 对象和 DEFAULT_TALK_FLOW 添加内置步骤 welcoming、askName、help 和 answer。
  • 添加仅存在于运行时的对话记忆。默认流程记录访客姓名并通过 talkContext 提供，不写入 cookies、本地存储、IndexedDB 或后端。
  • 添加 startTalking()，重置当前运行时上下文并重新启动配置的流程。
  • 添加 receive(input)，使宿主应用能用自己界面收集的文本继续当前提问或回答步骤。
  • 添加 stopTalking()，停止当前流程与语音输出。
  • 添加可配置属性 voiceEngine、talkFlow 和 intelligence。
  • 添加公开 TypeScript 契约 OrbzTalkStep、OrbzTalkContext 和 OrbzVoiceOptions。
  • 添加 OrbzVoiceEnginePort，使应用可替换语音输出而无需修改组件。
  • 添加 OrbzIntelligencePort，连接智能体或其他回答提供商，同时将产品逻辑和凭据保留在 Orbz 外部。
  • 未配置智能提供商或提供商失败时，提供本地备用回答。
  • 添加事件 orbz-speaking-change，详情为 { speaking: boolean }。
  • 添加事件 orbz-talk-error，通过 { error: unknown } 提供原始错误。
  • 播放音频时暂时切换到 speaking 视觉状态，之后恢复原状态。
  • 麦克风采集、语音识别、权限、转录和文本输入仍由宿主应用负责。Orbz 只接收通过 receive() 传入的文本。

浏览器语音

  • 添加 WebSpeechAdapter 作为零配置默认语音引擎。
  • 将默认语音语言改为 en-US。
  • 浏览器语音会等待异步语音列表加载后再选择音色。
  • 添加显式英语筛选，不再接受无关语言的系统默认语音。
  • 添加首选语音选择，支持已配置的语音，以及浏览器提供的高质量 Google、Microsoft、自然、神经、premium、增强或在线语音。
  • 可配置语言、首选语音、语速、音高、音量和语音加载超时。
  • 检测无法启动的语音，避免对话流程无限等待。
  • 若浏览器通过 NotAllowedError 阻止自动音频，首次渲染的语音会在首次指针、键盘或触摸交互后自动重试。
  • 移除示例中必须通过全部重置重新挂载元素才能开始语音的行为。
  • 明确浏览器语音仍由访客的浏览器和操作系统提供。可以改善语音选择，但系统语音不会因此变成 OpenAI 生成的语音。

OpenAI 语音

  • 添加 OpenAISpeechAdapter，通过应用代理使用 OpenAI 文本转语音。
  • 默认使用 gpt-4o-mini-tts、marin 音色、MP3 输出和自然美式英语朗读指令。
  • 可配置模型、音色、响应格式、指令、凭据、请求头和 fetch 实现。
  • 兼容旧模型 tts-1 和 tts-1-hd，使用兼容的默认音色并省略不受支持的指令。
  • OpenAI API 密钥保留在浏览器和 Orbz 包之外。适配器调用集成方拥有的端点获取生成的音频。
  • 输出停止或被替换时取消待处理的语音请求。
  • 播放、取消或失败后清理生成的音频对象 URL。
  • 处理浏览器激活错误，使生成音频参与与浏览器语音相同的首次交互重试流程。

外观与组件 API

  • 用两种严格互斥的外观模式取代开放的 colors 属性：

    • preset 属性；
    • 五个属性 color-primary、color-secondary、color-accent、color-highlight 和 color-background。

  • 添加六个预设：neongate、periwinkle、magenta、peach、mocha 和 ivory。

  • 预设和自定义颜色互斥。两者同时存在时，Orbz 报告冲突、应用预设，并忽略自定义颜色，直到预设属性被移除。

  • 添加布尔属性 elevated，用于可选的居中阴影。

  • 保留五个公开视觉状态：idle、listening、thinking、speaking 和 asleep。

  • 保留正值速度倍数、尺寸规范化、暂停与播放、动画重启，以及 system、always、never 减弱动态效果策略。

  • 保留状态、预设、减弱动态效果、尺寸、速度和颜色配置的公开常量、校验及规范化函数。

  • 将 Shadow DOM 从开放改为封闭。

  • 移除公开 Shadow Parts 和外部 ::part(...) 样式。

  • 移除公开 --orbz-* CSS 变量定制。内部选择器与变量现在是私有实现细节。

  • 将组件源码样式移至 src/element/index.css，保留在封闭的 shadow root 内，并生成同一份 dist/index.css。

框架集成与包入口

  • 移除框架专用 React 组件和 @neongate-ai/orbz/react 入口。
  • 从 Orbz 运行时包的 peer dependency 和开发依赖中移除 React。
  • 所有框架统一使用字面自定义元素 <orb-z>。
  • 更新 React 和 Next.js 集成，注册浏览器入口并直接渲染 <orb-z>。
  • 在 React 和 Next.js 示例中添加本地 JSX intrinsic-element 声明，提供 TypeScript 类型识别，无需包装组件。
  • 保留 @neongate-ai/orbz 作为无副作用的类型、常量、适配器、接口、工厂和显式注册工具入口。
  • 保留 @neongate-ai/orbz/browser 作为注册 <orb-z> 的浏览器入口。
  • 保留 @neongate-ai/orbz/standalone，为 CDN 和直接脚本集成提供自动注册的独立浏览器包。
  • 保留服务端渲染环境中自定义元素类创建和注册的防护。
  • 多个包或微前端尝试注册元素时，defineOrbz() 仍保持幂等。
  • 将高级元素类创建函数改名为 orbzElementClassFactory()。
  • 将浏览器注册副作用移入显式浏览器入口，不再从包根入口执行。

构建、打包与内部组织

  • 添加 prepack 生命周期，在 npm pack 或 npm publish 前执行严格 TypeScript 校验并重新构建。
  • npm 包仅含生成的 dist 产物，以及 npm 自动包含的 package.json、README.md、LICENSE 等文件。
  • 文档、示例、内部智能体指令、源码及工作区配置不进入 npm tarball。
  • 为共享 tsdown 配置导入添加显式 .ts 扩展名，兼容 Node 原生 TypeScript 配置加载。
  • 按 core、element、factories、ports、services 和 talk 重组内部模块。
  • 将原 voice 源码区域改名为 talk。
  • 将相关类型声明整合到 .types.ts 模块。
  • 移除内部文件名中冗余的 orbz 前缀，保留公开 Orbz* 符号名。
  • 扁平化不必要的单文件目录。
  • 从包源码中完全移除 React 运行时实现。

示例与文档

  • 添加基于相同 <orb-z> 界面的同步 Vanilla、React、Vue、Svelte、Angular 和 Next.js 示例。
  • 重置控件恢复状态，无需重新挂载自定义元素。
  • 用 Nextra 文档站替换原 VitePress 框架。
  • 添加原生、框架及 CDN 集成入门文档。
  • 添加设计理念、状态、外观、动画与无障碍概念文档。
  • 添加框架、微前端、SSR 和语音助手指南。
  • 添加完整的元素和包导出 API 参考。
  • 添加示例、故障排查及迁移指南。
  • 将 orbz.site  设为主要文档地址。
  • 将框架专用子域名设为同步示例的部署地址。

在 npm 查看 0.2.0

从 0.1.0 迁移

替换 React 适配器

移除旧 React 入口的导入：

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

改为注册浏览器入口并渲染原生自定义元素：

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

如果 TypeScript 尚不识别 orb-z，请添加本地 JSX intrinsic-element 声明。此声明仅提供编译时类型识别，不会创建 React 组件。

替换颜色 API

移除旧 colors 对象：

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

使用内置预设：

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

或不设置 preset，使用五个受支持的自定义颜色属性：

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

除非有意让预设优先，否则不要同时设置显式预设和自定义颜色。

移除外部 Shadow DOM 定制

移除依赖以下内容的集成：

  • element.shadowRoot；
  • 内部选择器；
  • ::part(...)；
  • 公开 --orbz-* CSS 变量；
  • 对内部 DOM 结构的假设。

改用文档中公开的属性、方法、接口、适配器、事件及导出。

显式注册自定义元素

当前模块需要注册 <orb-z> 时使用浏览器入口：

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

导入类型或工具且不需要浏览器副作用时，使用包根入口：

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

需要由宿主应用控制注册时，显式调用 defineOrbz()。

显式启用语音

0.2.0 和 0.3.0 会在首次连接渲染后调度对话流程。0.3.1 移除了此行为：现在应用设置 voiceEngine、talkFlow 和 intelligence，并在访客选择启用后显式调用 startTalking()。

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();
});

如果浏览器在显式操作后仍拒绝请求的音频，Orbz 会在下一次交互时重试该流程。

0.1.0 — 首个公开版本

  • 在 npm 发布首个 @neongate-ai/orbz 包。
  • 将 Orbz 定义为使用 Web Components 构建、独立于框架的 AI 语音视觉组件。
  • 提供五个助手状态：idle、listening、thinking、speaking 和 asleep。
  • 提供可配置尺寸、动画速度、暂停与播放、动画重启及减弱动态效果配置。
  • 添加 SSR 安全的自定义元素创建与注册。
  • 添加浏览器注册入口和独立浏览器包。
  • 添加首版 React 适配器。
  • 通过 JavaScript colors 属性公开颜色覆盖。
  • 公开 --orbz-* CSS 变量。
  • 使用开放 Shadow DOM 和命名 Shadow Parts 支持外部定制。

在 npm 查看 0.1.0

版本管理约定

文档所列属性、方法、事件、接口、适配器、类型、常量和包导出都属于公开 API。

从 Orbz 1.0.0 开始：

  • 不兼容的公开 API 变更递增主版本；
  • 向后兼容的功能递增次版本；
  • 向后兼容的修复递增补丁版本。

示例、文档、部署配置和内部源码组织可以演进，而不增加公开运行时契约。它们演示并解释已发布包，但只有显式导出或列入组件文档契约的内容才属于 npm API。

最近更新于
故障排查演示