specific-ai-cli 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,241 @@
+import * as n from '../../../core/normalize.js';
+/** 快手原始对象 → 归一化类型（AGENTS 6.2）。字段来源参考上游 utils/data_util.py 的 handle_work_info。 */
+export const photoUrl = (id) => `https://www.kuaishou.com/short-video/${id}`;
+export const profileUrl = (eid) => `https://www.kuaishou.com/profile/${eid}`;
+export const liveUrl = (eid) => `https://live.kuaishou.com/u/${eid}`;
+const first = (o, ...keys) => {
+    for (const k of keys)
+        if (o && o[k] != null && o[k] !== '')
+            return o[k];
+    return undefined;
+};
+export function ref(id, name) {
+    return n.userRef({ id, name, url: id == null || id === '' ? null : profileUrl(id) });
+}
+/** 取 URL：字符串，或 [{url}] / [{cdn,url}] 列表的第一个。 */
+function urlOf(v) {
+    if (typeof v === 'string')
+        return n.url(v);
+    if (Array.isArray(v) && v.length)
+        return urlOf(typeof v[0] === 'object' ? v[0]?.url : v[0]);
+    return null;
+}
+/** 图集：photo.atlas 或 photo.ext_params.atlas，`{cdn, list: [path]}`。 */
+function atlasImages(photo) {
+    const atlas = photo?.atlas ?? photo?.ext_params?.atlas;
+    if (!atlas || typeof atlas !== 'object')
+        return [];
+    let cdn = atlas.cdn ?? '';
+    if (Array.isArray(cdn))
+        cdn = cdn[0] ?? '';
+    return (atlas.list ?? []).map((p) => (cdn ? `https://${cdn}${p}` : p));
+}
+/** manifest.adaptationSet[].representation[]：挑分辨率最高的一路。 */
+export function bestRepresentation(manifest) {
+    const reps = [];
+    for (const set of manifest?.adaptationSet ?? [])
+        for (const r of set?.representation ?? [])
+            if (r?.url)
+                reps.push({ ...r, duration: set.duration });
+    reps.sort((a, b) => (b.width ?? 0) * (b.height ?? 0) - (a.width ?? 0) * (a.height ?? 0) || (b.maxBitrate ?? b.avgBitrate ?? 0) - (a.maxBitrate ?? a.avgBitrate ?? 0));
+    return reps[0];
+}
+/** 作品的媒体：图集为图片，否则取 manifest 最高画质，退回 photoUrl。 */
+export function photoMedia(photo) {
+    const images = atlasImages(photo);
+    if (images.length)
+        return images.map((url, i) => n.media({ id: String(i + 1), type: 'image', url }));
+    const manifest = typeof photo?.manifest === 'object' && photo.manifest ? photo.manifest : null;
+    const best = bestRepresentation(manifest);
+    const duration = n.seconds(photo?.duration != null ? Number(photo.duration) / 1000 : null);
+    if (best)
+        return [n.media({ id: n.idOrNull(best.id), type: 'video', url: n.url(best.url), width: best.width ?? null, height: best.height ?? null, duration }, best)];
+    const url = urlOf(first(photo, 'photoUrl', 'photoUrls', 'mainMvUrls'));
+    return url ? [n.media({ type: 'video', url, width: photo?.width ?? null, height: photo?.height ?? null, duration })] : [];
+}
+/** 一条 feed（`{photo, author, ...}`）或单独的 photo。 */
+export function feed(v, authorFallback) {
+    const photo = v?.photo ?? v;
+    const author = v?.author ?? authorFallback ?? {};
+    const id = n.id(first(photo, 'id', 'photoId', 'photo_id'));
+    const images = atlasImages(photo);
+    const comments = first(photo, 'commentCount', 'comment_count') ?? first(v?.comment, 'us_c', 'commentCount');
+    return n.item({
+        id,
+        kind: images.length ? 'image' : 'video',
+        url: photoUrl(id),
+        text: n.str(first(photo, 'caption', 'originCaption')),
+        author: ref(first(author, 'id', 'authorId', 'user_id', 'eid'), first(author, 'name', 'user_name', 'nickname')),
+        created_at: n.time(first(photo, 'timestamp', 'create_time')),
+        cover: urlOf(first(photo, 'coverUrl', 'coverUrls')),
+        media: photoMedia(photo),
+        stats: {
+            views: n.count(first(photo, 'viewCount', 'view_count')),
+            likes: n.count(first(photo, 'realLikeCount', 'likeCount', 'like_count')),
+            comments: n.count(comments),
+            collects: n.count(first(photo, 'collectCount', 'collect_count')),
+            shares: n.count(first(photo, 'shareCount', 'share_count')),
+        },
+    }, v);
+}
+/** visionVideoDetail。 */
+export function detail(d) {
+    return feed({ ...d, photo: d.photo, author: d.author });
+}
+/** 当前用户资料（/rest/v/profile/get）。 */
+export function selfUser(v) {
+    const id = n.id(first(v, 'eid', 'userDefineId', 'userId', 'user_id'));
+    return n.user({
+        id,
+        name: n.str(first(v, 'userName', 'user_name', 'name')),
+        handle: n.str(first(v, 'kwaiId', 'userId')),
+        avatar: n.url(first(v, 'userHead', 'headurl', 'avatar')),
+        url: profileUrl(id),
+        bio: n.str(first(v, 'userText', 'user_text', 'description')),
+        stats: {
+            followers: n.count(first(v, 'fans', 'fan', 'followerCount')),
+            following: n.count(first(v, 'follows', 'follow', 'followingCount')),
+            items: n.count(first(v, 'photo', 'photoCount', 'photo_public')),
+            likes: n.count(first(v, 'liked', 'likedCount')),
+        },
+    }, v);
+}
+/** visionProfileReduced。 */
+export function reducedUser(v) {
+    const p = v?.userProfile?.profile ?? {};
+    const id = n.id(p.user_id);
+    return n.user({ id, name: n.str(p.user_name), avatar: n.url(p.headurl), url: profileUrl(id), bio: n.str(p.user_text) }, v);
+}
+/** 搜索 / 关注 / 粉丝列表里的用户。 */
+export function listUser(v) {
+    const id = n.id(first(v, 'user_id', 'eid', 'id', 'userId'));
+    return n.user({
+        id,
+        name: n.str(first(v, 'user_name', 'name', 'userName')),
+        handle: n.str(first(v, 'kwaiId', 'kwai_id')),
+        avatar: n.url(first(v, 'headurl', 'headerUrl', 'avatar', 'userHead')),
+        url: profileUrl(id),
+        bio: n.str(first(v, 'user_text', 'description', 'userText')),
+        stats: {
+            followers: n.count(first(v, 'fansCount', 'fans', 'fan')),
+            following: n.count(first(v, 'followCount', 'follows')),
+            items: n.count(first(v, 'photoCount', 'photo')),
+        },
+    }, v);
+}
+/** GraphQL 评论（rootCommentsV2 / subCommentsV2 / REST 的同名字段）。 */
+export function comment(v, itemId, parentId = null) {
+    return n.comment({
+        id: n.id(v.commentId ?? v.comment_id),
+        item_id: itemId,
+        parent_id: parentId,
+        author: ref(first(v, 'authorEid', 'authorId', 'author_id'), first(v, 'authorName', 'author_name')),
+        text: String(v.content ?? ''),
+        created_at: n.time(v.timestamp),
+        stats: { likes: n.count(first(v, 'realLikedCount', 'likedCount')), replies: n.count(first(v, 'subCommentCount')) ?? (v.hasSubComments ? null : 0) },
+    }, v);
+}
+/** 直播首页 home/list 里的直播间（id 用主播 eid，也就是房间页 /u/<eid>）。 */
+export function liveRoom(v) {
+    const author = v?.author ?? {};
+    const eid = n.id(author.id);
+    return n.live({
+        id: eid,
+        url: liveUrl(eid),
+        title: n.str(v.caption),
+        status: v.living || author.living ? 'live' : 'offline',
+        host: n.userRef({ id: eid, name: author.name, url: liveUrl(eid) }),
+        cover: n.url(v.poster),
+        stats: { viewers: n.count(v.watchingCount) },
+    }, v);
+}
+/** 直播回放列表。 */
+export function playback(v, eid) {
+    const id = n.id(first(v, 'id', 'productId', 'photoId'));
+    return n.item({
+        id,
+        kind: 'video',
+        url: `https://live.kuaishou.com/playback/${id}`,
+        title: n.str(first(v, 'caption', 'title')),
+        author: ref(eid, null),
+        created_at: n.time(first(v, 'createTime', 'timestamp')),
+        cover: n.url(first(v, 'poster', 'coverUrl')),
+        stats: { views: n.count(v.viewCount), likes: n.count(v.likeCount), comments: n.count(v.commentCount) },
+    }, v);
+}
+/** 创作者中心作品管理的状态。 */
+function workStatus(v) {
+    const s = Number(first(v, 'publishStatus', 'status', 'auditStatus'));
+    if (!Number.isFinite(s))
+        return null;
+    if (v?.photoStatus === 2 || v?.privacy === 2)
+        return 'private';
+    if (s === 1 || s === 3)
+        return 'published';
+    if (s === 2 || s === 0)
+        return 'reviewing';
+    // 真机（2026-09-29）：仅自己可见的作品都是 publishStatus 4、judgementStatus 1、没有驳回原因，公开主页上看不到
+    if (s === 4)
+        return 'private';
+    if (s < 0)
+        return 'rejected';
+    return null;
+}
+/** 作品管理页（photo/list）的一行。 */
+export function work(v) {
+    const id = n.id(first(v, 'workId', 'photoId', 'photoIdStr', 'publishId'));
+    return n.item({
+        id,
+        // 作品管理的列表没有 photoType：多图图集有 showAtlasIcon；单图没有图集图标，但不显示时长、时长为 0（视频是 showDuration: true）
+        kind: first(v, 'atlasId') || v?.photoType === 1 || v?.showAtlasIcon === true || (v?.showDuration === false && !Number(v?.durationSecond)) ? 'image' : 'video',
+        url: first(v, 'workId', 'photoId', 'photoIdStr') ? photoUrl(id) : null,
+        text: n.str(first(v, 'caption', 'title')),
+        author: v?.userIdStr ? n.userRef({ id: String(v.userIdStr), name: n.str(v.userName), url: profileUrl(v.userIdStr) }) : null,
+        created_at: n.time(first(v, 'publishTime', 'uploadTime', 'createTime')),
+        cover: n.url(first(v, 'coverUrl', 'publishCoverUrl', 'cover')),
+        stats: {
+            views: n.count(first(v, 'playCount', 'viewCount')),
+            likes: n.count(first(v, 'likeCount')),
+            comments: n.count(first(v, 'commentCount')),
+            collects: n.count(first(v, 'collectCount')),
+            shares: n.count(first(v, 'shareCount')),
+        },
+        status: workStatus(v),
+    }, v);
+}
+/** 礼物面板的一项（gift-list 的 `gifts[]`）。价格是快币。 */
+export function gift(g) {
+    return n.gift({ id: n.id(g.id), name: String(g.name ?? ''), price: g.unitPrice != null ? { amount: Number(g.unitPrice), currency: 'KSCOIN' } : null }, g);
+}
+/**
+ * 礼物字典的 `[id, 名字]`：gift-list 是 `{gifts: [...]}`；allgifts 是以礼物 id 为键的对象，
+ * 也兼容数组形式（`gifts` / `list`）。
+ */
+export function giftNames(d) {
+    const out = [];
+    const push = (id, g) => {
+        const key = g?.id ?? id;
+        if (key != null && key !== '' && g?.name)
+            out.push([String(key), String(g.name)]);
+    };
+    const list = Array.isArray(d) ? d : (d?.gifts ?? d?.list);
+    if (Array.isArray(list))
+        for (const g of list)
+            push(null, g);
+    else if (d && typeof d === 'object')
+        for (const [id, g] of Object.entries(d))
+            if (g && typeof g === 'object')
+                push(id, g);
+    return out;
+}
+/**
+ * 发布后管理页的那一行，合并 publish/refresh 里同一个 publishId 的状态。
+ * 作品真正发布出来之前没有 workId，这时 id 是 publishId、url 为空。
+ */
+export function publishedWork(row, refresh) {
+    const id = row?.publishId;
+    const d = refresh?.data;
+    const rows = Array.isArray(d) ? d : Array.isArray(d?.list) ? d.list : d && typeof d === 'object' ? Object.values(d) : [];
+    const match = rows.find((r) => r && typeof r === 'object' && String(r.publishId ?? r.id) === String(id));
+    return work({ ...row, ...(match ?? {}) });
+}

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

@@ -0,0 +1,329 @@
+import { createHash } from 'node:crypto';
+import * as fs from 'node:fs';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { basename, dirname, isAbsolute, join } from 'node:path';
+import { format } from 'node:util';
+import vm from 'node:vm';
+import { SpecificAIError } from '../../../core/errors.js';
+import { cacheDir, staticFile } from '../../../core/paths.js';
+import { DEFAULT_SEED, isDeterministic, now } from '../../../core/rand.js';
+import { createContext } from '../../../core/vm.js';
+import { compactJson } from '../../../core/py.js';
+import { ACCEPT_ENCODING, ACCEPT_LANGUAGE, UA } from './profile.js';
+/**
+ * webweapon 预言机（上游 utils/sign/weapon_oracle.py、like_token.py）：在 node:vm 里跑官方 kwf / kws 脚本
+ * 与 likeData token 引擎，产出 `kwfv1` / `kwscode` / 指纹上报 / like token。
+ *
+ * 上游把 reverse/tools/*_oracle.js 当命令行脚本起子进程（读环境变量、往 stdout 打印 JSON）；
+ * 这里在 vm 里按 CommonJS 执行同一份脚本（static/kuaishou/ 原样复制），由包装层喂环境变量、收 stdout。
+ * 预言机自己会 `require('vm').createContext` 再跑官方脚本：确定性模式（对拍）下给这些内层 context
+ * 也注入固定的 Math.random / Date，与 scripts/golden/kuaishou/vm_determinism.cjs 一致。
+ */
+const hostRequire = createRequire(import.meta.url);
+const P = 'kuaishou';
+export const KWF_ORACLE = staticFile(P, 'tools/kwf_oracle.js');
+export const KWS_ORACLE = staticFile(P, 'tools/kws_oracle.js');
+export const LIKE_ORACLE = staticFile(P, 'tools/like_token_oracle.js');
+export const WEAPON_DIR = staticFile(P, 'bundles/weapon');
+const KWF_CURRENT_SCRIPT = staticFile(P, 'js/cp-kwf.js');
+const KWF_LEGACY_NAME = 'kwf-0.0.2.2cee19b4b7dec496.js';
+const KWF_LEGACY_SCRIPT = join(WEAPON_DIR, KWF_LEGACY_NAME);
+const KWF_CURRENT_CAPTURE_NAME = 'kwf-0.1.1.a6d1e5d478c2cafa.js';
+const KWF_NEW_GENERATION_COUNTER = 999;
+const HEX64 = /^[0-9a-f]{64}$/;
+const KWS_FILENAME = /^kws-(\d+)-0\.0\.1-obfuscated\.([0-9a-f]{16})\.js$/;
+const KWS_MIN_BYTES = 32_000;
+const KWS_MAX_BYTES = 128_000;
+const sources = new Map();
+function source(file) {
+    let s = sources.get(file);
+    if (s == null)
+        sources.set(file, (s = fs.readFileSync(file, 'utf8')));
+    return s;
+}
+/**
+ * 确定性模式下注入内层 context 的代码，与 scripts/golden/kuaishou/vm_determinism.cjs 逐字相同。
+ * Date 不能用 `class extends Date`：like token 的 VM 用 `constructor.prototype` 找原型，子类会无限循环。
+ */
+const INNER_PATCH = (seed, fixed) => `(() => {
+  let a = ${seed} >>> 0
+  Math.random = () => {
+    a = (a + 0x6d2b79f5) >>> 0
+    let t = Math.imul(a ^ (a >>> 15), a | 1)
+    t = (t + Math.imul(t ^ (t >>> 7), t | 61)) ^ t
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+  }
+  const D = Date
+  const F = function Date(...a) {
+    if (!new.target) return new D(${fixed}).toString()
+    return new D(...(a.length ? a : [${fixed}]))
+  }
+  F.prototype = D.prototype
+  F.now = () => ${fixed}
+  F.parse = D.parse
+  F.UTC = D.UTC
+  globalThis.Date = F
+})()`;
+/** 预言机里 `require('vm')` 拿到的模块：确定性模式下每个新 context 都从种子重新开始。 */
+function oracleVm() {
+    if (!isDeterministic())
+        return vm;
+    const patch = INNER_PATCH(DEFAULT_SEED, now());
+    return {
+        ...vm,
+        createContext(sandbox, options) {
+            const ctx = vm.createContext(sandbox, options);
+            vm.runInContext(patch, ctx);
+            return ctx;
+        },
+    };
+}
+class OracleExit extends Error {
+    code;
+    constructor(code) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+/**
+ * 按 CommonJS 执行一个预言机脚本，返回它写到 stdout 的内容。env 只含预言机要的 KS_* 变量。
+ */
+function runOracle(file, options) {
+    const out = [];
+    const err = [];
+    const env = {};
+    for (const [k, v] of Object.entries(options.env))
+        if (v != null)
+            env[k] = v;
+    const fakeProcess = {
+        env,
+        argv: ['node', file, ...(options.argv ?? [])],
+        platform: process.platform,
+        versions: process.versions,
+        nextTick: process.nextTick,
+        exit(code = 0) {
+            throw new OracleExit(code);
+        },
+        stdout: { write: (s) => (out.push(String(s)), true) },
+        stderr: { write: (s) => (err.push(String(s)), true) },
+    };
+    const fakeConsole = {
+        log: (...a) => out.push(format(...a) + '\n'),
+        info: (...a) => out.push(format(...a) + '\n'),
+        error: (...a) => err.push(format(...a) + '\n'),
+        warn: (...a) => err.push(format(...a) + '\n'),
+        debug: () => { },
+    };
+    const vmModule = oracleVm();
+    const fsModule = {
+        ...fs,
+        readFileSync: (p, ...rest) => (p === 0 ? (options.stdin ?? '') : fs.readFileSync(p, ...rest)),
+    };
+    const module = { exports: {} };
+    const req = ((id) => (id === 'vm' ? vmModule : id === 'fs' ? fsModule : hostRequire(id)));
+    Object.assign(req, { main: module, resolve: hostRequire.resolve, cache: {} });
+    const context = createContext({
+        require: req,
+        module,
+        exports: module.exports,
+        __filename: file,
+        __dirname: dirname(file),
+        process: fakeProcess,
+        console: fakeConsole,
+    });
+    try {
+        vm.runInContext(source(file), context, { filename: file });
+    }
+    catch (e) {
+        if (!(e instanceof OracleExit) || e.code !== 0) {
+            const detail = err.join('').trim().slice(0, 300);
+            throw new SpecificAIError('ERROR', `快手 webweapon 预言机 ${basename(file)} 执行失败${detail ? `：${detail}` : ''}`, { cause: e });
+        }
+    }
+    return out.join('').trim();
+}
+function lastJson(out) {
+    const lines = out.split(/\r?\n/);
+    try {
+        return JSON.parse(lines[lines.length - 1] ?? '');
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------- kwf
+/**
+ * 按持久化的 kwfcv1 计数器或 gdfp 下发的 fpUrl 选择 kwf 脚本（_kwf_script_for_counter）：
+ * fpUrl 只接受已抓包的两个内容寻址文件名，未知脚本直接失败；没有 fpUrl 时计数器 >= 999 用 0.1.1。
+ */
+export function kwfScriptFor(kwfcv1 = '', scriptPath = '') {
+    if (scriptPath) {
+        if (fs.existsSync(scriptPath))
+            return scriptPath;
+        let name;
+        try {
+            name = basename(decodeURIComponent(new URL(scriptPath).pathname)).toLowerCase();
+        }
+        catch {
+            name = basename(scriptPath).toLowerCase();
+        }
+        if (name === KWF_CURRENT_CAPTURE_NAME)
+            return KWF_CURRENT_SCRIPT;
+        if (name === KWF_LEGACY_NAME.toLowerCase())
+            return KWF_LEGACY_SCRIPT;
+        throw new SpecificAIError('UPSTREAM', `快手下发了未收录的 kwf 脚本：${scriptPath}`, { detail: { kind: 'webweapon', fpUrl: scriptPath } });
+    }
+    if (Number.parseInt(kwfcv1, 10) >= KWF_NEW_GENERATION_COUNTER)
+        return KWF_CURRENT_SCRIPT;
+    return '';
+}
+function hostnameOf(href, fallback) {
+    return /^https?:\/\/([^/]+)/.exec(href)?.[1] ?? fallback;
+}
+/** gen_kwfv1：跑官方 kwf 脚本产出当前 kwfv1（174 或 218 字符），连同更新后的 kwfcv1 计数器。 */
+export function genKwfv1(o) {
+    const script = kwfScriptFor(o.kwfcv1 ?? '', o.scriptPath ?? '');
+    const out = runOracle(KWF_ORACLE, {
+        argv: ['--json'],
+        env: {
+            KS_DID: o.did,
+            KS_HREF: o.href,
+            KS_HOSTNAME: hostnameOf(o.href, 'www.kuaishou.com'),
+            KS_COOKIE: o.cookie || (o.did ? `did=${o.did}` : ''),
+            KS_KWFCV1: o.kwfcv1 ?? '',
+            KS_KWFV1: o.currentKwfv1 ?? '',
+            KS_HARDWARE_CONCURRENCY: '20',
+            KS_KWF_SCRIPT: script || undefined,
+        },
+    });
+    const state = lastJson(out) ?? {};
+    const value = String(state.value ?? '');
+    return { value, kwfv1: String(state.kwfv1 || value), kwfcv1: String(state.kwfcv1 || o.kwfcv1 || '') };
+}
+/** gen_fingerprint_report：kwf 的 getData(1)，作为 gdfp /s/w/p 的 data。 */
+export function genFingerprintReport(o) {
+    const script = kwfScriptFor(o.kwfcv1 ?? '', '');
+    const out = runOracle(KWF_ORACLE, {
+        argv: ['--json'],
+        env: {
+            KS_DID: o.did,
+            KS_HREF: o.href,
+            KS_HOSTNAME: hostnameOf(o.href, 'cp.kuaishou.com'),
+            KS_COOKIE: o.cookie || (o.did ? `did=${o.did}` : ''),
+            KS_KWFCV1: o.kwfcv1 ?? '',
+            KS_KWFV1: o.currentKwfv1 ?? '',
+            KS_HARDWARE_CONCURRENCY: '20',
+            KS_KWF_REPORT_MODE: '1',
+            KS_KWF_SCRIPT: script || undefined,
+        },
+    });
+    return String(lastJson(out)?.value ?? '');
+}
+// ---------------------------------------------------------------- kws
+function looksLikeOfficialKws(content) {
+    if (content.length < KWS_MIN_BYTES || content.length > KWS_MAX_BYTES)
+        return false;
+    if (!content.subarray(0, 256).toString('latin1').trimStart().startsWith('(function(){'))
+        return false;
+    return content.subarray(0, 16_000).includes('function') && content.includes('window') && /[A-Za-z0-9+/=]{20000,}/.test(content.toString('latin1'));
+}
+/** 文件名里的 hash 是脚本 MD5 的中间 16 位。 */
+function kwsHashMatches(name, content) {
+    const m = KWS_FILENAME.exec(name);
+    return Boolean(m && createHash('md5').update(content).digest('hex').slice(8, 24) === m[2]);
+}
+/** 校验 signUrl（官方内容寻址的 static.yximgs.com 地址），返回文件名。 */
+function kwsName(signUrl) {
+    let u;
+    try {
+        u = new URL(signUrl);
+    }
+    catch {
+        throw new SpecificAIError('UPSTREAM', `KWS signUrl 不合法：${signUrl}`);
+    }
+    const host = u.hostname.toLowerCase();
+    const name = basename(decodeURIComponent(u.pathname));
+    const query = [...u.searchParams];
+    const ok = u.protocol === 'https:' &&
+        !u.username &&
+        !u.password &&
+        (u.port === '' || u.port === '443') &&
+        (host === 'static.yximgs.com' || host.endsWith('.static.yximgs.com')) &&
+        !u.hash &&
+        u.pathname.toLowerCase().includes('/kws/') &&
+        (query.length === 0 || (query.length === 1 && query[0][0] === 'x-kcdn-pid' && /^\d+$/.test(query[0][1]))) &&
+        KWS_FILENAME.test(name);
+    if (!ok)
+        throw new SpecificAIError('UPSTREAM', `KWS signUrl 不符合官方脚本地址：${signUrl}`, { detail: { kind: 'webweapon' } });
+    return name;
+}
+/**
+ * 找到 signUrl 指定的那一份 kws 脚本：先找随包的已抓副本，再找本机缓存，都没有就下载（校验内容与 MD5）。
+ * 绝不用别的变体替代。
+ */
+export async function resolveKwsScript(signUrl, href, http) {
+    const name = kwsName(signUrl);
+    const bundled = join(WEAPON_DIR, name);
+    if (fs.existsSync(bundled))
+        return bundled;
+    const cached = join(cacheDir(P), 'kws', name);
+    if (fs.existsSync(cached)) {
+        const content = await readFile(cached);
+        if (looksLikeOfficialKws(content) && kwsHashMatches(name, content))
+            return cached;
+    }
+    const res = await http.request({
+        url: signUrl,
+        redirect: 'manual',
+        cookies: false,
+        headers: [
+            ['user-agent', UA],
+            ['accept', '*/*'],
+            ['accept-encoding', ACCEPT_ENCODING],
+            ['accept-language', ACCEPT_LANGUAGE],
+            ['referer', href || 'https://www.kuaishou.com/new-reco'],
+            ['sec-fetch-dest', 'script'],
+            ['sec-fetch-mode', 'no-cors'],
+            ['sec-fetch-site', 'cross-site'],
+        ],
+    });
+    if (res.status !== 200)
+        throw new SpecificAIError('UPSTREAM', `下载 KWS 脚本失败：HTTP ${res.status}`, { detail: { kind: 'webweapon', url: signUrl } });
+    const content = Buffer.from(await res.arrayBuffer());
+    if (!looksLikeOfficialKws(content) || !kwsHashMatches(name, content)) {
+        throw new SpecificAIError('UPSTREAM', 'KWS 脚本内容与文件名 hash 不一致', { detail: { kind: 'webweapon', url: signUrl } });
+    }
+    await mkdir(dirname(cached), { recursive: true });
+    const tmp = `${cached}.${process.pid}.tmp`;
+    await writeFile(tmp, content);
+    await rename(tmp, cached);
+    return cached;
+}
+/** gen_kwscode：执行 /s/w/c 指派的那一份 kws 脚本，产出 64 位小写 hex 的 kwscode。 */
+export async function genKwscode(o) {
+    const script = await resolveKwsScript(o.signUrl, o.href, o.http);
+    const out = runOracle(KWS_ORACLE, {
+        argv: [isAbsolute(script) ? script : join(WEAPON_DIR, script), '--json'],
+        env: {
+            KS_SECTOKEN: o.secToken,
+            KS_DID: o.did,
+            KS_HREF: o.href,
+            KS_COOKIE: o.did ? `did=${o.did}` : '',
+            KS_KWS_SCRIPT_URL: o.signUrl,
+        },
+    });
+    const code = String(lastJson(out)?.kwscode ?? '');
+    if (!HEX64.test(code)) {
+        throw new SpecificAIError('UPSTREAM', 'KWS 脚本没有产出合法的 kwscode（环境检测或脚本漂移）', { detail: { kind: 'webweapon', kwscode: code.slice(0, 80) } });
+    }
+    return code;
+}
+// ---------------------------------------------------------------- like token
+/** likeDataQuery 的 56 位 hex token：输入是 {did, ts, uri} 的值按键排序后用 `:` 连接，交给抓包 bundle 的 $encode 引擎。 */
+export function genLikeToken(did, ts, uri = '/rest/v/feed/myfollow') {
+    const out = runOracle(LIKE_ORACLE, { stdin: compactJson({ did, ts, uri }), env: {} });
+    if (!/^[0-9a-f]{56}$/.test(out))
+        throw new SpecificAIError('ERROR', `like token 引擎输出不合法：${out.slice(0, 80)}`);
+    return out;
+}