YouTube 视频摘要（youtube2md）

使用该软件包/仓库中官方发布的 youtube2md CLI 行为（固定版本 youtube2md@1.1.0）。

运行时与安全前提条件

• 要求 Node.js 20.18.1+。
• 要求已在系统 PATH 中预安装 youtube2md。
  • 推荐的固定版本安装方式：npm i -g youtube2md@1.1.0
• 默认执行器仅调用本地的 youtube2md 可执行文件。
• 本技能执行器**不支持**运行时 npm 执行（npx）。
• 执行器**拒绝接受**通过 YOUTUBE2MD_BIN 环境变量指定可执行路径的覆盖行为。
• 完整模式（full mode）需要配置摘要提供方；当使用 --provider auto 时，youtube2md 尝试按以下顺序启用：
  1. Codex SDK（需 ChatGPT 登录） —— 当可选对等依赖 @openai/codex-sdk 已安装，且存在已通过 ChatGPT 认证的 Codex 会话时启用。OPENAI_API_KEY 不会传递给 Codex。
  2. OpenAI API —— 当 Codex 不可用或失败，且 OPENAI_API_KEY 已设置时启用。
• 任一提供方均会将基于字幕提取的内容发送至 OpenAI 系统；对于敏感内容，请在字幕可用时优先使用简单模式（simple）或字幕模式（transcript）。
• 模型默认值：执行器仅在第五个执行器参数或 YOUTUBE2MD_DEFAULT_MODEL 环境变量被显式设置时，才向下游传递 --model 参数；否则采用上游默认模型（两个提供方均为 gpt-5.6-luna），或由各提供方专属环境变量 CODEX_MODEL / OPENAI_MODEL 控制。
• 提取模式（extract mode）默认启用 --captions-only：在简单/字幕模式下，音频**永远不会**发送至 Whisper。如需对无字幕视频启用 Whisper 语音转文字（STT），请设置 YOUTUBE2MD_CAPTIONS_ONLY=0（此时需配置 OPENAI_API_KEY）。
• 当 YouTube 封禁匿名访问字幕/音频时，可使用 YOUTUBE_COOKIES_PATH 或 YOUTUBE_COOKIE_HEADER。
• 在敏感环境中，应在安装或未来升级版本前，审计上游 youtube2md@1.1.0 及其全部依赖项。

首次安装/启用前，请参阅 references/security.md。

工作流程

1. 输入校验

   • 接受 youtube.com 和 youtu.be 域名下的 URL（支持 watch、Shorts、Live、Embed、Music 及 youtube-nocookie.com 的嵌入格式；带时间戳的 &t= URL 可被接受，但整段视频仍将被完整处理）。
   • 若 URL 中包含 & 字符，在 shell 中传入时需加引号。
   • 若用户消息中仅含 YouTube URL，则视作请求使用本技能进行摘要。
   • 若仅提供 YouTube URL 而未明确指定任务，默认输出摘要，而非仅字幕。
   • 若未提供 URL，请提示用户每行输入一个 URL。

2. 选择模式

   • 完整模式（Full mode）：使用 youtube2md 的摘要流水线生成 Markdown（优先尝试 Codex ChatGPT 登录，失败后回退至 OpenAI API）。
     • 若任一提供方可用（Codex ChatGPT 登录或已配置 OPENAI_API_KEY），且外部 API 调用可接受，建议优先尝试完整模式。
     • 摘要详略程度可通过 YOUTUBE2MD_DETAIL=concise|balanced|exhaustive 调节（上游默认为 balanced）。当用户要求“极详细”或“接近逐字稿”的摘要时使用 exhaustive；仅需快速概览时使用 concise。
   • 简单模式（Simple mode）：内部调用 youtube2md 的 --extract-only --extract-format timestamped-text --captions-only，先生成带时间戳的 .txt 字幕稿，再基于该文本进行摘要。
     • 适用于无可用提供方、内容敏感、不可调用外部 API，或完整模式失败/自动回退的场景。
   • 字幕模式（Transcript mode）：复用相同提取路径，但仅返回字幕内容，不生成摘要。
     • 当用户明确请求“字幕提取”、“仅字幕输出”、“原始字幕”或机器可读的字幕 JSON（YOUTUBE2MD_EXTRACT_FORMAT=json）时启用。
   • 优先保障无错误路径：执行器预先检查提供方可用性，并在完整模式无法运行时自动切换至提取路径。

3. 运行转换器

   • 首选执行脚本：
     • scripts/run_youtube2md.sh full [output_md_path] [language] [model]
       • 若无可用于摘要的提供方，执行器将自动回退至内部提取路径；此时摘要输出应标注为“简单模式（simple）”。
       • [model] 与 YOUTUBE2MD_DEFAULT_MODEL 均为可选项；若未指定，则采用上游默认值。
     • scripts/run_youtube2md.sh extract [output_txt_path]
       • extract 是执行器/CLI 的模式名称；默认输出为带时间戳的纯文本（.txt）。
       • 若基于该 .txt 文件进一步生成摘要，则对外披露为 simple 模式。
       • 若直接返回字幕内容而不生成摘要，则对外披露为 transcript 模式。
   • 可选的机器可读 CLI 输出：
     • YOUTUBE2MD_JSON=1 scripts/run_youtube2md.sh full
     • YOUTUBE2MD_JSON=1 scripts/run_youtube2md.sh extract
     • 启用 --json 或 --stdout 后，标准输出（stdout）仅承载单个数据载荷；执行器状态信息输出至标准错误（stderr）。
   • 可选的标准输出/无文件模式：
     • YOUTUBE2MD_STDOUT=1 scripts/run_youtube2md.sh extract
   • 可选的输出目录：
     • YOUTUBE2MD_OUT_DIR=./output scripts/run_youtube2md.sh extract
   • 可选的字幕语言偏好：
     • YOUTUBE2MD_CAPTION_LANG=ko scripts/run_youtube2md.sh extract
   • 可选的完整模式摘要密度：
     • YOUTUBE2MD_DETAIL=exhaustive scripts/run_youtube2md.sh full
   • 运行时控制：
     • 仅使用本地已安装的 youtube2md 可执行文件。
     • 本技能**不得**使用运行时 npm 执行（npx）。
   • 等效的直接 CLI 命令：
     • 完整模式：youtube2md --url [--out ] [--out-dir ] [--lang ] [--model ] [--provider auto|codex|openai] [--detail concise|balanced|exhaustive]
     • 简单/字幕模式：youtube2md --url --extract-only --extract-format timestamped-text --captions-only [--out ]
     • 添加 --caption-lang 以指定首选字幕语言。
     • 添加 --json 可获得带版本标识的机器可读结果封装体（含 outputPath 字段）。
     • 添加 --stdout 可将输出写入标准输出而非文件。

4. 验证输出

   • 完整模式：Markdown 文件存在且非空（除非启用了 --stdout）。
   • 简单模式：当启用文件输出时，带时间戳的 .txt 字幕稿存在且非空。
   • 字幕模式：.txt 或 .json 字幕输出存在且非空（除非启用了 --stdout）。
   • 若启用 --json，请解析封装体字段：ok: true/false、outputPath、transcriptSource、actualLanguage、provider、fallbackUsed；具体错误码处理请参考 references/troubleshooting.md。

5. 向用户响应

   • 遵循 references/output-format.md 中定义的响应结构：完整模式为包原生 Markdown 的逐字透传；简单/字幕模式采用紧凑的作者结构化格式。
   • 遵循 references/summarization-behavior.md 中定义的源策略及章节/要点密度规则。
   • 摘要内容必须以内联方式完整呈现于回复中——禁止以附件、下载链接或元描述替代实际内容，无论长度如何。即使是对长达 3 小时、含 100+ 章节的视频，也必须将完整摘要粘贴至回复正文；长度绝不能成为附加、截断或二次摘要的理由。
   • **不得**在面向用户的常规回复中包含生成的本地文件路径。
   • 仅当用户明确要求时（例如调试/导出流程），方可共享文件路径或生成导出文件。
   • 摘要源策略：
     • 完整模式成功 → youtube2md 生成的 Markdown 输出即为最终摘要；须逐字呈现（仅追加模式行）。**不得**重新摘要、压缩、删减章节/要点，或重排为紧凑模板——这将丢失包本身产出的细节。此设计确保本技能的行为与直接运行 youtube2md 完全一致。
     • 简单模式 → Claude 基于带时间戳的 .txt 字幕稿，按 references/output-format.md 中的紧凑结构生成摘要。
     • 字幕模式 → 返回字幕内容或所请求的字幕制品详情，不生成摘要。
   • 始终在面向用户的最终结果后追加一行模式标识：
     • Mode: full
     • Mode: simple
     • Mode: simple (fallback from full; no summarization provider available)：当用户请求完整模式但执行器因无可用提供方而回退，且仍生成了摘要时使用。
     • Mode: transcript：当用户明确请求仅字幕输出时使用。
   • 保持面向用户的交互流畅：若无可用于摘要的提供方，应直接使用简单模式输出，并基于 .txt 进行摘要，避免向用户暴露本可规避的工具错误信息。