specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/platforms/tiktok/web/im.js

@@ -0,0 +1,133 @@
+import { SpecificAIError } from '../../../core/errors.js';
+import { md5Hex } from '../../../core/hash.js';
+import { quote } from '../../../core/py.js';
+import * as rand from '../../../core/rand.js';
+import * as api from './api.js';
+import { ORIGIN } from './profile.js';
+import { imConversationRequest, imOuterRequest, imSendBody, imSendFrame, imUserInitRequest } from './wire.js';
+import { frontierSign } from './jsrun.js';
+/**
+ * 私信（上游 api/tiktok_web.py 的 IM 部分）。
+ *
+ * 上游要求浏览器会话里的 im_headers（32 个键的有序 map）、im_sequence_id、im_config_id 等运行时字段，缺了就拒绝。
+ * specific-ai 优先用会话 JSON 里的 browser_metrics；没有时 im_headers 按与 query 相同的浏览器画像补齐，
+ * sequence_id 从 10000 起递增，config_id 缺省时不发（与上游 `None` 时不写字段一致）。
+ */
+export const IM_HEADER_KEYS = [
+    'aid', 'app_name', 'channel', 'device_platform', 'device_id', 'region', 'priority_region', 'os', 'referer', 'root_referer', 'cookie_enabled',
+    'screen_width', 'screen_height', 'browser_language', 'browser_platform', 'browser_name', 'browser_version', 'browser_online', 'verifyFp',
+    'app_language', 'webcast_language', 'tz_name', 'is_page_visible', 'focus_state', 'is_fullscreen', 'history_len', 'user_is_login',
+    'data_collection_enabled', 'from_appID', 'locale', 'user_agent', 'Web-Sdk-Ms-Token',
+];
+/** Request.headers 的有序 map（上游 _im_header_map）。 */
+export function imHeaders(t) {
+    const source = t.metrics.im_headers;
+    if (source && typeof source === 'object') {
+        const missing = IM_HEADER_KEYS.filter((k) => !(k in source));
+        if (missing.length)
+            throw new SpecificAIError('ERROR', `会话里的 im_headers 缺少字段：${missing.join(', ')}`);
+        return IM_HEADER_KEYS.map((k) => [k, String(source[k])]);
+    }
+    const values = {
+        aid: '1988',
+        app_name: 'tiktok_web',
+        channel: 'tiktok_web',
+        device_platform: 'web_pc',
+        device_id: t.deviceId,
+        region: t.region,
+        priority_region: t.priorityRegion,
+        os: 'windows',
+        referer: api.MESSAGES_PAGE,
+        root_referer: api.MESSAGES_PAGE,
+        cookie_enabled: 'true',
+        screen_width: '2560',
+        screen_height: '1440',
+        browser_language: 'zh-CN',
+        browser_platform: 'Win32',
+        browser_name: 'Mozilla',
+        browser_version: t.ua.split('Mozilla/').slice(1).join('Mozilla/'),
+        browser_online: 'true',
+        verifyFp: t.verifyFp,
+        app_language: 'zh-Hans',
+        webcast_language: 'zh-Hans',
+        tz_name: 'Asia/Shanghai',
+        is_page_visible: 'true',
+        focus_state: 'true',
+        is_fullscreen: 'false',
+        history_len: '4',
+        user_is_login: 'true',
+        data_collection_enabled: 'true',
+        from_appID: '1988',
+        locale: 'zh-Hans',
+        user_agent: t.ua,
+        'Web-Sdk-Ms-Token': t.msToken,
+    };
+    return IM_HEADER_KEYS.map((k) => [k, values[k]]);
+}
+/** 下一个 sequence_id：会话里给了就从它开始，之后每次 +1（存在凭证里）。 */
+function nextSequence(t, key) {
+    const extra = t.ctx.credential.extra;
+    const stored = Number(extra[key] ?? t.metrics[key] ?? 10000);
+    extra[key] = stored + 1;
+    return stored;
+}
+/** 私信 HTTP 拉取请求的公共外层字段。 */
+export function envelope(t) {
+    const config = t.metrics.im_config_id;
+    return { sequenceId: nextSequence(t, 'im_sequence_id'), deviceId: t.deviceId, headers: imHeaders(t), configId: config == null ? null : Number(config) };
+}
+/** cmd 203：私信页初次拉取（会话与最近消息）。翻页时 cursor 用上一页回包的 next_cursor。 */
+export async function pullInit(t, cursor = 0) {
+    return api.postImProtobuf(t, '/v2/message/get_by_user_init', imUserInitRequest(cursor, envelope(t)));
+}
+/** cmd 301：一个会话的消息。 */
+export async function pullConversation(t, c) {
+    const raw = imConversationRequest({ conversationId: c.conversationId, shortId: c.shortId, type: c.type, anchorIndex: c.anchorIndex ?? '0', direction: c.direction ?? 1, limit: c.limit ?? 50 }, envelope(t));
+    return api.postImProtobuf(t, '/v1/message/get_by_conversation', raw);
+}
+export function convCache(t) {
+    return (t.ctx.credential.extra.im_conversations ??= {});
+}
+// ---------------------------------------------------------------- WebSocket
+/** WS 的 access_key：md5("9" + app_key + wid + 盐)，wid 来自 privacy config（上游 build_im_access_key）。 */
+export async function imWsUrl(t) {
+    let wid = String(t.metrics.im_wid ?? '');
+    if (!wid) {
+        const body = await api.cookiePrivacyConfig(t);
+        wid = String(body?.body?.consent?.wid ?? '');
+        if (!wid)
+            throw new SpecificAIError('UPSTREAM', 'TikTok privacy config 缺少 body.consent.wid');
+    }
+    const accessKey = md5Hex(`9e1bd35ec9db7b8d846de66ed140b1ad9${wid}f8a69f1719916z`);
+    const ttwid = t.ttwid;
+    if (!ttwid)
+        throw new SpecificAIError('AUTH_REQUIRED', '私信 WebSocket 缺少 ttwid cookie', { hint: 'specific-ai tiktok auth login' });
+    return (`wss://im-ws-${t.region.toLowerCase()}.tiktok.com/ws/v2?device_platform=web&version_code=fws_1.0.0&access_key=${accessKey}` +
+        `&fpid=9&aid=1459&ttwid=${quote(ttwid, '|~-._')}&xsack=1&xaack=1&xsqos=0`);
+}
+/** cmd 100 的完整帧：Request 里带现签的 ticket-guard，帧头带 frontierSign(md5(Request))（上游 send_im_message）。 */
+export async function buildSendFrame(t, c) {
+    const normal = imHeaders(t);
+    const guard = t.ticketGuard('/ws/v2');
+    const requestHeaders = [...normal];
+    for (const [k, v] of Object.entries(guard)) {
+        const i = requestHeaders.findIndex(([key]) => key === k);
+        if (i >= 0)
+            requestHeaders[i] = [k, v];
+        else
+            requestHeaders.push([k, v]);
+    }
+    const clientMessageId = rand.uuid4();
+    const body = imSendBody({ conversationId: c.conversationId, shortId: c.shortId, type: c.type, text: c.text, clientMessageId });
+    const sequenceId = nextSequence(t, 'im_ws_sequence_id');
+    const request = imOuterRequest(100, body, { sequenceId, deviceId: t.deviceId, devicePlatform: 'web', headers: requestHeaders, authType: 1 });
+    const marker = await frontierSign({
+        cookie: t.device.document_cookie || t.cookieStr,
+        userAgent: t.ua,
+        referer: String(t.metrics.im_page || `${ORIGIN}/messages`),
+        metrics: t.metrics,
+        stub: md5Hex(request),
+    });
+    const frame = imSendFrame({ request, sequenceId, logId: rand.now(), xBogus: marker, frameHeaders: normal });
+    return { frame, request, body, clientMessageId, sequenceId };
+}

package/dist/platforms/tiktok/web/jsrun.js

@@ -0,0 +1,126 @@
+import { spawn } from 'node:child_process';
+import { join } from 'node:path';
+import { SpecificAIError } from '../../../core/errors.js';
+import { PACKAGE_ROOT, staticFile } from '../../../core/paths.js';
+import * as rand from '../../../core/rand.js';
+/**
+ * 上游的两个签名运行器（AGENTS 7.4 的子进程退路）：
+ * - static/tiktok/signing/env/sign.js：WebMssdk 的 frontierSign（直播 / 私信 WebSocket 的 16 位 X-Bogus）；
+ * - static/tiktok/shop_bsid/sign.js：TikTok Shop 的 OEC Lucifer BSID。
+ *
+ * 两者都改写进程级全局（global.window、Function.prototype.toString、隐藏 process 等），放不进 node:vm，
+ * 所以和上游一样每次起一个 node 子进程，按包内路径运行原样复制的 JS。
+ *
+ * 确定性模式（对拍）下预加载 scripts/golden/tiktok/node_determinism.cjs，与上游对拍时用的是同一个文件。
+ */
+async function runNode(script, input, env = {}) {
+    const deterministic = rand.isDeterministic();
+    const extra = deterministic
+        ? {
+            NODE_OPTIONS: `--require "${join(PACKAGE_ROOT, 'scripts', 'golden', 'tiktok', 'node_determinism.cjs').replaceAll('\\', '/')}"`,
+            SPECIFIC_AI_GOLDEN_SEED: String(rand.DEFAULT_SEED),
+            SPECIFIC_AI_GOLDEN_NOW: String(rand.now()),
+        }
+        : { NODE_OPTIONS: '' };
+    return new Promise((resolve, reject) => {
+        const child = spawn(process.execPath, [script], {
+            env: { ...process.env, ...extra, ...env },
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        const out = [];
+        const err = [];
+        const timer = setTimeout(() => child.kill(), 30_000);
+        child.stdout.on('data', (d) => out.push(d));
+        child.stderr.on('data', (d) => err.push(d));
+        child.on('error', (e) => {
+            clearTimeout(timer);
+            reject(new SpecificAIError('ERROR', `签名进程启动失败：${e.message}`));
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const stdout = Buffer.concat(out).toString('utf8');
+            if (code !== 0 && !stdout.trim()) {
+                // 运行器的 stderr 可能带着 cookie，只取最后一行错误类型
+                const reason = Buffer.concat(err).toString('utf8').trim().split(/\r?\n/).reverse().find((l) => /(Error|error):|is required|failed|length/.test(l)) ?? '';
+                reject(new SpecificAIError('ERROR', `签名进程失败${reason ? `：${reason.slice(0, 200)}` : ''}`));
+            }
+            else
+                resolve(stdout);
+        });
+        child.stdin.end(input);
+    });
+}
+export async function frontierSign(o) {
+    const request = { mode: 'frontier_sign', url: o.referer, cookie: o.cookie, user_agent: o.userAgent, referer: o.referer, metrics: o.metrics ?? {}, headers: {} };
+    if (o.stub != null) {
+        if (!/^[0-9a-f]{32}$/.test(o.stub))
+            throw new SpecificAIError('ERROR', 'IM X-MS-STUB 必须为 32 位小写 MD5');
+        request.stub = o.stub;
+    }
+    const stdout = await runNode(staticFile('tiktok', 'signing/env/sign.js'), JSON.stringify(request) + '\n');
+    const replies = stdout.split(/\r?\n/).filter((l) => l.startsWith('{"ok":'));
+    let result = {};
+    try {
+        result = replies.length ? JSON.parse(replies[replies.length - 1]) : {};
+    }
+    catch { }
+    const marker = result?.result?.values?.['X-Bogus'];
+    if (!result.ok || typeof marker !== 'string' || marker.length !== 16) {
+        throw new SpecificAIError('ERROR', `本地 frontierSign 未产生长度 16 的 X-Bogus${result.error ? `：${String(result.error).slice(0, 200)}` : ''}`);
+    }
+    return marker;
+}
+// ---------------------------------------------------------------- Shop BSID（signing/shop_bsid.py ShopBSIDSigner）
+export const SHOP_BSID_LENGTH = 382;
+const BROWSER_MS_TOKEN_LENGTHS = [144, 152];
+export async function shopSign(o) {
+    const oec = /(?:^|;\s*)oec_lucifer=([^;]+)/.exec(o.cookie)?.[1];
+    if (!oec || !/^[0-9a-fA-F]{160}$/.test(oec)) {
+        throw new SpecificAIError('AUTH_REQUIRED', '当前 Cookie 缺少浏览器生成的 160 位 oec_lucifer（在 shop.tiktok.com 打开任一商品页后重新导出 Cookie）', {
+            hint: 'specific-ai tiktok auth login --cookie @tiktok-session.json',
+        });
+    }
+    const msToken = [...o.cookie.matchAll(/(?:^|;\s*)msToken=([^;]+)/g)].map((m) => decodeURIComponent(m[1])).find((v) => BROWSER_MS_TOKEN_LENGTHS.includes(v.length)) ?? '';
+    if (!/^[0-9A-Za-z_-]+={0,2}$/.test(msToken)) {
+        throw new SpecificAIError('AUTH_REQUIRED', '当前 Cookie 缺少 Shop 请求使用的 144/152 位 msToken（在 shop.tiktok.com 打开商品页后重新导出 Cookie）', {
+            hint: 'specific-ai tiktok auth login --cookie @tiktok-session.json',
+        });
+    }
+    if (!o.userAgent)
+        throw new SpecificAIError('ERROR', 'Shop X-Bogus 纯算需要完整 user-agent');
+    const sep = o.url.includes('?') ? '&' : '?';
+    // Chrome 的 pre-sign URL 里 base64 的 == 原样保留
+    const signingUrl = `${o.url}${sep}msToken=${encodeURIComponent(msToken).replace(/%3D/g, '=')}`;
+    const payload = {
+        url: signingUrl,
+        method: o.method.toUpperCase(),
+        headers: o.headers,
+        body: o.body,
+        cookie: o.cookie,
+        expected_length: SHOP_BSID_LENGTH,
+        expected_ms_token_length: msToken.length,
+        x_bogus: o.xBogus(msToken),
+    };
+    const stdout = await runNode(staticFile('tiktok', 'shop_bsid/sign.js'), JSON.stringify(payload), { TIKTOK_BSID_QUIET: '1' });
+    let result;
+    try {
+        result = JSON.parse(stdout);
+    }
+    catch {
+        throw new SpecificAIError('ERROR', 'Shop BSID 运行器返回了非 JSON 数据');
+    }
+    const bsid = String(result.bsid ?? '');
+    if (bsid.length !== SHOP_BSID_LENGTH || !/^[0-9a-f]+$/.test(bsid) || String(result.length) !== String(SHOP_BSID_LENGTH)) {
+        throw new SpecificAIError('ERROR', 'Shop BSID 输出格式或长度与 Chrome 不一致');
+    }
+    return {
+        signed_url: String(result.signed_url ?? ''),
+        bsid,
+        length: SHOP_BSID_LENGTH,
+        pre_sign_lengths: result.pre_sign_lengths ?? {},
+        pre_sign_url_length: Number(result.pre_sign_url_length ?? 0),
+        pre_sign_order: result.pre_sign_order ?? [],
+        pre_sign_url: String(result.pre_sign_url ?? ''),
+    };
+}

package/dist/platforms/tiktok/web/normalize.js

@@ -0,0 +1,286 @@
+import * as n from '../../../core/normalize.js';
+import { jsonLoads } from '../../../core/py.js';
+import { ORIGIN, SHOP } from './profile.js';
+/** TikTok 原始对象 → 归一化类型（AGENTS 6.2）。 */
+export const userUrl = (uniqueId) => (uniqueId ? `${ORIGIN}/@${uniqueId}` : null);
+export const itemUrl = (uniqueId, id, photo = false) => `${ORIGIN}/@${uniqueId || '_'}/${photo ? 'photo' : 'video'}/${id}`;
+export const liveUrl = (uniqueId) => (uniqueId ? `${ORIGIN}/@${uniqueId}/live` : null);
+export const productUrl = (id) => `${SHOP}/view/product/${id}`;
+export function ref(id, name, uniqueId) {
+    return n.userRef({ id, name: name || uniqueId, url: userUrl(uniqueId) });
+}
+const first = (v) => (Array.isArray(v) ? n.url(v[0]) : n.url(v));
+/** 作品（itemStruct：视频页 hydration、搜索、推荐、主页列表都用这个结构）。 */
+export function item(v) {
+    const a = v.author ?? {};
+    const photo = Boolean(v.imagePost);
+    const s = { ...(v.stats ?? {}), ...(v.statsV2 ?? {}) };
+    return n.item({
+        id: n.id(v.id),
+        kind: photo ? 'image' : 'video',
+        url: itemUrl(a.uniqueId, v.id, photo),
+        title: n.str(v.imagePost?.title),
+        text: n.str(v.desc),
+        author: ref(a.id, a.nickname, a.uniqueId),
+        created_at: n.time(v.createTime),
+        cover: n.url(v.video?.cover || v.video?.originCover) ?? first(v.imagePost?.cover?.imageURL?.urlList),
+        media: itemMedia(v),
+        stats: {
+            views: n.count(s.playCount),
+            likes: n.count(s.diggCount),
+            comments: n.count(s.commentCount),
+            collects: n.count(s.collectCount),
+            shares: n.count(s.shareCount),
+        },
+        status: v.privateItem || v.secret ? 'private' : null,
+    }, v);
+}
+/**
+ * 可播放 / 下载的媒体：视频取 playAddr（同源 h264），图文取每张图。
+ * 背景音乐：图文总是附上（图文的声音只在音乐里）；视频只在 `withMusic` 时附上（`item media` 要，Item.media 与下载不要）。
+ */
+export function itemMedia(v, withMusic = false) {
+    const out = [];
+    const images = v.imagePost?.images ?? [];
+    if (images.length) {
+        images.forEach((img, i) => {
+            const url = first(img.imageURL?.urlList);
+            if (url)
+                out.push(n.media({ id: String(i + 1), type: 'image', url, width: n.count(img.imageWidth), height: n.count(img.imageHeight) }, img));
+        });
+    }
+    else if (v.video) {
+        const url = n.url(v.video.playAddr) ?? n.url(v.video.downloadAddr) ?? first(v.video.bitrateInfo?.[0]?.PlayAddr?.UrlList);
+        if (url) {
+            out.push(n.media({ id: n.id(v.video.id || v.id), type: 'video', url, width: n.count(v.video.width), height: n.count(v.video.height), duration: n.seconds(v.video.duration) }, v.video));
+        }
+    }
+    if ((images.length || withMusic) && v.music?.playUrl)
+        out.push(n.media({ id: n.id(v.music.id), type: 'audio', url: n.url(v.music.playUrl), duration: n.seconds(v.music.duration) }, v.music));
+    return out;
+}
+/** 用户（user-detail 的 userInfo，或列表里的 {user, stats}）。 */
+export function user(info) {
+    const u = info.user ?? info;
+    const s = { ...(info.stats ?? {}), ...(info.statsV2 ?? {}) };
+    return n.user({
+        id: n.id(u.id ?? u.uid),
+        name: n.str(u.nickname ?? u.nickName),
+        handle: n.str(u.uniqueId ?? u.unique_id),
+        avatar: n.url(u.avatarLarger ?? u.avatarMedium ?? u.avatarThumb),
+        url: userUrl(u.uniqueId ?? u.unique_id),
+        bio: n.str(u.signature),
+        stats: {
+            followers: n.count(s.followerCount),
+            following: n.count(s.followingCount),
+            items: n.count(s.videoCount),
+            likes: n.count(s.heartCount ?? s.heart),
+        },
+    }, info);
+}
+export function comment(v, itemId) {
+    const u = v.user ?? {};
+    const parent = v.reply_id && v.reply_id !== '0' ? n.id(v.reply_id) : null;
+    return n.comment({
+        id: n.id(v.cid),
+        item_id: n.id(v.aweme_id ?? itemId),
+        parent_id: parent,
+        author: ref(u.uid, u.nickname, u.unique_id),
+        text: String(v.text ?? ''),
+        created_at: n.time(v.create_time),
+        stats: { likes: n.count(v.digg_count), replies: n.count(v.reply_comment_total) },
+    }, v);
+}
+/** 商品评价（Shop PDP 的 product_reviews 项）。 */
+export function review(v, productId) {
+    return n.comment({
+        id: n.id(v.review_id ?? v.id),
+        item_id: productId,
+        author: n.userRef({ id: v.review_user?.user_id ?? v.user_id ?? v.review_user?.name, name: v.review_user?.name ?? v.user_name }),
+        text: String(v.review_text ?? v.display_text ?? v.text ?? ''),
+        created_at: n.time(v.review_timestamp ?? v.review_time ?? v.create_time),
+        stats: { likes: n.count(v.like_count ?? v.helpful_count), replies: null },
+    }, v);
+}
+/** 商品（Shop PDP SSR 的 product_info.component_data）。 */
+export function product(d) {
+    const p = d.product_info?.product_model ?? {};
+    const promo = d.product_info?.promotion_model ?? d.promotion_model ?? {};
+    const seller = d.product_info?.seller_model ?? d.seller_model ?? d.shop_info ?? {};
+    const price = promo.promotion_product_price ?? promo.min_price ?? p.min_price ?? {};
+    const images = p.images ?? [];
+    const amount = price.sale_price_decimal ?? price.real_price ?? price.min_sku_price ?? price.price_val;
+    return n.item({
+        id: n.id(p.product_id),
+        kind: 'goods',
+        url: productUrl(p.product_id),
+        title: n.str(p.name ?? p.title),
+        text: n.str(p.description_text ?? null),
+        author: n.userRef({ id: seller.seller_id ?? seller.shop_id, name: seller.name ?? seller.shop_name }),
+        cover: first(images[0]?.url_list),
+        media: images.flatMap((img, i) => {
+            const url = first(img.url_list);
+            return url ? [n.media({ id: String(i + 1), type: 'image', url, width: n.count(img.width), height: n.count(img.height) }, img)] : [];
+        }),
+        stats: { comments: n.count(d.review_info?.total_reviews ?? p.review_count), views: null, likes: null, collects: null, shares: null },
+        price: n.price(amount, price.currency ?? price.currency_name ?? 'USD'),
+        status: p.status === 1 || p.status == null ? 'on_sale' : 'off_shelf',
+    }, d);
+}
+export function folder(v) {
+    return n.folder({ id: n.id(v.collectionId), name: String(v.name ?? ''), count: n.count(v.total), url: v.userName ? `${ORIGIN}/@${v.userName}/collection/${encodeURIComponent(v.name ?? '')}-${v.collectionId}` : null }, v);
+}
+export function series(v) {
+    const id = n.id(v.mixId ?? v.id);
+    const creator = v.creator?.uniqueId;
+    return n.folder({ id, name: String(v.mixName ?? v.name ?? ''), count: n.count(v.videoCount), url: creator ? `${ORIGIN}/@${creator}/playlist/${encodeURIComponent(v.mixName ?? v.name ?? '')}-${id}` : null }, v);
+}
+// ---------------------------------------------------------------- 直播
+/** /api-live/user/room 的 data：user + liveRoom。status 2 为直播中。 */
+export function liveRoom(d) {
+    const u = d.user ?? {};
+    const r = d.liveRoom ?? {};
+    return n.live({
+        id: n.id(u.roomId || r.roomId),
+        url: liveUrl(u.uniqueId),
+        title: n.str(r.title),
+        status: Number(r.status ?? u.status) === 2 ? 'live' : 'offline',
+        host: ref(u.id, u.nickname, u.uniqueId),
+        cover: n.url(r.coverUrl),
+        stats: { viewers: n.count(r.liveRoomStats?.userCount) },
+    }, d);
+}
+/** webcast 接口的房间对象（feed、搜索）：snake_case。 */
+export function webcastRoom(r) {
+    const o = r.owner ?? {};
+    return n.live({
+        id: n.id(r.id_str ?? r.id),
+        url: liveUrl(o.display_id),
+        title: n.str(r.title),
+        status: Number(r.status) === 2 ? 'live' : 'offline',
+        host: ref(o.id_str ?? o.id, o.nickname, o.display_id),
+        cover: first(r.cover?.url_list),
+        stats: { viewers: n.count(r.user_count ?? r.stats?.total_user) },
+    }, r);
+}
+/** 画质的顺序：原画在前，纯音频（ao）在最后。 */
+const QUALITIES = ['origin', 'uhd', 'hd', 'sd', 'ld', 'md', 'ao'];
+const PROTOCOLS = ['flv', 'hls', 'cmaf', 'dash', 'lls'];
+function parseJson(v) {
+    if (typeof v !== 'string')
+        return v ?? null;
+    try {
+        return jsonLoads(v);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 拉流地址（上游没有解析）。两种来源：
+ * - `pull_data.stream_data`：JSON 串，`data.<画质>.main.{flv,hls,...}`，`sdk_params`（JSON 串）里有 resolution。
+ *   /api-live/user/room 在 `liveRoom.streamData`，webcast 房间对象在 `stream_url.live_core_sdk_data`；
+ * - webcast 房间对象的 `stream_url.flv_pull_url`（画质 → 地址）、`hls_pull_url_map`、`hls_pull_url`、`rtmp_pull_url`。
+ */
+export function liveStreams(source) {
+    const out = [];
+    const seen = new Set();
+    const push = (id, url, raw, size) => {
+        const u = n.url(url);
+        if (!u || seen.has(u))
+            return;
+        seen.add(u);
+        const [w, h] = /^(\d+)x(\d+)$/.exec(String(size ?? ''))?.slice(1) ?? [];
+        out.push(n.media({ id, type: id.startsWith('ao-') ? 'audio' : 'video', url: u, width: n.count(w), height: n.count(h) }, raw));
+    };
+    // 可能是 {pull_data}、{live_core_sdk_data}，也可能已经是 stream_data 本身（JSON 串或解析后的对象）
+    const pull = source?.pull_data ?? source?.live_core_sdk_data?.pull_data;
+    const data = parseJson(pull?.stream_data ?? (typeof source === 'string' || source?.data ? source : null))?.data;
+    if (data && typeof data === 'object') {
+        const keys = Object.keys(data).sort((a, b) => (QUALITIES.indexOf(a) + 1 || 99) - (QUALITIES.indexOf(b) + 1 || 99));
+        for (const q of keys) {
+            const main = data[q]?.main ?? {};
+            const size = parseJson(main.sdk_params)?.resolution;
+            for (const p of PROTOCOLS)
+                push(`${q}-${p}`, main[p], data[q], size);
+        }
+    }
+    for (const [q, url] of Object.entries(source?.flv_pull_url ?? {}))
+        push(`${q}-flv`, url, source);
+    for (const [q, url] of Object.entries(source?.hls_pull_url_map ?? {}))
+        push(`${q}-hls`, url, source);
+    push('default-hls', source?.hls_pull_url, source);
+    push('default-rtmp', source?.rtmp_pull_url, source);
+    return out;
+}
+export function gift(g) {
+    return n.gift({ id: n.id(g.id), name: String(g.name ?? ''), price: g.diamond_count != null ? { amount: Number(g.diamond_count), currency: 'TIKTOK_DIAMOND' } : null }, g);
+}
+export function rank(v, i) {
+    const u = v.user ?? {};
+    const r = ref(u.id_str ?? u.id, u.nickname, u.display_id);
+    return r ? n.rank({ rank: Number(v.rank ?? i + 1), user: r, score: n.count(v.score) }, v) : null;
+}
+function liveUserRef(u) {
+    return u && u.id !== '0' ? ref(u.id, u.nickname, u.display_id) : null;
+}
+/** 直播 protobuf 事件 → Event；只保留上游关心的 chat / like / gift。 */
+export function liveEvent(e) {
+    if (e.type === 'chat')
+        return n.event({ type: 'chat', user: liveUserRef(e.user), text: e.text ?? '' }, e);
+    if (e.type === 'like')
+        return n.event({ type: 'like', user: liveUserRef(e.user), text: e.count != null ? String(e.count) : null }, e);
+    if (e.type === 'gift')
+        return n.event({ type: 'gift', user: liveUserRef(e.user), gift: { name: e.gift?.name || String(e.gift_id ?? ''), count: e.combo_count || 1 } }, e);
+    return null;
+}
+export function categories(tabs) {
+    return tabs.flatMap((t) => [
+        n.category({ id: String(t.tab_type ?? t.tab_name), name: String(t.tab_name ?? t.tab_type) }, t),
+        ...(t.sub_tabs ?? []).map((s) => n.category({ id: String(s.tab_type ?? s.tab_name), name: String(s.tab_name ?? s.tab_type), parent_id: String(t.tab_type ?? t.tab_name) }, s)),
+    ]);
+}
+// ---------------------------------------------------------------- 通知与私信
+const NOTICE_TYPES = { 31: 'comment', 45: 'comment', 33: 'follow', 41: 'like', 60: 'like', 62: 'like', 43: 'mention', 44: 'mention' };
+/**
+ * 通知：动态（group 500，按 follow / digg / comment / at 分）与系统通知（group 661，`system` 为 true）。
+ * 模板通知（template_notice）的标题在 notice.title_template.title，正文在 notice.content；动态里的转发通知也用模板。
+ */
+export function notice(v, system = false) {
+    const template = v.template_notice?.notice;
+    const type = system ? 'system' : (NOTICE_TYPES[Number(v.type)] ?? (v.follow ? 'follow' : v.digg ? 'like' : v.comment ? 'comment' : v.at ? 'mention' : 'system'));
+    const body = v.follow ?? v.digg ?? v.comment ?? v.at ?? v.system ?? template ?? {};
+    const u = body.from_user?.[0] ?? body.user ?? body.from_user ?? v.from_user ?? {};
+    const aweme = body.aweme ?? body.comment?.aweme ?? null;
+    const text = template ? [template.title_template?.title, template.content].filter(Boolean).join('\n') : (body.content ?? body.comment?.text ?? body.title ?? v.content);
+    return n.notice({
+        id: n.id(v.nid_str ?? v.nid),
+        type,
+        user: ref(u.uid ?? u.id, u.nickname, u.unique_id ?? u.uniqueId),
+        target: aweme?.aweme_id ? { id: n.id(aweme.aweme_id), url: itemUrl(aweme.author?.unique_id, aweme.aweme_id) } : null,
+        text: n.str(text),
+        created_at: n.time(v.create_time),
+    }, v);
+}
+/** 私信文本消息：拉取回包（PulledMessage）和 WS 推送（ImTextMessage）的字段相同。 */
+export function imMessage(m) {
+    return n.message({
+        id: m.server_message_id,
+        conversation_id: m.conversation_id,
+        from: n.userRef({ id: m.sender }),
+        type: 'text',
+        text: m.text,
+        created_at: n.time(m.create_time),
+    }, m);
+}
+export function conversation(id, peer, last, raw) {
+    return n.conversation({
+        id,
+        peer: peer ? n.userRef({ id: peer }) : null,
+        last_message: last?.text ?? null,
+        updated_at: last ? n.time(last.create_time) : null,
+    }, raw);
+}
+export function poi(v) {
+    return n.poi({ id: n.id(v.poi_id ?? v.id), name: String(v.poi_name ?? v.name ?? ''), address: n.str(v.address ?? v.poi_address ?? v.city_name) }, v);
+}