OmniGet Claude Code 插件媒体下载全解析：fetch 命令、底层脚本与故障排查实战-平芜编程栈

OmniGet Claude Code 插件媒体下载全解析：fetch 命令、底层脚本与故障排查实战

【免费下载链接】omnigetDownload Udemy and Hotmart courses, YouTube videos, music and books — 1,800+ sites, no terminal. Free open-source desktop app for Windows, macOS and Linux, with a built-in course player, PDF/EPUB reader and music library. Powered by yt-dlp. Your files stay on your computer.项目地址: https://gitcode.com/GitHub_Trending/om/omniget

本文围绕 OmniGet 仓库中 Claude Code 插件的fetch命令（claude-plugin/omniget/commands/fetch.md）展开，深入讲解其背后的fetch.sh下载脚本、工具解析机制、Cookie 自动重试与错误分类逻辑。读完本文，你将掌握如何在 Claude Code 会话中一键下载 URL 指向的媒体、理解底层 yt-dlp / omniget-cli 调用链、学会用 setup 与 doctor 解决工具缺失和下载失败问题，并能通过测试用例验证整个流程的可靠性。

一、fetch 命令是什么：Claude Code 里的媒体下载入口

在 OmniGet 的 Claude Code 插件中，fetch是一个面向 Agent 的命令定义文件。它本身只有十几行，却是整个媒体下载链路的总入口：当用户在对话中粘贴一个视频、音频或社交平台链接并表达"下载"意图时，Claude（Agent）会依据该命令执行真正的下载脚本。

命令文件的开头 Frontmatter 定义了三项关键元数据：

description: Download the media at a URL with OmniGet's tooling (yt-dlp, ffmpeg, omniget-cli) argument-hint: <url> [--audio] [--quality N] [--out DIR] allowed-tools: ["Bash", "Read"]

description：向 Agent 描述该命令的能力边界——使用 yt-dlp、ffmpeg、omniget-cli 组成的工具链下载媒体；
argument-hint：声明参数形态，即<url> [--audio] [--quality N] [--out DIR]，这正是底层脚本的参数契约；
allowed-tools：限定 Agent 执行本命令时只能使用 Bash（运行脚本）和 Read（读取文件）两类工具，避免权限越界。

命令正文给出了唯一的执行动作：

bash "${CLAUDE_PLUGIN_ROOT}/scripts/fetch.sh" $ARGUMENTS

执行成功后，Agent 需要用一两句话向用户汇报保存的文件路径、大小和时长（而非粘贴 JSON）；若失败，则先运行doctor.sh诊断，再依据omniget-fetchskill 中的错误表格处理，且在安装任何东西前必须先征得用户同意。

二、fetch.sh 源码拆解：一次下载的完整生命周期

命令真正调用的核心是 claude-plugin/omniget/scripts/fetch.sh。它只打印一行 JSON（{file,title,duration,size,platform,engine,id}），进度信息走 stderr，保证输出可被 Agent 程序化解析。

2.1 参数解析

脚本用while循环手工解析参数，支持三个可选开关：

参数	含义	底层行为
`--audio`	仅保留音频轨道	追加`-x --audio-format m4a`，输出`.m4a`
`--quality N`	限制视频高度（如 720）	追加`-f "bv*[height<=N]+ba/b[height<=N]/b"`
`--out DIR`	指定输出目录	未指定时用`og_output_dir()`得到默认目录

未传 URL 或传了未知 flag 时，脚本输出 usage 并以退出码 2 结束：

[ -n "$url" ] || { echo "usage: fetch.sh <url> [--audio] [--quality N] [--out DIR]" >&2; exit 2; }

2.2 双引擎策略：omniget-cli 优先，yt-dlp 兜底

fetch.sh最核心的设计是引擎选择：对部分平台优先使用 OmniGet 自带的原生提取器omniget-cli，其余平台回退到通用 yt-dlp。

if og_prefers_cli "$url" && cli="$(og_tool_path omniget-cli)"; then info="$("$cli" --json info "$url")" args=(--json download "$url" -o "$out") $audio && args+=(--audio-only) [ -n "$quality" ] && args+=(-q "$quality") ... fi

og_prefers_cli在 resolve-tools.sh 中实现，命中的主机包括：instagram.com、threads.net、threads.com、twitter.com、x.com、bilibili.com、b23.tv。这些站点对登录态与反爬更敏感，OmniGet 的原生提取器（位于 src-tauri/omniget-cli/src/commands/download.rs）比裸 yt-dlp 更可靠，还能复用桌面应用里已配置的 Cookie 账号。

yt-dlp 分支的参数构造同样值得注意：

args=(--no-warnings --no-playlist --no-simulate --quiet --print "%(id)s ||| %(extractor_key)s ||| %(duration)s ||| %(title)s" --print "after_move:filepath" -o "$out/%(title).120B [%(id)s].%(ext)s") [ -n "$ffmpeg_dir" ] && args+=(--ffmpeg-location "$ffmpeg_dir")

--no-playlist：URL 是列表时只取单条媒体，避免意外批量下载；
两条--print：第一行输出元数据（ID、提取器名、时长、标题），第二行在下载完成后输出实际文件路径——脚本随后用head -n 1/tail -n 1分别取回两者；
-o模板将标题截断到 120 字符并附加视频 ID，保证文件名的可读性与唯一性；
--ffmpeg-location：若找到 ffmpeg，则显式指定其目录，供 yt-dlp 做音视频合并。

格式选择遵循三段式：--audio用bestaudio/best；指定质量用bv*[height<=N]+ba/b[height<=N]/b（视频按高度筛选，音频兜底）；默认用bv*+ba/b取最佳视频+最佳音频，均以 mp4 合并输出。

2.3 输出与结果校验

yt-dlp 分支最后用og_json工具（resolve-tools.sh 中的 Python 辅助函数）拼装结果 JSON：size:n=表示数值字段，空值自动省略；duration为"NA"时置空。脚本还会校验文件真实存在：[ -f "$path" ] || { echo "download finished but file not found" ... }，防止"下载成功但文件丢失"的静默失败。

三、工具查找与运行环境：resolve-tools.sh 的解析顺序

fetch.sh 的所有底层能力都来自被 source 的 resolve-tools.sh。它的核心函数og_find_tool遵循与桌面应用find_tool_with_source一致的三级查找顺序：

显式覆盖：环境变量OMNIGET_TOOL_<NAME>（如OMNIGET_TOOL_YT_DLP）指定的路径，来源标记为custom；
OmniGet 托管目录：<data dir>/bin下的自管二进制，来源为omniget。数据目录按 OS 自动探测——macOS 为~/Library/Application Support/wtf.tonho.omniget，Linux 为${XDG_DATA_HOME:-~/.local/share}/wtf.tonho.omniget，Windows 为${APPDATA}/wtf.tonho.omniget；
skill 缓存与系统 PATH：先查~/.cache/omniget-skill/bin，最后command -v落到系统 PATH，来源为system。

这套顺序意味着：只要桌面端 OmniGet 安装过，脚本就能直接复用其管理的 yt-dlp/ffmpeg，无需额外安装——这与插件 README 的说明一致（claude-plugin/omniget/README.md）。

其他关键辅助函数：

og_output_dir：输出目录，默认~/Downloads/omniget，可用环境变量OMNIGET_DIR覆盖；
og_cookie_file：在 OmniGet 的 cookies 目录下按域名找最新的 cookies.txt，供 yt-dlp 的--cookies使用；
og_url_host：剥离 URL 协议、路径与www./m.前缀得到裸主机名，且将x.com归一化为twitter.com以匹配 Cookie 目录；
og_arch：归一化 CPU 架构（aarch64/x86_64），与发布产物的 target triple 对齐。

四、登录墙与限流的自动应对：Cookie 一键重试机制

这是 fetch 链路中最具实战价值的机制，实现在og_run_ytdlp中。流程如下：

先用og_cookie_args检测当前域名是否有可用 Cookie（OmniGet 账号 Cookie 或OMNIGET_COOKIES_FROM_BROWSER指定的浏览器来源）；
携带 Cookie 执行 yt-dlp，成功则直接返回；
失败时，若首次尝试未使用任何 Cookie且错误属于"登录墙/限流"类别，则自动探测已登录浏览器（og_detect_browser按 Chrome → Brave → Edge → Firefox → Safari 的顺序探测），追加--cookies-from-browser <browser>重试一次；
重试仍失败则视为硬限流，停止并返回错误。

值得注意的两点边界：macOS 首次读取浏览器 Cookie 可能弹出一次性 Keychain 授权提示；多浏览器配置文件场景下可用OMNIGET_COOKIES_FROM_BROWSER=chrome:"Profile 3"固定指定配置。

这套逻辑不是纸面设计——仓库提供了专门的离线测试 claude-plugin/omniget/tests/test_retry.sh，用 stub yt-dlp 验证三条断言：

cookie 解锁成功：stub 在收到--cookies-from-browser后成功输出 → 期望退出码 0、返回 stdout、打印重试提示；
硬失败不无限重试：stub 始终失败 → 期望退出码 1、stderr 被捕获到错误文件；
DRM 错误不触发重试：stub 报SAMPLE-AES (FairPlay DRM)→ 期望绝不出现retrying with提示。

这意味着"登录墙自动重试"是经过测试保障的确定性行为，而非脚本里的侥幸逻辑。

五、失败处理：错误分类表与 doctor 诊断

fetch 命令规定：脚本失败后先跑 doctor，再按omniget-fetchskill 的错误表格处置。该表格（见 skills/omniget-fetch/SKILL.md）与og_explain_error的匹配模式一一对应，把原始 stderr 映射为可行动建议：

stderr 症状	含义	处置动作
`yt-dlp not found`	无下载引擎	展示 doctor 的安装命令，征求同意后再装
`Sign in to confirm`、`login required`、`Private video`、HTTP 401/403	平台要求登录会话	使用 OmniGet 站点 Cookie，或设`OMNIGET_COOKIES_FROM_BROWSER=chrome`后重试
HTTP 429、`rate-limit`	请求过频	等待 30 秒重试一次，仍失败则停止并告知用户
`empty media response`、HTTP 400（Instagram/X）	限流或登录门禁	等几分钟重试；若是私有内容则提供 Cookie。`omniget-cli`处理这些站点优于裸 yt-dlp
`DRM`、`SAMPLE-AES`、`Widevine`	受 DRM 保护	停止；OmniGet 不绕过 DRM
`Unsupported URL`	无可用提取器	说明情况，若有直链可建议用户提供
`Requested format is not available`	画质上限过严	去掉`--quality`重试

脚本失败时还会输出一行-> hint的明文提示，归类限流/登录/DRM 三类根因。若某站点之前正常、现在全员失败，通常是工具过期：执行setup.sh --update刷新即可。

og_explain_error的实现（resolve-tools.sh 中）把上述症状串进 case 匹配，例如命中HTTP 429或rate-limit就返回"平台正在限流…等待几分钟重试；若为私有内容请登录（见 Cookie 说明）"。og_should_retry_with_cookies则复用同一分类逻辑，只对限流与登录两类错误放行 Cookie 重试。

六、从零到可用的环境准备：setup.sh 与 doctor.sh

6.1 一键安装 setup.sh

首次运行或缺工具时，命令文件要求用setup.sh一步补齐，而非向用户抛裸安装命令（claude-plugin/omniget/scripts/setup.sh）：

bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"

脚本自动检测 OS 与包管理器（mac 用 brew，Windows 用 winget/scoop/choco，Linux 用 apt/dnf/pacman/zypper），列出缺失项并在单次确认后安装 yt-dlp、ffmpeg；同时会下载当前 OS/arch 对应的预编译omniget-cli（从 GitHub Releases 按 triple 匹配，如x86_64-unknown-linux-gnu），为 Instagram/X/Bilibili/Threads 提供原生提取器。主要开关：

开关	作用
`--yes`/`-y`	跳过确认提示
`--local`	额外安装本地 Whisper 引擎与默认模型
`--no-cli`	跳过 omniget-cli 安装
`--check-only`	只报告状态、不安装（对 Agent 安全）
`--update`	刷新 yt-dlp/ffmpeg 并重装 omniget-cli

若桌面端 OmniGet 已安装，yt-dlp 与 ffmpeg 已由其托管，setup 会发现它们而无需任何安装动作。

6.2 诊断工具 doctor.sh

doctor（claude-plugin/omniget/scripts/doctor.sh）以表格形式汇报每个工具的状态与来源：omniget-cli、yt-dlp、ffmpeg、ffprobe、whisper-cli、mlx_whisper的存在性，Whisper 模型是否就位，GEMINI_API_KEY/OPENAI_API_KEY是否配置，以及omniget-app是否安装。--check-keys追加密钥检查，--json输出机器可读结果。缺什么就打印对应的安装命令（brew/winget/apt 等），是否执行完全由用户决定。

七、完整工作流与实用要点

综合 fetch 命令、skill 与脚本，一次典型下载的完整链路为：

用户粘贴 URL 并表达下载意图 →omniget-fetchskill 触发，Agent 执行fetch.sh "<url>" [--audio] [--quality N] [--out DIR]；
resolve-tools.sh解析出引擎：Instagram/X/Bilibili/Threads 走omniget-cli，其余走 yt-dlp + ffmpeg；
下载遇登录墙/限流时自动用浏览器 Cookie 重试一次；
成功则输出单行 JSON，Agent 用一两句话汇报文件路径、大小、时长；失败则先doctor.sh --check-keys，再按错误表格处置，任何安装操作前必须征得用户同意。

环境变量速查（均可在运行前设置以调整行为）：

变量	含义
`OMNIGET_DIR`	输出目录（默认`~/Downloads/omniget`）
`OMNIGET_DATA_DIR`	OmniGet 应用数据目录（按 OS 自动探测）
`OMNIGET_TOOL_YT_DLP`/`OMNIGET_TOOL_FFMPEG`	显式指定二进制路径
`OMNIGET_COOKIES_FROM_BROWSER`	`chrome`/`firefox`/`safari`/`edge`，用于登录态媒体；可带 profile 如`chrome:"Profile 3"`
`OMNIGET_KEYS_FILE`	替换默认的`~/.config/ai-keys.env`密钥文件

边界与原则：只下载用户明确索取的媒体；裸 URL 加提问属于转写请求而非下载请求（应走omniget-transcribeskill）；绝不绕过 DRM 与付费墙，只使用用户已有的会话（OmniGet Cookie 账号或浏览器 Cookie）；Cookie 文件与 API 密钥永不打印、复制或提交。对播客、演讲等只听不看的场景，优先--audio以减小体积并加快下载。

这套设计把"下载媒体"这件看似简单的操作做成了可诊断、可重试、可测试的工程化流程：Agent 无需手写 yt-dlp 命令，只需调用稳定的脚本契约，而脚本复用桌面端已有的全部工具资产——这正是 OmniGet "文件留在你的电脑上"理念在 AI 编程助手场景下的自然延伸。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考