YouTube 油管视频互动数据与观看留存分析

输入一个公开的 YouTube 视频 链接，获取内容身份和公开互动指标，并保存可复核的 engagement.json。

何时使用

• 用户想查看一条 YouTube 视频 的播放、点赞、评论、收藏或分享数据。
• 用户想把 YouTube 视频 表现整理成结构化互动快照。
• 用户想比较多条 YouTube 视频 时，先分别采集每条内容的数据。

不要用于账号主页资料分析，不要访问私人或受限内容，也不要从互动计数推断受众身份、转化率或投资回报率。

输入

每次只接受一个公开的 YouTube 视频 URL，例如：

https://www.youtube.com/watch?v=<video_id>

拒绝账号主页、搜索页、包含用户名密码的 URL 和本地网络地址。

工作流

1. 确认 URL 属于 YouTube 且指向一条具体视频。
2. 使用 --json 和独立的 --output-dir 执行脚本，每个 URL 只请求一次。
3. 检查 success、resultPath、missingCoreFields 和 warnings。
4. 保留原始播放、点赞、评论、收藏和分享字段，不把缺失值写成零。
5. 仅在分母存在且非零时计算比率，并明确展示公式；不得把派生值描述成平台官方指标。

输出

成功结果包含作者、标题、标签、播放数、点赞数、评论数、收藏数、分享数、时长、发布时间、封面和平台返回的其他字段。最终文件为 engagement.json。

不同平台对播放、收藏和分享的定义可能不同，跨平台比较时必须说明口径差异。

示例指令

• “帮我看看这条 YouTube 视频 的互动数据。”
• “把这个 YouTube 链接的播放、点赞和评论整理出来。”
• “给这条 YouTube 视频 生成一份互动快照。”

OAuth 授权

正常执行原任务。缺少凭据时，脚本返回 AUTH_REQUIRED（退出码 2），不要把它当作可重试的业务错误，也不要要求用户自行获取或粘贴 API Key。

向用户说明将打开 UnityClaw 授权页面，并询问是否同意。只有用户明确同意后，才运行：

node scripts/authorize.js --authorize --json

授权命令只完成 OAuth 和凭据保存，不调用业务接口。成功后重新执行用户原来的业务命令一次；用户拒绝、取消、超时或授权失败时停止，不循环弹窗。不得回显、记录或写入凭据。

如果旧凭据无效，不要直接 OAuth 后重试；先排查并清理旧凭据，否则它可能覆盖新授权结果。服务端业务失败不触发 OAuth。

运行

node scripts/generate.js --url "https://www.youtube.com/watch?v=<video_id>" --lang zh --json --output-dir ./tasks