Communitygithub.com

AiCurv/ADBCommander

使用 z-ai-web-dev-sdk 实现专门的视频理解能力。当用户需要分析视频内容、理解动作和时间序列、从视频帧中提取信息、描述视频场景或执行基于视频的 AI 分析时使用此技能。针对 MP4、AVI、MOV 等常见视频格式进行了优化。

ADBCommander 是什么?

该技能利用 z-ai-web-dev-sdk 包,为 AI 模型提供专门的视频理解能力,使其能够分析、描述和提取视频内容中的信息,包括动作、时间序列和场景变化。它同时支持 CLI 和 SDK 两种使用方式:CLI 适用于快速视频总结和一次性分析,SDK 适用于多轮对话和复杂的视频处理流水线。技能提供了丰富的 API 示例,涵盖单一视频分析、场景理解、动作检测、事件时间线提取、视频分类以及更高级的用例(如多轮视频对话、质量评估、内容审核和体育视频分析)。该技能优化用于 MP4、AVI、MOV、WebM、MKV 和 FLV 等常见视频格式,并建议将本地视频上传至 CDN 或对长视频进行分块采样以获得更好的性能。CLI 支持流式输出和思维链推理,SDK 则提供了更详细的编程接口以实现自定义集成。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/AiCurv/ADBCommander/tree/HEAD/skills/video-understand

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

视频理解技能

此技能使用 z-ai-web-dev-sdk 包提供专门的视频理解功能,使 AI 模型能够分析、描述和提取视频内容中的信息,包括动作、时间序列和场景变化。

技能路径

技能位置:{project_path}/skills/video-understand

此技能位于你项目中的上述路径。

参考脚本:示例测试脚本可在 {技能位置}/scripts/ 目录中找到,用于快速测试和参考。请参阅 {技能位置}/scripts/video-understand.ts 获取工作示例。

概述

视频理解专注于视频内容分析,提供以下功能:

  • 视频场景理解与描述
  • 动作与运动检测
  • 时间序列分析
  • 视频中的事件检测
  • 视频内容摘要
  • 场景变化检测
  • 跨帧的人物与物体跟踪
  • 视听内容分析(如适用)

重要提示:z-ai-web-dev-sdk 仅能在后端代码中使用。切勿在客户端代码中使用。

前提条件

z-ai-web-dev-sdk 包已安装。按照以下示例所示导入即可。

CLI 用法(适用于简单任务)

对于快速的视频分析任务,你可以使用 z-ai CLI 而不是编写代码。这非常适合简单的视频描述、测试或自动化。

基本视频分析

# 分析来自 URL 的视频
z-ai vision --prompt "总结这个视频中发生的事情" --image "https://example.com/video.mp4"

# 注意:视频 URL 也使用 --image 参数
z-ai vision -p "描述关键事件" -i "https://example.com/presentation.mp4"

分析本地视频

# 分析本地视频文件
z-ai vision -p "这个视频中展示了哪些活动?" -i "./recording.mp4"

# 将响应保存到文件
z-ai vision -p "提供详细摘要" -i "./meeting.mp4" -o summary.json

高级视频分析

# 复杂场景理解与思考
z-ai vision \
  -p "分析此视频并识别:1) 主要事件,2) 人物及其动作,3) 关键时刻的时间线" \
  -i "./event.mp4" \
  --thinking \
  -o analysis.json

# 动作检测
z-ai vision \
  -p "识别此视频中人物执行的所有动作" \
  -i "./sports.mp4" \
  --thinking

流式输出

# 流式传输视频分析
z-ai vision -p "描述此视频内容" -i "./video.mp4" --stream

CLI 参数

  • --prompt, -p <文本>:必需 - 关于视频的问题或指令
  • --image, -i <URL 或路径>:可选 - 视频 URL 或本地文件路径(尽管名称如此,它也适用于视频)
  • --thinking, -t:可选 - 启用链式思维推理以进行复杂分析(默认:禁用)
  • --output, -o <路径>:可选 - 输出文件路径(JSON 格式)
  • --stream:可选 - 实时流式传输响应

支持的视频格式

  • MP4 (.mp4) - 最广泛支持的格式
  • AVI (.avi) - 音频视频交错
  • MOV (.mov) - QuickTime 格式
  • WebM (.webm) - Web 优化格式
  • MKV (.mkv) - Matroska 格式
  • FLV (.flv) - Flash 视频格式

何时使用 CLI 与 SDK

使用 CLI 的场景:

  • 快速视频摘要
  • 一次性视频分析
  • 测试视频理解能力
  • 简单的自动化脚本
  • 生成视频描述

使用 SDK 的场景:

  • 关于视频的多轮对话
  • 复杂的视频处理流水线
  • 带有错误处理的生产应用程序
  • 使用视频处理逻辑进行自定义集成
  • 带有自定义工作流的批量视频处理

推荐方法

为了获得更好的本地视频性能和可靠性,请考虑:

  1. 将视频上传到 CDN 并使用 URL
  2. 对于较短的视频,将关键帧转换为图像以加快分析速度
  3. 对于长视频,考虑分块或按间隔采样

基本视频理解实现

单一视频分析

import ZAI from 'z-ai-web-dev-sdk';

async function analyzeVideo(videoUrl, prompt) {
  const zai = await ZAI.create();

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          {
            type: 'text',
            text: prompt
          },
          {
            type: 'video_url',
            video_url: {
              url: videoUrl
            }
          }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

// 使用示例
const summary = await analyzeVideo(
  'https://example.com/presentation.mp4',
  '总结此视频中呈现的要点'
);

const actionDetection = await analyzeVideo(
  'https://example.com/sports.mp4',
  '识别并描述此视频中执行的所有运动动作'
);

视频场景理解

import ZAI from 'z-ai-web-dev-sdk';

async function understandVideoScenes(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `分析此视频并提供:
1. 视频内容的总体摘要
2. 主要场景或片段(如果可能,附上大致时间戳)
3. 关键人物或角色及其作用
4. 按时间顺序排列的重要动作或事件
5. 场景和环境描述
6. 整体情绪或基调`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' } // 启用详细分析
  });

  return response.choices[0]?.message?.content;
}

// 用法
const sceneAnalysis = await understandVideoScenes(
  'https://example.com/documentary.mp4'
);

运动和动作检测

import ZAI from 'z-ai-web-dev-sdk';

async function detectActions(videoUrl, specificAction = null) {
  const zai = await ZAI.create();

  const prompt = specificAction
    ? `识别此视频中所有"${specificAction}"的实例。对于每个实例,描述其发生的时间并提供其执行方式的详细信息。`
    : '识别并描述此视频中所有重要的动作和运动。包括执行者及发生时间。';

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

// 用法
const runningActions = await detectActions(
  'https://example.com/sports.mp4',
  'running'
);

const allActions = await detectActions(
  'https://example.com/activity.mp4'
);

事件时间线提取

import ZAI from 'z-ai-web-dev-sdk';

async function extractTimeline(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `创建此视频中事件的详细时间线:
- 识别关键时刻和过渡
- 注意大致时间(开始、中间、结束或可见的具体时间戳)
- 描述每个关键点发生的事件
- 识别事件之间的任何因果关系

格式化为按时间顺序排列的列表。`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

视频内容分类

import ZAI from 'z-ai-web-dev-sdk';

async function classifyVideo(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `分类此视频内容:
1. 主要类别(例如:教育、娱乐、体育、新闻、教程)
2. 子类别或类型
3. 目标受众
4. 内容风格(专业、休闲、纪录片等)
5. 关键主题或话题
6. 建议标签(10-15 个关键词)

将回答格式化为结构化 JSON。`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  const content = response.choices[0]?.message?.content;
  
  try {
    return JSON.parse(content);
  } catch (e) {
    return { rawResponse: content };
  }
}

高级用例

多轮视频对话

import ZAI from 'z-ai-web-dev-sdk';

class VideoConversation {
  constructor() {
    this.messages = [];
  }

  async initialize() {
    this.zai = await ZAI.create();
  }

  async loadVideo(videoUrl, initialQuestion) {
    this.messages.push({
      role: 'user',
      content: [
        { type: 'text', text: initialQuestion },
        { type: 'video_url', video_url: { url: videoUrl } }
      ]
    });

    return this.getResponse();
  }

  async askFollowUp(question) {
    this.messages.push({
      role: 'user',
      content: [
        { type: 'text', text: question }
      ]
    });

    return this.getResponse();
  }

  async getResponse() {
    const response = await this.zai.chat.completions.createVision({
      messages: this.messages,
      thinking: { type: 'disabled' }
    });

    const assistantMessage = response.choices[0]?.message?.content;
    
    this.messages.push({
      role: 'assistant',
      content: assistantMessage
    });

    return assistantMessage;
  }
}

// 用法
const conversation = new VideoConversation();
await conversation.initialize();

const initial = await conversation.loadVideo(
  'https://example.com/lecture.mp4',
  '这次讲座的主要主题是什么?'
);

const followup1 = await conversation.askFollowUp(
  '你能解释一下提到的关键概念吗?'
);

const followup2 = await conversation.askFollowUp(
  '使用了哪些例子来说明这些概念?'
);

视频质量评估

import ZAI from 'z-ai-web-dev-sdk';

async function assessVideoQuality(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `评估此视频的质量:
1. 视觉质量(分辨率、清晰度、光照)- 评分 1-10
2. 音频质量(如果存在音频)- 评分 1-10
3. 摄像工作(稳定性、构图、画面布局)- 评分 1-10
4. 制作价值(剪辑、过渡、特效)- 评分 1-10
5. 内容清晰度(信息是否明确?)- 评分 1-10
6. 节奏(太快、太慢、恰到好处)
7. 技术问题(伪影、模糊、音画不同步等)
8. 总体评分 - 1-10
9. 具体改进建议

为每个标准提供详细的反馈。`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

视频内容审核

import ZAI from 'z-ai-web-dev-sdk';

async function moderateVideo(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `审核此视频的内容:
1. 检查任何不恰当或敏感内容
2. 识别任何潜在的安全问题
3. 注意任何可能违反常见社区准则的内容
4. 评估适龄性
5. 识别任何可见的受版权保护材料(标志、品牌、音乐)
6. 总体安全评级:安全 / 谨慎 / 需要审查

对于识别的任何问题,提供具体示例。`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

视频转录生成(视觉描述)

import ZAI from 'z-ai-web-dev-sdk';

async function generateVisualTranscript(videoUrl) {
  const zai = await ZAI.create();

  const prompt = `生成此视频的详细视觉转录:
- 描述每个场景中发生了什么
- 注意屏幕上出现的任何文本
- 描述重要的视觉元素
- 提及任何场景变化或过渡
- 包括人物动作和表情的描述

格式化为基于时间的叙述(例如:"开始时…","然后…","最后…")。`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'disabled' }
  });

  return response.choices[0]?.message?.content;
}

体育视频分析

import ZAI from 'z-ai-web-dev-sdk';

async function analyzeSportsVideo(videoUrl, sport = null) {
  const zai = await ZAI.create();

  const prompt = sport
    ? `详细分析此${sport}视频:
1. 识别球员及其位置
2. 描述关键打法和策略
3. 注意得分事件或重要时刻
4. 评估球员表现
5. 识别任何规则违规或犯规
6. 描述比赛的节奏和流程`
    : `分析此体育视频:
1. 识别正在进行的运动
2. 描述关键动作和比赛
3. 注意任何得分或重大事件
4. 描述球员移动和策略
5. 比赛或对局的总体评估`;

  const response = await zai.chat.completions.createVision({
    messages: [
      {
        role: 'user',
        content: [
          { type: 'text', text: prompt },
          { type: 'video_url', video_url: { url: videoUrl } }
        ]
      }
    ],
    thinking: { type: 'enabled' }
  });

  return response.choices[0]?.message?.content;
}

批量视频处理

import ZAI from 'z-ai-web-dev-sdk';

async function batchAnalyzeVideos(videoUrls) {
  const zai = await ZAI.create();
  const results = [];

  for (const videoUrl of videoUrls) {
    try {
      const response = await zai.chat.completions.createVision({
        messages: [
          {
            role: 'user',
            content: [
              { type: 'text', text: '提供此视频的简要摘要' },
              { type: 'video_url', video_url: { url: videoUrl } }
            ]
          }
        ],
        thinking: { type: 'disabled' }
      });

      results.push({
        url: videoUrl,
        summary: response.choices[0]?.message?.content,
        status: 'success'
      });
    } catch (error) {
      results.push({
        url: videoUrl,
        error: error.message,
        status: 'failed'
      });
    }
  }

  return results;
}

// 用法
const batchResults = await batchAnalyzeVideos([
  'https://example.com/video1.mp4',
  'https://example.com/video2.mp4',
  'https://example.com/video3.mp4'
]);

常见问题

支持哪些视频格式?

支持的格式包括:.mp4、.avi、.mov、.webm、.mkv、.flv。视频的最大文件大小取决于你的提供商限制(通常为 100MB - 1GB)。

如何处理长视频?

对于长视频(超过 10 分钟),请考虑:

  • 以固定间隔采样关键帧
  • 将视频分成较短的片段
  • 使用 --thinking 标志进行更详细的处理
  • 首先关注特定部分或时间范围

视频理解支持音频吗?

视频理解主要关注视觉内容分析。虽然 z-ai-web-dev-sdk 在适用时会尝试处理音频,但音频分析并非主要功能。对于纯音频分析,请使用专门的语音转文本工具。

我可以分析实时视频流吗?

当前的实现针对预先录制的视频进行了优化。对于实时流,你需要捕获帧并定期发送进行分析。这不直接支持,但可以在你的实现中构建。

隐私请注意

上传到 AI 服务进行分析的视频将根据服务提供商的隐私政策进行处理。处理敏感或机密视频内容时请考虑这一点。

故障排除

常见错误

  1. "视频文件太大" - 将视频压缩到较小尺寸或采样关键帧
  2. "不支持的格式" - 转换为支持的格式(推荐 .mp4)
  3. "分析超时" - 对于长视频,增加超时时间或使用 --thinking 标志
  4. "URL 无效" - 确保视频 URL 可公开访问或使用本地文件路径
  5. "文件未找到" - 检查本地文件路径是否正确以及文件是否存在

性能提示

  • 对于本地视频,在分析前转换为基于 URL 的访问
  • 分析前将视频压缩到合理的分辨率(例如 720p)
  • 对于简单任务,使用 CLI 以获得更快的初始结果
  • 复杂的多步分析启用 thinking 模式
  • 对于大型项目,使用 SDK 进行更强大的错误处理

下一步

  • 探索 {技能位置}/scripts/ 中的参考脚本以了解实际情况
  • 尝试不同的提示以优化特定用例的分析
  • 考虑将视频理解与其他 AI 功能结合用于多模态应用程序
  • 为你的领域自定义提示模板(例如,医疗、教育、安全)
  • 构建视频分析管道以进行大规模处理

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

AiCurv/ADBCommander

Generate a single-file Chinese atelier-style portfolio website (horizontal-row list + hover-reveal thumb interaction, art lishu typography "Alimama DaoLiTi" via CDN, light/dark theme, hash-routed detail pages). Takes a natural-language description of the studio (name, director, discipline, works) and outputs ONE working .html file. Runs in BOTH Claude Code (writes to ~/Desktop) and GLM / online chat (outputs HTML inline). Trigger phrases include "做个中式工作室作品集", "做个隶书作品集", "lishu-portfolio-gen ...", "做个白屋风格的作品集", or when user drags this skill folder into chat asking for an atelier-style site.

AiCurv/ADBCommander

Premium calm-tech SaaS landing template — bilingual (CN/EN) literary voice over a dark forest-night palette with warm gold accent, Cormorant + Noto Serif SC, Three.js procedural forest hero, station-based scrolling narrative, custom cursor. Built for ambient-AI / creative-tool / philosophical SaaS, not loud commercial launch.

AiCurv/ADBCommander

Pro-camera HUD mockup template — full-viewport black canvas wrapping a real video with monospace overlays (corner brackets, top status bar, side AF/exposure columns, bottom timecode + aperture/shutter/ISO row, vertical 8-filter wheel, animated reticle). For cinematographer portfolios, camera-app demos, LUT pack previews, filter-look auditions. NOT a TikTok/Reels mockup, NOT a storyboard, NOT a shot list, NOT a script document. The chrome wraps real footage — never a div placeholder.

AiCurv/ADBCommander

Premium pre-launch waitlist page template — dark charcoal canvas with subtle vignette, drifting portrait video-thumbnail cards, fade-up cascades, glass nav, live-updating join counter, single email form with success/error states. Built for creative-tool / AI / niche-SaaS invite-only launches with hushed exclusive tone, not loud growth-marketing.

AiCurv/ADBCommander

Route design-related HTML artifact tasks to the right artifact skill, reference, design system generation, or export skill.

AiCurv/ADBCommander

Implement text-to-speech (TTS) capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to convert text into natural-sounding speech, create audio content, build voice-enabled applications, or generate spoken audio files. Supports multiple voices, adjustable speed, and various audio formats.

AiCurv/ADBCommander

Implement AI-powered video generation capabilities using the z-ai-web-dev-sdk. Use this skill when the user needs to generate videos from text prompts or images, create video content programmatically, or build applications that produce video outputs. Supports asynchronous task management with status polling and result retrieval.

相关技能