抖音数据统计（douyin-video-data）

SDD 结构（规格驱动开发）：本技能 v3.1.0 按规格重构，功能基线 v2.0.3，行为不变。

• 需求与验收标准：references/SPEC.md
• 设计决策与权衡：references/EXPLANATION.md
• 实现：scripts/fetch.js（入口）+ scripts/lib/*（分层模块）
• 测试：test/*.test.js（node:test，零依赖，离线可跑；开发期资产，不进分发包）

Overview

通过 Playwright 打开抖音创作者中心（creator.douyin.com）自动登录（首次扫码，登录态持久化 .dy_profile，后续免扫），拉取指定周期（上一周/上一个月）的经营数据。口径：自然周（周一~周日）/ 自然月（1号~月末）。

输出：

• 周期统计 CSV：统计周期、播放量、主页访问、作品点赞、作品分享、作品评论、5秒完播率、2秒跳出率、封面点击率、平均播放时长、净增粉丝、吸粉量、脱粉量、回访粉丝量、总粉丝量（POST date_range 取后台官方聚合值）
• 单篇 CSV：标题、封面、发布时间、视频时长、播放、点赞、评论、分享、收藏、完播率、5秒完播率、2秒跳出率、平均播放时长、吸粉量、粉丝播放占比、最大流量来源、搜索关键词
• 单篇封面图片（按发布时间+item_id 命名，下载到 dist/{周期}单篇封面/）

产物统一放在运行目录 dist/，CSV 用中文命名（如 2026年07月抖音月度数据统计.csv）。

前置条件

1. Node.js ≥ 18（Playwright 要求）与 npm
2. Playwright：本地项目安装 npm install playwright，然后 npx playwright install chromium（浏览器二进制，用户级缓存全项目共享，只下载一次）
   • 国内镜像：set PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright 后再执行 install chromium（只填镜像根地址、不带版本号）
   • 若未安装浏览器，脚本启动时会报错并给出中文指引，按提示执行即可
3. 登录态：首次运行自动打开浏览器，弹出扫码页请用抖音 App 扫码（无免扫码通道），脚本自动检测登录（最长 120s）；登录态持久化在运行目录 .dy_profile/，后续免扫且秒登
4. 浏览器约定：一律用 playwright 自带 chromium，禁用 channel: 'chrome'/'msedge'

执行流程

1. 将 scripts/ 整个目录复制到当前工作区（fetch.js 依赖 lib/ 子模块）
2. 工作区 npm init -y && npm install playwright（若无 node_modules）+ npx playwright install chromium（若未装浏览器）
3. 运行 node fetch.js，交互输入（回车即提交）：
   • 1 = 上一周（自然周 周一~周日）
   • 2 = 上一个月（自然月 1号~月末）
   • 也支持参数直跑：node fetch.js 1 / node fetch.js 2（自动化友好，跳过交互）
4. 首次运行会打开浏览器 → 扫码登录 → 自动继续
5. 产物生成在 dist/：
   • {时间}抖音{月度|周度}数据统计.csv — 15 列横向大宽表（自然周期聚合）
   • {时间}抖音单篇数据统计.csv — 单篇明细
   • {时间}单篇封面/ — 每作品 1 张封面

测试（离线回归）

核心逻辑（周期/时区/CSV/指标映射/产物组装）已规格化为纯函数并有单测覆盖（对应 SPEC 各 AC）：

node --test test/*.test.js   # Node ≥ 18，零依赖，约 0.3s

• 纯函数类验收标准（⚙）全部自动化；需真连抖音的端到端类（🔌：登录/真实接口/崩溃恢复）发布前手动 node fetch.js 1 核对一次
• 改日期口径、CSV 列序、格式等敏感逻辑后必须先跑测试再交付

接口与字段映射

周期统计（POST + date_range，后台官方聚合值）

v2.0.0 关键能力：dashboard / dashboard/fans 接口支持 POST + body date_range（日历选自然月/周后前端就调这个）：

POST /janus/douyin/creator/data/overview/dashboard
Body: {"recent_days":7,"date_range":{"start_date":"20260701","end_date":"20260731"}}

• date_range.start_date / end_date 格式：YYYYMMDD（无横线）
• 返回值与抖音后台"数据总览"选日期后看到的指标完全一致
• 13 项 dashboard 指标 + 6 项 fans 指标一次拿全
• 踩坑：GET + query ?start_date=...&end_date=... 无效；POST body 嵌套 date_range 才对

单篇作品列表（janus work_list，无签名全量）

• work_list 替代旧 item/list 抓全量单篇：297 条 8 页约 20s

GET https://creator.douyin.com/janus/douyin/creator/pc/work_list?status=0&count=40&max_cursor=X&scene=star_atlas&device_platform=android&aid=1128

• 无签名，可直接 page.request.get；count 上限 40，max_cursor 翻页直到 has_more=false
• 响应：items[]（含 metrics 详细指标）+ aweme_list[]（按相同下标对应，含 duration 毫秒、statistics 基础统计、desc/caption 等）
• 单篇 metrics：view_count / like_count / comment_count / share_count / favorite_count / completion_rate / completion_rate_5s / bounce_rate_2s / avg_view_second / subscribe_count（吸粉量） / fan_view_proportion（粉丝播放占比 0-1） / unsubscribe_count 等 25 项

单篇流量分析（janus 无签名，单篇详情页接口）

GET https://creator.douyin.com/janus/douyin/creator/data/item/play/source?aid=2906&item_id={id}
GET https://creator.douyin.com/janus/douyin/creator/data/item_analysis/search/keyword?aid=2906&id={id}

• 流量来源：play_source[] → key（homepage_hot=推荐页/search=搜索/familiar=朋友页/follow=关注页/homepage=个人主页）+ value（0-1 占比）+ history_difference（对比7日）
• 搜索关键词：show_from[]（用户通过这些词看到作品，即搜索来源关键词，含 keyword + percent）+ inspire_search[]（看完后常搜的词），合并输出去重（如"同道机械"）
• 踩坑：只解析 inspire_search 会漏数据——多数作品的搜索关键词在 show_from 里
• 注意：item_id 必须是 aweme_list[].aweme_id（字符串）；items[].id 是数字会丢精度（>2^53），查不到数据
• 老作品（数据过期）可能返回空 play_source → 显示"暂无数据"
• 需逐条作品调用（21 条约 20s，间隔 300ms 防风控）

关键实现要点

• POST date_range 是周期统计的关键：直接拿到后台官方聚合值
• id 精度坑：work_list 的 items[].id 是数字，JSON.parse 后 >2^53 丢精度；必须用 aweme_list[].aweme_id（字符串）作为接口参数和文件名
• 登录检测：轮询 user/info 接口（status_code===0 才算登录）；URL 判断不可靠（未登录也可能停在 /creator-micro）
• 时间戳：用 JS Date 计算，勿手算；单篇发布时间/封面文件名统一按北京时间显示（bj() 时区换算，与系统时区无关）
• 窗口最大化：viewport:null + args:['--start-maximized']
• CSV 写 UTF-8 BOM（Excel 不乱码），被占用时重试
• 崩溃自恢复（v2.0.3）：页面崩溃（Page crashed，常见于远程/无桌面会话）自动重启页面并续跑；接口请求失败自动重试 3 次；接口重试仍失败时单篇对应列标记 "接口失败"（区别于正常无数据的"暂无数据"）
• 非交互环境（v2.0.3）：未传参数且 stdin 非终端时明确报错并提示 node fetch.js 1|2，不再静默退出
• 封面下载（v2.0.3）：带 referer: https://creator.douyin.com/ 请求头，规避图片 CDN 防盗链

已知限制

• 搜索关键词：多数作品"暂无数据"（需作品有搜索流量才会产生关键词）
• 老作品（数据过期）最大流量来源可能为空
• 单篇全量拉取 + 流量接口逐条调用，21 条作品总耗时约 40s
• work_list 翻页上限 50 页（约 2000 条）；超量会截断并在日志提示
• 周日当天运行取"上一周" = 上周一 ~ 上周日（本周日发布的作品不计入上一周统计）

详细接口参数与坑见 references/api.md。

产物示例

dist/
├── 2026年07月抖音月度数据统计.csv    ← 统计周期,播放量,主页访问,...,回访粉丝量,总粉丝量
├── 2026年07月抖音单篇数据统计.csv    ← 标题,封面,发布时间,视频时长,播放,...,最大流量来源,搜索关键词
└── 2026年07月单篇封面/
    ├── 20260701_120000_7657107376989933000.jpg
    └── ...