gog YouTube 实战指南在终端中用 gog 完成 YouTube 数据查询、订阅与播放列表管理【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli本文基于 gog 项目中面向 Agent 的gog-youtube技能.agents/skills/gog-youtube/SKILL.md及其配套官方文档docs/youtube.md系统讲解如何用 gog 在终端中操作 YouTube包括 API Key 与账户 OAuth 两种访问模式、七大子命令的完整用法、--parts字段选择、LL收藏夹读取、订阅与播放列表的增删改以及面向自动化与安全的关键参数--dry-run、--force、--readonly、--no-input。阅读本文后你将能够独立完成从认证配置、公共数据查询到个人数据写入的完整 YouTube 自动化流程并能结合源码理解其底层实现原理。技能定位与前置要求gog-youtube是 gog 面向 Agent也面向脚本与人工使用的 YouTube 操作技能核心定位一句话概括通过 gog CLI 安全地执行 YouTube 数据读取与受限写入。技能本身的规格很简洁真正的完整用法沉淀在官方文档 docs/youtube.md 与生成的命令参考中。在深入 YouTube 命令之前必须先掌握 gog 的公共约定包括共享认证auth规则账户选择、OAuth 刷新、keyring 解锁等详见 .agents/skills/gog/SKILL.md共享输出output规则--json、--plainTSV、--select/--fields、--wrap-untrusted等跨命令统一行为共享安全safety规则--readonly、--dry-run、--no-input、--enable-commands/--disable-commands命令守卫共享实时写入live-write规则任何写操作前确认账户、对象与具体变更。命令实现的入口在 cmd/gog/ 与 internal/cmd/其中 YouTube 相关源码集中在 internal/cmd/youtube.go、internal/cmd/youtube_services.go 和 internal/googleapi/youtube.go。安全启动Safe Start技能推荐在动手前先执行三条探路命令确认认证状态、Schema 契约与命令帮助避免凭记忆猜语法gog auth list --check --json --no-input gog schema youtube --json gog --readonly --account userexample.com youtube --help配套的核心安全原则来自 .agents/skills/gog-youtube/SKILL.md显式选择账户所有需要身份的操作都用--account指定账户避免默认账户误用Agent 可解析输出读取 Google 内容时使用--json --wrap-untrusted将外部文本字段包裹成不可信内容标记防止内容注入污染解析逻辑任务不允许变更时使用--readonly运行时拦截一切变更 API 请求自动化必须--no-input任何需要交互的提示如 keyring 密码都会以失败收场而不是挂起等待写入前先--dry-run支持的命令会在不创建 API 服务、不发网络请求的情况下打印预期动作删除/不可逆操作需确认执行前必须核对账户、对象与变更内容。命令总览gog youtube别名gog yt下辖 7 个子命令定义见 internal/cmd/youtube.go命令用途访问模式activities列出频道活动上传、订阅、点赞等事件流API Key 或账户 OAuthchannels按 ID 或认证用户列出频道API Key 或账户 OAuthcomments列出视频或频道的评论线程comment threadsAPI Key 或账户 OAuthforce-sslplaylists管理播放列表创建、增删视频、删除播放列表写操作需账户 OAuthforce-sslsearch搜索视频、频道或播放列表API Keysubscriptions管理频道订阅写操作需账户 OAuthforce-sslvideos按 ID、热门榜单或我的评分列出视频API Key 或账户 OAuth统一用法gog youtube command --help # 查看子命令旗标 gog schema youtube command --json # 获取机器可读的命令契约 gog youtube command ... # 实际执行完整旗标可查看生成的命令参考docs/commands/gog-youtube.md 及其子命令文档如 gog-youtube-subscriptions.md、gog-youtube-playlists.md。技能明确提醒不要猜测命令语法一律先查--help或schema。两种访问模式API Key 与账户 OAuthgog 的 YouTube 支持根据数据性质自动选择客户端见 internal/cmd/youtube_services.go公共数据API Key对于频道、视频、活动、播放列表、评论、搜索等公共数据启用 YouTube Data API v3 并存一个 API Keygog config set youtube_api_key YOUR_API_KEY gog yt videos list --chart mostPopular --region US --max 5配置项名称为youtube_api_key定义见 internal/config/keys.go同时支持环境变量GOG_YOUTUBE_API_KEY。从源码看API Key 缺失时 getYouTubeAPIKey 会直接报错并提示set config youtube_api_key KEY or GOG_YOUTUBE_API_KEY。配置写入与 dry-run 预览会自动对 API Key 打码同时保留原始存储值。公共读取的自动降级逻辑当命令没有指定--account、GOG_ACCOUNT环境变量或--access-token时getYouTubeReadService 走 API Key 通道一旦检测到账户选择器youtubeAccountSelectorPresent则自动改用账户 OAuth。这意味着同样的videos list --id命令加不加--account会走完全不同的认证路径。私有数据与写入账户 OAuth账户读取使用默认的youtube.readonlyscope该 scope 常量定义见 internal/googleauth/service.gogog auth add yougmail.com --services youtube gog yt activities list --mine --account yougmail.com订阅与播放列表等写操作以及评论读取需要额外的youtube.force-sslscope必须在认证时显式申请gog auth add yougmail.com --services youtube \ --extra-scopes https://www.googleapis.com/auth/youtube.force-ssl \ --force-consentscope 划分在源码中有明确注释internal/googleapi/youtube.goGoogle 要求commentThreads.list必须用youtube.force-sslyoutube.readonly不够而youtube.force-ssl覆盖订阅、播放列表、评论操作通用账户客户端仍被限制在youtube.readonly。对应地internal/cmd/youtube.go 定义了youtubeForceSSLOAuthScope常量写命令统一走getYouTubeWriteServiceForAccount。注意账户必须已经拥有 YouTube 频道。若 API 返回youtubeSignupRequired需要先在 youtube.com 初始化频道后重试。读取播放列表与收藏视频列出播放列表按频道 ID 或按认证用户自己的频道列出gog yt playlists list --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw gog yt playlists list --mine --account yougmail.com列出播放列表内的视频playlists items list读取单个播放列表中的视频。公共播放列表可用 API Key私有播放列表和特殊的LL已收藏/liked videos播放列表必须用账户 OAuth。--all自动翻页遍历大播放列表gog yt playlists items list --playlist-id PLAYLIST_ID --all gog yt playlists items list --playlist-id LL --account yougmail.com --all从源码看internal/cmd/youtube.go当--playlist-id为LL时会强制走账户认证并在 JSON 模式下返回items与nextPageToken表格模式下提示使用--all/--all-pages翻页。直接读取评分喜欢/不喜欢视频videos list --my-rating是每用户读取永远走账户 OAuthgog yt videos list --my-rating like --account yougmail.com --max 50 gog yt videos list --my-rating dislike --account yougmail.com --json这两种读取只用默认youtube.readonlyscope不需要额外 scope源码在 internal/cmd/youtube.go 中明确注释myRating读取必须 OAuth 而非 API Key。选择视频字段--parts的规则videos list保持紧凑的历史默认值snippet、contentDetails、statistics默认列表定义见 internal/cmd/youtube.go。需要全字段时用--parts all或传精确的逗号分隔列表gog yt videos list --id VIDEO_ID --parts all --json gog yt videos list --id YOUR_VIDEO_ID --parts snippet,fileDetails --account yougmail.com --json关键规则源码resolveParts实现见 internal/cmd/youtube.goall展开为对任意视频可读的全部 part但排除仅属主可读的fileDetails、processingDetails、suggestions排除列表见youtubeVideoAllNonOwnerParts常量internal/cmd/youtube.go显式列表原样透传认证属主可以查询自己上传视频的这些私有 part--parts all不能与其他 part 名混用否则报 usage 错误。搜索 YouTubesearch list支持按视频、频道、播放列表三种资源类型搜索按相关性/日期/评分/标题/视频数/观看数排序gog yt search list golang tutorial --type video --max 10 gog yt search list open source --type channel,playlist --order viewCount --max 20 --json参数细节定义见 internal/cmd/youtube.go旗标说明默认值--type资源类型逗号分隔video、channel、playlistvideo--order排序relevance、date、rating、title、videoCount、viewCountrelevance--channel-id限制结果来自特定频道空--max最大结果数1–5025源码在 API 返回后还会按--type再次过滤filterYouTubeSearchItemsByTypeinternal/cmd/youtube.go保证返回项与请求类型一致。搜索公共内容走 API Key 通道。管理订阅订阅是每用户数据列表和增删都要求账户 OAuth。列出订阅单页或全量翻页gog yt subscriptions list --max 50 --account yougmail.com gog yt subscriptions list --all --account yougmail.com --json按频道 ID 订阅gog yt subscriptions subscribe \ --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw \ --account yougmail.com退订支持两种定位方式直接用subscriptions list返回的订阅 ID或用频道 IDgog 会先做订阅查找再删除gog yt subscriptions unsubscribe --id SUBSCRIPTION_ID \ --account yougmail.com --force gog yt subscriptions unsubscribe --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw \ --account yougmail.com --force从源码看internal/cmd/youtube.go--channel-id路径会先调用Subscriptions.List(Mine(true)).ForChannelId(channelID)查找订阅 ID找不到时报not subscribed to channel ...找到后才进入删除确认流程。管理播放列表新建播放列表默认私有仅在明确需要更广可见性时才用--privacy unlisted或--privacy public枚举public,unlisted,private默认private见 internal/cmd/youtube.gogog yt playlists create --title Research \ --description Videos to review \ --account yougmail.com --json gog yt playlists add --playlist-id PLAYLIST_ID --video-id VIDEO_ID \ --position 0 --account yougmail.com--position是 0 起始的位置不设置时默认追加到末尾源码默认值-1表示追加internal/cmd/youtube.go设置后通过ForceSendFields强制发送Position字段。移除播放列表项有两种方式直接用已知的 playlist item ID或提供播放列表 ID 视频 ID 让 gog 先查找再删除gog yt playlists remove --item-id PLAYLIST_ITEM_ID \ --account yougmail.com --force gog yt playlists remove --playlist-id PLAYLIST_ID --video-id VIDEO_ID \ --account yougmail.com --force删除整个播放列表gog yt playlists delete PLAYLIST_ID --account yougmail.com --force从源码看remove --playlist-id/--video-id会先以PlaylistIdVideoId查询MaxResults(1)找不到时报video ... not found in playlist ...--item-id与--video-id互斥internal/cmd/youtube.go。评论读取comments list按视频或频道列出顶层评论线程--video-id与--channel-id二选一gog yt comments list --video-id VIDEO_ID --max 20 gog yt comments list --channel-id UC_x5XG1OV2P6uZZ5FSM9Ttw --json注意评论线程读取在账户模式下需要youtube.force-ssl见上文 scope 说明使用 API Key 时则无此限制。自动化与安全dry-run、确认与错误处理所有写操作支持--dry-run订阅与播放列表的每个变更命令都支持--dry-run且 dry-run不会创建 API 服务、不发起任何网络请求只是打印预期动作并以成功退出gog yt playlists add --playlist-id PLAYLIST_ID --video-id VIDEO_ID \ --account yougmail.com --dry-run --json破坏性操作的确认机制退订、移除播放列表项、删除播放列表在执行前都会提示确认。仅在核对目标后使用--force在刻意自动化的场景下可组合--no-input --force--no-input让未确认的自动化快速失败而不是挂起。源码中的统一入口为dryRunAndConfirmDestructive见 internal/cmd/youtube.go 等调用点。统一的上限校验所有 YouTube 列表类命令的--max都被validateYouTubeMax限制在1–50之间internal/cmd/youtube.go超界直接报 usage 错误。scope 不足时的友好提示当写操作或评论读取因insufficientPermissions/insufficient authentication scopes/ACCESS_TOKEN_SCOPE_INSUFFICIENT失败时wrapYouTubeForceSSLError 会把原始错误包装成可直接执行的重新认证命令youtube mutations require OAuth scope https://www.googleapis.com/auth/youtube.force-ssl; re-authenticate with: gog auth add account --services youtube \ --extra-scopes https://www.googleapis.com/auth/youtube.force-ssl --force-consent这个细节让 Agent 在遇到 scope 问题时不至于误判为配置错误直接按提示重认证即可。输出约定--json结构化 JSON 到 stdout列表类输出包含items与nextPageToken--plain稳定 TSV 输出如idTABchannel_idTABtitleTABsubscribed_at便于脚本解析人工进度、提示、警告统一走 stderrstdout 只承载数据参见共享 SKILL 的约定.agents/skills/gog/SKILL.md。源码级实现小结把官方文档与源码对应起来gog 的 YouTube 支持可以概括为几个清晰的分层命令层internal/cmd/youtube.go声明 7 个子命令的结构体、旗标定义、参数校验与输出格式化约 1100 行服务选择层internal/cmd/youtube_services.go根据--account/GOG_ACCOUNT/--access-token是否存在在 API Key 服务、账户只读服务、账户写服务、评论服务之间路由Google API 适配层internal/googleapi/youtube.goNewYouTubeWithAPIKey使用option.WithAPIKey构建公共数据客户端NewYouTubeForAccount走youtube.readonly账户 OAuthNewYouTubeCommentsForAccount与NewYouTubeWriteForAccount强制youtube.force-ssl认证 scope 配置internal/googleauth/service.goyoutube.readonly作为账户默认 scope 注册配置项internal/config/keys.goyoutube_api_key存储 API Key同时支持GOG_YOUTUBE_API_KEY环境变量。配套测试覆盖了 scope 选择与错误包装逻辑例如 internal/googleapi/youtube_test.go 校验只读 scope 与 force-ssl scope 的常量internal/cmd/youtube_mutations_test.go 校验 force-ssl 错误提示文案是理解实现行为的可靠参考。推荐阅读官方完整指南docs/youtube.md命令参考docs/commands/gog-youtube.md 与 docs/commands/README.md共享安全与认证约定.agents/skills/gog/SKILL.md、docs/safety-profiles.md更多技能规格docs/agent-skills.md【免费下载链接】gogcliGoogle Workspace in your terminal.项目地址: https://gitcode.com/GitHub_Trending/gogcl/gogcli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考