主题
系统指令
系统指令是平台预置的通用控制指令,所有企业开箱可用,无需在平台上配置,只需要设备端实现对应接口即可让用户触发。
关于「指令 vs 技能」的边界,详见 指令库总览。
1. 系统指令与技能的差异
- 技能:AI 理解用户意图后,生成一段文字回复;
- 系统指令:AI 识别用户意图后,既下发一条控制命令给设备执行,同时也生成一段文字回复给用户。
举个例子:
- 技能:用户说「天空为什么是蓝色的」 → AI 生成一段科普文字回复;
- 指令:用户说「音量调大」 → AI 一方面告诉设备「把音量调大」,另一方面回复用户「好的,已经帮你把音量调大了」。
因此,多数系统指令都需要设备端配合开发——设备需要能接收并执行平台下发的指令。唯一的例外是 设备码查询:云端识别意图后直接生成 TTS 音频回流,端侧无需任何改造。
📌 系统指令 vs 自定义指令的挂载方式差异
- 系统指令(本篇的电量查询、音量调节、退出对话、设备码查询):在应用编辑页点击「添加指令」直接选中即可生效,无需挂载 AIoT 指令控制 技能。
- 自定义指令集:需要在应用中挂载 AIoT 指令控制 技能,平台才会走「型号→指令集→指令」的建模路径识别并下发。
详见技术手册 §6.6.6 指令选择与自定义。
2. 电量查询
当用户询问设备还剩多少电时,AI 识别后下发电量查询指令,设备端返回当前电量信息。
| 项目 | 内容 |
|---|---|
| 指令编码 | CHECK_BATTERY |
| 触发说法示例 | 「还剩多少电」「电量还有多少」「电池怎么样了」 |
| 需要提取的信息 | 无 |
| 设备端开发 | 必须——设备端需实现电量上报接口,平台下发查询指令后设备返回当前电量 |
🔌 端侧协议引用:平台通过
CALL_SKILL_EVENT事件下发指令,设备端接收并回执电量数据。事件结构与建模细节见技术手册 §6.1 IOT 设备控制 与 §6.6.6 指令下行示例。
3. 音量调节
当用户要求调整设备音量时,AI 识别具体的调节方式,下发对应的音量控制指令给设备执行。
支持的调节方式
| 指令 | 编码 | 触发说法示例 | 需要提取的信息 |
|---|---|---|---|
| 音量调大 | VOLUME_UP | 「音量加大」「把音量调高」「声音再大些」 | 无 |
| 音量调小 | VOLUME_DOWN | 「音量小点」「音量降低」「把音量调小」 | 无 |
| 音量调到 XX | VOLUME_SET | 「音量调到 30%」「设成 50% 的音量」「声音调到 70」 | 需要提取具体数值(如 30 / 50 / 70) |
| 音量调到最大 | VOLUME_MAX | 「音量最大」「声音开到最大」「音量拉满」 | 无 |
| 音量调到最小 | VOLUME_MIN | 「音量最小」「调到最低音量」「音量降到最低」 | 无 |
关于「音量调到 XX」的数值提取
当用户说「音量调到 30%」时,AI 需要从这句话中提取出具体的目标数值(30),然后连同指令一起下发给设备。这是音量调节中唯一需要提取额外信息的指令。
| 项目 | 内容 |
|---|---|
| 设备端开发 | 必须——设备端需支持接收音量控制指令并执行 |
🔌 端侧协议引用:音量五种编码(
VOLUME_UP/VOLUME_DOWN/VOLUME_SET/VOLUME_MAX/VOLUME_MIN)复用CALL_SKILL_EVENT下发通道,数值型「音量调到 XX」在事件 payload 里携带具体数值。事件结构与三维正交建模细节见 §6.1 IOT 设备控制。
4. 退出对话
当用户明确表达想要结束与 AI 的对话、不想再聊了时,系统下发退出对话指令,设备终止当前对话会话。
触发条件
必须同时满足以下两个条件:
- 用户使用了明确的终止性动词或短语(如「退出」「结束」「停止」「关闭」「不聊」);
- 表达的对象是「对话」本身(如「对话」「聊天」「说话」「讲」「聊天/对话模式」「你」)。
核心公式:退出对话 = 终止动词 + 对话对象,二者缺一不可。
典型触发说法
- 「退出对话」「结束对话」「关闭对话」
- 「不想聊了」「不想跟你聊了」
- 「不和你聊了」「不说了」
- 「不要说话了」「闭嘴」
- 「别说话了」
- 「拜拜」「再见」(含明确告别语义)
🔌 端侧协议引用:退出对话触发后设备从「对话态」切换到「空闲态」,音频上下行链路关闭。设备状态机(空闲态 / 对话态 / 播放阶段等)完整定义见技术手册 端侧程序设计详解 · 设备状态机。
5. 设备码查询
当用户向设备索要或询问「设备码 / 反馈码 / 七位码 / 设备编号」时,平台识别意图后为该设备生成或返回一个 7 位纯数字短码,并直接通过 TTS 播报给用户,便于用户在反馈问题时口述、记录、输入——避免用户念那一长串 32 位十六进制的 botid。
| 项目 | 内容 |
|---|---|
| 指令编码 | 由云端内部处理,不下发到端侧 |
| 触发说法示例 | 「给我一个设备码」「设备码是多少」「你的反馈码是什么」「告诉我设备编号」 |
| 需要提取的信息 | 无 |
| 设备端开发 | 不需要——本指令是系统指令中的特例,云端识别意图后直接生成 TTS 音频回流,走标准对话音频通道,端侧只要能正常播 TTS 就行(与 查天气、闲聊 同链路) |
⚡ 与本篇其他 3 个系统指令的关键差异:完全无需端侧配合开发
电量查询 / 音量调节 / 退出对话都需要端侧实现对应接口(接收
CALL_SKILL_EVENT、执行硬件动作、上报回执)。设备码查询是唯一的例外——短码由云端直接生成,答案通过 TTS 走标准对话音频通道下发。端侧只要能正常播 TTS 就行,不用新增任何事件、协议或字段。
5.1 为什么需要设备码
设备原始标识 botid 是 32 位十六进制字符串(例如 abff7373ec214fba8e9066359baafd17)——长度过长,用户在反馈问题时难以口述、难以记录、难以输入,运营侧核对成本高。
「设备码查询」为每台设备提供一个 7 位纯数字短码,与 botid 一一绑定,用户按需触发即可获取,专门用于:
- 用户反馈问题:向客服 / 运营口述这一串 7 位数字即可,不用抄那一长串十六进制
- 运营反查设备:运营在设备管理中按短码 → 一键定位对应设备与产品(见下方 §5.4 运营侧:短码反查设备)
5.2 用户怎么触发
用户在与设备对话时,用自然语言索要或询问设备码即可触发,平台会识别并按需生成 / 返回。
典型说法示例:
| 场景 | 用户可以怎么说 |
|---|---|
| 索要设备码 | 「给我一个设备码」「设备码是多少」「把设备码给我」「我要设备码」「发个设备码」 |
| 询问设备码 | 「你的设备码是多少」「你的设备码是什么」「告诉我你的设备码」「你有设备码吗」 |
| 其他等价说法 | 「给我反馈码」「我的七位码是多少」「告诉我设备编号」「你的编号是多少」「报个反馈码给我」 |
不会触发(会走其他技能 / 闲聊):
- 用户提到的是验证码 / 扫码 / 支付码 / 二维码等与设备识别码无关的「码」——例如「验证码收到了吗」「扫码支付」「发个二维码」
- 用户问的是知识性问题——例如「二维码怎么生成」「条形码是什么原理」,会走知识问答
- 用户只是陈述或评价、没有明确索要——例如「这个码好长啊」「我记得有个编号」
5.3 工作方式
用户语音 → 云端(意图识别) → 短码生成 tool → 云端 TTS 直接播报 7 位数字云端做完全部事情:
- 意图识别:识别用户是否在索要 / 询问设备码
- 短码生成与绑定:首次触发时按规则生成 7 位纯数字 → 经过唯一性校验 → 与该设备的
botid绑定并持久化 - 返回与复用:再次触发时直接返回已绑定的短码(不会生成新的)
- 组织播报话术:云端直接生成 TTS 音频,通过标准对话音频通道回流给设备
端侧要做什么:什么都不用做——只要能正常播 TTS 的设备,添加本指令后即可开箱使用。
短码规则:
- 一台设备一个短码:与
botid一一绑定,同一台设备多次触发返回的是同一个短码 - 全局唯一:短码在系统内全局唯一,生成时冲突则重新生成直到唯一
- 持久化:一旦生成即永久保存,不会因为设备重启、应用切换而变化
5.4 运营侧:短码反查设备
用户反馈问题时会口述这个 7 位短码,运营在 设备管理 中可以通过短码一键反查设备:
- 入口:「设备管理」→ 顶部「短码查询」按钮
- 输入:7 位纯数字短码
- 输出:该短码绑定的设备详情(
botid、所属应用、设备名称、SN 编码等) - 异常:短码不存在时提示「未找到对应设备」
详细操作截图与流程见 设备管理 · 短码查询。
5.5 Q&A
Q1:设备端到底要不要开发?不用。云端识别意图后直接生成 TTS 音频回流,与用户问「今天天气怎么样」的链路完全一致。端侧只要能正常播 TTS 就能用。
Q2:同一台设备,今天问一次、明天问一次,短码会一样吗? 一样。短码与 botid 一对一绑定,一旦生成就持久化,同一台设备任意时刻查询返回的都是同一个 7 位数字。
Q3:短码为什么是 7 位纯数字,不是 6 位或 8 位? 在可容纳的设备量级(千万级)和用户口述记忆负担之间取的平衡点——6 位数字容量不足以覆盖全量设备,8 位对用户记忆和口述都偏长,7 位是当前的最佳折中。
Q4:两台不同设备的短码会重复吗? 不会。短码在全平台全局唯一,生成时做唯一性校验,冲突则重新生成直到唯一。
Q5:短码泄露有什么风险? 短码本身只是识别码,不是凭证——只能用于运营反查设备信息,不能用来登录、控制设备或修改配置。风险等同于告诉别人一个设备的名字。
Q6:短码可以修改吗? 当前不支持用户 / 运营主动修改短码。如需重置,请联系平台管理员。
6. 指令与技能对比总结
| 对比项 | 技能 | 指令 |
|---|---|---|
| AI 做什么 | 理解意图 → 生成文字回复 | 识别意图 → 下发控制命令 |
| 是否需要设备配合 | 不一定 | 通常必须(设备码查询是特例,无需端开) |
| 典型场景 | 查天气、闲聊、知识问答 | 音量调节、电量查询、退出对话、设备码查询 |
| 用户感知 | AI「说」了一段话 | 设备「做」了一个动作(设备码查询表现为「说」) |
7. 注意事项
- 多数系统指令都需要设备端开发支持——如果设备没有实现对应的接口,即使 AI 正确识别了意图并下发了指令,设备也无法执行。设备码查询是唯一例外:云端闭环,端侧无需改造。
- 电量查询需要设备主动上报电量数据——平台下发查询请求后,需要设备返回当前电量值。
- 退出对话的识别非常严格——为避免误判(如用户只是说「不想」被错误结束对话),系统要求必须同时包含终止动词和对话对象。
- 设备码查询的短码永久绑定——同一台设备多次触发返回的是同一个 7 位数字,不会变;短码与
botid一对一,全局唯一。
8. 相关链接
- 系统指令直接在应用编辑页「添加指令」处选择即可,若需自定义硬件控制,请转至 自定义指令集——自定义指令集才需要挂载 AIoT 指令控制 技能;
- 让指令按设定时间自动触发,请参考 定时指令;
- 想让设备执行指令时完全静默,请参考 静默指令;
- 端侧协议全景:§6.1 IOT 设备控制 · §6.6.6 指令选择与自定义 · 端侧程序设计详解。