analyze_video_potential

Analyze YouTube Shorts performance by providing detailed metrics like views and engagement rates to assess video potential.

Instructions

深度分析单个 YouTube Shorts 视频的表现。提供详细的播放量、互动率等核心指标。

Input Schema

TableJSON Schema

Name	Required	Description	Default
`video_url`	Yes	YouTube Shorts 视频链接

Implementation Reference

src/server.py:458-501 (handler)

Main handler implementation for analyze_video_potential tool. Extracts video ID, fetches video details from YouTube, gets channel info, analyzes metrics using ViralAnalyzer, and returns a detailed analysis report.

async def analyze_video_potential(video_url: str) -> list[TextContent]:
    """工具 2 的实现:分析单个视频的爆款潜力"""
    
    try:
        # 提取视频 ID
        video_id = extract_video_id(video_url)
        
        if not video_id:
            return [TextContent(
                type="text",
                text=f"❌ 无效的 YouTube 链接: {video_url}\n\n支持的格式:\n- https://www.youtube.com/shorts/VIDEO_ID\n- https://www.youtube.com/watch?v=VIDEO_ID\n- https://youtu.be/VIDEO_ID"
            )]
        
        # 获取视频详情
        client = YouTubeClient()
        videos = client.get_video_details([video_id])
        
        if not videos:
            return [TextContent(
                type="text",
                text=f"❌ 未找到视频: {video_id}"
            )]
        
        video = videos[0]
        
        # 获取频道信息
        channel_map = client.get_channel_info([video.channel_id])
        if video.channel_id in channel_map:
            video.channel_subscribers = channel_map[video.channel_id].subscribers
        
        # 分析视频
        analyzer = ViralAnalyzer()
        video = analyzer.analyze_video(video)
        
        # 生成详细报告
        report = analyzer.generate_analysis_report(video)
        
        return [TextContent(type="text", text=report)]
    
    except Exception as e:
        return [TextContent(
            type="text",
            text=f"❌ 分析失败: {str(e)}"
        )]

src/server.py:185-201 (registration)

Tool registration for analyze_video_potential in the list_tools function. Defines tool name, description, and JSON Schema for the required 'video_url' parameter.

Tool(
    name="analyze_video_potential",
    description=(
        "深度分析单个 YouTube Shorts 视频的表现。"
        "提供详细的播放量、互动率等核心指标。"
    ),
    inputSchema={
        "type": "object",
        "properties": {
            "video_url": {
                "type": "string",
                "description": "YouTube Shorts 视频链接"
            }
        },
        "required": ["video_url"]
    }
),

src/server.py:333-336 (registration)
Tool routing logic in call_tool handler that routes 'analyze_video_potential' tool calls to the handler function.
```
elif name == "analyze_video_potential":
    return await analyze_video_potential(
        video_url=arguments["video_url"]
    )
```

src/server.py:104-117 (helper)

Helper function extract_video_id that parses YouTube URLs to extract the video ID. Supports multiple URL formats (shorts, watch, youtu.be).

def extract_video_id(url: str) -> Optional[str]:
    """从 YouTube URL 中提取视频 ID"""
    patterns = [
        r'youtube\.com/shorts/([a-zA-Z0-9_-]+)',
        r'youtube\.com/watch\?v=([a-zA-Z0-9_-]+)',
        r'youtu\.be/([a-zA-Z0-9_-]+)',
    ]
    
    for pattern in patterns:
        match = re.search(pattern, url)
        if match:
            return match.group(1)
    
    return None

src/youtube/analyzer.py:105-169 (helper)

Helper method generate_analysis_report in ViralAnalyzer that creates a detailed Markdown report with video metrics, engagement rate assessment, and potential evaluation based on views and interaction data.

    def generate_analysis_report(cls, video: VideoData) -> str:
        """
        生成单个视频的详细分析报告
        
        Args:
            video: 视频数据
        
        Returns:
            Markdown 格式的分析报告
        """
        report = f"""
## 📊 视频分析报告

**标题**: {video.title}
**链接**: {video.url}

### 基础数据
- **频道**: {video.channel_name}
- **发布时间**: {video.published_at.strftime('%Y-%m-%d %H:%M UTC')}

### 核心指标
- **播放量**: {video.views:,}
- **点赞数**: {video.likes:,}
- **评论数**: {video.comments:,}
- **互动率**: {video.engagement_rate:.2f}%

### 潜力评估
"""
        
        # 播放量评估
        if video.views >= 1000000:
            report += "- ✅ 播放量超过 100万,属于热门视频\n"
        elif video.views >= 500000:
            report += "- ✅ 播放量超过 50万,表现优秀\n"
        elif video.views >= 100000:
            report += "- ⚠️ 播放量超过 10万,值得关注\n"
        else:
            report += "- ℹ️ 播放量较低\n"
        
        # 互动率评估
        if video.engagement_rate >= 10:
            report += "- ✅ 互动率超过 10%,内容质量极高\n"
        elif video.engagement_rate >= 5:
            report += "- ✅ 互动率超过 5%,内容质量优秀\n"
        elif video.engagement_rate >= 2:
            report += "- ⚠️ 互动率一般,有提升空间\n"
        else:
            report += "- ℹ️ 互动率较低\n"
        
        # 频道影响力(如果有数据)
        if video.channel_subscribers:
            subs = video.channel_subscribers
            views_per_sub = video.views / max(subs, 1)
            report += f"\n### 频道影响力\n"
            report += f"- **订阅数**: {subs:,}\n"
            report += f"- **播放/订阅比**: {views_per_sub:.2f}\n"
            
            if views_per_sub >= 0.5:
                report += "- ✅ 播放量远超订阅数,内容传播力强\n"
            elif views_per_sub >= 0.1:
                report += "- ⚠️ 播放量正常,依赖订阅者观看\n"
            else:
                report += "- ℹ️ 播放量低于预期\n"
        
        return report

Viral Shorts