shield_lock
JinDaGe
← Back to skills
extension
Category: Data & AnalyticsAPI key required

频道视频归档 清单生成 采集整理

自动采集YouTube频道全部视频，生成可编辑的清单文件。

personAuthor: user_a10ab3adhubcommunity
downloadDownload package

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

<!-- professional-disclaimer-injected -->

本内容由 AI 生成，仅供学习参考

<!-- ai-generated-notice -->

SKILL.md — yt-videos-list

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

| 维度 | 说明 | |------|------| | 核心能力 | 输入一个 YouTube 频道标识（频道 ID / 自定义句柄 / 频道主页 URL），输出该频道当前可见的全部视频条目清单（CSV / JSON / Markdown 三种格式可选） | | 附加能力 | 自动提取每个视频的标题、发布时间、视频时长、观看次数、视频描述摘要、视频 ID、缩略图链接 | | 不做的事 | 不下载视频文件本身；不采集会员专享（Members-only）视频；不采集已删除或已设为私密的视频；不处理需要登录才能观看的年龄限制内容；不提供任何形式的翻墙或代理配置建议 | | 适用对象 | 内容运营人员、市场调研人员、竞品分析者、视频创作者（用于整理自己的频道）、学术研究者（需公开数据） | | 不适用对象 | 需要批量下载视频文件用于二次分发的人；需要采集非公开数据的人；对数据实时性要求达到分钟级的人 |

输入要求：

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

输出产物：

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

二、触发方式与场景映射

| 触发词 / 用户说法 | 实际含义 | 本 Skill 的响应 | |-------------------|----------|-----------------| | "yt-videos-list" | 直接调用工具名 | 执行完整采集流程 | | "帮我拉一下这个频道的所有视频" | 需要频道视频清单 | 引导提供频道链接或 ID，执行采集 | | "YouTube视频列表" | 中文直呼功能名 | 同上 | | "频道视频采集" | 需要批量获取视频元数据 | 同上，并询问输出格式偏好 | | "视频清单生成" | 需要结构化清单文件 | 同上，默认输出 CSV | | "YouTube频道归档" | 需要长期保存频道内容索引 | 同上，并建议定期执行策略 | | "盘点一下这个频道发了什么" | 需要内容概览 | 执行采集并输出摘要统计（视频数、时间跨度、平均时长） | | "导出这个频道的视频目录" | 需要可编辑的目录文件 | 执行采集，默认输出 CSV 并提示可用 Excel 打开 |

不触发的情况：

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

三、标准执行流程

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

  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 |

字段边界值说明：

| 字段 | 类型 | 边界值 | |------|------|--------| | duration_seconds | 整数 | 最小值 0（直播回放可能为 0），最大值不超过 12 小时（43200 秒） | | view_count | 整数 | 最小值 0，最大值可能超过 21 亿（需用 64 位整数存储） | | description_snippet | 字符串 | 固定截取前 100 个字符，若描述为空则输出空字符串 | | published_at | ISO 8601 字符串 | 格式固定为 YYYY-MM-DDTHH:MM:SSZ，UTC 时区 |

四、置信度门控

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

| 场景 | 处理方式 | |------|----------| | API 返回的某个字段缺失（如视频描述为空） | 输出空字符串，不猜测内容 | | 频道存在但视频数为 0 | 正常输出空清单，元数据中 total_count=0，不报错 | | 频道 ID 有效但无法获取 uploads 播放列表 | 输出 [需核实:频道上传列表] 占位，提示用户检查频道状态 | | 视频时长字段解析失败 | 输出 [需核实:duration] 占位，跳过该字段 | | 采集过程中部分视频 API 请求失败（网络抖动） | 重试 3 次，仍失败则跳过该视频并在元数据中记录 skipped_count 和 skipped_ids | | 用户提供的频道标识疑似拼写错误 | 输出 [需核实:频道标识]，提示用户确认，不自动修正 |

禁止行为：

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

五、错误码体系

| 错误码 | 含义 | 用户提示话术 | 修正步骤 | |--------|------|--------------|----------| | E1001 | 输入格式无法识别 | "无法识别您提供的频道标识，请提供完整的频道 URL、频道 ID（UC开头）或句柄（@开头）" | 1. 检查输入是否包含空格或多余字符；2. 确认复制的是完整链接；3. 重新输入 | | E1002 | 频道不存在或已注销 | "未找到对应的 YouTube 频道，请确认频道链接是否有效" | 1. 在浏览器中打开该链接验证；2. 确认频道未被删除或改名；3. 重新提供正确的频道标识 | | E2001 | 试运行字段校验失败 | "试运行结果字段不完整，请检查网络后重试" | 1. 确认网络连接正常；2. 检查 API 配额是否耗尽；3. 重新执行试运行 | | E2002 | API 配额耗尽 | "YouTube API 配额已用尽，请稍后再试或更换 API Key" | 1. 等待配额重置（通常为每日 UTC 0 点）；2. 在环境变量中配置新的 API Key；3. 重新执行 | | E3001 | 输出目录不可写 | "无法写入输出文件，请检查目标目录权限" | 1. 确认输出目录存在；2. 检查目录写权限；3. 更换 --output-dir 参数 | | E3002 | 输出文件已存在且未开启覆盖 | "输出文件已存在，请使用 --overwrite 参数覆盖或更换输出目录" | 1. 确认是否需要覆盖；2. 添加 --overwrite 参数；3. 或指定新的输出目录 | | E9001 | 未知错误 | "发生未知错误，请查看日志文件 debug.log 获取详细信息" | 1. 查看日志；2. 携带日志内容反馈问题 |

六、FAQ 反模式对照

| # | 常见坑（反模式） | 正确做法（正模式） | |---|------------------|-------------------| | 1 | 直接批量执行不试运行：用户提供 50 个频道，直接全量采集，结果发现字段映射错误，全部返工 | 先单样本试运行：任选 1 个频道执行完整流程，核对输出无误后再批量执行。批量执行时保留原始数据备份（--backup 参数） | | 2 | 忽略分页限制：只拉取第一页 50 条就结束，导致清单不完整 | 循环翻页直到 nextPageToken 为空：同时设置最大页数保护（默认 100 页），防止死循环 | | 3 | 描述字段全量存储：将完整描述写入 CSV，导致文件巨大且 CSV 格式错乱（描述中含逗号和换行） | 只截取前 100 字符，且用双引号包裹字段，内部双引号转义为 "" | | 4 | 时区混乱：将 API 返回的 UTC 时间直接当作本地时间展示，导致发布时间偏差 | 统一使用 ISO 8601 UTC 格式存储，展示时由用户自行转换时区 | | 5 | 不处理限流：高频请求触发 YouTube API 限流，导致大量请求失败 | 内置指数退避重试：首次失败等待 1 秒，第二次 2 秒，第三次 4 秒，最多重试 3 次；同时支持 --rate-limit 参数自定义请求间隔（默认 0.1 秒） | | 6 | 覆盖原文件：重复执行时直接覆盖上次的清单文件，导致历史数据丢失 | 默认生成带日期戳的文件名，如需覆盖必须显式添加 --overwrite 参数 |

七、渐进式披露阅读路径

速查卡（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 参数实现增量更新。

参数速查表

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | --format | string | csv | 输出格式：csv / json / markdown | | --max-items | int | 无限制 | 单频道最大采集视频数 | | --output-dir | string | 当前目录 | 输出文件保存目录 | | --overwrite | boolean | false | 是否覆盖已存在的同名输出文件 | | --batch-file | string | 无 | 包含多个频道标识的文本文件路径 | | --rate-limit | float | 0.1 | API 请求间隔（秒） | | --backup | boolean | false | 批量执行前是否备份已有数据 | | --selftest | boolean | false | 运行自检程序，验证环境配置 | | --version | boolean | false | 显示版本号并退出 |

八、环境配置与依赖

| 依赖项 | 版本要求 | 用途 | |--------|----------|------| | Python | ≥ 3.9 | 运行环境 | | google-api-python-client | ≥ 2.100.0 | YouTube Data API 客户端 | | python-dotenv | ≥ 1.0.0 | 读取 API Key 环境变量 |

环境变量配置：

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 | 同类通用方案 | |----------|----------|--------------| | 批量采集能力 | 支持单次输入多个频道标识（文本文件每行一个），自动遍历采集全部视频条目 | 多数同类工具仅支持单频道逐个手动操作，无法批量处理 | | 输出格式 | 同时支持 CSV / JSON / Markdown 三种结构化格式，适配不同下游使用场景 | 通常仅提供单一格式导出，或需额外插件转换 | | 元数据丰富度 | 自动提取标题、发布时间、时长、观看次数、描述摘要、视频 ID、缩略图链接共 7 类元数据 | 同类方案通常仅提取标题与链接，信息维度明显不足 | | 可配置性 | 提供 --format、--max-items、--output-dir 三个可选参数，灵活控制输出格式、采集上限与存储位置 | 多数工具为固定逻辑，无法按需调整采集深度与输出路径 | | 元数据追踪 | 每次采集自动生成 .meta.json 元数据文件，记录采集时间、采集源、频道名称、视频总数等上下文信息 | 同类工具普遍缺少采集溯源与上下文记录，不利于数据审计与复现 |

相比市面同类工具，本 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 将上述能力封装为可执行脚本与结构化输出，开箱即用，无需额外配置环境。