# Query Record Skill

> Query Record Skill

- Skill: `ahang1598/query-record-skill` (Agent Skill)
- Install (CLI): `npx get-skill add ahang1598/query-record-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahang1598/query-record-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ahang1598 (https://skillmd.com/u/ahang1598)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/ahang1598/query-record-skill

---

# 观影历史记录查询Skill

## 触发关键词

### 正向语料（可正常查询）

**触发判断**：使用 `trigger-phrases.js` 的 `shouldTriggerQuery(userInput)` 函数

- 返回 `{ shouldTrigger: true }` 时触发查询
- 返回 `{ shouldTrigger: false, reason: "..." }` 时不触发并提示

> **注意**：
>
> 1. MateTV仅支持华为视频的观影记录查询，不支持第三方应用的观影记录
> 2. 异常场景，仅答复用户，禁止打印分析过程和原因

## 设备识别与多设备处理

### 设备过滤规则（重要）

**MateTV设备判断**：通过 `mate-tv-utils.js` 脚本的 `isMateTV(prodId)` 函数判断设备是否为MateTV

1. **多设备查询时**（用户未指定具体设备）：

   - 遍历用户绑定的所有 `09C`类设备
   - **isMateTV(prodId)返回true**：**并行发起POST请求**查询，并行轮询GET结果
2. **单设备查询时**（用户指定了具体设备名）：

   - 遍历用户的设备列表，看是否有用户指定的设备，若没有则告知用户该设备不存在
   - 仅查询用户指定的单个设备
   - **若isMateTV(prodId)返回false**，使用 record-parser.js 脚本的buildUnsupportedDeviceNotice(deviceName)方法获取提示并告知用户
   - 支持用户模糊描述设备（如"客厅的屏"、"卧室大屏"），需匹配合法设备名
3. **多维度设备描述**：

   - 位置描述：客厅MateTV、卧室大屏、主卧智慧屏
   - 组合描述：客厅智慧屏的前3条、客厅看过的记录
4. **角色查询流程**：

   - 支持按角色（家长/儿童）筛选历史记录
   - 通过 `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，开启授权" |

## 查询流程

**只允许打印步骤标题，禁止打印具体内容和脚本内容**

### 第一阶段：获取设备列表（不需要打印）

```bash
# 查询账号下所有智慧屏设备（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 | 角色名称（如"爸爸"、"妈妈"、"孩子"） |

**角色查询策略**：

1. **用户指定角色**：遍历 `roleInfoList`，匹配用户指定的角色名对应的 `roleId`
   - **匹配成功**：记录该设备的 `roleId`，用于后续POST请求
   - **匹配失败**：提示用户"未找到该角色，可能原因：1. 该角色未注册，请先去智慧屏的智慧识人应用中注册角色；2. 如果已注册，请确认该角色在**智慧屏**上已开启小艺Claw授权，路径：设置 > 小艺 > 智慧识人 > 智慧识人设置 > 信息共享 > 选择角色 > 小艺Claw，开启授权"，**停止查询**
2. **用户未指定角色**（具体影片查询场景）：
   - 获取该设备的所有角色列表 `roleInfoList`
   - 对每个角色分别执行第三、四阶段的POST+GET查询
   - 每个角色都需要从头开始遍历所有分页，查找目标影片
   - 示例：用户问"昨天西游记是谁看的"，需要查询"爸爸"、"妈妈"、"孩子"每个角色的所有分页记录
3. **多设备场景**：若指定角色在多台MateTV设备上都存在，需询问用户选择查询哪台设备的观影记录

### 第三阶段：并行发起POST请求

```bash
# 多设备时并行执行所有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结果

```bash
# 每设备独立执行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条），满足条件停止查询

**具体影片查询分页逻辑**（当用户查询具体影片时，如"昨天西游记是谁看的"）：

1. **影片匹配判断**：在第四阶段轮询时，检查返回的mediaRecordList中是否包含用户指定的影片
2. **分页遍历策略**：
   - 首次POST请求使用pageIndex=0
   - GET返回后检查是否找到目标影片
   - 若未找到目标影片且 totalPages > pageIndex + 1，使用pageIndex+1继续查询
   - 累加每次返回的mediaRecordList，直至找到目标影片或达到totalPages上限
3. **角色循环**：对每个角色分别执行上述分页查询，每个角色都需要从头开始遍历所有分页
4. **查询终止条件**：
   - 找到目标影片：停止查询，返回该角色的观看记录
   - 全部角色都查完且未找到：提示用户"未找到该影片的观看记录"
5. **示例**：用户问"昨天西游记是谁看的"
   - 先查询角色列表（爸爸、妈妈、孩子）
   - 对"爸爸"角色：pageIndex=0查第1页，未找到西游记，pageIndex=1查第2页，以此类推，直到找到西游记记录或最后一条记录，停止查询
   - 对"妈妈"和"孩子"角色：因已找到，跳跃式查询（先查最后一页确认是否有，无则查中间页）

### 第五阶段：汇总展示

- 按设备顺序逐一展示查询结果
- 每个设备使用独立表格展示

**数据解析**：使用 `record-parser.js` 脚本解析原始数据

```bash
# 解析单设备观影记录
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`的数据为未成年人模式下的观影记录

1. **表格标题**：

   - `{设备名称}`上 `华为视频`的最近观影记录如下：
2. **排序规则**：按观看时间顺序由**近至远**展示
3. **数量限制**：

   - **用户未指定查询个数时**：严格限制每个设备最多展示5条**非未成年人模式**下的记录
   - **用户指定数量时**：按指定数量展示，展示内容**不包含**未成年人模式下的观影记录
4. **多设备展示**：

   - 每个设备使用独立表格展示
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%     |

**查询限制说明**：

1. 未指定条数查询时（pageIndex=900）：使用 `buildQueryLimitNotice()` 返回提示"仅查询最近五条历史记录数据"，并展示在表格下方

**不支持查询的设备说明**：

1. 非MateTV设备提示：`buildUnsupportedDeviceNotice(deviceName)`
2. 原始数据为空数据`{}`或解析失败提示：`buildParseErrorNotice(deviceName)`
3. 解析后的数据存在hasMinorMode为true时提示：`buildMinorModeNotice()`

## ⚠️禁止展示的信息

**严禁打印/展示的内容**：

1. 设备信息：prodId、devId、设备型号等
2. 原始数据或中间过程数据
3. 返回数据中的任何字段名和字段值（如roleId、pageIndex、totalRoles、mediaRecordList等）
4. 用户标识信息：userId、用户id、roleId等

**执行命令时禁止使用 `--verbose` 参数**，因为verbose日志会打印设备ID等信息

**执行流程要求**：

- 执行设备查询命令时**不带 `--verbose`**
- 执行控制命令时**不带 `--verbose`**
- 仅在排查问题时临时启用，排查完毕必须移除verbose参数

