企业官网建设流程全解析

• 人工智能
• AI Agent
• MCP 服务
• AI 技能
• CLI

本篇技术指南以 Agent-Reach 的 视频/播客参考文档 为核心骨架，系统讲解如何为 AI Agent 赋予 YouTube、B站、小宇宙播客三大声频平台的内容提取能力。你将掌握 yt-dlp 字幕抓取、bili-cli 只读查询、OpenCLI 浏览器会话补字幕、B站搜索 API 零配置兜底，以及基于 Whisper 的agent-reach transcribe无字幕音视频转录全套实战方案，并理解doctor体检与后端路由的边界（active_backend: yt-dlp不等于字幕已实时验证）。

概览：三平台、五条后端链路

Agent-Reach 对视频与播客内容的处理遵循"多后端路由 + 失败重试链 + 无字幕兜底"的总体设计：

从源码结构看，频道基类 定义了backends有序候选列表与active_backend语义：backends[0]是首选后端，其余为降级路径，用户还可以通过<channel>_backend配置键或<CHANNEL>_BACKEND环境变量强制指定后端。这正是上述"重试链"与"多后端路由"机制的实现基础。

YouTube：用 yt-dlp 提取元数据、字幕与评论

获取视频元数据

--dump-json输出完整视频 JSON（标题、时长、UP主、播放互动数据等），是 Agent 做视频信息检索的基础命令：

yt-dlp --dump-json "URL"

下载字幕（不下载视频）

# 下载字幕 (不下载视频) yt-dlp --write-sub --write-auto-sub --sub-lang "zh-Hans,zh,en" --skip-download -o "/tmp/%(id)s" "URL" # 然后读取 .vtt 文件 cat /tmp/VIDEO_ID.*.vtt

• --write-sub拉取手动上传字幕，--write-auto-sub拉取自动生成字幕，--sub-lang限定语言（中文简繁 + 英文），--skip-download只取字幕不下载视频，-o "/tmp/%(id)s"以视频 ID 命名输出文件。
• 字幕质量注意：手动上传的字幕提取可靠；自动生成字幕可能存在行间重复，需要后处理（Agent 读取.vtt后应做去重/清洗）。

获取评论

# 提取评论（best-effort，不保证完整） yt-dlp --write-comments --skip-download --write-info-json \ --extractor-args "youtube:max_comments=20" \ -o "/tmp/%(id)s" "URL" # 评论在 .info.json 的 comments 字段中

评论注意：--write-comments基于网页抓取（非 YouTube Data API），部分评论可能丢失，属于 best-effort 结果，不应视为完整评论数据。

搜索视频

yt-dlp --dump-json "ytsearch5:query"

ytsearch5:query前缀让 yt-dlp 直接执行搜索并输出前 5 个结果的 JSON，适合 Agent 的"搜索→选取→深入提取"工作流。

前置条件：yt-dlp 与 JS runtime

YouTube 的解密与播放地址解析依赖外部 JS runtime，这一点在 YouTube 通道实现 中体现得很明确：

• 通道check()会真实执行yt-dlp --version探活（而非仅查shutil.which），区分"未安装 / venv 断链跑不动 / 版本过旧"三种状态；
• 缺少 JS runtime（Node.js 或 deno）时返回warn：YouTube 必须使用 JS runtime。安装 Node.js 或 deno 后运行agent-reach install --system；
• 若只有 Node.js 而无 deno，需在 yt-dlp 用户配置中显式加入--js-runtimes node一行（deno 开箱即用，Node.js 需要显式配置）。升级命令为python -m pip install -U "yt-dlp[default]"，yt-dlp 需不低于2025.11.12才支持 JS runtime 配置；
• 从源码可见（youtube.py#L96-L118），当 Groq/OpenAI Whisper key 已配置且 ffmpeg、ffprobe 齐备时，doctor还会提示"可转写音频（groq/openai）"。

字幕失败时的重试链（按序执行，拿到实质内容即停）

关键认知：doctor只确认 yt-dlp 本体与 JS runtime 能执行，不会请求具体视频；因此active_backend: yt-dlp不等于目标视频的字幕已经通过实时验证。这也符合 doctor.py 的职责边界——它只聚合各通道的体检结果，不执行平台命令。

1. 先用上面的yt-dlp --write-sub --write-auto-sub命令。
2. 若出现 bot 校验、字幕响应为空或没有生成字幕文件，且 OpenCLI 已连接：opencli youtube transcript "URL" -f yaml。
3. OpenCLI 若返回Caption URL returned empty response，最多重试 3 次；这是带过期时间的字幕 URL 偶发失效，不能把空响应当成"视频没有字幕"。
4. 仍失败或视频本来就没有字幕：agent-reach transcribe "URL"下载音频转写。

成功标准是实际得到非空字幕/转录内容，不是命令退出码或doctor的版本探测结果。

无字幕兜底：agent-reach transcribe与 Whisper 音频转写

视频没有字幕时的最终兜底方案是下载音频并用 Whisper 转写：

# 视频没有字幕时的兜底：下载音频并用 Whisper 转写（Groq 免费 key 即可） agent-reach transcribe "https://www.youtube.com/watch?v=VIDEO_ID" agent-reach transcribe ./local_audio.mp3 -o /tmp/transcript.txt

输入约束与提供商路由

• agent-reach transcribe只接收公开 http(s) URL 或本地音频文件。用ytsearch5:搜索时，先从 yt-dlp 结果里选出具体视频 URL，再转写；
• 需要先配置 key：agent-reach configure groq-key（隐藏输入；免费，console.groq.com）或agent-reach configure openai-key；
• 默认 auto 模式只使用第一个已配置服务商（优先 Groq，否则 OpenAI），失败即停止，不会把音频自动发给另一家；
• --allow-provider-fallback会显式授权跨服务商降级；同一音频内容可能被 Groq 和 OpenAI 分别处理，并可能产生 OpenAI 费用，只应在确认内容可分享给两家后使用。CLI 层同样校验：--allow-provider-fallback要求--provider auto（见 cli.py#L220-L225）。

底层流水线与安全边界

从 transcribe.py 的实现可以看到完整流水线：

1. URL 安全校验（_assert_safe_public_url）：仅允许公开 http(s)，拒绝 localhost、私网 IP、编码/歧义主机，防 SSRF；
2. 音频下载：yt-dlp -x --audio-format m4a --audio-quality 0 --no-playlist，限制源文件 ≤ 512 MiB；
3. 时长探测：ffprobe读取时长，超过 4 小时（MAX_AUDIO_SECONDS = 24 × 600s）直接拒绝；
4. 压缩：ffmpeg 重编码为单声道 / 16kHz / 32kbps m4a，使多数内容低于 Whisper API 的 25MB 上限；
5. 分片：超过 24MB 时按 10 分钟一段切分（CHUNK_SECONDS = 600），每片 ≤ 24MB，总切片 ≤ 96MiB；
6. 逐片转写：调用提供商端点并拼接结果。Groq 使用whisper-large-v3，OpenAI 使用whisper-1（PROVIDERS定义）。

对应的测试覆盖了端点路由、模型选择、鉴权头与 fallback 行为（见 test_transcribe.py）。

B站 / Bilibili：bili-cli 为主、OpenCLI 补字幕

⚠️不要用 yt-dlp 读 B站：B站风控已全面 412 拦截 yt-dlp（实测最新版、直连/代理/带 Cookie 全部无效）。yt-dlp 只用于 YouTube。这一结论在 Bilibili 通道源码 中有明确记录（live-verified 2026-06）：yt-dlp 已从该通道后端中移除，bili-cli 与 OpenCLI 取而代之。

视频详情/搜索/热门/排行（bili-cli，只读无需登录）

# 视频详情（标题/UP主/时长/播放互动数据/字幕可用性） bili video BVxxx # 搜索视频 bili search "query" --type video -n 5 # 热门视频 / 排行榜 bili hot -n 10 bili rank -n 10 # 下载音频并切分为 ASR-ready WAV（无字幕时配合 agent-reach transcribe 转写） bili audio BVxxx

• 安装：pipx install bilibili-cli（上游 2026-03 起停更但实测健康；只读场景无需登录，bili login扫码可解锁动态/收藏等个人功能）；
• doctor对 bili-cli 的体检逻辑在 bilibili.py#L82-L94：真实执行bili --version探活，区分未装/断链/探测失败，可用时返回"搜索/热门/排行/视频详情/音频，无需登录；字幕需 OpenCLI"。

字幕（OpenCLI，需要桌面 Chrome）

# 字幕逐句带时间轴 opencli bilibili subtitle BVxxx # OpenCLI 也能搜索/读视频元数据（备选） opencli bilibili search "query" -f yaml opencli bilibili video BVxxx -f yaml

OpenCLI 走浏览器会话，能绕过纯命令行工具拿不到的字幕。安装方式：agent-reach install --system --channels opencli（桌面环境专用，服务器环境会被自动跳过，见 cli.py#L326-L342）。OpenCLI 通道的doctor状态为warn（已连接但登录态与实际命令未实时验证），因为 Doctor 不执行平台命令——使用前请先在 Chrome 里完成登录（见 _opencli_site.py）。

零配置兜底：搜索 API 直连

即使 bili-cli 与 OpenCLI 都不可用，B站搜索仍可通过 Web 接口直连：

UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36" curl -s -c /tmp/bili_ck.txt -o /dev/null -A "$UA" "https://www.bilibili.com/" curl -s -b /tmp/bili_ck.txt -A "$UA" -e "https://www.bilibili.com/" \ "https://api.bilibili.com/x/web-interface/search/all/v2?keyword=QUERY&page=1"

此方案需要先访问主页获取 Cookie（-c写入、-b回读），并带 Referer 与浏览器 UA 头。Bilibili 通道的体检实现会直连search/all/v2并检查返回code == 0来判定该兜底是否可用（bilibili.py#L24-L32），可用时后端显示为"B站搜索 API（仅搜索，curl 直连）"。

小宇宙播客 / Xiaoyuzhou Podcast：一键转录单集

转录单集播客（可选 --polish 增强标点）

# 输出 Markdown 文件到 /tmp/。--polish 让 Llama 3.3 70B 给文稿补中文标点+合理分段 ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh --polish "https://www.xiaoyuzhoufm.com/episode/EPISODE_ID"

转写 prompt 已要求 Whisper 输出中文标点；若标点效果仍不理想，可加--polish用 Groq 上免费的 Llama 3.3 70B 补标点+合理分段（9 分钟播客约多 ~7 秒）。每次转写多一轮 LLM 调用，按需使用。

从 transcribe_xiaoyuzhou.sh 的实现看，--polish阶段使用llama-3.3-70b-versatile，提示词严格要求"只补中文标点（，。！？：；）与合理分段，不得修改、删除、增加任何汉字或英文/数字"，输出被截断时还会从中点切半递归重试（最多 3 层）。脚本另有完整的安全护栏：仅接受xiaoyuzhoufm.com及其子域（L47-L66）、音频时长上限 3 小时、Groq API 429 限流自动等待重试、5xx 时提示用agent-reach transcribe兜底。

前置要求

1. ffmpeg:brew install ffmpeg（Linux 可用apt install -y ffmpeg）
2. Groq API Key(免费): https://console.groq.com/keys
3. 配置 Key:agent-reach configure groq-key（隐藏输入）
4. 首次运行:agent-reach install --env=auto --system --channels=xiaoyuzhou（需用户明确授权）

安装逻辑见 cli.py#L914-L962：脚本会写入~/.agent-reach/tools/xiaoyuzhou/transcribe.sh并以 0700 权限保护；Groq key 优先取GROQ_API_KEY环境变量，否则读取~/.agent-reach/config.yaml。

检查状态

agent-reach doctor

doctor汇总所有频道的健康状态（✅ 可用 / [!] 已装但需配置 / [X] 未安装），并给出安全提示。输出 Markdown 文件默认保存到/tmp/。

选择指南

常见问题与注意事项

• doctor不等于功能验证：doctor只做静态/版本级探活（真实执行--version类命令，见 probe.py），不会请求具体视频；每条字幕链路都要以"实际拿到非空内容"为成功标准；
• yt-dlp 的 B站限制：412 风控拦截是实测结论，B站场景请勿再用 yt-dlp，改用 bili-cli / OpenCLI / 搜索 API；
• transcribe 的提供商边界：默认 auto 只用一个提供商；跨服务商降级必须显式--allow-provider-fallback，注意隐私与费用影响；
• 安全设计：转写流水线内置 SSRF 防护（拒绝私网/内网地址）、文件大小与时长上限、分片总量上限；小宇宙脚本限制域名白名单；
• 资源来源：本文所有命令与行为均可对照仓库源码：频道路由见 base.py，YouTube 见 youtube.py，B站见 bilibili.py，转写流水线见 transcribe.py，小宇宙脚本见 transcribe_xiaoyuzhou.sh，CLI 命令定义见 cli.py。

• 人工智能
• AI Agent
• MCP 服务
• AI 技能
• CLI