一、项目简介:解决什么问题,给谁用
奇遇是一款运行在 Rokid Glasses 上的 AIUI 智能体。出发点很小:同样戴着乐奇眼镜的两个人擦肩而过,本可以认识一下。
但做完「认识」之后,很快撞上第二个问题:认识之后呢?很多同类产品在这里选择把用户导向站外聊天工具,故事就结束了。奇遇从 v2.2 起做了一个相反的决定,把连接留在站内:成为站内好友、用语音转文字聊天、每天互发续火花、一键进同一个语音房间、一起玩 7 款语音游戏。所有动作都在眼镜里完成,镜腿一次单击就是一个动作。
一句话概括现在的奇遇:
十公里内遇见同样戴乐奇眼镜的人;双方同意后成为站内好友,语音聊天续火花;报一个房号,全球任何一副眼镜都能进同一个语音房间,自由麦加实时字幕;还能一起玩。
目标用户是三群人:早期设备持有者(尝鲜与社交意愿)、户外佩戴场景用户(骑行、徒步、通勤),以及需要演示与联机的开发者(离线演示房间、服务自检、演示好友)。
截至 v2.5.4,奇遇包含 23 个 Page、3 个 Widget、1 个 Agent Worker,以及一套一体化公网服务端;约 2 万行代码(含测试与工具),147 项静态护栏、约 250 项单元测试与服务端双账号联调全部通过。当前安装包 dist/奇遇2.5.4.aix 约 178 KB。
────────────────────────────────────────
二、场景与用户意图:智能体如何理解「在场」
在眼镜上,「在场」不是抽象概念,它由三种很具体的输入构成。
第一是位置。默认发现 10 公里内的附近 Rokider。附近人少时不偷偷扩大范围,而是把「扩大到 20 / 50 / 100 公里」做成一个用户可以单击的显式选项,攒够 5 人即停止,且只影响本机这次查询。
第二是姿态与场景。走路、骑行时不能挡住视线,所以对讲房间提供三种信息密度预设,中间可以大面积留白;夜里或嘈杂环境还能切到放大字幕。
第三是输入。用户手上只有三个动作:前滑、后滑、单击、双击中的组合,没有触摸屏、没有键盘、没有第二个手指。
所以奇遇的意图设计不是做关键词匹配,而是把「用户此刻能做什么」直接写进页面结构与 app.json 的 agentPrompt:
说「附近有什么人」,打开首页附近列表; 说「一起玩」,打开对讲大厅的游戏列表; 说「打开积分商店」,进商店,第一行是分类,往下是 12 件商品; 说「和某某聊天」,直接进那个好友的聊天页; 说「背包」「我的道具」,打开背包查看已拥有道具与生效中的功能。
这套路由与 pages 数组一一对应,用户不需要学习层级,只要说出想做的事。收到好友请求时,请求会聚合在「消息」页,打开奇遇即可逐条处理。
这里有一个刻意的取舍:v2.5.4 之前,版本依赖「Rokid 账号信息」三方授权来下发系统通知;整改后不再申请任何账号或通知权限,改为打开应用后在消息中心聚合提醒。原因写在第七节,它也是这篇文章里最值得复盘的一次工程决策。
────────────────────────────────────────
三、方案设计:从「认识」到「留下」的四段链路
3.1 三手势契约:单击只有一个含义
眼镜交互最贵的成本不是「学不会」,而是不确定。奇遇把所有按键裁决集中到 lib/key-router.js,页面只能声明三种意图:
前滑或后滑:移动一项,不附带单击,不跳多项。 单击:确认当前焦点;不可逆动作先进确认层,绝不顺手返回。 双击:返回上一层;只有首页双击才退出奇遇,且必须通过强双击授权闸门。
页面不允许自己判断 event.code。三个动作、三种确定性,是后面所有体验设计的地基。
3.2 对讲房间的界面预设:为「戴着眼镜走路」设计
同一个房间,三种信息密度:
全面:成员名单加谁在说话,最多 4 条字幕,居家或坐着时用。 简洁:中间大面积留白,只看房号、麦状态和一行字幕,走路骑行用。 字幕:底部放大最近 3 条,嘈杂环境或路演用。
三屏只差信息密度,不差功能,预设可在大厅里滑动实时预览。积分商店里的「夜行字幕」商品在有效期内会强制切到字幕预设,这是「买的东西必须真的生效」的一个具体例子。
3.3 去微信化:把连接留在站内
这是 v2.2 最大的一次产品取舍。原本的「双同意互换第三方联系方式」被整体替换成:
附近发现 → 好友请求(双方同意)→ 站内好友 ├─ 一键进同一房间(房号自动送达) ├─ 语音转文字聊天(每天互发续火花) └─ 一起玩(7 款语音游戏)
好处有三层:平台不必担心流量外流;用户少一步「加好友再回眼镜」的割裂;隐私上根本不存在「交出联系方式」这个动作。代价是必须自己把聊天和留存做出来,于是有了火花与积分。
3.4 二次确认:不可逆动作的统一姿势
v2.5.3 补上了体验漏洞。积分商店原本单击商品就扣分,容易误触。现在单击只进确认层,界面用大字显示:
确认兑换 免死金牌 50 分 · 兑换后剩 10 分 数字炸弹踩中也算过关 取消 确认兑换 单击「确认兑换」才扣分 · 双击返回取消
余额不足时不会进入确认层,直接提示「还差 N 分」。这条规则和按键层的「双击返回」是同一套思路:不可逆的动作,必须先给一次反悔的机会。
3.5 匿名站内身份:把权限面缩到最小
v2.5.4 把身份体系重写为「本机随机匿名 ID」。首次启动生成 anonId,服务端只用它签发站内会话令牌,不读取账号标识、昵称、头像、手机号或通讯录。好友请求与房间邀请只在用户打开应用后于「消息」页聚合展示,不申请系统通知权限、不后台常驻、不跨应用推送。
这条改动让「附近社交」这类敏感场景的权限面缩到只剩三项:GEOLOCATION、RECORD_AUDIO、INTERNET。
────────────────────────────────────────
四、AIUI 实现:项目结构与关键代码
4.1 项目结构
pages/ 23 个页面:附近、好友、聊天、商店、背包、对讲 7 页、替身、每日、设置等 widgets/ 1×1 附近小组件、1×2 新消息提醒叠加层、1×2 新请求叠加层 workers/ Agent Worker:通知与意图直达 lib/key-router.js 三手势裁决、回音吞并、返回静默 lib/input.js 页面输入作用域与「三参数契约」 lib/auth-gate.js 匿名站内身份与连接态 lib/points.js 积分、等级、任务、商店(纯函数) lib/spark.js 火花档位与结算(纯函数) lib/chat.js 聊天气泡、互发日期、离线队列 lib/talk-game.js 7 款语音游戏的统一驱动 lib/realtime.js createRealtimeClient(poll | agora) lib/tts.js 按性别与说话档案选音色 lib/profile.js 资料合并:本机优先、云端补齐 server/ 主服务:附近、好友、聊天、积分 server/talk/ 对讲服务:房号、语音段、字幕 server-all/ 一体化部署,/api 与 /talk 同域 tools/validate.mjs 147 项静态护栏 tests/ 约 250 项单测与服务端联调
有一条经验值得单独说:页面按键处理必须传三个参数。
onKeyUp(event) {
handleKeyUp(event, this.__scope, {
isRoot: false,
step: (dir, code) => this.step(dir, code),
confirm: () => this.confirm(),
back: () => this.back(),
});
}
早期写成 handleKeyUp(event, this),结果整页按键全被吞:路由层拿不到 scope 和三个处理器,只能把事件判成「无主」。现在这条已经变成静态护栏,任何页面少传参数,打包前就会失败。
4.2 按键路由:把「幽灵单击」治理成确定性状态机
真机触摸板一次手势会尾随上报 0.3 到 1 秒的原始信号,造成过两类恶性 bug:单击变双击退出、返回后自动进入别的页面。
现在的裁决模型是:一次点击只产生一个 pending;双击必须满足「真实抬起 + 间隔 140 到 300 毫秒 + 同页面作用域 + 独立按下证据」;返回后三层防护依次为 130 毫秒硬静默吞尾随、320 毫秒软静默只吞无按下证据的孤立信号、hook 设备 8 秒「无证据即回声」;退出奇遇是唯一不可逆动作,必须通过 isExitGrantValid 的强双击闸门。
带按下证据的真人点击随时放行,没有证据的孤立信号按时间窗拦下。底部提示因此写的是「返回后等 3 秒再单击」——比承诺「可以直接单击」然后落空更诚实。
4.3 对讲数据面:不用 WebSocket 的多人语音
对讲最初的约束是「要能在最便宜的托管上跑」,所以数据面非常朴素:说话时按 1.4 秒切一个可独立播放的短语音段,base64 上行;客户端 320 毫秒轮询拉新段,按 userId 分轨播放,同人顺序、异人并行;字幕走系统级连续语音识别,本机说的话立刻在本机上屏,置信度 0.82 加最短 2 字过滤;服务端只在内存中转,语音段不落盘。
它不完美,延迟受轮询影响,但零依赖、可单端口托管、全球可达,在免费容器上就能跑完整链路。
4.4 实时抽象与声网接口预留
对讲真正的下一步是实时音频与实时消息,所以先把抽象层写掉:
export function createRealtimeClient(mode) {
if (mode === 'agora') {
// 预留:RTC 音频 + RTM 信令 + ConvoAI 语音克隆
return { ok: false, reason: 'SDK 未接入' };
}
return pollClient();
}
export function channelNameFor(roomNo) {
return 'qiyu-' + roomNo;
}
服务端也预留了 token 路由。接入声网时,需要改的只有一处实现,页面契约、房间号、成员状态与积分数据都不动。特意让 agora 模式在未接入时明确失败,而不是静默降级到轮询:用户不该在不知情的情况下以为自己在用实时音频。
4.5 积分与火花:两个可复跑的纯函数模块
留存的抓手不能是「每天弹个提醒」,而要变成用户自己会想完成的小事。所以积分和火花都做成零依赖的纯函数模块,能直接在 Node 里跑单测。
// lib/spark.js:档位只由天数决定
export const SPARK_TIERS = [
{ min: 0, name: '未点亮', icon: '·' },
{ min: 1, name: '迷你火花', icon: '★' },
{ min: 3, name: '小火花', icon: '★★' },
{ min: 7, name: '中火花', icon: '☾' },
// 后续 14 / 30 / 60 / 100 / 200 / 365 / 730 天
];
关键规则只有一条:火花天数只能由「双方都发过消息的日期」算出(mutualDaysOf),不允许前端自己数「我发了几条」。这样两台设备、换手机、重装,算出来的天数都一致。图标沿用 QQ 那套星、月、日、冠十级顺序;真机字体缺符号时可一键切到纯中文图标。
积分只奖励社交行为:签到、今日一问、随机匹配、建房、进别人房、玩一局、给好友发消息、邀请好友、与 3 / 5 / 7 人同房满 5 分钟。挂机不计时。
4.6 积分商店:从赚到花,再到真生效
积分不给出口,很快会变成一串没人看的数字。所以商店做成周期制为主:
消耗品 5 件:提示卡、重摇骰子、免死金牌、补签卡、火花保护卡。 周期品 7 件:今日置顶 1 天、匹配优先 1 天、话题卡包 7 天、夜行字幕 7 天、专属称号 30 天、霓虹房间 7 天、替身扩容 30 天。 周期商品重复购买是叠加时长,过期自动失效。
更重要的是「买了必须真生效」,否则用户第二次就不买了。每件商品都有明确的生效点:
提示卡:游戏里上滑时自动多用一条线索。 免死金牌:数字炸弹踩中时自动免死一轮。 重摇骰子:真心话大冒险说「重摇」时自动重开。 补签卡:今日页补回连续签到天数。 火花保护卡:火花结算时自动顶一次断签。 夜行字幕:房间强制切到字幕预设。 专属称号、霓虹房间:房间昵称后缀与顶部装饰行。 话题卡包:破冰话题牌堆增加 10 张。 替身扩容:声音采集句数从 4 句扩到 8 句。 今日置顶、匹配优先:写入服务端 boostUntil,附近排序与匹配队列都认。
背包页把「已激活功能」与「我的道具」分开显示,周期功能写明剩余天数或小时,到期自动消失。
4.7 替身、音色与 EverOS 记忆接口
AI 替身的思路是「用你的方式替你接话」,而不是「假装你在线」:朗读 4 句采集平均句长、口头禅、语气词、语气倾向,样本只存本机;音色按「资料性别 + 替身页选择」解析,成员名单与字幕始终标注「替身」,绝不冒充本人。
早期把 utterance.voice 写死成女声,男用户的替身听起来完全不对,这是 v2.5.0 修掉的一个真实 bug。现在朗读统一走 lib/tts.js:能挑到同性别系统音色就精确指定,挑不到就用音高兜底。
长期记忆留给 EverOS。服务端 /api/memory/sync 与客户端 memoryPayload() 已经就绪,只上传统计特征、性别与 cloneId,朗读原文不出本机。没配 EVEROS_API_KEY 时页面明确显示「本机已保存 · 记忆服务未接入」,不假装同步成功。
4.8 匿名会话:一次「不改页面」的身份替换
v2.5.4 的身份整改要求「功能不中断、用户数据不丢」。做法是新增 /api/session/anon,并为尚未部署新接口的服务端保留回退通道:
const primary = await request('/session/anon', { method: 'POST', body: { anonId } });
if (primary.ok) return save(primary);
const fallback = await request('/session/bind', {
method: 'POST', body: { accountId: 'anon:' + anonId, code: '' },
});
return save(fallback.ok ? fallback : primary);
两条路径的 userId 都由 hash('anon:' + anonId) 得出,因此服务端后续升级到新接口时,用户资料、积分、好友关系不会换号。这个细节让我可以在不强制用户同步升级服务端的前提下完成客户端整改。
────────────────────────────────────────
五、交互与体验:界面与反馈
单色绿 480×352 的屏幕没有颜色可用,所有层级只能靠字号、留白、符号表达。几条实践:
一屏最多 5 条可聚焦行,超过就靠滚动,且焦点必须始终可见。 底部固定操作提示:「前后滑动切换一项 · 单击确定 · 双击返回 · 返回后等 3 秒再单击」。 危险动作先确认(兑换、清空档案),确认层写清「兑换后剩多少分」。 所有买了的东西在背包里能查到剩余时间,过期自动消失。 聊天页最下方常驻「每天互发一条续火花 · 再 N 天到下一档」。 首页顶部直接显示「我的等级:初见 · 30 积分(还差 70 升级)」。
v2.5.4 针对审核意见「页面内文字过小」做了全站字号整改:23 个页面与 3 个小组件共 284 处 font-size 按「小字加 2、中等加 1、大标题不变」整体调大,最小字号由 8px 提升到 10px,正文由 9px / 10px 提升到 11px / 12px,行高与滚动区域重新核对,避免放大后出现重叠或裁切。提审预览图与演示视频按同一映射重绘,保证材料与真机界面一致。
────────────────────────────────────────
六、调试与验证:让质量可复跑
这一块投入最多,也最值得分享。因为开发机 USB 口接触不良,adb devices 长期为空,v2.1.1 之后基本无法装机,只能靠三层替代验证:
第一层,静态护栏 147 项。tools/validate.mjs 检查页面结构、按键三参数、返回提示文案、昵称规则、商店二次确认、匿名身份是否残留官方账号接口、最小字号、打包是否漏进 .dev.vars、版本号是否升、旧版本包是否清掉。
第二层,纯函数单测约 250 项。按键路由用假时钟跑时序回归;火花用固定日期跑断签与保护卡;积分跑合并算法;游戏跑答案匹配,剥掉「我觉得 / 是 / 吧」之后再整体比对。
第三层,服务端双账号联调。真起进程,走完注册、资料、附近、加好友、聊天、积分备份,含 401 与越权校验;线上连通性另外用 curl 实测 health 与会话绑定接口。
一个具体例子是积分合并。用户要求「更新版本不能清空积分」,但如果只是取最大值,已经花掉的积分会在下一次同步时被补回来。所以引入单调的 earned:
out.earned = Math.max(a.earned, b.earned);
if (a.earned > b.earned) out.total = a.total;
else if (b.earned > a.earned) out.total = b.total;
else out.total = Math.min(a.total, b.total);
三种场景都有测试锁死:花了 20 分不会被补回、旧云端不会覆盖本机新分数、换设备能把分数找回来。资料与设置也用同样的「本机优先、云端补齐」规则,避免「昨天设的昵称今天没了」。
最后交付前固定跑三件事:npm test、aix check(0 diagnostic)、解包复核(0 凭据、0 服务端源码、0 文档、0 敏感字样)。真机渲染与触摸板手感仍需装机确认,这一点在本文里如实说明,不用静态检查冒充真机验证。
────────────────────────────────────────
七、成果与复盘
7.1 可运行成果与可验证材料
眼镜端:23 个页面、3 个 Widget、1 个 Agent Worker,安装包 dist/奇遇2.5.4.aix 约 178 KB,与 dist/奇遇.aix 内容一致。 服务端:一体化部署,/api 与 /talk 同域,国内可达。健康检查地址 qiyu-talk-rooms.app.workbuddy.host/api/health?… 协议页:用户协议与隐私政策同域公开,qiyu-talk-rooms.app.workbuddy.host/agreement.h… 玩法:7 款语音游戏、积分与商店、好友火花、随机匹配、AI 替身、离线演示房间。 材料:16 张界面预览图、34 秒演示视频、提审文案、参赛策划案、README 与 AGENTS 工程契约,tools/validate.mjs 与 tests/ 可直接复跑。
投稿状态如实说明:奇遇已提交 Rokid 智能体商店审核,v2.5.4 是针对审核意见完成整改后的版本;本文为纯文字版,截图与录屏材料在项目内单独提供,发布到论坛或 CSDN 时可另行上传。
7.2 遇到的问题与解决(挑四个)
第一,返回后第一击被吞。三个真凶:reset() 抹掉按下证据、返回时刻被记成一次 tap 导致去重、120 毫秒导航静默吞掉整段。修复后返回约 0.3 秒即可单击,同时把提示如实改成「等 3 秒」。
第二,资料隔天消失。旧代码用 payload.profile || local 覆盖,服务端记录一空就把本机昵称清掉。改成 mergeProfile「本机优先、云端补齐」,并把对讲昵称备份进资料字段。
第三,商店误触。单击直接扣分。v2.5.3 加入确认层,余额不足时不进入无效确认;v2.5.4 又把它写进静态护栏,防止后续改版退回旧写法。
第四,提审被判「请检查用户手机号获取必要性」。自查发现应用里根本没有获取手机号的按钮,全项目检索为 0;真正的原因在两处:提审表单的「Rokid 账号信息」被建议保持勾选,而平台在该勾选框旁标注「仅获取手机号时需勾选」;同时应用内有一整套引导用户去勾选该授权的首页行、1×2 叠加层、帮助页与设置页。审核看到的是「申请了账号与手机号相关权限」。
整改不是删一个按钮,而是换掉整条身份链路:不再调用官方账号信息接口,改用本机匿名 ID 签发站内会话令牌;删除全部授权引导入口,把「未打开时也能收到提示」功能整体改为打开应用后在消息中心聚合查看;提审填写说明改成「Rokid 账号信息保持未勾选」,用户协议与隐私政策同步补充不申请账号权限的说明;顺带清理旧版遗留字段与一道涉及通讯录的游戏题目。整改后应用源码与安装包内均为 0 处「手机号」「微信」相关字样,静态护栏新增三条:禁止官方账号接口、匿名路由必须存在、字号不得小于 10px。
这件事的教训很直接:合规问题往往不在「你写了什么功能」,而在「你申请了什么权限、材料里怎么描述它」。权限面能缩就缩,材料与源码必须同一套口径。
7.3 复盘与下一步
奇遇现在的定位很清楚:它不是一个用完即走的工具,而是一条从偶遇到日常的社交链路。下一步两件事都已留好接口,但当前版本均未接入,不把未实现的能力写成已实现。
声网 Agora(预计 SDK 可用后接入):RTC 把短语音段加轮询换成实时音频以降低延迟;RTM 承载成员变化、谁在说话与游戏状态;空间音频让多人房间按方位摆位;ConvoAI 实现真音色克隆,让替身用机主本人的音色说话。目前先按性别选音色并在页面明示。
EverOS 长期记忆:配置 Key 即开启,写入长期说话档案(句长、口头禅、语气、cloneId),换设备后替身仍然像你;坚持最小化,只上传统计特征,朗读原文不出本机。
────────────────────────────────────────
附:投稿与体验信息
作品名:奇遇(QiYu) 形态:Rokid AIUI 智能体,23 Page / 3 Widget / 1 Agent Worker / 一体化服务端 当前版本:v2.5.4 征文主题:从对话到行动 —— 用 AIUI 构建意图驱动的智能界面 发布渠道:Rokid 开发者论坛「征文计划」板块(普通贴、公开可见)与 CSDN(全部可见) 体验路径:打开奇遇 → 积分商店(单击商品看二次确认)→ 我的背包(看生效中的功能)→ 好友 → 测试用户(演示)→ 聊天续火花;或 对讲 → 离线演示房间(无需联网) 工程文档:README 记录版本迭代,AGENTS 记录硬性契约,tools/validate.mjs 与 tests/ 可复跑
因为乐奇,所以遇见。下一次擦肩而过,希望你能在眼镜里看到对方。