# native-subtitle-quote-image

Adopt this skill: https://proskills.md/skills/other/chengyi-ai-native-subtitle-quote-image-skills-native-subtitle-quote-image

Page: https://proskills.md/skills/other/chengyi-ai-native-subtitle-quote-image-skills-native-subtitle-quote-image
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/native-subtitle-quote-image/SKILL.md
size: 25039
sha: 3a97a8c4e5fa17ec50275ede800a79cfc1db2b25
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/SKILL.md

````text
---
name: native-subtitle-quote-image
description: 将本地视频或用户有权处理的在线视频，经过来源获取、文字稿定位、选题选句、精确取帧、紧凑裁切、拼图和逐张质检，制作成 3:4 或保留画面原比例的视频字幕长图。支持两种明确分开的输出：保留画面内已烧录字幕的原生字幕模式，以及把已审核的时间点与台词绘制到真实视频帧上的脚本字幕模式。用户要求原生字幕截图、字幕帧拼图、YouTube 金句长图、台词截图、不重绘字幕、自定义中文台词，或调整主图比例、字幕区域、台词间隔和美感时使用。
---

# 视频字幕拼图

先确认用户想要的字幕模式，再判断素材是否支持。不要把两种模式混为一种，也不要默默从原生字幕切到绘制字幕。

## 开始时确认模式

如果用户没有明确指定模式，先用用户当前使用的语言询问，并简短说明两种选择。中文提问可直接使用：

> 您当前是选择原生字幕还是脚本字幕？原生字幕会保留视频画面里已有的字幕，不重绘文字；脚本字幕会把您确认过的台词或翻译后期绘制到真实视频帧上，并标明是后期字幕。

用户已明确说“原生字幕”“保留画面原字幕”“不重绘字幕”，或“脚本字幕”“把指定台词/翻译绘制到画面上”时，按其选择继续，不重复询问。用户尚未选择时，可以只读检查素材以说明哪种模式可行，但不要执行模式专属的渲染；等用户选择后再继续。若所选模式与素材不匹配，说明具体原因并征求用户是否改选，不能自行切换。

## 非阻塞版本检查

每个新任务开始、处理素材之前运行一次：

```bash
python3 "<SKILL_DIR>/scripts/check_update.py" --json
```

- 脚本从 Skill 内的 `VERSION` 读取本地版本，只访问本项目的 GitHub Latest Release；默认 24 小时内复用一次缓存。
- 结果为 `update_available` 时，用一句话告诉用户当前版本、最新版本和 Release 链接，然后继续当前任务。只提醒，不自动更新、不覆盖本地 Skill。
- 结果为 `up_to_date` 时无需打扰用户。结果为 `unavailable` 时也不要阻塞当前任务；若只是运行环境禁止联网，可申请对 GitHub API 的只读访问并用 `--force` 重试一次，未获授权就继续任务。
- 缓存只包含检查时间、最新版本号和 Release 链接，不写入仓库，也不记录账号、素材或使用行为。

## 模式路由

| 条件 | 模式 | 成品文字来源 | 命令 |
|---|---|---|---|
| 关闭播放器 CC 后，截图里仍有字幕；用户要求保留原字幕 | **原生字幕模式** | 视频画面像素 | `render` |
| 视频没有需要的烧录字幕，但用户要求把经确认的台词、翻译或观点排成案例风格 | **脚本字幕模式** | 已审核 JSON 中的 `text` | `render-script` |

- 原生模式不得 OCR 后重绘、翻译、改写或覆盖字幕。
- 脚本模式必须明确称为“脚本字幕”或“后期绘制字幕”，不得宣称文字是画面原字幕。
- 脚本台词必须能回到原视频、用户稿件或其他明确来源复核；不编造人名、数据、引语或翻译含义。
- 用户只说“保留原字幕”时，不能因为原字幕难处理就转脚本模式。

## 按任务读参考文件

- **YouTube 等 URL**：先读 [references/yt-dlp-and-transcripts.md](references/yt-dlp-and-transcripts.md)，获取用户有权处理的视频、元数据和辅助时间轴。URL 任务不能在一次公开请求失败后直接退回“只支持本地视频”：若 YouTube 返回机器人登录验证、年龄验证或用户自己的非公开视频限制，先说明原因并取得授权，再按参考文件用 `yt-dlp --cookies-from-browser chrome` 继续。字幕和视频分两条命令下载；下载前用 `yt-dlp -F` 枚举变体并按 AV1 → VP9 → H.264 择优，下载后必须运行 `native_subtitle_stitch.py check-source VIDEO --min-height 720`（解码前 N 秒无错误、分辨率达标）才能继续；视频报 HTTP 403 或自检失败时按参考文件的格式回退表逐级换变体，低于 720p 的级别须先征得用户确认，每次尝试记入 `download-attempts.log`；字幕报 429 时缩减语言并放慢请求，都不要无限重试。调 yt-dlp 优先用 `scripts/fetch_source.py`：它会识别 403/429 并按类型做有上限的退避重试，自动写 `download-attempts.log`，不静默失败。
- **读长视频 → 选题 → 写文章/帖子 → 配图**：读 [references/end-to-end-workflow.md](references/end-to-end-workflow.md)。
- **台词条太高、间隔太宽、缺少美感**：读 [references/visual-style.md](references/visual-style.md)。
- **报错、出图异常或结果不对**：先查 [references/troubleshooting.md](references/troubleshooting.md)，按「症状 → 先查什么 → 怎么处理」逐项排查。
- **本地短视频且时间点已确定**：直接执行下面的核心流程。

## 环境与路径

将 `<SKILL_DIR>` 解析为当前 `SKILL.md` 所在目录的绝对路径；不要假设 Agent 的工作目录就是 Skill 目录。

URL 模式的下载入口（包装 yt-dlp，带 403/429 退避重试与尝试日志）：

```bash
# 元数据自检（不带 Cookie 的第一步）
python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode metadata

# 字幕：先 yt-dlp --list-subs 看真实标签，再只请求需要的一两个
python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode subs \
  --sub-langs zh-Hans,en-orig -o "source/%(id)s/%(id)s.%(ext)s"

# 视频：格式回退表每级换一次 -f
python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode video \
  -f "bv*[height<=1080][vcodec^=av01]+ba" -o "source/%(id)s/%(id)s.%(ext)s"
```

- 429（请求过密）按 `--backoff`×2^n 退避重试，最多 `--retries` 次（默认 3，上限 6，单次等待封顶 600s）。
- 403 始终最多重试 1 次；它通常是 yt-dlp 版本落后或该格式签名失效，要靠升级和换 `-f` 解决，而不是多试几次。
- 登录验证、年龄验证类报错**不重试**，直接停下并要求先取得用户授权；授权后用 `--extra --cookies-from-browser chrome` 透传，脚本不自行添加 Cookie 参数。
- 每次尝试（含成功）记入 `download-attempts.log`，失败时把 yt-dlp 原始报错和处理建议一起输出到 stderr，退出码非零。
- 它不绕过 DRM、付费墙、地区限制或平台风控；重试耗尽就停下汇报，不换 IP、不换账号、不遍历浏览器配置。

```bash
# 本地原生字幕
python3 "<SKILL_DIR>/scripts/check_environment.py"

# 中日韩脚本字幕
python3 "<SKILL_DIR>/scripts/check_environment.py" --script-mode

# URL + 脚本字幕
python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode --script-mode
```

核心依赖为 Python 3.10+、Pillow，以及 FFmpeg 或 `imageio-ffmpeg`。URL 模式另需 `yt-dlp` 和 YouTube 完整解析所需的 JavaScript runtime。环境检查只报告状态；缺失时先说明用途并取得授权，再运行：

```bash
python3 -m pip install -r "<SKILL_DIR>/requirements.txt"
```

不擅自修改系统 Python、shell 配置、浏览器 Cookies 或包管理器。Chrome Cookie 只是在无 Cookie 请求被 YouTube 登录验证拦截后的受控恢复路径；首次读取前必须说明用途并取得用户授权。

## 共同的默认版式

- 原生字幕默认使用内容自适应布局：保留源宽度，高度为主图和字幕条之和，整图统一等比缩放。用户未指定比例时，不主动添加 `--aspect 3:4`。
- 脚本字幕默认输出 3:4、1440×1920。
- 默认使用 5 个严格递增的时间点：第一帧是主画面，其余四帧是字幕条。
- 两种模式每张图最多 7 个时间点（1 个主画面 + 6 个字幕条）；台词更多时拆成多张图，不压缩字幕条。
- 脚本固定布局的 4 个字幕条时，主画面约占 70%，每条约占 7.5%。原生模式不强制这个比例，第一句和后续字幕必须保持同一缩放倍数；原视频字号不同则保留差异，不重绘文字。两种模式条间距都为 0。
- 可选 `render-script --six-line-card` 使用 6 个严格递增的时间点：首句画在主画面底部，其余 5 句各占连续字幕条；固定 3:4 布局，1080×1440 时主画面 870px、每条 114px，六句行距一致。原版默认布局不变。
- 原生模式显式 `--aspect 3:4` 或 `--layout fixed` 时，默认 `--fit crop`：自动识别每句字幕左右边界，对整张拼图统一裁去两侧，最多裁到字幕安全边界，剩余差额留黑边；任一句识别不到字幕边界时不裁切、整图留边。人物偏离中心时用 `--crop-center`（0–1）移动裁切窗口；用户要求不裁画面时用 `--fit pad`。不得单独放大主图来填满。`--hero-fraction` 只调整源主图裁切高度，受真实帧高度限制，不保证占最终含边画布的该比例。脚本模式只有自动布局确实不适用时才传它。
- 不覆盖已有成品。只有用户明确要替换时才添加 `--overwrite`。
- 受限环境（沙箱、企业策略）下系统 Temp 不可写时，给 `sample` / `band` / `render` / `render-script` 加 `--tmp-dir <可写目录>`，或设置环境变量 `NSQI_TMP_DIR`（参数优先）；默认仍用系统临时目录。目录不存在或不可写会直接报错，抽帧临时文件用完即删。
- 批量 `render` 默认遇到失败就中止。需要容错时加 `--keep-going`：单张失败不影响其余，结束时输出失败清单（序号、时间点、原因）并写入 `渲染失败报告.json`，退出码非零且不生成总览图。向用户报告失败清单，修正 manifest 后加 `--resume` 只补渲缺失或损坏的卡；已有效的图即使 manifest 改了也不会重渲（要重渲先删掉对应图），总览图和时间点文件会重新生成。
- 渲染器遇到重复帧会中止，共三种情形：所有时间点画面几乎相同（疑似静态封面视频或画面冻结）；**任意两个时间点的画面几乎相同**（固定机位素材常见，报错会点名是哪两个时间点）；或原生模式相邻字幕条几乎相同。先用 `sample` 核对画面并向用户说明；不要为了出图直接加 `--allow-duplicate-frames`，只有用户确认确实需要时才加。
- 重复判定阈值可调：`--duplicate-ratio`（`render` 与 `render-script` 均支持）是缩略图上明显变化像素的占比下限，范围 0–0.2，默认 0.005。调高更严（连景别相近的帧也拦），调低更宽松，0 等于只拦完全一致的帧。不要和 `--allow-duplicate-frames` 同时传（互斥）。默认值不满意时先调阈值，而不是直接跳过检查。
- 源视频低清时可输出 1440×1920 版面，但必须说明这不等于真实清晰度提升。

### 保留画面原比例

“人物原比例 / 不裁横屏 / 原生尺寸”是画面几何要求，不等于选择原生字幕模式。字幕来源仍按用户的选择处理。

- 用户要求保留完整横屏构图时使用 `--layout natural`：保留源宽度，高度按主画面与字幕条相加；不再强制 3:4。
- 不传 `--width` 时保留源宽度；传入宽度时仅等比缩放。裁切后禁止把画面 resize 回原来的宽高，也禁止把成品直接拉成 1440×1920。
- 原生字幕模式保留从画面顶部到 `--band-bottom` 的主图和完整字幕条；不重绘文字。
- 脚本字幕模式可用 `--frame-top` / `--frame-bottom` 仅裁去不需要的源画面区域，默认保留全帧。先预览边界，不能裁掉人物关键部位；`--band-center` 相对裁切后的画面。
- `natural` 不与 `--aspect` / `--hero-fraction` 合用；70% 主图验收只适用于脚本固定布局。两种布局都不得非等比拉伸。
- 选源优先多机位、景别有变化的视频；固定单机位（大师课、网课式录制）是高风险素材，六张主图容易几乎一样。确需使用时可传 `--hero-zoom 1.0,0.9,0.95`（`render` 与 `render-script`）：逗号分隔的每卡主图缩放系数，范围 0.8–1.0，按卡循环，默认不启用且输出不变。它只裁掉更多主图画面再放大，不改字幕条、文字、条间距和 `--six-line-card` 几何；原生模式的裁切窗口不进入字幕条。源清晰度不足时主图会更模糊，不等于真实清晰度提升。`render-script` 只出一张图，取第一个系数。
- 缓解手机上的拥挤感可选 `--strip-gap N`（条间黑色呼吸缝，0–8px，默认 0）与 `--hero-divider line`（主图与字幕条之间插入 2px 细分隔线，默认 none），`render` 与 `render-script` 均支持。二者只新增背景像素，不覆盖或重绘任何画面，原生字幕仍只经历整图统一缩放；脚本固定画布总尺寸不变，字幕条相应变矮；与 `--six-line-card` 不兼容（固定几何）。

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
  --script script.json --out natural.jpg --layout natural \
  --frame-bottom 0.72
```

上例 `0.72` 只是裁切示例，不是所有视频的默认值。

## 共同前半流程

### 1. 检查来源与字幕类型

确认本地视频或 URL，素材使用权，视频时长、语言和目标图片数。用真实截图判断字幕是烧录字幕还是独立字幕轨，不能只看是否下载到 VTT/SRT。

时间点不明时，先生成候选帧总览：

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \
  --out candidate-contact-sheet.jpg
```

已有文字稿候选时间点时，围绕每个点生成前、中、后三帧：

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \
  -t 61.2 -t 68.9 -t 74.5 -t 82.0 -t 88.4 \
  --around 0.8 --out focused-candidates.jpg
```

### 2. 选主题与稳定帧

一张图只表达一个连贯观点。候选句需要语义递进，并且每个时间点都能回到视频验证。避免空字幕、同句重复、字幕切换残影、转场、黑帧、广告贴片、播放器 UI 和人物闭眼。

主图（每张图的第一个时间点）由你来选，渲染器不识别人脸、也不自动挑帧，manifest 或 `lines` JSON 写的是哪个时间点就用哪一帧：

- **固定主图时间点**：选定后把时间点直接写进 manifest 或 JSON，渲染前用 `sample -t 时间点 --around 0.8` 回看前后画面，确认主体是说这句话的人、构图完整、没有闭眼或动作模糊。
- **主图构图检查**：渲染器不检查构图，选定主图后按 `references/visual-style.md` 的「主图构图检查清单」逐张目测：头顶不被切、上方留白约 ≥8%；下巴离主图下缘（第一条字幕条上沿）约 ≥5%；脸中心大致在主图高度 35–60%、宽度 35–65%。固定比例 `--fit crop` 时按裁切后的成品判断。不达标先用 `sample 视频 --start T-1.5 --end T+1.5 --interval 0.3`（T 为原时间点秒数，start 不小于 0、end 不超过视频时长）在前后约 1.5 秒内重找；仍找不到时用最好的一帧，并在交付时写明哪张主图构图不达标、差在哪里。这些比例是目测参考，不是渲染器校验。
- **高风险素材**：两人并排的宽景对谈、主持人与嘉宾同框的节目，主图很容易落在主持人或画面另一侧的人身上。优先找说话人的单人近景；整段都没有时，向用户说明，不要拿错的人凑数。
- **固定机位素材**：一套图的主图容易几乎一模一样。先用 `sample` 看整段有没有景别或动作变化，尽量为每张图挑不同的画面；源视频只有一个机位时，向用户说明这是素材限制。
- **第三方水印、台标、角标**：默认保留，不遮盖、不模糊、不涂抹，交给用户决定。用户在意时只能换时间点，或在用户同意后调整裁切位置避开。

### 多人对话与访谈

渲染器只按时间点顺序拼图，不识别谁在说话；字幕条只裁画面底部，读者会默认整张图都是主画面人物说的。访谈、播客、对谈、辩论等多人素材必须先做说话人区分，再选句：

1. **先标说话人**：YouTube 字幕轨和普通 Whisper 文字稿都不带说话人。有说话人分离（diarization）的转写就使用它；没有时，在文字稿里逐句写上说话人，并用 `sample -t ... --around 0.8` 回看画面（口型、机位、画面内名牌）确认。无法确认归属的句子不用。
2. **默认一张图只放一个人的话**：同一说话人连续表达一个观点；主画面必须是这个人在说话的稳定帧。
3. **问答结构要明确**：用户要“一问一答”时，先向用户确认结构；问与答必须在原视频中相邻，不得跳过对方插话后把两人的句子拼成一个人的观点。原生模式无法在画面上补标说话人，问答图要在交付说明里逐句写明说话人；脚本模式可在每句写 `speaker` 并用 `--speaker-prefix on-change` 在画面上标出（见 4B）。
4. **核对每个时间点的说话人**：两人交替快或抢话时，同一时间点画面里的字幕可能是对方的话。逐个时间点回看完整画面，而不是只看裁出的字幕条。

## 原生字幕模式

### 3A. 预览字幕区域

单行字幕从 `0.78–0.96` 开始；两行字幕或位置偏高时，先预览再扩大到例如 `0.62–0.96`。

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" band VIDEO -t 61.2 \
  --band-top 0.78 --band-bottom 0.96 --out band-preview.jpg
```

### 4A. 建立 manifest 并渲染

```json
{
  "images": [
    {
      "title": "模型独立工作时长正在快速增长",
      "times": [61.6, 69.3, 75.0, 82.4, 88.8]
    }
  ]
}
```

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render VIDEO \
  --manifest manifest.json --out-dir OUTPUT_DIR \
  --band-top 0.78 --band-bottom 0.96
```

`title` 只用于文件名，不画进图片。`times` 必须来自已回看的稳定帧。输出包含逐张 JPG、`原生字幕时间点.json` 和 `final_contact_sheet.jpg`。

## 脚本字幕模式

### 3B. 建立已审核的时间点 + 台词 JSON

```json
{
  "lines": [
    {"t": 61.6, "text": "第一句已核对台词"},
    {"t": 69.3, "text": "第二句已核对台词"},
    {"t": 75.0, "text": "第三句已核对台词"},
    {"t": 82.4, "text": "第四句已核对台词"},
    {"t": 88.8, "text": "第五句已核对台词"}
  ]
}
```

- `t` 必须严格递增且小于视频时长。
- `text` 必须是已核对的单行台词；过长时拆句，不靠极小字号硬塞。
- 翻译台词要先核对含义、人名、数字和专有名词。
- 第一帧优先表情、手势和构图，其余帧优先台词连贯与背景可读性。

### 4B. 渲染脚本字幕

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
  --script script.json --out OUTPUT.jpg \
  --aspect 3:4 --width 1440
```

可选六句卡（脚本字幕）：准备 6 句已核对、时间点严格递增的 `script.json`，然后运行：

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
  --script script.json --out six-line.jpg \
  --six-line-card --aspect 3:4 --width 1080
```

此预设默认在源画面高度的 60% 处取字幕条；必要时仍可用 `--band-center` 调整。它不接受 `--hero-fraction`，因为主画面高度由五条连续字幕条反推。`--six-line-card` 仅影响后期绘制的脚本字幕，不改变原生字幕模式。

可选说话人前缀（仅脚本字幕）：经用户确认的问答、对谈图，在每句加 `speaker`，说话人写在这里，不写进 `text`：

```json
{"lines": [
  {"t": 37.2, "speaker": "主持人", "text": "在这么竞争激烈的行业里，"},
  {"t": 38.8, "speaker": "主持人", "text": "你觉得是什么让你脱颖而出？"},
  {"t": 44.0, "speaker": "王薇薇", "text": "说实话，我觉得是运气。"}
]}
```

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
  --script script.json --out qa.jpg --speaker-prefix on-change
```

- `--speaker-prefix none`（默认）不画前缀；`on-change` 只在换人时画，推荐用于问答；`every` 每句都画，画面较挤，只在用户要求时用。
- 启用前缀时每句都必须有 `speaker`；前缀比台词小一号、用强调色，字号不随台词缩小，台词放不下时只缩台词。
- 说话人名称同样要核对：确认不了身份时写“主持人”“嘉宾”等角色，不猜人名。单人独白不用前缀。

**可选金句强调（仅脚本模式）**：`--emphasize-line last`（最后一句）或 `--emphasize-line N`（从 1 起算）给一句台词加暖色、加粗描边和轻微半透明底衬；也可在 `script.json` 某句写 `"emphasis": true`。默认不启用，输出不变；行号越界会报错。仍属后期绘制，需按脚本模式标注；原生模式不支持，不得重绘原字幕。图内不绘制卡片小标题，本 Skill 无此功能。

脚本会尝试 macOS、Windows 和 Linux 常见 CJK 字体；台词含谚文时优先尝试韩文字体（macOS AppleSDGothicNeo、Windows Malgun Gothic），`--font` 始终最优先。无法自动找到时，用 `--font /path/to/font.ttc` 指定已获授权的字体。需要调整字幕条在原帧中的垂直采样位置时，使用 `--band-center`；不要把它当作行距参数。

## 逐张质检与有界返工

先看缩略总览，再打开每张原尺寸 JPG。

- 字幕完整、稳定、无重复，时间顺序与原视频一致。
- 多人素材：每条字幕的说话人与文字稿标注一致；默认同一张图只有一个说话人，主画面就是该说话人。脚本模式启用 `--speaker-prefix` 时，画面前缀与 JSON 的 `speaker` 一致，并且台词字号没有因前缀明显变小。
- 原生模式没有改字；脚本模式的文字与已审核 JSON 一致。
- 主体完整，没有异常切脸、巨大空白、无关 UI 或变形；主图逐张过一遍「主图构图检查清单」（头顶留白、下巴不贴字幕条、脸位不偏），不达标的已重找或已在交付中说明。
- 原生模式检查第一句与后续字幕是否使用同一缩放倍数、没有横向裁字；固定画布允许外侧留边。`--fit crop` 的成品要逐张确认每句字幕两端完整、人物没有被两侧裁切切脸，并在交付中说明渲染输出的裁切或留边结果。脚本固定布局默认四条时主图约占 68–72%；内容块之间没有额外间距。
- 脚本模式的字号、描边、对比度在原尺寸与手机缩略图中都可读。
- 文件数量、尺寸、比例、JSON 和总览一致。

发现问题时只调整对应变量：时间点通常移动 `0.3–1.5` 秒；原生字幕被裁时调整 `band` 边界；台词条太高时先恢复自动布局；文字过长时先拆句。连续三轮仍找不到稳定画面时，换片段或报告限制，不无限微调。

## 与其他工具或 Skill 协作

- `yt-dlp`：获取用户有权处理的在线视频、元数据和字幕轨；不负责最终渲染。
- 字幕轨或 Whisper：生成带时间戳的内容索引。原生模式只用它定位；脚本模式可把已复核文字写入 JSON。
- 视频理解、选题或内容分析 Skill：提名主题、时间范围和句子顺序。
- 写作 Skill：产生配套文章或帖子；它不能在原生模式中改变画面字幕。
- 本 Skill：管理最终时间点、真实视频帧、字幕来源标识、拼图和视觉 QA。

复用上游已经下载的视频、文字稿和缓存，不重复消耗网络或转写成本。不假设用户一定安装了某个命名 Skill；缺少上游 Skill 时，自行完成最低限度的文字稿阅读和主题选择。

## 停止条件

- 用户没有下载、处理或发布来源素材的权限。
- 链接需要绕过 DRM、付费墙、地区限制或其他访问控制。
- 用户要求原生字幕，但画面没有烧录字幕；此时先说明，只有用户同意才转脚本模式。
- 原生模式找不到字幕完整稳定的帧。
- 脚本模式的台词或翻译尚未核对，或没有可用 CJK 字体。
- 源画质、遮挡或 UI 严重到无法达到可读交付。

登录、年龄验证、机器人验证或用户自己的非公开视频需要 Cookies 时，必须先取得授权；授权后优先让 `yt-dlp` 通过 `--cookies-from-browser chrome` 临时读取用户自己的已登录会话，而不是让用户粘贴密码或导出 Cookie 文件。不得把浏览器数据写入仓库。

## 交付

提供输出路径、逐张成品、时间点/`lines` JSON、总览图与已完成的视觉和技术检查。明确标记使用的字幕模式。只有用户需要分享包时再生成 ZIP；不得把未逐张打开检查的图片报告为完成。
````

## File: skills/native-subtitle-quote-image/scripts/check_environment.py
size: 9146
sha: bdba00199798a82f0b08e50e99d3134feb030cf5
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/scripts/check_environment.py

```text
#!/usr/bin/env python3
"""检查视频字幕拼图的原生、脚本与 URL 模式所需组件，不执行安装。"""

import argparse
import importlib
import importlib.util
import json
import locale
import shutil
import subprocess
import sys
from pathlib import Path

CJK_FONT_CANDIDATES = [
    "/System/Library/Fonts/PingFang.ttc",
    "/System/Library/Fonts/STHeiti Medium.ttc",
    "/System/Library/Fonts/Hiragino Sans GB.ttc",
    "C:/Windows/Fonts/msyh.ttc",
    "C:/Windows/Fonts/simhei.ttf",
    "/System/Library/Fonts/AppleSDGothicNeo.ttc",
    "C:/Windows/Fonts/malgun.ttf",
    "/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
    "/usr/share/fonts/opentype/noto/NotoSansCJKsc-Regular.otf",
    "/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
]

def command_version(command, args=("--version",)):
    path = shutil.which(command)
    if not path:
        return None, None
    try:
        proc = subprocess.run(
            [path, *args],
            capture_output=True,
            encoding="utf-8",
            errors="replace",
            timeout=10,
            check=False,
        )
    except (OSError, subprocess.SubprocessError):
        return path, "无法读取版本"
    output = (proc.stdout or proc.stderr or "").strip().splitlines()
    return path, output[0] if output else "版本未知"

def module_version(name):
    if importlib.util.find_spec(name) is None:
        return None
    module = importlib.import_module(name)
    return getattr(module, "__version__", "已安装")

def add(rows, component, status, purpose, detail="", required="core"):
    rows.append(
        {
            "component": component,
            "status": status,
            "purpose": purpose,
            "detail": detail,
            "required": required,
        }
    )

def utf8_default():
    if sys.flags.utf8_mode:
        return True
    return locale.getpreferredencoding(False).lower().replace("-", "") == "utf8"

def inspect_environment():
    rows = []
    python_ok = sys.version_info >= (3, 10)
    add(
        rows,
        "Python 3.10+",
        "ok" if python_ok else "missing",
        "运行 Skill 脚本",
        sys.version.split()[0],
    )

    if not utf8_default():
        add(
            rows,
            "UTF-8 encoding",
            "optional",
            "文本读写：默认编码非 UTF-8 时中文路径与输出可能乱码",
            f"当前默认编码 {locale.getpreferredencoding(False)}；"
            "建议设置 PYTHONUTF8=1（cmd: set PYTHONUTF8=1）",
            required="optional",
        )

    pillow = module_version("PIL")
    add(
        rows,
        "Pillow",
        "ok" if pillow else "missing",
        "裁图、拼图、导出 JPG",
        str(pillow or "未安装"),
    )

    ffmpeg_detail = ""
    imageio = module_version("imageio_ffmpeg")
    if imageio:
        try:
            imageio_module = importlib.import_module("imageio_ffmpeg")
            ffmpeg_detail = f"imageio-ffmpeg {imageio}: {imageio_module.get_ffmpeg_exe()}"
        except Exception as exc:  # pragma: no cover - platform-specific failure
            ffmpeg_detail = f"imageio-ffmpeg 已安装但不可用: {exc}"
            imageio = None
    system_ffmpeg, ffmpeg_version = command_version("ffmpeg", ("-version",))
    ffmpeg_ok = bool(imageio or system_ffmpeg)
    if system_ffmpeg:
        system_detail = f"system: {system_ffmpeg} ({ffmpeg_version})"
        ffmpeg_detail = f"{ffmpeg_detail}; {system_detail}" if ffmpeg_detail else system_detail
    add(
        rows,
        "FFmpeg provider",
        "ok" if ffmpeg_ok else "missing",
        "读取视频并精确取帧",
        ffmpeg_detail or "请安装 imageio-ffmpeg 或 FFmpeg 可执行文件",
    )

    cjk_font = next(
        (candidate for candidate in CJK_FONT_CANDIDATES if Path(candidate).is_file()),
        None,
    )
    add(
        rows,
        "CJK font",
        "ok" if cjk_font else "missing",
        "脚本字幕模式：绘制中文、日文或韩文台词",
        cjk_font or "未找到常见 CJK 字体；可安装 Noto Sans CJK 或用 --font 指定",
        required="script",
    )

    ytdlp_path, ytdlp_version = command_version("yt-dlp")
    add(
        rows,
        "yt-dlp",
        "ok" if ytdlp_path else "missing",
        "URL 模式：读取元数据、字幕轨和下载视频",
        f"{ytdlp_version} ({ytdlp_path})" if ytdlp_path else "本地视频模式不需要",
        required="url",
    )

    runtimes = []
    for label, command in (
        ("Deno", "deno"),
        ("Node.js", "node"),
        ("QuickJS", "qjs"),
        ("Bun (deprecated)", "bun"),
    ):
        path, version = command_version(command)
        if path:
            runtimes.append((label, command, path, version))
    if runtimes:
        label, command, path, version = runtimes[0]
        if command == "deno":
            detail = f"{label} {version} ({path})；yt-dlp 默认启用"
        elif command == "bun":
            detail = (
                f"{label} {version} ({path})；调用 yt-dlp 时添加 "
                "--js-runtimes bun；官方已将 Bun 支持标记为弃用"
            )
        else:
            detail = (
                f"{label} {version} ({path})；调用 yt-dlp 时添加 "
                f"--js-runtimes {command}"
            )
        add(
            rows,
            "JavaScript runtime",
            "ok",
            "URL 模式：完整解析 YouTube",
            detail,
            required="url",
        )
    else:
        add(
            rows,
            "JavaScript runtime",
            "missing",
            "URL 模式：完整解析 YouTube",
            "推荐 Deno；也可使用 Node.js 或 QuickJS；Bun 支持已弃用",
            required="url",
        )

    whisper_cli, whisper_version = command_version("whisper")
    whisper_module = module_version("faster_whisper") or module_version("whisper")
    whisper_ok = bool(whisper_cli or whisper_module)
    whisper_detail = "未安装；只有来源没有可用时间轴时才需要"
    if whisper_cli:
        whisper_detail = f"CLI {whisper_version} ({whisper_cli})"
    elif whisper_module:
        whisper_detail = f"Python module {whisper_module}"
    add(
        rows,
        "Whisper / speech-to-text",
        "optional" if not whisper_ok else "ok",
        "可选：没有字幕轨时生成带时间戳文字稿",
        whisper_detail,
        required="optional",
    )
    return rows

def is_blocking(row, url_mode, script_mode):
    if row["status"] != "missing":
        return False
    return (
        row["required"] == "core"
        or (url_mode and row["required"] == "url")
        or (script_mode and row["required"] == "script")
    )

def print_human(rows, url_mode, script_mode):
    labels = {"ok": "可用", "missing": "缺失", "optional": "可选"}
    widths = (26, 8, 38)
    print(f"{'组件':<{widths[0]}} {'状态':<{widths[1]}} 用途")
    print("-" * 92)
    for row in rows:
        print(
            f"{row['component']:<{widths[0]}} "
            f"{labels[row['status']]:<{widths[1]}} "
            f"{row['purpose']}"
        )
        if row["detail"]:
            print(f"  {row['detail']}")

    blocking = [row for row in rows if is_blocking(row, url_mode, script_mode)]
    source = "URL" if url_mode else "本地视频"
    subtitle = "脚本字幕" if script_mode else "原生字幕"
    mode = f"{source} + {subtitle}模式"
    if blocking:
        print(f"\n{mode}尚不可用，缺少: " + ", ".join(row["component"] for row in blocking))
    else:
        print(f"\n{mode}环境检查通过。")
    if url_mode:
        print(
            "提示：若 YouTube 返回登录或机器人验证，不要退回本地模式；"
            "先取得用户授权，再在该 URL 的 yt-dlp 命令中添加 "
            "--cookies-from-browser chrome。"
        )

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument(
        "--url-mode",
        action="store_true",
        help="把 yt-dlp 和 JavaScript runtime 也作为必需组件检查",
    )
    parser.add_argument(
        "--script-mode",
        action="store_true",
        help="把绘制中文台词所需的 CJK 字体也作为必需组件检查",
    )
    parser.add_argument("--json", action="store_true", help="输出机器可读 JSON")
    args = parser.parse_args()

    rows = inspect_environment()
    blocking = [
        row
        for row in rows
        if is_blocking(row, args.url_mode, args.script_mode)
    ]
    if args.json:
        print(
            json.dumps(
                {
                    "mode": "url" if args.url_mode else "local",
                    "script_mode": args.script_mode,
                    "ok": not blocking,
                    "components": rows,
                },
                ensure_ascii=False,
                indent=2,
            )
        )
    else:
        print_human(rows, args.url_mode, args.script_mode)
    raise SystemExit(1 if blocking else 0)

if __name__ == "__main__":
    main()
```

## File: skills/native-subtitle-quote-image/scripts/check_update.py
size: 8212
sha: 9e6f6806c9382c0140260d4647fb6dd98e9ad2dd
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/scripts/check_update.py

```text
#!/usr/bin/env python3
"""Check GitHub Releases for a newer Skill version without auto-updating."""

import argparse
import json
import os
import platform
import re
import subprocess
import urllib.error
import urllib.request
from datetime import datetime, timedelta, timezone
from pathlib import Path

REPOSITORY = "chengyi-ai/native-subtitle-quote-image"
LATEST_API = f"https://api.github.com/repos/{REPOSITORY}/releases/latest"
RELEASES_URL = f"https://github.com/{REPOSITORY}/releases"
CACHE_TTL = timedelta(hours=24)
VERSION_FILE = Path(__file__).resolve().parents[1] / "VERSION"

def parse_version(value):
    match = re.fullmatch(r"\s*v?(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?\s*", value)
    if not match:
        raise ValueError(f"无法识别版本号: {value!r}")
    return tuple(int(part) for part in match.groups())

def normalize_version(value):
    return ".".join(str(part) for part in parse_version(value))

def read_current_version():
    return normalize_version(VERSION_FILE.read_text(encoding="utf-8"))

def default_cache_path():
    override = os.environ.get("NATIVE_SUBTITLE_UPDATE_CACHE")
    if override:
        return Path(override).expanduser()

    system = platform.system()
    if system == "Darwin":
        root = Path.home() / "Library" / "Caches"
    elif system == "Windows":
        root = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
    else:
        root = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
    return root / "native-subtitle-quote-image" / "update-check.json"

def utc_now():
    return datetime.now(timezone.utc)

def format_timestamp(value):
    return value.astimezone(timezone.utc).isoformat().replace("+00:00", "Z")

def parse_timestamp(value):
    return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc)

def read_cache(path):
    try:
        payload = json.loads(path.read_text(encoding="utf-8"))
        latest_version = normalize_version(payload["latest_version"])
        checked_at = parse_timestamp(payload["checked_at"])
        release_url = payload.get("release_url") or RELEASES_URL
    except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError):
        return None
    return {
        "latest_version": latest_version,
        "release_url": release_url,
        "checked_at": checked_at,
    }

def cache_is_fresh(cache, now):
    if not cache:
        return False
    age = now - cache["checked_at"]
    return timedelta(0) <= age < CACHE_TTL

def write_cache(path, payload):
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_name(f".{path.name}.tmp")
    temporary.write_text(
        json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
        encoding="utf-8",
    )
    temporary.replace(path)

def release_from_payload(payload):
    latest_version = normalize_version(payload["tag_name"])
    return {
        "latest_version": latest_version,
        "release_url": payload.get("html_url") or RELEASES_URL,
    }

def fetch_latest_release(timeout=4):
    request = urllib.request.Request(
        LATEST_API,
        headers={
            "Accept": "application/vnd.github+json",
            "User-Agent": "native-subtitle-quote-image-update-check",
        },
    )
    try:
        with urllib.request.urlopen(request, timeout=timeout) as response:
            return release_from_payload(json.load(response))
    except (OSError, urllib.error.URLError) as urllib_error:
        # Python.org builds on macOS can lack a configured CA bundle. Use the
        # operating system's curl as a verified-HTTPS fallback; never disable TLS.
        try:
            proc = subprocess.run(
                [
                    "curl",
                    "-fsSL",
                    "--connect-timeout",
                    str(timeout),
                    "--max-time",
                    str(timeout),
                    "-H",
                    "Accept: application/vnd.github+json",
                    "-A",
                    "native-subtitle-quote-image-update-check",
                    LATEST_API,
                ],
                capture_output=True,
                encoding="utf-8",
                errors="replace",
                check=False,
                timeout=timeout + 1,
            )
        except (OSError, subprocess.SubprocessError) as curl_error:
            raise OSError(
                f"Python HTTPS 失败: {urllib_error}; curl 回退失败: {curl_error}"
            ) from curl_error
        if proc.returncode != 0:
            detail = proc.stderr.strip() or f"退出码 {proc.returncode}"
            raise OSError(
                f"Python HTTPS 失败: {urllib_error}; curl 回退失败: {detail}"
            )
        return release_from_payload(json.loads(proc.stdout))

def check_for_update(force=False, now=None, cache_path=None, fetcher=None):
    now = now or utc_now()
    cache_path = cache_path or default_cache_path()
    fetcher = fetcher or fetch_latest_release
    current_version = read_current_version()
    cache = read_cache(cache_path)
    error = None

    if cache_is_fresh(cache, now) and not force:
        release = cache
        from_cache = True
    else:
        try:
            release = fetcher()
            release = {
                "latest_version": normalize_version(release["latest_version"]),
                "release_url": release.get("release_url") or RELEASES_URL,
                "checked_at": now,
            }
            from_cache = False
            try:
                write_cache(
                    cache_path,
                    {
                        "checked_at": format_timestamp(now),
                        "latest_version": release["latest_version"],
                        "release_url": release["release_url"],
                    },
                )
            except OSError as exc:
                error = f"无法写入更新缓存: {exc}"
        except (OSError, KeyError, TypeError, ValueError, json.JSONDecodeError, urllib.error.URLError) as exc:
            error = f"无法检查更新: {exc}"
            if cache:
                release = cache
                from_cache = True
            else:
                return {
                    "status": "unavailable",
                    "current_version": current_version,
                    "latest_version": None,
                    "release_url": RELEASES_URL,
                    "checked_at": None,
                    "from_cache": False,
                    "error": error,
                }

    latest_version = release["latest_version"]
    status = (
        "update_available"
        if parse_version(latest_version) > parse_version(current_version)
        else "up_to_date"
    )
    return {
        "status": status,
        "current_version": current_version,
        "latest_version": latest_version,
        "release_url": release.get("release_url") or RELEASES_URL,
        "checked_at": format_timestamp(release["checked_at"]),
        "from_cache": from_cache,
        "error": error,
    }

def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--force", action="store_true", help="忽略 24 小时缓存并立即检查")
    parser.add_argument("--json", action="store_true", help="输出机器可读 JSON")
    parser.add_argument("--verbose", action="store_true", help="没有更新或检查失败时也显示状态")
    args = parser.parse_args()

    result = check_for_update(force=args.force)
    if args.json:
        print(json.dumps(result, ensure_ascii=False, indent=2))
    elif result["status"] == "update_available":
        print(
            f"发现 Skill 新版本 v{result['latest_version']} "
            f"（当前 v{result['current_version']}）：{result['release_url']}"
        )
    elif args.verbose and result["status"] == "up_to_date":
        print(f"当前已是最新版 v{result['current_version']}。")
    elif args.verbose:
        print(result["error"] or "暂时无法检查更新。")

    # 更新检查永远不阻断主要任务。
    return 0

if __name__ == "__main__":
    raise SystemExit(main())
```

## File: skills/native-subtitle-quote-image/scripts/fetch_source.py
size: 8591
sha: 7d97b10412d0df5b773d7edc2a16dba878d5dbf7
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/scripts/fetch_source.py

```text
#!/usr/bin/env python3
"""包装 yt-dlp 的下载入口：识别 HTTP 403 / 429 并做有上限的退避重试。

设计边界（与 SKILL.md 一致）：
- 不绕过 DRM、付费墙、地区限制或平台风控；403/429 只做有限重试和清楚报错。
- 429 是请求过密，退避等待后重试；403 大多是 yt-dlp 版本或该格式的签名失效，只重试一次。
- 任何失败都显式报错并记入 download-attempts.log，不静默失败、不无限重试。
- 不自行添加 Cookie 参数；Cookie 仅在用户授权后由调用方传入 --extra。
"""

import argparse
import datetime as _datetime
import os
import re
import shutil
import subprocess
import sys
import time
from pathlib import Path

ATTEMPT_LOG = "download-attempts.log"
# 429 默认最多重试 3 次；再多就是在硬冲平台速率限制。
DEFAULT_RETRIES = 3
MAX_RETRIES = 6
# 退避基数（秒）：等待为 base * 2**n，并封顶在 MAX_BACKOFF。
DEFAULT_BACKOFF = 30.0
MAX_BACKOFF = 600.0
# 403 通常不是速率问题，重试再多也没意义。
FORBIDDEN_RETRIES = 1
FORBIDDEN_BACKOFF = 5.0

RATE_LIMITED = "rate_limited"
FORBIDDEN = "forbidden"
BOT_CHECK = "bot_check"
OTHER = "other"

_PATTERNS = (
    (RATE_LIMITED, re.compile(r"HTTP Error 429|Too Many Requests", re.IGNORECASE)),
    (FORBIDDEN, re.compile(r"HTTP Error 403|\bForbidden\b", re.IGNORECASE)),
    (
        BOT_CHECK,
        re.compile(
            r"Sign in to confirm|confirm you’?re not a bot|not a bot"
            r"|age[- ]restricted|cookies",
            re.IGNORECASE,
        ),
    ),
)

_ADVICE = {
    RATE_LIMITED: (
        "HTTP 429：请求过于频繁，常见于一次请求多条自动翻译字幕轨。"
        "缩减 --sub-langs 只留需要的一两个标签，加 --sleep-subtitles 5，并改成串行单个视频；"
        "不要换 IP 或缩短间隔硬冲。"
    ),
    FORBIDDEN: (
        "HTTP 403：通常是 yt-dlp 版本落后于站点改动，或该格品的签名 URL 已失效。"
        "先 python3 -m pip install -U 'yt-dlp[default]' 升级并确认 JavaScript runtime 生效，"
        "再按 references/yt-dlp-and-transcripts.md 的格式回退表逐级换 -f，每级只试一次。"
    ),
    BOT_CHECK: (
        "平台要求登录态（机器人验证、年龄验证或非公开视频）。不要重试："
        "先向用户复述真实报错并取得授权，再用 --extra 传入 --cookies-from-browser chrome。"
    ),
    OTHER: "yt-dlp 未按 403/429 分类失败，请看下方原始报错。",
}

def classify(text):
    """把 yt-dlp 的 stderr 归类；顺序重要，429 优先于 403。"""
    for kind, pattern in _PATTERNS:
        if pattern.search(text or ""):
            return kind
    return OTHER

def retry_plan(kind, retries, backoff):
    """返回（该类错误还能重试几次，退避基数）。"""
    if kind == RATE_LIMITED:
        return retries, backoff
    if kind == FORBIDDEN:
        return min(FORBIDDEN_RETRIES, retries), FORBIDDEN_BACKOFF
    # 登录验证和其他错误重试没有意义。
    return 0, backoff

def wait_seconds(backoff, attempt):
    return min(MAX_BACKOFF, backoff * (2 ** attempt))

def log_attempt(log_path, attempt, kind, detail):
    stamp = _datetime.datetime.now().astimezone().isoformat(timespec="seconds")
    line = f"{stamp}\t第 {attempt} 次\t{kind}\t{detail}\n"
    try:
        with open(log_path, "a", encoding="utf-8") as handle:
            handle.write(line)
    except OSError as exc:
        print(f"警告: 无法写入 {log_path}（{exc}）", file=sys.stderr)

def last_lines(text, count=4):
    lines = [line.strip() for line in (text or "").splitlines() if line.strip()]
    return "\n".join(lines[-count:]) or "没有返回错误详情"

def run_once(command):
    proc = subprocess.run(
        command, capture_output=True, encoding="utf-8", errors="replace"
    )
    return proc.returncode, proc.stdout or "", proc.stderr or ""

def fetch(command, retries, backoff, log_path, sleeper=time.sleep, runner=run_once):
    """执行 yt-dlp 并按错误类型退避重试；成功返回 0，否则非零。"""
    attempt = 0
    while True:
        attempt += 1
        code, stdout, stderr = runner(command)
        if stdout:
            print(stdout, end="" if stdout.endswith("\n") else "\n")
        if code == 0:
            log_attempt(log_path, attempt, "成功", " ".join(command[1:]) or "-")
            print(f"下载成功（第 {attempt} 次尝试），尝试记录: {log_path}")
            return 0
        kind = classify(stderr)
        detail = last_lines(stderr, 1)
        log_attempt(log_path, attempt, kind, detail)
        allowed, base = retry_plan(kind, retries, backoff)
        remaining = allowed - (attempt - 1)
        if remaining <= 0:
            print(
                f"下载失败（{kind}，共 {attempt} 次尝试）。\n{_ADVICE[kind]}\n"
                f"yt-dlp 原始报错:\n{last_lines(stderr)}\n尝试记录: {log_path}",
                file=sys.stderr,
            )
            return 1
        delay = wait_seconds(base, attempt - 1)
        print(
            f"第 {attempt} 次失败（{kind}），{delay:.0f}s 后重试，还剩 {remaining} 次。\n"
            f"{_ADVICE[kind]}",
            file=sys.stderr,
        )
        sleeper(delay)

def build_command(args, ytdlp):
    command = [ytdlp, "--no-playlist"]
    if args.mode == "metadata":
        command += [
            "--skip-download",
            "--print",
            "%(id)s | %(title)s | %(channel)s | %(duration_string)s",
        ]
    elif args.mode == "subs":
        command += ["--skip-download", "--write-subs", "--write-auto-subs",
                    "--sub-format", "vtt", "--sub-langs", args.sub_langs,
                    "--sleep-subtitles", str(args.sleep_subtitles)]
    else:
        command += ["-f", args.format]
    if args.output:
        command += ["-o", args.output]
    command += list(args.extra)
    command.append(args.url)
    return command

def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("url")
    parser.add_argument(
        "--mode", choices=("metadata", "subs", "video"), default="video",
        help="metadata 只读元数据；subs 只下字幕；video 下视频（默认）",
    )
    parser.add_argument(
        "-f", "--format", default="bv*[height<=1080]+ba/b[height<=1080]",
        help="video 模式的 yt-dlp -f 参数",
    )
    parser.add_argument("-o", "--output", help="yt-dlp -o 输出模板")
    parser.add_argument(
        "--sub-langs", default="zh-Hans,en-orig",
        help="subs 模式的字幕语言标签；先用 --list-subs 看真实标签，不要用 zh.* 这类泛匹配",
    )
    parser.add_argument(
        "--sleep-subtitles", type=float, default=5.0,
        help="subs 模式每条字幕轨之间的等待秒数，默认 5，降低 429 概率",
    )
    parser.add_argument(
        "--retries", type=int, default=DEFAULT_RETRIES,
        help=f"429 最多重试次数，0–{MAX_RETRIES}，默认 {DEFAULT_RETRIES}；403 始终最多重试 1 次",
    )
    parser.add_argument(
        "--backoff", type=float, default=DEFAULT_BACKOFF,
        help=f"退避基数秒，等待为 base×2^n 并封顶 {MAX_BACKOFF:.0f}s，默认 {DEFAULT_BACKOFF:.0f}",
    )
    parser.add_argument(
        "--log", help=f"尝试日志路径，默认当前工作目录的 {ATTEMPT_LOG}",
    )
    parser.add_argument(
        "--extra", nargs=argparse.REMAINDER, default=[],
        help="透传给 yt-dlp 的其余参数，必须放在最后（例如 --extra --cookies-from-browser chrome）",
    )
    args = parser.parse_args(argv)

    if not 0 <= args.retries <= MAX_RETRIES:
        parser.error(f"--retries 必须在 0–{MAX_RETRIES} 之间")
    if not 0 < args.backoff <= MAX_BACKOFF:
        parser.error(f"--backoff 必须大于 0 且不超过 {MAX_BACKOFF:.0f}")
    if args.sleep_subtitles < 0:
        parser.error("--sleep-subtitles 不能为负数")

    ytdlp = shutil.which("yt-dlp")
    if not ytdlp:
        raise SystemExit(
            "找不到 yt-dlp；先说明用途并取得授权后运行"
            ' python3 -m pip install -U "yt-dlp[default]"'
        )

    log_path = Path(args.log).expanduser() if args.log else Path(os.getcwd()) / ATTEMPT_LOG
    command = build_command(args, ytdlp)
    print("执行: " + " ".join(["yt-dlp", *command[1:]]))
    return fetch(command, args.retries, args.backoff, log_path)

if __name__ == "__main__":
    sys.exit(main())
```

## File: skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py
size: 62729
sha: 52a05411242b4876c129303a5c130bcde5273e53
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py

Content is not inlined in the catalog. Read the upstream file: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py

## File: skills/native-subtitle-quote-image/references/end-to-end-workflow.md
size: 17581
sha: dd1053a8d740edaa7e84bc52b35c7bc7213fd6c0
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/references/end-to-end-workflow.md

````text
# 从读视频到字幕长图的完整工作流

本文件用于多阶段任务：链接获取、长视频理解、选题、选句、精确取帧、原生/脚本字幕分流、拼图、质检和返工。只有本地短视频且时间点已经明确时，可以不读本文件，直接使用 `SKILL.md` 的核心流程。

## 交付标准

一次完整交付至少包含：

- 一个独立输出目录，并明确标注原生字幕或脚本字幕模式；
- 逐张 JPG，比例符合所选布局或用户明确要求；
- 原生模式的 `原生字幕时间点.json`，或脚本模式的 `lines` JSON；
- 多图任务的 `final_contact_sheet.jpg`；
- 对来源、字幕类型、画质限制和素材权限的简短说明；
- 逐张视觉检查结论，而不是只报告脚本退出码。

## 来源模式与字幕模式

这是两个独立维度：来源可以是本地或 URL，字幕可以是原生或脚本。例如，YouTube URL 既可用原生字幕模式，也可在用户需要已审核中文台词时用脚本字幕模式。

### A. 字幕模式

- **原生字幕**：文字已经烧录在画面像素中；只取帧、裁切和拼接，不改字。
- **脚本字幕**：文字来自已审核的时间点 + 台词 JSON；在真实视频帧上后期绘制。

用户要求原生字幕时，只能使用原生模式。画面没有对应烧录字幕时，先报告限制；只有用户同意，才改用脚本模式。

### B. 来源与任务模式

#### 本地成片模式

用户提供本地视频。完成环境检查、候选帧、选句、模式判断、渲染和质检。`yt-dlp` 不是必需项；文字稿或 Whisper 只在需要语义定位时使用。

#### URL 完整模式

用户提供 YouTube 等链接。先按 [yt-dlp-and-transcripts.md](yt-dlp-and-transcripts.md) 获取视频与辅助时间轴，再选择原生字幕或脚本字幕模式。

#### 内容生产模式

用户想完成“读视频 → 选题 → 写文章/帖子 → 生成字幕截图”。先让视频理解、转写、选题或写作 Skill 处理文字稿；再把每个主题对应的时间范围交回本 Skill，从真实视频帧选择最终画面。原生模式不改字；脚本模式只绘制已复核台词。

## 推荐目录

每个来源使用独立目录，避免缓存、成品和其他视频混在一起：

```text
任务目录/
├── source/                    # 下载或用户提供的视频、字幕轨、元数据
├── analysis/
│   ├── transcript.vtt        # 可选，仅用于理解和定位
│   ├── candidate-topics.md    # 可选，候选主题与时间范围
│   └── candidate-frames.jpg  # 带时间点候选帧
├── manifest.json             # 原生模式的最终时间点
├── script.json               # 脚本模式的时间点 + 已审核台词
├── previews/
│   └── band-preview.jpg
└── output-v1/
    ├── 01_主题.jpg
    ├── 原生字幕时间点.json  # 原生模式
    └── final_contact_sheet.jpg
```

不要把原视频、Cookie、个人账号信息、临时字幕或成品图提交进 Skill 仓库。输出目录已存在时创建 `output-v2`；只有用户明确要求覆盖时才使用 `--overwrite`。

## 阶段 0：确认任务

开始前确认四件事：

1. 输入是本地文件还是 URL；
2. 用户想要几张图、发布比例和目标受众；
3. 是否需要先理解长视频、选题或写文章；
4. 用户是否有权下载、处理并发布来源素材。

缺少图片数量时，可以先做 2–3 个候选主题，但不要把推测当作用户已经确认的发布方案。

## 阶段 1：环境诊断

本地模式：

```bash
python3 "<SKILL_DIR>/scripts/check_environment.py"
```

URL 模式：

```bash
python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode
```

脚本字幕中含中日韩文字时增加 `--script-mode`；URL 来源可以同时传 `--url-mode --script-mode`。

核心依赖缺失时先取得安装授权。URL 模式缺少 Deno，但已有 Node.js 时，不需要强制再装 Deno；在 yt-dlp 命令里显式使用 `--js-runtimes node` 即可。Deno 仍是官方推荐和默认启用的选择。

## 阶段 2：获得来源并建立来源记录

URL 模式按专门参考文件执行。至少保留：

- 原始 URL；
- 视频标题、作者/频道、视频 ID、时长；
- 实际下载的视频文件；
- 使用了人工字幕、自动字幕还是语音识别；
- 下载日期与 yt-dlp 版本；
- `download-attempts.log`：每次下载尝试的格式、结果和错误摘要。

下载后必须运行 `check-source VIDEO --min-height 720`，通过才能进入抽帧；失败则按参考文件换下一级变体重试。低于 720p 的变体须先征得用户确认。

来源记录用于复核，不要把账号凭据、Cookie 内容或本机绝对路径写进去。

## 阶段 3：判断字幕类型并锁定模式

字幕类型是硬门槛。不能只看播放器是否显示字幕，也不能只看是否下载到了 VTT。必须在出图前记录使用哪种字幕模式。

先生成整段候选帧总览：

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \
  --out analysis/candidate-frames.jpg
```

逐格检查：

- 字幕是否直接存在于画面像素；
- 字幕语言和用户需求是否一致；
- 字幕位置是否稳定；
- 是否有节目 Logo、标题条、广告贴片遮住字幕；
- 视频画质是否足够。

若大多数帧没有字幕，不要马上判定失败；可能抽到了停顿或转场。结合文字稿选 2–3 个明确说话的时间点，再使用聚焦采样。

最终分流：

- 用户要求保留原字幕，且稳定帧里能直接看到文字：原生字幕模式。
- 用户要求中文翻译、提炼台词或统一字体，并理解文字会后期绘制：脚本字幕模式。
- 用户要求原生字幕，但只找到独立字幕轨：先停止并说明，取得同意后才可转脚本模式。

## 阶段 4：用文字稿选题，再核对文字用途

字幕轨或 Whisper 文字稿首先用来快速回答：

- 视频有哪些值得传播的独立观点；
- 每个观点在哪个时间范围；
- 哪段能组成 4–6 句连续表达；
- 哪些句子是提问、结论、反常识或行动建议。

### 多人对话与访谈：先标说话人

访谈、播客、对谈、圆桌和辩论里，文字稿是多个人交替说话的结果，而 YouTube 字幕轨与普通 Whisper 文字稿都不标说话人。直接按“4–6 句连续表达”选句，会把主持人的提问和嘉宾的回答拼成一个人的观点，读起来像串线或乱序。选题前先做三件事：

1. **建立说话人索引**：有带说话人分离（diarization）的转写时使用它；没有时，在 `analysis/` 下另存一份带说话人标注的文字稿，例如 `[61.2] 主持人：……`、`[68.9] 嘉宾 A：……`。不确定的句子用 `sample -t ... --around 0.8` 回看画面，依据口型、机位和画面内名牌判断；仍无法确认的句子不入选。
2. **按说话人切分主题**：默认一张图只放同一个人围绕一个观点的连续表达。主持人的提问只在用户需要“问答”结构时入选。
3. **问答结构单独确认**：用户要一问一答时，先确认结构；问与答必须在原视频中相邻，不跳过对方插话，也不把两人的句子改写成一人的观点。原生模式无法在画面上补标说话人，交付说明里要逐句写明说话人。

不标说话人就选句，是多人素材“分不清谁说的、顺序乱”的主要原因；不要靠后期换帧补救。

### 候选主题评分

每个候选主题按以下维度判断，不需要机械打分，但应明确取舍：

| 维度 | 判断问题 |
|---|---|
| 独立性 | 脱离上下文后还能看懂吗？ |
| 连续性 | 4–6 句能构成完整的小论证吗？ |
| 画面可用性 | 对应时间段是否有人物清楚、字幕稳定的帧？ |
| 信息密度 | 是否每一句都在推进，而不是重复铺垫？ |
| 真实性 | 是否能回到原视频验证，没有改写成另一层意思？ |
| 说话人一致 | 多人素材中，句子是否都属于同一说话人，或是经用户确认、在原视频中相邻的问答？ |
| 发布价值 | 是否符合用户正在做的文章、帖子或栏目？ |

为每个主题记录：标题、起止时间、一句话价值、候选时间点。标题是文件名和内部导航，不会被画进图片。

文字稿在两种模式中的边界不同：

- **原生模式**：文字稿只是检索索引，最终字幕以画面像素为准。
- **脚本模式**：文字稿可以进入 `text`，但必须先核对原语义、人名、数字、专有名词和时间点。翻译或压缩过的句子需明确属于后期台词，不能冒充原字幕。

### 与其他 Skill 协作

- **视频理解/语音转写 Skill**：生成带时间戳文字稿，作为检索索引。
- **选题/内容分析 Skill**：从文字稿提名主题、判断受众价值。
- **写作 Skill**：围绕已选主题写文章或帖子，并引用来源事实。
- **本 Skill**：掌管最终画面、真实时间点、字幕来源标识、裁切/绘制和视觉 QA。

如果某个上游 Skill 未安装，就直接完成必要的文字稿阅读与主题提炼；不要假设一个不存在的 Skill。用户只要求做图时，不要擅自扩展成写文章或发布内容。

## 阶段 5：把语义时间点校准成可用画面

文字稿时间戳通常落在一句话开始处，容易截到字幕刚出现、上一句残留或无字幕帧。对每个候选时间点生成前、中、后三帧：

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" sample VIDEO \
  -t 61.2 -t 68.9 -t 74.5 -t 82.0 -t 88.4 \
  --around 0.8 --out analysis/focused-candidates.jpg
```

选择规则：

- 取字幕完整稳定显示后的中间帧，不取切换瞬间；
- 相邻时间点必须是不同句，且严格递增；
- 同一张图的句子应组成连续表达，允许跳过无信息过渡句；
- 第一帧是主画面，优先人物表情、动作或场景完整；多人素材的主画面必须是这些台词的说话人在说话；
- 多人素材逐个时间点回看完整画面，确认说话人与字幕都对应文字稿标注；两人交替快或抢话时，字幕可能已切到对方的话；
- 避免转场、黑帧、广告贴片、人物闭眼、Logo 穿脸；
- 原生模式的字幕文字以画面为准；脚本模式的台词以已审核 JSON 为准。

如果 0.8 秒范围仍找不到稳定字幕，把 `--around` 改为 0.4 或 1.2；不要一次偏移太大，否则可能跳到另一句话。

## 阶段 6：校准视觉采样区域

原生模式需要完整包住画面已有字幕；脚本模式则需要为后期台词找到背景简洁、对比足够的水平画面条。

在典型时间点预览上下边界：

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" band VIDEO -t 61.2 \
  --band-top 0.78 --band-bottom 0.96 \
  --out previews/band-preview.jpg
```

检查两条红线：

- 上边界要包含完整的第一行字幕和描边；
- 下边界要包含字幕底部，但避免大块黑边；
- 单行字幕优先保持约 `0.78–0.96` 的紧凑裁切；
- 两行字幕、字幕位置偏高时可尝试 `0.62–0.96` 或 `0.68–0.97`；
- 同一期节目字幕位置变化时，至少抽查开头、中段、结尾三个时间点。

脚本模式不使用 `band`，而是用 `render-script --band-center`设定字幕条在原帧中的垂直中心。默认 `0.88`；背景杂乱或与原有字幕重叠时，先从候选帧换画面，再小范围调整中心。

## 阶段 7：建立最终时间点文件

每张图默认使用 5 个严格递增的时间点：第一帧做主画面，其余四帧做字幕条。

### 原生字幕 manifest

```json
{
  "images": [
    {
      "title": "模型独立工作时长正在快速增长",
      "times": [61.6, 69.3, 75.0, 82.4, 88.8]
    },
    {
      "title": "衡量趋势时不要忽略任务成功率",
      "times": [104.2, 109.0, 114.7, 121.3, 127.0]
    }
  ]
}
```

manifest 只记录最终确认的时间点，不把文字稿改写后的句子放进去，避免让人误以为渲染器会重绘文字。

### 脚本字幕 JSON

```json
{
  "lines": [
    {"t": 61.6, "text": "第一句已核对台词"},
    {"t": 69.3, "text": "第二句已核对台词"},
    {"t": 75.0, "text": "第三句已核对台词"},
    {"t": 82.4, "text": "第四句已核对台词"},
    {"t": 88.8, "text": "第五句已核对台词"}
  ]
}
```

`text` 必须是单行已审核文字。过长台词先拆句，不依靠极小字号填满一条。翻译时把人名、数字、专有名词和否定关系单独复核。

## 阶段 8：渲染

### 原生字幕

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render VIDEO \
  --manifest manifest.json --out-dir output-v1 \
  --band-top 0.78 --band-bottom 0.96
```

### 脚本字幕

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" render-script VIDEO \
  --script script.json --out output-v1/01_主题.jpg \
  --aspect 3:4 --width 1440
```

中日韩文绘制需要 CJK 字体。脚本会先尝试常见系统字体；无法自动找到时，使用 `--font /path/to/font.ttc`。对字体文件同样要遵守其授权条款，不将未授权字体提交到公开仓库。

原生模式默认保留源宽度，先拼源像素、再整图统一等比缩放，高度按真实内容计算。用户未指定比例时不要添加 `--aspect 3:4`；显式指定时，默认对整张拼图统一裁去两侧、最多裁到字幕安全边界，剩余差额才留边；不单独放大主图、不横向裁掉字幕。脚本固定布局仍默认 1440×1920，五个时间点时主画面约占 70%、四条各约占 7.5%。两者条间距为 0。任何输出放大都不等于真实画质提升，应在交付中说明。

用户明确要求调整视觉密度时，读取 [visual-style.md](visual-style.md)。只有确有需要才显式传 `--hero-fraction` 覆盖自动布局。

## 阶段 9：逐张质检

多图任务先看 `final_contact_sheet.jpg` 发现整体问题，再逐张打开原尺寸 JPG；单图脚本模式直接打开原尺寸成品。

### 视觉检查

- 主画面主体完整，没有异常切脸、切头或巨大空白；
- 每条字幕完整，没有切掉描边、标点或第二行；
- 没有同句重复、空字幕、字幕切换残影；
- 原生字幕第一句与后续字幕使用同一缩放倍数，保留全部文字；脚本固定布局四条时主画面约占 68–72%，字幕条紧凑相接；
- 各条之间没有黑边、白缝、额外间距或缩放变形；原生固定画布两侧统一裁切后的剩余留边是保留字幕的取舍，不是条间距；
- 没有广告贴片、进度条、鼠标、通知或无关 UI；
- 画面内已有来源标识时保持原样，不自行新增或删除。
- 脚本模式的文字水平居中，白字黑边清晰，不压主体，不与原有 UI 或字幕叠在一起；
- 脚本模式的字号不应因为台词过长缩到手机上不可读；此时拆句。

### 技术检查

- 每张图可正常解码；
- 尺寸与目标比例一致；
- 文件数量与 manifest 的 `images` 数量一致；
- 原生模式的 `原生字幕时间点.json`，或脚本模式的 `lines` JSON 与实际渲染版本一致；
- 总览图包含全部成品；
- 不同成品不是重复文件。

### 语义检查

- 一张图只表达一个中心观点；
- 五句顺序与原视频一致；
- 多人素材每句的说话人与文字稿标注一致；没有把不同人的话拼成一个人的观点；
- 原生模式没有用标题或文章文案替换原字幕；
- 脚本模式的台词与已审核 JSON 完全一致，而且交付中没有把它误标为原生字幕；
- 如果配套写文章，文章观点能够回到视频或其他来源核验。

## 阶段 10：有界返工

发现问题时只改对应变量：

| 问题 | 优先修改 |
|---|---|
| 字幕刚出现或残留 | 对应时间点 ±0.3–1.5 秒 |
| 同句重复 | 换到下一句稳定帧 |
| 字幕被裁 | `--band-top` / `--band-bottom` |
| 主图不好 | 只换该组第一个时间点 |
| 台词少但字幕条很高 | 使用默认自适应布局，移除过小的 `--hero-fraction` |
| 主图太矮或太高 | 确认默认自适应仍不合适后，再调整 `--hero-fraction` |
| 脚本台词过长 | 先拆句或重选连贯的简短表达，不先压缩字号 |
| 脚本文字与背景混在一起 | 换稳定帧，再小幅调整 `--band-center` |
| 全组主题不连贯 | 回到文字稿重新选段，不靠换帧硬救 |
| 多人素材分不清谁说的 | 回到带说话人标注的文字稿，按说话人重新选段 |
| 字幕条是对方的话或上一句 | 对照说话人标注重新回看该时间点，必要时换句 |

每轮改动后重新逐张检查。连续三轮仍找不到稳定画面时，说明该段不适合做原生字幕拼图，换主题或向用户报告限制；不要无限微调。

## 阶段 11：交付

向用户提供：

1. 输出目录；
2. 成品直接预览，多图任务另提供 `final_contact_sheet.jpg`；
3. 每张成品的标题或用途；
4. 对应模式的时间点 manifest 或 `lines` JSON；
5. 已完成的视觉与技术检查；
6. 明确的字幕模式和文字来源说明；
7. 仍存在的源画质、版权或字幕限制。

只有用户需要分享打包时再生成 ZIP。不要把未经打开检查的图片报告为完成。
````

## File: skills/native-subtitle-quote-image/references/troubleshooting.md
size: 6068
sha: f33155c5171b63a0bdbd63e34e319093e99c85a4
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/references/troubleshooting.md

```text
# 排错手册

按「症状 → 先查什么 → 怎么处理」整理常见失败。下载与字幕轨的细节问题见 [yt-dlp-and-transcripts.md 的常见故障](yt-dlp-and-transcripts.md#常见故障)，这里只列和出图直接相关的部分。

处理原则：每次只改一个变量；同一问题连续三轮仍不行时，换片段或向用户说明限制，不无限重试。

## 环境与编码

### 运行前环境不确定

- **先查**：运行 `python3 "<SKILL_DIR>/scripts/check_environment.py"`；脚本模式加 `--script-mode`，URL 任务再加 `--url-mode`。
- **处理**：按输出逐项补齐 FFmpeg、Pillow、CJK 字体等；显示为可选的项目不阻塞出图。

### 中文 Windows 上读写报 `UnicodeDecodeError` 或输出乱码

- **先查**：`check_environment.py` 是否提示「默认编码非 UTF-8」。
- **处理**：本仓库脚本从 v2.6.1 起都显式使用 UTF-8；仍有问题时设置 `PYTHONUTF8=1`（cmd：`set PYTHONUTF8=1`，PowerShell：`$env:PYTHONUTF8="1"`）后重试，并把命令和完整报错反馈到 issue。

## 源视频

### 下载的视频偏低清，或渲染时报解码错误

- **先查**：`native_subtitle_stitch.py check-source VIDEO --min-height 720`。它会检查分辨率并解码前 N 秒（`--seconds`，默认 10）。
- **处理**：自检失败就按 [格式回退表](yt-dlp-and-transcripts.md#4-下载视频) 换下一级变体重新下载，不要拿坏流继续出图。低于 720p 的版本必须先征得用户同意。

### 长视频 AV1 / VP9 源渲染到一半稳定失败

- **先查**：源是否为 1 小时以上的 AV1 / VP9 变体；同一源换 H.264 变体是否会遇到 HTTP 403。
- **处理**：不要反复重试，先把已下载的源转码成 H.264 再渲染，例如 `ffmpeg -i source.mkv -c:v libx264 -preset veryfast -crf 20 -c:a aac -b:a 128k source-h264.mkv`。加 `-vf scale=-2:720` 可以加快转码、降低解码压力，但会把 4K 降到 720p，成品清晰度会跟着下降，需要告诉用户；想保留清晰度可以去掉它或改成 1080。转码后先跑一次 `check-source` 再出图。
- **已知情况**：目前只有两个实测样本，原因还没确认，**可能**在第 2 张起稳定失败（不是必然现象）。

### 报「无法读取视频尺寸或时长」或「取帧失败」

- **先查**：文件是否下载完整、路径是否正确，再跑一次 `check-source`。
- **处理**：文件损坏就重新下载；时间点超出视频时长时，回到文字稿核对时间点。

## 选帧与画面

### 报「所有时间点取到的画面几乎相同」或「字幕条几乎相同」

- **先查**：用 `sample` 看这些时间点的画面。常见原因是静态封面视频、画面冻结、同一句字幕选了两次，或那一段画面本来没有字幕。
- **处理**：换时间点或换片段；固定机位源可配 `--hero-zoom` 缓解。报错点名两个时间点时，只换那一张卡的时间点就行。觉得判得太严或太松先调 `--duplicate-ratio`（0–0.2，默认 0.005，调高更严）；只有确认这正是用户要的效果时，才加 `--allow-duplicate-frames`（与 `--duplicate-ratio` 互斥）。

### 主图选错了人（双人同框、主持人和嘉宾并排）

渲染器不识别人脸，也不自动选帧：主图就是 manifest（原生模式）或 `lines` JSON 第一句（脚本模式）指定的那个时间点。

- **先查**：用 `sample -t 时间点 --around 0.8` 回看主图前后的画面，确认画面主体就是说这句话的人。
- **处理**：在 manifest 或 JSON 里把主图时间点换成单人近景、构图完整的稳定帧，再重新渲染。「两人并排的宽景对谈」属于高风险素材，见 [SKILL.md 的选帧说明](../SKILL.md#2-选主题与稳定帧)。

### 一套图的主图几乎一模一样（固定机位）

- **先查**：用 `sample` 生成整段候选帧总览，看源视频有没有景别、机位或动作变化。
- **处理**：每张图的主图挑不同景别或不同动作的时间点；源视频本身只有一个机位时，向用户说明这是素材限制。

### 画面里有第三方水印、台标或角标

- **处理**：默认保留，不遮盖、不模糊、不涂抹，交给用户决定。用户在意时，只能换时间点，或在用户同意后调整裁切位置避开；不能用后期手段抹掉来源标识。

## 字幕与排版

### 原生字幕被裁掉一部分

- **先查**：用 `band -t 时间点 --band-top ... --band-bottom ...` 预览裁切区域。
- **处理**：两行字幕或字幕位置偏高时，调整 `--band-top` / `--band-bottom`，例如扩大到 `0.62–0.96`。

### 脚本模式报「找不到可用的中文字体」

- **处理**：安装中文字体，或用 `--font /path/to/font.ttc` 指定已获授权的字体文件。

### 脚本模式报「台词过长，缩小到可读下限后仍放不下」

- **处理**：拆句或删减，不要靠极小字号硬塞。

### 同一张图里各行字号不一致

脚本模式会按每行实际宽度自动缩小放不下的台词，所以长短差距大的台词字号会不一样。

- **处理**：先把过长的句子拆短，让各行长度接近。仍不一致时，用 `--font-size` 指定一个比默认更小、能让最长一行也放下的基础字号。

## 批量渲染与输出

### 报「以下输出已存在」

渲染器默认不覆盖已有成品。

- **处理**：换一个输出目录或文件名；确认要替换时再加 `--overwrite`。

### 一张图失败导致整批中止

以下两个参数仅原生字幕模式的 `render` 支持，脚本模式 `render-script` 没有。

- **处理**：加 `--keep-going`，失败的那张会被跳过，结束时输出失败清单（序号、时间点、原因）并写入输出目录的 `渲染失败报告.json`。修正 manifest 后加 `--resume`，只补渲缺失或损坏的图。
- **注意**：`--resume` 不会重新生成已经正常的图，即使 manifest 改过；要重渲某张，先删掉那张图。

```

## File: skills/native-subtitle-quote-image/references/visual-style.md
size: 10482
sha: 077051d91d66c8194aa76b2e3d43f0e524e03f42
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/references/visual-style.md

````text
# 紧凑型视频字幕拼图视觉规范

当用户强调“好看、紧凑、有节奏、不要台词间隔太宽”，或准备最终视觉质检时读取本文件。规则同时适用于原生字幕和脚本字幕模式；只有脚本模式会绘制字体和描边，原生模式始终保留视频像素。本规范来自对高质量成品的版式测量与视觉归纳；参考原图不随 Skill 分发。

## 核心判断

3:4 拼图的视觉中心应是主画面，而不是平均分配的五块视频截图。字幕条只承担连续阅读，不应因为台词少而被拉成大块画面。

默认目标：

- 原生字幕默认按源画面和字幕条计算高度，不强制 3:4；显式要求固定比例时，默认对整张拼图统一裁去两侧（`--fit crop`），最多裁到字幕安全边界，剩余差额再留边；不分别填满主图和字幕条。
- 脚本字幕固定画布为 3:4；推荐输出 1440×1920，1080×1440 也符合比例。
- 一张图使用 5 个时间点：1 个主画面 + 4 个字幕条。
- 脚本固定布局的 4 个字幕条时，主画面约占总高度 70%，每个字幕条约占 7.5%。原生模式优先保证所有字幕同一缩放倍数，不套用此比例。
- 字幕条首尾直接相接，条间距为 0，不增加边框、留白或装饰分隔线。
- 原生模式的单行字幕默认从源画面的 `0.78–0.96` 高度范围裁切；字幕偏高或两行时再扩大。

## 原比例布局

用户要求保留横屏构图或原始画面尺寸时，用 `--layout natural`，而不是强制把画面填进 3:4。主图与字幕条只裁切、等比缩放，最终高度为各块实际高度之和；不传 `--width` 时保留源宽度。原生字幕保留到 `--band-bottom` 的主图；脚本字幕默认保留全帧，可按实测边界用 `--frame-top` / `--frame-bottom` 裁去源字幕等区域。`--band-center` 相对裁切后的画面。

裁去底部 28% 后，剩余画面高度就是原高的 72%，不能再拉回原高。最后也不能用直接 resize 强制输出 3:4；确实需要固定比例时回到固定布局重新渲染。画面原比例与“原生字幕”是不同概念，不改变字幕模式。

下面的密度计算和 68–72% 验收仅适用于脚本固定布局；原生模式及原比例布局检查主体几何、文字完整及紧凑拼接，不追求同一个高度比例。

## 自适应密度

脚本固定布局默认按字幕条数量自动计算主画面比例：

```text
主画面比例 = clamp(1 - 字幕条数量 × 0.075, 0.48, 0.82)
```

常见结果：

| 时间点 | 字幕条 | 主画面比例 | 视觉效果 |
|---:|---:|---:|---|
| 3 | 2 | 82% | 少量台词时保留大主图，不拉高字幕条 |
| 4 | 3 | 77.5% | 适合短观点 |
| 5 | 4 | 70% | 默认、最均衡 |
| 6 | 5 | 62.5% | 信息较多，仍保持紧凑 |
| 7 | 6 | 55% | 接近密度上限，需要重点检查字号与可读性 |

用户明确传入 `--hero-fraction` 时尊重用户值。只有实际版式需要时才覆盖自动值，不要为了“更满”而把主图压得过小。

原生固定布局的此参数仅调整源主图的裁切高度，受可用源像素限制；不能分别缩放主图和字幕条以达成目标比例。原生字幕不重绘、不人为统一原视频中本就不同的字号。

## 固定机位源与 `--hero-zoom`

优先选多机位、景别有变化的视频。固定单机位源（大学大师课、网课式录制）是高风险素材：六张主图只差表情，整组看起来像同一张图。

确需使用时，用 `--hero-zoom` 给每张卡设不同的主图缩放，例如 `--hero-zoom 1.0,0.9,0.95`，按卡循环，范围 0.8–1.0，默认不启用。它只裁掉更多主图画面再放大，字幕条、文字、条间距和六句卡几何不变；原生模式下裁切窗口不会进入字幕条。注意：这是裁切后放大，源视频清晰度不足时主图会更模糊，不等于真实清晰度提升。

## 呼吸缝与分隔线

版式默认主图与字幕条硬边相接、条间距为 0。手机上觉得拥挤时可用 `--strip-gap 2`–`4`（条间黑色缝隙）和 `--hero-divider line`（2px 分隔线）。它们是插入的背景像素，不叠加在画面上，所以不会盖住原生字幕；渐变会改动主图下缘的字幕像素，因此不提供。与 `--six-line-card` 不兼容。

## 字幕区域

### 单行字幕

从 `--band-top 0.78 --band-bottom 0.96` 开始预览。目标是：

- 保留完整文字、描边和标点；
- 字幕上下有少量呼吸空间，但不会出现大块无文字背景；
- 缩放到最终条高后仍然清楚；
- 不切进播放器进度条或画面底部黑边。

### 两行字幕或位置偏高

不要继续使用窄裁切硬切第二行。先通过 `band` 预览，再按实际位置扩大，例如 `0.62–0.96` 或 `0.68–0.97`。两行字幕会提高字幕条本身的信息密度，需要检查是否仍适合 4 条拼接。

### 字幕位置变化

同一视频至少抽查开头、中段、结尾。若节目在不同段落改变字幕位置，不能只用一张预览推断整期；换片段或为不同组分别渲染。

## 主画面选择

主画面承担第一眼吸引力，优先级高于第一句文字是否最完整：

1. 主体面部、手势或关键物体清楚；
2. 人物不闭眼、不处于口型或动作的尴尬过渡；
3. 麦克风、前景物体和画面边缘不异常切断主体；
4. 背景明暗和主体分离，字幕描边能够读清；
5. 第一条字幕位于画面下部，不压脸、不贴底；
6. 避免转场、黑帧、广告、播放器控件、通知和无关 UI。

主画面可以与后续字幕条来自同一场景，但帧本身必须比普通字幕条更完整、更有表现力。

### 主图构图检查清单

渲染器不识别人脸，也不校验构图；以下由 Agent 在渲染后逐张目测成品主图（固定比例 `--fit crop` 时看裁切后的画面），比例都是近似参考值：

| 检查项 | 参考值 | 常见问题 |
|---|---|---|
| 头顶留白 | 头顶到主图上缘约 ≥8% 主图高度 | 切掉头顶或发际线 |
| 下巴与下缘 | 下巴到主图下缘（第一条字幕条上沿）约 ≥5% 主图高度 | 下巴贴着字幕条，像被字幕压住 |
| 脸中心垂直位置 | 主图高度约 35–60% | 脸太低像在往下掉，太高顶住上缘 |
| 脸中心水平位置 | 主图宽度约 35–65% | 脸挤在一侧，另一侧大片空背景 |

不适用：主体不是人脸（产品、手势、屏幕演示）时，按同样思路检查关键物体是否完整、不贴边。用户明确要特写、侧脸或刻意偏置构图时以用户要求为准。

不达标时按顺序处理：

1. 只换主图时间点：用 `sample 视频 --start T-1.5 --end T+1.5 --interval 0.3`（T 为原时间点秒数，start 不小于 0、end 不超过视频时长）在原时间点前后约 1.5 秒内重找，挑满足清单且不闭眼、不模糊的帧；
2. 固定比例裁切切到人物两侧时，调整 `--crop-center`；它只移动水平裁切窗口，解决不了头顶留白、下巴贴条这类垂直问题，垂直问题只能靠换时间点；
3. 仍找不到时用最接近的一帧出图，在交付说明中写明第几张主图哪一项不达标，不无限微调。

## 字幕条节奏

- 四条字幕应像连续段落，而不是四张独立海报。
- 每条只保留一个稳定字幕单位；不要在一条里留下上一句残影。
- 相邻字幕语义递进，避免同义重复和长铺垫。
- 背景变化可以增加节奏，但不能以字幕难读、人物异常或画面杂乱为代价。
- 明暗差异很大的条可以保留，这是原视频真实画面；不要额外加纯色背景统一它们。
- 原生模式不重新绘字、不改字体、不人为增加行距，不用文章标题替换视频字幕。
- 脚本模式使用已审核单行台词，白字黑边、水平居中；字号过小时拆句，不通过放大字幕条来补救。

## 常见失败及修正

| 现象 | 原因 | 修正 |
|---|---|---|
| 台词之间像隔着大段空白 | 主图比例固定过小，少量字幕条被平均拉高 | 使用自动主图比例，不显式传过小的 `--hero-fraction` |
| 每条字幕上下背景太多 | 字幕裁切区域过高 | 单行字幕从 `0.78–0.96` 重新预览 |
| 第一条字幕很大，后续字幕很小 | 主图与字幕条分别填满不同形状的区域 | 先拼源像素，再整图统一缩放；原生模式不用 70% 硬填主图 |
| 字幕条之间有黑缝或白缝 | 额外边距、画布未贴合或源黑边被裁入 | 条间距保持 0，并收紧字幕区域 |
| 文字被切边 | 为追求紧凑直接套用窄裁切 | 以完整字幕为硬条件，扩大 `band` 后重新预览 |
| 固定 3:4 上下黑边很厚 | 横屏拼图比 3:4 宽，又用了纯留边 | 保持默认 `--fit crop`；字幕太宽裁不动时，减少过宽的句子或接受部分留边 |
| 两侧裁切切到人物 | 主体偏离画面中心 | 用 `--crop-center` 把裁切窗口移向人物；仍不行时改用 `--fit pad` |
| 五句话不连贯 | 只按画面挑帧，没有先做语义选段 | 回到文字稿重选连续表达，不靠换帧硬拼 |
| 主图人物被切脸 | 时间点或裁切窗口不合适 | 只换第一时间点，必要时调整主图比例 |
| 切头顶、下巴贴字幕条或脸偏一侧 | 选帧只看表情，没看构图 | 按「主图构图检查清单」在前后约 1.5 秒内重找；找不到就在交付中说明 |

## 最终视觉验收

交付前在原尺寸和缩略总览两个尺度检查：

- 缩略图中主画面明显占主导，四条字幕形成紧凑节奏；
- 原尺寸中每个字、描边和标点完整；
- 每张主图都过了「主图构图检查清单」，不达标的已在交付中说明；
- 脚本固定布局主画面约 68–72%、字幕条合计约 28–32%（默认 4 条时）；原生模式检查同源字号没有因各块缩放而变大变小；
- 条与条之间没有额外像素间距；原生固定画布为保留完整内容而出现的外侧留边不算条间距；
- 没有一条因为无文字背景过多而显得“松”；
- 没有为了紧凑牺牲两行字幕完整性；
- 原生模式的台词都来自真实视频像素；脚本模式的台词与已审核 JSON 一致；两者时间顺序都正确；
- 若成品仍显得松散，先收紧 `band`，再检查时间点数量，最后才手动调整主图比例。
````

## File: skills/native-subtitle-quote-image/references/yt-dlp-and-transcripts.md
size: 16702
sha: a470acbd5449055681fa6f03857330aaa966216a
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/references/yt-dlp-and-transcripts.md

````text
# URL 获取与时间轴

当输入是 YouTube 等在线视频链接，而不是本地视频时，读取本文件。`yt-dlp` 只负责获取用户有权处理的视频、元数据和字幕时间轴；最终图片仍由 `native_subtitle_stitch.py` 从真实视频帧生成。

不要因为第一次公开请求被 YouTube 拒绝，就告诉用户“这个 Skill 只能读取本地视频”。URL 获取本来就是此 Skill 的正式入口：先尝试无 Cookie 公开访问；若命中登录或机器人验证，再走本文的 Chrome Cookie 授权流程。

## 先区分两种“字幕”

| 内容 | 用途 | 原生字幕模式 | 脚本字幕模式 |
|---|---|---|---|
| 画面内烧录字幕 | 保留原字幕 | 必须从真实视频帧保留 | 如与后期文字重叠，应换帧或换模式 |
| YouTube 字幕轨、VTT/SRT、Whisper 文字稿 | 理解内容、选题、定位时间点 | 只做索引，不能画进成品 | 经复核后可写入 `lines[].text`，必须标记为后期台词 |

有字幕轨不等于视频画面有字幕。下载后必须实际取帧检查。若用户要求原生字幕，但画面没有烧录字幕，停止并说明；只有用户同意后，才使用本 Skill 的 `render-script` 模式，不要偷偷切换。

## 官方依据

- [yt-dlp 官方 README](https://github.com/yt-dlp/yt-dlp#readme)
- [安装说明](https://github.com/yt-dlp/yt-dlp/wiki/Installation)
- [External JavaScript 指南](https://github.com/yt-dlp/yt-dlp/wiki/EJS)

yt-dlp 当前支持 CPython 3.10+ 和 PyPy 3.11+。完整 YouTube 支持强烈建议 FFmpeg、`yt-dlp-ejs` 和 JavaScript runtime。官方优先推荐 Deno，并默认启用它；Node.js 或 QuickJS 需要通过 `--js-runtimes` 显式启用。Bun 目前仍可用，但官方已将其支持标记为弃用，不应作为新环境首选。

## 环境检查

先运行 Skill 自带的只读诊断：

```bash
python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode
```

如果要绘制中日韩台词，同时检查 CJK 字体：

```bash
python3 "<SKILL_DIR>/scripts/check_environment.py" --url-mode --script-mode
```

它不会安装软件，只报告：

- Python、Pillow、FFmpeg provider 是否可用；
- `yt-dlp` 版本；
- Deno 或其他 JavaScript runtime；
- 脚本模式所需的 CJK 字体（使用 `--script-mode` 时）；
- 可选的 Whisper/语音识别能力。

缺少组件时先向用户说明，再取得安装授权。不要擅自修改系统 Python、包管理器或 shell 配置。

### 安装与更新原则

- 核心渲染依赖：`python3 -m pip install -r "<SKILL_DIR>/requirements.txt"`。
- yt-dlp 可使用官方独立可执行文件，或安装 PyPI 的 `yt-dlp[default]`；`default` extra 会带上官方推荐的 Python 依赖。
- 官方文档当前建议普通用户使用 nightly；若稳定版遇到站点解析问题，先按官方说明更新 nightly，再判断是不是命令或权限问题。
- Deno 使用官方安装方式，当前最低支持 2.3.0；若环境已有 Node.js 22+，可保留 Node，并在每条 yt-dlp 命令中加入 `--js-runtimes node`。

示例（使用 pip 的环境）：

```bash
python3 -m pip install -U "yt-dlp[default]"
```

稳定版出现站点解析错误、且用户同意更新时：

```bash
python3 -m pip install -U --pre "yt-dlp[default]"
```

不要把“安装成功”和“能解析当前链接”混为一谈；安装后至少运行：

```bash
yt-dlp --version
yt-dlp --no-playlist --skip-download --print "%(id)s | %(title)s | %(duration_string)s" "URL"
```

## 获取顺序

### 1. 只读检查元数据

```bash
yt-dlp --no-playlist --skip-download \
  --print "%(id)s | %(title)s | %(channel)s | %(duration_string)s" \
  "URL"
```

使用 Node.js 时：

```bash
yt-dlp --js-runtimes node --no-playlist --skip-download \
  --print "%(id)s | %(title)s | %(channel)s | %(duration_string)s" \
  "URL"
```

先确认链接指向单个目标视频。默认添加 `--no-playlist`，避免一个播放列表被意外整批下载。

### 2. 列出字幕轨

```bash
yt-dlp --no-playlist --list-subs "URL"
```

记录可用语言标签，不要假设一定叫 `zh`、`en` 或 `en-orig`。

### 3. 只下载文字时间轴

优先人工字幕，同时允许自动字幕作为备选：

```bash
yt-dlp --no-playlist --skip-download \
  --write-subs --write-auto-subs \
  --sub-langs "zh.*,en.*" --sub-format vtt \
  -o "source/%(id)s/%(id)s.%(ext)s" \
  "URL"
```

字幕和视频始终分两条命令下载：字幕命令带 `--skip-download`，视频命令不带任何 `--write-*subs` 参数。这样字幕请求失败（例如 429）不会中止视频下载，视频格式出错也不会白白重复请求字幕。

`zh.*` 这类正则会同时匹配 YouTube 的自动翻译轨（标签形如 `zh-Hans-en`），这类轨道最容易触发 HTTP 429。先看 `--list-subs` 的真实标签，只请求需要的一两个，例如人工字幕 `zh-Hans` 和原声自动字幕 `en-orig`；请求多个语言时加 `--sleep-subtitles 5`。

字幕轨先用来建立“内容—时间点”索引。原生模式不把 VTT 画回图片，也不因为文字稿里有一句话，就假设该时刻画面内烧录字幕完全相同。脚本模式可以使用已复核的 VTT/SRT/Whisper 文字，但必须标明为后期绘制，并将人名、数字、专有名词和翻译含义单独核对。

#### 自动字幕的滚动重复

YouTube 自动字幕（含 `en-orig` 等原声轨）是滚动显示的：VTT 里相邻条目常重复上一行文字，同一句话会出现在两三个条目里，条目开始时间也早于该句在画面上完整显示的时刻。直接拿条目开始时间取帧，容易截到上一句或对方的话，看起来像顺序错乱。使用前先：

1. 去重：合并文字相同或前缀包含关系的相邻条目，每句只保留一条，开始时间取该句首次出现的时间，结束时间取最后一次出现的时间；
2. 用去重后条目的中段而不是开始时间作为候选时间点，再用 `sample -t ... --around 0.8` 回看确认；
3. 自动字幕不分说话人，多人对话素材还要按 [end-to-end-workflow.md](end-to-end-workflow.md#多人对话与访谈先标说话人) 补标说话人。

人工字幕一般没有滚动重复，但同样不带说话人。

### 4. 下载视频

通常不需要 4K。1080p 足以做 1440×1920 的社交图；输出尺寸可能放大，但不应宣称提升了真实清晰度。

```bash
yt-dlp --no-playlist \
  -f "bv*[height<=1080]+ba/b[height<=1080]" \
  -o "source/%(id)s/%(id)s.%(ext)s" \
  "URL"
```

用 `scripts/fetch_source.py` 代替直接调 yt-dlp，它把 403/429 的识别、退避重试和尝试日志固定下来（详见下文「用 fetch_source.py 处理 403/429」）：

```bash
python3 "<SKILL_DIR>/scripts/fetch_source.py" "URL" --mode video \
  -f "bv*[height<=1080]+ba/b[height<=1080]" \
  -o "source/%(id)s/%(id)s.%(ext)s"
```

`/` 只在格式**不存在**时生效；某个格式存在但下载时返回 HTTP 403，yt-dlp 不会自动改用下一项。遇到 403 时先更新 yt-dlp 并重试一次（`fetch_source.py` 会自动重试这一次），仍失败就按下表逐级换一条 `-f` 重新下载，每级只试一次：

| 级别 | `-f` 参数 | 说明 |
| --- | --- | --- |
| 1 | `bv*[height<=1080][vcodec^=av01]+ba` | 1080p AV1，优先 |
| 2 | `bv*[height<=1080][vcodec^=vp09]+ba` | 1080p VP9 |
| 3 | `bv*[height<=1080][vcodec^=avc1]+ba[ext=m4a]` | 1080p H.264 + AAC，兼容性最好 |
| 4 | `bv*[height<=1080]+ba` | 1080p 任意编码 |
| 5 | `bv*[height<=720]+ba` | 降到 720p 的分离流 |
| 6 | `b[height<=1080]` | 已合并的单文件；YouTube 上通常只剩 360p |
| 7 | `b` | 任意可用的单文件，最后手段 |

下载前先运行 `yt-dlp --no-playlist -F "URL"` 枚举变体，按 AV1 → VP9 → H.264 的顺序择优，并确认列表里有不低于 720p 的视频流。第 5~7 级实际分辨率可能低于 720p：**必须先向用户说明实际分辨率并取得确认，不得静默接受**；用户不接受就停止并报告。

每次下载后立刻自检，通过后才能抽帧、渲染：

```bash
python3 "<SKILL_DIR>/scripts/native_subtitle_stitch.py" check-source VIDEO --min-height 720
```

`check-source` 读取分辨率，并用 FFmpeg 解码前 N 秒（`--seconds`，默认 10），出现任何解码错误（例如 h264 mmco 报错）或低于 `--min-height` 就以非零状态退出。不传 `--min-height` 时，低于 720p 只警告。自检失败的文件删除后，换下一级变体重试，每级只试一次。

每次尝试（含 403、自检失败）都追加一行到工作目录的 `download-attempts.log`，记录级别、`-f` 参数、结果（成功 / HTTP 403 / 自检失败 / 用户拒绝低清）和错误摘要。所有级别用尽就停止，把日志内容报告给用户，不要继续尝试 extractor 参数。

分离的视频和音频需要 FFmpeg 合并。原生字幕取帧不依赖音频，但保留带音频的完整源文件方便复核内容。重复执行时复用已有文件，不要无理由重新下载。

## 用 fetch_source.py 处理 403/429

`scripts/fetch_source.py` 是 yt-dlp 的调用包装：把错误分类、重试上限和尝试日志固定下来，避免每次凭印象决定重试几次。三种模式对应上面三步：`--mode metadata`、`--mode subs`、`--mode video`。

| 错误类型 | 识别依据 | 重试策略 |
| --- | --- | --- |
| `rate_limited` | `HTTP Error 429` / `Too Many Requests` | 最多 `--retries` 次（默认 3，上限 6），等待 `--backoff`×2^n，单次封顶 600s |
| `forbidden` | `HTTP Error 403` / `Forbidden` | 始终最多 1 次，间隔 5s |
| `bot_check` | 要求登录、年龄验证、Cookie | 不重试，直接停下要求授权 |
| `other` | 其余失败 | 不重试，原样报出 yt-dlp 报错 |

为什么 403 和 429 策略不同：429 是速率问题，等待本身就是解法；403 多是 yt-dlp 版本落后或该格式的签名 URL 已失效，重试再多也不会变，要靠升级 yt-dlp、装好 JavaScript runtime 或换 `-f`。

行为约定：

- 每次尝试（含成功）记一行到 `download-attempts.log`，四列制表符分隔：时间、第几次、错误类型、摘要。`--log` 可改路径。
- 失败时 stderr 同时给出错误类型、具体处理建议和 yt-dlp 原始报错尾部，退出码非零；不静默失败、不把失败当成“只能处理本地视频”。
- 不自行添加 Cookie 参数。用户授权后用 `--extra --cookies-from-browser chrome` 透传，`--extra` 必须放在最后。
- 不绕过 DRM、付费墙、地区限制或平台风控；重试耗尽就停下汇报，不换 IP、不换账号、不遍历浏览器配置。
- 格式回退表仍由调用方逐级执行：脚本只负责单条命令的 403/429 重试，不自己换 `-f`。

## 没有可用字幕轨

按以下顺序处理：

1. 检查视频描述、章节和人工字幕轨；
2. 检查自动字幕轨；
3. 如果画面本身有烧录字幕，可先用候选帧总览人工选句；
4. 用户确实需要长视频的语义选段时，再询问是否允许使用本地 Whisper 或环境中已有的语音转写 Skill。

Whisper 是可选上游，用来生成带时间戳文字稿。它的识别文本不能替代画面内原生字幕；脚本模式需要使用它时，也必须先校对文本，并回到视频帧验证时间点。

## 登录、Cookies 与访问限制

- 只处理用户有权访问、下载和再利用的内容。
- 先执行一次不带 Cookie 的元数据检查。不要把 Cookie 作为所有公开视频的默认参数。
- 遇到 `Sign in to confirm you’re not a bot`、登录、年龄验证或用户自己的非公开视频时，不要退回“只能处理本地视频”；先说明原因并取得授权，再使用 `--cookies-from-browser chrome`。
- 不要求用户粘贴账号密码，不导出或提交 Cookie 文件，不把浏览器配置、访问令牌或绝对路径写入仓库。
- 不绕过 DRM、付费墙、地区限制或其他访问控制。
- Cookie 命令只用于当前来源获取，不得显示 Cookie 内容，也不得把 Cookie 写入日志、来源记录或交付物。
- Cookies 失败时停止并报告，不要遍历或反复尝试多个浏览器账户。

### Chrome Cookie 授权流程

只在无 Cookie 请求明确被访问验证拦截后执行：

1. 向用户复述真实错误，例如 YouTube 要求“登录以确认不是机器人”。
2. 询问：`是否允许我让 yt-dlp 临时读取 Chrome 中已登录的 YouTube Cookie？它只用于获取这个链接的视频和字幕，不会导出、保存或上传 Cookie。`
3. 用户明确同意后，把 `--cookies-from-browser chrome` 加到这个 URL 后续所有 yt-dlp 命令，而不是只加在第一次探测命令上。
4. 默认只读 Chrome 当前默认配置。若机器上有多个 Chrome 配置且默认配置无效，停止并询问用户要使用哪个配置；不要自行扫描所有配置。
5. 若用户拒绝，提供两种清晰选择：让用户自行下载视频后按本地模式继续，或结束 URL 任务。不要把这种受限后的备选说成 Skill 的固有限制。

授权后的元数据检查：

```bash
yt-dlp --cookies-from-browser chrome --js-runtimes node \
  --no-playlist --skip-download \
  --print "%(id)s | %(title)s | %(channel)s | %(duration_string)s" \
  "URL"
```

授权后的字幕轨检查与下载：

```bash
yt-dlp --cookies-from-browser chrome --js-runtimes node \
  --no-playlist --list-subs "URL"

yt-dlp --cookies-from-browser chrome --js-runtimes node \
  --no-playlist --skip-download \
  --write-subs --write-auto-subs \
  --sub-langs "zh.*,en.*" --sub-format vtt \
  -o "source/%(id)s/%(id)s.%(ext)s" \
  "URL"
```

授权后的视频下载：

```bash
yt-dlp --cookies-from-browser chrome --js-runtimes node \
  --no-playlist \
  -f "bv*[height<=1080]+ba/b[height<=1080]" \
  -o "source/%(id)s/%(id)s.%(ext)s" \
  "URL"
```

如果环境使用 Deno，删除 `--js-runtimes node` 即可，Cookie 规则不变。若默认 Chrome 配置不含有效 YouTube 会话，可在用户明确指定配置后使用 yt-dlp 支持的 `chrome:PROFILE` 形式；不要猜测配置名。读取失败、系统钥匙串拒绝访问或站点仍拒绝请求时，只重试一次经过用户确认的同一配置，然后停止并报告具体错误。

## 常见故障

### `yt-dlp` 有版本但 YouTube 格式不完整

先看诊断里是否存在 JavaScript runtime。Deno 默认启用；Node.js 环境必须显式添加：

```bash
yt-dlp --js-runtimes node ...
```

随后更新 yt-dlp。不要先改一串实验性 extractor 参数，因为这会让工作流难以复现。

### YouTube 要求登录以确认不是机器人

这是来源访问验证，不代表 Skill 只能处理本地视频。按“Chrome Cookie 授权流程”先取得用户授权，再让同一 URL 的元数据、字幕和视频命令都带上 `--cookies-from-browser chrome`。用户没有授权时才停止联网获取，并给出本地文件备选。

### 字幕语言下载不到

先运行 `--list-subs`，按真实语言标签修改 `--sub-langs`。不要把自动翻译字幕当成人工原字幕。

### 视频下载报 HTTP 403

403 通常只针对某个具体格式，或说明 yt-dlp 版本已落后于站点改动。`fetch_source.py` 会自动重试一次并把这次记入日志；仍失败时先更新 yt-dlp 并确认 JavaScript runtime 生效，再按“下载视频”一节的格式回退表逐级重试。若所有格式都返回 403，且无 Cookie 的元数据请求也被拒，转到“登录、Cookies 与访问限制”处理，不要循环重试。

### 字幕下载报 HTTP 429

429 表示请求过于频繁，多见于自动翻译字幕轨。处理顺序：

1. 确认字幕命令与视频命令是分开的，视频下载不受影响。
2. 改用 `--list-subs` 中的具体标签，去掉自动翻译轨，只请求一两个语言。
3. 加 `--sleep-requests 1 --sleep-subtitles 5`，等待几分钟后重试一次；用 `fetch_source.py --mode subs` 时这步的退避等待已内置，按 `--retries` / `--backoff` 调整即可。
4. 仍失败时，用已拿到的其他语言字幕定位时间点，或在用户同意后用 Whisper 转写；不要反复请求同一字幕轨。

### 视频下载成功，但图片里没有字幕

这不是取帧失败，而是原生字幕条件不成立。说明该视频只有独立字幕轨；若用户同意后期绘制，转用 `render-script`，否则停止。

### 下载很慢或中断

保留工作目录和分片，重试同一条命令以复用缓存。连续失败后报告网络或站点限制，不要无限重试。
````

## File: skills/native-subtitle-quote-image/agents/openai.yaml
size: 467
sha: 1d68fb0801ad3bd366a404d4f157f6a8305ddbbe
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/agents/openai.yaml

```text
interface:
  display_name: "原生字幕拼图"
  short_description: "读取视频，选句取帧，生成 3:4 或保留原比例的字幕拼图"
  default_prompt: "使用 $native-subtitle-quote-image 把这个视频或链接做成紧凑字幕拼图；若用户未指定模式，先问‘您当前是选择原生字幕还是脚本字幕？’，简述两者区别并等待选择；随后检查来源、字幕类型和环境，再选句、取帧、渲染并质检。"
```

## File: skills/native-subtitle-quote-image/requirements.txt
size: 33
sha: b47f6bd94a71ca40d7182c78ee52466df90e9505
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/requirements.txt

```text
imageio-ffmpeg>=0.5
Pillow>=10.0
```

## File: skills/native-subtitle-quote-image/VERSION
size: 7
sha: 46b81d815a23b1a6b60bc9160f21295a5f9e4e75
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/skills/native-subtitle-quote-image/VERSION

```text
2.11.0
```

## File: README.md
upstream: https://github.com/chengyi-ai/native-subtitle-quote-image/blob/main/README.md

````text
<a name="readme-top"></a>

<div align="center">
  <img src="assets/banner-zh.jpg" alt="原生字幕拼图头图：深色背景上铺满中英韩成品长图，左侧标题「一段视频，拼成字幕长图」" width="880">

  <p><strong>把真实视频帧，做成保留原字幕或绘制台词的长图</strong><br>
  <sub>原生字幕不重绘 · 脚本字幕不冒充原字幕</sub></p>

  <p>
    <a href="#快速开始"><strong>快速开始</strong></a> &nbsp;·&nbsp;
    <a href="#能做什么">了解能力</a> &nbsp;·&nbsp;
    <a href="#成品案例">成品案例</a> &nbsp;·&nbsp;
    <a href="#两种字幕模式">两种模式</a> &nbsp;·&nbsp;
    <a href="README_EN.md">English</a> &nbsp;·&nbsp;
    <a href="README_KO.md">한국어</a>
  </p>

  <p>
    <a href="https://github.com/chengyi-ai/native-subtitle-quote-image/releases"><img src="https://img.shields.io/github/v/release/chengyi-ai/native-subtitle-quote-image?color=369eff&logo=github&labelColor=black&style=flat-square&cacheSeconds=300" alt="最新版本"></a>
    <a href="https://github.com/chengyi-ai/native-subtitle-quote-image/actions/workflows/validate.yml"><img src="https://img.shields.io/github/actions/workflow/status/chengyi-ai/native-subtitle-quote-image/validate.yml?branch=main&label=test&logo=githubactions&logoColor=white&labelColor=black&style=flat-square" alt="测试状态"></a>
    <a href="https://github.com/chengyi-ai/native-subtitle-quote-image/stargazers"><img src="https://img.shields.io/github/stars/chengyi-ai/native-subtitle-quote-image?color=ffcb47&labelColor=black&style=flat-square" alt="GitHub stars"></a>
    <a href="LICENSE"><img src="https://img.shields.io/github/license/chengyi-ai/native-subtitle-quote-image?color=white&labelColor=black&style=flat-square" alt="MIT License"></a>
  </p>
</div>

## 能做什么

- **从视频直接出图**：本地文件或 YouTube 链接进来，经过找句子、精确取帧、拼图、逐张质检，输出原生或脚本字幕 JPG，可按内容布局或指定比例。
- **两种字幕，从不混用**：原生模式只裁切画面里本来就有的字幕；脚本模式把你审核过的台词画到真实画面上，并标明是后期字幕。
- **版式紧凑**：原生字幕先拼源像素，再统一缩放，第一句不会被单独放大；脚本固定布局的主图约占 70%。字幕条之间没有空隙。
- **Agent 能用，脚本也能单独跑**：在 Codex、Claude Code 等 Agent 里用一句话调用；也可以直接运行 Python 脚本。

## 成品案例

本页只展示中文字幕作品，均为 3:4、5 句。英文和韩文作品分别在 [English](README_EN.md#gallery) 与 [한국어](README_KO.md#완성-예시) README 中。点击图片查看原图。

<table>
  <tr>
    <td width="33%" align="center" valign="top"><strong>《大巴上的女孩》</strong><br><sub>原生字幕 · 生命属于你自己</sub><br><a href="examples/gallery/zh/girls-on-the-bus-native.jpg"><img src="examples/gallery/zh/girls-on-the-bus-native.jpg" alt="原生字幕模式：剧集《大巴上的女孩》片段，母亲角色的主画面与 4 条字幕条；5 句中英双语字幕（含主画面上的第一句）都直接裁自视频画面，未识别、未重绘" width="280"></a></td>
    <td width="33%" align="center" valign="top"><strong>里克·鲁宾</strong><br><sub>脚本字幕 · 创意像一片变化的云</sub><br><a href="examples/gallery/zh/rick-rubin-creative-clouds.jpg"><img src="examples/gallery/zh/rick-rubin-creative-clouds.jpg" alt="脚本字幕模式：音乐制作人里克·鲁宾在播客录音室微笑的主画面，下方 5 条后期绘制的中文译写字幕，内容关于创意像一片变化的云" width="280"></a></td>
    <td width="33%" align="center" valign="top"><strong>陈数</strong><br><sub>脚本字幕 · 工作投入，生活简单</sub><br><a href="examples/gallery/zh/chen-shu-simple-life.jpg"><img src="examples/gallery/zh/chen-shu-simple-life.jpg" alt="脚本字幕模式：陈数访谈主画面，下方 5 条依据原字幕整理后重新绘制的中文台词" width="280"></a></td>
  </tr>
</table>

- **原生字幕**：第一张的字幕是视频里已烧录的非官方中英双语字幕（随 Bilibili 搬运版烧录在画面里），直接从画面像素裁切，未识别、未重绘；左上角是原视频平台的水印。
- **脚本字幕**：后两张的中文是后期绘制的整理或翻译台词，不是视频原字幕，也不作为人物的逐字引语。

[查看来源、台词与时间点](examples/README.md#中文案例)

<div align="right"><a href="#readme-top">↑ 回到顶部</a></div>

## 快速开始

**1. 安装 Skill**

```bash
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：

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

> 升级时请先删除旧目录再复制，否则新版本已删除的旧文件会残留（Claude Code 把 `.codex` 换成 `.claude`）：
>
> ```bash
> rm -rf ~/.codex/skills/native-subtitle-quote-image
> ```
>
> ```powershell
> Remove-Item -Recurse -Force "$HOME\.codex\skills\native-subtitle-quote-image"
> ```

<details>
<summary>用 Claude Code、Codex Skill Installer 或其他 Agent？</summary>

<br>

**Claude Code**：复制到 Claude Code 的 Skills 目录。

```bash
mkdir -p ~/.claude/skills && cp -R skills/native-subtitle-quote-image ~/.claude/skills/
```

Windows PowerShell：

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

**Codex Skill Installer**：在 Codex 中调用 `$skill-installer`，让它安装这个目录：

```text
https://github.com/chengyi-ai/native-subtitle-quote-image/tree/main/skills/native-subtitle-quote-image
```

**其他 Agent**：本项目使用开放的 Agent Skills 目录格式。把 `skills/native-subtitle-quote-image/` 复制到目标 Agent 的 Skills 目录即可，具体位置以该 Agent 的文档为准。

</details>

**2. 安装依赖并自检**

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

要处理 YouTube 链接，再装 `yt-dlp`：

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

要画中日韩台词，用 `--script-mode` 检查字体。环境自检是只读的，不会自动安装或修改任何软件；缺组件时，Agent 会先说明用途，征得你同意再装。

**3. 重开一个 Agent 任务，说一句话**

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

<div align="right"><a href="#readme-top">↑ 回到顶部</a></div>

## 两种字幕模式

如果你没有指定模式，Agent 会先问“您当前是选择原生字幕还是脚本字幕？”，并用一句话解释两者区别，再按你的选择处理。

| | 原生字幕 | 脚本字幕 |
|---|---|---|
| **什么时候用** | 关掉播放器的 CC 后，字幕仍然烧在画面里 | 要把已核对的台词、翻译或观点画到真实画面上 |
| **图里的字从哪来** | 视频像素本身，不 OCR 重绘，不翻译改写 | 你审核过的 `lines[].text`，明确属于后期字幕 |
| **命令** | `render` | `render-script` |

> [!IMPORTANT]
> 原生模式的字只能来自视频像素；脚本模式的字只能来自已审核的 JSON，不能冒充原字幕。
> 如果你要原生字幕，但视频只有可开关的字幕轨，Agent 会先说明限制，经你同意后才改用脚本模式。

### 工作流

```mermaid
flowchart LR
  A[本地视频<br>或 YouTube 链接] --> B[获取视频<br>与字幕轨]
  B --> C[检查真实帧<br>区分烧录字幕]
  C --> D[按文字稿<br>选题选句]
  D --> E{锁定模式}
  E -->|原生| F[裁切画面<br>里的字幕条]
  E -->|脚本| G[绘制已<br>审核台词]
  F --> H[按模式渲染<br>逐张质检]
  G --> H
```

Skill 支持三种工作方式：

1. **本地成片**：直接从本地视频选句、取帧、出图，不需要 `yt-dlp`。
2. **URL 完整流程**：用 `yt-dlp` 获取你有权处理的视频、元数据和辅助字幕轨，再决定字幕模式。
3. **内容生产**：读视频、选题、写文章或帖子，最后配字幕截图。其他内容类 Skill 负责上游，本 Skill 负责时间点、真实画面、字幕来源标识和质检。

<div align="right"><a href="#readme-top">↑ 回到顶部</a></div>

## 用一句话调用

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

> [!TIP]
> `$native-subtitle-quote-image` 是 Codex 的写法。在 Claude Code 里可以用 `/native-subtitle-quote-image`，或者直接描述需求。

Agent 会先检查来源、字幕类型和候选帧，确定模式后再生成：

- 逐张 JPG，比例符合所选布局；
- 原生模式的 `原生字幕时间点.json`，或脚本模式的 `lines` JSON；
- 多图任务的 `final_contact_sheet.jpg` 总览图。

<div align="right"><a href="#readme-top">↑ 回到顶部</a></div>

## 命令行

不经过 Agent 也可以直接跑脚本。下面的 `VIDEO` 换成你的视频路径。

**自检来源**：下载后先检查分辨率并解码前 10 秒，坏流或低清在抽帧前就失败（不传 `--min-height` 时低于 720p 只警告）。

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

**挑帧**：生成带时间点的候选帧总览，不用反复试时间点。

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

不传 `--start`、`--end` 和 `--interval` 时，会在整段视频里均匀抽取最多 24 帧。已经知道大概时间点时，可以围绕每个点取前、中、后三帧，避开字幕切换的瞬间：

```bash
python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py sample VIDEO \
  -t 61.2 -t 68.9 -t 74.5 -t 82.0 -t 88.4 \
  --around 0.8 --out focused-candidates.jpg
```

**原生字幕**：先用 `band` 确认字幕的裁切区域，再按 manifest 渲染一组成品。

```bash
python3 skills/native-subtitle-quote-image/scripts/native_subtitle_stitch.py band VIDEO \
  -t 61.2 --band-top 0.78 --band-bottom 0.96 --out band-preview.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
```

**脚本字幕**：准备 `script.json`，然后渲染。

```bash
python3 skills/native-subtitle-quote-image
````
