specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/core/pb.js

@@ -0,0 +1,59 @@
+import protobuf from 'protobufjs/minimal.js';
+/** 解一层消息。varint 为 bigint，fixed32 / fixed64 为 number / bigint，length-delimited 为字节。 */
+export function decode(buf) {
+    const r = protobuf.Reader.create(buf);
+    const out = new Map();
+    while (r.pos < r.len) {
+        const tag = r.uint32();
+        const field = tag >>> 3;
+        let value;
+        switch (tag & 7) {
+            case 0:
+                value = BigInt(r.uint64().toString());
+                break;
+            case 1:
+                value = BigInt(r.fixed64().toString());
+                break;
+            case 2:
+                value = r.bytes();
+                break;
+            case 5:
+                value = r.fixed32();
+                break;
+            default:
+                throw new Error(`protobuf：不支持的 wire type ${tag & 7}`);
+        }
+        const list = out.get(field);
+        if (list)
+            list.push(value);
+        else
+            out.set(field, [value]);
+    }
+    return out;
+}
+/** 取字段的第一个值。 */
+export function first(m, field) {
+    return m.get(field)?.[0];
+}
+export function str(m, field) {
+    const v = first(m, field);
+    return v instanceof Uint8Array ? Buffer.from(v).toString('utf8') : null;
+}
+export function int(m, field) {
+    const v = first(m, field);
+    return typeof v === 'bigint' ? Number(BigInt.asIntN(64, v)) : typeof v === 'number' ? v : null;
+}
+/** 64 位整数按字符串取（ID 用）。 */
+export function int64(m, field) {
+    const v = first(m, field);
+    return typeof v === 'bigint' ? BigInt.asIntN(64, v).toString() : null;
+}
+/** repeated 的子消息。 */
+export function messages(m, field) {
+    return (m.get(field) ?? []).filter((v) => v instanceof Uint8Array).map(decode);
+}
+export function message(m, field) {
+    const v = first(m, field);
+    return v instanceof Uint8Array ? decode(v) : null;
+}
+export { protobuf };

package/dist/core/py.js

@@ -0,0 +1,181 @@
+/**
+ * 与 Python 标准库逐字节一致的编码函数。上游的签名常常算在 `urlencode` / `json.dumps` 的结果上，
+ * 移植时必须产出同样的字符串，否则签名对不上。
+ */
+const ALWAYS_SAFE = /[A-Za-z0-9_.\-~]/;
+export function toPairs(init) {
+    if (!init)
+        return [];
+    return Array.isArray(init) ? init : Object.entries(init);
+}
+/** Python 的 `str(value)`：True / False / None 的写法与 JS 不同。 */
+export function pyStr(value) {
+    if (value === true)
+        return 'True';
+    if (value === false)
+        return 'False';
+    if (value == null)
+        return 'None';
+    return String(value);
+}
+/** 有限 double 的精确十进制：|x| = digits / 10^scale。 */
+function exactDecimal(x) {
+    const view = new DataView(new ArrayBuffer(8));
+    view.setFloat64(0, Math.abs(x));
+    const bits = view.getBigUint64(0);
+    const exponent = Number((bits >> 52n) & 0x7ffn);
+    let mantissa = bits & ((1n << 52n) - 1n);
+    let e = -1074;
+    if (exponent) {
+        mantissa |= 1n << 52n;
+        e = exponent - 1075;
+    }
+    if (e >= 0)
+        return { digits: mantissa << BigInt(e), scale: 0 };
+    return { digits: mantissa * 5n ** BigInt(-e), scale: -e };
+}
+/**
+ * Python 的 `round(x, ndigits)`（float）：按 x 的精确二进制值舍入到 ndigits 位小数，恰好一半时取偶，
+ * 结果为 0 时保留符号。`Number.prototype.toFixed` 在恰好一半时进位，不能直接用。
+ */
+export function pyRound(x, ndigits = 0) {
+    if (!Number.isFinite(x) || x === 0)
+        return x;
+    const { digits, scale } = exactDecimal(x);
+    if (scale <= ndigits)
+        return x;
+    const divisor = 10n ** BigInt(scale - ndigits);
+    let q = digits / divisor;
+    const twice = (digits % divisor) * 2n;
+    if (twice > divisor || (twice === divisor && q % 2n === 1n))
+        q += 1n;
+    const out = Number(`${q}e-${ndigits}`);
+    return x < 0 ? -out : out;
+}
+/**
+ * Python 的 `str(float)` / `repr(float)`：最短往返表示；整数值带 `.0`；
+ * 小于 1e-4 或不小于 1e16 时用指数形式，指数至少两位（`1e-05`）。
+ */
+export function pyFloatStr(x) {
+    if (Number.isNaN(x))
+        return 'nan';
+    if (!Number.isFinite(x))
+        return x > 0 ? 'inf' : '-inf';
+    if (x === 0)
+        return Object.is(x, -0) ? '-0.0' : '0.0';
+    const abs = Math.abs(x);
+    if (abs < 1e-4 || abs >= 1e16) {
+        const [mantissa, exp] = x.toExponential().split('e');
+        const sign = exp.startsWith('-') ? '-' : '+';
+        return `${mantissa}e${sign}${exp.replace(/^[+-]/, '').padStart(2, '0')}`;
+    }
+    const s = String(x);
+    return s.includes('.') ? s : `${s}.0`;
+}
+/** `urllib.parse.quote(s, safe)`，默认 safe 为 `/`。 */
+export function quote(s, safe = '/') {
+    let out = '';
+    for (const byte of Buffer.from(s, 'utf8')) {
+        const ch = String.fromCharCode(byte);
+        out += byte < 0x80 && (ALWAYS_SAFE.test(ch) || safe.includes(ch)) ? ch : '%' + byte.toString(16).toUpperCase().padStart(2, '0');
+    }
+    return out;
+}
+/** `urllib.parse.quote_plus(s, safe)`：空格编码成 `+`。 */
+export function quotePlus(s, safe = '') {
+    return s.includes(' ') ? quote(s, safe + ' ').replaceAll(' ', '+') : quote(s, safe);
+}
+/** `urllib.parse.unquote(s)`。 */
+export function unquote(s) {
+    return s.replace(/(%[0-9A-Fa-f]{2})+/g, (m) => Buffer.from(m.replaceAll('%', ''), 'hex').toString('utf8'));
+}
+/** `urllib.parse.urlencode(pairs, safe=safe, quote_via=...)`，值先经 Python 的 `str()`。 */
+export function urlencode(init, options = {}) {
+    const q = options.via === 'percent' ? quote : quotePlus;
+    const safe = options.safe ?? '';
+    return toPairs(init)
+        .map(([k, v]) => `${q(k, safe)}=${q(pyStr(v), safe)}`)
+        .join('&');
+}
+/** `urllib.parse.parse_qsl(query, keep_blank_values=True)`。 */
+export function parseQsl(query) {
+    return query
+        .split(/[&;]/)
+        .filter(Boolean)
+        .map((part) => {
+        const i = part.indexOf('=');
+        const [k, v] = i < 0 ? [part, ''] : [part.slice(0, i), part.slice(i + 1)];
+        return [unquote(k.replaceAll('+', ' ')), unquote(v.replaceAll('+', ' '))];
+    });
+}
+const REQUOTE_SAFE = "!#$%&'()*+,/:;=?@[]~|";
+const UNRESERVED = /[A-Za-z0-9\-._~]/;
+/** curl_cffi 的 `requote_uri`：已编码的部分保持不变，其余非法字符补上编码（requests 的版本不把 `|` 当安全字符）。 */
+export function requoteUri(uri) {
+    // unquote_unreserved：%XX 表示的是非保留字符时解开
+    const unreserved = uri.replace(/%([0-9A-Fa-f]{2})/g, (m, h) => {
+        const ch = String.fromCharCode(parseInt(h, 16));
+        return UNRESERVED.test(ch) ? ch : m.toUpperCase();
+    });
+    return quote(unreserved, REQUOTE_SAFE);
+}
+const ESCAPES = { '"': '\\"', '\\': '\\\\', '\n': '\\n', '\r': '\\r', '\t': '\\t', '\b': '\\b', '\f': '\\f' };
+function dumpString(s, ensureAscii) {
+    let out = '"';
+    for (let i = 0; i < s.length; i++) {
+        const ch = s[i];
+        const code = s.charCodeAt(i);
+        if (ESCAPES[ch])
+            out += ESCAPES[ch];
+        else if (code < 0x20 || (ensureAscii && code > 0x7e))
+            out += '\\u' + code.toString(16).padStart(4, '0');
+        else
+            out += ch;
+    }
+    return out + '"';
+}
+/**
+ * `json.loads`：与 Python 一样保留大整数。超出 JS 安全整数范围（2^53）的整数（各平台的 64 位 ID，
+ * 例如 TikTok 的 collectionId）保留成原文字符串，不按 double 取近似值；其余与 JSON.parse 相同。
+ */
+export function jsonLoads(text) {
+    return JSON.parse(text, (_key, value, context) => typeof value === 'number' && !Number.isSafeInteger(value) && context?.source != null && /^-?\d+$/.test(context.source) ? context.source : value);
+}
+/**
+ * `json.dumps(value, separators=..., ensure_ascii=...)`。对象按插入顺序输出，与 Python dict 一致。
+ * 注意 JS 对象里形如整数的键（如 `"3064"`）总是排在最前；需要精确键序时传 Map。
+ */
+export function jsonDumps(value, options = {}) {
+    const [itemSep, keySep] = options.separators ?? [', ', ': '];
+    const ascii = options.ensureAscii ?? true;
+    const dump = (v) => {
+        if (v === null || v === undefined)
+            return 'null';
+        if (v === true)
+            return 'true';
+        if (v === false)
+            return 'false';
+        if (typeof v === 'number') {
+            if (!Number.isFinite(v))
+                return Number.isNaN(v) ? 'NaN' : v > 0 ? 'Infinity' : '-Infinity';
+            return String(v);
+        }
+        if (typeof v === 'bigint')
+            return v.toString();
+        if (typeof v === 'string')
+            return dumpString(v, ascii);
+        if (Array.isArray(v))
+            return '[' + v.map(dump).join(itemSep) + ']';
+        if (v instanceof Map)
+            return '{' + [...v].map(([k, x]) => dumpString(String(k), ascii) + keySep + dump(x)).join(itemSep) + '}';
+        if (typeof v === 'object') {
+            return '{' + Object.entries(v).map(([k, x]) => dumpString(k, ascii) + keySep + dump(x)).join(itemSep) + '}';
+        }
+        throw new TypeError(`jsonDumps：不支持的类型 ${typeof v}`);
+    };
+    return dump(value);
+}
+/** 紧凑、不转义非 ASCII：`json.dumps(v, separators=(',', ':'), ensure_ascii=False)`。 */
+export function compactJson(value) {
+    return jsonDumps(value, { separators: [',', ':'], ensureAscii: false });
+}

package/dist/core/rand.js

@@ -0,0 +1,131 @@
+import { randomBytes } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+/**
+ * 随机数与时钟。平台代码一律经由这里取随机数和当前时间，不直接用 Math.random / Date.now，
+ * 这样对拍测试可以换成确定性的序列（见 {@link deterministic}），与上游 Python 的输出逐字节比较。
+ *
+ * 各方法的推导公式与 scripts/golden/specific_ai_golden.py 里对 Python random 的替换一一对应，改动时两边一起改。
+ */
+let source = Math.random;
+let clock = Date.now;
+/** [0, 1) 的浮点数。对应 Python 的 `random.random()`。 */
+export function random() {
+    return source();
+}
+/** [a, b] 的整数，含两端。对应 `random.randint(a, b)`。 */
+export function randint(a, b) {
+    return a + Math.floor(source() * (b - a + 1));
+}
+/** 对应 `random.uniform(a, b)`。 */
+export function uniform(a, b) {
+    return a + (b - a) * source();
+}
+/** 对应 `random.choice(seq)`。 */
+export function choice(seq) {
+    return seq[Math.floor(source() * seq.length)];
+}
+/** 从 alphabet 里取 n 个字符。对应 `''.join(random.choice(alphabet) for _ in range(n))`。 */
+export function string(n, alphabet) {
+    let s = '';
+    for (let i = 0; i < n; i++)
+        s += choice(alphabet);
+    return s;
+}
+const TWOPI = 2 * Math.PI;
+let gaussNext = null;
+/**
+ * 对应 `random.gauss(mu, sigma)`：Box-Muller 一次算出两个，第二个缓存到下一次调用（Python 的 `gauss_next`）。
+ * 缓存在 {@link deterministic} 切换时清空。cos / sin / log 用的是 V8 的实现，与 C libm 可能差最后一位。
+ */
+export function gauss(mu = 0, sigma = 1) {
+    let z = gaussNext;
+    gaussNext = null;
+    if (z === null) {
+        const x2pi = source() * TWOPI;
+        const g2rad = Math.sqrt(-2 * Math.log(1 - source()));
+        z = Math.cos(x2pi) * g2rad;
+        gaussNext = Math.sin(x2pi) * g2rad;
+    }
+    return mu + z * sigma;
+}
+/** 对应 `random.sample(population, k)`（部分 Fisher-Yates）。 */
+export function sample(population, k) {
+    const pool = Array.from(population);
+    for (let i = 0; i < k; i++) {
+        const j = i + Math.floor(source() * (pool.length - i));
+        [pool[i], pool[j]] = [pool[j], pool[i]];
+    }
+    return pool.slice(0, k);
+}
+/** 原地打乱。对应 `random.shuffle(x)`。 */
+export function shuffle(x) {
+    for (let i = x.length - 1; i > 0; i--) {
+        const j = Math.floor(source() * (i + 1));
+        [x[i], x[j]] = [x[j], x[i]];
+    }
+    return x;
+}
+/** n 个随机字节。对应 `os.urandom(n)` / `secrets.token_bytes(n)`。 */
+export function bytes(n) {
+    if (source === Math.random)
+        return new Uint8Array(randomBytes(n));
+    const out = new Uint8Array(n);
+    for (let i = 0; i < n; i++)
+        out[i] = Math.floor(source() * 256);
+    return out;
+}
+/** 2n 位小写十六进制。对应 `secrets.token_hex(n)`。 */
+export function hex(n) {
+    return Buffer.from(bytes(n)).toString('hex');
+}
+/** 对应 `str(uuid.uuid4())`。 */
+export function uuid4() {
+    const b = bytes(16);
+    b[6] = (b[6] & 0x0f) | 0x40;
+    b[8] = (b[8] & 0x3f) | 0x80;
+    const h = Buffer.from(b).toString('hex');
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+}
+/** 当前时间，毫秒。 */
+export function now() {
+    return clock();
+}
+/** 当前时间，秒（整数）。对应 `int(time.time())`。 */
+export function nowSeconds() {
+    return Math.floor(clock() / 1000);
+}
+/** 等待（毫秒）。确定性模式下不等，对应对拍时被替换成空操作的 `time.sleep`。 */
+export async function sleep(ms, signal) {
+    if (isDeterministic() || ms <= 0)
+        return;
+    await delay(ms, undefined, { signal }).catch(() => { });
+}
+/** mulberry32：Python 侧有逐位相同的实现。 */
+export function mulberry32(seed) {
+    let a = seed >>> 0;
+    return () => {
+        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;
+    };
+}
+export const DEFAULT_SEED = 20260927;
+export const DEFAULT_NOW = 1790000000123;
+/** 切换成确定性的随机数与固定时钟，返回恢复函数。只给测试用。 */
+export function deterministic(options = {}) {
+    const prev = [source, clock];
+    source = mulberry32(options.seed ?? DEFAULT_SEED);
+    gaussNext = null;
+    const fixed = options.now ?? DEFAULT_NOW;
+    clock = () => fixed;
+    return () => {
+        ;
+        [source, clock] = prev;
+        gaussNext = null;
+    };
+}
+/** 当前是否处于确定性模式（签名 vm 据此给脚本注入固定的 Math.random / Date）。 */
+export function isDeterministic() {
+    return source !== Math.random;
+}

package/dist/core/registry.js

@@ -0,0 +1,129 @@
+import { z } from 'zod';
+import { PAGING } from './options.js';
+import { OUTPUT_TYPES } from './schemas.js';
+import { CORE_COMMANDS, RESOURCES, VOCAB } from './vocab.js';
+export const ENDPOINTS = ['web', 'app', 'pc'];
+const coreHandler = (name) => () => import('./auth-handlers.js').then((m) => m[name]);
+/**
+ * 平台 index.ts 用的 handler 声明：`h('itemGet')` 懒加载 handler，`impl('full', 'itemGet', {...})` 连同 upstream 一起声明。
+ * `wrap` 给每个 handler 套一层（例如抖音遇到 Uifid 失效时重试）。
+ */
+export function handlers(load, wrap) {
+    const h = (name) => Object.assign(() => load().then((m) => {
+        const handler = m[name];
+        return wrap ? wrap(m, handler) : handler;
+    }), { handlerName: name });
+    const impl = (upstream, name, extra = {}) => ({ upstream, handler: h(name), ...extra });
+    return { h, impl };
+}
+export function definePlatform(decl) {
+    const endpoints = {};
+    for (const endpoint of ENDPOINTS) {
+        const e = decl.endpoints[endpoint];
+        endpoints[endpoint] =
+            e === 'planned' ? 'planned' : { login: e.login, logout: e.logout, guest: e.guest ?? false, commands: resolveCommands(decl, e) };
+    }
+    return {
+        id: decl.id,
+        name: decl.name,
+        aliases: decl.aliases,
+        item: decl.item,
+        pageInterval: decl.pageInterval ?? 1000,
+        endpoints,
+    };
+}
+function resolveCommands(decl, e) {
+    const commands = new Map();
+    const fail = (key, message) => {
+        throw new Error(`注册表错误 ${decl.id} "${key}"：${message}`);
+    };
+    for (const [key, value] of Object.entries(e.commands)) {
+        const parts = key.split(' ');
+        if (parts.length !== 2 || !parts.every((p) => /^[a-z]+$/.test(p)))
+            fail(key, '命令名必须是 "resource action"');
+        if (CORE_COMMANDS.includes(key))
+            fail(key, '由 core 自动注册，不要声明');
+        const d = typeof value === 'string' ? { upstream: value } : value;
+        const base = VOCAB[key];
+        if (!base) {
+            for (const field of ['summary', 'args', 'auth', 'output']) {
+                if (d[field] === undefined)
+                    fail(key, `扩展命令必须写全字段，缺少 ${field}`);
+            }
+        }
+        const spec = { ...base, ...d };
+        if (!e.guest && parts[0] !== 'auth') {
+            if (d.auth === 'optional')
+                fail(key, '该端不支持游客态，auth 只能是 required');
+            spec.auth = 'required';
+        }
+        const options = { ...(spec.paged ? PAGING : {}), ...base?.options, ...d.options };
+        const unsupported = [];
+        if (d.supports) {
+            const standard = Object.keys(base?.options ?? {});
+            for (const k of d.supports)
+                if (!standard.includes(k))
+                    fail(key, `supports 里的 ${k} 不是这个命令的标准选项`);
+            for (const k of standard) {
+                if (d.supports.includes(k))
+                    continue;
+                if (d.options && k in d.options)
+                    fail(key, `选项 ${k} 既在 options 里声明，又没列进 supports`);
+                unsupported.push(k);
+                delete options[k];
+            }
+        }
+        if (key === 'auth login') {
+            options.method = z.enum(e.login.methods).default(e.login.default).describe('登录方式');
+            if (e.login.scopes?.length)
+                options.scope = z.enum(e.login.scopes).optional().describe('子站点');
+        }
+        const output = spec.output.replace(/\[\]$/, '');
+        if (!output.startsWith('{') && !OUTPUT_TYPES.has(output))
+            fail(key, `未知的输出类型 ${spec.output}`);
+        commands.set(key, {
+            ...spec,
+            key,
+            resource: parts[0],
+            action: parts[1],
+            summary: spec.summary.replaceAll('{item}', decl.item),
+            args: spec.args.map((a) => ({ ...a, summary: a.summary.replaceAll('{item}', decl.item) })),
+            options,
+            note: d.note ?? null,
+            status: d.handler ? 'implemented' : 'planned',
+            extension: !base,
+            unsupported,
+            handler: d.handler ?? null,
+        });
+    }
+    for (const key of CORE_COMMANDS) {
+        const [resource, action] = key.split(' ');
+        commands.set(key, {
+            ...VOCAB[key],
+            key,
+            resource,
+            action,
+            upstream: null,
+            note: null,
+            status: 'implemented',
+            extension: false,
+            unsupported: [],
+            handler: coreHandler(action),
+        });
+    }
+    return commands;
+}
+const VOCAB_ORDER = new Map(Object.keys(VOCAB).map((k, i) => [k, i]));
+/** 按词表顺序排列命令；扩展 action 排在同 resource 的词表命令之后，新增的 resource 排在最后。 */
+export function sortCommands(commands) {
+    const list = [...commands];
+    const extra = [...new Set(list.map((c) => c.resource).filter((r) => !RESOURCES.includes(r)))];
+    const rank = (c) => {
+        const r = RESOURCES.indexOf(c.resource);
+        return [r >= 0 ? r : RESOURCES.length + extra.indexOf(c.resource), VOCAB_ORDER.get(c.key) ?? Infinity];
+    };
+    return list
+        .map((c, i) => ({ c, i, k: rank(c) }))
+        .sort((a, b) => a.k[0] - b.k[0] || a.k[1] - b.k[1] || a.i - b.i)
+        .map((x) => x.c);
+}

package/dist/core/schemas.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { LOGIN_METHODS } from './options.js';
+/** 输出类型名，注册表的 `output` 只能用这些（加 `[]` 表示数组），或 `{...}` 形式的内联结构。 */
+export const OUTPUT_TYPES = new Set([
+    'User', 'Item', 'Comment', 'Folder', 'Series', 'Category', 'Keyword', 'Topic', 'Poi', 'Live', 'Event', 'Gift',
+    'Rank', 'Conversation', 'Message', 'Notice', 'NoticeCount', 'Media', 'AuthStatus', 'Account', 'File', 'Subtitle',
+    'Danmaku', 'Order', 'Coupon',
+]);
+/** 归一化对象上挂平台原始对象，`--raw` 时用它替换。JSON 序列化会忽略 symbol 键。 */
+export const RAW = Symbol.for('specific-ai.raw');
+export function withRaw(value, raw) {
+    Object.defineProperty(value, RAW, { value: raw, enumerable: false });
+    return value;
+}
+// ---- 凭证文件（AGENTS 5.4） ----
+const UserRefSchema = z.object({ id: z.string(), name: z.string().nullable(), url: z.string().nullable() });
+const CookieSchema = z.object({
+    name: z.string(),
+    value: z.string(),
+    domain: z.string(),
+    path: z.string().default('/'),
+    /** Unix 秒；会话 cookie 为 null。 */
+    expires: z.number().nullable().default(null),
+});
+const ScopeSchema = z.object({
+    cookies: z.array(CookieSchema).default([]),
+    tokens: z.record(z.string(), z.unknown()).default({}),
+});
+export const CredentialSchema = z.object({
+    schema: z.literal(1),
+    platform: z.string(),
+    endpoint: z.enum(['web', 'app', 'pc']),
+    account: z.string(),
+    user: UserRefSchema.nullable(),
+    method: z.enum([...LOGIN_METHODS, 'guest']),
+    created_at: z.string(),
+    updated_at: z.string(),
+    scopes: z.record(z.string(), ScopeSchema),
+    device: z.record(z.string(), z.unknown()).default({}),
+    extra: z.record(z.string(), z.unknown()).default({}),
+});

package/dist/core/stream.js

@@ -0,0 +1,104 @@
+import { websocket } from 'wreq-js';
+import { SpecificAIError } from './errors.js';
+import { toNetworkError } from './http.js';
+import { sleep } from './rand.js';
+/** 打开一个 WebSocket。消息按到达顺序进入 messages；连接关闭或 signal 中止时迭代结束，出错时抛出。 */
+export async function openSocket(url, options = {}) {
+    const { signal, ...wsOptions } = options;
+    const queue = [];
+    let wake = null;
+    let done = false;
+    let failure = null;
+    const notify = () => {
+        const w = wake;
+        wake = null;
+        w?.();
+    };
+    let ws;
+    try {
+        ws = await websocket(url, { browser: 'chrome', os: 'windows', ...wsOptions, binaryType: 'nodebuffer' });
+    }
+    catch (err) {
+        throw toNetworkError(err);
+    }
+    ws.onmessage = (e) => {
+        queue.push(e.data);
+        notify();
+    };
+    ws.onclose = () => {
+        done = true;
+        notify();
+    };
+    ws.onerror = (e) => {
+        failure = new Error(String(e.message ?? 'WebSocket 出错'));
+        done = true;
+        notify();
+    };
+    const onAbort = () => {
+        ws.close();
+        done = true;
+        notify();
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    return {
+        send: async (data) => {
+            await ws.send(data);
+        },
+        close: () => ws.close(),
+        messages: {
+            async *[Symbol.asyncIterator]() {
+                try {
+                    for (;;) {
+                        while (queue.length)
+                            yield queue.shift();
+                        if (done)
+                            break;
+                        await new Promise((r) => (wake = r));
+                    }
+                    if (failure)
+                        throw failure;
+                }
+                finally {
+                    signal?.removeEventListener('abort', onAbort);
+                    if (!done)
+                        ws.close();
+                }
+            },
+        },
+    };
+}
+/** 连续多少次 UPSTREAM 错误后不再重连。 */
+const MAX_UPSTREAM_FAILURES = 5;
+/**
+ * 断线自动重连：connect 每次返回一段事件流，流结束或出错后按指数退避重连，直到 signal 中止。
+ * 重连解决不了的错误直接抛出：登录态失效、风控、参数错误等（NETWORK、UPSTREAM 以外的 SpecificAIError）；
+ * UPSTREAM（例如房间不存在）连续 5 次、中间一条事件都没收到时也抛出。其余错误（断线）一直重连。
+ */
+export async function* reconnecting(ctx, connect, options = {}) {
+    let attempt = 0;
+    let upstreamFailures = 0;
+    while (!ctx.signal.aborted) {
+        try {
+            for await (const value of connect(attempt)) {
+                attempt = 0;
+                upstreamFailures = 0;
+                yield value;
+            }
+        }
+        catch (err) {
+            if (ctx.signal.aborted)
+                return;
+            if (err instanceof SpecificAIError && err.code !== 'NETWORK') {
+                if (err.code !== 'UPSTREAM' || ++upstreamFailures >= MAX_UPSTREAM_FAILURES)
+                    throw err;
+            }
+            ctx.log.warn(`连接断开：${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (ctx.signal.aborted)
+            return;
+        attempt++;
+        const delay = Math.min(1000 * 2 ** (attempt - 1), options.maxDelay ?? 30_000);
+        ctx.log.info(`${Math.round(delay / 1000)} 秒后重连（第 ${attempt} 次）`);
+        await sleep(delay, ctx.signal);
+    }
+}

package/dist/core/toolkit.js

@@ -0,0 +1,35 @@
+import { CookieJar } from './cookies.js';
+import { SpecificAIError } from './errors.js';
+import { HttpClient } from './http.js';
+import { endpointFlag, GUEST } from './auth-store.js';
+/** 凭证里的一个子站点分区，不存在时创建。 */
+export function scope(credential, name = 'main') {
+    return (credential.scopes[name] ??= { cookies: [], tokens: {} });
+}
+/** 绑定到凭证某个 scope 的 cookie 罐：请求中更新的 cookie 会随凭证由 core 落盘。 */
+export function jarOf(credential, name = 'main') {
+    return new CookieJar(scope(credential, name).cookies);
+}
+/** 按本次调用的代理和超时创建 HTTP 客户端。 */
+export function httpClient(ctx, options = {}) {
+    const { scope: name, ...rest } = options;
+    return new HttpClient({ jar: jarOf(ctx.credential, name), ...rest, proxy: ctx.config.proxy, timeout: ctx.config.timeout, log: ctx.log });
+}
+/** 当前身份是否是游客。 */
+export function isGuest(ctx) {
+    return ctx.account == null || ctx.account === GUEST || ctx.credential.method === 'guest';
+}
+/** 平台返回登录墙时：游客 → AUTH_REQUIRED；已登录 → AUTH_EXPIRED（AGENTS 5.2）。 */
+export function authError(ctx, message) {
+    const p = ctx.platform.id;
+    const e = endpointFlag(ctx.endpoint);
+    if (isGuest(ctx))
+        return new SpecificAIError('AUTH_REQUIRED', message ?? '需要登录', { hint: `specific-ai ${p} auth login${e}` });
+    return new SpecificAIError('AUTH_EXPIRED', message ?? `账号 ${ctx.account} 的登录态已失效`, {
+        hint: `specific-ai ${p} auth login -a ${ctx.account}${e}`,
+    });
+}
+/** 分页结果。 */
+export function paged(data, cursor, hasMore) {
+    return { data, page: { cursor: hasMore && cursor != null ? String(cursor) : null, has_more: hasMore && cursor != null } };
+}