名称： TubeScribe
描述： "YouTube 视频摘要工具，具备说话人检测、格式化文档和音频输出功能。开箱即用，支持 macOS 内置 TTS。可选推荐工具（pandoc、ffmpeg、mlx-audio）可提升质量。访问 YouTube 需要网络。无需付费 API 或订阅。当用户发送 YouTube 链接或要求总结/转录 YouTube 视频时使用。"
元数据：
{
"openclaw":
{
"emoji": "🎬",
"requires": { "bins": ["summarize"] }
}
}

TubeScribe 🎬

将任何 YouTube 视频转化为精美的文档 + 音频摘要。

只需提供一个 YouTube 链接 → 即可获得一份精美的转录稿，包含说话人标签、关键引述、可跳转回视频的时间戳，以及一份可供随时收听的音频摘要。

💸 完全免费，无需付费 API

• 无需订阅或 API 密钥 — 开箱即用
• 本地处理 — 转录、说话人检测和 TTS 均在您的设备上运行
• 需要网络访问 — 从 YouTube 获取数据（字幕、元数据、评论）需要互联网
• 数据不上传 — 所有处理均在本地进行，不发送到外部服务
• 安全的子代理 — 启动的子代理有严格指令：不安装软件，除访问 YouTube 外不进行网络调用

✨ 核心功能

• 📄 带摘要和关键引述的转录稿 — 可导出为 DOCX、HTML 或 Markdown
• 🎯 智能说话人检测 — 自动识别参与者
• 🔊 音频摘要 — 收听关键要点（MP3/WAV 格式）
• 📝 可点击的时间戳 — 每个引述都直接链接到视频中的对应时刻
• 💬 YouTube 评论分析 — 观众情绪分析和精选评论
• 📋 队列支持 — 发送多个链接，它们将按顺序处理
• 🚀 非阻塞工作流 — 视频在后台处理时，对话可继续进行

🎬 支持各类视频

• 访谈与播客（多说话人检测）
• 讲座与教程（单说话人）
• 音乐视频（歌词提取）
• 新闻与纪录片
• 任何带有字幕的 YouTube 内容

快速开始

当用户发送 YouTube 链接时：
1. 立即 启动一个包含完整处理管道的子代理
2. 回复："🎬 TubeScribe 正在处理 — 完成后我会通知您！"
3. 继续对话（无需等待！）
4. 子代理完成后会通过通知告知，包含视频标题和详细信息

切勿阻塞 — 立即启动子代理并继续对话。

首次设置

运行设置脚本以检查依赖项并配置默认值：

python skills/tubescribe/scripts/setup.py

此脚本检查：summarize CLI、pandoc、ffmpeg、Kokoro TTS

完整工作流（单一子代理）

启动一个执行完整管道的子代理：

sessions_spawn(
    task=f"""
## TubeScribe: 处理 {youtube_url}

⚠️ 重要：请勿安装任何软件。
禁止使用 pip、brew、curl、venv 或下载二进制文件。
如果缺少某个工具，请停止并报告所需内容。

运行完整的处理流程 — 直到所有步骤完成前不要停止。

### 步骤 1：提取
```bash
python3 skills/tubescribe/scripts/tubescribe.py "{youtube_url}"

注意脚本打印的 源文件 和 输出 路径。后续步骤请使用这些确切路径。

步骤 2：读取源 JSON

从步骤 1 的输出中读取源文件路径，并记录：
- metadata.title (用于文件名)
- metadata.video_id
- metadata.channel, upload_date, duration_string

步骤 3：创建格式化 Markdown 文档

写入到步骤 1 的输出路径：

1. # **<标题>**

2. 视频信息块 — 频道、日期、时长、URL（可点击）。每个字段间空一行。

3. ## **参与者** — 带粗体标题的表格：
   | **姓名** | **角色** | **描述** | |----------|----------|-----------------|

4. ## **摘要** — 3-5 段文字总结

5. ## **关键引述** — 5 条最佳引述，附带可点击的 YouTube 时间戳。每条格式如下：
   ```
   "引述内容。" - 12:34

"另一条引述。" - 25:10
`` 使用普通短横线-，而非长破折号—。不要使用块引用>`。仅使用普通段落。

6. ## **观众情绪** (如果存在评论)

7. ## **精选评论** (如果存在评论) — 前 5 条，评论间无空行：
   ```
   评论内容。

- ▲ 123 @作者名

下一条评论内容。

- ▲ 45 @另一位作者
`` 署名行：短横线 + 斜体。评论间仅用空行分隔，不要使用---` 分隔符。

8. ## **完整转录稿** — 合并片段，包含说话人标签和可点击时间戳

步骤 4：创建 DOCX 文档

清理标题以用作文件名（移除特殊字符），然后：

pandoc <输出路径> -o ~/Documents/TubeScribe/<安全标题>.docx

步骤 5：生成音频

将摘要文本写入临时文件，然后使用 TubeScribe 内置的音频生成功能：

# 将摘要写入临时文件（使用 python3 写入，避免 shell 转义问题）
python3 -c "
text = '''你的摘要文本'''
with open('<临时目录>/tubescribe_<视频ID>_summary.txt', 'w') as f:
    f.write(text)
"

# 生成音频（自动从配置中检测引擎、语音、格式）
python3 skills/tubescribe/scripts/tubescribe.py \
  --generate-audio <临时目录>/tubescribe_<视频ID>_summary.txt \
  --audio-output ~/Documents/TubeScribe/<安全标题>_summary

此命令读取 ~/.tubescribe/config.json，并自动使用配置的 TTS 引擎（mlx/kokoro/builtin）、语音混合和语速。输出格式（mp3/wav）来自配置。

步骤 6：清理

python3 skills/tubescribe/scripts/tubescribe.py --cleanup <video_id>

步骤 7：打开文件夹

open ~/Documents/TubeScribe/

报告

告知创建了哪些文件：DOCX 文件名、MP3 文件名 + 时长、视频统计信息。
""",
label="tubescribe",
runTimeoutSeconds=900,
cleanup="delete"
)

**启动子代理后，立即回复：**
> 🎬 TubeScribe 正在处理 - 完成后我会通知您！
然后继续对话。子代理完成时会通过通知告知。

## 配置

配置文件：`~/.tubescribe/config.json`

```json
{
  "output": {
    "folder": "~/Documents/TubeScribe",
    "open_folder_after": true,
    "open_document_after": false,
    "open_audio_after": false
  },
  "document": {
    "format": "docx",
    "engine": "pandoc"
  },
  "audio": {
    "enabled": true,
    "format": "mp3",
    "tts_engine": "mlx"
  },
  "mlx_audio": {
    "path": "~/.openclaw/tools/mlx-audio",
    "model": "mlx-community/Kokoro-82M-bf16",
    "voice": "af_heart",
    "lang_code": "a",
    "speed": 1.05
  },
  "kokoro": {
    "path": "~/.openclaw/tools/kokoro",
    "voice_blend": { "af_heart": 0.6, "af_sky": 0.4 },
    "speed": 1.05
  },
  "processing": {
    "subagent_timeout": 600,
    "cleanup_temp_files": true
  }
}

输出选项

文档选项

音频选项

MLX-Audio 选项（Apple Silicon 首选）

Kokoro PyTorch 选项（备用）

处理选项

评论选项

队列选项

输出结构

~/Documents/TubeScribe/
├── {视频标题}.html         # 格式化文档（或 .docx / .md）
└── {视频标题}_summary.mp3  # 音频摘要（或 .wav）

生成后，会自动打开文件夹（而非单个文件），方便您访问所有内容。

依赖项

必需：
- summarize CLI — brew install steipete/tap/summarize
- Python 3.8+

可选（提升质量）：
- pandoc — DOCX 输出：brew install pandoc
- ffmpeg — MP3 音频：brew install ffmpeg
- yt-dlp — YouTube 评论：brew install yt-dlp
- mlx-audio — Apple Silicon 上最快的 TTS：pip install mlx-audio（使用 MLX 后端运行 Kokoro）
- Kokoro TTS — PyTorch 备用方案：参见 https://github.com/hexgrad/kokoro

yt-dlp 搜索路径

TubeScribe 按顺序检查以下位置：

如果未找到，设置脚本会下载一个独立的二进制文件到工具目录。
工具目录的版本不会与系统安装的版本冲突。

队列处理

当用户在处理一个视频时发送多个 YouTube 链接：

开始前检查

python skills/tubescribe/scripts/tubescribe.py --queue-status

如果已有任务在处理

# 添加到队列，而不是启动并行处理
python skills/tubescribe/scripts/tubescribe.py --queue-add "新链接"
# → 回复："📋 已添加到队列（位置 2）"

完成后

# 检查队列中是否还有更多任务
python skills/tubescribe/scripts/tubescribe.py --queue-next
# → 自动弹出并处理下一个链接

队列命令

批量处理（一次处理多个 URL）

python skills/tubescribe/scripts/tubescribe.py url1 url2 url3

按顺序处理所有 URL，并在最后提供总结。

错误处理

脚本会检测并清晰地报告以下错误：

发生错误时，向用户报告并停止处理该视频。

使用技巧

• 对于长视频（>30 分钟），建议将子代理超时增加到 900 秒
• 说话人检测在清晰的访谈/播客格式下效果最佳
• 单说话人视频（教程、讲座）会自动跳过说话人标签
• 时间戳直接链接到 YouTube 的对应时刻
• 处理多个视频时使用批量模式：tubescribe url1 url2 url3