Orbz 的设计理念

Orbz 从一个刻意精简的想法出发：应用每次更换框架时，不应重新构建助手的视觉形象。

浏览器已有通用组件模型，Orbz 直接使用它。原生 <orb-z> 在纯 HTML、Vue、Svelte、Angular、React、Next.js 或混合微前端页面中提供相同状态、外观和动效控制。

一个契约，多种宿主

框架集成往往逐渐分化：React 包装器新增 Vue 没有的功能，Angular 选择不同默认值，纯 JavaScript 版本被遗忘。Orbz 保持一个原生实现，让框架绑定公开属性。

所有宿主因此共用相同词汇：

• 五个助手状态：idle、listening、thinking、speaking、asleep
• 一个 preset 属性或五个自定义颜色属性
• size、speed、paused、elevated、reduced-motion
• play()、pause()、restart() 方法

六个沙盒有意呈现相同界面。框架代码不同，组件契约与用户体验相同。

带可选语音接口的视觉基础组件

Orbz 负责视觉表达，并提供可选对话流程以及浏览器和 OpenAI 兼容语音适配器。应用负责赋予其含义的决策与安全边界：

• 语音何时开始或结束，以及访客如何主动启用
• 麦克风权限、音频采集和语音识别
• 语音引擎选择、受保护端点和凭据
• 模型请求、工具调用和流式传输
• 轮次交替、取消、错误和重试
• 转录、按钮、标签及其他语义界面

此边界使软件包适用于任何语音供应商、AI SDK、状态管理器或后端。应用把领域事件映射为五个 Orbz 状态之一，并在需要时显式启动已配置的对话运行时；Orbz 渲染对应表现。

实际状态映射见构建语音助手。

有意保持严格

支持的接口有意以属性为中心。Orbz 不公开 Shadow DOM 部分、公共 CSS 变量或框架专用组件适配器。

这种严格性有三个目的：

1. 可移植性。 同一配置在每个宿主中含义相同。
2. 稳定性。 内部图层与动画可演进，不会意外成为公开 API。
3. 一致性。 团队定制预定的设计参数，而不是逐个选择器替换组件。

产品需要独特外观时，可选内置预设或提供五个文档化颜色。不同的语义或交互应由球体周围的应用实现。

隔离是实现承诺

每个实例创建封闭 Shadow DOM。其标记、样式和动画图层私有，页面 CSS 无法进入改写，Orbz 也不会将内部选择器泄露到页面。

封闭不等于不可访问。Orbz 是装饰性视觉组件，内部图形对辅助技术隐藏。宿主提供无障碍标签，最好在附近提供实时状态文字，描述助手当前状态。

服务端安全，浏览器原生

服务端渲染时可导入软件包，不会在模块作用域求值 HTMLElement 子类。注册带保护且幂等：服务器上不操作，浏览器中仅在未注册时定义 orb-z。

因此，原生元素兼容服务端渲染的外壳，同时保持浏览器原生运行。服务器输出元素，客户端在注册后升级。可选 react-types 入口添加 JSX 类型，无需 React 包装器或运行时适配器。

推荐模式见 SSR 与水合。

仓库遵循公开边界

Orbz 软件包、本文档站和 Orbz Sandbox 是独立项目。沙盒应用从 npm 使用 @neongate-ai/orbz@0.3.1；文档和沙盒都不导入相邻包工作区或私有源码路径。

每个沙盒可作为独立 Vercel 项目部署。微前端外壳也可使用相同包。持久边界是已发布的软件包和 <orb-z> 契约，而非共享仓库布局。

新功能的判断标准

扩展公开接口前，请问：

• 这是各框架共有的视觉需求吗？
• 能用简洁可序列化属性或有类型的属性表达吗？
• 能在原生 HTML 与适配器中保持确定行为吗？
• 保留组件封闭且严格的边界吗？
• 应用仍能在球体外提供无障碍含义吗？

若答案为否，该功能可能属于宿主应用。精简契约不是限制，而是让同一个组件能在各处保持一致的条件。