analyze_video_potential

Instructions

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