# YouTube Clipper Skill Pro - Agentic Workflow Edition

> 🚀 **基于原版 [Youtube-clipper-skill](https://github.com/op7418/Youtube-clipper-skill) 的增强版本**  
> 采用先进的 **Agentic Workflow** 架构，通过专家级 Subagent 实现智能分析、高质量翻译和社交媒体发布自动化。

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![Based on](https://img.shields.io/badge/based%20on-op7418%2FYoutube--clipper--skill-blue)](https://github.com/op7418/Youtube-clipper-skill)

[English](#english-version) | [简体中文](#简体中文版本)

---

## 📋 目录

- [核心优化](#核心优化)
- [快速开始](#快速开始)
- [安装指南](#安装指南)
- [使用方法](#使用方法)
- [项目结构](#项目结构)
- [配置说明](#配置说明)
- [常见问题](#常见问题)

---

## ✨ 核心优化

相比原版仓库，本项目在以下方面进行了重大升级：

### 🤖 1. Agentic Workflow 架构

采用**主智能体 + 专家 Subagent** 的协作模式，将复杂任务分解为专业化的子任务：

- **AnalysisAgent** - 内容语义分析专家
  - 深度理解视频内容结构
  - 生成高质量的章节划分方案
  - 支持交互式反馈循环，确保切分逻辑符合用户意图

- **TranslationAgent** - 双语翻译专家
  - 批量翻译优化（20条/批次）
  - 95% API 调用减少，10倍速度提升
  - 保持主 Agent 上下文清晰，避免翻译任务污染主流程

- **TweetAgent** ⭐ **新增** - 社交媒体文案专家
  - 自动生成推特风格的分享文案
  - 针对每个视频片段优化内容吸引力
  - 支持自定义文案风格和话题标签

### 🐦 2. Twitter 自动发布集成 ⭐ **新增**

集成 **[baoyu-post-to-x-video](https://github.com/baoyu-io/post-to-x-video)** Skill：

- ✅ 一键将剪辑好的视频发布到 Twitter/X
- ✅ 自动附带 AI 生成的推广文案
- ✅ 支持视频预览和发布前确认
- ✅ 完整的浏览器自动化流程

### 🧠 3. 上下文管理优化

通过 Subagent 架构实现：
- 主 Agent 专注于流程编排
- 专家 Agent 处理具体任务
- 避免单一 Agent 上下文过载
- 提升整体工作流的稳定性和可维护性

### 📊 4. 增强的分析性能

- 更精准的语义理解
- 支持用户自定义章节划分策略
- 交互式反馈机制，持续优化直到满意

---

## 🚀 快速开始

### 前置要求

- macOS / Linux / Windows (WSL)
- Python 3.8+
- Claude Code / Claude Desktop
- Git

### 一键安装

```bash
# 克隆仓库到本地
git clone https://github.com/Mr-funny/Youtube-clipper-skill.git ~/youtube_clips

# 进入项目目录
cd ~/youtube_clips

# 查看实际的 Skill 代码（在 .claude 目录下）
ls -la .claude/skills/Youtube-clipper-skill/
```

---

## 📦 安装指南

### 方式一：直接使用（推荐）

本项目采用特殊的目录结构，**实际的 Skill 代码位于 `.claude/skills/Youtube-clipper-skill/` 目录下**。

1. **克隆项目到本地**

```bash
git clone https://github.com/Mr-funny/Youtube-clipper-skill.git ~/youtube_clips
cd ~/youtube_clips
```

2. **安装系统依赖**

**macOS:**
```bash
# 安装 yt-dlp（YouTube 下载工具）
brew install yt-dlp

# 安装 FFmpeg（必须包含 libass 支持）
brew install ffmpeg
# 或者安装完整版
brew install ffmpeg-full

# 验证 FFmpeg libass 支持
ffmpeg -filters 2>&1 | grep subtitles
# 应该输出: subtitles    V->V  (...)
```

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install yt-dlp ffmpeg libass-dev python3-pip
```

3. **安装 Python 依赖**

```bash
cd .claude/skills/Youtube-clipper-skill/
pip install yt-dlp pysrt python-dotenv
```

4. **配置环境变量**

```bash
# 复制示例配置文件
cp .claude/skills/Youtube-clipper-skill/.env.example .claude/skills/Youtube-clipper-skill/.env

# 编辑配置（可选）
nano .claude/skills/Youtube-clipper-skill/.env
```

5. **验证安装**

```bash
cd .claude/skills/Youtube-clipper-skill/

# 检查 yt-dlp
yt-dlp --version

# 检查 FFmpeg
ffmpeg -version

# 检查 Python 依赖
python3 -c "import yt_dlp; print('✅ yt-dlp available')"
```

### 方式二：符号链接到 Claude 全局 Skills 目录

如果您希望在所有项目中使用此 Skill：

```bash
# 创建符号链接到 Claude 的全局 skills 目录
ln -s ~/youtube_clips/.claude/skills/Youtube-clipper-skill ~/.claude/skills/youtube-clipper-pro

# 或者对于 .agent 目录
ln -s ~/youtube_clips/.claude/skills/Youtube-clipper-skill ~/.agent/skills/youtube-clipper-pro
```

---

## 🎯 使用方法

### 在 Claude Code 中使用

1. **启动 Claude Code 并进入项目目录**

```bash
cd ~/youtube_clips
```

2. **告诉 Claude 执行剪辑任务**

```
请使用 YouTube Clipper Skill 剪辑这个视频：
https://youtube.com/watch?v=VIDEO_ID

我想要：
- 自动分析并切分章节
- 生成中英双语字幕
- 生成推特分享文案
```

3. **Claude 会自动执行以下流程：**

```
Step 0: 环境检测
  ├─ 检查 yt-dlp
  ├─ 检查 FFmpeg + libass
  └─ 检查 Python 依赖

Step 1: 下载视频和字幕
  └─ 使用浏览器 Cookie 绕过 YouTube 验证

Step 2: AI 智能分析（AnalysisAgent）
  ├─ 分析视频内容
  ├─ 生成章节方案
  └─ 交互式反馈，直到用户满意

Step 3: 用户选择章节
  └─ 选择要处理的章节（单个/多个/全部）

Step 4: 切分视频素材
  └─ 为每个章节生成独立文件夹

Step 5: 并行处理（Subagent 协作）
  ├─ TranslationAgent: 翻译字幕
  ├─ TweetAgent: 生成推特文案 ⭐
  └─ 烧录双语字幕到视频

Step 6: 交付成果
  └─ 展示所有生成的文件
```

### 输出文件结构

```
youtube_clips_pro/
└── Video_Title_ID/
    ├── chapters.json                    # 章节元数据
    ├── context.json                     # 视频上下文
    ├── for_analysis_agent.txt          # 分析 Agent 输入
    ├── Video_ID.mp4                    # 原始视频
    │
    └── Chapter_Title_1/
        ├── Chapter_Title_1_source.mp4           # 原始片段
        ├── Chapter_Title_1_final_bilingual.mp4  # 带字幕的最终版本
        ├── en.srt                               # 英文字幕
        ├── zh_en.srt                            # 中英双语字幕
        ├── meta.json                            # 章节元数据
        └── tweet.md                             # 推特文案 ⭐
```

### 发布到 Twitter（可选）

生成视频后，可以使用集成的 Twitter 发布 Skill：

```
请使用 baoyu-post-to-x-video Skill 将这个视频发布到 Twitter：
视频路径：youtube_clips_pro/Video_Title/Chapter_1/Chapter_1_final_bilingual.mp4
文案：使用 tweet.md 中的内容
```

---

## 📁 项目结构

```
youtube_clips/                          # 项目根目录
├── .git/                               # Git 仓库
├── .gitignore                          # Git 忽略规则
├── .gitattributes                      # Git 属性配置
├── README.md                           # 本文件
│
├── .claude/                            # Claude AI 配置目录
│   ├── agents/                         # Subagent 定义（如果有）
│   └── skills/                         # Skills 目录
│       ├── Youtube-clipper-skill/      # 🎯 核心 Skill 代码
│       │   ├── SKILL.md                # Skill 定义和工作流
│       │   ├── README.md               # 详细文档
│       │   ├── .env.example            # 环境变量示例
│       │   ├── scripts/                # Python 脚本
│       │   │   ├── video_clipper_pro.py      # 主控制脚本
│       │   │   ├── download_video.py         # 下载模块
│       │   │   ├── analyze_subtitles.py      # 字幕分析
│       │   │   ├── translate_subtitles.py    # 翻译模块
│       │   │   ├── burn_subtitles.py         # 字幕烧录
│       │   │   └── ...
│       │   ├── references/             # 参考文档
│       │   └── templates/              # 模板文件
│       │
│       └── baoyu-post-to-x-video/      # Twitter 发布 Skill ⭐
│
└── youtube_clips_pro/                  # 输出目录（.gitignore）
    └── [生成的视频文件]
```

### 为什么代码在 `.claude/skills/` 下？

这是一个**专为 AI Agent 设计的项目结构**：

1. **`.claude/skills/`** 是 Claude Code 读取 Skills 的标准路径
2. AI Agent 执行任务时会从这里加载 `SKILL.md` 和相关脚本
3. 根目录保持干净，只包含 Git 配置和说明文档
4. 输出文件（`youtube_clips_pro/`）被 `.gitignore` 排除，不会污染仓库

---

## ⚙️ 配置说明

编辑 `.claude/skills/Youtube-clipper-skill/.env` 文件：

```bash
# FFmpeg 路径（留空则自动检测）
FFMPEG_PATH=

# 输出目录（相对于项目根目录）
OUTPUT_DIR=./youtube_clips_pro

# 视频质量限制（720, 1080, 1440, 2160）
MAX_VIDEO_HEIGHT=1080

# 翻译批次大小（推荐 20-25）
TRANSLATION_BATCH_SIZE=20

# 目标翻译语言
TARGET_LANGUAGE=中文

# 目标章节时长（秒，推荐 180-300）
TARGET_CHAPTER_DURATION=180

# YouTube 下载代理（可选）
YT_DLP_PROXY=

# 浏览器选择（chrome, firefox, safari）
BROWSER_FOR_COOKIES=chrome
```

---

## 🔧 常见问题

### 1. FFmpeg 字幕烧录失败

**错误信息**: `Option not found: subtitles` 或 `filter not found`

**原因**: FFmpeg 没有 libass 支持

**解决方案**:

```bash
# macOS
brew uninstall ffmpeg
brew install ffmpeg-full

# Ubuntu
sudo apt install ffmpeg libass-dev

# 验证
ffmpeg -filters 2>&1 | grep subtitles
```

### 2. YouTube 下载失败（机器人检测）

**错误信息**: `Sign in to confirm you're not a bot`

**解决方案**: 使用浏览器 Cookie

```bash
# 在下载命令中添加 --browser 参数
python3 scripts/video_clipper_pro.py download <URL> --browser chrome
```

确保您已经在 Chrome 浏览器中登录 YouTube。

### 3. 找不到 Skill

**问题**: Claude 提示找不到 youtube-clipper Skill

**解决方案**:

```bash
# 检查 Skill 目录是否存在
ls -la .claude/skills/Youtube-clipper-skill/SKILL.md

# 如果不存在，检查是否在正确的项目目录
pwd  # 应该显示 ~/youtube_clips 或您克隆的路径

# 确保在项目根目录下启动 Claude Code
cd ~/youtube_clips
```

### 4. Python 依赖缺失

**错误信息**: `ModuleNotFoundError: No module named 'yt_dlp'`

**解决方案**:

```bash
cd .claude/skills/Youtube-clipper-skill/
pip install yt-dlp pysrt python-dotenv

# 或者使用 pip3
pip3 install yt-dlp pysrt python-dotenv
```

### 5. 翻译质量不佳

**解决方案**:

1. 在 `context.json` 中添加术语表
2. 调整 `TRANSLATION_BATCH_SIZE`（减小批次可能提高质量）
3. 使用 TranslationAgent 的反馈机制要求重新翻译

### 6. Twitter 发布失败

**解决方案**:

1. 确保已安装 `baoyu-post-to-x-video` Skill
2. 检查浏览器是否已登录 Twitter/X
3. 查看 Skill 文档了解详细配置

---

## 🤝 贡献

欢迎贡献！请：

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启一个 Pull Request

---

## 📄 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情。

---

## 🙏 致谢

- **[op7418/Youtube-clipper-skill](https://github.com/op7418/Youtube-clipper-skill)** - 原始项目，提供了坚实的基础
- **[Claude Code](https://claude.ai/claude-code)** - 强大的 AI 编程助手
- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** - YouTube 下载引擎
- **[FFmpeg](https://ffmpeg.org/)** - 视频处理利器
- **[baoyu-io/post-to-x-video](https://github.com/baoyu-io/post-to-x-video)** - Twitter 发布 Skill

---

## 📞 联系方式

如有问题或建议，请：
- 提交 [GitHub Issue](https://github.com/Mr-funny/Youtube-clipper-skill/issues)
- 或通过 Pull Request 贡献代码

---

<div align="center">

**Made with ❤️ based on [op7418's work](https://github.com/op7418/Youtube-clipper-skill)**

**Enhanced with Agentic Workflow by [Mr-funny](https://github.com/Mr-funny)**

如果这个项目对您有帮助，请给它一个 ⭐️

</div>