alibabacloud-bailian-videoanalysis

Bailian Video Analysis

此技能基于阿里云 Bailian Video Analysis 轻应用，提供视频分析功能。它使用 Bailian（QuanMiaoLightApp）API 进行智能视频理解，包括镜头分析、ASR 转录、标题生成、字幕提取和思维导图。

架构： CLI (Credential Chain) + OSS (File Storage) + Bailian Workspace + Quanmiao Video Analysis Service + Python SDK Scripts

---

输出语言策略

检测优先级： 用户输入语言 → 环境语言 → 默认：中文

适用范围： 所有面向用户的消息、摘要、错误说明和交互提示。

保留原始语言： 代码片段、API 响应、文件路径、技术标识符、HTTP 状态码。

---

安装

1. Python 依赖

python -m pip install -r scripts/requirements.txt
# On some systems, use pyhon3 instead of python

2. Alibaba Cloud CLI

预先检查：需要 Aliyun CLI >= 3.3.1 运行 aliyun version 确认版本是否 >= 3.3.1。如果尚未安装或版本过低， 请参阅 references/cli-installation-guide.md 查看安装说明。 然后**[必须]**运行 aliyun configure set --auto-plugin-install true，启用自动安装插件。

aliyun CLI 的 AI-Mode 配置

在此技能中使用 aliyun CLI 时，必须配置 AI-Mode 设置：

# 启用 AI-Mode（使用 CLI 命令前必须完成）
aliyun configure ai-mode enable

# 设置用于跟踪的 User-Agent（必需）
aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

# 将插件更新到最新版本（推荐）
aliyun plugin update

注意： 完成任务后，可以禁用 AI-Mode：

aliyun configure ai-mode disable

3. 重要前提：开通 Bailian 和视频分析服务

使用此技能前，必须先在 Alibaba Cloud Bailian 控制台开通视频分析服务！

1. 访问 Bailian Video_Analysis 页面
2. 点击 “付费开通” 按钮
3. 确认开通并等待服务生效（通常需要 1-2 分钟）

4. 重要前提：引导用户在 Alibaba Cloud Access Control 和 Bailian 中授予权限

使用此技能前，必须为先前配置的 AK 授予以下权限，否则调用会失败，并可能导致 403 错误

1) 授予 RAM 权限

所需 RAM 权限的完整列表和授权说明，请参阅 references/ram-policies.md。

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

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

2) 授予 Bailian 工作空间权限

1. 访问 Alibaba Cloud Bailian 权限管理
2. 如果 AK 对应的 RAM 用户不存在，请点击页面右上角的 “添加用户”，选择对应的 RAM 用户并点击确认以添加。
3. 配置后需要等待 30s 才会生效，请耐心等待片刻。

---

身份验证

预检查：需要 Alibaba Cloud 凭证

安全规则：

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

aliyun configure list

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

如果没有有效的配置文件，请立即停止。

1. 从 Alibaba Cloud Console 获取凭证
2. 在本会话之外配置凭证（在终端中运行 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 等待 aliyun configure list 显示有效配置文件后，返回并重新运行

---

参数确认

重要：参数确认——执行任何命令或 API 调用前， 确认用户提供或可自定义的参数（视频源、OSS 存储桶、OSS 对象键）。 系统自动解析的参数（workspace_id、默认 OSS 存储桶）无需明确确认， 除非用户想要覆盖它们。

参数	类型	描述	默认值 / 解析方式
video_source	必填	本地文件路径或可下载的视频 URL	N/A（用户必须提供）
workspace_id	自动解析	Bailian 工作空间 ID	自动检测（用户可覆盖）
ossBucket	可选	用于上传文件的 OSS 存储桶名称	自动检测第一个可用存储桶；用户可指定（例如 --ossBucket my-bucket）
ossObjectKey	可选	已上传文件的 OSS 对象键	/temp/quanmiao/YYYYMMDD/filename
expireSeconds	可选	临时 URL 过期时间（秒）	14400（4 小时）

确认流程：

1. 先自动检测：技能会在可能的情况下自动检测 workspace_id 和 ossBucket
2. 用户覆盖：如果用户想指定自定义值，使用前先确认
3. 本地文件还是 URL：确认用户提供的是本地文件路径还是公共 URL

---

核心工作流

⚠️ 关键：必须使用云 API——此技能必须使用 Bailian（QuanMiaoLightApp）API 进行视频分析。禁止使用本地工具（ffmpeg、whisper、OpenCV、ffprobe、mediainfo 等）。如果 API 调用因凭证或权限问题失败，请按照“权限失败处理”流程操作——不要回退到本地分析。

步骤 1：环境检查

运行 python scripts/check_env.py，验证：

• Python 软件包已安装
• 已通过默认凭证链配置凭证

如果 check_env.py 失败或返回 {"ready": false}：

• 缺少软件包 → 运行 python -m pip install -r scripts/requirements.txt
• 缺少凭证或凭证无效 → 按照“权限失败处理”流程操作：
  1. 阅读 references/ram-policies.md 了解所需权限
  2. 使用 ram-permission-diagnose 技能引导用户申请权限
  3. 等待用户确认后再继续
  4. 不要使用本地分析工具继续操作

预期输出： {"ready": true} 表示环境已正确配置。

第 2 步：获取 Workspace ID

不要预先询问用户 workspace_id。 始终先自动获取可用的工作空间：

aliyun modelstudio list-workspaces --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

工作空间选择逻辑：

• 返回单个工作空间 → 直接使用，无需提示用户
• 返回多个工作空间 → 显示编号列表，并按以下方式继续：
  1. 默认行为：自动使用列表中的第一个工作空间，避免不必要的交互
  2. 用户明确要求选择：如果用户说“让我选择工作空间”“显示工作空间列表”或类似的话，则展示完整列表并请用户选择一个
• 未返回工作空间 → 告知用户没有可用的 Bailian 工作空间，并引导他们前往 Bailian 控制台创建
• 在会话中记录用户的选择，避免重复询问

第 3 步：将文件(video_source)上传到 OSS

根据输入资源验证中输入的资源类型：

情况 A：用户提供了可下载的 URL → 验证 URL 是否可访问：使用适用于当前操作系统的方法测试 URL 是否可下载 → 跳过此步骤。在第 4 步中将 video_source 用作 file_url。

情况 B：用户提供了本地文件路径 → 自动检测 OSS bucket、将本地文件上传到 OSS，并获取用于第 4 步的临时 URL(file_url)：

• （1）自动检测或使用用户指定的 OSS bucket：
  • 如果用户指定了 --ossBucket <bucket_name>，则尝试使用该 bucket
  • 如果指定的 bucket 返回 403 AccessDenied 或 BucketAlreadyExists：不要自动切换到其他 bucket。应改为：
    1. 告知用户指定的 bucket 无法访问
    2. 按照 RAM Policy 部分中的权限失败处理流程操作
    3. 引导用户授予 OSS bucket 访问权限，或指定其拥有的其他 bucket
    4. 等待用户确认后再继续
  • 如果未指定 bucket，则自动检测第一个可用的 bucket

aliyun ossutil ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

• （2）将文件上传到 OSS：为上传的文件生成唯一的 key(oss_object_key)。

重要 - 上传路径限制：

• 默认路径：必须使用 /temp/quanmiao/YYYYMMDD/filename 格式（根据当前日期自动生成）
• 自定义路径：仅当用户明确指定自定义 oss_object_key 时才使用，否则始终使用默认路径
• 安全规则：除非用户明确要求，否则绝不将文件上传到 /temp/quanmiao/ 前缀之外的路径

aliyun ossutil cp <video_source> oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}

• （3）生成临时 URL：使用 ossutil sign 命令为上传的文件生成临时 URL。
  • --expireSeconds：默认 14400s（4 小时）；如需其他值，请先确认

aliyun ossutil sign oss://{oss_bucket}/{oss_object_key} --expires-duration {expire_seconds} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis --region {oss_region}

• （4）验证 URL 是否可访问：使用适用于当前操作系统的方法测试生成的 URL 是否可下载
  • 注意：验证时优先使用 GET 请求，而不是 HEAD 请求，因为某些 OSS 签名版本可能会拒绝 HEAD 请求。

推荐的 URL 可下载性验证方法：

• macOS/Linux：curl -L --connect-timeout 10 --max-time 30 -o /dev/null -w "%{http_code}" <file_url>（返回 HTTP 状态码）
• Windows：Invoke-WebRequest -Uri <file_url> -Method Head -TimeoutSec 30（PowerShell）

验证标准：

• HTTP 200 → URL 有效且可访问，继续第 4 步
• HTTP 403/404 → URL 已过期或无效，使用 ossutil sign 重新生成
• 其他错误 → 检查网络或 OSS 权限

步骤 4：提交视频分析任务

⚠️ 必须调用 API — 必须在 QuanMiaoLightApp 产品（版本 2024-08-01）上调用 SubmitVideoAnalysisTask。不要使用 videorecog、Mts 或任何其他产品。不要尝试本地分析。

API 选择检查清单 — 调用前，请确认：

• ✅ 产品：QuanMiaoLightApp（不是 videorecog，也不是 Mts）
• ✅ 版本：2024-08-01
• ✅ 操作：SubmitVideoAnalysisTask
• ✅ 参数：workspace_id、file_url

python scripts/quanmiao_submit_videoAnalysis_task.py --workspace_id <workspace_id> --file_url <file_url>

需要确认的参数：

• --workspace_id：来自步骤 2（与用户确认）
• --file_url：来自步骤 3 的上传结果或用户提供的 URL（确认其有效性）

错误处理：

• 如果 API 返回 401 InvalidApiKey 或 403 AccessDenied：停止，并遵循权限失败处理流程
• 不要尝试其他 API 或本地工具
• 告知用户：“视频分析需要启用 Bailian 服务并配置适当的 RAM 权限。请按照权限授予指南操作。”

返回用于轮询的 task_id。

步骤 5：轮询任务结果

⚠️ 必须调用 API — 必须在 QuanMiaoLightApp 产品（版本 2024-08-01）上轮询 GetVideoAnalysisTask，直到状态为 SUCCESSED。不要使用本地工具生成摘要，也不要根据文件名推断。

视频分析是异步的。请轮询直至完成：

任务状态： PENDING → RUNNING → SUCCESSED | FAILED | CANCELED

变量：

• result_json_path：~/.quanmiao/videoanalysis/<video_filename_without_ext>_<task_id>.json
• index_file：~/.quanmiao/videoanalysis/index.jsonl

轮询循环：

1. 提交后等待 10 秒
2. 运行：python scripts/quanmiao_get_videoAnalysis_task_result.py --workspace_id <workspace_id> --task_id <task_id> --save_path <result_json_path>
3. 检查返回的 status 字段：
   • SUCCESSED → 脚本会自动将 JSON 保存到 result_json_path，向 index_file 追加条目，显示保存位置，然后继续步骤 6
   • FAILED 或 CANCELED → 检查错误消息，告知用户，然后停止
   • PENDING 或 RUNNING → 显示任何可用的部分结果，等待 10 秒，然后从步骤 2 重复
4. 最多重试 180 次（约 30 分钟）

当 taskStatus = SUCCESSED 时：

1. 追加到索引文件（index_file）：

   {"task_id": "<task_id>", "video_source": "<original_path_or_url>", "workspace_id": "<workspace_id>", "result_file": "<result_json_path>", "timestamp": "<ISO8601>"}
   

2. 显示保存位置：

✅ Files saved successfully:
- Raw JSON result: <result_json_path>
- Index updated: <index_file>

需要确认的参数：

• --workspace_id：与步骤 4 相同（确认一致）
• --task_id：来自步骤 4 的提交结果（轮询前确认）

步骤 6：总结视频内容

关键：直接使用步骤 5 的结果。不要再次调用 API。不要重新执行任何分析。

从步骤 5 获取的 SUCCESSED 响应中提取数据，并根据用户要求进行总结。

情况 A：用户有具体的分析要求（例如“分析说话者的肢体语言”“提取关键业务洞见”“比较视频中的两个人”），请主要依据：

• payload.output.videoGenerateResults — 逐场景分析、描述和解读
• payload.output.videoAnalysisResult.text — 视觉镜头分析、物体/人物识别、动作检测 结合这些字段构建有针对性的回答。如有相关性，可补充其他字段（字幕、思维导图、标题）作为上下文。

情况 B：没有具体要求，使用标准输出格式：标题 → 大纲 → 摘要 → 字幕 → 镜头分析 → 时间线 → Token 用量

重要限制

• 仅限云端： 不使用本地备用方案（ffmpeg、whisper 等）。如果云端 API 调用失败，请遵循权限失败处理流程。
• 违规后果： 使用本地工具而非 QuanMiaoLightApp API 将导致任务失败。
• 安全： 切勿在日志或提示词中泄露凭据
• 权限： 出现身份验证错误时，请参阅 ram-policies.md
• 缓存： 重新分析同一视频前，请检查 ~/.quanmiao/videoanalysis/index.jsonl

---

成功验证

有关分步验证命令和预期结果，请参阅 references/verification-method.md。

---

清理

清理此技能创建的资源：

删除已上传的 OSS 对象：

aliyun ossutil rm oss://{oss_bucket}/{oss_object_key} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-bailian-videoanalysis

清理最佳实践：

• 删除前确认存储桶名称和 OSS 对象键
• 仅删除带有 /temp/quanmiao/ 前缀的对象，以避免意外丢失数据
• ~/.quanmiao/videoanalysis/ 中的缓存结果可留作将来参考，也可手动删除

---

最佳实践

1. 始终先检查环境 — 在执行任何其他操作前运行 check_env.py，尽早发现缺失的依赖项或凭据。
2. 自动检测 workspace_id — 始终通过 list-workspaces 获取工作空间；默认使用第一个结果，但如果用户明确要求选择，则显示选择列表。
3. 使用默认 OSS 设置 — 除非用户指定特定存储桶，否则让脚本自动检测存储桶并生成 OSS 对象键。
4. 轮询时显示部分结果 — 当任务状态为 RUNNING 时，显示可用结果（标题、字幕），为用户提供实时反馈。
5. 保存完整结果用于总结 — 当状态变为 SUCCESSED 时，直接使用完整结果载荷执行步骤 6，无需再次调用 API。
6. 注意 URL 过期时间 — 临时 OSS URL 会在 expireSeconds（默认 14400s）后过期；确保在 URL 过期前提交任务。
7. 妥善处理权限错误 — 遵循 RAM 策略部分中的权限失败处理流程；切勿擅自尝试修复凭据。

---

命令表

有关可用脚本及其参数的完整列表，请参阅 references/related-commands.md。

---

参考链接

参考资料	用途
references/cli-installation-guide.md	安装和升级 Aliyun CLI
references/ram-policies.md	RAM 权限检查清单和授权指南
references/acceptance-criteria.md	验收标准以及正确和错误的使用模式
references/related-commands.md	可用脚本和 CLI 命令参考
references/verification-method.md	分步成功验证命令

---

故障排除

常见情况：

• 权限被拒绝 → 请参阅 ram-policies.md
• 找不到 CLI → 请参阅 cli-installation-guide.md
• 找不到工作空间 → 在 Bailian Console 中创建
• 上传失败 → 检查 OSS 存储桶权限
• 任务超时 → 视频过大或存在网络问题

---