00 · FLOW
完整流程总览（与 catclaw 1:1）
这是用户点击「启动探索」按钮后，TaskRunner 实际执行的步骤。代码源自 web/server/tiktok/collectors/scout-collector.ts。
1
打开 tiktok.com/live
在 Electron 隐藏 BrowserWindow 中加载 https://www.tiktok.com/live，等待首页加载完成。scout-collector.ts:571-605
2
点击第一个直播间卡片，进入 LIVE 房间
选择器扫描：a[href*="/@"][href*="/live"]、[data-e2e="live-card"] a 等。点击后等待 6 秒页面加载。
3
5 策略提取 username
① URL regex /@([^/?\s#]+)/ ② DOM data-e2e（live-username/user-card-nickname）③ header 区 /@username 链接 ④ SIGI_STATE / __NEXT_DATA__（Next.js 内部状态）⑤ document.title。scout-collector.ts:149-263
⚠ 失败处理：10 次连续失败 → 重回 /live 首页；2 次同主播 → swipe 卡住，重置
4
WebSocket 连接 LiveMonitor
调用 liveMonitor.connectRoom(username) 建立 tiktok-live-connector WS，捕获 gift / chat / member 事件流。scout-collector.ts:354-361
5
停留 30-60 秒（随机），并行录制视频
用 MediaRecorder 捕取 <video> 元素 captureStream() 录制 WebM，最多 15 秒。scout-collector.ts:368
6
ffmpeg 转码 WebM → MP4
调用 ffmpeg -i input.webm -c:v libx264 -preset ultrafast output.mp4。scout-collector.ts:23-62
7
截屏备份
同时调用 BrowserWindow.capturePage() 备份一帧静态图（万一视频转码失败，AI 分析有 fallback）。scout-collector.ts:390-401
8
读取 live_events 数据 + 计算指标
从 SQLite 查询该房间停留期间所有事件（最多 500 条）。计算：观众数 start/end/peak、点赞总数 / 增量、礼物总数 / 总价值 / 分类、弹幕样本（后 30 条）、高光段算法（5 秒桶化 + 权重 gift=3 / chat=2 / 其他=1，取 top 10）。scout-collector.ts:404-431, 118-143
9
Qwen Vision 14 维度分析
主模型 qwen3.6-plus，fallback qwen-vl-max。视频优先，截屏兜底。返回 14 维度结构化 JSON。qwen-vision.ts · DASHSCOPE_API_KEY
10
持久化到 scout_sessions 表
30+ 字段一行：room_id / username / 观众/点赞/礼物指标 / 14 维 AI 字段 / 视频路径 / 截屏路径 / 弹幕样本 / 高光段。scout-collector.ts:461-501
11
获取主播档案（导航到 /@username 页）
解析 nickname / followers / following / likes / bio / avatar_url，upsert 到 broadcasters 表。scout-collector.ts:503-520
12
循环：滑到下一个直播间，重复步骤 3-11
跳过逻辑：已采过的 / skipStreamers 列表 / 连续 3 个已存在 → 重回 /live
13
采完默认 30 个后 → 一次性打开 Backstage 批量邀约
导航 https://live-backstage.tiktok.com/portal/anchor/relation → 30 个 batch → 填 textarea → 点下一步 → 解析返回表格 → 更新 invite_status。backstage-collector.ts:39-198
✓ 旧逻辑（每 30 个就开窗口频繁切换）→ 新逻辑（采完一次性处理 ONE-SHOT），用户体验大幅改善。
01 · TASK CONTROL
启动 / 停止任务面板
触发方式：手动启动 TaskRunner 任务（非定时 cron）。默认单次采集 30 位（DEFAULT_SCOUT_MAX_COUNT = 30）。可暂停 / 重启 / 配置 skipStreamers。
Pawcast · Explorer · Task Controlv0.1.0
探索任务
当前任务 #task_2026_47
RUNNING · 已 12 / 30
正在分析 · @niko_devu
N
niko_devu
抽帧 12/30 · Qwen Vision 评分中...
启动新任务
任务类型
采集上限 maxCount
skipStreamers（已采过的，跳过）
自动从 scout_sessions 表读取所有已采主播 · 当前 248 位
完成后自动 Backstage 邀约 (autoInvite)
采完 30 个 → 一次性打开 Backstage 批量发邀约
本月成本
Qwen Vision
¥17.36
DASHSCOPE 调用 248 次
¥0.07 / 主播
历史任务
#task_47 · 当前running
#task_46 · 04-2930/30 ✓
#task_45 · 04-2530/30 ✓
①当前任务卡4 个进度数字（已采集 / 已跳过 / 失败 / Feed 重置）。Feed 重置 = 卡住 / 重复主播过多 → 重回 /live 首页继续。
②正在分析实时显示当前正在 Qwen 分析的主播 + 进度（抽帧 / 评分中）。让用户看到系统在工作。
③scout_then_backstage推荐的复合模式：scout 采完 30 个 → 立即打开 backstage 批量邀约。一站式。
④skipStreamers自动跳过已采过的主播。每次新任务从 DB 自动加载列表，无需手动维护。
实现说明TaskRunner 在 worker 进程跑，主进程通过 IPC progress event 推到 UI。stop 走 runtime.stopRequested = true flag，下个循环检测到自动退出。
失败检测10 次连续无法提取 username → 重回 /live；2 次同主播卡住 → 视为 swipe 失败重置。这俩阈值在 catclaw 已被实战验证。
02 · POOL
探索池主页 · 主播卡片
所有 scout_sessions 的卡片瀑布流。卡片显示 14 维度核心评分 + AI 推荐结果（强烈推荐/推荐/一般/不推荐）+ 邀约状态。
Pawcast · Explorer · Poolv0.1.0
主播池 · 248
本月新增 47 位
全部 · 248
强烈推荐 · 18
推荐 · 24
一般 · 142
不推荐 · 64
未发邀约 · 198
已发邀约 · 28
可邀约 · 12
地区不匹配 · 38
Mira K.
24.8k
@mira.k_official
娱乐
跳舞
室内
互动 92
质量 88
参与 very_high
停留 3:24
AI: 上镜稳，节奏感强，编排有原创性，画质好。粉丝增长 18% / 7d。
Yuki S.8.4k
@yuki.spring
游戏FPSCosplay
互动 87质量 82参与 high停留 2:48
AI: 镜头互动多，弹幕回应及时，观众停留高。
Ace142.1k
@aceofthestage
音乐说唱
互动 84质量 90参与 very_high礼物 ¥2.4K
AI: 礼物转化高，缺团队配合。
Lila3.6k
@lila.world
生活英
互动 62质量 58
⚠ Backstage 返回"地区不匹配" - 暂不可邀约
显示 4 / 共 248 位 · 滚动加载更多
①四种 AI 推荐强烈推荐（绿）/ 推荐（紫）/ 一般（黄）/ 不推荐（灰），来自 Qwen Vision 14 维分析的 recommendation 字段。
②邀约状态来自 Backstage 真实返回：可邀约 / 已邀约 / 已关注 / 邀请中 / 地区不匹配 / 不可邀约 / 已拒绝 / 待确认。这些状态从 backstage-collector.ts 解析的真实表格 cell。
③14 维度展示卡片顶部展示「性别 · 年龄 · 语言 」（缩写）+ 「分类 + 子类 + 场景」标签。详情看抽屉。
④4 项核心评分互动评分 / 内容质量 / 参与度 / 停留时长。互动 + 质量是 0-100 分，参与度是 5 档 enum，停留是分钟。
⑤地区不匹配卡片变灰 + 警告横条，避免重复尝试发邀约（Backstage 已确认不可发）。
实现说明使用 react-window 虚拟滚动，248+ 卡片不卡顿。每张卡片 12 字段读 SQLite + 抽屉详情按需加载。
03 · DETAIL DRAWER
详情抽屉 · 14 维度 + 视频 + 高光段
点击卡片右侧滑入 480px 宽抽屉。包含：14 维度展示（不是 7 维）+ AI 评语全文 + 录制视频回放（mp4 / screenshot fallback）+ 弹幕样本 + 高光段 timeline。所有数据来自 scout_sessions 表的 30+ 字段。
主播详情 · @mira.k_official
×
M
Mira K.
强烈推荐
@mira.k_official · 24.8k 粉丝 · 韩国
基础属性 (Qwen Vision)
ethnicityasian
genderfemale
skinTonelight
ageRange26-35
appearance长发，穿黑色 T 恤，戴耳机
language韩
直播内容
liveCategory娱乐
liveSubCategory跳舞
liveScene室内
评分（核心决策维度）
interactivityScore92 / 100
audienceEngagementvery_high
recommendation强烈推荐
AI Summary
"上镜稳定，节奏感强，编排有原创性。互动密度高，弹幕回应及时。画质和灯光均佳，符合中型团播标准。粉丝增长 18% / 7d。建议立即邀约。"
录制内容（4 月 28 日）
▶
video_path~/...frames/r1234.mp4
stay_duration42 秒
peak_viewers1,287
total_likes+8.4k
gift_value¥126
chat_count68
高光段 · 5 秒桶化算法（top 3）
00:18-00:23 · 礼物 ×4 + 弹幕 ×8
权重 22
00:31-00:36 · 弹幕 ×12 + 关注 ×3
权重 18
00:08-00:13 · 礼物 ×2 + 弹幕 ×6
权重 15
弹幕样本（最后 30 条）
@taro_pop: wow 太好看了！
@silent_fan: 跳得真稳
@kawaii_jin: 求歌曲名
@uchan_: 关注了！
Backstage 邀约状态
可邀约
尚未发出
从 Backstage 表格解析：地区匹配 ✓ · 未关注 · 未发过邀约
①14 维度分 4 组① 基础属性（民族/性别/肤色/年龄/外貌/语言）② 直播内容（分类/子类/场景/标签）③ 评分（互动/质量/参与/推荐）④ AI Summary。
②录制视频实际是 mp4 文件，存在 ~/.pawcast/scout-frames/。点击播放可看回放。如果转码失败，会用 screenshot 兜底。
③高光段 top 3来自 5 秒桶化算法（gift=3 / chat=2 / 其他=1 权重）。看高光直接定位到精彩时段。
④弹幕样本采集期间最后 30 条弹幕。能看出主播的观众调性 + 主播是否回应（catclaw scout-collector.ts:428-431）。
⑤Backstage 状态从 Backstage 表格解析的 6 种状态之一（可邀约 / 已邀约 / 已关注 / 邀请中 / 地区不匹配 / 不可邀约）。catclaw 实战代码。
抽屉数据加载scout_sessions 30+ 字段一次查回；视频路径用 file:// 协议本地播放；不依赖网络。
04 · BACKSTAGE
Backstage 批量邀约（一次性 ONE-SHOT）
采完 30 个主播后一次性打开 Backstage 窗口，filledtextarea 30 个 username → 点击「下一步」→ 解析返回表格 → 更新每个主播的 invite_status。backstage-collector.ts:39-198
Backstage 邀约 · 第 2 / 1 批次
×
本批 30 个主播
已成功 22
地区不匹配 6
失败 2
速率：5-10s/条
01
M
@mira.k_official
可邀约
已发送
02
Y
@yuki.spring
已邀约
3 天前
03
A
@aceofthestage
可邀约
已发送
04
L
@lila.world
地区不匹配
不发送
05
N
@niko_devu
已关注
已发送
06
H
@hana.live
邀请中
已发送
...
还有 24 个主播
实施细节：
① Playwright/bridge.executeJS 在 Backstage 网页填充 textarea（用 native HTMLTextAreaElement.prototype.value setter + input/change 事件，触发 React 监听）
② 点击"下一步"等待 3 秒，扫描结果表格 table tbody tr
③ matchBackstageResult() 模糊匹配 username（catclaw backstage-collector.ts:25-37）
④ 批次间 5-10 秒延迟，避免风控
批次大小 30BATCH_SIZE = 30 是 catclaw 实战经验值，太小效率低，太大风控易触发。
6 种状态完整解析可邀约 / 已邀约 / 已关注 / 邀请中 / 地区不匹配 / 不可邀约。每个 row 自动落库到 scout_sessions.invite_status。
地区不匹配处理这条 catclaw 没发邀约（即使列在 batch 里），TikTok Backstage 自己跳过不算速率。下次新任务自动从 skipStreamers 排除。
关键 Hackfilling textarea 必须用 Object.getOwnPropertyDescriptor(HTMLTextAreaElement.prototype, 'value').set 走 native setter，否则 React 不会感知 value 变化（catclaw 实战踩过坑）。
速率控制批次间 5-10 秒随机延迟。每次任务最多 1-3 个批次（30-90 个主播），单次 5-15 分钟完成。