Communitygithub.com

Cetc2211/AcTR-app - 视频理解技能

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

AcTR-app - 视频理解技能 是什么?

该技能通过 z-ai-web-dev-sdk 包为 AI 模型提供专门的视频理解功能,支持分析、描述和从视频内容中提取信息,包括运动、时间序列和场景变化。它适用于多种平台,如 Claude Code、Cursor 和 Codex,并支持 MP4、AVI、MOV、WebM、MKV 和 FLV 等常见视频格式。技能的核心优势在于其易用性:通过 CLI 工具可快速进行视频摘要、动作检测和场景分析,适合一次性任务或自动化脚本;而 SDK 则支持多轮对话、复杂视频处理流水线和生产级应用,具有完善的错误处理能力。工作原理包括初始化 ZAI 客户端,构造包含文本提示和视频 URL 的消息,然后调用 createVision 方法获取分析结果。高级用例包括多轮视频对话、质量评估、内容审核和体育视频分析,其中启用 thinking 模式可获取更详细的链式推理输出。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cetc2211/AcTR-app/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 <text>:必需 - 关于视频的问题或指令
  • --image, -i <URL 或路径>:可选 - 视频 URL 或本地文件路径(尽管命名如此,它也适用于视频)
  • --thinking, -t:可选 - 为复杂分析启用链式推理(默认:禁用)
  • --output, -o <path>:可选 - 输出文件路径(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',
  '跑步'
);

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;
}

Individual skills in this repo

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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

Cetc2211/AcTR-app

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.

Cetc2211/AcTR-app

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.

相关技能