YouTube 字幕与搜索
视频是大多数研究代理无法读取的主要来源。本技能可将任意 YouTube 视频、频道或搜索查询转换为带时间戳的可引用文本。
所有操作均通过一个 REST API 完成。无需 yt-dlp、无头浏览器或任何二进制文件。
设置
API 需要在环境变量中配置密钥。向 FrontierAgent 的 .env 文件添加一行：
echo 'TRANSCRIPT_API_KEY=sk_your_key_here' >> .env
在 https://transcriptapi.com 获取密钥。免费版提供 100 积分，无需信用卡。
FrontierAgent 启动时会加载 .env 文件，shell 命令会继承其中的环境变量，因此 $TRANSCRIPT_API_KEY 可在下方所有命令中使用。
如果该变量为空，请停止操作并告知用户添加密钥。不要猜测密钥，也不要将密钥值打印给用户。
每个请求都需要两个请求头
Authorization: Bearer $TRANSCRIPT_API_KEY 和一个真实的 User-Agent。缺少或使用默认的 User-Agent 会收到 Cloudflare 的 403 响应，错误代码 1010。
获取字幕
消耗 1 积分。video_url 接受完整的 YouTube URL 或 11 位视频 ID。
curl -sS -G "https://transcriptapi.com/api/v2/youtube/transcript" \
--data-urlencode "video_url=$VIDEO" \
--data-urlencode "format=text" \
--data-urlencode "send_metadata=true" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
当需要逐段的 start 和 duration 值（例如引用时间戳）时，请使用 format=json。JSON 格式为：
{"video_id": "...", "language": "en", "transcript": [{"text": "...", "start": 18.0, "duration": 3.5}]}。
搜索视频或频道
消耗 1 积分。type 取 video 或 channel，limit 取值范围为 1 到 50。
curl -sS -G "https://transcriptapi.com/api/v2/youtube/search" \
--data-urlencode "q=$QUERY" \
--data-urlencode "type=video" \
--data-urlencode "limit=20" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
解析频道句柄
免费，不消耗积分。接受 @handle、频道 URL 或 UC... 格式的 ID。
curl -sS -G "https://transcriptapi.com/api/v2/youtube/channel/resolve" \
--data-urlencode "input=@TED" \
-H "Authorization: Bearer $TRANSCRIPT_API_KEY" \
-H "User-Agent: FrontierAgent/1.0"
其他频道端点可直接接受相同的 channel 值，因此通常无需先进行解析。
辅助脚本
scripts/transcript.sh 封装了字幕调用，当密钥缺失时会显式报错。
bash plugins/skills/youtube-transcripts/scripts/transcript.sh "https://www.youtube.com/watch?v=nm1TxQj9IsQ"
调用失败的处理
| 状态码 | 含义 | 处理方式 |
|---|---|---|
| 401 | 密钥错误或缺失 | 请用户检查 .env 中的 TRANSCRIPT_API_KEY |
| 403 | Cloudflare 拦截了请求 | 未添加 User-Agent 头。添加后重试 |
| 404 | 视频没有字幕 | 明确告知用户。不要伪造字幕 |
| 422 | 视频 ID 或 URL 格式错误 | 从用户提供的链接中重新读取 ID |
| 429 | 积分不足或触发限流 | 报告情况。不要循环重试 |
长字幕可能超出工具输出预算。请请求 format=text，将正文写入文件 > outputs/transcript.txt，然后读取所需部分。
处理返回结果
当精确措辞承载了主张时，请直接引用字幕而非转述。自动字幕可能存在识别错误，因此遇到异常的技术术语时应保持怀疑，并在基于其构建论点之前对照视频标题或描述进行验证。