Initial import of NousResearch/hermes-agent

2026-05-31 09:36:58 +08:00
commit d73ff9b0fb
4188 changed files with 1614916 additions and 0 deletions
@@ -0,0 +1,106 @@
+---
+title: "Gif Search — 通过 curl + jq 搜索/下载 Tenor GIF"
+sidebar_label: "Gif Search"
+description: "通过 curl + jq 搜索/下载 Tenor GIF"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Gif Search
+
+通过 curl + jq 搜索/下载 Tenor GIF。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/media/gif-search` |
+| 版本 | `1.1.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `GIF`, `Media`, `Search`, `Tenor`, `API` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# GIF Search（Tenor API）
+
+通过 Tenor API 使用 curl 直接搜索和下载 GIF，无需额外工具。
+
+## 使用场景
+
+适用于查找反应 GIF、创建视觉内容以及在聊天中发送 GIF。
+
+## 配置
+
+在环境中设置 Tenor API 密钥（添加到 `~/.hermes/.env`）：
+
+```bash
+TENOR_API_KEY=your_key_here
+```
+
+在 https://developers.google.com/tenor/guides/quickstart 免费获取 API 密钥 —— Google Cloud Console Tenor API 密钥免费且具有较高的速率限制。
+
+## 前置条件
+
+- `curl` 和 `jq`（macOS/Linux 标准工具）
+- `TENOR_API_KEY` 环境变量
+
+## 搜索 GIF
+
+```bash
+# 搜索并获取 GIF URL
+curl -s "https://tenor.googleapis.com/v2/search?q=thumbs+up&limit=5&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.gif.url'
+
+# 获取较小的预览版本
+curl -s "https://tenor.googleapis.com/v2/search?q=nice+work&limit=3&key=${TENOR_API_KEY}" | jq -r '.results[].media_formats.tinygif.url'
+```
+
+## 下载 GIF
+
+```bash
+# 搜索并下载排名第一的结果
+URL=$(curl -s "https://tenor.googleapis.com/v2/search?q=celebration&limit=1&key=${TENOR_API_KEY}" | jq -r '.results[0].media_formats.gif.url')
+curl -sL "$URL" -o celebration.gif
+```
+
+## 获取完整元数据
+
+```bash
+curl -s "https://tenor.googleapis.com/v2/search?q=cat&limit=3&key=${TENOR_API_KEY}" | jq '.results[] | {title: .title, url: .media_formats.gif.url, preview: .media_formats.tinygif.url, dimensions: .media_formats.gif.dims}'
+```
+
+## API 参数
+
+| 参数 | 说明 |
+|-----------|-------------|
+| `q` | 搜索查询（空格用 `+` 进行 URL 编码） |
+| `limit` | 最大结果数（1-50，默认 20） |
+| `key` | API 密钥（来自 `$TENOR_API_KEY` 环境变量） |
+| `media_filter` | 过滤格式：`gif`、`tinygif`、`mp4`、`tinymp4`、`webm` |
+| `contentfilter` | 安全级别：`off`、`low`、`medium`、`high` |
+| `locale` | 语言：`en_US`、`es`、`fr` 等 |
+
+## 可用媒体格式
+
+每个结果在 `.media_formats` 下包含多种格式：
+
+| 格式 | 使用场景 |
+|--------|----------|
+| `gif` | 完整质量 GIF |
+| `tinygif` | 小型预览 GIF |
+| `mp4` | 视频版本（文件体积更小） |
+| `tinymp4` | 小型预览视频 |
+| `webm` | WebM 视频 |
+| `nanogif` | 微型缩略图 |
+
+## 注意事项
+
+- 对查询进行 URL 编码：空格用 `+`，特殊字符用 `%XX`
+- 在聊天中发送时，`tinygif` URL 更轻量
+- GIF URL 可直接用于 markdown：`![alt](https://github.com/NousResearch/hermes-agent/blob/main/skills/media/gif-search/url)`
@@ -0,0 +1,189 @@
+---
+title: "Heartmula — HeartMuLa：基于歌词与标签的类 Suno 歌曲生成"
+sidebar_label: "Heartmula"
+description: "HeartMuLa：基于歌词与标签的类 Suno 歌曲生成"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Heartmula
+
+HeartMuLa：基于歌词与标签的类 Suno 歌曲生成。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/media/heartmula` |
+| 版本 | `1.0.0` |
+| 平台 | linux, macos, windows |
+| 标签 | `music`, `audio`, `generation`, `ai`, `heartmula`, `heartcodec`, `lyrics`, `songs` |
+| 相关 skill | `audiocraft` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# HeartMuLa - 开源音乐生成
+
+## 概述
+HeartMuLa 是一系列开源音乐基础模型（Apache-2.0），可根据歌词和标签生成音乐，支持多语言。能从歌词与标签生成完整歌曲，是开源领域中可与 Suno 媲美的方案。包含：
+- **HeartMuLa** — 音乐语言模型（3B/7B），从歌词与标签生成音乐
+- **HeartCodec** — 12.5Hz 音乐编解码器，用于高保真音频重建
+- **HeartTranscriptor** — 基于 Whisper 的歌词转录工具
+- **HeartCLAP** — 音频-文本对齐模型
+
+## 使用场景
+- 用户希望从文本描述生成音乐/歌曲
+- 用户需要开源的 Suno 替代方案
+- 用户需要本地/离线音乐生成
+- 用户询问 HeartMuLa、heartlib 或 AI 音乐生成相关内容
+
+## 硬件要求
+- **最低配置**：8GB 显存，配合 `--lazy_load true`（按需加载/卸载模型）
+- **推荐配置**：16GB+ 显存，可在单 GPU 上流畅运行
+- **多 GPU**：使用 `--mula_device cuda:0 --codec_device cuda:1` 将模型分布到多张 GPU
+- 3B 模型在 lazy_load 模式下峰值显存约为 6.2GB
+
+## 安装步骤
+
+### 1. 克隆仓库
+```bash
+cd ~/  # 或目标目录
+git clone https://github.com/HeartMuLa/heartlib.git
+cd heartlib
+```
+
+### 2. 创建虚拟环境（需要 Python 3.10）
+```bash
+uv venv --python 3.10 .venv
+. .venv/bin/activate
+uv pip install -e .
+```
+
+### 3. 修复依赖兼容性问题
+
+**重要**：截至 2026 年 2 月，固定的依赖版本与较新的包存在冲突。请应用以下修复：
+
+```bash
+# 升级 datasets（旧版本与当前 pyarrow 不兼容）
+uv pip install --upgrade datasets
+
+# 升级 transformers（需要兼容 huggingface-hub 1.x）
+uv pip install --upgrade transformers
+```
+
+### 4. 修补源代码（transformers 5.x 必须执行）
+
+**补丁 1 — RoPE 缓存修复**，文件：`src/heartlib/heartmula/modeling_heartmula.py`：
+
+在 `HeartMuLa` 类的 `setup_caches` 方法中，在 `reset_caches` 的 try/except 块之后、`with device:` 块之前，添加 RoPE 重新初始化代码：
+
+```python
+# Re-initialize RoPE caches that were skipped during meta-device loading
+from torchtune.models.llama3_1._position_embeddings import Llama3ScaledRoPE
+for module in self.modules():
+    if isinstance(module, Llama3ScaledRoPE) and not module.is_cache_built:
+        module.rope_init()
+        module.to(device)
+```
+
+**原因**：`from_pretrained` 首先在 meta 设备上创建模型；`Llama3ScaledRoPE.rope_init()` 在 meta 张量上跳过缓存构建，且在权重加载到真实设备后也不会重建。
+
+**补丁 2 — HeartCodec 加载修复**，文件：`src/heartlib/pipelines/music_generation.py`：
+
+在所有 `HeartCodec.from_pretrained()` 调用中添加 `ignore_mismatched_sizes=True`（共 2 处：`__init__` 中的 eager 加载和 `codec` 属性中的 lazy 加载）。
+
+**原因**：VQ codebook 的 `initted` buffer 在 checkpoint 中形状为 `[1]`，而模型中为 `[]`。数据相同，仅为标量与 0 维张量的差异，可安全忽略。
+
+### 5. 下载模型检查点
+```bash
+cd heartlib  # 项目根目录
+hf download --local-dir './ckpt' 'HeartMuLa/HeartMuLaGen'
+hf download --local-dir './ckpt/HeartMuLa-oss-3B' 'HeartMuLa/HeartMuLa-oss-3B-happy-new-year'
+hf download --local-dir './ckpt/HeartCodec-oss' 'HeartMuLa/HeartCodec-oss-20260123'
+```
+
+三个检查点可并行下载，总大小为数 GB。
+
+## GPU / CUDA
+
+HeartMuLa 默认使用 CUDA（`--mula_device cuda --codec_device cuda`）。如果用户已安装支持 CUDA 的 PyTorch 并拥有 NVIDIA GPU，则无需额外配置。
+
+- 已安装的 `torch==2.4.1` 开箱即支持 CUDA 12.1
+- `torchtune` 可能显示版本为 `0.4.0+cpu` — 这只是包元数据，实际仍通过 PyTorch 使用 CUDA
+- 如需确认 GPU 是否被使用，可查看输出中的 "CUDA memory" 行（例如 "CUDA memory before unloading: 6.20 GB"）
+- **没有 GPU？** 可使用 `--mula_device cpu --codec_device cpu` 在 CPU 上运行，但生成速度会**极慢**（单首歌曲可能需要 30-60 分钟以上，而 GPU 约需 4 分钟）。CPU 模式还需要大量内存（12GB+ 空闲）。如果用户没有 NVIDIA GPU，建议使用云 GPU 服务（Google Colab 免费 T4、Lambda Labs 等）或访问在线 demo：https://heartmula.github.io/
+
+## 使用方法
+
+### 基本生成
+```bash
+cd heartlib
+. .venv/bin/activate
+python ./examples/run_music_generation.py \
+  --model_path=./ckpt \
+  --version="3B" \
+  --lyrics="./assets/lyrics.txt" \
+  --tags="./assets/tags.txt" \
+  --save_path="./assets/output.mp3" \
+  --lazy_load true
+```
+
+### 输入格式
+
+**标签**（逗号分隔，无空格）：
+```
+piano,happy,wedding,synthesizer,romantic
+```
+或
+```
+rock,energetic,guitar,drums,male-vocal
+```
+
+**歌词**（使用方括号结构标签）：
+```
+[Intro]
+
+[Verse]
+Your lyrics here...
+
+[Chorus]
+Chorus lyrics...
+
+[Bridge]
+Bridge lyrics...
+
+[Outro]
+```
+
+### 关键参数
+| 参数 | 默认值 | 说明 |
+|-----------|---------|-------------|
+| `--max_audio_length_ms` | 240000 | 最大时长（毫秒，240s = 4 分钟） |
+| `--topk` | 50 | Top-k 采样 |
+| `--temperature` | 1.0 | 采样温度（temperature） |
+| `--cfg_scale` | 1.5 | 无分类器引导（classifier-free guidance）缩放比例 |
+| `--lazy_load` | false | 按需加载/卸载模型（节省显存） |
+| `--mula_dtype` | bfloat16 | HeartMuLa 的数据类型（推荐 bf16） |
+| `--codec_dtype` | float32 | HeartCodec 的数据类型（推荐 fp32 以保证质量） |
+
+### 性能
+- RTF（实时率）≈ 1.0 — 生成一首 4 分钟的歌曲约需 4 分钟
+- 输出：MP3，48kHz 立体声，128kbps
+
+## 注意事项
+1. **不要对 HeartCodec 使用 bf16** — 会降低音频质量。请使用 fp32（默认值）。
+2. **标签可能被忽略** — 已知问题（#90）。歌词往往占主导地位；建议尝试调整标签顺序。
+3. **macOS 上 Triton 不可用** — GPU 加速仅支持 Linux/CUDA。
+4. 上游 issue 中报告了 **RTX 5080 不兼容**问题。
+5. 依赖版本冲突需要按上述说明手动升级并打补丁。
+
+## 相关链接
+- 仓库：https://github.com/HeartMuLa/heartlib
+- 模型：https://huggingface.co/HeartMuLa
+- 论文：https://arxiv.org/abs/2601.10547
+- 许可证：Apache-2.0
@@ -0,0 +1,98 @@
+---
+title: "Songsee — 通过 CLI 生成音频频谱图/特征（mel、chroma、MFCC）"
+sidebar_label: "Songsee"
+description: "通过 CLI 生成音频频谱图/特征（mel、chroma、MFCC）"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Songsee
+
+通过 CLI 生成音频频谱图/特征（mel、chroma、MFCC）。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/media/songsee` |
+| 版本 | `1.0.0` |
+| 作者 | community |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Audio`, `Visualization`, `Spectrogram`, `Music`, `Analysis` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# songsee
+
+从音频文件生成频谱图（spectrogram）及多面板音频特征可视化图。
+
+## 前置条件
+
+需要安装 [Go](https://go.dev/doc/install)：
+```bash
+go install github.com/steipete/songsee/cmd/songsee@latest
+```
+
+可选：安装 `ffmpeg` 以支持 WAV/MP3 以外的格式。
+
+## 快速开始
+
+```bash
+# 基本频谱图
+songsee track.mp3
+
+# 保存到指定文件
+songsee track.mp3 -o spectrogram.png
+
+# 多面板可视化网格
+songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux
+
+# 时间切片（从 12.5s 开始，持续 8s）
+songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg
+
+# 从 stdin 读取
+cat track.mp3 | songsee - --format png -o out.png
+```
+
+## 可视化类型
+
+使用 `--viz` 并以逗号分隔多个值：
+
+| 类型 | 描述 |
+|------|-------------|
+| `spectrogram` | 标准频率频谱图 |
+| `mel` | Mel 尺度频谱图 |
+| `chroma` | 音高类别分布 |
+| `hpss` | 谐波/打击乐分离 |
+| `selfsim` | 自相似矩阵 |
+| `loudness` | 随时间变化的响度 |
+| `tempogram` | 节拍估计 |
+| `mfcc` | Mel 频率倒谱系数 |
+| `flux` | 频谱通量（起始点检测） |
+
+多个 `--viz` 类型将以网格形式渲染为单张图像。
+
+## 常用标志
+
+| 标志 | 描述 |
+|------|-------------|
+| `--viz` | 可视化类型（逗号分隔） |
+| `--style` | 色彩调色板：`classic`、`magma`、`inferno`、`viridis`、`gray` |
+| `--width` / `--height` | 输出图像尺寸 |
+| `--window` / `--hop` | FFT 窗口和跳跃大小 |
+| `--min-freq` / `--max-freq` | 频率范围过滤 |
+| `--start` / `--duration` | 音频时间切片 |
+| `--format` | 输出格式：`jpg` 或 `png` |
+| `-o` | 输出文件路径 |
+
+## 注意事项
+
+- WAV 和 MP3 原生解码；其他格式需要 `ffmpeg`
+- 输出图像可使用 `vision_analyze` 进行检查，以实现自动化音频分析
+- 适用于比较音频输出、调试合成过程或记录音频处理流水线
@@ -0,0 +1,151 @@
+---
+title: "Spotify — Spotify：播放、搜索、队列、管理播放列表和设备"
+sidebar_label: "Spotify"
+description: "Spotify：播放、搜索、队列、管理播放列表和设备"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Spotify
+
+Spotify：播放、搜索、队列、管理播放列表和设备。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/media/spotify` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `spotify`, `music`, `playback`, `playlists`, `media` |
+| 相关 skill | [`gif-search`](/user-guide/skills/bundled/media/media-gif-search) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Spotify
+
+通过 Hermes Spotify 工具集（7 个工具）控制用户的 Spotify 账户。设置指南：https://hermes-agent.nousresearch.com/docs/user-guide/features/spotify
+
+## 何时使用此 skill
+
+用户说出类似以下内容时："play X"、"pause"、"skip"、"queue up X"、"what's playing"、"search for X"、"add to my X playlist"、"make a playlist"、"save this to my library" 等。
+
+## 7 个工具
+
+- `spotify_playback` — play、pause、next、previous、seek、set_repeat、set_shuffle、set_volume、get_state、get_currently_playing、recently_played
+- `spotify_devices` — list、transfer
+- `spotify_queue` — get、add
+- `spotify_search` — 搜索曲库
+- `spotify_playlists` — list、get、create、add_items、remove_items、update_details
+- `spotify_albums` — get、tracks
+- `spotify_library` — 使用 `kind: "tracks"|"albums"` 进行 list/save/remove
+
+修改播放状态的操作需要 Spotify Premium；搜索/曲库/播放列表操作在免费版上也可使用。
+
+## 规范模式（最小化工具调用次数）
+
+### "Play &lt;artist/track/album>"
+一次搜索，然后通过 URI 播放。除非用户要求选项，否则**不要**循环遍历搜索结果并逐一描述。
+
+```
+spotify_search({"query": "miles davis kind of blue", "types": ["album"], "limit": 1})
+→ got album URI spotify:album:1weenld61qoidwYuZ1GESA
+spotify_playback({"action": "play", "context_uri": "spotify:album:1weenld61qoidwYuZ1GESA"})
+```
+
+对于"play some &lt;artist>"（无特定歌曲），优先使用 `types: ["artist"]` 并播放艺术家的 context URI — Spotify 会自动处理智能随机播放。如果用户说"the song"或"that track"，则搜索 `types: ["track"]` 并将 `uris: [track_uri]` 传给 play。
+
+### "What's playing?" / "What am I listening to?"
+单次调用——不要在 get_currently_playing 之后再链式调用 get_state。
+
+```
+spotify_playback({"action": "get_currently_playing"})
+```
+
+如果返回 204/空（`is_playing: false`），告知用户当前没有播放内容。不要重试。
+
+### "Pause" / "Skip" / "Volume 50"
+直接执行操作，无需预先检查状态。
+
+```
+spotify_playback({"action": "pause"})
+spotify_playback({"action": "next"})
+spotify_playback({"action": "set_volume", "volume_percent": 50})
+```
+
+### "Add to my &lt;playlist name> playlist"
+1. 用 `spotify_playlists list` 按名称查找播放列表 ID
+2. 获取曲目 URI（来自当前播放，或通过搜索）
+3. 用 playlist_id 和 URI 调用 `spotify_playlists add_items`
+
+```
+spotify_playlists({"action": "list"})
+→ found "Late Night Jazz" = 37i9dQZF1DX4wta20PHgwo
+spotify_playback({"action": "get_currently_playing"})
+→ current track uri = spotify:track:0DiWol3AO6WpXZgp0goxAV
+spotify_playlists({"action": "add_items",
+                   "playlist_id": "37i9dQZF1DX4wta20PHgwo",
+                   "uris": ["spotify:track:0DiWol3AO6WpXZgp0goxAV"]})
+```
+
+### "Create a playlist called X and add the last 3 songs I played"
+```
+spotify_playback({"action": "recently_played", "limit": 3})
+spotify_playlists({"action": "create", "name": "Focus 2026"})
+→ got playlist_id back in response
+spotify_playlists({"action": "add_items", "playlist_id": <id>, "uris": [<3 uris>]})
+```
+
+### "Save / unsave / is this saved?"
+使用 `spotify_library` 并指定正确的 `kind`。
+
+```
+spotify_library({"kind": "tracks", "action": "save", "uris": ["spotify:track:..."]})
+spotify_library({"kind": "albums", "action": "list", "limit": 50})
+```
+
+### "Transfer playback to my &lt;device>"
+```
+spotify_devices({"action": "list"})
+→ pick the device_id by matching name/type
+spotify_devices({"action": "transfer", "device_id": "<id>", "play": true})
+```
+
+## 关键失败模式
+
+**`403 Forbidden — No active device found`** 出现在任何播放操作上，意味着 Spotify 在任何地方都未运行。告知用户："请先在手机/桌面/网页播放器上打开 Spotify，随便播放一首曲目几秒钟，然后重试。"不要盲目重试工具调用——结果会完全相同。可以调用 `spotify_devices list` 确认；空列表意味着没有活跃设备。
+
+**`403 Forbidden — Premium required`** 意味着用户使用的是免费版，并尝试修改播放状态。不要重试；告知用户此操作需要 Premium。读取操作仍然有效（搜索、播放列表、曲库、get_state）。
+
+**`get_currently_playing` 返回 `204 No Content`** 不是错误——它表示当前没有播放内容。工具返回 `is_playing: false`。直接将此情况告知用户即可。
+
+**`429 Too Many Requests`** = 速率限制。等待后重试一次。如果持续发生，说明你在循环——停止。
+
+**`401 Unauthorized` 重试后仍出现** — 刷新令牌已被撤销。告知用户重新运行 `hermes auth spotify`。
+
+## URI 和 ID 格式
+
+Spotify 使用三种可互换的 ID 格式。工具接受所有三种并会自动规范化：
+
+- URI：`spotify:track:0DiWol3AO6WpXZgp0goxAV`（推荐）
+- URL：`https://open.spotify.com/track/0DiWol3AO6WpXZgp0goxAV`
+- 裸 ID：`0DiWol3AO6WpXZgp0goxAV`
+
+如有疑问，使用完整 URI。搜索结果在 `uri` 字段中返回 URI——直接传入即可。
+
+实体类型：`track`、`album`、`artist`、`playlist`、`show`、`episode`。请为操作使用正确的类型——`spotify_playback.play` 的 `context_uri` 期望 album/playlist/artist；`uris` 期望曲目 URI 数组。
+
+## 禁止事项
+
+- **不要在每次操作前调用 `get_state`。** Spotify 接受 play/pause/skip 而无需预检。仅在用户询问"what's playing"或需要推断设备/曲目时才检查状态。
+- **除非被要求，否则不要描述搜索结果。** 如果用户说"play X"，搜索、获取排名第一的 URI、播放。如果播放错了，他们自己会听出来。
+- **不要在 `403 Premium required` 或 `403 No active device` 时重试。** 在用户采取行动之前，这些错误是永久性的。
+- **不要用 `spotify_search` 按名称查找播放列表** — 那会搜索 Spotify 公开曲库。用户播放列表来自 `spotify_playlists list`。
+- **不要在 `spotify_library` 中将 `kind: "tracks"` 与专辑 URI 混用**（反之亦然）。工具会规范化 ID，但 API 端点不同。
@@ -0,0 +1,93 @@
+---
+title: "Youtube Content — YouTube 视频转文字摘要、推文、博客"
+sidebar_label: "Youtube Content"
+description: "YouTube 视频转文字摘要、推文、博客"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Youtube Content
+
+YouTube 视频转文字摘要、推文、博客。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 内置（默认安装） |
+| 路径 | `skills/media/youtube-content` |
+| 平台 | linux, macos, windows |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# YouTube Content Tool
+
+## 使用时机
+
+当用户分享 YouTube URL 或视频链接、要求总结视频、请求获取文字稿，或希望提取并重新格式化任意 YouTube 视频内容时使用。可将文字稿转换为结构化内容（章节、摘要、推文线程、博客文章）。
+
+从 YouTube 视频中提取文字稿并将其转换为实用格式。
+
+## 安装
+
+```bash
+pip install youtube-transcript-api
+```
+
+## 辅助脚本
+
+`SKILL_DIR` 是包含此 SKILL.md 文件的目录。该脚本接受任何标准 YouTube URL 格式、短链接（youtu.be）、Shorts、嵌入链接、直播链接，或原始 11 位视频 ID。
+
+```bash
+# JSON 输出（含元数据）
+python3 SKILL_DIR/scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID"
+
+# 纯文本输出（适合管道传递给后续处理）
+python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only
+
+# 带时间戳
+python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps
+
+# 指定语言并设置回退链
+python3 SKILL_DIR/scripts/fetch_transcript.py "URL" --language tr,en
+```
+
+## 输出格式
+
+获取文字稿后，根据用户需求选择以下格式：
+
+- **章节（Chapters）**：按主题转换分组，输出带时间戳的章节列表
+- **摘要（Summary）**：对整个视频进行 5–10 句的简洁概述
+- **章节摘要（Chapter summaries）**：各章节附带简短段落摘要
+- **推文线程（Thread）**：Twitter/X 线程格式——编号帖子，每条不超过 280 字符
+- **博客文章（Blog post）**：含标题、各节及关键要点的完整文章
+- **引用（Quotes）**：带时间戳的精彩引用
+
+### 示例——章节输出
+
+```
+00:00 Introduction — host opens with the problem statement
+03:45 Background — prior work and why existing solutions fall short
+12:20 Core method — walkthrough of the proposed approach
+24:10 Results — benchmark comparisons and key takeaways
+31:55 Q&A — audience questions on scalability and next steps
+```
+
+## 工作流程
+
+1. **获取**：使用辅助脚本并加上 `--text-only --timestamps` 参数获取文字稿。
+2. **验证**：确认输出非空且语言符合预期。若为空，去掉 `--language` 参数重试以获取任意可用文字稿。若仍为空，告知用户该视频可能已禁用文字稿。
+3. **分块（如需）**：若文字稿超过约 50K 字符，将其拆分为有重叠的块（约 40K，重叠 2K），逐块摘要后再合并。
+4. **转换**：将内容转换为用户请求的输出格式。若用户未指定格式，默认输出摘要。
+5. **校验**：重新阅读转换后的输出，在呈现前检查连贯性、时间戳准确性及完整性。
+
+## 错误处理
+
+- **文字稿已禁用**：告知用户；建议其在视频页面检查字幕是否可用。
+- **视频不可用或为私密视频**：转达错误信息，请用户核实 URL。
+- **无匹配语言**：去掉 `--language` 参数重试以获取任意可用文字稿，并向用户说明实际语言。
+- **缺少依赖**：执行 `pip install youtube-transcript-api` 后重试。