🎯 学什么：学会封装「外部 API（API/应用程序接口：让不同软件之间互相通信的"插座"，调用它就能使用外部服务功能）调用 + 后处理」型 Skill。理解何时该用脚本、何时该用 AI。这是继 L1-01（工具型）和 L1-03（流水线型）之后的第三种核心 Skill 架构。 💡 难易度：⭐⭐ | ⏱️ 预计时间：45 分钟

1. 课程概览

💡 白话小课堂：你有没有遇到过想引用一个 YouTube 视频里的话，但不想手动打字？这个 Skill 就像「视频录音笔」——给它一个 YouTube 链接，它自动把视频里的字幕（支持中英文和多语言）全扒下来，还能帮你做章节分段、识别说话人、翻译成其他语言。

本课跟前面三课的关系——这是三种核心 Skill 架构的最后一环：

课程	架构类型	脚本的角色	AI 的角色
[[L1-01-智能图片压缩\|L1-01]]	工具型	做所有事	传话筒（调脚本）
[[L1-03-Markdown格式化排版\|L1-03]]	流水线型	做排版修正（Step 6）	核心工人（分析+格式化）
L1-04（本课）	API 桥接型	获取数据（API 调用+缓存）	后处理增值（摘要+翻译+分段）

🔑 核心秘诀：三层封装的核心逻辑——「确定性的事情让脚本做，不确定性的事情让 AI 做」。API 调用、错误重试、数据缓存是确定性的（脚本处理）；理解用户意图、格式化输出、生成摘要是不确定性的（AI 处理）。分工越清晰，Skill 越可靠。

⚠️ 避坑指南：description（description/描述字段：Skill 的"自我介绍"，写在 YAML 头部，AI 据此判断是否加载——写得不好 AI 永不加载正文）的详细程度取决于「用户有多少种表达方式」。YouTube 字幕场景用户表达非常集中——"字幕""transcript""captions""download subtitles"——2-3 个触发词就够了。不要像 L1-02 那样罗列一堆触发词，那只会浪费 token（token/词元：AI 处理文本的最小单位，约等于 0.75 个英文单词或 1 个汉字，消耗量直接影响费用和速度）。

2. 三层封装详解

baoyu-youtube-transcript 的结构体现了「API 桥接型」Skill 的核心设计模式：三层分工，各司其职。

┌──────────────────────────────────────────────┐
│              用户说「帮我扒这个视频的字幕」        │
└────────────────────┬─────────────────────────┘
                     │
┌────────────────────▼─────────────────────────┐
│  Layer 3: LLM 后处理层                        │
│  • 字幕摘要（要点总结 + 时间戳）                   │
│  • 说话人识别（sub-agent + prompt模板）           │
│  • 翻译（多语言输出）                             │
│  • 格式化输出（标题/段落/时间戳）                    │
│  → AI 做：需要语义理解的增值工作                    │
└────────────────────┬─────────────────────────┘
                     │
┌────────────────────▼─────────────────────────┐
│  Layer 2: SKILL.md 正文层                     │
│  • 告诉 AI「什么时候用这个 Skill」                │
│  • 参数说明（--languages, --chapters, --speakers）│
│  • 输出格式说明（text/srt）                      │
│  • 错误处理指南                                  │
│  → 连接层：AI 和脚本之间的「翻译官」                 │
└────────────────────┬─────────────────────────┘
                     │
┌────────────────────▼─────────────────────────┐
│  Layer 1: CLI 脚本层（scripts/main.ts）         │
│  • YouTube InnerTube API（API/应用程序接口：让不同软件之间互相通信的"插座"） 调用（无需 API Key）   │
│  • 数据缓存（meta.json + transcript-raw.json）  │
│  • 错误重试 + yt-dlp 自动回退                    │
│  • 句子切分 + 时间戳计算                          │
│  → 脚本做：确定性的技术操作                        │
└──────────────────────────────────────────────┘

Layer 1：CLI 脚本层 —— 为什么不用 AI 调 API？

这是最容易被新手搞错的地方。很多人会想：「AI 直接调 YouTube API 不就行了？为什么要中间夹一层脚本？」

答案是：AI 不擅长做确定性操作。

操作	为什么不适合 AI 做	为什么适合脚本做
API 调用 + 认证	AI 需要记住 token、管理 session，每次多消耗几百 token	脚本一行 `fetch()` 搞定
错误重试	AI 需要判断"这是网络问题还是 API 限流"，逻辑复杂	脚本 try-catch + 指数退避，经典模式
数据缓存	AI 没有"记住上次结果"的能力（上下文外的数据全丢）	脚本写 JSON 到磁盘，永久缓存
句子切分 + 时间戳计算	纯算法问题，不需要任何语义理解	脚本按标点切分，按字符比例分配时间戳

缓存策略是 Layer 1 最精妙的设计：

第一次提取视频 A 的字幕：
  → 脚本访问 YouTube API → 下载原始数据
  → 保存 meta.json + transcript-raw.json + transcript-sentences.json + cover.jpg
  → 生成 transcript.md

第二次提取同一个视频 A 的字幕（比如换一种语言）：
  → 脚本检测到缓存已存在 → 零网络请求
  → 直接从缓存文件重新格式化输出
  → 速度快 10 倍 + 不消耗 API 配额

🔑 设计要点：缓存的粒度选择——缓存「原始数据」而非「最终输出」。如果缓存的是最终 .md 文件，用户想换格式（text → srt）就得重新请求。缓存 raw data，格式化可以反复跑。

回退策略：当 YouTube 封锁 InnerTube API 时，脚本自动回退到 yt-dlp。用户无需感知——脚本内部决策，对外表现一致。

Layer 2：SKILL.md 正文层 —— AI 和脚本之间的「翻译官」

这一层不执行任何代码，但它决定了 AI 能不能正确地调用 Layer 1。

它做了什么：

告诉 AI 何时触发：description 中列出触发词——"YouTube transcript""下载字幕""get captions"
告诉 AI 传什么参数：参数表 + 默认值（--languages en、--format text）
告诉 AI 输出格式：Markdown（含 frontmatter + 时间戳 + 可选目录/章节/说话人）、SRT（视频播放器可用）
告诉 AI 怎么处理错误：错误码含义表——Transcripts disabled、Video unavailable、IP blocked 等

💡 白话小课堂：Layer 2 就像餐厅菜单——你不需要知道厨房（Layer 1）怎么做菜，但你需要知道有哪些菜、怎么点、上菜是什么样。description 比 L1-02 短是因为"点菜方式"简单——用户基本只说"字幕"或"transcript"，不需要罗列 10 种触发词。

参数设计的关键：--chapters 和 --speakers 默认开启——"默认最佳"原则。用户不传参数就能拿到最丰富的输出（含章节分段 + 说话人标注）。想精简？自己关掉。

Layer 3：LLM 后处理层 —— AI 真正发挥价值的地方

Layer 1 返回的是「数据」，Layer 3 把它变成「知识」。

后处理的三种典型场景：

后处理	输入	输出	AI 做了什么
要点总结	完整字幕文本	产品功能点 + 时间戳列表	理解内容 → 提取关键信息 → 关联时间点
说话人识别	原始字幕 + 视频元数据	标注了 `Speaker Name:` 的对话	从标题猜嘉宾 → 从对话模式判断话轮 → 用子 Agent 降低成本
翻译	英文字幕	中/日/其他语言字幕	语义翻译（非字面翻译）→ 保持术语一致性

说话人识别的设计特别值得学：

主流程（SKILL.md 正文的 AI，通常是 Opus/Sonnet）：
  → 调脚本拿到 raw transcript（含 SRT 时间戳 + 视频描述）
  → 决定需要说话人识别

子 Agent（spawn 一个更便宜的模型，如 Haiku）：
  → 读 {baseDir}/prompts/speaker-transcript.md（prompt 模板）
  → 分析视频元数据 → 从标题提取嘉宾名、从频道名提取主持人名
  → 从对话模式判断话轮（问答模式、上下文线索）
  → 覆盖写入带说话人标注的 .md 文件

🔑 设计要点：为什么用子 Agent 而非主流程直接做？两个原因：(1) 成本——说话人识别是机械的文本处理，不需要 Opus 级别的推理能力，用 Haiku 便宜 10 倍；(2) 上下文隔离——子 Agent 的 prompt 模板独立维护，改模板不需要改 SKILL.md。

L1-04 与 L1-03 的分工线对比

两课都有「AI + 脚本」协作，但分工线完全不同：

L1-03（流水线型）：
  AI 做核心工作（Step 2-5: 分析+格式化） → 脚本做收尾修正（Step 6: 排版）
  分工逻辑：AI 理解内容 → 脚本不动内容只改格式

L1-04（API 桥接型）：
  脚本做核心工作（Layer 1: API调用+缓存+数据提取） → AI 做增值后处理（Layer 3: 摘要+翻译+识别）
  分工逻辑：脚本获取原始数据 → AI 把数据变知识

🔑 一句话记：L1-03 是「AI 主厨 + 脚本洗碗」，L1-04 是「脚本买菜备菜 + AI 炒菜摆盘」。

3. 结构拆解：API 桥接型模板

从 L1-04 的三层架构中提取可复用的模板：

name: [skill-name] description: [功能描述 + 触发词] ← 触发词数量取决于用户表达方式的集中度

[功能名]

[一句话功能描述]

Script Directory

Script	Purpose
`scripts/main.ts`	[核心 CLI：API 调用 + 数据缓存 + 错误处理]

Usage

${BUN_X} {baseDir}/scripts/main.ts <input> [options]

Options

Option	Description	Default
`<input>`	[输入描述]	Required
`--format`	[输出格式选项]	[默认格式]
...	...	...

Workflow

调脚本获取原始数据
检查缓存 → 复用或强制刷新
[可选] LLM 后处理：[摘要/翻译/分析/格式化]
输出最终结果

Post-Processing（后处理）

[定义 AI 在脚本输出之上做什么增值工作]

场景 1：[摘要] → 用什么 prompt / 模板
场景 2：[翻译] → 注意事项
...

Error Cases

Error	Meaning
[错误信息]	[原因 + 处理建议]

API 桥接型 vs 工具型 vs 流水线型：

特征	工具型（L1-01）	流水线型（L1-03）	API 桥接型（L1-04）
核心步骤	1 步（调脚本）	7 步（工位流）	2-3 步（获取→后处理→输出）
谁做核心工作	脚本	AI	脚本获取 + AI 增值
中间产物	无	分析报告文件	原始数据缓存（JSON）
后处理	不需要	排版脚本	LLM 摘要/翻译/识别
适合场景	确定性技术操作	需要判断力的编辑	数据获取 + 智能加工
典型例子	图片压缩、格式转换	文章排版、代码审查	字幕提取、网页抓取

什么时候用 API 桥接型？ → 当任务本质是「从外部获取数据」+「根据用户意图加工数据」。数据获取是确定性的（脚本），加工方式因人而异（AI）。

这个模板的三个变通点：

缓存不是必选——数据变化频繁（如实时股价）就不要缓存
后处理可深可浅——简单场景只格式化，复杂场景加摘要+翻译+分析
子 Agent 不是必选——只有当后处理任务量大且不需要高级推理时才用（降成本）

4. 电商案例：提取竞品测评视频字幕——搭建产品卖点对比库

🛒 实战案例：某国产美妆品牌的产品经理需要跟踪YouTube上8个海外竞品品牌的测评视频。每周约15个新测评视频发布（英文/日文），团队要从中提取：消费者最关心的功效维度（控油vs保湿vs遮瑕）、测评博主反复提到的优点和槽点、评论区高频问题。过去逐个人工看视频+手动记笔记，每周花12小时，而且「那个博主上个月好像吐槽过这个成分」永远靠记忆找不回来。

用 baoyu-youtube-transcript 搭建竞品测评知识库：

Step 1：自动采集——每周新测评视频发布后，一键提取字幕（原语言+英文翻译）：

${BUN_X} {baseDir}/scripts/main.ts 'https://youtube.com/watch?v=xxx' \
  --languages en,ja --chapters --speakers

Step 2：LLM 后处理——提取三种结构化信息（这是 Layer 3 的核心价值）：

输出类型	从字幕中提取什么	服务于谁
卖点对比表	博主提到的优点和槽点，按"产品名+功效维度"整理	产品经理——竞品差距一目了然，不需要看完整视频
消费者关注点	评论区高频问题聚类（如"适合敏感肌吗""持妆几小时"）	市场部——知道消费者真正关心什么，反哺产品详情页文案
成分关键词	被反复提到的成分名及其评价语境（正面/负面）	研发部——竞品主打成分的市场反馈，指导配方方向

Step 3：Obsidian 全文检索——存入 竞品测评/ 目录，按品牌+发布月份归档，支持全文搜索。搜索"retinol 刺痛"能找到所有相关视频中关于视黄醇刺激性的讨论。

效果：

竞品信息收集从每周12小时 → 1.5小时（减少87.5%）
8个品牌的300+条测评视频形成可搜索知识库
新产品brief中的竞品分析从"印象流"变成"数据流"——每条卖点决策背后都有可追溯的视频来源
一份字幕同时服务于产品、市场、研发三个部门——被复用了3次

🔑 启示：竞品测评视频不是看一遍就完了——里面藏着消费者真实的关注点和竞品的真正短板。但没有人有时间看完300个视频。API桥接型Skill的价值不是"提取字幕"（那只是一个API调用），而是"让字幕变成可搜索、可对比、可追溯的战略情报"。

5. 手写模仿

不看源码，写一个「GitHub Issue 获取器」Skill。

要求：

name: gh-issue-fetcher
功能：输入 issue URL，获取标题+正文+评论 → 格式化为 Markdown
可选后处理：LLM 摘要 + 关键讨论点提取
输出：{repo}-{issue-number}.md

点击查看参考写法

name: gh-issue-fetcher description: Fetches GitHub issues and converts to markdown with optional LLM summary. Use when user asks to "get github issue", "fetch issue", "下载 issue", "查看 issue".

GitHub Issue Fetcher

Fetches GitHub issues via gh CLI, formats as structured markdown.

CLI Setup

脚本路径：scripts/fetch-issue.ts（{baseDir} = SKILL.md 所在目录，跟所有工具型 Skill 一样）

选择运行时：检测系统有 bun 还是 npx → 填入 ${BUN} 占位符
验证 gh CLI 已安装并登录：gh auth status
拼出脚本路径：${FETCH} = {baseDir}/scripts/fetch-issue.ts

步骤 1 和 3 的原始写法是 ${BUN} 和 ${FETCH}，它们都是模板占位符——运行时系统会自动把 ${BUN} 替换为实际的 bun/npx，把 ${FETCH} 替换为脚本的实际路径。

Usage

# ${BUN} = 运行时选择器  |  ${FETCH} = 脚本实际路径
${BUN} ${FETCH} <issue-url> [options]

Options

Option	Description	Default
`<url>`	GitHub issue URL	Required
`--output`	Output file path	{owner}-{repo}-#{num}.md
`--comments`	Include comments	true
`--reactions`	Include reaction counts	false
`--summarize`	Generate LLM summary	false

Post-Processing

After fetching, optionally:

LLM 摘要：提取核心问题、关键讨论、最终结论
相关 Issue：如果有引用 issue，提取并标注

Output

{title}

Repo: {owner}/{repo} · Issue #{num} 作者: @{author} · 状态: {open/closed} 创建: {date} · 标签: {labels}

正文

{body}

评论（{count}条）

@{commenter} · {date}

{comment body}

5.1 延伸思考：API 调用的 3 个常见坑

坑	为什么	怎么避免
API 挂了导致 Skill 失败	外部依赖不可控	脚本内加重试 + 友好错误提示
响应格式变了	API 升级	脚本做格式验证，不符合预期时报错
调用太慢	网络延迟	设置 timeout，超时后建议用户稍后再试

🔑 延伸：这三个坑的解决策略都在 Layer 1（脚本层），不是因为 AI 不能处理它们，而是因为这些处理逻辑是确定性的——重试几次、超时多久、格式怎么验证——不应该浪费 AI 的 token 和判断力。

6. 掌握检验

Q1：baoyu-youtube-transcript 属于「API 桥接型」Skill。它的三层封装分别是什么？

A) 前端 Layer → 后端 Layer → 数据库 Layer
B) CLI 脚本层 → SKILL.md 正文层 → LLM 后处理层
C) 用户输入层 → 数据缓存层 → 输出格式化层
D) API Key 管理层 → 网络请求层 → 错误处理层

Q2：为什么 baoyu-youtube-transcript 的 description 比 L1-02（url-to-markdown）短很多？

A) YouTube 的功能比网页转换简单，所以描述可以简短
B) 用户的表达方式集中（基本只说 "youtube transcript" 或 "字幕"），不需要罗列大量触发词
C) 作者为了减少 YAML 头部占用的 token 数
D) 因为 YouTube API 的文档写得更详细，SKILL.md 不需要重复

Q3：为什么不让 AI 直接调用 YouTube API，而非要让脚本处理 API 调用？这里「确定性」和「不确定性」的分工线在哪里？请结合三个具体操作（API 调用、错误重试、数据缓存）来说明。

Q4：在 baoyu-youtube-transcript 中，LLM 后处理适合用来做什么？什么情况下不需要 LLM 后处理？给出具体例子。说话人识别为什么用子 Agent（便宜模型）而不是主流程 AI 直接处理？

Q5：以下哪项不是 API 调用常见的坑（常见问题）？

A) API 服务挂了导致 Skill 失败
B) 响应格式变更导致解析错误
C) 网络延迟导致调用太慢
D) API 返回的数据太完整导致本地存储不够

Q6：L1-04（API 桥接型）和 L1-03（流水线型）都有「AI + 脚本」协作，但分工线不同。请对比两种架构中 AI 和脚本各自的角色，并说明分工依据。

Q7：某智能硬件电商想用 YouTube 字幕构建产品视频知识库。提取字幕后，LLM 可以生成哪三种后处理输出？每种输出分别服务于什么用户场景？为什么缓存「原始数据」而非「最终输出」？

7. 答案

点击查看答案

Q1：B — 三层依次是：Layer 1: CLI 脚本层（scripts/）管理 API 调用、认证、错误重试、数据缓存；Layer 2: SKILL.md 正文告诉 AI 何时调用、传什么参数、如何输出；Layer 3: LLM 后处理层，可选的摘要/翻译/关键点提取/说话人识别。A 是通用的前后端分层，C 和 D 只涵盖了部分职责。

Q2：B — description 的长度取决于用户表达需求的多样性。YouTube 字幕场景中用户表达方式非常集中（"YouTube transcript"、"字幕"、"download subtitles"），只需要 2-3 个触发词即可。而 url-to-markdown 场景用户表达多样（"save page"、"convert URL"、"fetch page"、"保存网页"），需要罗列更多触发词。判断标准：用户只有 2-3 种表达方式 → description 可以简短。

Q3：让 AI 直接调 API 的问题：(1) API 调用：AI 需要管理 HTTP 请求、处理认证、解析响应——每一步都在消耗 token 和上下文，而脚本一个 fetch() 搞定，零 token 消耗；(2) 错误重试：API 限流时需要判断"这是临时故障还是配额用完？该等多久？重试几次？"——这是典型的 if-else 逻辑，脚本做又快又准；(3) 数据缓存：AI 没有持久记忆——每次新会话之前的 API 调用结果全部丢失，必须重新请求。脚本直接写 JSON 到磁盘，下次秒读。核心分工线：确定性 = 脚本（有明确规则可循），不确定性 = AI（需要理解和判断）。

Q4：LLM 后处理适用于需要理解和创造的任务：1) 要点总结——从完整字幕中提取产品功能点 + 时间戳；2) 操作步骤提取——将教程视频字幕转化为分步操作指南；3) FAQ 生成——识别字幕中的常见问题对，自动生成 FAQ 条目。不需要 LLM 后处理的场景：用户只需要原始字幕文本（翻译人员需要双语对照）、只需要特定语言的字幕（直接输出）、只需要 SRT 格式用于视频播放器加载。说话人识别用子 Agent（便宜模型）的原因：说话人识别本质是模式匹配（从标题提取名字、从对话模式判断话轮）而非深度推理——不需要 Opus 级别的模型，用 Haiku 便宜 10 倍且效果足够。同时子 Agent 的 prompt 模板独立维护，和主 SKILL.md 解耦。

Q5：D — "API 返回的数据太完整导致存储不够"不是本节讨论的常见坑。三个真实坑位是：API 服务挂了（外部依赖不可控，需加重试和友好错误提示）、响应格式变了（API 升级，需做格式验证）、调用太慢（网络延迟，需设 timeout）。A、B、C 都是真实坑位。

Q6：L1-03（流水线型）：AI 做核心工作（Step 2-5：读文章→分析→标题→格式化），脚本做收尾修正（Step 6：排版脚本修 CJK 间距/标点/引号）。分工逻辑：AI 理解内容质量（需要语义）→ 脚本不动内容只改格式（纯规则）。L1-04（API 桥接型）：脚本做核心工作（Layer 1：API 调用+缓存+数据提取），AI 做增值后处理（Layer 3：摘要+翻译+识别）。分工逻辑：脚本获取原始数据（确定性）→ AI 把数据变知识（需要理解和判断）。一句话：L1-03 是「AI 主厨 + 脚本洗碗」，L1-04 是「脚本买菜备菜 + AI 炒菜摆盘」。

Q7：三种后处理输出及服务场景：1) 要点总结（产品功能点 + 时间戳）——服务于客服团队快速查阅，将 1 小时视频压缩为 5 分钟阅读材料，遇到用户问"视频里说的功能怎么用"时按关键词搜索 15 秒搞定；2) 操作步骤（分步教程）——服务于终端用户，将视频教程转化为可打印、可复制粘贴的文字教程；3) FAQ 条目——服务于知识库建设，从视频中自动识别常见问题对，FAQ 覆盖率提升 40%。缓存「原始数据」而非「最终输出」的原因：如果用户先要 Markdown 格式、后要 SRT 格式，缓存 raw data 可以直接从缓存重新生成不同格式——零网络请求；如果缓存的是最终 .md 文件，要 SRT 就得重新调 API。

（6/7 通过）

8. 延伸阅读

[[L1-05-封面图智能生成|下一课：文章封面图生成]] — 从「索取型 API」到「生成型 API」的范式转换
[[L1-02-网页转Markdown|L1-02：网页转Markdown]] — 更复杂的 API 桥接 + 质量闸门
[[L1-03-Markdown格式化排版|L1-03：Markdown格式化]] — 回顾「AI + 脚本」协作的另一种分工模式