specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/platforms/kuaishou/web/commands.js

@@ -0,0 +1,863 @@
+import { basename, extname } from 'node:path';
+import { GUEST } from '../../../core/auth-store.js';
+import { SpecificAIError } from '../../../core/errors.js';
+import { downloadMedia, readMedia } from '../../../core/files.js';
+import { cookieCredential, finishLogin, freshCredential, loginContext, poll, showQrcode, smsLogin } from '../../../core/login.js';
+import * as n from '../../../core/normalize.js';
+import * as rand from '../../../core/rand.js';
+import { openSocket, reconnecting } from '../../../core/stream.js';
+import { paged } from '../../../core/toolkit.js';
+import * as api from './api.js';
+import { bootstrapDeviceFingerprint, credentialCookies, Ks } from './client.js';
+import { decodeFrame, enterRoomFrame, feedEvents, heartbeatFrame, userExitFrame } from './live.js';
+import * as norm from './normalize.js';
+import { CP, LIVE, UA, WWW } from './profile.js';
+import { resolveItem, resolveRoom, resolveUser, selfEid } from './resolve.js';
+import { mergeIssued } from './session.js';
+/** 建立会话（相当于上游 KuaishouAuth.initialize），命令结束前把状态写回凭证。 */
+async function ks(ctx, site = 'www') {
+    const k = new Ks(ctx);
+    await k.init();
+    if (site === 'live')
+        k.s.useSite(LIVE);
+    else if (site === 'cp')
+        k.s.useSite(CP);
+    return k;
+}
+/** 跑完命令后保存凭证：设备 cookie、轮换过的票据、kwfcv1 计数器。 */
+async function run(ctx, site, fn) {
+    const k = await ks(ctx, site);
+    try {
+        return await fn(k);
+    }
+    finally {
+        k.save();
+    }
+}
+const NO_MORE = new Set(['', 'no_more', '-1', 'None', 'null', 'undefined']);
+const more = (cursor) => cursor != null && !NO_MORE.has(String(cursor));
+/** 搜索的翻页游标：pcursor 与首屏返回的 searchSessionId 一起。 */
+function searchCursor(ctx) {
+    if (!ctx.cursor)
+        return ['', ''];
+    try {
+        const [p, s] = JSON.parse(ctx.cursor);
+        return [String(p ?? ''), String(s ?? '')];
+    }
+    catch {
+        throw new SpecificAIError('USAGE', '无效的 --cursor');
+    }
+}
+// ================================================================ auth
+/** 登录后校验：userInfoQuery 给出 eid 与昵称。 */
+async function completeLogin(ctx, k, credential) {
+    k.s.useSite(WWW);
+    const info = await api.userInfo(k);
+    const eid = info?.eid ?? info?.id;
+    if (!eid)
+        throw new SpecificAIError('AUTH_REQUIRED', '登录没有成功：cookie 无效或已过期');
+    k.save(credential);
+    return finishLogin(ctx, credential, norm.ref(eid, info.name));
+}
+/** 直播站子站点：passToken 换票 + userLogin，失败只提示（直播命令会再试一次）。 */
+async function liveSubsite(k) {
+    if (!k.s.cookies.get('passToken'))
+        return;
+    try {
+        k.s.useSite(LIVE);
+        if (!(await api.refreshLiveSession(k)))
+            k.log.warn('直播站换票没有成功，直播相关命令会在使用时重试');
+    }
+    catch (err) {
+        k.log.warn(`直播站换票失败：${err.message}`);
+    }
+}
+/**
+ * login_browser_session / _finish_mobile_browser_session 的公共后半段：
+ * CP STS + CP 文档 + 设备指纹上报 → 回到 www 再导航一次文档。
+ */
+async function finishBrowserSession(k, issued) {
+    const cp = await api.stsLogin(k, api.SID_CP, CP);
+    if (!cp.some(([key]) => key === `${api.SID_CP}_ph`)) {
+        throw new SpecificAIError('AUTH_REQUIRED', '创作者中心 STS 换票没有下发 kuaishou.web.cp.api_ph', { detail: { stage: 'cp/sts', cookies: cp.map(([key]) => key) } });
+    }
+    mergeIssued(issued, cp);
+    mergeIssued(issued, await api.bootstrapDocument(k, CP, '/article/publish/video?origin=www.kuaishou.com'));
+    const fp = await bootstrapDeviceFingerprint(k);
+    k.s.useSite(WWW);
+    const doc = await api.bootstrapDocument(k, WWW, '/new-reco');
+    mergeIssued(issued, [
+        ['wid', fp.wid],
+        ['didv', fp.didv],
+    ]);
+    mergeIssued(issued, doc);
+    return issued;
+}
+/** 登录用的新会话（上游 prepare_auth("") + _ensure_browser_defaults）。 */
+function loginKs(ctx, credential) {
+    const k = new Ks({ ...ctx, account: GUEST, credential });
+    k.s.prepare([]);
+    k.s.liveBootstrapEnabled = true;
+    k.s.ensureBrowserDefaults();
+    return k;
+}
+/** 扫码登录的总时限（等扫码与等确认共用）。 */
+const QR_TIMEOUT_MS = 600_000;
+async function qrcodeLogin(ctx) {
+    const credential = freshCredential(ctx, 'qrcode');
+    const k = loginKs(ctx, credential);
+    const sid = api.SID_WWW;
+    const channel = api.channelFor(sid);
+    const deadline = rand.now() + QR_TIMEOUT_MS;
+    const state = { token: '', signature: '' };
+    const issue = async () => {
+        const start = await api.qrStart(k, sid, channel);
+        if (start?.result !== 1)
+            return false;
+        state.token = start.qrLoginToken;
+        state.signature = start.qrLoginSignature;
+        await showQrcode(ctx, String(start.qrUrl ?? ''), '请用快手 App 扫码并确认');
+        return true;
+    };
+    if (!(await issue()))
+        throw new SpecificAIError('UPSTREAM', '申请二维码失败', { detail: { stage: 'qr/start' } });
+    // 上游 login_by_qr 的 poll：等扫码时二维码过期（707）就换一张，扫过之后不能再换；711 / 712 是在手机上取消
+    const wait = (step) => poll(async () => {
+        let data;
+        try {
+            data = step === 'scan' ? await api.qrScanResult(k, state.token, state.signature, channel) : await api.qrAcceptResult(k, state.token, state.signature, sid, channel);
+        }
+        catch (err) {
+            // 长轮询读超时是正常的（上游 ReadTimeout 接着轮）；其他网络错误交给 poll 容忍几次
+            if (err instanceof SpecificAIError && err.code === 'NETWORK' && err.detail?.kind === 'timeout')
+                return undefined;
+            throw err;
+        }
+        const result = data?.result;
+        if (result === 1)
+            return data;
+        if (result === 707) {
+            if (step === 'accept' || !(await issue()))
+                throw new SpecificAIError('AUTH_REQUIRED', '二维码已过期', { hint: 'specific-ai kuaishou auth login' });
+            return undefined;
+        }
+        if (result === 711 || result === 712)
+            throw new SpecificAIError('AUTH_REQUIRED', '已在手机上取消登录', { detail: { result } });
+        return undefined;
+    }, { interval: 1000, timeout: deadline - rand.now(), what: '扫码登录' });
+    await wait('scan');
+    ctx.log.info('已扫码，请在手机上确认');
+    const accepted = await wait('accept');
+    const qrToken = accepted.qrToken ?? accepted.qr_token;
+    if (!qrToken)
+        throw new SpecificAIError('UPSTREAM', '确认登录后没有拿到 qrToken', { detail: { stage: 'acceptResult' } });
+    const [data, issued] = await api.qrCallback(k, qrToken, sid, channel);
+    if (!issued.length || data?.result !== 1)
+        throw new SpecificAIError('AUTH_REQUIRED', `扫码登录失败（result=${data?.result}）`, { detail: { stage: 'callback' } });
+    k.s.update(issued);
+    mergeIssued(issued, await api.stsLogin(k, sid));
+    mergeIssued(issued, await api.bootstrapDocument(k, WWW, '/new-reco'));
+    await finishBrowserSession(k, issued);
+    k.s.update(issued);
+    k.s.ensureBrowserDefaults();
+    await liveSubsite(k);
+    return completeLogin(ctx, k, credential);
+}
+async function smsFlow(ctx) {
+    const credential = freshCredential(ctx, 'sms');
+    let k = null;
+    return smsLogin(ctx, {
+        send: async (phone) => {
+            k = loginKs(ctx, credential);
+            await k.s.current();
+            const r = await api.requestMobileCode(k, phone);
+            if (r?.result !== 1) {
+                throw new SpecificAIError('UPSTREAM', `短信验证码申请失败：${r?.error_msg ?? r?.result}`, { detail: { result: r?.result } });
+            }
+            return { phone, cookies: [...k.s.cookies].filter(([name]) => name !== 'kwscode' && name !== 'kwssectoken'), kwfcv1: k.s.kwfcv1 };
+        },
+        verify: async (state, code) => {
+            if (!k) {
+                k = new Ks({ ...ctx, account: GUEST, credential });
+                k.s.prepare(state.cookies);
+                k.s.restoreCounter(state.kwfcv1);
+                k.s.liveBootstrapEnabled = true;
+                k.s.ensureBrowserDefaults();
+            }
+            const [data, issued] = await api.mobileCodeLogin(k, state.phone, code);
+            if (data?.result !== 1 || !data?.passToken) {
+                throw new SpecificAIError('AUTH_REQUIRED', `验证码登录失败：${data?.error_msg ?? data?.result}`, { detail: { stage: 'mobileCode', result: data?.result } });
+            }
+            k.s.update(issued);
+            k.s.update(issued);
+            mergeIssued(issued, await api.stsLogin(k, api.SID_WWW, WWW));
+            mergeIssued(issued, await api.bootstrapDocument(k, WWW, '/new-reco'));
+            await finishBrowserSession(k, issued);
+            k.s.update(issued);
+            k.s.ensureBrowserDefaults();
+            await liveSubsite(k);
+            return completeLogin(ctx, k, credential);
+        },
+    });
+}
+async function cookieLogin(ctx) {
+    const credential = cookieCredential(ctx, '.kuaishou.com');
+    const k = new Ks(loginContext(ctx, credential));
+    await k.init(credentialCookies(credential));
+    // 用户 CK 里有 passToken 但缺创作者中心票据时，补一次 CP STS（specific-ai 补充，失败只提示）
+    if (k.s.cookies.get('passToken') && !k.s.cookies.get('kuaishou.web.cp.api_ph')) {
+        try {
+            await api.stsLogin(k, api.SID_CP, CP);
+        }
+        catch (err) {
+            ctx.log.warn(`创作者中心换票失败：${err.message}`);
+        }
+    }
+    if (!k.s.cookies.get('kuaishou.live.web_st'))
+        await liveSubsite(k);
+    return completeLogin(ctx, k, credential);
+}
+export async function authLogin(ctx) {
+    const method = ctx.options.method;
+    if (method === 'cookie')
+        return cookieLogin(ctx);
+    if (method === 'sms')
+        return smsFlow(ctx);
+    if (method === 'qrcode')
+        return qrcodeLogin(ctx);
+    throw new SpecificAIError('USAGE', `不支持的登录方式：${method}`);
+}
+export async function authStatus(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const info = await api.userInfo(k);
+        const eid = info?.eid ?? info?.id;
+        return {
+            logged_in: Boolean(eid),
+            user: eid ? norm.ref(eid, info.name) : null,
+            method: eid ? ctx.credential.method : null,
+            expires_at: null,
+        };
+    });
+}
+/**
+ * 服务端登出（`auth logout` 删除本地凭证前由 core 调用）：直播页的 passport logout + userLogout。
+ * 直播站票据不全时先用 passToken 补一次（specific-ai 补充，与 live listen 相同），否则上游拒绝按半清理的状态登出。
+ */
+export async function serverLogout(ctx) {
+    await run(ctx, 'live', async (k) => {
+        const has = (name) => Boolean(k.s.cookies.get(name));
+        const live = ['kuaishou.live.web_st', 'kuaishou.live.web_ph'].filter(has).length;
+        if (has('userId') && live < 2 && has('passToken'))
+            await api.refreshLiveSession(k, api.roomReferer(api.LIVE_LOGOUT_EID));
+        await api.liveLogout(k);
+    });
+}
+// ================================================================ user
+export async function userGet(ctx) {
+    return run(ctx, 'www', async (k) => {
+        if (ctx.args.user === 'me') {
+            const p = k.check(await api.profile(k), 'profile/get');
+            return norm.selfUser(p);
+        }
+        const eid = await resolveUser(k, ctx.args.user);
+        // result 与其他接口一样映射（109 需要登录、2 风控）；result=1 却没有 userProfile 的是用户不存在或不可见
+        const r = k.check(await api.profileReduced(k, eid), '用户资料');
+        if (!r.userProfile)
+            throw new SpecificAIError('UPSTREAM', `用户不存在或不可见（result=${r?.result}）`, { detail: { result: r?.result, user: eid } });
+        return norm.reducedUser(r);
+    });
+}
+export async function userSearch(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const [pcursor, session] = searchCursor(ctx);
+        const r = k.check(await api.searchUser(k, ctx.args.keyword, pcursor, session), '搜索');
+        const list = (r.users ?? r.list ?? []).map(norm.listUser);
+        const next = r.pcursor;
+        return paged(list, JSON.stringify([next, r.searchSessionId ?? session]), list.length > 0 && more(next));
+    });
+}
+export async function userItems(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const eid = await resolveUser(k, ctx.args.user);
+        const r = k.check(await api.profileFeed(k, eid, ctx.cursor ?? ''), 'profile/feed');
+        const list = (r.feeds ?? []).map((f) => norm.feed(f));
+        return paged(list, r.pcursor, list.length > 0 && more(r.pcursor));
+    });
+}
+/** 快手只能看自己的点赞、关注、粉丝。 */
+function onlyMe(ctx, what) {
+    const u = ctx.args.user ?? 'me';
+    if (u !== 'me')
+        throw new SpecificAIError('UNSUPPORTED', `快手只能查看自己的${what}`, { hint: `specific-ai kuaishou ${ctx.resource} ${ctx.action}` });
+}
+export async function userLikes(ctx) {
+    onlyMe(ctx, '点赞');
+    return run(ctx, 'www', async (k) => {
+        const r = k.check(await api.likedList(k, ctx.cursor ?? ''), 'feed/liked');
+        const list = (r.feeds ?? []).map((f) => norm.feed(f));
+        return paged(list, r.pcursor, list.length > 0 && more(r.pcursor));
+    });
+}
+export async function userCollects(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const eid = await resolveUser(k, ctx.args.user ?? 'me');
+        const r = k.check(await api.collectList(k, eid, ctx.cursor ?? ''), 'collect/list');
+        const list = (r.feeds ?? []).map((f) => norm.feed(f));
+        return paged(list, r.pcursor, list.length > 0 && more(r.pcursor));
+    });
+}
+async function relation(ctx, ftype) {
+    onlyMe(ctx, ftype === 1 ? '关注' : '粉丝');
+    return run(ctx, 'www', async (k) => {
+        await selfEid(k);
+        const r = k.check(await api.relation(k, ftype, ctx.cursor ?? ''), 'relation/fol');
+        const list = (r.authors ?? r.fols ?? r.users ?? []).map(norm.listUser);
+        return paged(list, r.pcursor, list.length > 0 && more(r.pcursor));
+    });
+}
+export const userFollowers = (ctx) => relation(ctx, 2);
+export const userFollowing = (ctx) => relation(ctx, 1);
+// ================================================================ item
+async function detailOf(k, input) {
+    return api.videoDetail(k, await resolveItem(k, input));
+}
+export async function itemGet(ctx) {
+    return run(ctx, 'www', async (k) => norm.detail(await detailOf(k, ctx.args.item)));
+}
+export async function itemSearch(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const [pcursor, session] = searchCursor(ctx);
+        const r = k.check(await api.searchFeed(k, ctx.args.keyword, pcursor, session), '搜索');
+        const list = (r.feeds ?? r.list ?? []).map((f) => norm.feed(f));
+        return paged(list, JSON.stringify([r.pcursor, r.searchSessionId ?? session]), list.length > 0 && more(r.pcursor));
+    });
+}
+export async function itemRelated(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const r = await api.shortVideoReco(k, await resolveItem(k, ctx.args.item));
+        return paged((r.feeds ?? []).map((f) => norm.feed(f)), null, false);
+    });
+}
+/** 作品管理页的时间范围：服务端拒绝超过一年的范围（「时间范围不能大于1年」），一次查一年。 */
+const WORKS_RANGE_MS = 365 * 86_400_000;
+const WORKS_PAGE = 20;
+/** 往前翻的下限：快手 2011 年上线，更早的窗口不用再查。 */
+const WORKS_FLOOR_MS = Date.parse('2011-01-01T00:00:00+08:00');
+/** photo/list 的查询（上游 video_photo_list，字段顺序照浏览器）：时间窗口 [end - 1 年, end]，从 cursor 往前翻。 */
+function worksQuery(queryType, cursor, end) {
+    return { queryType, cursor, startTime: end - WORKS_RANGE_MS, endTime: end, limit: WORKS_PAGE, timeRangeType: 5, keyword: '' };
+}
+/** item list 的游标 `<cursor>:<窗口终点>`；只有一个数字的（旧版本输出的）按窗口终点为现在处理。 */
+function worksCursor(cursor, now) {
+    if (!cursor)
+        return [now, now];
+    const [at, end] = cursor.split(':').map(Number);
+    if (!Number.isSafeInteger(at) || (end !== undefined && !Number.isSafeInteger(end)))
+        throw new SpecificAIError('USAGE', '无效的 --cursor');
+    return [at, end ?? now];
+}
+/**
+ * 作品管理页的作品列表（创作者中心），带审核状态。服务端一次只查一年：窗口里按 nextCursor 往前翻，
+ * 一个窗口翻完（一页不满 20 条）就把窗口前移一年接着翻（窗口编进游标），直到某个窗口一条作品都没有，或者早于快手上线。
+ */
+export async function itemList(ctx) {
+    return run(ctx, 'cp', async (k) => {
+        const now = rand.now();
+        const [cursor, end] = worksCursor(ctx.cursor, now);
+        const r = await api.videoPhotoList(k, worksQuery('0', cursor, end));
+        try {
+            k.check(r, '作品管理');
+        }
+        catch (err) {
+            // 前移过的窗口没有实测过：服务端不认时当作没有更早的作品，前面已经取到的不因此作废
+            if (end > now - WORKS_RANGE_MS || !(err instanceof SpecificAIError) || err.code !== 'UPSTREAM')
+                throw err;
+            k.log.warn(`更早的作品没有取到，停止往前翻：${err.message}`);
+            return paged([], null, false);
+        }
+        const rows = r.data?.list ?? [];
+        const list = rows.map(norm.work);
+        // nextCursor 是本页最后一条的时间减 1 毫秒；一页满 20 条就在这个窗口里接着翻
+        const next = r.data?.nextCursor;
+        if (rows.length >= WORKS_PAGE && more(next))
+            return paged(list, `${next}:${end}`, true);
+        const start = end - WORKS_RANGE_MS;
+        if ((!rows.length && cursor === end) || start <= WORKS_FLOOR_MS)
+            return paged(list, null, false);
+        return paged(list, `${start - 1}:${start - 1}`, true);
+    });
+}
+export async function itemMedia(ctx) {
+    return run(ctx, 'www', async (k) => norm.photoMedia((await detailOf(k, ctx.args.item)).photo));
+}
+export async function itemDownload(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const d = await detailOf(k, ctx.args.item);
+        return downloadMedia(ctx, k.http, String(d.photo?.id), norm.photoMedia(d.photo), {
+            headers: [
+                ['user-agent', UA],
+                ['referer', 'https://www.kuaishou.com/'],
+            ],
+        });
+    });
+}
+// ---------------------------------------------------------------- 发布与上传（publish_api.py）
+const MAX_IMAGE_BYTES = 15 * 1024 * 1024;
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+/** 图文上传的 wire 合同是 image/png：非 PNG 先转成 PNG（上游用 Pillow，这里用 @napi-rs/canvas）。 */
+async function toPng(file) {
+    if (Buffer.from(file.data.subarray(0, 8)).equals(PNG_SIGNATURE))
+        return file;
+    const { createCanvas, loadImage } = await import('@napi-rs/canvas');
+    let image;
+    try {
+        image = await loadImage(Buffer.from(file.data));
+    }
+    catch {
+        throw new SpecificAIError('USAGE', `无法读取图片：${file.filename}`);
+    }
+    const canvas = createCanvas(image.width, image.height);
+    canvas.getContext('2d').drawImage(image, 0, 0);
+    const stem = basename(file.filename, extname(file.filename)) || 'image';
+    return { data: new Uint8Array(await canvas.encode('png')), filename: `${stem}.png`, contentType: 'image/png' };
+}
+/** ksuploader：resume → 逐片 fragment → complete。服务端已有的分片跳过。 */
+async function uploadBytes(k, token, endpoints, data, afterResume) {
+    if (!endpoints.length)
+        throw new SpecificAIError('UPSTREAM', 'upload/pre 没有下发上传地址');
+    const base = api.uploadBase(endpoints[0]);
+    const info = await api.uploadResume(k, base, token);
+    const d = info?.data ?? info ?? {};
+    const done = new Set((d.fragment_list ?? d.fragmentList ?? []).map((f) => Number(f?.id)));
+    const hint = Number(d.fragment_index ?? d.fragmentIndex ?? -1);
+    if (!done.size && hint >= 0)
+        for (let i = 0; i <= hint; i++)
+            done.add(i);
+    if (afterResume)
+        await afterResume();
+    const count = Math.max(1, Math.ceil(data.length / api.CHUNK_SIZE));
+    if (!d.existed) {
+        for (let i = 0; i < count; i++) {
+            if (done.has(i))
+                continue;
+            const start = i * api.CHUNK_SIZE;
+            const chunk = data.subarray(start, Math.min(start + api.CHUNK_SIZE, data.length));
+            k.log.info(`上传 ${i + 1}/${count}`);
+            await api.uploadFragment(k, base, token, i, chunk, start, data.length);
+        }
+    }
+    await api.uploadComplete(k, base, token, count);
+}
+/** upload_atlas_images：权限预检 → 图文编辑器预请求 → 逐图 pre / 上传 / single finish → 单图草稿快照。 */
+async function uploadAtlas(k, inputs) {
+    if (!inputs.length || inputs.length > 31)
+        throw new SpecificAIError('USAGE', '图文需要 1～31 张图片');
+    const images = [];
+    for (const input of inputs) {
+        if (input.data.length >= MAX_IMAGE_BYTES)
+            throw new SpecificAIError('USAGE', `${input.filename} 超过 15MB`);
+        images.push(await toPng(input));
+    }
+    if (k.s.cookies.get('kwpsecproductname') !== 'onvideo-cp')
+        k.s.useSite(CP);
+    await api.requirePublishAuthority(k);
+    for (const [label, r] of [
+        ['realize/entrance', await api.atlasRealizeEntrance(k)],
+        ['activity/list', await api.activityList(k, 'initial', 'atlas')],
+        ['collection/canAddAtlas', await api.collectionCanAddAtlas(k)],
+    ]) {
+        if (r?.result !== 1)
+            throw new SpecificAIError('UPSTREAM', `图文发布预检 ${label} 没有通过`, { detail: { result: r?.result, message: r?.message } });
+    }
+    let fileId = null;
+    let atlasId = null;
+    let resumed = false;
+    const blobKeys = [];
+    const urls = [];
+    for (const [i, image] of images.entries()) {
+        const pre = await api.atlasUploadPre(k, image.contentType, atlasId, fileId);
+        if (pre?.result !== 1)
+            throw new SpecificAIError('UPSTREAM', `第 ${i + 1} 张图片 upload/pre 失败：${pre?.message ?? pre?.result}`, { detail: { result: pre?.result } });
+        const data = pre.data ?? {};
+        fileId = data.fileId ?? fileId;
+        atlasId = data.atlasId ?? atlasId;
+        const one = data.uploadInfo?.[0] ?? {};
+        if (!one.token || !one.blobKey)
+            throw new SpecificAIError('UPSTREAM', `第 ${i + 1} 张图片 upload/pre 没有下发上传票据`);
+        await uploadBytes(k, one.token, one.endPoints ?? one.endpoints ?? [], image.data, async () => {
+            if (resumed)
+                return;
+            resumed = true;
+            for (const r of [await api.activityList(k, 'post_resume', 'atlas'), await api.activityTab(k, 'atlas'), await api.activityFilter(k, 'atlas')]) {
+                if (r?.result !== 1)
+                    throw new SpecificAIError('UPSTREAM', '图文编辑器活动接口没有通过', { detail: { result: r?.result } });
+            }
+        });
+        const done = await api.atlasUploadSingleFinish(k, fileId, atlasId, one.blobKey);
+        if (done?.result !== 1)
+            throw new SpecificAIError('UPSTREAM', `第 ${i + 1} 张图片 single/finish 失败`, { detail: { result: done?.result } });
+        blobKeys.push(one.blobKey);
+        urls.push(n.url(done.data?.url?.[0]?.url));
+    }
+    if (images.length === 1) {
+        const snap = await api.atlasSnapshotSave(k, fileId, atlasId);
+        if (snap?.result !== 1)
+            throw new SpecificAIError('UPSTREAM', '图文草稿快照保存失败', { detail: { result: snap?.result } });
+    }
+    return { fileId, atlasId, blobKeys, urls };
+}
+/** upload_video_file：权限预检 → 视频上传上下文 → upload/pre → 分片上传 → upload/finish。 */
+async function uploadVideo(k, file) {
+    if (!file.data.length)
+        throw new SpecificAIError('USAGE', '视频文件为空');
+    await api.requirePublishAuthority(k);
+    await k.s.useCpUpload();
+    const pre = await api.videoUploadPre(k);
+    if (pre?.result !== 1)
+        throw new SpecificAIError('UPSTREAM', `upload/pre 失败：${pre?.message ?? pre?.result}`, { detail: { result: pre?.result } });
+    const data = pre.data ?? {};
+    await uploadBytes(k, data.token, data.endPoints ?? data.endpoints ?? [], file.data);
+    const finish = await api.videoUploadFinish(k, data.token, file.filename, file.contentType.startsWith('video/') ? file.contentType : 'video/mp4', file.data.length);
+    if (finish?.result !== 1)
+        throw new SpecificAIError('UPSTREAM', `upload/finish 失败：${finish?.message ?? finish?.result}`, { detail: { result: finish?.result } });
+    if (!(Number(finish.data?.videoDuration) > 0))
+        throw new SpecificAIError('UPSTREAM', '获取视频时长失败，请换一个视频');
+    return finish.data;
+}
+function caption(o) {
+    const tags = [...(o.tag ?? []), ...(o.topic ?? [])].map((t) => `#${t.replace(/^#/, '')}`);
+    return [[o.title, o.text].filter(Boolean).join('\n'), tags.join(' ')].filter(Boolean).join(' ');
+}
+export async function itemPublish(ctx) {
+    const o = ctx.options;
+    const images = o.image ?? [];
+    if (!images.length === !o.video)
+        throw new SpecificAIError('USAGE', '快手发布需要 --image（1～31 张）或 --video，二选一', { hint: 'specific-ai kuaishou item publish --image a.jpg --text "正文"' });
+    const photoStatus = api.PHOTO_STATUS[(o.visibility ?? 'public')];
+    const publishTime = o.schedule ? Date.parse(o.schedule) : 0;
+    return run(ctx, 'cp', async (k) => {
+        const text = caption(o);
+        if (images.length) {
+            const files = [];
+            for (const input of images)
+                files.push(await readMedia(k.http, input));
+            const up = await uploadAtlas(k, files);
+            const checked = await api.atlasUploadFinish(k, up.fileId, up.atlasId, up.blobKeys);
+            if (checked?.result !== 1)
+                throw new SpecificAIError('UPSTREAM', `图文审核没有通过：${checked?.message ?? checked?.result}`, { detail: { result: checked?.result } });
+            const r = k.check(await api.publishAtlas(k, { caption: text, fileId: up.fileId, atlasId: up.atlasId, photoStatus, publishTime }), '图文发布');
+            return n.item({
+                id: n.id(up.atlasId ?? up.fileId),
+                kind: 'image',
+                text: text || null,
+                media: up.urls.filter((u) => Boolean(u)).map((url, i) => n.media({ id: up.blobKeys[i] ?? null, type: 'image', url })),
+                status: o.visibility === 'private' ? 'private' : 'reviewing',
+            }, r);
+        }
+        const file = await readMedia(k.http, o.video);
+        const info = await uploadVideo(k, file);
+        const r = k.check(await api.publishVideo(k, {
+            fileId: Number(info.fileId),
+            coverKey: String(info.coverKey ?? ''),
+            mediaId: String(info.mediaId ?? ''),
+            videoDuration: Number(info.videoDuration),
+            caption: text,
+            photoStatus,
+            publishTime,
+        }), '视频发布');
+        const fallback = n.item({ id: n.id(info.fileId), kind: 'video', text: text || null, status: o.visibility === 'private' ? 'private' : 'reviewing' }, r);
+        const published = await afterVideoPublish(k, String(info.coverKey ?? '')).catch((err) => {
+            k.log.warn(`发布已提交，但取发布状态失败：${err.message}`);
+            return null;
+        });
+        if (!published)
+            return fallback;
+        // 就地改字段：展开会丢掉不可枚举的原始对象（--raw）
+        published.text ??= fallback.text;
+        if (o.visibility === 'private')
+            published.status = 'private';
+        return published;
+    });
+}
+/**
+ * 视频提交后浏览器跳到作品管理页（status=2&from=publish）：photo/list 拿到这次发布的 publishId，
+ * 再 publish/refresh 取一次发布状态（上游 video_photo_list(post_publish) + video_publish_refresh）。
+ * 这一行对不上本次上传（不是唯一一行、已有 workId、封面不是这次的）时不轮询，只用列表里的数据。
+ */
+export async function afterVideoPublish(k, coverKey) {
+    const now = rand.now();
+    const list = await api.videoPhotoList(k, worksQuery('2', now, now), { postPublish: true });
+    if (list?.result !== 1)
+        return null;
+    const rows = list.data?.list ?? [];
+    const id = api.publishRefreshId(list, coverKey);
+    if (id == null)
+        return rows.length === 1 && rows[0]?.unPublishCoverKey === coverKey ? norm.work(rows[0]) : null;
+    const refresh = await api.videoPublishRefresh(k, [id]);
+    return norm.publishedWork(rows[0], refresh?.result === 1 ? refresh : null);
+}
+export async function mediaUpload(ctx) {
+    return run(ctx, 'cp', async (k) => {
+        const file = await readMedia(k.http, ctx.args.file);
+        if (file.contentType.startsWith('video/')) {
+            const info = await uploadVideo(k, file);
+            return n.media({ id: n.id(info.fileId), type: 'video', url: `${CP}/rest/cp/works/v2/video/pc/upload/cover/view?coverKey=${encodeURIComponent(String(info.coverKey ?? ''))}` }, info);
+        }
+        const up = await uploadAtlas(k, [file]);
+        return n.media({ id: up.blobKeys[0] ?? null, type: 'image', url: up.urls[0] ?? '' }, up);
+    });
+}
+// ================================================================ comment
+export async function commentList(ctx) {
+    if (ctx.options.product)
+        throw new SpecificAIError('NOT_IMPLEMENTED', 'kuaishou 的 comment list --product 尚未实现', { detail: { upstream: 'none' } });
+    return run(ctx, 'www', async (k) => {
+        const photoId = await resolveItem(k, ctx.args.item);
+        const r = await api.commentListGql(k, photoId, ctx.cursor ?? '');
+        const list = (r.rootCommentsV2 ?? r.rootComments ?? []).map((c) => norm.comment(c, photoId));
+        const next = r.pcursorV2 ?? r.pcursor;
+        return paged(list, next, list.length > 0 && more(next));
+    });
+}
+export async function commentReplies(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const photoId = await resolveItem(k, ctx.args.item);
+        const root = ctx.args.comment;
+        const r = await api.subCommentList(k, photoId, root, ctx.cursor ?? '');
+        const list = (r.subCommentsV2 ?? r.subComments ?? []).map((c) => norm.comment(c, photoId, root));
+        const next = r.pcursorV2 ?? r.pcursor;
+        return paged(list, next, list.length > 0 && more(next));
+    });
+}
+// ================================================================ feed
+/**
+ * recommend 是 new-reco 的推荐流（get_feed_hot，上游 docstring：“获取推荐流（精彩推荐）”）；following 是关注页。
+ * 推荐流每页都返回 pcursor="1"、翻页固定发 `{}`，原样输出的话游标不变，core 会停止翻页：输出的游标带上已取的页数
+ * `<pcursor>:<页数>`，请求时只用 pcursor。某页没有作品、或者 pcursor 表示没有更多时停止（与上游 get_some_feed_hot 相同）。
+ */
+export async function feedList(ctx) {
+    const kind = ctx.options.kind ?? 'recommend';
+    return run(ctx, 'www', async (k) => {
+        if (kind === 'following') {
+            const r = await api.likeData(k);
+            if (r?.result != null && r.result !== 1)
+                k.check(r, '关注流');
+            return paged((r.feeds ?? []).map((f) => norm.feed(f)), null, false);
+        }
+        const [pcursor, pages] = feedCursor(ctx.cursor);
+        const r = k.check(await api.feedHot(k, pcursor), 'feed/hot');
+        const list = (r.feeds ?? []).map((f) => norm.feed(f));
+        return paged(list, `${r.pcursor}:${pages + 1}`, list.length > 0 && more(r.pcursor));
+    });
+}
+/** 推荐流的游标 `<pcursor>:<已取的页数>`；没有页数的（旧版本输出的）按已取一页处理。 */
+function feedCursor(cursor) {
+    if (!cursor)
+        return ['', 0];
+    const i = cursor.lastIndexOf(':');
+    const pages = i < 0 ? 1 : Number(cursor.slice(i + 1));
+    if (!Number.isSafeInteger(pages) || pages < 1)
+        throw new SpecificAIError('USAGE', '无效的 --cursor');
+    return [i < 0 ? cursor : cursor.slice(0, i), pages];
+}
+// ================================================================ live
+const ROOM_CACHE_TTL = 6 * 3600_000;
+const ROOM_CACHE_MAX = 200;
+/** 首页列表里的直播间快照（上游 find_live_room 把它交给 LiveDanmakuClient，避免首页轮换后找不到）。 */
+function rememberRooms(ctx, items) {
+    const cache = { ...(ctx.credential.extra.live_rooms ?? {}) };
+    for (const item of items) {
+        const eid = String(item?.author?.id ?? '');
+        if (!item?.id || !eid)
+            continue;
+        cache[eid] = { id: item.id, caption: item.caption, poster: item.poster, living: item.living, watchingCount: item.watchingCount, author: { id: eid, name: item.author?.name, living: item.author?.living }, at: rand.now() };
+    }
+    const entries = Object.entries(cache).sort((a, b) => Number(b[1].at) - Number(a[1].at)).slice(0, ROOM_CACHE_MAX);
+    ctx.credential.extra.live_rooms = Object.fromEntries(entries);
+}
+function homeRooms(home) {
+    const out = [];
+    for (const section of home?.list ?? [])
+        for (const group of section?.gameLiveInfo ?? [])
+            for (const item of group?.liveInfo ?? [])
+                if (item?.id && item?.author?.id)
+                    out.push(item);
+    return out;
+}
+/** get_room_state：在直播首页 home/list 里找这个主播的直播间（拿 liveStreamId），找不到时用最近见过的快照。 */
+async function roomState(k, eid) {
+    const rooms = homeRooms(k.checkLive(await api.homeList(k)));
+    rememberRooms(k.ctx, rooms);
+    const found = rooms.find((item) => String(item.author.id) === eid);
+    if (found)
+        return found;
+    const cached = k.ctx.credential.extra.live_rooms?.[eid];
+    if (cached && rand.now() - Number(cached.at) < ROOM_CACHE_TTL)
+        return cached;
+    throw new SpecificAIError('UPSTREAM', `直播首页列表里没有这个直播间：${eid}`, { hint: 'specific-ai kuaishou live list 查看当前可访问的直播间', detail: { room: eid } });
+}
+export async function liveGet(ctx) {
+    return run(ctx, 'live', async (k) => norm.liveRoom(await roomState(k, await resolveRoom(k, ctx.args.room))));
+}
+export async function liveList(ctx) {
+    return run(ctx, 'live', async (k) => {
+        const items = homeRooms(k.checkLive(await api.homeList(k)));
+        rememberRooms(ctx, items);
+        const seen = new Set();
+        const rooms = [];
+        for (const item of items) {
+            const eid = String(item.author.id);
+            if (seen.has(eid))
+                continue;
+            seen.add(eid);
+            rooms.push(norm.liveRoom(item));
+        }
+        rooms.sort((a, b) => Number(b.status === 'live') - Number(a.status === 'live'));
+        return paged(rooms, null, false);
+    });
+}
+export async function liveCategories(ctx) {
+    return run(ctx, 'live', async (k) => {
+        const d = k.checkLive(await api.categoryClassify(k));
+        const out = [];
+        const parents = new Set();
+        for (const c of d.list ?? []) {
+            const parent = n.idOrNull(c.categoryAbbr);
+            if (parent && !parents.has(parent)) {
+                parents.add(parent);
+                out.push(n.category({ id: parent, name: String(c.categoryName ?? parent) }));
+            }
+            out.push(n.category({ id: n.id(c.id), name: String(c.name ?? ''), parent_id: parent }, c));
+        }
+        return out;
+    });
+}
+export async function liveGifts(ctx) {
+    return run(ctx, 'live', async (k) => {
+        const eid = await resolveRoom(k, ctx.args.room);
+        const room = await roomState(k, eid);
+        // 进房间时的首屏列表，再点开“更多礼物”（sortType=0）取全量；全量取不到时退回首屏
+        const first = k.checkLive(await api.giftList(k, String(room.id), eid)).gifts ?? [];
+        let all = [];
+        try {
+            all = k.checkLive(await api.giftList(k, String(room.id), eid, 0)).gifts ?? [];
+        }
+        catch (err) {
+            k.log.warn(`“更多礼物”没有取到，只列出首屏礼物：${err.message}`);
+        }
+        return (all.length ? all : first).map(norm.gift);
+    });
+}
+export async function liveReplays(ctx) {
+    return run(ctx, 'www', async (k) => {
+        const eid = await resolveUser(k, ctx.args.user);
+        const r = k.check(await api.playbackList(k, eid, ctx.cursor ?? ''), '直播回放');
+        const rows = r.list ?? r.playbackList ?? r.feeds ?? r.data?.list ?? [];
+        const list = rows.map((v) => norm.playback(v, eid));
+        const next = r.pcursor ?? r.data?.pcursor;
+        return paged(list, next, list.length > 0 && more(next));
+    });
+}
+/** 直播弹幕长连（上游 ks_apis/live_ws.py 的 LiveDanmakuClient）。 */
+export function liveListen(ctx) {
+    return (async function* () {
+        const k = await ks(ctx, 'live');
+        try {
+            const eid = await resolveRoom(k, ctx.args.room);
+            const referer = api.roomReferer(eid);
+            if (!k.s.cookies.get('kuaishou.live.web_st') || !k.s.cookies.get('kuaishou.live.web_ph')) {
+                if (!k.s.cookies.get('passToken') || !(await api.refreshLiveSession(k, referer))) {
+                    throw new SpecificAIError('AUTH_REQUIRED', '快手直播弹幕需要登录（缺少直播站票据）', { hint: 'specific-ai kuaishou auth login' });
+                }
+            }
+            const room = await roomState(k, eid);
+            const liveStreamId = String(room.id);
+            if (!(room.living || room.author?.living))
+                ctx.log.warn(`主播当前可能不在播：${eid}`);
+            let info = (await api.websocketInfo(k, liveStreamId, eid))?.data ?? {};
+            if (!info.token) {
+                ctx.log.info('websocketinfo 没有给 token，重建直播会话后重试');
+                if (await api.refreshLiveSession(k))
+                    info = (await api.websocketInfo(k, liveStreamId, eid))?.data ?? {};
+            }
+            if (info.result === 400002 || (info.result === 2 && !info.token)) {
+                throw new SpecificAIError('RISK_CONTROL', '快手直播风控拦截：需要先在浏览器里过一次滑块验证', { detail: { kind: info.result === 400002 ? 'captcha' : 'blocked', result: info.result } });
+            }
+            const token = String(info.token ?? '');
+            const urls = info.websocketUrls ?? [];
+            if (!token || !urls.length)
+                throw new SpecificAIError('UPSTREAM', 'websocketinfo 没有给 token 或接入地址', { detail: { result: info.result } });
+            // 礼物名：首屏礼物列表 + 房间的完整礼物字典（allgifts，含不在面板上的礼物）
+            const gifts = new Map();
+            for (const [label, load] of [
+                ['礼物列表', () => api.giftList(k, liveStreamId, eid)],
+                ['礼物字典', () => api.emojiAllGifts(k, eid)],
+            ]) {
+                try {
+                    for (const [id, name] of norm.giftNames(k.checkLive(await load())))
+                        gifts.set(id, name);
+                }
+                catch (err) {
+                    ctx.log.debug(`${label}获取失败：${err.message}`);
+                }
+            }
+            k.save();
+            yield* reconnecting(ctx, async function* (attempt) {
+                const url = urls[attempt % urls.length];
+                const socket = await openSocket(url, { headers: { Origin: LIVE, 'User-Agent': UA }, signal: ctx.signal });
+                let beat = null;
+                try {
+                    await socket.send(enterRoomFrame(token, liveStreamId, attempt));
+                    for await (const raw of socket.messages) {
+                        if (typeof raw === 'string')
+                            continue;
+                        const frame = decodeFrame(raw);
+                        ctx.log.debug(`ws ${frame.type}`);
+                        if (frame.type === 'SC_ENTER_ROOM_ACK' && !beat) {
+                            const interval = Math.max(1000, Number(frame.payload?.heartbeatIntervalMs ?? 20000));
+                            beat = setInterval(() => void socket.send(heartbeatFrame(rand.now())).catch(() => { }), interval).unref();
+                        }
+                        else if (frame.type === 'SC_FEED_PUSH') {
+                            yield* feedEvents(frame.payload, (id) => gifts.get(id) ?? null);
+                        }
+                        else if (frame.type === 'SC_ERROR') {
+                            ctx.log.warn(`直播服务端报错：${JSON.stringify(frame.payload)}`);
+                        }
+                    }
+                }
+                finally {
+                    if (beat)
+                        clearInterval(beat);
+                    await socket.send(userExitFrame(rand.now())).catch(() => { });
+                    socket.close();
+                }
+            });
+        }
+        finally {
+            k.save();
+        }
+    })();
+}
+// ================================================================ notice
+/** 创作者中心未读通知数。 */
+export async function noticeCount(ctx) {
+    return run(ctx, 'cp', async (k) => {
+        const r = k.check(await api.notificationUnreadCount(k), '通知');
+        const d = r.data ?? {};
+        const num = (...keys) => {
+            for (const key of keys)
+                if (typeof d[key] === 'number')
+                    return d[key];
+            return null;
+        };
+        const total = num('total', 'totalCount', 'unReadCount', 'unreadCount', 'count');
+        return n.noticeCount({
+            total: total ?? undefined,
+            comment: num('comment', 'commentCount'),
+            mention: num('at', 'atCount', 'mention', 'mentionCount'),
+            like: num('like', 'likeCount'),
+            follow: num('follow', 'followCount', 'fans', 'fansCount'),
+            system: num('system', 'systemCount', 'notice', 'noticeCount'),
+        }, r);
+    });
+}