原生字幕拼图 Agent Skill

这是什么

native-subtitle-quote-image 是一个开源的 Agent Skill 项目（MIT 协议），由 chengyi-ai 开发，目前已获得 2731 个 Star 和 272 个 Fork，最新版本为 v2.10.3。它的核心任务很简单：把一段视频变成一张带有字幕的精美社交长图。

这个 Skill 解决了短视频创作者的一个长期痛点——想要把视频里的精彩台词或字幕做成适合微博、小红书、朋友圈传播的 3:4 竖版长图。传统做法是手动截图然后用图像工具拼接，费时费力。而它通过 AI Agent 自动完成找句子、精确取帧、裁切、拼图、质检的全流程。

项目特别强调两种字幕模式的区分：原生字幕直接裁取视频画面中已烧录的字幕，不识别、不重绘；脚本字幕则把经你审核的台词绘制到真实画面上，并明确属于后期字幕。这两种模式严格分开，绝不混用。

适合谁

自媒体运营者：需要将视频中的金句、观点做成社交传播图；
视频内容创作者：希望快速从自己的视频素材中提取精彩帧；
播客/访谈剪辑师：想把嘉宾的精彩发言做成视觉化摘要；
使用 Codex 或 Claude Code 的 AI Agent 用户：希望通过一句话命令自动完成出图。

能做什么

从本地视频或 YouTube 链接直接出图，经过找句、取帧、拼图、逐张质检，输出 JPG 长图；
支持原生字幕模式：只裁切画面里本来就有的烧录字幕，保留原始像素，不识别不重绘；
支持脚本字幕模式：把你审核过的台词绘制到真实画面上，并标明是后期字幕；
版式紧凑：原生字幕先拼源像素再统一缩放，字幕条之间无空隙；
支持 3:4 固定比例或保留画面原比例（natural 布局）；
提供多机位主图缩放（--hero-zoom）、呼吸缝（--strip-gap）、分隔线（--hero-divider）、说话人前缀、金句强调等高级选项；
支持六句卡预设（--six-line-card），适合更多台词的内容；
既可被 Agent 调用，也可通过 Python 命令行脚本独立运行。

使用前准备

使用前需要准备：

Python 3 环境；
ffmpeg 等视频处理组件（依赖项会自动检查）；
如果你要处理 YouTube 链接，需要额外安装 yt-dlp；
如果使用脚本字幕模式绘制中日韩台词，需要系统有可用的 CJK 字体。

项目提供了环境自检脚本 check_environment.py，它是只读操作，不会自动安装或修改任何软件；缺组件时，Agent 会先说明用途，征得你同意再安装。

安装方法

1. 克隆仓库并安装 Skill（macOS / Linux）:

git clone https://github.com/chengyi-ai/native-subtitle-quote-image.git
cd native-subtitle-quote-image
mkdir -p ~/.codex/skills && cp -R skills/native-subtitle-quote-image ~/.codex/skills/

Windows PowerShell:

New-Item -ItemType Directory -Force "$HOME\.codex\skills" | Out-Null
Copy-Item -Recurse skills\native-subtitle-quote-image "$HOME\.codex\skills\"

2. 安装依赖并自检:

python3 -m pip install -r skills/native-subtitle-quote-image/requirements.txt
python3 skills/native-subtitle-quote-image/scripts/check_environment.py

3. 处理 YouTube 链接需额外安装 yt-dlp:

python3 -m pip install -U "yt-dlp[default]"
python3 skills/native-subtitle-quote-image/scripts/check_environment.py --url-mode

对于 Claude Code，将目录复制到 ~/.claude/skills/ 即可。其他 Agent 使用开放的 Agent Skills 目录格式，把 skills/native-subtitle-quote-image/ 复制到目标 Agent 的 Skills 目录即可。

升级时建议先删除旧目录再复制，避免旧文件残留。

使用示例

安装完成后，重开一个 Agent 任务，说一句话即可调用：

使用 $native-subtitle-quote-image，把这个带内嵌中文字幕的视频做成原生字幕拼图。

其他常见调用场景：

给的是链接：使用 $native-subtitle-quote-image，读取这个 YouTube 链接，先检查下载权限和烧录字幕，再选 3 个适合传播的主题，做成原生字幕拼图并逐张质检。
写稿配图一起做：先根据视频文字稿提炼选题并写文章，再用 $native-subtitle-quote-image 为每个核心观点选真实视频帧并出图；先判断原生或脚本字幕模式，不要混用。
用自己核对过的台词：使用 $native-subtitle-quote-image 的脚本字幕模式，把这份带时间点的中文台词画到真实视频帧上，做成紧凑 3:4 长图并逐张质检。

也可以不用 Agent，直接运行命令行脚本。例如先自检源视频：

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py check-source VIDEO --min-height 720

挑选候选帧：

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py sample VIDEO \
  --start 30 --end 120 --interval 5 --out candidate-contact-sheet.jpg

渲染原生字幕成品：

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render VIDEO \
  --manifest manifest.json --out-dir output-v1 \
  --band-top 0.78 --band-bottom 0.96

渲染脚本字幕成品：

python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py render-script VIDEO \
  --script script.json --out output.jpg --aspect 3:4 --width 1440

风险与注意事项

版权与权限：处理 YouTube 等在线视频时，必须确保你有权下载和处理该视频；Agent 会先检查下载权限。
两种字幕模式绝不能混用：原生模式的字只能来自视频像素；脚本模式的字只能来自已审核的 JSON。如果视频只有可开关的字幕轨，而你要原生字幕，Agent 会先说明限制，经你同意后才改用脚本模式。
固定机位视频风险：大师课、网课式等固定机位录制的视频属于高风险素材，多张主图容易几乎一样。建议优先选多机位、景别有变化的视频。
清晰度限制：--hero-zoom 是裁切后放大，源视频清晰度不足时主图会更模糊，不等于真实清晰度提升。
脚本字幕内容责任：脚本字幕属于后期绘制，不作为人物逐字引语，内容需你自己核对。
环境要求：受限环境下系统临时目录可能没有写权限，需要指定 --tmp-dir 或设置 NSQI_TMP_DIR 环境变量。
输出质检：出图前会检查重复画面（如静态封面图、相邻字幕条几乎相同），不合格会直接报错，需手动修正。

项目使用 MIT 协议，完全免费且开源，授权宽松，可以放心使用。当前版本 v2.10.3 功能完善，社区活跃（0 个未关闭 Issues），是一个可靠的选择。