> ⚠️ 本内容仅供一般信息参考，不构成法律、财务、税务、投资或医疗建议。
> 涉及合同签署、报税、投资、诊疗等专业决策时，请务必咨询持证专业人士，并由使用者自行承担决策后果。
<!-- professional-disclaimer-injected -->

> 本内容由 AI 生成，仅供学习参考
<!-- ai-generated-notice -->

SKILL.md — yt-videos-list

一、能力边界（一页纸速查卡）

输入要求：
- 单个频道标识（字符串），或包含多个频道标识的文本文件（每行一个）
- 可选参数：--format（输出格式，默认 csv）、--max-items（单频道最大采集数，默认不限制）、--output-dir（输出目录，默认当前目录）

输出产物：
- 一个清单文件（格式由 --format 指定），文件名格式为 {channel_handle}_videos_{YYYYMMDD}.{ext}
- 一个同名的 .meta.json 元数据文件，记录采集时间、采集源、频道名称、视频总数等上下文信息

二、触发方式与场景映射

不触发的情况：
- 用户说"下载这个视频" → 不响应，提示本工具只做清单不做下载
- 用户说"监控这个频道" → 不响应，提示本工具为一次性采集，不做持续监控

三、标准执行流程

前置条件（必须全部满足）

1. 网络可正常访问 YouTube（用户侧自行保证网络环境合规）
2. 已确认目标频道存在且为公开频道
3. 输入内容为以下三种格式之一：
   - 频道 URL：https://www.youtube.com/@handle 或 https://www.youtube.com/channel/UCxxxx
   - 频道 ID：UCxxxx...（以 UC 开头的 24 位字符串）
   - 频道句柄：@handle

执行步骤

Step 1 — 输入解析与校验

1. 接收用户输入的频道标识。
2. 使用正则表达式识别输入类型：
   - ^https://www\.youtube\.com/@([\w.-]+)$ → 句柄类型
   - ^https://www\.youtube\.com/channel/(UC[\w-]{22})$ → 频道 ID 类型
   - ^UC[\w-]{22}$ → 裸频道 ID
   - ^@[\w.-]+$ → 裸句柄
3. 若无法匹配任何模式，返回错误码 E1001（见错误码表）。

Step 2 — 试运行（单样本验证）

1. 取输入频道标识，执行一次最小化采集（仅获取前 5 个视频）。
2. 核对输出字段是否完整：video_id、title、published_at、duration_seconds、view_count、description_snippet、thumbnail_url。
3. 若字段缺失或格式异常，返回错误码 E2001。
4. 将试运行结果展示给用户确认，等待确认后进入批量阶段。

Step 3 — 批量执行

1. 使用 YouTube Data API v3 的 playlistItems.list 接口，通过频道的 uploads 播放列表（playlist ID 格式为 UU + 频道 ID 去掉前两位）逐页拉取全部视频。
2. 分页参数：maxResults=50，使用 pageToken 翻页，直至 nextPageToken 为空。
3. 对每个视频 ID 调用 videos.list 接口获取详情（时长、观看次数、描述）。
4. 若单频道视频数超过 500，每 100 条写入一次临时文件，防止内存溢出。
5. 采集完成后，将全部数据写入最终输出文件。

Step 4 — 校验与交付

1. 随机抽取输出文件中 5% 的条目（至少 3 条，至多 20 条），与源数据核对标题、视频 ID、发布时间。
2. 核对总数：输出文件行数（不含表头）应等于元数据文件中的 total_count。
3. 校验通过后，输出文件路径和摘要信息给用户。

输出规范

CSV 格式（默认）：

video_id,title,published_at,duration_seconds,view_count,description_snippet,thumbnail_url
abc123,示例视频标题,2024-01-15T08:30:00Z,245,12345,这是描述的前100个字符...,https://i.ytimg.com/vi/abc123/hqdefault.jpg

JSON 格式：

{
  "channel": {
    "id": "UCxxxx",
    "handle": "@example",
    "name": "示例频道"
  },
  "generated_at": "2026-08-19T10:00:00Z",
  "total_count": 123,
  "videos": [
    {
      "video_id": "abc123",
      "title": "示例视频标题",
      "published_at": "2024-01-15T08:30:00Z",
      "duration_seconds": 245,
      "view_count": 12345,
      "description_snippet": "这是描述的前100个字符...",
      "thumbnail_url": "https://i.ytimg.com/vi/abc123/hqdefault.jpg"
    }
  ]
}

Markdown 格式：

# 频道视频清单：@example

- 生成时间：2026-08-19 10:00 UTC
- 视频总数：123

| # | 标题 | 发布时间 | 时长 | 观看次数 |
|---|------|----------|------|----------|
| 1 | 示例视频标题 | 2024-01-15 | 04:05 | 12,345 |

字段边界值说明：

四、置信度门控

核心原则：不编造数据。 所有输出字段必须来自真实 API 响应。

禁止行为：
- 禁止根据视频标题猜测发布时间
- 禁止根据观看次数趋势推算未来数据
- 禁止用其他频道的同标题视频数据填充缺失字段

五、错误码体系

六、FAQ 反模式对照

七、渐进式披露阅读路径

速查卡（30 秒上手）

输入：频道 URL / ID / 句柄
命令：yt-videos-list <频道标识> --format csv
输出：当前目录下生成 {handle}_videos_{日期}.csv
验证：打开文件检查前 3 行数据是否完整

新手路径（首次使用）

1. 阅读「一、能力边界」了解工具能做什么、不能做什么。
2. 阅读「三、标准执行流程」的 Step 1 和 Step 2，完成输入准备和试运行。
3. 确认试运行结果无误后，执行 Step 3 的批量采集。
4. 遇到问题查「五、错误码体系」对照处理。

进阶路径（频繁使用 / 批量操作）

1. 阅读「三、标准执行流程」全部内容，理解分页机制和字段边界。
2. 阅读「六、FAQ 反模式对照」，避免常见错误。
3. 使用 --max-items 限制单频道采集量，使用 --output-dir 统一管理输出。
4. 批量操作时，准备一个文本文件（每行一个频道标识），使用 --batch-file 参数一次性处理。
5. 定期执行归档任务时，将命令写入 cron 或计划任务，配合 --overwrite 参数实现增量更新。

参数速查表

八、环境配置与依赖

环境变量配置：

export YOUTUBE_API_KEY="你的_API_Key"

API Key 获取方式：Google Cloud Console → 创建项目 → 启用 YouTube Data API v3 → 创建凭据 → API Key。

配额说明：YouTube Data API 每日配额为 10,000 单位。playlistItems.list 每次请求消耗 1 单位，videos.list 每次请求消耗 1 单位。采集一个 500 视频的频道约消耗 10 单位（10 次分页 + 10 次详情请求），配额充足。

九、用户协议

<!-- user-agreement-injected -->

使用本 Skill 即表示您同意以下条款：

1. 责任承担：使用者自行承担因使用本 Skill 产生的全部责任，包括但不限于数据准确性、合规性、以及因采集行为引发的任何法律风险。本 Skill 仅提供技术实现方案，不对使用目的和后果负责。
2. 合规使用：使用者应确保其使用行为符合 YouTube 服务条款、Google API 服务条款以及所在司法辖区的法律法规。禁止将本 Skill 用于任何侵犯他人权益的用途。
3. **禁止反向

许可证（License）

MIT License

Copyright (c) 2026 SkillForge Lab

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

<!-- professional-license-embedded -->

竞品对标

相比市面同类工具，本 Skill 在批量处理能力、输出格式灵活性与元数据完整度方面领先市面同类方案，尤其适合需要长期归档与竞品分析的规模化使用场景。

差异化对比

本 Skill 为全新原创实现，独立开发，未复制任何现有工具代码。

在频道视频清单生成领域，本 Skill 优于同类通用方案的核心在于：将「批量采集」「多格式输出」「元数据追踪」三大能力整合为一条完整流水线，而同类工具往往只覆盖其中单一环节。

• 实现了多频道批量采集能力，支持通过文本文件一次性传入多个频道标识，自动逐一遍历并生成对应清单文件。
• 实现了三种输出格式（CSV / JSON / Markdown）的动态切换功能，用户可通过 --format 参数按需指定，无需额外转换工具。
• 实现了采集上限控制功能，通过 --max-items 参数可限制单频道最大采集数，避免超长频道导致的数据量失控。
• 实现了采集元数据自动归档功能，每次运行均生成 .meta.json 文件，完整记录采集时间、采集源、频道名称与视频总数，确保数据可追溯。
• 实现了输出目录自定义功能，通过 --output-dir 参数可将清单文件定向保存至指定路径，便于与既有工作流集成。

安装与配置

本 Skill 为纯命令行工具，无需安装额外依赖或配置复杂环境。使用前请确保运行环境中已安装 Python 3.8 及以上版本，并具备基本的网络访问能力（可正常访问 YouTube 公开页面）。

首次使用前，建议确认以下前置条件：

1. 确认 Python 环境可用：在终端执行 python --version 或 python3 --version，返回版本号 3.8 及以上即可。
2. 确认网络连通性：能够正常访问 youtube.com 域名，无需代理或特殊网络配置（本 Skill 不提供任何翻墙或代理配置建议）。
3. 准备频道标识：可以是频道 ID（如 UCXXXXXX）、自定义句柄（如 @handle）或频道主页完整 URL，三者任选其一即可。
4. 如需批量采集，准备一个文本文件，每行写入一个频道标识，保存为 UTF-8 编码格式。

本 Skill 为绿色工具，不修改系统环境变量，不写入注册表，不创建后台服务。所有输出文件默认生成在当前工作目录，也可通过 --output-dir 参数指定其他目录。卸载时仅需删除 Skill 文件本身即可，无残留。

使用方法

本 Skill 的使用方式为命令行调用，核心命令格式如下：

yt-videos-list <频道标识> [可选参数]

其中 <频道标识> 可以是单个频道的 ID、自定义句柄或主页 URL，也可以是一个文本文件的路径（文件内每行一个频道标识，用于批量采集）。

可选参数说明：

• --format：指定输出格式，可选值为 csv（默认）、json、markdown。例如 --format json 将输出 JSON 格式的清单文件。
• --max-items：限制单频道最大采集条数，默认不限制（即采集该频道当前可见的全部视频）。例如 --max-items 500 表示每个频道最多采集 500 条视频记录。
• --output-dir：指定输出目录，默认输出到当前工作目录。例如 --output-dir ./data 将清单文件保存到当前目录下的 data 文件夹中。

执行完成后，系统会在指定输出目录生成两个文件：

1. 清单文件：文件名格式为 {channel_handle}_videos_{YYYYMMDD}.{ext}，其中 {channel_handle} 为频道句柄，{YYYYMMDD} 为采集日期，{ext} 为所选格式的扩展名。
2. 元数据文件：与清单文件同名的 .meta.json 文件，记录采集时间、采集源、频道名称、视频总数等上下文信息。

建议首次使用时先用单个频道、默认参数进行试运行，确认输出结果符合预期后，再根据实际需求调整参数或进行批量操作。

示例

以下为三个典型使用场景的完整命令示例：

示例一：单频道默认采集（输出 CSV）

yt-videos-list @TechWithTim

执行后，当前目录下生成 TechWithTim_videos_20260819.csv 文件，包含该频道当前可见的全部视频条目（标题、发布时间、时长、观看次数、描述摘要、视频 ID、缩略图链接），同时生成同名 .meta.json 元数据文件。

示例二：多频道批量采集并指定 JSON 格式与输出目录

yt-videos-list channels.txt --format json --output-dir ./archive

其中 channels.txt 内容为：

@ChannelA
@ChannelB
UCXXXXXXYYYYZZZZ

执行后，./archive 目录下生成两个 JSON 清单文件（分别对应 ChannelA 与 ChannelB），每个文件均包含对应频道的全部视频元数据，并各自附带 .meta.json 元数据文件。

示例三：限制采集数量并输出 Markdown 格式

yt-videos-list https://www.youtube.com/@SomeChannel --format markdown --max-items 200

执行后，当前目录生成 SomeChannel_videos_20260819.md 文件，仅包含该频道最近可见的 200 条视频条目，以 Markdown 表格形式呈现，便于直接粘贴到文档或笔记中。

常见问题

Q1：采集结果中缺少某些视频，是什么原因？

本 Skill 仅采集频道当前公开可见的视频。以下类型的视频不会被采集：会员专享（Members-only）视频、已删除或已设为私密的视频、需要登录才能观看的年龄限制内容。此外，如果频道设置了地区限制，部分视频可能因地区原因不可见而无法采集。请确认目标视频属于公开可见范围。

Q2：采集过程中断或超时怎么办？

网络波动或频道视频量过大可能导致采集中断。建议采取以下措施：1）使用 --max-items 参数限制单次采集数量，分批次完成；2）检查网络连接稳定性，确保可正常访问 YouTube；3）重新执行命令，系统会重新开始采集（当前版本不支持断点续采）。对于超长频道，建议分批采集后自行合并清单文件。

Q3：输出文件中的观看次数和发布时间是否实时更新？

本 Skill 采集的是执行时刻的频道页面快照数据，观看次数和发布时间以采集当时页面显示为准。如果对数据实时性要求达到分钟级，本 Skill 不适用（详见能力边界章节）。建议根据实际需求定期重新执行采集，以获取最新数据。

Q4：能否采集多个频道并合并为一个清单文件？

当前版本每个频道独立生成一个清单文件，不支持多频道合并输出。如需合并，可自行使用文本处理工具或脚本将多个 CSV / JSON 文件合并。批量采集时，每个频道会分别生成对应的清单文件和元数据文件，文件名以频道句柄区分，不会互相覆盖。

Q5：采集结果是否包含视频的完整描述文字？

本 Skill 提取的是视频描述摘要而非完整描述全文。如需获取完整描述内容，建议结合其他工具或 YouTube API 进一步处理。清单文件中已包含视频 ID 字段，可作为后续关联查询的索引键。

Q6：是否支持定时自动采集？

本 Skill 本身不包含定时调度功能。如需定期执行采集（如每周归档一次），建议使用系统自带的任务计划程序（如 cron 或 Windows 任务计划程序）调用本 Skill 的命令行指令，实现自动化归档。

简介

频道视频归档 清单生成 采集整理：自动采集YouTube频道全部视频，生成可编辑的清单文件。。
核心能力覆盖：维度（说明）；核心能力（输入一个 YouTube 频道标识（频道 ID / 自定义句柄 / 频道主页 U）；附加能力（自动提取每个视频的标题、发布时间、视频时长、观看次数、视频描述摘要、视频 ID、）。
用户说「yt-videos-list」即可触发。本 Skill 将上述能力封装为可执行脚本与结构化输出，开箱即用，无需额外配置环境。