这个项目最初的起因很简单:我想在 Rokid 眼镜上玩飞花令。
不是那种“对着语音助手念一句诗,它夸我一句”的玩法,而是真正有规则的对局:定一个关键字,双方轮流说含这个字的诗句,重复、答错、超时都算输。手机上有不少飞花令小程序,但玩的时候要低头、要点屏幕,戴眼镜反而更别扭。眼镜的屏幕小,麦克风一直在线,用户的手是空的,这些限制凑在一起,刚好适合做一件很窄的事:用语音完成一整局对诗。
于是有了诗词飞花令。它现在有两个模式,飞花令和成语接龙;一局大约几分钟,能完整跑完“选模式、选难度、AI 出句、用户接句、判定、结算”的流程。下面是开发过程中的一些记录,包括设计取舍和踩过的坑。
一、项目简介
诗词飞花令是一个面向 Rokid 眼镜的语音对诗智能体。核心玩法是飞花令:系统随机给出一个关键字,比如“春”,AI 先说一句“春眠不觉晓”,用户要在 20 秒内说出一句含“春”的诗句,不能和本局已经出现过的句子重复。说对了,AI 继续接;说错、重复或者超时,本局结束。
第二个模式是成语接龙。AI 先出一个四字成语,用户接一个首字和上一个成语尾字相同的成语,循环下去。简单模式允许同音字,普通模式要求严格同字。
目标用户大概是两类人:一类是通勤、散步、排队时想找点事做的眼镜用户,另一类是想练诗词但不想盯着手机的学生或爱好者。它不解决什么宏大问题,就是让一段碎片时间有个轻量的、不用动手的对手。
当前版本包含 20 个关键字、86 条诗句、140 条成语。诗句和成语都打包在应用里,判定时本地库优先,本地找不到再调用 LanguageModel。这样做的原因很实际:眼镜端网络不一定稳,而飞花令的判定又必须在一两秒内给出反馈,不能每句都等云端。
二、场景与用户意图
典型的使用场景是这样:
晚上散步,戴上眼镜,说一句“飞花令”。首页列出“飞花令”和“成语接龙”,用户可以用方向键选,也可以直接说“成语接龙”。选完模式进入难度页,说“简单”或者“普通”。开局后 AI 先出句,屏幕右上角常驻一个 HUD,显示本局关键字、比分和倒计时。用户说一句诗,系统判定,对了弹一张两秒的反馈卡,然后 AI 接下一句;错了进结算页,可以选择再来一局、换个字、调难度或者退出。
这里面的用户意图其实不止“答题”一种。至少还有:
-
开局意图:选模式、选难度、指定关键字;
-
对局意图:说一句诗、确认或否认 ASR 听错的内容;
-
控制意图:换字、再来一局、调难度、退出。
如果只做一个聊天框,这些意图会混在一起,用户说“简单点”和说“春眠不觉晓”对系统来说都是文本。飞花令需要明确的回合、计时和胜负,所以我没有把它做成自由对话,而是做成了一个状态机:每个阶段只接受这个阶段该有的输入,语音和按键走同一套处理逻辑。
这也是我对“意图驱动界面”的理解:界面不是把所有功能一次性摆出来,而是跟着当前意图走。选模式的时候只给两个选项,对局的时候只留关键字、上一句和倒计时,结算的时候才出现指令列表。用户不需要记住“现在能说什么”,屏幕会告诉他。
三、方案设计
状态与页面
飞花令主页面在 pages/index/index.ink。
状态依次是 mode、difficulty、intro、playing、disambig、result。
-
mode:选飞花令还是成语接龙; -
difficulty:选简单或普通; -
intro:AI 出第一句,展示两秒开局信息卡; -
playing:倒计时、ASR 听用户作答、判定; -
disambig:ASR 结果有歧义时暂停倒计时做确认; -
result:结算卡常驻,等待“再来一局 / 换个字 / 简单点 / 难一点 / 退出”。
成语接龙单独放在 pages/idiom/idiom.ink。它的回合结构和飞花令不一样,有 AI 出词、用户接词、判定、首次答错重试这些子状态,塞进同一个页面会让条件分支变得很难读,所以干脆拆成子页面,从首页 navigateTo 过去。首页在 onShow 里检测到从子页面返回时,会把状态重置回模式选择。
屏幕布局
屏幕宽 480 像素、高 352 像素,单色绿透明屏,安全区上下 12px、左右 16px。布局只有三层:
-
右上角常驻 HUD:关键字、比分、倒计时、本地模式标签;
-
中间主区域:模式列表、难度列表、AI 当前句、状态提示、结算比分;
-
底部一行提示:当前可用操作。
单色屏没有颜色层级可用,只能靠字号、透明度、边框和留白区分主次。关键字用 22px,正文 14px,辅助信息 10px;选中态不用背景色,用一个 8px 的圆点加边框。HUD 固定 120px 宽,正文区域最大 280px,避免在 playing 阶段压到右上角的信息。
判定链路
飞花令的判定顺序是:
-
诗句里有没有本局关键字(简单模式查同音字表,普通模式严格匹配);
-
本局有没有说过(去掉空白后比较);
-
本地诗句库能不能找到出处;
-
本地找不到,调 LanguageModel 判定;
-
LM 超时或失败,降级为“含字且不重复即通过”,并在 HUD 上标“本地模式”。
这个降级策略比较宽松,严格说不能保证用户说的是真正的古诗。但在眼镜上,判定延迟比学术严谨更重要;标出“本地模式”是让用户知道这一局的判定精度下降了,而不是假装一切正常。
AI 出句也走类似的顺序:先按难度从本地库挑没出现过的含字句,挑不到再让 LM 生成,LM 也失败就从全库里兜底。简单模式用中小学必背句,普通模式放宽到唐宋经典。
难度设计
飞花令的简单模式允许同音字,普通模式严格匹配原文字。成语接龙的简单模式允许首字和尾字同音,普通模式要求同一个汉字。
同音字这块目前做得不算完整。飞花令只给少数几个关键字配了真正的异形同音字,比如“花”和“华”、“云”和“雲”,其他关键字基本还是严格匹配。成语接龙的同音分组覆盖得好一些,因为成语库的尾字相对集中。这是数据问题,不是逻辑问题,后面会继续补表。
四、AIUI 实现
项目结构不复杂:
诗词飞花令/
app.json
app.js
pages/
index/index.ink
idiom/idiom.ink
utils/
poetryLib.js
gameEngine.js
idiomLib.js
idiomEngine.js
voiceManager.js
workers/init.js
tests/regression_test.js
app.json 里注册两个页面,声明 RECORD_AUDIO 权限,并挂了一个 open 触发的 init worker。worker 的作用只是把关键字和诗词数量写进 storage 做缓存,写失败也不影响页面,因为页面本来就直接 import 数据模块。
Ink 页面
每个 .ink 文件由四块组成:script def 写页面配置,script setup 写页面逻辑,page 写模板,style 写样式。页面逻辑是一个对象,数据放在 data 里,读取用 this.data.xxx,更新用 this.setData()。这一点和常见的小程序框架不太一样,this.xxx 不会代理到 data 字段,刚开始写的时候很容易读到一个 undefined。
模板用 ink:if、ink:for、ink:key。有一个限制值得记一下:ink:for 里的 class 必须是固定字符串,不能拼表达式。所以选中态不能写成 class="option-row {{selected ? 'active' : ''}}",只能在行里放一个子元素,用 ink:if 控制那个圆点显不显示。
样式上也有几个坑:
-
display: flex默认方向是column,横向排列必须显式写flex-direction: row; -
border-top、border-bottom这种单侧边框会被忽略,要么用完整 border,要么单独放一个 1px 高的 view; -
letter-spacing、text-transform不在 Ink CSS 白名单里,写了不报错,但也不生效。
这些限制会逼着人把布局写简单。写完之后回头看,反而比堆一堆 CSS 更接近眼镜上真正需要的东西。
语音
语音部分封装在 utils/voiceManager.js,对外提供 speak、cancelSpeech、startListening、stopListening 和销毁方法。
ASR 用全局构造器 new SpeechRecognition(),语言设为 zh-CN,continuous = false,interimResults = false。中间结果在当前宿主上设 true 会直接报 NotSupportedError,所以只能等最终结果。ASR 侧的超时设成 25 秒,比一局的 20 秒长,避免用户还在想的时候识别先被掐掉。
TTS 用 speechSynthesis.speak(utterance, 'immediate'),返回一个 task,播报结束、出错、被中止都有回调。停止播报必须用 speechSynthesis.cancel(),wx.speech 那套 API 在这个环境里没有可用的停止方法。
ASR 和 TTS 是互斥的。播报的时候如果开着麦克风,眼镜会把 AI 自己的声音收进去。所以 speak() 一进来就先停 ASR,等播报结束再延迟 420ms 重开。这个 420ms 不是文档里的值,是实测下来比较稳的 echo guard。
倒计时也不是开局就启动,而是等 TTS 播完 AI 那句诗再启动:
// 播报结束后才启动倒计时和 ASR,避免 TTS 占用用户答题时间
onSpeakEnd() {
if (this.data.phase !== 'playing' || this.data.busy) return;
this._startCountdown();
this.voice.startListening();
this.setData({ asrActive: true });
}
看起来是小事,但如果不这么做,AI 念一句七言诗要两三秒,用户实际能用来想的时间就少了。眼镜上的交互,时间感比动画重要。
LanguageModel
LM 从 language-model 模块导入:
import { LanguageModel } from 'language-model';
用 LanguageModel.create() 建一个带 system prompt 的会话,判定时把关键字、难度、已用诗句、用户输入一起塞进 prompt,要求只返回 JSON。调用外面包了一层 10 秒超时,超时就降级到本地逻辑。页面卸载时调 destroyLMSession() 把会话销毁。
LM 在这里只做两件事:判定本地库覆盖不到的诗句,以及在本地库没有合适出句时生成一句。它不负责流程控制,也不直接决定胜负,这样即使模型不稳定,游戏也能继续跑。
五、交互与体验
一局飞花令的完整体验大概是这样:
-
进入页面,TTS 播“欢迎来到诗词飞花令,请选择游戏”;
-
模式页只有两个选项,方向键移动,单击确认,也可以直接说模式名;
-
难度页同样只有两个选项,选完进入对局;
-
AI 出第一句,屏幕中间显示诗句和出处,同时弹一张两秒的开局卡,写着关键字、难度、每轮限时;
-
卡片消失后进入 playing,TTS 念 AI 的诗,念完才开始倒计时和听写;
-
用户说完,屏幕进入判定,正确弹“正确”反馈卡,两秒后 AI 接下一句;错误或超时进结算;
-
结算页显示双方比分和一列指令,可以按键选,也可以直接说“再来一局”“换个字”。
几个细节是后来补的:
-
结算页的方向键去重会清空,避免上一阶段的最后一次方向键把结算页的第一次选择吃掉;
-
进入页面有 800ms 的 phantom key 保护,防止眼镜戴上瞬间的误触;
-
方向键的上下和左右做了 200ms 的 alias 去重,一次滑动不会连跳两格;
-
麦克风不可用时,提示“可用按键操作”,不把用户卡死在语音路径上;
-
判定走本地降级时,HUD 上会出现“本地模式”,不让用户误以为一切正常。
语音和按键不是两套流程,而是同一套状态机的两个入口。模式、难度、结算指令都既能说也能按;对局中的答题以语音为主,按键只保留跳过和退出。这样在嘈杂环境里不至于完全玩不了,也不会让界面同时出现两套操作提示。
六、调试与验证
开发主要是在 AIUI Studio 的预览和真机之间来回切。预览适合调布局和状态,真机才能验证麦克风、TTS、回声和按键。
踩过的坑不少,挑几个有代表性的:
TTS 停止没有现成 API。 一开始想用 wx.speech.stopTTS,后来发现这个方法不存在,cancelTTS、cancel 也没有。最后统一用 speechSynthesis.cancel(),同时把当前 task abort 掉。
TTS 的 onend 不总是可靠。 偶尔会不回调,导致 ASR 一直不重开。后来加了一个兜底 timer,按字数估算播报时长(约 280ms/字),超过两倍还没结束就强制收尾。主路径仍然用 task 的真实回调。
ASR 主动 abort 也会触发 onerror。 超时、暂停、销毁时我们主动调 abort(),宿主会回一个 error='aborted'。如果不忽略这个错误,页面会收到“超时”和“错误”两个回调,重复重启 ASR。现在 aborted 直接 return,由调用方自己处理后续。
倒计时和 ASR 超时容易打架。 页面倒计时是唯一的时间权威,ASR 超时只代表“这一轮没听到声音”,不应该直接判负。所以 ASR 超时后,只要倒计时还没到 0,就自动重听一次,不重置倒计时。这个顺序调了好几遍才顺。
状态和定时器要一起清。 onHide 里停 ASR、cancel TTS、清所有 timer;onUnload 里再 destroy voice 和 LM session。眼镜应用被系统切走的频率比手机高,漏清一个 timer,回来就可能出现两个倒计时同时跑。
测试方面,我写了一份回归脚本,覆盖判定、指令解析、难度一致性、数据完整性这些纯逻辑。它能跑的时候挺省事,但也有明显的局限:引擎层 import 了 language-model,在 Node 里直接跑会找不到模块,需要 mock;页面层的异步状态(TTS 回调、ASR 重听、卡片计时)很难用脚本模拟,最后还是得靠真机手测。这份脚本目前更像一个检查清单,还没做到完全自动化。
真机测试主要看几件事:一局能不能从开局走到结算;连续答对时 AI 会不会重复;TTS 和 ASR 会不会互相抢;断网时“本地模式”能不能正常降级;戴着眼镜走动时按键会不会误触。目前主流程能跑通,但还有一些收尾问题,比如语音选难度和按键选难度走了两条分支,前者还没接到成语接龙页;成语指令里“过”的匹配范围太宽,用户说“过目不忘”会被当成“跳过”。这些不是设计上的大问题,是收尾没做好,已经记在下一版的清单里。
七、成果与复盘
现在这个版本能完成的事情:
-
飞花令和成语接龙两个模式,各自有简单/普通两档难度;
-
语音完成选模式、选难度、答题、换字、再来一局、退出;
-
本地库优先判定,LM 兜底,失败时降级并明确标注;
-
常驻 HUD 显示关键字、比分、倒计时;开局卡、反馈卡、结算卡三种临时界面;
-
本地诗词库 86 条、成语库 140 条,20 个关键字,全部打包在应用内。
做这个项目最大的感受是:AIUI 写起来不像网页,更像在写一个很小的系统应用。屏幕尺寸、单色、按键、麦克风、TTS、前后台切换,每个约束都会直接改变交互设计。比如“倒计时什么时候开始”这种问题,在网页上可能无所谓,在眼镜上就会影响用户能不能答上来。
另一个感受是,语音应用最难的不是识别,而是“什么时候该听、什么时候该说”。TTS 和 ASR 必须严格排队,否则会自己听自己;判定和播报必须分开,否则用户会在等结果的时候被下一句打断;状态和定时器必须一起清,否则切走再回来就会乱。把这些顺序理顺之后,LLM 反而只是链路里的一环,不是全部。
后续打算做几件事:
-
把诗句库从 86 条扩到 300 条以上,补齐每个关键字的常用句,顺便把几条“标注了关键字但诗句里其实没有这个字”的数据修掉;
-
补全同音字表,让简单模式真的能容错,而不是只在少数关键字上生效;
-
把语音和按键的选择路径收敛成一条,避免两个入口走出不同结果;
-
把回归脚本里的
language-model做成可注入的 mock,让引擎层测试能在 CI 里跑; -
增加长局测试,看连续玩十几分钟后定时器和会话会不会泄漏。