specific-ai-cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,166 @@
+import * as n from '../../../core/normalize.js';
+import { noWaterImage } from './api.js';
+/**
+ * 小红书原始对象 → 归一化类型（AGENTS 6.2）。字段来源以上游 xhs_utils/data_util.py 的 handle_* 为准，
+ * 并兼容列表接口里的卡片形态（note_card / user 等）。
+ *
+ * 小红书的 url 必须带 xsec_token（AGENTS 4.8）：拿不到 token 的对象，url 为不带 token 的地址，
+ * 取详情前需要从带 token 的列表或分享链接进入。
+ */
+const WEB = 'https://www.xiaohongshu.com';
+export function noteUrl(id, token, source = 'pc_feed') {
+    return token ? `${WEB}/explore/${id}?xsec_token=${encodeURIComponent(String(token))}&xsec_source=${source}` : `${WEB}/explore/${id}`;
+}
+export function userUrl(id, token, source = 'pc_note') {
+    if (id == null || id === '')
+        return null;
+    return token ? `${WEB}/user/profile/${id}?xsec_token=${encodeURIComponent(String(token))}&xsec_source=${source}` : `${WEB}/user/profile/${id}`;
+}
+export function ref(u) {
+    if (!u)
+        return null;
+    const id = u.user_id ?? u.userId ?? u.id;
+    return n.userRef({ id, name: u.nickname ?? u.nick_name ?? u.name ?? u.userName, url: userUrl(id, u.xsec_token) });
+}
+const kindOf = (type) => (type === 'video' ? 'video' : 'image');
+/** 图片的地址：info_list 里取默认档（上游取 info_list[1]），否则 url_default / url。 */
+function imageUrl(img) {
+    const list = img?.info_list ?? [];
+    return n.url(list.find((x) => x.image_scene === 'WB_DFT')?.url ?? list[1]?.url ?? list[0]?.url ?? img?.url_default ?? img?.url);
+}
+/** 编码的优先顺序：新版 Web 把编码名混淆成 EF4（h264）/ EF5（h265）等，优先兼容性最好的 h264，其余编码排在后面。 */
+const CODECS = ['h264', 'EF4', 'h265', 'EF5'];
+const streamUrl = (s) => s?.master_url || s?.url || s?.backup_urls?.[0] || undefined;
+/** 上游 handle_note_info 的视频地址：按编码优先顺序取第一个有地址的流，否则 origin_video_key 拼 sns-video-bd。 */
+function videoMedia(v) {
+    const stream = v?.media?.stream ?? {};
+    const codecs = [...CODECS, ...Object.keys(stream).filter((k) => !CODECS.includes(k))];
+    const s = codecs.flatMap((c) => (Array.isArray(stream[c]) ? stream[c] : [])).find(streamUrl);
+    const url = streamUrl(s) ?? (v?.consumer?.origin_video_key ? `https://sns-video-bd.xhscdn.com/${v.consumer.origin_video_key}` : null);
+    if (!url)
+        return null;
+    return n.media({ id: n.idOrNull(v?.media?.video_id), type: 'video', url: n.url(url), width: s?.width ?? null, height: s?.height ?? null, duration: n.seconds(v?.capa?.duration ?? (s?.duration ? s.duration / 1000 : null)) }, v);
+}
+/** 笔记详情（feed 接口的 items[i]：{id, xsec_token?, note_card}）。 */
+export function note(v, token) {
+    const c = v.note_card ?? v;
+    const id = String(v.id ?? c.note_id);
+    const kind = kindOf(c.type);
+    const images = (c.image_list ?? []).map((img) => imageUrl(img)).filter(Boolean);
+    const media = [];
+    if (kind === 'video') {
+        const vm = videoMedia(c.video);
+        if (vm)
+            media.push(vm);
+    }
+    else
+        for (const [i, img] of (c.image_list ?? []).entries()) {
+            const url = imageUrl(img);
+            if (url)
+                media.push(n.media({ id: String(i), type: 'image', url, width: img.width ?? null, height: img.height ?? null }, img));
+        }
+    const i = c.interact_info ?? {};
+    return n.item({
+        id,
+        kind,
+        url: noteUrl(id, v.xsec_token ?? token),
+        title: n.str(c.title) ?? n.str(c.display_title),
+        text: n.str(c.desc),
+        author: ref(c.user),
+        created_at: n.time(c.time),
+        cover: n.url(c.cover?.url_default ?? c.cover?.url) ?? images[0] ?? null,
+        media,
+        stats: { likes: n.count(i.liked_count), comments: n.count(i.comment_count), collects: n.count(i.collected_count), shares: n.count(i.share_count) },
+    }, v);
+}
+/** 列表卡片：用户笔记 / 点赞 / 收藏（{note_id, xsec_token, display_title, cover, user, interact_info, type}）与搜索、推荐流（{id, xsec_token, note_card}）。 */
+export function card(v) {
+    const c = v.note_card ?? v;
+    const id = String(v.id || v.note_id || c.note_id || '');
+    const i = c.interact_info ?? {};
+    return n.item({
+        id,
+        kind: kindOf(c.type),
+        url: id ? noteUrl(id, v.xsec_token ?? c.xsec_token) : null,
+        title: n.str(c.display_title) ?? n.str(c.title),
+        author: ref(c.user),
+        created_at: n.time(c.time),
+        cover: n.url(c.cover?.url_default ?? c.cover?.url ?? c.cover?.info_list?.[0]?.url),
+        stats: { likes: n.count(i.liked_count), comments: n.count(i.comment_count), collects: n.count(i.collected_count), shares: n.count(i.shared_count ?? i.share_count) },
+    }, v);
+}
+/** 媒体地址（item media / download）：图片换成无水印 JPEG，视频用原始流。 */
+export function mediaOf(item) {
+    return item.media.map((m) => (m.type === 'image' && m.url ? { ...m, url: noWaterImage(m.url) } : m));
+}
+/** 用户资料（user/otherinfo：{basic_info, interactions, tags}）。 */
+export function profile(v, id, token) {
+    const b = v.basic_info ?? {};
+    const count = (type) => n.count((v.interactions ?? []).find((x) => x.type === type)?.count);
+    return n.user({
+        id,
+        name: n.str(b.nickname),
+        handle: n.str(b.red_id),
+        avatar: n.url(b.imageb ?? b.images),
+        url: userUrl(id, token),
+        bio: n.str(b.desc),
+        stats: { following: count('follows'), followers: count('fans'), likes: count('interaction') },
+    }, v);
+}
+/** user/me。 */
+export function me(v) {
+    return n.user({ id: String(v.user_id), name: n.str(v.nickname), handle: n.str(v.red_id), avatar: n.url(v.images ?? v.imageb), url: userUrl(v.user_id), bio: n.str(v.desc) }, v);
+}
+/** 搜索用户的结果项。 */
+export function searchUser(v) {
+    const id = String(v.id ?? v.user_id);
+    return n.user({
+        id,
+        name: n.str(v.name ?? v.nickname),
+        handle: n.str(v.red_id),
+        avatar: n.url(v.image ?? v.avatar),
+        url: userUrl(id, v.xsec_token, 'pc_search'),
+        bio: n.str(v.desc),
+        stats: { followers: n.count(v.fans), items: n.count(v.note_count) },
+    }, v);
+}
+/** 私信页的关注列表（users/following/all 的 follow_user_d_t_o_list[i]：{user_id, nick_name, ...}）。 */
+export function followingUser(v) {
+    const id = String(v.user_id ?? v.userId ?? v.id);
+    return n.user({
+        id,
+        name: n.str(v.nick_name ?? v.nickname ?? v.name),
+        handle: n.str(v.red_id),
+        avatar: n.url(v.avatar ?? v.image ?? v.images),
+        url: userUrl(id),
+        bio: n.str(v.desc),
+    }, v);
+}
+/** 评论（comment/page 的 comments[i] 与 sub_comments）。 */
+export function comment(v, itemId, parent = null) {
+    return n.comment({
+        id: String(v.id),
+        item_id: itemId,
+        parent_id: parent ?? n.idOrNull(v.target_comment?.id) ?? null,
+        author: ref(v.user_info),
+        text: String(v.content ?? ''),
+        created_at: n.time(v.create_time),
+        stats: { likes: n.count(v.like_count), replies: n.count(v.sub_comment_count) },
+    }, v);
+}
+/** 创作者中心「笔记管理」的笔记（审核状态：0 已发布；1/2 审核中；3 未通过；私密看 permission）。 */
+export function postedNote(v) {
+    const id = String(v.id ?? v.note_id);
+    const audit = Number(v.audit_status ?? v.status ?? 0);
+    const status = v.permission_code === 1 || v.permission_msg === '仅自己可见' ? 'private' : audit === 3 || audit === 4 ? 'rejected' : audit === 1 || audit === 2 ? 'reviewing' : 'published';
+    return n.item({
+        id,
+        kind: v.type === 'video' ? 'video' : 'image',
+        url: noteUrl(id, v.xsec_token),
+        title: n.str(v.display_title ?? v.title),
+        created_at: n.time(v.time ?? v.post_time),
+        cover: n.url(v.images_list?.[0]?.url ?? v.cover?.url),
+        stats: { views: n.count(v.view_count), likes: n.count(v.likes), comments: n.count(v.comments_count), collects: n.count(v.collected_count), shares: n.count(v.shared_count) },
+        status,
+    }, v);
+}

package/dist/platforms/xhs/web/profile.js

@@ -0,0 +1,127 @@
+import { readFileSync } from 'node:fs';
+import { CREATOR_JS, PC_JS } from './js.js';
+/**
+ * 小红书 web 端的常量：站点、设备画像（上游 xhs_pc/js/reference_profile.json、xhs_creator/js/reference_profile.json）
+ * 与浏览器实抓的请求头顺序（上游 xhs_pc/params.py、xhs_creator/params.py）。
+ */
+export const PC_REFERENCE = JSON.parse(readFileSync(PC_JS('reference_profile.json'), 'utf8'));
+export const CREATOR_REFERENCE = JSON.parse(readFileSync(CREATOR_JS('reference_profile.json'), 'utf8'));
+export const WEB = 'https://www.xiaohongshu.com';
+export const EDITH = 'https://edith.xiaohongshu.com';
+export const SO = 'https://so.xiaohongshu.com';
+export const LIVE = 'https://live-room.xiaohongshu.com';
+export const AS = 'https://as.xiaohongshu.com';
+export const SEM = 'https://pages.xiaohongshu.com';
+export const CREATOR = 'https://creator.xiaohongshu.com';
+export const CUSTOMER = 'https://customer.xiaohongshu.com';
+export const ROS_UPLOAD = 'https://ros-upload.xiaohongshu.com';
+export const PUSH_URL = 'wss://apppush-rws.xiaohongshu.com/rwp';
+export const COOKIE_DOMAIN = '.xiaohongshu.com';
+/** 上游 curl_cffi 用 chrome146（PC）/ chrome150（Creator）的 TLS 指纹；wreq-js 最新到 chrome_149。 */
+export const BROWSER = 'chrome_146';
+export const CREATOR_BROWSER = 'chrome_149';
+export const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/152.0.0.0 Safari/537.36';
+export const SEC_CH_UA = '"Not;A=Brand";v="8", "Chromium";v="152", "Google Chrome";v="152"';
+export const LOGIN_LANG = 'zh-CN,zh;q=0.9';
+export const BUSINESS_LANG = 'zh-CN,zh;q=0.9,en;q=0.8,zh-TW;q=0.7,ja;q=0.6';
+export const ACCEPT_ENCODING = 'gzip, deflate, br, zstd';
+export const XHR_ACCEPT = 'application/json, text/plain, */*';
+export const DOC_ACCEPT = 'text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7';
+// ---------------------------------------------------------------- 头顺序（PC）
+const o = (s) => s.split(' ');
+export const PC_ORDER = {
+    navigation: o('upgrade-insecure-requests user-agent sec-ch-ua sec-ch-ua-mobile sec-ch-ua-platform accept accept-encoding accept-language cookie priority sec-fetch-dest sec-fetch-mode sec-fetch-site sec-fetch-user'),
+    honeypot: o('sec-ch-ua-platform referer user-agent accept sec-ch-ua content-type sec-ch-ua-mobile accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    security: o('sec-ch-ua-platform referer sec-ch-ua sec-ch-ua-mobile x-t x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    sem: o('sec-ch-ua-platform referer sec-ch-ua sec-ch-ua-mobile x-t x-s-common user-agent accept x-s accept-encoding accept-language origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    signedPost: o('sec-ch-ua-platform referer sec-ch-ua x-xray-traceid sec-ch-ua-mobile x-t x-b3-traceid x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    signedGet: o('sec-ch-ua-platform referer sec-ch-ua x-xray-traceid sec-ch-ua-mobile x-t x-b3-traceid x-s-common user-agent accept x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    businessPost: o('referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    businessGet: o('referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    cdeviceGet: o('referer x-xray-traceid c_device_id x-t x-b3-traceid x-s-common user-agent accept x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    livePost: o('referer xy-common-params x-t x-s-common x-ratelimit-meta accept content-type x-s user-agent accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    liveGet: o('referer xy-common-params x-t x-s-common x-ratelimit-meta accept x-s user-agent accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    rapPost: o('referer x-xray-traceid x-t x-b3-traceid x-s-common x-rap-param accept content-type x-s user-agent accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    xyRapPost: o('xy-direction referer x-xray-traceid x-t x-b3-traceid x-s-common x-rap-param accept content-type x-s user-agent accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    rapGet: o('referer x-xray-traceid x-t x-b3-traceid x-s-common x-rap-param user-agent accept x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+};
+// ---------------------------------------------------------------- 头顺序（Creator）
+export const CREATOR_ORDER = {
+    navigation: PC_ORDER.navigation,
+    honeypot: o('referer user-agent accept content-type accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    redcaptcha: o('referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    security: o('authorization referer x-t x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    get: o('authorization referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept x-s accept-encoding accept-language cookie priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    post: o('authorization referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    casGet: o('authorization referer x-t x-s-common user-agent accept x-ratelimit-meta x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    casPost: o('authorization referer x-t x-s-common user-agent accept x-ratelimit-meta content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    casGetNoRate: o('authorization referer x-t x-s-common user-agent accept x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    casPostNoRate: o('authorization referer x-t x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie origin priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    loginUserInfo: o('authorization referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept content-type x-s accept-encoding accept-language cookie priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    noteManager: o('authorization referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept x-s accept-encoding accept-language cookie priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+    noteManagerUserInfo: o('authorization referer x-xray-traceid x-t x-b3-traceid x-s-common user-agent accept x-s accept-encoding accept-language cache-control cookie pragma priority sec-fetch-dest sec-fetch-mode sec-fetch-site'),
+};
+/**
+ * 上游 xhs_core/http.ordered_wire_headers：键转小写、补 accept-encoding 与 cookie，按实抓顺序排列；
+ * 顺序表外的键（optional 除外）直接报错，保证与浏览器的头集合一致。
+ */
+export function orderedHeaders(headers, order, cookies, options = {}) {
+    const values = {};
+    for (const [k, v] of Object.entries(headers))
+        if (k.toLowerCase() !== 'authority')
+            values[k.toLowerCase()] = v == null ? null : String(v);
+    values['accept-encoding'] ??= ACCEPT_ENCODING;
+    const cookie = cookieHeader(cookies);
+    if (cookie)
+        values.cookie = cookie;
+    else
+        delete values.cookie;
+    const optional = new Set(options.optional ?? []);
+    const missing = order.filter((k) => !(k in values) && !optional.has(k));
+    const unexpected = Object.keys(values).filter((k) => !order.includes(k) && !optional.has(k));
+    if (missing.length || ((options.strict ?? true) && unexpected.length)) {
+        throw new Error(`请求头与实抓顺序不符：missing=${missing.join(',')} unexpected=${unexpected.join(',')}`);
+    }
+    const out = order.filter((k) => k in values).map((k) => [k, values[k]]);
+    for (const k of Object.keys(values))
+        if (optional.has(k) && !order.includes(k))
+            out.push([k, values[k]]);
+    return out.filter((p) => p[1] != null);
+}
+export function cookieHeader(cookies) {
+    return cookies ? Object.entries(cookies).map(([k, v]) => `${k}=${v}`).join('; ') : '';
+}
+/** 导航请求的公共头（上游 get_common_headers）。 */
+export function navigationHeaders(site = 'none') {
+    return {
+        'upgrade-insecure-requests': '1',
+        'user-agent': UA,
+        'sec-ch-ua': SEC_CH_UA,
+        'sec-ch-ua-mobile': '?0',
+        'sec-ch-ua-platform': '"Windows"',
+        accept: DOC_ACCEPT,
+        'accept-language': LOGIN_LANG,
+        priority: 'u=0, i',
+        'sec-fetch-dest': 'document',
+        'sec-fetch-mode': 'navigate',
+        'sec-fetch-site': site,
+        'sec-fetch-user': '?1',
+    };
+}
+/** 在 after 之后插入一个头（上游 _insert_header_after / _insert_after）。 */
+export function insertAfter(headers, key, value, after) {
+    const out = {};
+    let inserted = false;
+    for (const [k, v] of Object.entries(headers)) {
+        if (k.toLowerCase() === key.toLowerCase())
+            continue;
+        out[k] = v;
+        if (k.toLowerCase() === after.toLowerCase()) {
+            out[key] = value;
+            inserted = true;
+        }
+    }
+    if (!inserted)
+        out[key] = value;
+    return out;
+}

package/dist/platforms/xhs/web/push.js

@@ -0,0 +1,361 @@
+import { constants, createPublicKey, publicEncrypt } from 'node:crypto';
+import { SpecificAIError } from '../../../core/errors.js';
+import { compactJson, jsonLoads } from '../../../core/py.js';
+import * as rand from '../../../core/rand.js';
+import { openSocket } from '../../../core/stream.js';
+import { celestialLt } from './api.js';
+import { PUSH_URL, UA, WEB } from './profile.js';
+/**
+ * 私信 / 直播间的 RWP 长连（上游 apis/xhs_live.py 的 XHSWebSocket 与 IM protobuf 编解码）。
+ * 帧是 JSON 信封 `{v, t, m, b}`；私信正文是 protobuf（ChatOneMessage），直播间事件是 base64 的 JSON。
+ */
+// ---------------------------------------------------------------- protobuf（上游 _pb_*，只用到 varint / length-delimited）
+function varint(v) {
+    let n = BigInt(v);
+    if (n < 0n)
+        throw new Error('protobuf varint 不能为负');
+    const out = [];
+    while (n > 0x7fn) {
+        out.push(Number(n & 0x7fn) | 0x80);
+        n >>= 7n;
+    }
+    out.push(Number(n));
+    return out;
+}
+const field = (num, wire, payload) => [...varint((num << 3) | wire), ...payload];
+const pbUint = (num, v) => field(num, 0, varint(v));
+const pbBool = (num, v) => field(num, 0, varint(v ? 1 : 0));
+const pbBytes = (num, b) => field(num, 2, [...varint(b.length), ...b]);
+const pbString = (num, s) => pbBytes(num, [...Buffer.from(s, 'utf8')]);
+function readVarint(d, o) {
+    let v = 0n;
+    let shift = 0n;
+    while (o < d.length) {
+        const b = d[o++];
+        v |= BigInt(b & 0x7f) << shift;
+        if (!(b & 0x80))
+            return [v, o];
+        shift += 7n;
+        if (shift >= 64n)
+            throw new Error('protobuf varint 无效');
+    }
+    throw new Error('protobuf varint 被截断');
+}
+function readFields(d) {
+    const out = new Map();
+    let o = 0;
+    while (o < d.length) {
+        const [tag, o1] = readVarint(d, o);
+        o = o1;
+        const num = Number(tag >> 3n);
+        const wire = Number(tag & 7n);
+        let v;
+        if (wire === 0)
+            [v, o] = readVarint(d, o);
+        else if (wire === 2) {
+            const [len, o2] = readVarint(d, o);
+            v = d.subarray(o2, o2 + Number(len));
+            o = o2 + Number(len);
+        }
+        else
+            throw new Error(`protobuf wire type ${wire} 不支持`);
+        const list = out.get(num);
+        if (list)
+            list.push(v);
+        else
+            out.set(num, [v]);
+    }
+    return out;
+}
+const last = (f, n) => f.get(n)?.at(-1);
+const text = (f, n) => {
+    const v = last(f, n);
+    return v instanceof Uint8Array ? Buffer.from(v).toString('utf8') : '';
+};
+const int = (f, n) => {
+    const v = last(f, n);
+    return typeof v === 'bigint' ? Number(v) : 0;
+};
+/**
+ * encode_im_chat_message：ChatSendMessage 包进 ChatOneMessage（type=1, field 9）。
+ * 上游的 _pb_* 不省略默认值：token / nickname / ref_id 为空串、group_chat 为 false 也照写；command 为 None 时不写。
+ */
+export function encodeChatMessage(m) {
+    const send = [
+        ...pbString(1, m.mid),
+        ...pbUint(2, m.ts),
+        ...pbString(3, ''),
+        ...pbString(4, m.sender),
+        ...pbString(5, m.receiver),
+        ...pbString(6, m.content),
+        ...pbUint(7, m.contentType),
+        ...pbString(8, ''),
+        ...pbBool(9, false),
+        ...pbString(11, ''),
+        ...pbUint(12, 1),
+    ];
+    return Uint8Array.from([...pbUint(1, 1), ...pbBytes(9, send)]);
+}
+/** decode_im_one_message：field 4 是收到的私信，field 5 是发送回执。 */
+export function decodeChat(data) {
+    const outer = readFields(data);
+    const out = {};
+    const m = last(outer, 4);
+    if (m instanceof Uint8Array) {
+        const f = readFields(m);
+        const payload = text(f, 5);
+        let json = null;
+        try {
+            json = jsonLoads(payload);
+        }
+        catch { }
+        out.message = { mid: text(f, 1), messageId: text(f, 2), ts: int(f, 3), payload, json };
+    }
+    const a = last(outer, 5);
+    if (a instanceof Uint8Array) {
+        const f = readFields(a);
+        out.ack = { mid: text(f, 1), messageId: text(f, 2), ts: int(f, 3), code: int(f, 5), msg: text(f, 6) };
+    }
+    return out;
+}
+/** 私信正文常嵌套多层 JSON（上游 demo._im_text）：剥出最内层文本。 */
+export function innerText(body) {
+    let content = body;
+    for (let i = 0; i < 6; i++) {
+        if (content && typeof content === 'object' && 'content' in content) {
+            content = content.content;
+            continue;
+        }
+        if (typeof content === 'string') {
+            try {
+                const parsed = jsonLoads(content);
+                if (parsed && typeof parsed === 'object') {
+                    content = parsed;
+                    continue;
+                }
+            }
+            catch { }
+        }
+        break;
+    }
+    return typeof content === 'string' ? content : JSON.stringify(content);
+}
+// ---------------------------------------------------------------- RSA 短链（HTTP 兜底发私信）
+const RSA_N = 'd321555d67813eace010dc27e72ab14876a9b671c7d58d3c9c2064cd60f7e9f79ad3799657b35a1b7654d82725408a71549d5ade11e74bbf1ec39b549ed32116affd4f6b03f2c9c44d91f84157b159a8a225150916e2716cc82dc8fd62385e5a01c83b784c139462a1dd45d47d96ebb4f5068c42b3de8590123a03565a9e5aed';
+/** rsa_encrypt_short_link_payload：RSAES-PKCS1-v1_5 按 117 字节分块，结果按 latin-1 转成字符串。 */
+export function rsaShortLink(payload) {
+    const pub = createPublicKey({ key: { kty: 'RSA', n: Buffer.from(RSA_N, 'hex').toString('base64url'), e: 'AQAB' }, format: 'jwk' });
+    const key = { key: pub, padding: constants.RSA_PKCS1_PADDING };
+    const chunks = [];
+    for (let o = 0; o < payload.length; o += 117)
+        chunks.push(publicEncrypt(key, payload.subarray(o, o + 117)));
+    return Buffer.concat(chunks).toString('latin1');
+}
+// ---------------------------------------------------------------- RWP 信封
+/** message_id：uuid4().hex[:14] + '-' + hex(now)[-11:]。 */
+export const messageId = () => rand.uuid4().replaceAll('-', '').slice(0, 14) + '-' + rand.now().toString(16).slice(-11);
+const envelope = (t, m, b) => JSON.stringify({ v: 1, t, ...(m != null ? { m } : {}), ...(b !== undefined ? { b } : {}) });
+const b64 = (v) => Buffer.from(v).toString('base64');
+export function handshakeFrame(id) {
+    const m = messageId();
+    const payload = {
+        appId: 'xhs-pc',
+        authInfo: { authType: 'generic', sid: id.sid, uid: id.uid, domain: 'red' },
+        deviceInfo: { deviceId: id.deviceId, fingerprint: id.fingerprint, platform: 'browser', os: 'web', osVersion: '10.15', deviceName: 'Chrome', appVersion: '131.0.0.0', userAgent: UA },
+        serviceTag: '',
+        bizInfos: [
+            { bizName: 'dqa_chatsearch', serializeType: 'protobuf' },
+            { bizName: 'xhs_dots_pc', serializeType: 'protobuf' },
+            { bizName: 'push', serializeType: 'json' },
+        ],
+        roomInfo: [],
+        roomInfos: [],
+        tagInfo: [],
+        extInfo: {},
+        state: 1,
+    };
+    return [envelope(2, m, { d: { a: 1, s: 0, b: payload } }), m];
+}
+export const registerFrame = (biz, type) => envelope(2, messageId(), { d: { a: 1, s: 1, b: { bizInfo: { bizName: biz, serializeType: type }, register: true } } });
+export const joinRoomFrame = (roomId) => envelope(2, messageId(), { d: { a: 1, s: 8, b: { info: { bizName: 'room', roomId, roomType: 'LIVE' } } } });
+export const heartbeatFrame = () => envelope(0);
+export const stateSyncFrame = () => envelope(2, messageId(), { d: { a: 1, s: 6, b: {} } });
+/** im_frame：客户端发私信用 action=2、服务 rrmp.b.i。 */
+export const imFrame = (payload) => envelope(3, messageId(), { d: { a: 2, c: 'sendMessage', biz: 'im', b: b64(payload), e: {}, s: 'rrmp.b.i' } });
+/** 直播间观看心跳（上游 heartbeat）。 */
+export function viewerHeartFrame(roomId, profile) {
+    const custom = { type: 'viewer_heart', priority: 0, profile, source: 'web_live', desc: '' };
+    const data = { roomId, roomType: 'LIVE', command: 1, customData: JSON.stringify(custom) };
+    return envelope(3, messageId(), { d: { a: 0, c: 'liveHeartBeat', biz: 'room', b: b64(JSON.stringify(data)), e: {}, s: 'rrmp.o.l' } });
+}
+/**
+ * encode_room_text_payload + room_text_frame：直播间文本弹幕（t=3，biz=room，c=sendMessage，a=0，s=rrmp.o.l）。
+ * 上游要求调用方给出 command / priority / role；这里用与观看心跳（viewer_heart）相同的 1 / 0 / 0。
+ * 返回帧和它的 m（服务端的回执带同一个 m）。
+ */
+export function roomTextFrame(t) {
+    const custom = { type: 'text', priority: t.priority ?? 0, profile: { nickname: t.nickname, avatar: t.avatar, user_id: t.userId, role: t.role ?? 0 }, desc: t.content };
+    const payload = compactJson({ roomId: t.roomId, roomType: t.roomType ?? 'LIVE', command: t.command ?? 1, customData: compactJson(custom) });
+    const m = messageId();
+    return [envelope(3, m, { d: { a: 0, c: 'sendMessage', biz: 'room', b: b64(payload), e: {}, s: 'rrmp.o.l' } }), m];
+}
+/** decode_room_push：t=4 帧里 biz=room 的事件（base64 JSON，customData 再解一层）。 */
+export function decodeRoomPush(frame) {
+    const d = frame?.t === 4 ? frame?.b?.d : null;
+    if (!d || d.biz !== 'room' || !Array.isArray(d.b))
+        return [];
+    const out = [];
+    for (const item of d.b) {
+        if (typeof item?.d !== 'string')
+            continue;
+        try {
+            const payload = jsonLoads(Buffer.from(item.d, 'base64').toString('utf8'));
+            if (typeof payload?.customData === 'string') {
+                try {
+                    payload.customData = jsonLoads(payload.customData);
+                }
+                catch { }
+            }
+            out.push(payload);
+        }
+        catch { }
+    }
+    return out;
+}
+/** IM 帧：t=3 的 b.d.b 是单个 base64，t=4 的 b.d.b 是 [{d}] 批量；发送回执在 b.a.b。 */
+export function decodeImFrame(frame) {
+    const out = [];
+    const d = frame?.b?.d;
+    const tryDecode = (s) => {
+        if (typeof s !== 'string' || !s)
+            return;
+        try {
+            out.push(decodeChat(Buffer.from(s, 'base64')));
+        }
+        catch { }
+    };
+    if (d?.biz === 'im') {
+        if (typeof d.b === 'string')
+            tryDecode(d.b);
+        else if (Array.isArray(d.b))
+            for (const item of d.b)
+                tryDecode(item?.d);
+    }
+    if (!out.length)
+        tryDecode(frame?.b?.a?.b);
+    return out;
+}
+/** 长连的等待时限（毫秒）：握手回执、发送回执（上游 _wait_transport_ack 的 10 秒）。测试里调短。 */
+export const PUSH_TIMEOUTS = { handshake: 10_000, ack: 10_000 };
+const TIMEOUT = Symbol('timeout');
+/** ms 毫秒后兑现为 TIMEOUT 的定时器（真实时间，不受 rand 的假时钟影响）；用完 cancel。 */
+function timer(ms) {
+    let t;
+    const expired = new Promise((resolve) => (t = setTimeout(() => resolve(TIMEOUT), ms)));
+    return { expired, cancel: () => clearTimeout(t) };
+}
+/**
+ * 在 ms 毫秒内等 pick 认领一帧（返回非 undefined 的值）。超时或连接断开时返回 undefined。
+ * 超时后那次挂起的读取还在，会吞掉下一帧，所以这条连接不能再读，调用方随即 close。
+ */
+export async function awaitFrame(conn, ms, pick) {
+    const frames = conn.frames[Symbol.asyncIterator]();
+    const wait = timer(ms);
+    try {
+        for (;;) {
+            const r = await Promise.race([frames.next(), wait.expired]);
+            if (r === TIMEOUT || r.done)
+                return undefined;
+            const v = pick(r.value);
+            if (v !== undefined)
+                return v;
+        }
+    }
+    finally {
+        wait.cancel();
+    }
+}
+/**
+ * 上游 connect_push_from_storage：没有 RWP token 时先 celestial/lt 换一个，再握手、注册 im（可选进直播间）。
+ * 握手回执最多等 PUSH_TIMEOUTS.handshake；握手没成功时关掉连接再抛错。
+ */
+export async function connectPush(p, signal, roomId) {
+    const tokenValid = () => p.state.rwpToken && p.state.rwpToken.uid === p.userId && (p.state.rwpToken.expiredAt == null || p.state.rwpToken.expiredAt > rand.now());
+    if (!tokenValid()) {
+        p.state.rwpToken = null;
+        p.check(await celestialLt(p));
+    }
+    const sid = p.state.rwpToken?.aLt ?? '';
+    if (!sid || !p.userId)
+        throw new SpecificAIError('AUTH_REQUIRED', '没有拿到私信长连的登录 token（celestial/lt）', { hint: 'specific-ai xhs auth login' });
+    const id = { uid: p.userId, sid, deviceId: p.state.tabDeviceId, fingerprint: p.state.rwpFingerprint };
+    const cookie = Object.entries(p.wire(PUSH_URL.replace('wss://', 'https://'))).map(([k, v]) => `${k}=${v}`).join('; ');
+    const socket = await openSocket(PUSH_URL, { headers: { 'User-Agent': UA, Origin: WEB, ...(cookie ? { Cookie: cookie } : {}) }, signal });
+    const it = socket.messages[Symbol.asyncIterator]();
+    const pending = [];
+    const parse = (raw) => {
+        try {
+            return jsonLoads(String(raw));
+        }
+        catch {
+            return { raw: String(raw) };
+        }
+    };
+    try {
+        const [hs, hsId] = handshakeFrame(id);
+        await socket.send(hs);
+        // 浏览器等握手的 c=0 回执后才注册，否则后续帧都会被拒（3100001 Account has not privilege）
+        const wait = timer(PUSH_TIMEOUTS.handshake);
+        try {
+            for (;;) {
+                const r = await Promise.race([it.next(), wait.expired]);
+                if (r === TIMEOUT)
+                    throw new SpecificAIError('NETWORK', `私信长连握手超时（${PUSH_TIMEOUTS.handshake / 1000} 秒没有回执）`, { detail: { kind: 'timeout' } });
+                if (r.done)
+                    throw new SpecificAIError('NETWORK', '私信长连在握手时断开');
+                const f = parse(r.value);
+                if (f?.m !== hsId) {
+                    pending.push(f);
+                    continue;
+                }
+                const c = f?.b?.a?.c;
+                if (c !== 0)
+                    throw new SpecificAIError('AUTH_EXPIRED', `私信长连握手被拒绝：c=${c} ${f?.b?.a?.m ?? ''}`, { hint: 'specific-ai xhs auth login' });
+                break;
+            }
+        }
+        finally {
+            wait.cancel();
+        }
+        await socket.send(registerFrame('im', 'protobuf'));
+        if (roomId) {
+            await socket.send(registerFrame('room', 'json'));
+            await socket.send(joinRoomFrame(roomId));
+        }
+    }
+    catch (err) {
+        socket.close();
+        throw err;
+    }
+    const beat = setInterval(() => void socket.send(heartbeatFrame()).catch(() => { }), 30_000).unref();
+    return {
+        socket,
+        send: (frame) => socket.send(frame),
+        close: () => {
+            clearInterval(beat);
+            socket.close();
+        },
+        frames: {
+            async *[Symbol.asyncIterator]() {
+                while (pending.length)
+                    yield pending.shift();
+                for (;;) {
+                    const r = await it.next();
+                    if (r.done)
+                        return;
+                    yield parse(r.value);
+                }
+            },
+        },
+    };
+}