specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/platforms/jd/web/chat.js

@@ -0,0 +1,132 @@
+import { jsonLoads, quote } from '../../../core/py.js';
+import * as rand from '../../../core/rand.js';
+import { openSocket } from '../../../core/stream.js';
+import { CHAT_ORIGIN, WS_HEADERS } from './profile.js';
+import { generateWid } from './util.js';
+/**
+ * 京东咚咚 WebSocket（上游 jd_apis/jd_chat_ws.py 的 JdChatWS）：纯 JSON 帧，信封由 packing() 生成，
+ * aid 必须在顶层；建连后先心跳再欢迎语；心跳 30 秒一次且不带 id。
+ */
+/** 咚咚消息类型（MsgType，取自 bundle 模块 5a50 的常量表）。 */
+export const MsgType = {
+    CHAT_MESSAGE: 'chat_message',
+    CHAT_MESSAGE_RESULT: 'chat_message_result',
+    CHAT_SESSION_OPEN: 'chat_session_open',
+    CHAT_SESSION_CLOSE: 'chat_session_close',
+    CHAT_CUSTOMER_LEAVE: 'chat_customer_leave',
+    CLIENT_HEARTBEAT: 'client_heartbeat',
+    EVENT_MESSAGE: 'event_message',
+    SYS_MSG: 'sys_msg',
+    FAILURE: 'failure',
+    AUTH: 'auth',
+    AUTH_RESULT: 'auth_result',
+    ACK: 'ack',
+    REVOKE_MESSAGE: 'revoke_message',
+    MSG_READ_ACK: 'msg_read_ack',
+    MSG_RECEIVE_ACK: 'msg_receive_ack',
+};
+export const HOSTS = ['ws1-dd.jd.com', 'ws0-dd.jd.com', 'ws3-dd.jd.com'];
+const CUSTOMER_APP = 'im.customer';
+export const WAITER_APP = 'jd.waiter';
+const CLIENT_TYPE = 'comet';
+const VER = '4.2';
+export const HEARTBEAT_INTERVAL = 30_000;
+/** 本地时间 `YYYY-MM-DD HH:MM:SS`（datetime.now().strftime）。 */
+function localDatetime(ms) {
+    const d = new Date(ms);
+    const p = (v) => String(v).padStart(2, '0');
+    return `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+export class ChatClient {
+    jd;
+    venderId;
+    venderApp;
+    url;
+    socket = null;
+    constructor(jd, venderId = '1', venderApp = WAITER_APP, host = HOSTS[0]) {
+        this.jd = jd;
+        this.venderId = venderId;
+        this.venderApp = venderApp;
+        const chat = jd.chat;
+        const params = [
+            ['pin', quote(jd.pin ?? '', '')],
+            ['appId', chat.app_id || CUSTOMER_APP],
+            ['aid', chat.aid ?? ''],
+            ['clientType', chat.client_type || CLIENT_TYPE],
+            ['_wid_', generateWid()],
+        ];
+        this.url = `wss://${host}/?${params.map(([k, v]) => `${k}=${v}`).join('&')}`;
+    }
+    /** 信封（packing）。 */
+    packing(type, body, to, id) {
+        const packet = {
+            from: { app: CUSTOMER_APP, pin: this.jd.pin ?? '', clientType: CLIENT_TYPE },
+            datetime: localDatetime(rand.now()),
+            ver: VER,
+            lang: 'zh_CN',
+            aid: this.jd.chat.aid ?? '',
+            type,
+            to: to ?? { app: this.venderApp },
+            timestamp: rand.now(),
+        };
+        if (type !== MsgType.CLIENT_HEARTBEAT)
+            packet.id = id || rand.uuid4().replaceAll('-', '');
+        if (body && Object.keys(body).length)
+            packet.body = body;
+        return packet;
+    }
+    chatinfo(pid = '', orderId = '') {
+        const info = { venderId: this.venderId, ct: '3', mt: '51' };
+        if (pid)
+            info.pid = pid;
+        if (orderId)
+            info.orderId = orderId;
+        return info;
+    }
+    textPacket(text, pid = '', orderId = '') {
+        return this.packing(MsgType.CHAT_MESSAGE, { content: text, type: 'text', chatinfo: this.chatinfo(pid, orderId) });
+    }
+    /** 会话首帧（sendHello）：type=config + cfg.welcome。 */
+    helloPacket(pid = '', orderId = '') {
+        let content = `顾客${this.jd.pin}发起咨询`;
+        if (pid)
+            content += `（商品编号：${pid}）`;
+        if (orderId)
+            content += `（订单编号：${orderId}）`;
+        return this.packing(MsgType.CHAT_MESSAGE, {
+            content,
+            type: 'config',
+            chatinfo: this.chatinfo(pid, orderId),
+            uniformBizInfo: {},
+            action: { code: 'cfg.welcome' },
+        });
+    }
+    /** 心跳发给自己这一侧（to.app = im.customer）。 */
+    heartbeatPacket() {
+        return this.packing(MsgType.CLIENT_HEARTBEAT, null, { app: CUSTOMER_APP });
+    }
+    async connect(signal) {
+        this.socket = await openSocket(this.url, {
+            headers: { ...WS_HEADERS, Cookie: this.jd.cookieStr, Origin: CHAT_ORIGIN },
+            signal,
+        });
+        return this.socket;
+    }
+    async send(packet) {
+        await this.socket.send(JSON.stringify(packet));
+    }
+    close() {
+        this.socket?.close();
+        this.socket = null;
+    }
+}
+/** 下行帧：单个对象或数组。 */
+export function packets(raw) {
+    try {
+        const v = jsonLoads(typeof raw === 'string' ? raw : raw.toString('utf8'));
+        return Array.isArray(v) ? v : [v];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/platforms/jd/web/client.js

@@ -0,0 +1,470 @@
+import { createCipheriv } from 'node:crypto';
+import { SpecificAIError } from '../../../core/errors.js';
+import * as n from '../../../core/normalize.js';
+import { HttpClient, parseJsonp } from '../../../core/http.js';
+import { compactJson, jsonDumps, jsonLoads, quote, unquote } from '../../../core/py.js';
+import * as rand from '../../../core/rand.js';
+import { authError, scope } from '../../../core/toolkit.js';
+import { DEVICE_PROFILE, DeviceToken, H5st } from './js.js';
+import { API_URL, APPID_PC_ITEM, AXIOS_ORDER, BROWSER, CLIENT_WH5, COOKIE_DOMAIN, FETCH_ORDER, H5ST_SIGN_KEYS, ITEM_ORIGIN, ITEM_REFERER, PROFILE, SEARCH_REFERER, xhr, } from './profile.js';
+import { sha256Hex } from './util.js';
+/**
+ * 京东 web 端的会话（上游 builder/auth.py 的 JdAuth + jd_apis/jd_api.py 的 call_api）。
+ *
+ * 上游的 cookie 是一张不分域的有序表，发往所有京东站点，响应里的 Set-Cookie 按名字合并（空值即删除）；
+ * 这里照搬：凭证里的 cookie 统一记在 `.jd.com` 下，请求时显式带上整张表。
+ * 按 origin 保存的 localStorage 放在凭证的 device.local_storage，咚咚会话参数放在 extra.chat。
+ */
+/** SimpleCookie 认得的属性（其余 key=value 会被它当作新 cookie）。 */
+const RESERVED = new Set(['expires', 'path', 'comment', 'domain', 'max-age', 'secure', 'httponly', 'version', 'samesite']);
+const FLAGS = new Set(['secure', 'httponly']);
+/** 合法的 cookie 名（签名脚本交回的 cookie 按它过滤）。 */
+const COOKIE_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** `http.cookies.SimpleCookie().load(line)` 的结果：解析失败时为空。 */
+export function simpleCookie(line) {
+    const patt = /\s*(?<key>[\w\d!#%&'~_`><@,:/$*+\-.^|)(?}{=]+?)(\s*=\s*(?<val>"(?:[^\\"]|\\.)*"|\w{3},\s[\w\d\s-]{9,11}\s[\d:]{8}\sGMT|[\w\d!#%&'~_`><@,:/$*+\-.^|)(?}{=\[\]]*))?\s*(\s+|;|$)/y;
+    const items = [];
+    let seen = false;
+    let i = 0;
+    while (i < line.length) {
+        patt.lastIndex = i;
+        const m = patt.exec(line);
+        if (!m || m[0].length === 0)
+            break;
+        i = patt.lastIndex;
+        const key = m.groups.key;
+        const value = m.groups.val;
+        if (key[0] === '$')
+            continue;
+        const lower = key.toLowerCase();
+        if (RESERVED.has(lower)) {
+            if (!seen)
+                return [];
+            if (value == null && !FLAGS.has(lower))
+                return [];
+        }
+        else if (value != null) {
+            items.push([key, cookieUnquote(value)]);
+            seen = true;
+        }
+        else
+            return [];
+    }
+    return items;
+}
+function cookieUnquote(v) {
+    if (v.length < 2 || v[0] !== '"' || v[v.length - 1] !== '"')
+        return v;
+    return v.slice(1, -1).replace(/\\(?:([0-3][0-7][0-7])|(.))/g, (_, oct, ch) => (oct ? String.fromCharCode(parseInt(oct, 8)) : ch));
+}
+export class Jd {
+    ctx;
+    http;
+    h5st;
+    device;
+    /** 与凭证同步的有序 cookie 表。 */
+    cookies;
+    /** searchWare 记下的关键词，后续同页请求用同一个 Referer。 */
+    searchKeyword = '';
+    constructor(ctx) {
+        this.ctx = ctx;
+        this.http = new HttpClient({ browser: BROWSER, os: 'windows', proxy: ctx.config.proxy, timeout: ctx.config.timeout, log: ctx.log });
+        this.cookies = new Map(scope(ctx.credential).cookies.map((c) => [c.name, c.value]));
+        const host = { http: this.http, log: ctx.log };
+        this.h5st = new H5st(host, {
+            load: () => {
+                const c = ctx.credential.device.h5st;
+                return c?.profile === PROFILE.profileId ? c : null;
+            },
+            save: (cache) => {
+                ctx.credential.device.h5st = cache;
+            },
+        });
+        this.device = new DeviceToken(host);
+    }
+    // ---------------------------------------------------------------- cookie
+    get cookieStr() {
+        return [...this.cookies].map(([k, v]) => `${k}=${v}`).join('; ');
+    }
+    cookie(name) {
+        return this.cookies.get(name);
+    }
+    /** 合并 cookie；空值按服务端删除指令处理（update_cookies）。 */
+    update(values) {
+        const entries = Symbol.iterator in Object(values) ? values : Object.entries(values);
+        let changed = false;
+        for (const [key, value] of entries) {
+            if (value == null || value === '') {
+                if (this.cookies.delete(key))
+                    changed = true;
+            }
+            else if (this.cookies.get(key) !== String(value)) {
+                this.cookies.set(key, String(value));
+                changed = true;
+            }
+        }
+        if (changed)
+            this.persist();
+    }
+    persist() {
+        const old = new Map(scope(this.ctx.credential).cookies.map((c) => [c.name, c]));
+        const list = [];
+        for (const [name, value] of this.cookies) {
+            const prev = old.get(name);
+            list.push({ name, value, domain: COOKIE_DOMAIN, path: '/', expires: prev?.value === value ? (prev.expires ?? null) : null });
+        }
+        scope(this.ctx.credential).cookies.splice(0, Infinity, ...list);
+    }
+    /** 吸收响应的 Set-Cookie 与 `x-rp-sdtoken`（absorb_response + _absorb_response）。 */
+    absorb(res) {
+        const lines = res.headers.getSetCookie();
+        for (const line of lines)
+            this.update(simpleCookie(line));
+        const jar = new Map();
+        for (const line of lines) {
+            const i = line.indexOf('=');
+            if (i < 0)
+                continue;
+            jar.set(line.slice(0, i).trim(), line.slice(i + 1).split(';', 1)[0].trim());
+        }
+        this.update([...jar].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+        const raw = res.headers.get('x-rp-sdtoken');
+        if (raw?.startsWith('set;')) {
+            const parts = splitN(raw, ';', 2);
+            if (parts.length === 3)
+                this.update([['sdtoken', parts[2]]]);
+        }
+    }
+    /** 登录态（thor 或 pt_key，加 pin）。 */
+    get pin() {
+        const raw = this.cookie('pin') || this.cookie('pt_pin') || this.cookie('_pst');
+        return raw ? unquote(raw) : null;
+    }
+    get isLogin() {
+        return Boolean((this.cookie('thor') || this.cookie('pt_key')) && this.pin);
+    }
+    // ---------------------------------------------------------------- localStorage 与咚咚会话
+    get storage() {
+        return (this.ctx.credential.device.local_storage ??= {});
+    }
+    static storageOrigin(pageUrl) {
+        try {
+            const u = new URL(pageUrl);
+            if (u.protocol && u.host)
+                return `${u.protocol}//${u.host}`.toLowerCase();
+        }
+        catch { }
+        return String(pageUrl ?? '');
+    }
+    localStorageFor(pageUrl) {
+        return { ...(this.storage[Jd.storageOrigin(pageUrl)] ?? {}) };
+    }
+    replaceLocalStorage(pageUrl, values) {
+        const origin = Jd.storageOrigin(pageUrl);
+        if (!origin || !values || typeof values !== 'object')
+            return;
+        this.storage[origin] = Object.fromEntries(Object.entries(values).filter(([, v]) => v != null).map(([k, v]) => [k, String(v)]));
+    }
+    get chat() {
+        return (this.ctx.credential.extra.chat ??= { aid: null, app_id: 'im.customer', dvc: null, client_type: 'comet' });
+    }
+    setChatInfo(values) {
+        for (const [k, v] of Object.entries(values))
+            if (v)
+                this.chat[k] = v;
+    }
+    get deviceProfile() {
+        return this.ctx.credential.device.profile ?? null;
+    }
+    setDeviceProfile(value) {
+        if (value)
+            this.ctx.credential.device.profile = value;
+    }
+    /** 签名脚本（WebM / JCAP 的 run.js）写的 cookie 与 localStorage 交回会话。 */
+    absorbScript(pageUrl, result) {
+        if (result.cookies && typeof result.cookies === 'object') {
+            this.update(Object.entries(result.cookies).filter(([k]) => COOKIE_NAME.test(k)).map(([k, v]) => [k, String(v ?? '')]));
+        }
+        if (result.localStorage && typeof result.localStorage === 'object')
+            this.replaceLocalStorage(pageUrl, result.localStorage);
+    }
+    // ---------------------------------------------------------------- 设备票据
+    /** 用 pc-tk.js 换设备票据写进 cookie；画像版本变化时强制换新。 */
+    async refreshDevice(page, origin, referer) {
+        this.device.configure(this.cookieStr, page, origin, referer);
+        const force = this.deviceProfile !== DEVICE_PROFILE;
+        const d = await this.device.get(force);
+        this.update([
+            ['3AB9D23F7A4B3C9B', d.eid],
+            ['3AB9D23F7A4B3CSS', d.eid2],
+            ...(d.giaD ? [['_gia_d', d.giaD]] : []),
+        ]);
+        this.setDeviceProfile(DEVICE_PROFILE);
+        return d;
+    }
+    // ---------------------------------------------------------------- 请求
+    /** 发请求并吸收 cookie。默认显式带整张 cookie 表。 */
+    async send(req) {
+        const res = await this.http.request({ cookies: Object.fromEntries(this.cookies), ...req });
+        this.absorb(res);
+        return res;
+    }
+    /** 签 h5st（builder/params.py with_h5st）：body 先取 SHA-256。 */
+    async signH5st(params, appId) {
+        const sign = {};
+        for (const k of H5ST_SIGN_KEYS)
+            if (params.has(k))
+                sign[k] = params.get(k);
+        if ('body' in sign)
+            sign.body = sha256Hex(String(sign.body));
+        return String((await this.h5st.sign(sign, appId)).h5st ?? '');
+    }
+    /**
+     * api.m.jd.com 通用调用（JdAPI.call_api）：装配 query → 算 h5st → 发请求；403 空 body 时重签重试。
+     * 返回平台原始 JSON（或 jsonp 解开后的对象）；风控处置（x-rp-content）命中时照样返回原始结果，
+     * 解开的处置挂在不可枚举的 `_disposal` 上，由 checkRisk 报 RISK_CONTROL。
+     */
+    async call(functionId, o = {}) {
+        const method = o.method ?? 'POST';
+        const sign = o.sign ?? true;
+        const withTime = o.withTime ?? true;
+        const retry = o.retry ?? 2;
+        const params = new Map();
+        for (const [k, v] of Object.entries(o.client ?? CLIENT_WH5))
+            if (!params.has(k))
+                params.set(k, v);
+        params.set('functionId', functionId);
+        if (o.withUuid ?? true) {
+            const uuid = o.uuid ?? this.cookie('__jdu');
+            if (uuid)
+                params.set('uuid', uuid);
+        }
+        if (o.body !== undefined)
+            params.set('body', typeof o.body === 'string' ? o.body : compactJson(o.body));
+        if (o.jsonp)
+            params.set('jsonp', o.jsonp);
+        for (const [k, v] of o.extra ?? [])
+            params.set(k, v);
+        if (sign)
+            this.h5st.configure(this.cookieStr, o.origin || ITEM_ORIGIN, o.referer || ITEM_REFERER);
+        const eid = this.cookie('3AB9D23F7A4B3CSS');
+        if (eid)
+            params.set('x-api-eid-token', eid);
+        for (const k of o.drop ?? [])
+            params.delete(k);
+        const axios = o.axios ?? Boolean(o.rpClient);
+        let h;
+        if (o.jsonp)
+            throw new Error('jsonp 调用未移植');
+        else if (method !== 'POST' || o.bodyInQuery)
+            h = xhr({ axios, accept: o.accept });
+        else
+            h = xhr({ axios, form: true, accept: o.accept });
+        if (o.contentType != null)
+            h.set('content-type', o.contentType);
+        h.referer(o.referer || ITEM_REFERER);
+        if (o.origin)
+            h.origin(o.origin);
+        if (o.rpClient) {
+            h.set('x-referer-page', o.refererPage || (o.origin ?? '') + '/');
+            h.set('x-rp-client', o.rpClient);
+        }
+        h.reorder(axios ? AXIOS_ORDER : FETCH_ORDER);
+        const url = `${API_URL}${o.path ?? '/client.action'}`;
+        let current = params;
+        for (let attempt = 0; attempt <= retry; attempt++) {
+            if (withTime)
+                current.set('t', String(rand.now()));
+            if (sign)
+                current.set('h5st', await this.signH5st(current, o.appId ?? APPID_PC_ITEM));
+            if (o.order)
+                current = reorder(current, o.order);
+            let query = [...current];
+            if (o.appendTime)
+                query.push(['t', String(rand.now())]);
+            let res;
+            if (method === 'POST') {
+                let formBody = '';
+                if (!o.bodyInQuery) {
+                    formBody = String(query.find(([k]) => k === 'body')?.[1] ?? '');
+                    query = query.filter(([k]) => k !== 'body');
+                }
+                res = await this.send({ method: 'POST', url, headers: h.get(), query, form: o.bodyInQuery ? undefined : [['body', formBody]] });
+            }
+            else {
+                res = await this.send({ method: 'GET', url, headers: h.get(), query });
+            }
+            const raw = new Uint8Array(await res.clone().arrayBuffer());
+            const rejected = res.status === 403 && raw.length === 0;
+            const risk = readDisposal(res);
+            if (risk) {
+                this.ctx.log.warn(`${functionId} 被风控拦下：${risk}`);
+                return withDisposal(await parse(res), res.headers.get('x-rp-content'));
+            }
+            if (!rejected || attempt === retry) {
+                if (rejected)
+                    this.ctx.log.warn(`${functionId} 连续 ${retry + 1} 次 403 空 body：被限流、风控或登录态失效`);
+                return parse(res);
+            }
+            await rand.sleep(600 * (attempt + 1));
+        }
+    }
+    /** risk_h5 信封（_risk_post）：内层 JSON 经 AES-CBC 加密。 */
+    async riskPost(referer, functionId, inner) {
+        const raw = Buffer.from(jsonDumps(inner, { separators: [',', ':'], ensureAscii: false }), 'utf8');
+        const cipher = createCipheriv('aes-128-cbc', Buffer.from('rhiasnkdhandrisk'), Buffer.from('r-s-h-n_r_isnkdk'));
+        const encrypted = Buffer.concat([cipher.update(raw), cipher.final()]);
+        const outer = { sdkClient: 'pc', sdkVersion: 'pc_2.1.0', enbody: encrypted.toString('base64url') };
+        const form = [
+            ['appid', 'risk_h5'],
+            ['functionId', functionId],
+            ['body', jsonDumps(outer, { separators: [',', ':'], ensureAscii: false })],
+        ];
+        const eid = this.cookie('3AB9D23F7A4B3CSS');
+        if (eid)
+            form.push(['x-api-eid-token', eid]);
+        const h = xhr({ form: true, accept: 'application/json' }).referer(referer).origin('https://cfe.m.jd.com');
+        const res = await this.send({ method: 'POST', url: `${API_URL}/api`, headers: h.get(), form });
+        return res.json();
+    }
+    /** 写操作 / 需要登录的接口前检查登录态。 */
+    requireLogin() {
+        if (!this.isLogin)
+            throw authError(this.ctx, '当前账号缺少 thor / pin，请重新登录');
+    }
+}
+/** 按浏览器实抓的顺序重排；不在 order 里的键按原顺序垫在后面。 */
+function reorder(params, order) {
+    const out = new Map();
+    for (const k of order)
+        if (params.has(k))
+            out.set(k, params.get(k));
+    for (const [k, v] of params)
+        if (!out.has(k))
+            out.set(k, v);
+    return out;
+}
+function splitN(s, sep, n) {
+    const out = [];
+    let rest = s;
+    while (out.length < n) {
+        const i = rest.indexOf(sep);
+        if (i < 0)
+            break;
+        out.push(rest.slice(0, i));
+        rest = rest.slice(i + sep.length);
+    }
+    out.push(rest);
+    return out;
+}
+/** 响应体：JSON，其次 jsonp，都不是时给出状态与片段（_parse）。 */
+export async function parse(res) {
+    const text = await res.text();
+    try {
+        return jsonLoads(text);
+    }
+    catch {
+        const p = parseJsonp(text);
+        if (p != null)
+            return p;
+        return { _status: res.status, _raw: text.slice(0, 1000) };
+    }
+}
+/** 解 `x-rp-content` 头里的风控处置（_read_disposal）。 */
+export function decodeDisposal(raw) {
+    if (!raw)
+        return null;
+    for (let cut = 0; cut < 4; cut++) {
+        const chunk = cut ? raw.slice(0, raw.length - cut) : raw;
+        try {
+            const b = Buffer.from(chunk.replaceAll('-', '+').replaceAll('_', '/'), 'base64');
+            return jsonLoads(b.toString('utf8'));
+        }
+        catch { }
+    }
+    return undefined;
+}
+function readDisposal(res) {
+    const raw = res.headers.get('x-rp-content');
+    if (!raw)
+        return null;
+    const info = decodeDisposal(raw);
+    if (info === undefined)
+        return `x-rp-content 解不开：${raw.slice(0, 60)}`;
+    let ev = {};
+    try {
+        ev = jsonLoads(info?.disposal?.evContent || '{}');
+    }
+    catch { }
+    return `code=${info?.code} ${ev.title ?? ''} ${ev.evTypeTip ?? ''}（接口 ${ev.evApi ?? ''}）`;
+}
+/** 搜索页 Referer：searchWare 记下的关键词优先（_search_page_referer）。 */
+export function searchReferer(jd, keyword = '') {
+    const kw = keyword || jd.searchKeyword;
+    if (kw)
+        return `https://search.jd.com/Search?keyword=${quote(kw)}&enc=utf-8`;
+    return SEARCH_REFERER;
+}
+/** x-rp-content 头里的处置挂到结果的 `_disposal` 上（不参与序列化，与上游的返回值一致），交给 checkRisk。 */
+function withDisposal(result, header) {
+    const out = result && typeof result === 'object' ? result : { _status: 200, _raw: String(result ?? '') };
+    Object.defineProperty(out, '_disposal', { value: decodeDisposal(header) ?? { code: null }, enumerable: false, configurable: true });
+    return out;
+}
+/**
+ * 业务响应里的风控处置 / 登录墙映射成 specific-ai 的错误。
+ * 处置有两种来源：body 里的 `disposal` / code 605，以及只在 x-rp-content 响应头里的（body 常为空、状态码 200，见 call）。
+ * 403 空 body 要先探测登录态才能分清是登录失效还是限流（见 commands.ts 的 check），这里只处理能直接判定的情况。
+ */
+export function checkRisk(jd, res) {
+    if (res?.disposal || String(res?.code) === '605') {
+        throw new SpecificAIError('RISK_CONTROL', '京东要求人机验证（605），纯程序验证未通过', { detail: { kind: 'captcha', code: res?.code ?? null } });
+    }
+    const header = res?._disposal;
+    if (header) {
+        let ev = {};
+        try {
+            ev = jsonLoads(header.disposal?.evContent || '{}');
+        }
+        catch { }
+        throw new SpecificAIError('RISK_CONTROL', `京东要求人机验证（x-rp-content code=${header.code ?? '?'}）：账号或 IP 被风控标记了`, {
+            hint: '等风控解除（十几分钟到几小时）后再试',
+            detail: { kind: 'captcha', code: header.code ?? null, api: ev.evApi ?? null },
+        });
+    }
+    if (res?._status === 401 || res?.code === 3 || res?.code === '3')
+        throw authError(jd.ctx);
+}
+/** 各接口的登录墙：网关的 code 3 之外，购物车回 `pin is null` + passport 地址，浏览历史回 resultCode -100「用户未登录」（2026-09-29 真机）。 */
+function loginWall(res) {
+    return (String(res.resultCode) === '-100' ||
+        /未登录|pin is null/i.test(String(res.message ?? res.msg ?? res.resultMsg ?? res.echo ?? '')) ||
+        /passport\.jd\.com/.test(String(res.url ?? '')));
+}
+/**
+ * 业务失败（上游只返回原始 JSON，由调用方自己看）。所有接口都认的：
+ * - body 不是 JSON（parse 给出 `_raw`）；
+ * - 网关错误 `{code, echo}`（如 601、1 Content-Type 不兼容）；
+ * - `success: false`（购物车、浏览历史的失败响应）。
+ * `strict` 时 `code` 存在且不是 0 / "0" 也算失败：只用于核对过正常响应的 code 的接口——
+ * hotwords 为 `0`，getChatSessionLog 为 `"0"`（2026-09-29 真机），getAidInfo 为 `"0"`（上游 get_aid_info 的注释）。
+ * 其余接口（详情、评价、优惠券、关注、浏览历史、购物车、搜索、relsearch / relwords、queryLastLogs）正常响应里 code 的含义没核对过，
+ * 例如 getRecommendCoupon 会回只有 `{"code":"1"}` 的响应，分不清是没有券还是失败，所以不按 code 判。
+ */
+export function checkBusiness(jd, res, strict = false) {
+    if (res == null || typeof res !== 'object' || Array.isArray(res))
+        return;
+    if ('_raw' in res) {
+        throw new SpecificAIError('UPSTREAM', `京东返回了无法解析的响应（HTTP ${res._status}）`, { detail: { status: res._status ?? null, body: String(res._raw).slice(0, 200) } });
+    }
+    const badCode = res.code != null && String(res.code) !== '0';
+    const failed = res.success === false || (badCode && (strict || res.echo != null));
+    if (!failed)
+        return;
+    const message = n.str(res.message ?? res.msg ?? res.resultMsg ?? res.echo);
+    if (loginWall(res))
+        throw authError(jd.ctx, message ? `登录态已失效：${message}` : undefined);
+    throw new SpecificAIError('UPSTREAM', `京东返回业务错误（code=${res.code ?? res.resultCode ?? '-'}）${message ? `：${message}` : ''}`, {
+        detail: { code: res.code ?? null, result_code: res.resultCode ?? null, echo: res.echo ?? null, message },
+    });
+}