OmniGet Claude 插件环境初始化完全指南：setup 命令与工具链自举原理-育师

OmniGet Claude 插件环境初始化完全指南：setup 命令与工具链自举原理

【免费下载链接】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

导读

本文围绕 claude-plugin/omniget/commands/setup.md 这一 Claude 命令定义展开，深入剖析 OmniGet 桌面应用配套的 Claude 插件（omniget skill）如何一次性完成运行环境初始化：检测并安装yt-dlp、ffmpeg、omniget-cli等核心工具，探测可用的转写后端，并安全地管理 OpenAI / Gemini API 密钥。读完本文，你将掌握setup.sh全部命令行参数的含义与底层实现、工具查找优先级、本地 Whisper 模型下载机制、API Key 的安全存储模型，以及 Claude 代理与用户终端之间的职责边界。

一、setup.md 在插件中的定位

setup.md是一个 Claude Code 命令（slash command）定义文件。它的 front-matter 声明了命令的元信息：

Front-matter 字段	值	含义
`description`	"Set up the omniget skill: install missing tools for this OS (confirm once) and check API keys"	命令的核心职责：安装缺失工具 + 检查 API Key
`argument-hint`	`[--yes] [--local]`	允许透传给脚本的参数
`allowed-tools`	`["Bash"]`	该命令只允许 Claude 使用 Bash 工具执行

命令的正文定义了三条执行规则：

运行 setup 脚本，并把用户传入的参数原样透传：
```
bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh" $ARGUMENTS
```
阅读输出并如实转述：告诉用户当前已安装了什么、有哪些转写选项可用（字幕始终可用；有模型则可用本地 Whisper；有通过校验的 Key 则可用 Gemini/OpenAI 云端转写）。
边界约束：不允许让用户把 Key 粘贴给 Claude，也绝不允许 Claude 自己执行keys.sh set——因为密钥输入必须在用户自己的终端中完成，绝不能经过对话上下文。

这套约束背后是明确的安全模型：Key 属于用户终端，不属于对话。后续章节将逐一展开其实现。

二、setup.sh：一次确认完成整机自举

scripts/setup.sh 是命令的实际执行者，自述为 "One-step setup for the omniget skill"。它按"检测 OS → 检查工具 → 单次确认 → 安装 → Key 检查"的顺序工作。

2.1 完整参数表

脚本的参数解析位于 setup.sh，除文档提及的--yes/--local外，实际还支持：

参数	效果	源码位置
`--yes`/`-y`	跳过安装确认提示，直接安装	L22
`--local`	额外安装本地 Whisper 引擎（`whisper-cli`）并下载默认模型	L23
`--check-only`	只报告状态并退出，不安装任何东西（对 Claude 安全）	L24
`--no-cli`	跳过`omniget-cli`的下载安装	L25
`--update`	刷新`yt-dlp`与`omniget-cli`；隐含`--yes`	L26
未知参数	打印`setup: unknown flag $arg`并返回退出码 2	L27

值得注意的是--update模式（L42-L62）：它会按检测到的包管理器升级yt-dlp/ffmpeg（brew upgrade、winget upgrade、scoop update、pipx upgrade），随后重新拉取最新版omniget-cli，最后执行keys.sh check汇总状态。当某个站点从"能用"变成"报错"时，setup.sh --update就是首选修复手段——正如 omniget-fetch/SKILL.md 中所说："If a site that used to work now fails for everyone, the fix is usually stale tools"。

2.2 平台与包管理器检测

脚本通过resolve-tools.sh提供的og_os()（基于uname -s判断 Darwin/Linux/MINGW）识别操作系统，然后按平台优先级探测包管理器（L33-L39）：

macOS：brew（Homebrew）
Windows：依次探测winget→scoop→choco
Linux：依次探测apt-get→dnf→pacman→zypper

2.3 按工具分发的安装命令

install_cmd()（setup.sh）是一个"工具 × 包管理器"的配方表，为每个组合输出精确的安装命令。下表是部分核心配方：

工具	平台	安装命令
`yt-dlp`	macOS	`brew install yt-dlp`
`yt-dlp`	Windows (winget)	`winget install --silent --accept-package-agreements --accept-source-agreements yt-dlp.yt-dlp`
`yt-dlp`	Debian/Ubuntu	`sudo apt-get update && sudo apt-get install -y pipx && pipx install yt-dlp`
`yt-dlp`	Fedora	`sudo dnf install -y yt-dlp`
`yt-dlp`	Arch	`sudo pacman -S --noconfirm yt-dlp`
`ffmpeg`	Windows (winget)	`winget install --silent --accept-package-agreements --accept-source-agreements Gyan.FFmpeg`
`ffmpeg`	Debian/Ubuntu	`sudo apt-get update && sudo apt-get install -y ffmpeg`
`whisper-cli`	macOS	`brew install whisper-cpp`

若某个工具在当前 OS 上没有自动安装配方，脚本会生成一条# no-auto-install recipe ...注释行，并在后续执行阶段跳过（L183）。若完全没有检测到包管理器，脚本不会硬装，而是给出平台化建议（L114-L120），例如 macOS 先安装 Homebrew、Windows 先安装 winget 或 scoop。

2.4 安装交互与 sudo 处理

核心交互逻辑在 L199-L212：当存在缺失工具时，除非--yes已生效，否则脚本会在有终端（[ -t 0 ]）时打印Install the N missing tool(s) now? [y/N]等待一次确认——这正是 setup.md 中 "confirm once"（只确认一次）的出处。

run_installs()（L177-L197）还有一处细心处理：如果安装命令包含sudo且当前没有交互终端（典型场景就是 Claude 通过非交互 Bash 调用），脚本不会强行执行，而是打印该命令行让用户自行运行，并置返回码为 1。

三、omniget-cli：原生提取器的自动装配

setup.sh在基础工具就绪后，还会下载 OmniGet 的专用命令行工具omniget-cli。它携带 OmniGet 的原生 Instagram / X / Bilibili / Threads 提取器，对这些站点比裸yt-dlp更可靠（脚本注释 L142-L143 明确说明）。

下载过程（install_omniget_cli()，setup.sh）如下：

根据OS:arch匹配预编译产物三元组（cli_triple()，L131-L139）：
- macOS Apple Silicon →aarch64-apple-darwin（tar.gz）
- macOS Intel →x86_64-apple-darwin（tar.gz）
- Windows x64 →x86_64-pc-windows-msvc（zip）
- Linux x64 →x86_64-unknown-linux-gnu（tar.gz）
- 其他组合返回空，脚本降级为"所有站点都用 yt-dlp"
通过 GitHub API 解析最新 release 的 tag（30 秒超时），拼出资产名omniget-cli-$ver-$triple.$ext并下载。
解压到 skill 缓存目录~/.cache/omniget-skill/bin，macOS 下额外执行xattr -d com.apple.quarantine解除隔离属性。
最后用omniget-cli --version做冒烟验证：运行不干净则回退到 yt-dlp（L173）。

仓库变量OMNIGET_REPO（默认tonhowtf/omniget，L128）可通过环境变量覆盖，用于指定从哪个仓库拉取发布资产。

四、工具查找优先级：OmniGet 自有副本优先

scripts/resolve-tools.sh 定义了所有脚本公用的工具解析逻辑。og_find_tool()（L57-L85）的查找顺序是：

显式覆盖：OMNIGET_TOOL_<NAME>环境变量（如OMNIGET_TOOL_YT_DLP=/path/to/yt-dlp），来源标记为custom；
OmniGet 应用管理目录<data dir>/bin（来源omniget）——如果桌面版 OmniGet 已安装，它自带的yt-dlp/ffmpeg就在这里，无需额外安装（这也是 omniget-fetch/SKILL.md 中"If OmniGet (the desktop app) is installed, yt-dlp and ffmpeg are already managed and nothing needs installing"的实现基础）；
skill 缓存目录~/.cache/omniget-skill/bin（来源skill）；
系统 PATH（来源system）；
对whisper-cli额外兼容 Homebrew 旧配方安装的whisper-cpp。

各平台的应用数据目录（og_data_dir()，L24-L35）与 OmniGet 桌面版的 Rust 路径实现（见src-tauri/omniget-core/src/core/paths.rs）保持一致：macOS 为~/Library/Application Support/wtf.tonho.omniget，Linux 为$XDG_DATA_HOME/.local/share/wtf.tonho.omniget，Windows 为%APPDATA%/wtf.tonho.omniget。

五、转写后端探测：setup 决定了哪些能力可用

setup 的最终效果是让omniget-transcribeskill 拥有可用的转写后端。按照 omniget-transcribe/SKILL.md 的--backend auto阶梯，可用性取决于 setup 阶段装了什么：

优先级	后端	依赖	setup 中的对应动作
1	`captions`	平台自带字幕	无需额外安装，始终可用
2	`local`	`whisper-cli`+ ggml 模型	`setup.sh --local`（安装引擎 + 下载模型）
3	`mlx`	`mlx_whisper`（Apple Silicon）	见`doctor.sh`的补充说明
4	`gemini`	`GEMINI_API_KEY`	`keys.sh set`后经`keys.sh check`验证
5	`openai`	`OPENAI_API_KEY`	同上

5.1 本地 Whisper 模型下载

当--local生效且whisper-cli已就位但无模型时（setup.sh），脚本会询问是否下载默认模型large-v3-turbo-q5_0（547 MB），确认后调用get-model.sh。

scripts/get-model.sh 的实现要点：

模型从 Hugging Face 的ggerganov/whisper.cpp仓库下载，目标目录优先为 OmniGet 的models/whisper目录，否则回退到~/.cache/omniget-skill/models；
下载前先从 HF API 解析该文件在 LFS 中的 SHA-256 期望值，下载完成后用sha256sum（或 macOS 的shasum -a 256）校验，不匹配即删除并报错退出（L33-L41）——确保本地模型文件未被篡改；
模型命名需去掉ggml-前缀与.bin后缀（L11），例如传入large-v3-turbo-q5_0对应文件ggml-large-v3-turbo-q5_0.bin。

而resolve-tools.sh的og_whisper_model()（L93-L115）会按large-v3-turbo（量化优先）→ medium → small → base → tiny的优先级，在 OmniGet 模型目录与 skill 缓存中自动挑选可用模型，并兼容OMNIGET_WHISPER_MODEL显式指定。

六、API Key 管理：keys.sh 的安全模型

setup 流程的最后一步（setup.sh）是执行keys.sh check并打印提示：让用户在自己的终端里运行keys.sh set。

6.1 set：交互式、隐藏输入、chmod 600

scripts/keys.sh 的cmd_set()（L36-L67）设计了三道防线：

强制交互终端：[ ! -t 0 ]时直接拒绝执行并提示用户去自己的终端运行（L37-L41）——这正是 setup.md 规则"never run keys.sh set yourself"的脚本级强制；
隐藏输入：使用read -r -s读取密钥，屏幕不回显；空输入表示保留当前值（支持"已设置则回车跳过"）；
值走 stdin 而非 argv：_upsert_env()（L22-L34）从标准输入读取密钥值写入文件，密钥不会出现在ps输出或 shell history 中。

密钥写入~/.config/ai-keys.env（可用OMNIGET_KEYS_FILE覆盖），文件权限强制为 600，且通过awk按变量名去重替换、保留文件中其他无关行（例如用户已有的REPLICATE_API_KEY、ANTHROPIC_API_KEY）。这一"保留其他行、同名替换、权限 600"的行为被 tests/test_keys.sh 以五组断言覆盖验证，包括：

无关 Key 保持不变（REPLICATE_API_KEY=keep-me与ANTHROPIC_API_KEY=also-keep原样保留）；
同名 Key 是替换而非追加（OPENAI_API_KEY只出现一次且为最新值）；
文件权限严格为 600。

6.2 check：只验证、不泄露

cmd_check()（L81-L117）对已配置的 Key 逐一做真实探测：

OpenAI：向https://api.openai.com/v1/models发送带Authorization: Bearer $KEY的请求，按 HTTP 状态码分类：200 = working，401/403 = BAD KEY，000 = 无网络/超时；
Gemini：向https://generativelanguage.googleapis.com/v1beta/models?key=$KEY探测，200 = working，400/401/403 = BAD KEY，000 = 无网络/超时。

无论何种情况，脚本永远不打印 Key 值本身。报告为 "working" 的 Key 即可在转写时使用--backend openai/--backend gemini；没有任何可用 Key 时，脚本会引导用户使用平台字幕或本地 Whisper，并给出keys.sh set提示。

值得注意的兼容性说明：keys.sh 明确不支持 OpenRouter（L12 注释）——因为 OpenRouter 没有 speech-to-text 端点，无法用于转写。

七、doctor.sh：随时复查的全景诊断

setup 完成之后，任何时刻都可通过 scripts/doctor.sh 复查环境。它报告的项目包括：

引擎工具：omniget-cli、yt-dlp、ffmpeg、ffprobe、whisper-cli、mlx_whisper（每个均标注 status 与来源路径）；
whisper-model：是否已存在可用模型；
密钥：GEMINI_API_KEY/OPENAI_API_KEY是否已设置；
omniget-app：桌面版是否安装（检查应用数据目录是否存在）；
output-dir：默认输出目录（$HOME/Downloads/omniget，可用OMNIGET_DIR覆盖）。

doctor.sh --json输出机器可读的 JSON 摘要；--check-keys追加执行keys.sh check。同时它会按平台打印补齐缺口的建议命令（macOS 的brew install whisper-cpp、Linux 的sudo apt install ffmpeg && pip install -U yt-dlp、Windows 的winget install yt-dlp.yt-dlp Gyan.FFmpeg等），但是否执行完全由用户决定——这是 omniget-fetch/SKILL.md 中"Never run an install command without the user's explicit yes"规则的延续。

八、典型使用流程与边界约定

综合 setup.md 与 skill 定义，一套标准的初始化对话大致如下：

全新机器：用户执行setup.sh→ 脚本检测到缺yt-dlp/ffmpeg→ 一次确认后按平台包管理器安装 → 下载omniget-cli→ 报告状态并提示keys.sh set。
需要离线/私密转写：用户执行setup.sh --local→ 额外安装whisper-cli并下载large-v3-turbo-q5_0模型（547 MB，带 SHA-256 校验）→ 之后transcribe.sh的--backend auto会自动优先走本地。
需要云端高精度转写：用户在自己的终端运行keys.sh set输入 OpenAI / Gemini Key → 回到对话用doctor.sh --check-keys或keys.sh check确认状态为 working → 即可使用--backend openai --model gpt-4o-transcribe等高精度配置。
站点突然失效：执行setup.sh --update刷新yt-dlp与omniget-cli。

三条不可逾越的边界（既是 setup.md 的规则，也在脚本与 skill 中反复强化）：

安装命令必须获得用户明确同意：setup.sh只在单次确认后自动安装，其他场景一律打印命令让用户决定；
API Key 永不经过 Claude 对话：keys.sh set强制要求交互终端，Key 只存在于用户终端的~/.config/ai-keys.env（chmod 600）；
Cookie 与密钥永不打印、复制或提交：相关值均通过 stdin 或文件传递，脚本只输出状态不输出内容。

九、小结

setup.md虽只是一个短小的命令定义，但其背后是一个设计严谨的"工具链自举"体系：setup.sh完成跨平台（macOS / Windows / Linux × 7 种包管理器）的依赖安装与omniget-cli装配，resolve-tools.sh定义了"自定义覆盖 → OmniGet 托管副本 → skill 缓存 → 系统 PATH"的解析优先级，get-model.sh以 SHA-256 校验保障本地模型完整性，keys.sh以"交互终端 + 隐藏输入 + 600 权限"守住密钥安全底线，doctor.sh则提供了随时可用的全景诊断入口。理解这套流程，你就能在任意新环境下一次完成 OmniGet 插件的全部初始化，并清楚知道哪些转写能力可用、为什么可用、以及如何在不泄露密钥的前提下补齐缺口。