mcpField
A
alibabacloud-liverecord-diagnosis

alibabacloud-liverecord-diagnosis

github.com/aliyun云与 DevOps28184 次安装1 天前更新
代码仓库

关于 alibabacloud-liverecord-diagnosis

用于排查阿里云 ApsaraVideo Live 录制故障的 Agent 技能，面向需要诊断录制、文件或回调问题的运维人员。它查询录制配置、直播流及回调记录，并给出修复建议，但不会代为修改配置。

主要功能

  1. 01检查录制内容与索引文件
  2. 02验证 OSS 和 VOD 录制配置
  3. 03排查录制回调设置与事件
  4. 04检查直播状态及音视频帧率
  5. 05依据查询结果提出诊断建议

适用场景

  1. 01直播流未生成录制文件
  2. 02录制文件缺少音频或视频
  3. 03未收到录制状态回调
  4. 04核对录制配置及直播流质量

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill alibabacloud-liverecord-diagnosis

安装后在 Claude Code 中输入/alibabacloud-liverecord-diagnosis确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
acceptance-criteria.md
api-response-examples.md
cli-installation-guide.md
diagnostic-report-template.md
error-codes.md
ram-policies.md
related-commands.md
verification-method.md

详细介绍

阿里云直播录制诊断 Skill

场景描述

此 Skill 为阿里云 ApsaraVideo Live 录制问题提供全面的诊断能力，帮助识别和排查以下问题：

  • 未录制直播流
  • 未生成录制文件
  • 录制文件不符合预期（缺少音频/视频、格式错误等）
  • 未收到录制回调或回调不正确
  • 其他与直播录制相关的问题

架构：ApsaraVideo Live + OSS/VOD + 录制配置 + 回调配置

诊断范围

范围内：

  1. 未录制直播流
  2. 未生成录制文件或录制文件不完整
  3. 录制文件缺少音轨或视频轨
  4. 录制回调问题（未收到回调、数据不正确）
  5. 录制配置验证
  6. 影响录制的流质量问题

范围外：

  • 与直播录制无关的问题（使用阿里云官方 AI 助手）
  • 编写/修改用户配置（用户必须自行通过控制台或 CLI 修改）

安装

预检查：需要 Aliyun CLI >= 3.3.3

运行 aliyun version 验证版本是否 >= 3.3.3。如果尚未安装或版本过低，请参阅 references/cli-installation-guide.md 获取详细安装说明。

预检查：需要更新 Aliyun CLI 插件

[MUST] 运行 aliyun configure set --auto-plugin-install true 以启用插件自动安装。 [MUST] 运行 aliyun plugin update，确保所有现有插件始终为最新版本。

安装 Live 插件：

aliyun plugin install --names live

身份验证

预检查：需要阿里云凭证

安全规则：

  • 绝不读取、回显或打印 AK/SK 值（例如，禁止使用 echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
  • 绝不要求用户在对话或命令行中直接输入 AK/SK
  • 绝不使用 aliyun configure set 和明文凭证值
  • 仅使用 aliyun configure list 检查凭证状态
aliyun configure list

检查输出中是否存在有效配置文件（AK、STS 或 OAuth 身份）。

如果不存在有效配置文件，请在此处停止。

  1. 从阿里云控制台获取凭证
  2. 在本会话之外配置凭证（在终端中运行 aliyun configure，或在 Shell 配置文件中设置环境变量）
  3. 返回并重新运行；在 aliyun configure list 显示有效配置文件后继续

RAM 策略

此诊断 Skill 需要以下 RAM 权限。完整的策略文档请参阅 references/ram-policies.md。

所需操作：

  • live:DescribeLiveDomainMapping - 查询域名映射
  • live:DescribeLiveStreamRecordContent - 查询录制内容
  • live:DescribeLiveStreamRecordIndexFiles - 查询录制索引文件
  • live:DescribeLiveRecordConfig - 查询录制配置
  • live:DescribeLiveRecordVodConfigs - 查询 VOD 录制配置
  • live:DescribeLiveRecordNotifyConfig - 查询回调配置
  • live:DescribeLiveStreamsOnlineList - 查询在线流
  • live:DescribeLiveStreamsPublishList - 查询流推流历史
  • live:DescribeLiveCenterStreamRateData - 查询流码率数据
  • live:DescribeLiveRecordNotifyRecords - 查询回调记录

[MUST] 权限失败处理： 在执行过程中的任何时刻，如果命令或 API 调用因权限错误而失败，请按以下流程处理：

  1. 阅读 references/ram-policies.md，获取此 SKILL 所需权限的完整列表
  2. 使用 ram-permission-diagnose Skill 指导用户申请所需权限
  3. 暂停操作，等待用户确认已授予所需权限

参数确认

重要：参数确认 — 执行任何命令或 API 调用前，必须先与用户确认所有可由用户自定义的参数（例如域名、流名称、应用名称、时间范围、地域 ID 等）。未经用户明确批准，不得假设或使用默认值。请注意，Alibaba Cloud Live API 或 CLI 可能使用 UTC 时区。调用 API/CLI 时，请将时间转换为用户的本地时区。

必需参数：

参数名称必需/可选说明默认值
live-stream-url必需要诊断的直播流 URL（用于提取 DomainName、AppName、StreamName）N/A
issue-description必需录制问题的说明N/A
time-range可选诊断时间范围（格式：YYYY-MM-DD HH:mm:ss，用户本地时区）过去 1 天（如果没有数据，则扩展到 7 天）
biz-region-id可选业务地域 IDCLI 配置中的默认地域

核心工作流

在核心工作流开始时（调用任何 CLI 之前）： [必须] 启用 AI-Mode — 执行 Agent Skill 必须启用 AI-mode。 在调用任何 CLI 之前，运行以下命令：

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-liverecord-diagnosis"
步骤 1：识别用户意图并验证信息是否完整

1.1 验证诊断范围

检查问题是否属于诊断范围：

  • 直播流未录制
  • 未生成录制文件
  • 录制文件不符合预期
  • 回调问题
  • 其他与录制相关的问题

如果问题超出范围，请礼貌地告知用户联系 Alibaba Cloud 支持或使用官方 AI 助手。

1.2 提取必需信息

从直播流 URL（例如 rtmp://example.com/live/stream123）中提取：

  • DomainName：主播放域名（例如 example.com）
  • AppName：应用名称（例如 live）
  • StreamName：流名称（例如 stream123）

1.3 确定时间范围

  • 如果用户提供了时间范围，则使用该范围。如果未指定年份，则默认为当前年份
  • 如果未提供，则默认为过去 1 天
  • 如果 1 天内未找到数据，则将范围扩展到 7 天

1.4 与用户确认参数

向用户展示提取的参数以供确认：

Diagnostic Parameters:
- Domain: play.example.com
- Application: live
- Stream: stream123
- Time Range: 2026-01-20T00:00:00Z to 2026-01-21T00:00:00Z

Please confirm these parameters are correct before proceeding.
步骤 2：查询域名映射和录制结果

必须执行本节中的步骤，以验证用户报告的问题。

2.1 查询域名映射

首先，查询域名映射以获取主播放域名：

aliyun live describe-live-domain-mapping \
  --domain-name <DomainName>

请参阅预期输出了解响应格式。提取主播放域名（Type: vhost），供后续查询使用。

2.2 查询录制内容

无论上一步的结果如何，都必须执行此步骤。查询指定时间范围内的录制内容。

aliyun live describe-live-stream-record-content \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

请参阅预期输出了解响应格式。

2.3 查询录制索引文件（OSS）

如果录制到 OSS，请查询索引文件：

aliyun live describe-live-stream-record-index-files \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

请参阅预期输出了解响应格式。

2.4 验证用户的问题

将查询结果与用户报告的问题进行比较：

  • 如果存在录制文件，但用户表示没有录制内容 → 问题可能出在访问或播放方面
  • 如果未找到录制文件 → 继续执行步骤 3，检查配置
  • 如果存在录制文件但不完整 → 在步骤 5 中检查流质量
步骤 3：查询录制配置

录制到 VOD/OSS 的配置可能会对应用名称、流名称使用通配符（*）匹配。如果存在多个配置，请使用匹配度最高的配置。

3.1 查询录制到 OSS 的配置

aliyun live describe-live-record-config \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName>

响应格式请参见预期输出。

录制配置中的 OnDemand 标志会影响是否可以启动录制任务。取值如下：

  • 0：自动录制
  • 1：调用通知配置中的 OnDemandUrl，以确定是否应启动录制
  • 7：手动录制，用户需要调用 RealTimeRecordCommand OpenAPI 手动开始或停止录制

验证清单：

  • ✅ 存在适用于该流的配置
  • ✅ OssBucket 和 OssEndpoint 正确
  • ✅ RecordFormat 包含所需格式（m3u8、flv、mp4）
  • ✅ OssObjectPrefix 配置正确

3.2 查询录制到 VOD 的配置

aliyun live describe-live-record-vod-configs \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName>

响应格式请参见预期输出。

验证清单：

  • ✅ 存在适用于该流的配置

3.3 诊断结论

  • 如果不存在配置：告知用户在开始推流前创建录制配置。请参见：https://help.aliyun.com/live/user-guide/live-stream-recording
  • 如果配置不正确：指出具体问题，并建议用户通过控制台或 CLI 更新配置。
  • 如果配置正确：继续检查回调配置。
  • 如果 OnDemand 为 7：继续检查直播流信息；如果存在直播流，提醒用户调用 RealTimeRecordCommand OpenAPI。
步骤 4：查询回调配置

如果用户的问题与回调无关，请跳过此步骤。

4.1 查询录制回调配置

aliyun live describe-live-record-notify-config \
  --domain-name <PlaybackDomain>

响应格式请参见预期输出。

验证清单：

  • ✅ 已配置 NotifyUrl（回调必需）
  • ✅ 已启用 NeedStatusNotify（用于状态回调）
  • ✅ 已配置 OnDemandUrl（用于按需录制）

4.2 诊断结论

  • 如果缺少 NotifyUrl：告知用户配置回调 URL。
  • 如果存在 NotifyUrl，但 NeedStatusNotify 为 false：建议启用 NeedStatusNotify，以接收状态回调。
  • 如果配置正确：继续检查流信息。
步骤 5：查询直播流信息

5.1 查询在线流

检查该流当前是否在线：

aliyun live describe-live-streams-online-list \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName>

响应格式请参见预期输出。

5.2 查询历史流推送记录

检查历史推送记录：

aliyun live describe-live-streams-publish-list \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

响应格式请参见预期输出。

5.3 查询流速率数据（音频/视频帧率）

如果存在在线流或推送流记录，请检查音频和视频帧率，以识别质量问题：

aliyun live describe-live-center-stream-rate-data \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime>

响应格式和分析指南请参见预期输出。

5.4 诊断结论

  • 如果未找到推送记录：告知用户确认流是否推送到了正确的 URL：rtmp://<push-domain>/<app-name>/<stream-name>
  • 如果检测到流质量问题（例如 AudioFrameRate=0）：建议检查推流源的音频/视频编码是否正确。
  • 如果流信息正常：继续检查回调记录。
步骤 6：查询录制回调记录

6.1 查询录制回调事件

查询回调记录以识别录制问题。

如果用户的问题与录制回调有关，则无论之前步骤的结果如何，都必须查询回调记录。

aliyun live describe-live-record-notify-records \
  --domain-name <PlaybackDomain> \
  --app-name <AppName> \
  --stream-name <StreamName> \
  --start-time <StartTime> \
  --end-time <EndTime> \
  --page-size <PageSize, e.g. 20> \
  --page-number <PageNumber, e.g. 1>

响应格式请参见 预期输出。

6.2 分析回调事件

录制事件类型：

  1. record_started - 录制成功开始
  2. record_paused - 录制已暂停／停止
  3. record_error - 发生录制错误
  4. transformat_error - 转码错误（适用于 MP4/FLV）

有关详细错误代码、解决步骤和诊断结论，请参见 references/error-codes.md。

6.3 诊断结论

根据回调事件识别错误代码，并按照 references/error-codes.md 中的说明解决问题。

如果未发现错误：

✅ No recording errors found in callback records.

If you're still experiencing issues, please provide more details about the specific problem.
步骤 7：生成诊断报告

完成所有诊断步骤后，使用 references/diagnostic-report-template.md 中的模板生成一份完整报告。

报告应涵盖：

  1. 流信息（域名、应用、流、时间范围）
  2. 每个步骤的诊断结果（域名映射、录制内容、配置、回调、流、质量、事件）
  3. 根因摘要
  4. 所需操作
  5. 建议的后续步骤

[MUST] 在每个退出点禁用 AI-Mode — 无论出于任何原因，在发送最终回复前，都必须先禁用 AI-mode。此要求适用于所有退出路径：工作流成功、工作流失败、错误／异常、用户取消、会话结束，或任何不会再执行 CLI 命令的场景。 AI-mode 仅用于 Agent Skill 调用场景，并且在技能停止运行后绝不能保持启用状态。

aliyun configure ai-mode disable

成功验证方法

完成诊断工作流后：

  1. 验证录制配置：检查录制配置是否存在且正确
  2. 验证回调配置（可选）：如果用户的问题与回调有关或有必要，检查是否已配置回调 URL
  3. 验证流状态：检查流是否已发布
  4. 验证回调记录：检查是否存在错误事件
  5. 验证录制文件：检查 OSS 或 VOD 中是否存在文件

有关详细验证步骤和命令，请参见 references/verification-method.md。

清理

此诊断技能不会创建任何资源，因此无需清理。

注意：此技能为只读，不会修改任何配置。如果需要更改配置，用户必须通过控制台或 CLI 更新。

最佳实践

  1. 始终先验证域名映射 - 确保查询的是正确的播放域名
  2. 使用合适的时间范围 - 先从 1 天开始，必要时扩展到 7 天
  3. 在流开始前检查录制配置 - 推流前必须创建录制配置
  4. 启用状态回调 - 设置 NeedStatusNotify=true，以接收详细的录制事件
  5. 定期监控回调事件 - 检查错误事件，以便及早发现问题
  6. 验证 OSS 权限 - 确保 ApsaraVideo Live 有权访问 OSS 存储桶
  7. 检查流质量 - 监控音频／视频帧率，确保编码正常
  8. 使用正确的域名类型 - 录制 API 需要主播放域名，而非推流域名
  9. 等待录制片段完成 - 录制内容会在片段时长结束后写入（例如 3600 秒）
  10. 先使用简单的流进行测试 - 在测试复杂场景前，先使用基础流验证配置

参考链接

参考文档描述
references/ram-policies.md此技能所需的完整 RAM 权限
references/related-commands.md此技能使用的完整 CLI 命令列表
references/verification-method.md详细的验证步骤和命令
references/error-codes.md完整的录制错误代码及解决方法列表
references/cli-installation-guide.mdAlibaba Cloud CLI 安装和配置指南
references/api-response-examples.md诊断命令的 API 响应格式示例
references/diagnostic-report-template.md诊断报告模板和示例

其他资源

评论

支持 Markdown