观影历史记录查询Skill
触发关键词
正向语料(可正常查询)
触发判断:使用 trigger-phrases.js 的 shouldTriggerQuery(userInput) 函数
- 返回
{ shouldTrigger: true }时触发查询 - 返回
{ shouldTrigger: false, reason: "..." }时不触发并提示
注意:
- MateTV仅支持华为视频的观影记录查询,不支持第三方应用的观影记录
- 异常场景,仅答复用户,禁止打印分析过程和原因
设备识别与多设备处理
设备过滤规则(重要)
MateTV设备判断:通过 mate-tv-utils.js 脚本的 isMateTV(prodId) 函数判断设备是否为MateTV
多设备查询时(用户未指定具体设备):
- 遍历用户绑定的所有
09C类设备 - isMateTV(prodId)返回true:并行发起POST请求查询,并行轮询GET结果
- 遍历用户绑定的所有
单设备查询时(用户指定了具体设备名):
- 遍历用户的设备列表,看是否有用户指定的设备,若没有则告知用户该设备不存在
- 仅查询用户指定的单个设备
- 若isMateTV(prodId)返回false,使用 record-parser.js 脚本的buildUnsupportedDeviceNotice(deviceName)方法获取提示并告知用户
- 支持用户模糊描述设备(如"客厅的屏"、"卧室大屏"),需匹配合法设备名
多维度设备描述:
- 位置描述:客厅MateTV、卧室大屏、主卧智慧屏
- 组合描述:客厅智慧屏的前3条、客厅看过的记录
角色查询流程:
- 支持按角色(家长/儿童)筛选历史记录
- 通过
roleInfo查询获取角色列表,匹配用户指定的角色名对应的roleId - 若用户未指定角色,使用
roleId: "all",返回所有角色的观看记录 - 若用户指定了角色但未匹配到,提示用户"未找到该角色,可能原因:1. 该角色未注册,请先去智慧屏的智慧识人应用中注册角色;2. 如果已注册,请确认该角色在智慧屏上已开启小艺Claw授权,路径:设置 > 小艺 > 智慧识人 > 智慧识人设置 > 信息共享 > 选择角色 > 小艺Claw,开启授权",停止查询
- 指定角色查询时:若多台MateTV设备都有该角色,需询问用户选择查询哪台设备的观影记录
异常处理
| 异常场景 | 处理方式 |
|---|---|
| MateTV关机 | 提示"设备已关机,无法查询观影记录" |
| MateTV无网络 | 提示"设备网络不可用,无法查询观影记录" |
| MateTV无历史记录 | 提示"暂无观影记录" |
| MateTV未授权 | 提示"该设备暂时不支持查询历史记录" |
| 查询超时(>60s) | 显示加载状态,超过60秒应返回结果 |
| 非MateTV设备(isMateTV返回false) | 在表格下方说明"{设备名} 暂不支持查询观影记录,仅Mate TV支持查询观影记录" |
| 角色未匹配 | 提示用户"未找到该角色,可能原因:1. 该角色未注册,请先去智慧屏的智慧识人应用中注册角色;2. 如果已注册,请确认该角色在智慧屏上已开启小艺Claw授权,路径:设置 > 小艺 > 智慧识人 > 智慧识人设置 > 信息共享 > 选择角色 > 小艺Claw,开启授权",停止查询 |
| 指定角色多设备 | 询问用户选择查询哪台设备的观影记录 |
| 返回数据中pageIndex = -1 | 提示"当前设备已开启未成年人模式,暂不支持查询观影记录" |
| 返回数据中pageIndex = -2 | 提示"该角色未开启信息共享授权,请在智慧屏上进入:设置 > 小艺 > 智慧识人 > 智慧识人设置 > 信息共享 > 查询角色名 > 小艺Claw,开启授权" |
查询流程
只允许打印步骤标题,禁止打印具体内容和脚本内容
第一阶段:获取设备列表(不需要打印)
# 查询账号下所有智慧屏设备(devType='09C')
node common-skill/bin/smarthome-claw.js get_devices_info \
--dev-type "09C"
禁止直接处理返回数据, 原始数据必须通过mate-tv-utils.js中filterMateTVDevices方法预处理
设备过滤:
- 用户未指定设备:通过
isMateTV(prodId)判断,函数返回true的设备进入查询,返回false但属于智慧屏类设备提示用户不支持查询观影记录 - 用户指定设备:仅对指定设备查询,若
isMateTV(prodId)返回false则提示用户不支持查询观影记录
第二阶段:查询角色信息get
前置条件:始终执行此阶段(用于具体影片查询时遍历角色)
角色查询:禁止直接处理getDeviceServiceSnapshot返回的原始快照数据,而是调用调用getDeviceServiceSnapshot后通过mate-tv-utils.js的getDeviceServiceInfo(data, devId, roleInfo)获取每台设备的角色信息列表
快照字段:
| 字段 | 说明 |
|---|---|
| totalRoles | 角色总数 |
| roleInfoList | 角色列表数组 |
| roleInfoList[].roleId | 角色ID |
| roleInfoList[].userName | 角色名称(如"爸爸"、"妈妈"、"孩子") |
角色查询策略:
- 用户指定角色:遍历
roleInfoList,匹配用户指定的角色名对应的roleId- 匹配成功:记录该设备的
roleId,用于后续POST请求 - 匹配失败:提示用户"未找到该角色,可能原因:1. 该角色未注册,请先去智慧屏的智慧识人应用中注册角色;2. 如果已注册,请确认该角色在智慧屏上已开启小艺Claw授权,路径:设置 > 小艺 > 智慧识人 > 智慧识人设置 > 信息共享 > 选择角色 > 小艺Claw,开启授权",停止查询
- 匹配成功:记录该设备的
- 用户未指定角色(具体影片查询场景):
- 获取该设备的所有角色列表
roleInfoList - 对每个角色分别执行第三、四阶段的POST+GET查询
- 每个角色都需要从头开始遍历所有分页,查找目标影片
- 示例:用户问"昨天西游记是谁看的",需要查询"爸爸"、"妈妈"、"孩子"每个角色的所有分页记录
- 获取该设备的所有角色列表
- 多设备场景:若指定角色在多台MateTV设备上都存在,需询问用户选择查询哪台设备的观影记录
第三阶段:并行发起POST请求
# 多设备时并行执行所有POST请求
# 单设备时单个执行
# roleId:用户指定角色时使用匹配到的roleId,未指定或未匹配时使用"all"
# pageIndex:用户指定数量时使用0,未指定数量时使用900,类似“全部|全量|所有”都属于指定数量
node common-skill/bin/smarthome-claw.js control_device \
--dev-id "xxx" \
--prod-id "xxx" \
--operation "POST" \
--sid "mediaRecord" \
--data '{"roleId":"匹配的roleId或all","pageIndex":用户指定数量时传0),未指定数量时传900}'
第四阶段:并行轮询GET结果
# 每设备独立执行GET轮询,最多重试2次
# 首次GET:POST后等待1s
# 第1次重试:间隔1s
# 第2次重试:间隔2s
# 总等待时间不超过5s
node common-skill/bin/smarthome-claw.js control_device \
--dev-id "xxx" \
--prod-id "xxx" \
--operation "GET" \
--sid "mediaRecord" \
--data '{}'
普通查询(用户未指定条数查询)
使用pageIndex=900查询,且无论返回的totalPage为多少,均不触发翻页逻辑,直接到第五阶段汇总展示
翻页逻辑(仅用户指定条数查询时):
- 首次查询POST请求使用pageIndex=0
- 首次GET返回后检查totalPages和当前返回总条数
- 若当前返回总条数 < 用户要求条数 且 totalPages > pageIndex,使用pageIndex+1继续查询
- 累加每次返回的记录数,直至满足用户要求的条数或达到totalPages上限
- 示例:服务端59条记录,用户要求20条,pageIndex=0返回10条,pageIndex=1再返回10条(累计20条),满足条件停止查询
具体影片查询分页逻辑(当用户查询具体影片时,如"昨天西游记是谁看的"):
- 影片匹配判断:在第四阶段轮询时,检查返回的mediaRecordList中是否包含用户指定的影片
- 分页遍历策略:
- 首次POST请求使用pageIndex=0
- GET返回后检查是否找到目标影片
- 若未找到目标影片且 totalPages > pageIndex + 1,使用pageIndex+1继续查询
- 累加每次返回的mediaRecordList,直至找到目标影片或达到totalPages上限
- 角色循环:对每个角色分别执行上述分页查询,每个角色都需要从头开始遍历所有分页
- 查询终止条件:
- 找到目标影片:停止查询,返回该角色的观看记录
- 全部角色都查完且未找到:提示用户"未找到该影片的观看记录"
- 示例:用户问"昨天西游记是谁看的"
- 先查询角色列表(爸爸、妈妈、孩子)
- 对"爸爸"角色:pageIndex=0查第1页,未找到西游记,pageIndex=1查第2页,以此类推,直到找到西游记记录或最后一条记录,停止查询
- 对"妈妈"和"孩子"角色:因已找到,跳跃式查询(先查最后一页确认是否有,无则查中间页)
第五阶段:汇总展示
- 按设备顺序逐一展示查询结果
- 每个设备使用独立表格展示
数据解析:使用 record-parser.js 脚本解析原始数据
# 解析单设备观影记录
node record-parser.js parse \
--device-name "客厅MateTV" \
--data '{"mediaRecordList":[...]}'
# 解析多设备观影记录
node record-parser.js parse-multi \
--data '[{"device":{...},"rawData":{...}},...]'
请求参数
| 参数 | 类型 | 说明 |
|---|---|---|
| roleId | 字符串 | 未明确角色使用"all",否则使用roleInfo查到的角色Id |
| pageIndex | 数字 | 用户指定数量时传0,未指定数量时传900 |
返回字段
| 字段 | 说明 |
|---|---|
| mediaRecordList | 观影历史记录列表 |
| totalPages | 总页数 |
显示格式
⚠️展示数据时,需要严格遵守下面的显示规范:
展示内容规范
userName字段中包含recordInMinorMode的数据为未成年人模式下的观影记录
表格标题:
{设备名称}上华为视频的最近观影记录如下:
排序规则:按观看时间顺序由近至远展示
数量限制:
- 用户未指定查询个数时:严格限制每个设备最多展示5条非未成年人模式下的记录
- 用户指定数量时:按指定数量展示,展示内容不包含未成年人模式下的观影记录
多设备展示:
- 每个设备使用独立表格展示
表格内容:通过
record-parser.js的解析函数获取,必须严格遵循以下格式
| 字段 | 格式要求 |
|---|---|
| 序号 | 数字,从1开始递增 |
| 影片名称 | 用 《》包裹,如 《示例影片》,禁止添加其他修饰 |
| 集数 | 格式为 第 X 集或 第 X 期,无集数时留空不显示任何内容 |
| 播放进度 | 格式为 XX%,如 75%、100%,playRate≤0时显示 不足1% |
⚠️严格禁止:
- 禁止在影片名称前后添加多余文字(如"电影:"、"片名:"等)
- 禁止在集数位置显示"无"、"无集数"等替代内容
- 禁止更改列顺序或增减列数
- 禁止添加额外列(如"观看时间"等)
呈现形式示例
{设备名称}上华为视频的最近观影记录如下:
| 序号 | 影片名称 | 集数 | 播放进度 |
|---|---|---|---|
| 1 | 《示例影片》 | 第 3 集 | 75% |
| 2 | 《示例影片》 | 第 2 期 | 100% |
| 3 | 《示例影片》 | 100% | |
| 4 | 《示例影片 2》 | 第 5 集 | 45% |
| 5 | 《示例影片 2》 | 第 4 集 | 100% |
查询限制说明:
- 未指定条数查询时(pageIndex=900):使用
buildQueryLimitNotice()返回提示"仅查询最近五条历史记录数据",并展示在表格下方
不支持查询的设备说明:
- 非MateTV设备提示:
buildUnsupportedDeviceNotice(deviceName) - 原始数据为空数据
{}或解析失败提示:buildParseErrorNotice(deviceName) - 解析后的数据存在hasMinorMode为true时提示:
buildMinorModeNotice()
⚠️禁止展示的信息
严禁打印/展示的内容:
- 设备信息:prodId、devId、设备型号等
- 原始数据或中间过程数据
- 返回数据中的任何字段名和字段值(如roleId、pageIndex、totalRoles、mediaRecordList等)
- 用户标识信息:userId、用户id、roleId等
执行命令时禁止使用 --verbose 参数,因为verbose日志会打印设备ID等信息
执行流程要求:
- 执行设备查询命令时不带
--verbose - 执行控制命令时不带
--verbose - 仅在排查问题时临时启用,排查完毕必须移除verbose参数