阿里云视频工坊（Alibaba Cloud Video Forge）

基于阿里云媒体处理服务（MPS）的一站式视频处理能力，涵盖封面生成、多分辨率转码、内容审核等核心功能。

前置条件

预检：Aliyun CLI ≥ 3.3.3
运行 aliyun version 验证版本是否 ≥ 3.3.3。若未安装或版本过低，请执行：
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 进行更新，
或参考 references/cli-installation-guide.md 获取完整安装说明。

预检：Aliyun CLI 插件需更新
[MUST] 执行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[MUST] 执行 aliyun plugin update 确保已安装插件始终为最新版本。

预检：AI-Mode 配置必需
[MUST] 在使用 aliyun CLI 命令前，必须完成 AI-Mode 配置：

• aliyun configure ai-mode enable
• aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge"
• aliyun configure ai-mode disable

预检：Python ≥ 3.10
运行 python3 --version 验证版本。

预检：阿里云凭据必需

运行 aliyun configure list 检查凭据状态；若无有效 profile，请通过 aliyun configure 配置。
凭据安全规范详见 references/security-guidelines.md。

🚀 快速入门

最简方式 — 一键式视频处理：

# 方法 1：使用端到端工作流脚本（推荐）
python scripts/video_workflow.py --input /path/to/video.mp4

# 方法 2：先检查环境健康状态
python scripts/health_check.py

# 方法 3：手动分步执行
python scripts/oss_upload.py --local-file video.mp4 --oss-key input/video.mp4
python scripts/mps_transcode.py --oss-object input/video.mp4 --preset multi
python scripts/mps_audit.py --oss-object input/video.mp4

典型场景

场景 1：Bilibili 视频发布

python scripts/video_workflow.py 
  --input my_video.mov 
  --preset 720p 
  --generate-cover 
  --scenes porn terrorism ad

场景 2：UGC 内容审核

python scripts/mps_audit.py --oss-object /input/user_uploaded.mp4

场景 3：多分辨率转码

python scripts/mps_transcode.py 
  --oss-object /input/course_video.mp4 
  --preset multi 
  --output-prefix output/course_2024/

场景说明

本技能支持以下视频分发类场景：

1. 转码（Transcoding） — 支持窄带高清（Narrowband HD）压缩的多分辨率转码
2. 内容审核（Content Moderation） — 自动识别敏感内容（涉黄、暴恐、广告等）
3. 截图（Snapshot） — 生成视频封面图与雪碧图（Sprite Sheet）
4. 防盗链（Anti-piracy） — 配置加密策略实现内容保护

架构概览

OSS Bucket + MPS Pipeline + 转码模板 + 审核服务

核心组件：

• OSS：用于存储原始视频及处理后的输出文件
• MPS Pipeline：任务队列调度与生命周期管理
• 转码模板：内置窄带高清（Narrowband HD）、标准预设等多种模板
• 审核服务：提供自动化内容安全检测能力

目标用户：视频平台、内容创作者、企业培训系统、教育平台

能力概览

详细功能树与自动流水线管理说明请参见 references/capability-overview.md。

环境变量

必需环境变量：

• ALIBABA_CLOUD_REGION — 服务地域（默认值：cn-shanghai）
• ALIBABA_CLOUD_OSS_BUCKET — OSS 存储空间名称（Bucket Name）
• ALIBABA_CLOUD_OSS_ENDPOINT — OSS 访问域名（Endpoint）
• ALIBABA_CLOUD_MPS_PIPELINE_ID — MPS 流水线 ID（可选；未设置时将自动选取）

安全提示：凭据通过阿里云默认凭据链（Default Credential Chain）进行管理。请统一使用 aliyun configure 命令配置凭据。切勿在脚本或命令中直接硬编码 AccessKey（AK/SK）。

🔒 安全指南

完整安全规范与凭据管理最佳实践请参见 references/security-guidelines.md。

SDK 安装

详细安装步骤与故障排查方法请参见 references/sdk-installation.md。

请运行 python3 --version 进行验证。部分脚本在旧版 Python 下可能无法正常运行。

RAM 权限

[MUST] RAM 权限预检：执行前请确认当前用户已具备以下 RAM 权限。
完整权限列表及说明详见 references/ram-policies.md。

[MUST] 权限失败处理流程：若任一命令或 API 调用在执行过程中因权限不足报错，请按以下流程处理：

1. 查阅 references/ram-policies.md 获取本 SKILL 所需全部权限清单
2. 调用 ram-permission-diagnose 技能，引导用户申请必要权限
3. 暂停执行，等待用户确认所需权限已授予后继续

参数确认

重要：参数确认要求 — 在执行任何命令或 API 调用前，所有用户可自定义参数（如输入视频路径、输出 Bucket、模板 ID 等）均须经用户显式确认。禁止未经用户明确授权而采用默认值。

核心工作流

场景 1：一站式视频标准化处理

完整流程：用户提供视频 → 上传至 OSS → 媒体信息探测 → 封面生成（截图）→ 多分辨率转码 → 内容审核 → 返回汇总结果（含下载链接）

步骤 0：自动流水线选择（可选）

本技能支持自动流水线管理，通常无需手动指定 Pipeline ID。脚本会根据任务类型自动选择适配的流水线。

如需手动指定，请使用以下任一方式：

# 方法 1：设置环境变量（优先级最高）
export ALIBABA_CLOUD_MPS_PIPELINE_ID="your-pipeline-id"

# 方法 2：命令行参数传入
python scripts/mps_transcode.py --oss-object /input/video.mp4 --pipeline-id your-pipeline-id

# 方法 3：调用脚本自动获取
export ALIBABA_CLOUD_MPS_PIPELINE_ID=$(python scripts/mps_pipeline.py --select)

步骤 1：上传视频至 OSS

source .venv/bin/activate
python scripts/oss_upload.py --local-file /path/to/video.mp4 --oss-key input/video.mp4

步骤 2：媒体信息探测

python scripts/mps_mediainfo.py --oss-object /input/video.mp4

步骤 3：封面生成（截图）

使用截图功能，在指定时间点生成视频封面：

python scripts/mps_snapshot.py --oss-object /input/video.mp4 --mode normal --time 5000

步骤 4：自适应转码（自动选择最优分辨率及 Narrowband HD 模板）

# 自适应模式：自动识别源视频分辨率，选取最优画质，应用 Narrowband HD 模板
python scripts/mps_transcode.py --oss-object /input/video.mp4

# 或手动指定多路转码
python scripts/mps_transcode.py 
  --oss-object /input/video.mp4 
  --preset multi

步骤 5：内容审核

python scripts/mps_audit.py --oss-object /input/video.mp4

步骤 6：轮询任务状态

python scripts/poll_task.py --job-id  --job-type transcode --region cn-shanghai

完整示例

# 1. 激活虚拟环境
source .venv/bin/activate

# 2. 上传视频
python scripts/oss_upload.py --local-file ./my_video.mp4 --oss-key input/my_video.mp4

# 3. 获取媒体信息
python scripts/mps_mediainfo.py --oss-object /input/my_video.mp4

# 4. 封面生成（第 5 秒截图）
python scripts/mps_snapshot.py --oss-object /input/my_video.mp4 --mode normal --time 5000

# 5. 提交转码任务（自适应模式：自动选择最优分辨率）
python scripts/mps_transcode.py 
  --oss-object /input/my_video.mp4
# 请保存返回的 job-id

# 6. 轮询转码任务状态
python scripts/poll_task.py --job-id  --job-type transcode --region cn-shanghai --interval 10

# 7. 内容审核
python scripts/mps_audit.py --oss-object /input/my_video.mp4

# 8. 下载处理后的视频至本地
python scripts/oss_download.py --oss-key output/transcode/transcoded.mp4 --local-file ./output_video.mp4

其他场景

场景 2：仅执行转码

跳过截图与审核环节，仅执行转码：

source .venv/bin/activate
python scripts/mps_transcode.py 
  --oss-object /input/video.mp4 
  --preset 1080p 
  --template-id "your-template-id"

场景 3：仅执行内容审核

仅对指定视频执行内容审核：

source .venv/bin/activate
python scripts/mps_audit.py 
  --oss-object /input/video.mp4 
  --scenes porn terrorism ad

成功验证

视频处理完成后，请按以下方式验证结果：

1. 脚本退出码（exit code）为 0
2. 输出中包含已处理媒体信息（OSS 路径）
3. 转码任务状态为 “Success”
4. 内容审核结果无违规项
5. 产物已通过 oss_download.py 成功下载至本地

关于产物获取的注意事项：

• OSS 文件需签名后方可在线访问；直接访问公开 URL 将返回 403 错误
• 建议统一使用 oss_download.py 下载产物至本地
• 如需在线预览，请使用 --sign-url 参数生成临时预签名 URL

# 验证转码是否成功
python scripts/poll_task.py --job-id  --job-type transcode --region cn-shanghai
# 预期输出：Status: Success

# 验证审核结果
python scripts/mps_audit.py --query-job-id 
# 预期输出：Moderation passed, no violations

故障排查

完整排障指南请参见 references/troubleshooting.md。

清理操作

本技能产生的中间文件与输出文件均存储于 OSS。如需清理，请使用以下命令：

# 删除单个文件
python scripts/oss_delete.py --oss-key output/transcode/video.mp4

# 删除目录下全部文件（递归删除）
python scripts/oss_delete.py --prefix output/ --recursive

# 强制删除（跳过确认提示，适用于脚本自动化）
python scripts/oss_delete.py --oss-key output/video.mp4 --force

# 预览模式（仅列出待删文件，不实际执行删除）
python scripts/oss_delete.py --prefix output/ --recursive --dry-run

注意：删除操作不可逆，请务必提前确认。建议首次使用时添加 --dry-run 参数预览。

可用脚本清单

最佳实践

1. 始终优先检查环境变量 — 每次会话开始时运行 python scripts/load_env.py --check-only
2. 使用轮询而非阻塞等待 — 提交任务后请使用 poll_task.py 自动轮询状态
3. 合理选择分辨率 — 根据目标终端设备特性选择合适的转码分辨率
4. 启用内容审核 — 对于 UGC 类内容，应始终开启自动审核
5. 使用虚拟环境 — 确保依赖隔离，避免版本冲突
6. 启用自动流水线管理 — 无需手动配置 Pipeline ID，脚本将依据任务类型自动选取适配流水线

参考文档

AI-Mode 配置

[MUST] Aliyun CLI 的 AI-Mode 配置 — 在使用 aliyun CLI 命令前，必须完成 AI-Mode 配置，以确保功能追踪与插件管理正常生效。

启用 AI-Mode

启用 AI-Mode 以获得增强功能：

aliyun configure ai-mode enable

配置 User-Agent

设置 User-Agent 以实现技能准确识别：

aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge"

禁用 AI-Mode

不再需要时可禁用 AI-Mode：

aliyun configure ai-mode disable

注意：为保障功能追踪准确性与插件兼容性，所有 aliyun CLI 命令执行前必须已启用 AI-Mode。

CLI 命令规范

重要说明：User-Agent 由 AI-Mode 配置自动注入。在执行 aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-video-forge" 后，后续所有 aliyun CLI 命令将自动携带正确 User-Agent。无需在每个命令中重复添加 --user-agent 参数。