常见问题
本页汇总 AIUI 开发过程中经常遇到的问题。开始开发前,建议先阅读快速开始;如果问题与某项具体能力有关,请同时查阅对应的组件或 API 文档。
我应该从哪里开始学习 AIUI?
第一次使用 AIUI 时,建议按以下顺序阅读:
- 阅读介绍,了解 AIUI 的适用场景。
- 完成快速入门,熟悉开发、调试与发布流程。
- 根据产品形态选择对话式 AIUI或沉浸式 AIUI。
- 阅读项目结构,了解项目文件如何组织。
对话式 AIUI 和沉浸式 AIUI 有什么区别?
对话式 AIUI 适合在聊天流程中展示轻量、上下文相关的交互内容;沉浸式 AIUI 适合需要独立页面、持续操作或更完整视觉布局的任务。两者可以在同一个智能体中配合使用,具体选择取决于任务需要的交互深度。
在哪里查找组件和 API 的用法?
- 界面元素及其属性请查阅组件。
- JavaScript、设备、网络、媒体和 AI 能力请查阅 API。
- 智能体的组织方式和运行机制请查阅智能体框架与智能体运行时。
遇到运行或显示问题时如何排查?
先确认项目结构和相关 API 用法是否符合当前文档,再使用网页端模拟调试快速检查逻辑和界面。涉及设备能力、平台差异或真实运行环境的问题,应继续使用真机调试验证。
如何打包和发布智能体?
请先了解 AIX 包格式,再根据提审与发布完成发布流程。需要在本地处理包文件时,可参考命令行工具。
全彩眼镜需要单独创建智能体吗?
仅做全彩适配无需单独创建智能体。建议在同一个项目、同一个 AIX 中复用业务逻辑、Page、Widget 和数据服务,按显示能力切换配色与资源,按可用空间调整布局。只有产品定位或核心功能需要独立时,再考虑拆分。具体步骤见全彩眼镜适配指南。
全彩规范适用于哪款设备?
当前全彩规范面向乐奇全彩眼镜,英文名为 Rokid Color,二者是同一设备的中英文名称。全彩内容区域宽 448、高度上限 352;单色显示的内容高度上限也为 352。RokidGlasses1 / RokidGlasses2 的单绿色显示继续参考 Monochrome。设备相关 API 与交互仍需分别验证,不要因为支持全彩就假定其他硬件能力一致。
适配全彩只需要换颜色吗?
还需要检查内容空间、字号、图标、内外边距、焦点态和资源。全彩文字为 14~24 dp,图标不小于 12 × 12;单色页面中的小字号、大面积填充和长页面不能直接照搬。内置主题提供默认样式,但不会自动修正自定义布局、图片或 Canvas。数值要求见全彩视觉规范。
如何判断当前是全彩还是单色?
在支持的运行时中,样式使用 @media (color) / @media (monochrome),页面逻辑使用 window.matchMedia()。不要用设备名称、屏幕宽度或 target 代替显示能力判断。两项查询都不匹配时保留未知状态,不能直接当作单色;旧版运行时需保留基础展示。示例见全彩眼镜适配指南。
为什么黑底、深色文字或半透明内容在眼镜上看不清?
纯黑在眼镜上显示为透明,不能遮住真实世界;过暗的颜色也不适合承载关键内容。优先使用白色正文与清晰亮色,可见内容 alpha 建议不低于 40%,避免对整个卡片叠加透明度。最外层卡片无边框;内部卡片描边为 1px 白色,默认 alpha 30%,选中或聚焦时为 100%。30% 的内部卡片边框不受前景 40% 建议下限约束;分割线仍为 1px、alpha 40%。请在不同真实背景和光照下验证,优化方法见全彩优化指南。
内容超过 352 高度,或者切到沉浸式后,应该怎么处理?
优先拆分摘要与详情、分页或使用可操作的滚动区域,保留关键操作。_blank 表示展示容器变化,不会取消全彩 448 宽、最高 352 的内容约束。不要依靠缩小字号、减少规定边距或裁剪内容解决溢出;在真机上检查阅读、滚动、焦点与返回路径。