抖音数据自动化（月度报表 + 单篇作品）

Overview

一个 skill 两条功能线，共用同一套环境与浏览器：

A 线 · 月度报表：数据中心-经营概览，筛「上一个完整自然月」，提取作品 8 字段 + 粉丝 5 字段，导出 YYYY年M月月度数据统计.csv
B 线 · 单篇作品：内容管理-作品列表，按时间范围加载全部作品，逐部抓取 14 项指标 + 下载封面，导出 YYYY年M月单篇数据统计.csv

两线时间口径统一：默认「上一个完整自然月」。浏览器登录态共享（CDP 复用），完整流程结束后自动关闭浏览器。

运行模型

STEP 0: AskUserQuestion 交互询问时间范围（一次，两线共用）
环境:  setup.js（一键安装 playwright/chromium）→ browser_launcher.js（启动浏览器，登录一次）
一键:   run_all.js（自动启动浏览器 → 月度报表 → 单篇作品 → 自动关闭）
A线:   select_date_range / extract_metrics / fans_data / export_report
B线:   works_all（一键抓取）/ works_progress（进度跟踪）

一键连跑（推荐入口）

node scripts/run_all.js                        # 默认：上一个月，两线都跑
node scripts/run_all.js --range=1w             # 上一完整自然周
node scripts/run_all.js --range=2m             # 上两个完整自然月
node scripts/run_all.js --range=custom --from=2026-07-01 --to=2026-07-31
node scripts/run_all.js --out=D:/reports       # 产物目录（默认 运行目录/dist）
node scripts/run_all.js --keep-open            # 全部完成保留浏览器

自动完成：检测/启动浏览器（未运行则自动拉起）→ 等待页面加载 → A 线（月度数据报表）→ B 线（单篇作品数据）→ 自动关闭浏览器
两线共用同一日期区间，产物 YYYY年M月月度数据统计.csv + YYYY年M月单篇数据统计.csv + 封面文件夹
A 线失败自动关闭浏览器并中止；参数格式 --k=v

STEP 0 — 选择时间范围（交互询问一次，两线共用）

调用本 skill 时，先通过 AskUserQuestion 弹窗询问时间范围（4 个选项；2026-08-15 用户确认 A/B 两线均采用交互询问）：

| 弹窗选项 | 语义 | A 线（export_report） | B 线（works_all） | |---------|------|----------------------|------------------| | 上一个月（默认） | 上一个完整自然月 | 不传（自动） | --range=1m | | 上一周 | 上一完整自然周（周一~周日） | --start/--end | --range=1w | | 上两个月 | 上两个完整自然月 | --start/--end | --range=2m | | 自定义范围 | 追问起止日期（--from 不得晚于 --to） | --start/--end | --range=custom --from/--to |

询问仅发生一次：用户选完日期后，需要跑月度报表和/或单篇作品时，两条线使用同一日期区间（如选「上一个月」→ 月度报表与单篇作品都是 7 月）
弹窗选「自定义范围」时追问起止日期（校验合法性，--from 不得晚于 --to）
脚本内部：export_report 仍会对「作品数据 / 粉丝数据」两个模块各执行一次日历选择（两模块日期组件独立，页面限制），works_all 对内容管理模块执行一次——这些是自动化内部动作，用户全程只感知「选一次日期」

随后询问「本次要执行哪个任务」（选项用易懂名称，2026-08-15 用户确认）：

| 弹窗选项 | 实际执行 | 产出 | |---------|---------|------| | 两者都要（推荐） | 先月度数据报表，再单篇作品数据 | 两个 CSV + 封面 | | 月度数据报表 | export_report.js（数据中心作品+粉丝汇总） | YYYY年M月月度数据统计.csv（13 字段） | | 单篇作品数据 | works_all.js（每部作品 14 项指标+封面） | YYYY年M月单篇数据统计.csv（17 列）+ 区间月单篇作品封面/（如 7月、6-7月，跨年带年份） |

STEP 1 — 环境准备（仅首次/纯净环境）

node scripts/setup.js --yes

检测 npm / playwright / chromium / 系统浏览器 / CDP 端口，缺失自动安装（官方源→npmmirror 回退，chromium 走国内镜像 + 版本校验）

STEP 2 — 启动浏览器

node scripts/browser_launcher.js [--port 9222] [--profile <dir>]

持久化 profile（data/profile/，登录态跨会话保留）+ CDP 端口 9222；端口已有实例则复用
首次未登录：浏览器窗口扫码（同机大概率「信任设备自动登录」免扫码）
连接失败/端口占用有友好提示

A 线 · 月度报表（数据中心）

日期筛选（时间范围由 STEP 0 交互询问确定；默认自动筛上一个完整自然月）

node scripts/select_date_range.js [--start 2026-07-01 --end 2026-07-31]

不传日期 = 自动上月（8 月跑 → 7 月，跨年自动处理）；日期组件精确选择（自动翻页）

提取数据

node scripts/extract_metrics.js [--fields "总播放量,总点赞量"]   # 作品 8 字段
node scripts/fans_data.js [--start ... --end ...]               # 粉丝 5 字段（筛选+提取一步）
node scripts/fans_data.js --extract-only                        # 仅提取当前值

作品 8 字段：总播放量/总点赞量/总分享量/总评论量/5秒完播率/2秒跳出率/封面点击率/平均播放时长
粉丝 5 字段：总粉丝量/粉丝净增/吸粉量/脱粉量/回访粉丝量
提取带加载重试（15s）；extract_metrics 输出当前统计区间提示

一键导出 CSV

node scripts/export_report.js [--start ... --end ...] [--out 目录] [--keep-open]

串行筛作品+粉丝为同一区间 → 合并 13 字段 → YYYY年M月月度数据统计.csv
CSV：首行字段名 + 首列年月、总粉丝量置末、平均播放时长去单位、UTF-8 BOM
默认执行完自动关闭浏览器；异常路径兜底关闭；--out 兼容 Git Bash 路径

B 线 · 单篇作品（内容管理）

一键抓取（筛选 → 列表 → 详情 → 封面 → CSV）

node scripts/works_all.js                     # 默认：上一个完整自然月
node scripts/works_all.js --range=1w          # 上一完整自然周（周一~周日）
node scripts/works_all.js --range=2m          # 上两个完整自然月
node scripts/works_all.js --range=custom --from=2026-07-01 --to=2026-07-31
node scripts/works_all.js --out=D:/reports    # 产物目录（等号格式）
node scripts/works_all.js --batch=3 --interval=3   # 并发/间隔（防风控）
node scripts/works_all.js --keep-open         # 抓完保留浏览器

参数统一 --k=v 格式（--keep-open 为无值 flag）
时间口径：1m = 上一个完整自然月（与 A 线一致，日历精确选择）；1w 上一完整自然周（周一~周日）；2m 上两个完整自然月（与 1m 同为日历精确选择）；custom 自定义
流程：连接浏览器 → 内容管理 → 等待登录 → 筛选 → 滚动加载全部卡片 → 分批并发抓详情（每批 1~5，失败重试 1 次，批次间隔 3s）→ 封面下载 → YYYY年M月单篇数据统计.csv（17 列）
抓取稳健性：详情页轮询提取（800ms，上限 25s）等关键字段齐全；字段缺失记 DATA_INCOMPLETE 并重试；标题校验防 mid 错位
默认执行完自动关闭浏览器；异常兜底关闭

进度跟踪（另开终端并行）

node scripts/works_progress.js --out=目录           # 打印一次进度（等号格式）
node scripts/works_progress.js --watch --out=目录    # 每 60s 刷新，任务结束自动退出

进度文件：<out>/progress.json（阶段/总数/已完成/成功/失败/当前作品/已用时长/预计剩余）

B 线产物（--out 目录，默认当前工作目录下的 dist/）

| 文件 | 说明 | |------|------| | YYYY年M月单篇数据统计.csv | 17 列：封面/标题/发布日期/视频时长/播放量/点赞量/评论量/分享量/收藏量/完播率/2s跳出率/涨粉量/粉丝播放占比/平均播放时长/5s完播率/流量来源/搜索关键词（标题校验/抓取状态为内部诊断，不输出，2026-08-15 用户确认）。单篇作品线（月份取区间起始日所在月，如默认自然月 7 月 → 2026年7月单篇数据统计.csv） | | 区间月单篇作品封面/（按区间起止月命名：7月 / 6-7月 / 跨年带年份） | 封面图（mid 命名，按 content-type 判扩展名） | | progress.json（运行中） | 实时进度，任务正常完成后自动删除（产物只留 CSV + 封面） |

产物路径：A/B 两线默认统一输出到「运行命令时的当前工作目录/dist/」（A 线 CSV、B 线 CSV、区间月单篇作品封面/ 集中于此（按起止月命名，跨年带年份）；progress.json 仅抓取运行中存在，完成后自动清理，2026-08-15 用户确认）。标准用法：在项目目录（如 D:\WorkBuddy\<会话目录>）下运行命令，产物即默认输出到项目目录/dist/（2026-08-15 用户确认）；也可用 --out 覆盖（B 线 --out=目录 等号格式、A 线 --out 目录 空格格式）。两线 CSV 命名已区分（月度 vs 单篇），同目录输出互不覆盖。

通用工具

node scripts/operate.js [--goto <url> | --click <文本> | --dump]   # 通用操作
node scripts/screenshot.js [--out <路径>]                          # 截图

公共模块（scripts/lib/）

session.js — 连接浏览器（失败提示）+ 幂等跳转 + 关闭浏览器
dom.js — 模块定位（作品/粉丝数据）+ 字段提取 + 加载重试
datepicker.js — 日期面板翻页精确选择
date.js — 上一个完整自然月计算
works_lib.js — B 线共享（日历交互/指标提取/CSV/封面/进度）

Resources

scripts/setup.js / scripts/browser_launcher.js — 环境与浏览器
scripts/select_date_range.js / extract_metrics.js / fans_data.js / export_report.js — A 线
scripts/works_all.js / works_progress.js — B 线
references/douyin_creator_guide.md — 数据中心页面结构、DOM、数据口径
references/works_detail_guide.md — 内容管理页结构、魔法数字依赖、改版排查