6.5 闹钟设置接入

闹钟是语音智能体的核心指令类能力之一：用户通过语音"设个明早七点的闹钟"，系统侧完成意图理解、时间换算、判重/冲突/容量校验后，通过 CALL_SKILL_EVENT 下发已校验、参数已就绪的指令事件，端侧负责执行、管理ID、触发响铃、触发后处理、回传结果。

6.5.1 整体链路

关键链路职责：智能体 负责语言理解与时间换算；闹钟工具 负责闹钟判重/匹配/冲突/容量校验与查询过滤；端侧 负责最终执行、管理ID、触发响铃、触发后处理、回传结果。

端侧主要实现以下功能：

1. 指令执行（收到 event → 增/删/改闹钟数据）
2. 状态上报（把当前闹钟列表上报云端，供工具查询/校验）
3. 触发与后处理（到点响铃、响铃表现、触发后清理）

闹钟有普通闹钟、间隔提醒等闹钟类型，如果不支持某类闹钟，需要在端侧做逻辑，回复固定话术，比如“暂不支持设置这类型的闹钟哦”。 端侧收到的是已校验、参数已就绪的指令事件，无需再做时间换算或判重。 闹钟个数限制等能力边界由端侧自己判断处理。

6.5.2 下行事件结构

端侧通过既有事件通道接收 CALL_SKILL_EVENT下行事件消息，其中eventData.data结构：

{
  "domain": "alarm",
  "instructions": [
    {
      "type": "normal_alarm | interval_reminder",
      "operation": "create | delete | delete_all",
      "params": {}
    }
  ]
}

字段	类型	必选	说明
domain	string	是	固定 "alarm"，保留用于未来多域区分
instructions	array	是	指令数组，一次可含多条，按数组顺序依次执行
instructions[].type	string	是	闹钟类型：normal_alarm（普通闹钟）/ interval_reminder（间隔提醒）
instructions[].operation	string	是	操作类型：create / delete / delete_all
instructions[].params	object	是	操作参数，结构随 type + operation 变化（见下文各节）

• 修改场景由上游拆成 [delete, create] 两条指令，端侧顺序执行（先删后建）。
• 删多个或组合场景用多条指令。

新建 / 按内容删除闹钟 示例（点击展开）

新建一个明天早上8点的闹钟（op=create）：

{
  "msg": "端侧事件下发",
  "data": {
    "domain": "alarm",
    "instructions": [
      {
        "type": "normal_alarm",
        "operation": "create",
        "params": {
          "time": {
            "hour": 8,
            "minute": 0
          },
          "date": "2026-08-05",
          "repeat": {
            "mode": "single"
          }
        }
      }
    ],
    "args": {
      "time": {
        "hour": 8,
        "minute": 0
      },
      "date": "2026-08-05",
      "repeat": {
        "mode": "single"
      }
    },
    "intentCode": "create"
  },
  "type": "CALL_SKILL_EVENT"
}

按内容删除吃饭的闹钟（op=delete）：

{
  "msg": "端侧事件下发",
  "data": {
    "domain": "alarm",
    "instructions": [
      {
        "type": "normal_alarm",
        "operation": "delete",
        "params": {
          "match_by": "event",
          "event_content": "吃饭",
          "ids": [
            "a_02"
          ]
        }
      }
    ],
    "args": {
      "match_by": "event",
      "event_content": "吃饭",
      "ids": [
        "a_02"
      ]
    },
    "intentCode": "delete"
  },
  "type": "CALL_SKILL_EVENT"
}

6.5.3 普通闹钟（normal_alarm）

具体时间点，支持跨天、单次/每天/按周重复。

假设：今天 2026-07-10，闹钟设置规则示例如下

用户说	time	date	repeat	end_date	event_content
明早7点叫我	07:00	2026-07-11	single	—	—
每天早上7点	07:00	2026-07-10	daily	—	—
周一到周五7点	07:00	2026-07-13	weekly [1,2,3,4,5]	—	—
从明天起每天7点到下周五	07:00	2026-07-11	daily	2026-07-17	—
后天3点提醒我交报告	15:00	2026-07-12	single	—	交报告
4天后下午2点提醒我开会	14:00	2026-07-14	single	—	开会

新建闹钟参数（params）

字段	类型	必选	说明	默认值
time	{hour, minute}	是	响铃时间，24 小时制绝对值	—
date	string	是	起始日期，YYYY-MM-DD	—
repeat.mode	string	否	重复方式：single / daily / weekly	single
repeat.weekdays	int[]	条件必选	按周星期，仅 mode=weekly 出现。0-6，0=周日，1=周一…6=周六	—
end_date	string	否	结束日期，YYYY-MM-DD，仅重复闹钟带	—
event_content	string	否	到点播报内容。空/缺省 → 纯铃声；有值 → 铃声 + TTS	—

• 参数已就绪：时间/日期都是绝对值，判重/冲突/容量校验已由工具完成，端侧直接落库。

删除闹钟参数（params）

按条件删除，端侧在自身闹钟列表中匹配并删除所有命中项：

params一般包含ids与match_by两部分信息，端侧删除按下面优先级处理：

优先级 1：ids存在且非空 —— 按 ids 精确删除

• ids是服务端工具已经用闹钟列表与删除条件匹配好的命中闹钟 id 列表。
• 端侧直接按 id 删除对应闹钟，跳过二次匹配。
• 删除完成后，仍用params里的其他字段（event_content/time/date/period/repeat_type等） 组织回复话术，避免因端侧再次匹配与服务端结果不一致导致答复错位。

优先级 2：无ids（缺省或空数组）—— 端侧按match_by兜底匹配

• 出现场景：上报列表里存在无 id 的历史条目、老版本工具未回填、字段兼容期等。
• 端侧据match_by在自己的闹钟列表中匹配并删除所有命中项（命中多条全删，不追问）：

字段	类型	必选	说明
match_by	string	是	匹配方式：time / date / type / period / event
time	{hour, minute}	条件必选	match_by=time 时带，时 + 分都相等才命中
date	string	条件必选	match_by=date 时带，日期字符串相等才命中
repeat_type	string	条件必选	match_by=type 时带，daily / weekly 与闹钟 repeat.mode 相等才命中
period	string	条件必选	match_by=period 时带，闹钟 time.hour 落在时段区间内才命中
event_content	string	条件必选	match_by=event 时带，与闹钟 event_content 双向包含匹配

match_by	匹配字段	规则
time	params.time vs 闹钟 time	时 + 分都相等（仅普通闹钟有 time）
date	params.date vs 闹钟 date	日期字符串相等
type	params.repeat_type vs 闹钟 repeat.mode	daily/weekly 相等
period	params.period 时段 vs 闹钟 time.hour	落在时段区间内（见下）
event	params.event_content vs 闹钟 event_content	双向包含（模糊）匹配，跨两类

时段边界（period）：morning=5~12，afternoon=12~18，evening=18~24，night=0~5（左闭右开，按小时）。

event 双向包含：kw in content or content in kw。例：event_content="喝水" 命中"提醒我喝水"和"喝水"；空内容闹钟不参与匹配。普通闹钟和间隔提醒都参与 event 匹配。

• params带match_by，端侧据此在自己的闹钟列表中匹配并删除所有命中项。
• 命中多条全部删除，不追问；重复闹钟整条删（不支持只删某一天）。
• 未命中时按"无可删"安全处理（工具侧已做存在性校验，正常情况下都有命中）。
• 删除成功后回传被删闹钟的完整信息。

删除全部闹钟参数（params）

params 为 {}，清空全部闹钟。

6.5.4 间隔提醒（interval_reminder）

时段 + 间隔，仅当天内（0~23 点），不跨天、不重复到第二天，当天结束自动失效。

新建提醒参数（params）

字段	类型	必选	说明	默认值
period_start	{hour, minute}	否	时段开始	当前时间
period_end	{hour, minute}	是	时段结束	—
interval_minutes	int	是	间隔分钟	—
event_content	string	否	每次播报内容。空→纯铃声	—

• 跨天在规划层拦截（如"从今晚到明早"），不产生指令。

删除提醒参数（params）

• 无条件（params={}）→ 取消全部间隔提醒（不影响普通闹钟）。
• 有条件 params有值，如{match_by:"event", event_content:"喝水"} → 按内容删对应间隔提醒。
• 与普通闹钟一致：若params含非空ids，端侧优先按 ids 精确删除，其他字段仅用于生成回复。

6.5.5 闹钟列表上报（供云端查询/校验）

• 工具做查询、判重、删除匹配时，读取的是端侧上报到云端的闹钟列表。
• 通过端侧上行事件协议CLIENT_UPDATE_CHAT_CONTEXT(主动更新对话上下文事件)方式上报。
• 端侧需按下述结构上报当前全量闹钟，字段与 create 落库一致 + id/enabled。
• 每次更新该上行事件时，需要配置全量参数，如有设备状态和闹钟就需要上传status和alarms。

列表结构

在主动更新对话上下文事件配置kvData中，新增属性alarms 数组：

完整列表示例（点击展开）

{
  "mid": "1",
  "contentType": "ACTIVITY",
  "content": {
    "activityType": "CLIENT_UPDATE_CHAT_CONTEXT",
    "effectiveTimeMinutes": 5,
    "kvData": {
      "alarms": [
        {
          "id": "a_01",
          "type": "normal_alarm",
          "enabled": true,
          "time": {
            "hour": 7,
            "minute": 0
          },
          "date": "2026-07-28",
          "repeat": {
            "mode": "weekly",
            "weekdays": [1, 2, 3, 4, 5]
          },
          "end_date": "2026-08-01",
          "event_content": "交报告"
        }, {
          "id": "r_01",
          "type": "interval_reminder",
          "enabled": true,
          "period_start": {
            "hour": 9,
            "minute": 0
          },
          "period_end": {
            "hour": 18,
            "minute": 0
          },
          "interval_minutes": 30,
          "event_content": "喝水"
        }
      ]
    }
  }
}

字段要求

字段	类型	说明
id	string	端侧生成、跨查询稳定、唯一。删除/修改回传用它定位
type	string	normal_alarm / interval_reminder
enabled	bool	是否启用。判重/冲突/删除匹配只针对 enabled=true 的条目，禁用的不参与
weekdays	int[]	仅 weekly 带，0-6，0=周日
其余字段	—	同 create 对应字段

判重规则（工具侧）

• 普通闹钟重复 = time + repeat.mode（weekly 还需 weekdays 集合相等）+（单次还需 date）全部一致。
• 时间冲突 = 同 time 但重复性不同（单次 vs 重复），按需求文档提示用户是否替换。
• 容量上限由端侧/工具配置，达到上限返回容量已满话术。

时效

列表要及时反映真机状态：新建/删除/触发后清理都要更新上报，否则查询和删除匹配会与真机不一致。

6.5.6 触发与后处理

注意：云端只处理了增删查的数据变更，不含到点响铃与触发后处理，本节端侧必须实现。

响铃表现

• 普通闹钟到设定时间点触发，循环播放本地预置铃声，最长 15 分钟。event_content 非空时配合 TTS 播报。
• 间隔提醒在时段内每 interval_minutes 触发一次，循环播放铃声。event_content 非空时配合 TTS 播报。
• 铃声由品牌方预置，用户不可选，不在下发协议里，端侧自行决定用哪个铃声。

触发后处理

类型	触发后
普通闹钟 single	触发后清除该闹钟
普通闹钟 daily/weekly	保留，等待下次触发
间隔提醒	每次触发后继续计时，等待下次间隔
间隔提醒到达 period_end	自动失效，清除该任务
间隔提醒当天结束（23:59）	自动失效（不跨天）

• 凡是"清除/失效"，端侧都要同步更新上报闹钟列表。

6.5.7 回传结果

• 操作执行后，需全量同步更新对话上下文事件所有配置KVData，上报闹钟列表。
• 当操作成功时，发送上行事件消息：CLIENT_INPUT_TEXT_TO_SPEECH(发送文本内容，请求音频合成)， 云端TTS合成后，端侧接收流式TTS音频播放。

6.5.8 端侧能力清单（对照自查）

• 解析下行事件CALL_SKILL_EVENT的eventData.data.instructions，按序执行
• create：生成稳定 id、按 type 落库
• delete：优先按 ids 精确删除，无 ids 时再按 time/date/type/period/event 五种 match_by 兜底匹配，命中多条全删
• delete_all：全部删除
• 间隔提醒无条件 delete：删除全部间隔提醒
• 闹钟列表上报（含 id/enabled，weekdays 0=周日）
• 响铃表现（普通闹钟 15min/×5；间隔提醒 ×3）
• 触发后处理（单次清除/重复保留；间隔到期或当天结束失效）+ 同步更新上报
• 回传执行结果

下一步

• 回看指令事件:读 4.4 WebSocket语音通道 —— CALL_SKILL_EVENT 事件机制
• 对比 IOT 指令:读 6.1 指令与控制 —— IOT 控硬件 vs 闹钟控系统功能
• 其他场景:读 6.2 媒体资源接入 / 6.3 魔法打印接入 / 6.4 视觉对话接入