沉浸式 AIUI
如果你希望 AIUI 承载更完整的交互过程,而不是只把 UI 放进聊天消息里,那么最适合从沉浸式 AIUI 开始理解。它的核心特点是:主交互发生在一个独立界面中,AI 与用户围绕这个界面持续协作。
1. 先理解它和对话式 AIUI 的区别
沉浸式 AIUI 和对话式 AIUI 最大的区别,不在于“页面更大”或“界面更复杂”,而在于它们的调起方式和上下文模型不同。
区别 1:它不是页面 tool,而是直接调起整个 agent
对话式 AIUI 通常会在页面的 script def 中通过 description 和 schema.data 把页面声明成一个可调用工具,模型根据上下文决定何时调用这张卡片或这块 UI。
沉浸式 AIUI 则不同。它不需要把某个页面定义成一个独立的 tool,而是通过智能体本身的描述信息直接调起整个 agent。被调起后,运行时会进入 app.json 中配置的第一个页面,由这个页面作为沉浸式交互的起点。
一个最小的入口关系可以先理解成这样:
# AGENTS.md
## Description
一个适合在斗地主场景中被直接调起的智能体,提供完整的牌桌界面、状态反馈和持续交互能力。
{
"pages": [
"pages/landlord/index"
],
"window": {
"navigationBarTitleText": "斗地主"
}
}
也就是说,在沉浸式 AIUI 里,真正被调起的是整个 agent,而不是某一个页面 tool;页面只是 agent 启动后承载体验的入口。
区别 2:它是独立上下文,语音交互需要开发者自己实现
对话式 AIUI 通常发生在现成的聊天上下文里,很多对话能力天然已经存在。
沉浸式 AIUI 则是一个独立运行的上下文。开发者如果还需要继续使用 ASR、LLM、TTS 等能力,就需要自己通过 SSE、WebSocket、fetch 等 API 把整套语音交互链路接起来,包括:
- 采集输入
- 把输入发送给模型或服务端
- 接收流式结果
- 更新界面状态
- 驱动语音播报或后续动作
这会增加实现成本,但它的最大好处也是高度自定义。你可以完全按照自己的产品节奏去组织语音、界面、状态和交互,而不受聊天容器本身的限制。
沉浸式 AIUI 常见的目标形态包括:
- 一个斗地主界面
- 一个任务面板
- 一个游戏或训练界面
- 一个操作流程较长的工具界面
在这些场景里,用户看到的重点不再是“AI 说了什么”,而是“当前界面正在发生什么”。
2. 创建一个基础项目
你同样可以先使用脚手架创建一个 AIUI 项目:
npm create @yodaos-pkg/aiui-agent my-aiui-immersive-agent
完成初始化后,你同样可以直接用 .ink 单文件组件来组织第一个沉浸式页面:
├── app.js
├── app.json
├── AGENTS.md
├── pages
│ └── landlord
│ └── index.ink
3. 用 .ink 先搭一个最小界面
以斗地主场景为例,先做出一个包含桌面区、手牌区和操作区的基础界面。这里的 .ink 页面只负责承载沉浸式界面本身,不再把自己声明成一个单独的页面 tool:
<script def>
{
"navigationBarTitleText": "斗地主"
}
</script>
<script setup>
export default {
data: {
roomId: '',
playerName: '你',
statusText: '等待用户操作',
selectedCards: ['7', '7'],
handCards: ['3', '4', '5', '7', '7', '9', '10', 'J', 'Q']
},
onLoad(query) {
this.setData({
roomId: query.roomId || 'room-demo',
playerName: query.playerName || '你'
});
},
playCards() {
this.setData({
statusText: '已提交当前出牌:一对 7'
});
},
passTurn() {
this.setData({
statusText: '本轮选择不要'
});
},
askAgentTip() {
this.setData({
statusText: 'AI 正在分析当前牌面,建议先出一对 7'
});
}
};
</script>
<page>
<view class="table">
<view class="desk-area">
<text class="section-title">牌桌区域</text>
<text class="desk-cards">上家出牌:6 6</text>
</view>
<view class="status-area">
<text class="status-text">{{ statusText }}</text>
</view>
<view class="hand-area">
<text class="section-title">{{ playerName }}的手牌</text>
<view class="cards">
<text
class="card"
ink:for="{{ handCards }}"
ink:key="*this"
>
{{ item }}
</text>
</view>
</view>
<view class="action-area">
<button bindtap="playCards">出牌</button>
<button bindtap="passTurn">不要</button>
<button bindtap="askAgentTip">提示</button>
</view>
</view>
</page>
<style>
.table {
display: flex;
flex-direction: column;
gap: 16px;
padding: 20px;
}
.desk-area,
.status-area,
.hand-area,
.action-area {
padding: 16px;
border-radius: 16px;
background: rgba(255, 255, 255, 0.05);
}
.section-title {
font-size: 16px;
font-weight: 600;
}
.desk-cards,
.status-text {
display: block;
margin-top: 8px;
font-size: 14px;
}
.cards {
display: flex;
flex-wrap: wrap;
gap: 8px;
margin-top: 12px;
}
.card {
width: 36px;
height: 48px;
text-align: center;
line-height: 48px;
border-radius: 8px;
background: #ffffff;
color: #111827;
}
.action-area {
display: flex;
gap: 12px;
}
</style>
这个 .ink 文件把整个沉浸式界面的核心骨架放在了一起。对于入门来说,这样能更快建立一个直觉:沉浸式 AIUI 的重点不是某条消息,而是围绕一个持续存在的界面去组织交互。这里的页面本身只是界面入口,不负责把自己声明成一个页面级 tool。
4. 这个界面是如何工作的?
在这个例子里:
statusText用来表达当前界面状态handCards用来渲染手牌区域playCards、passTurn、askAgentTip用来模拟操作和 AI 协作
也就是说,用户的操作、AI 的建议、界面上的状态变化,都会围绕这一个页面持续发生。
5. 适合从哪些场景开始?
如果你第一次做沉浸式 AIUI,建议从下面这些场景开始:
- 斗地主或其他回合制小游戏
- 任务执行面板
- 设备控制面板
- 流程较长的工具界面
- 需要持续状态反馈的交互界面
这些场景的共同点是:交互步骤更多、状态更连续、界面本身就是体验的核心。