specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/core/vm.js

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { format } from 'node:util';
+import vm from 'node:vm';
+import { DEFAULT_NOW, DEFAULT_SEED, isDeterministic, mulberry32, now } from './rand.js';
+/**
+ * 上游签名 JS 的执行环境（AGENTS 7.4）：每个脚本一个 vm context，懒创建、复用。
+ * `require` 指向 specific-ai 自己的 node_modules；console 输出到 stderr，保证 stdout 纯净。
+ *
+ * 确定性模式（对拍测试）下，每次调用都新建 context，并注入与 scripts/golden/node_determinism.cjs
+ * 相同的 Math.random 和 Date——上游每次签名都新起一个 node 进程，序列从头开始，这里保持一致。
+ */
+const require = createRequire(import.meta.url);
+const contexts = new Map();
+const sources = new Map();
+const stderrConsole = Object.fromEntries(['log', 'info', 'warn', 'error', 'debug', 'trace'].map((k) => [k, (...a) => process.stderr.write(format(...a) + '\n')]));
+/** 新建 context，带上签名 JS 常用的宿主全局对象。 */
+export function createContext(globals = {}) {
+    const context = vm.createContext({
+        require,
+        console: stderrConsole,
+        Buffer,
+        URL,
+        URLSearchParams,
+        TextEncoder,
+        TextDecoder,
+        atob,
+        btoa,
+        crypto: globalThis.crypto,
+        setTimeout,
+        clearTimeout,
+        setInterval,
+        clearInterval,
+        ...globals,
+    });
+    if (isDeterministic()) {
+        context.__specific_ai_random = mulberry32(DEFAULT_SEED);
+        context.__specific_ai_now = now() || DEFAULT_NOW;
+        vm.runInContext(`Math.random = __specific_ai_random;
+       (() => { const D = Date; globalThis.Date = class extends D {
+         constructor(...a) { super(...(a.length ? a : [__specific_ai_now])) }
+         static now() { return __specific_ai_now }
+       } })();`, context);
+    }
+    return context;
+}
+function source(file) {
+    let s = sources.get(file);
+    if (s == null)
+        sources.set(file, (s = readFileSync(file, 'utf8')));
+    return s;
+}
+/** 在该脚本专属的 context 里执行一次，返回 context（即脚本的全局对象），之后复用。 */
+export function loadScript(file, globals) {
+    const deterministic = isDeterministic();
+    let context = deterministic ? undefined : contexts.get(file);
+    if (!context) {
+        context = createContext(globals);
+        vm.runInContext(source(file), context, { filename: file });
+        if (!deterministic)
+            contexts.set(file, context);
+    }
+    return context;
+}
+/** 在脚本的 context 里调用一个全局函数。 */
+export function callScript(file, fn, args, globals) {
+    const context = loadScript(file, globals);
+    // 顶层 const / let 声明不会挂到全局对象上，按名字在 context 里求值
+    const f = context[fn] ?? (/^[\w$]+$/.test(fn) ? vm.runInContext(`typeof ${fn} === 'undefined' ? undefined : ${fn}`, context) : undefined);
+    if (typeof f !== 'function')
+        throw new Error(`${file} 里没有函数 ${fn}`);
+    return f(...args);
+}

package/dist/core/vocab.js

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+import { DOWNLOAD, PUBLISH, STREAM } from './options.js';
+const arg = {
+    user: { name: 'user', summary: '用户：ID、主页 URL、用户名或 me' },
+    userOrMe: { name: 'user', summary: '用户，省略时为 me', optional: true, default: 'me' },
+    item: { name: 'item', summary: '{item}：ID 或 URL' },
+    keyword: { name: 'keyword', summary: '关键词' },
+    comment: { name: 'comment', summary: '评论 ID' },
+    room: { name: 'room', summary: '直播间：ID 或 URL' },
+    conversation: { name: 'conversation', summary: '会话 ID' },
+};
+function read(summary, args, output, extra = {}) {
+    return { summary, args, output, options: {}, auth: 'optional', ...extra };
+}
+function list(summary, args, output, extra = {}) {
+    return read(summary, args, output, { paged: true, ...extra });
+}
+function write(summary, args, output = '{id}', extra = {}) {
+    return read(summary, args, output, { auth: 'required', ...extra });
+}
+function given(options, keys) {
+    return keys.filter((k) => options[k] != null);
+}
+const flags = (keys) => keys.map((k) => (k === 'text' ? '<text>' : `--${k}`)).join('、');
+/**
+ * `msg send` 的参数约束（AGENTS 4.8）：--to、--conversation、--item 用一个，只有 --to 与 --item 可以同时用；
+ * 要有消息内容。平台可以追加目标（京东的 --order）和内容（抖音的 --file、--share）。
+ * 某个平台不支持 --to 与 --item 同时用时，由 handler 报 UNSUPPORTED。
+ */
+export function checkMsgSend(a, o, extra = {}) {
+    const targets = given(o, ['to', 'conversation', 'item']);
+    const extraTargets = given(o, extra.targets ?? []);
+    if ((targets.length === 0 && extraTargets.length === 0) || (targets.length > 1 && targets.includes('conversation'))) {
+        return `${flags(['to', 'conversation', 'item', ...(extra.targets ?? [])])} 需要用一个，只有 --to 与 --item 可以同时用`;
+    }
+    const content = ['image', 'video', ...(extra.content ?? [])];
+    if (a.text == null && given(o, content).length === 0) {
+        const all = flags(['text', ...content]).split('、');
+        return `需要 ${all.slice(0, -1).join('、')} 或 ${all.at(-1)}`;
+    }
+}
+/** 通用词表（AGENTS 4.5、4.8、6.3）。平台只声明与默认不同的部分。 */
+export const VOCAB = {
+    'auth login': read('登录', [], 'Account', {
+        options: {
+            phone: z.string().optional().describe('手机号（sms）'),
+            code: z.string().optional().describe('短信验证码（sms）'),
+            username: z.string().optional().describe('用户名（password）'),
+            passwordStdin: z.boolean().optional().describe('从 stdin 读取密码（password）'),
+            cookie: z.string().optional().describe('cookie 字符串、@文件，或 - 表示从 stdin 读取（cookie）'),
+        },
+    }),
+    'auth status': read('在线校验登录态', [], 'AuthStatus'),
+    'auth logout': read('登出并删除本地凭证', [], 'Account'),
+    'auth list': read('本平台、本端的账号', [], 'Account[]'),
+    'auth use': read('切换当前账号', [{ name: 'account', summary: '账号名' }], 'Account'),
+    'user get': read('用户资料', [arg.user], 'User'),
+    'user search': list('搜索用户', [arg.keyword], 'User[]'),
+    'user items': list('用户发布的{item}', [arg.user], 'Item[]'),
+    'user likes': list('用户点赞的{item}', [arg.userOrMe], 'Item[]'),
+    'user collects': list('用户收藏的{item}', [arg.userOrMe], 'Item[]'),
+    'user reposts': list('用户转发的{item}', [arg.userOrMe], 'Item[]'),
+    'user followers': list('粉丝列表', [arg.userOrMe], 'User[]'),
+    'user following': list('关注列表', [arg.userOrMe], 'User[]'),
+    'user follow': write('关注', [arg.user]),
+    'user unfollow': write('取消关注', [arg.user]),
+    'item get': read('{item}详情', [arg.item], 'Item'),
+    'item search': list('搜索{item}', [arg.keyword], 'Item[]'),
+    'item related': list('相关推荐', [arg.item], 'Item[]'),
+    'item list': list('我发布的{item}，带审核状态', [], 'Item[]', { auth: 'required' }),
+    'item media': read('{item}的媒体地址', [arg.item], 'Media[]'),
+    'item download': read('下载{item}的媒体', [arg.item], 'File[]', { options: DOWNLOAD }),
+    'item like': write('点赞', [arg.item]),
+    'item unlike': write('取消点赞', [arg.item]),
+    'item collect': write('收藏', [arg.item]),
+    'item uncollect': write('取消收藏', [arg.item]),
+    'item repost': write('转发', [arg.item]),
+    'item unrepost': write('取消转发', [arg.item]),
+    'item publish': write('发布{item}', [], 'Item', { options: PUBLISH }),
+    'item delete': write('删除{item}', [arg.item], '{id}', { confirm: true }),
+    'item categories': read('{item}分类，即 --category 的取值', [], 'Category[]'),
+    'product get': read('商品详情', [{ name: 'product', summary: '商品：ID 或 URL' }], 'Item'),
+    'comment list': list('评论列表，也用于商品评价', [arg.item], 'Comment[]'),
+    'comment replies': list('评论的回复', [arg.item, arg.comment], 'Comment[]'),
+    'comment add': write('发表评论', [arg.item, { name: 'text', summary: '评论内容' }], 'Comment', {
+        options: { replyTo: z.string().optional().describe('回复某条评论（评论 ID）') },
+    }),
+    'comment delete': write('删除评论', [arg.item, arg.comment], '{id}', { confirm: true }),
+    'comment like': write('点赞评论', [arg.item, arg.comment]),
+    'comment unlike': write('取消点赞评论', [arg.item, arg.comment]),
+    'feed list': list('推荐 / 热门 / 关注流', [], 'Item[]'),
+    'feed categories': read('推荐流分类', [], 'Category[]'),
+    'live get': read('直播间信息', [arg.room], 'Live'),
+    'live list': list('直播列表', [], 'Live[]'),
+    'live search': list('搜索直播', [arg.keyword], 'Live[]'),
+    'live categories': read('直播分类', [], 'Category[]'),
+    'live listen': read('监听弹幕、礼物、进场等事件', [arg.room], 'Event', { stream: true, options: STREAM }),
+    'live history': read('最近的弹幕', [arg.room], 'Event[]'),
+    'live send': write('发弹幕，或用 --gift 送礼', [arg.room, { name: 'text', summary: '弹幕内容', optional: true }], '{id}', {
+        options: {
+            gift: z.string().optional().describe('礼物 id，取值来自 live gifts'),
+            count: z.number().int().positive().optional().describe('礼物数量'),
+        },
+        confirm: (o) => o.gift != null,
+        check: (a, o) => {
+            if ((a.text == null) === (o.gift == null))
+                return '需要 <text> 或 --gift，二选一';
+            if (o.count != null && o.gift == null)
+                return '--count 只能和 --gift 一起用';
+        },
+    }),
+    'live like': write('直播间点赞', [arg.room]),
+    'live rank': read('直播间排行榜', [arg.room], 'Rank[]'),
+    'live gifts': read('礼物列表', [arg.room], 'Gift[]'),
+    'live products': read('直播间商品', [arg.room], 'Item[]'),
+    'live media': read('直播流地址', [arg.room], 'Media[]'),
+    'live replays': list('直播回放', [arg.user], 'Item[]'),
+    'live start': write('开播', [], '{id push{url key}}'),
+    'live stop': write('下播', []),
+    'keyword suggest': read('搜索联想词', [{ name: 'prefix', summary: '输入的前缀' }], 'Keyword[]'),
+    'keyword hot': read('热搜词', [], 'Keyword[]'),
+    'notice list': list('通知列表', [], 'Notice[]', { auth: 'required' }),
+    'notice count': read('未读通知数', [], 'NoticeCount', { auth: 'required' }),
+    'msg list': list('会话列表', [], 'Conversation[]', { auth: 'required' }),
+    'msg history': list('会话的消息记录', [arg.conversation], 'Message[]', { auth: 'required' }),
+    'msg send': write('发私信；--item 表示联系商品的卖家或客服', [{ name: 'text', summary: '消息内容', optional: true }], 'Message', {
+        options: {
+            to: z.string().optional().describe('收信用户'),
+            conversation: z.string().optional().describe('会话 ID'),
+            item: z.string().optional().describe('商品：ID 或 URL'),
+            image: PUBLISH.image,
+            video: PUBLISH.video,
+        },
+        check: (a, o) => checkMsgSend(a, o),
+    }),
+    'msg listen': read('监听新消息', [], 'Message', { auth: 'required', stream: true, options: STREAM }),
+    'msg read': write('标记会话已读', [arg.conversation]),
+    'msg revoke': write('撤回消息', [arg.conversation, { name: 'message', summary: '消息 ID' }], '{id}', { confirm: true }),
+    'msg delete': write('删除会话', [arg.conversation], '{id}', { confirm: true }),
+    'media upload': write('上传媒体', [{ name: 'file', summary: '本地文件路径' }], 'Media'),
+    'folder list': list('收藏夹列表', [arg.userOrMe], 'Folder[]'),
+    'folder items': list('收藏夹里的{item}', [{ name: 'folder', summary: '收藏夹 ID' }], 'Item[]'),
+    'folder create': write('新建收藏夹', [{ name: 'name', summary: '收藏夹名字' }], 'Folder'),
+    'folder update': write('修改收藏夹', [{ name: 'folder', summary: '收藏夹 ID' }], 'Folder', {
+        options: { name: z.string().describe('新名字') },
+    }),
+    'folder delete': write('删除收藏夹', [{ name: 'folder', summary: '收藏夹 ID' }], '{id}', { confirm: true }),
+    'series list': list('合集列表', [arg.userOrMe], 'Series[]'),
+    'series items': list('合集里的{item}', [{ name: 'series', summary: '合集 ID' }], 'Item[]'),
+    'history list': list('浏览历史', [], 'Item[]', { auth: 'required' }),
+    'topic search': list('搜索话题', [arg.keyword], 'Topic[]'),
+    'poi search': list('搜索地点', [arg.keyword], 'Poi[]'),
+};
+/** 词表里的 resource，按 4.5 的顺序。 */
+export const RESOURCES = [...new Set(Object.keys(VOCAB).map((k) => k.split(' ')[0]))];
+/** 由 core 实现、自动注册到每个可用端的命令。 */
+export const CORE_COMMANDS = ['auth list', 'auth use', 'auth logout'];

package/dist/platforms/_shared/impaas.js

@@ -0,0 +1,410 @@
+import { SpecificAIError } from '../../core/errors.js';
+import { jsonDumps, jsonLoads } from '../../core/py.js';
+import * as rand from '../../core/rand.js';
+import { openSocket, reconnecting } from '../../core/stream.js';
+import { authError, paged } from '../../core/toolkit.js';
+/** listUserMessages 的起始游标（JS 的 Number.MAX_SAFE_INTEGER）。 */
+export const FIRST_CURSOR = '9007199254740991';
+/** 心跳间隔（上游 heart_beat 为 15 秒）。 */
+const HEARTBEAT_MS = 15_000;
+/** 注册后等服务端的 /s/vulcan 推送，超时后照样继续。 */
+const READY_MS = 10_000;
+// ================================================================ 帧（一个函数对应上游的一处构造）
+const imId = (p, id) => `${id}@${p.domain}`;
+const plainId = (p, id) => String(id ?? '').replace(new RegExp(`@${p.domain}$`), '');
+/** init 的第一帧：/reg。 */
+function regFrame(p, token, deviceId) {
+    return {
+        lwp: '/reg',
+        headers: {
+            'cache-header': 'app-key token ua wv',
+            'app-key': p.appKey,
+            token,
+            ua: p.ua,
+            dt: 'j',
+            wv: 'im:3,au:3,sy:6',
+            sync: '0,0;0;0;',
+            did: deviceId,
+            mid: p.mid(),
+        },
+    };
+}
+/** init 的第二帧：同步位点。 */
+function ackDiffFrame(p) {
+    const now = rand.now();
+    return {
+        lwp: '/r/SyncStatus/ackDiff',
+        headers: { mid: p.mid() },
+        body: [{ pipeline: 'sync', tooLong2Tag: 'PNM,1', channel: 'sync', topic: 'sync', highPts: 0, pts: now * 1000, seq: 0, timestamp: now }],
+    };
+}
+/** heart_beat。 */
+function heartbeatFrame(p) {
+    return { lwp: '/!', headers: { mid: p.mid() } };
+}
+/** 收到任何带 headers 的帧都回的 ack（上游 main / list_all_conversations 的循环体）。 */
+function ackFrame(p, h) {
+    const ack = { code: 200, headers: { mid: 'mid' in h ? h.mid : p.mid(), sid: 'sid' in h ? h.sid : '' } };
+    for (const key of ['app-key', 'ua', 'dt'])
+        if (key in h)
+            ack.headers[key] = h[key];
+    return ack;
+}
+/** list_all_conversations 的请求：一页 20 条，游标从大往小翻。 */
+function listFrame(p, cid, cursor) {
+    return { lwp: '/r/MessageManager/listUserMessages', headers: { mid: p.mid() }, body: [imId(p, cid), false, BigInt(cursor), 20, false] };
+}
+/** 从 SingleChatConversation/create 的响应里取会话 ID（去掉后缀）。 */
+function createdCid(p, res) {
+    const direct = res.body?.singleChatConversation?.cid ?? res.body?.cid;
+    return typeof direct === 'string' && direct ? plainId(p, direct) : null;
+}
+/** 一个平台的 IMPaaS：绑定了平台差异的帧构造与建连。 */
+export function impaas(p) {
+    return {
+        /** 加上后缀：`<id>@<domain>`。 */
+        imId: (id) => imId(p, id),
+        /** 去掉后缀。 */
+        plainId: (id) => plainId(p, id),
+        regFrame: (token, deviceId) => regFrame(p, token, deviceId),
+        ackDiffFrame: () => ackDiffFrame(p),
+        heartbeatFrame: () => heartbeatFrame(p),
+        listFrame: (cid, cursor) => listFrame(p, cid, cursor),
+        createdCid: (res) => createdCid(p, res),
+        /** 连接并注册，见 {@link Im.open}。 */
+        open: (client, options) => Im.open(p, client, options),
+    };
+}
+const realConnect = (url, headers, ctx) => openSocket(url, {
+    // Host、Connection 由 WebSocket 库自己生成
+    headers: headers.filter(([k]) => !/^(host|connection)$/i.test(k)),
+    ...(ctx.config.proxy ? { proxy: ctx.config.proxy } : {}),
+    signal: ctx.signal,
+});
+let connector = realConnect;
+/** 替换建立长连的函数，返回恢复函数。只给测试用。 */
+export function mockConnect(fn) {
+    const prev = connector;
+    connector = fn;
+    return () => {
+        connector = prev;
+    };
+}
+/** 一条私信长连：注册、ack、按 mid 配对请求与响应、收集推送。 */
+export class Im {
+    p;
+    ctx;
+    socket;
+    pending = new Map();
+    pushes = [];
+    wake = null;
+    failure = null;
+    closed = false;
+    regMid = '';
+    heartbeat = null;
+    readyResolve;
+    readyReject;
+    readyPromise = new Promise((resolve, reject) => {
+        this.readyResolve = resolve;
+        this.readyReject = reject;
+    });
+    constructor(p, ctx) {
+        this.p = p;
+        this.ctx = ctx;
+        this.readyPromise.catch(() => { });
+    }
+    /**
+     * 连接并注册（上游 init：先 get_token，再发 /reg 与 ackDiff）。listen 时再发一次心跳，之后每 15 秒一次。
+     * 上游先连接再取 token；这里先取 token，登录态无效时不必建连接。
+     */
+    static async open(p, client, options = {}) {
+        const token = await p.token(client);
+        const im = new Im(p, client.ctx);
+        im.socket = await connector(p.url, p.headers(client.cookieString()), client.ctx);
+        try {
+            const reg = regFrame(p, token, client.deviceId);
+            im.regMid = reg.headers.mid;
+            await im.send(reg);
+            await im.send(ackDiffFrame(p));
+            if (options.heartbeat) {
+                await im.send(heartbeatFrame(p));
+                im.heartbeat = setInterval(() => void im.send(heartbeatFrame(p)).catch(() => { }), HEARTBEAT_MS);
+                im.heartbeat.unref();
+            }
+        }
+        catch (err) {
+            im.close();
+            throw err;
+        }
+        void im.read();
+        return im;
+    }
+    send(frame) {
+        return this.socket.send(jsonDumps(frame));
+    }
+    /** 等服务端的 /s/vulcan（上游 list_all_conversations 收到它才发请求）；注册失败时报错。 */
+    async ready() {
+        let timer;
+        const timeout = new Promise((resolve) => (timer = setTimeout(resolve, READY_MS)));
+        try {
+            await Promise.race([this.readyPromise, timeout]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** 发请求帧，等同一 mid 的响应；code 不是 200 时报错。 */
+    async request(frame) {
+        if (this.failure)
+            throw this.failure;
+        const mid = String(frame.headers.mid);
+        const response = new Promise((resolve, reject) => this.pending.set(mid, { resolve, reject }));
+        let timer;
+        const timeout = new Promise((_, reject) => {
+            timer = setTimeout(() => {
+                this.pending.delete(mid);
+                reject(new SpecificAIError('NETWORK', `私信请求超时：${frame.lwp}`, { detail: { kind: 'timeout' } }));
+            }, this.ctx.config.timeout * 1000);
+        });
+        try {
+            await this.send(frame);
+            const res = await Promise.race([response, timeout]);
+            if (res.code !== 200)
+                throw this.responseError(frame.lwp, res);
+            return res;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /** 取一页消息记录（上游 list_all_conversations 循环里的一次请求）。游标没往前走时按没有更多处理，免得原地打转。 */
+    async historyPage(cid, cursor) {
+        const body = (await this.request(listFrame(this.p, cid, cursor))).body ?? {};
+        const nextCursor = body.nextCursor == null ? null : String(body.nextCursor);
+        const hasMore = Number(body.hasMore) === 1 && nextCursor != null && nextCursor !== cursor;
+        return { models: body.userMessageModels ?? [], nextCursor, hasMore };
+    }
+    /**
+     * 在同一条连接上按 nextCursor 往更早翻（上游 list_all_conversations：收到一页就接着发下一页的请求），
+     * 直到没有更多；调用方不再需要时提前结束迭代即可。翻页间隔用平台默认值（AGENTS 4.9）。
+     */
+    async *historyPages(cid, cursor) {
+        for (;;) {
+            const page = await this.historyPage(cid, cursor);
+            yield page;
+            if (!page.hasMore)
+                return;
+            cursor = page.nextCursor;
+            await rand.sleep(this.ctx.platform.pageInterval, this.ctx.signal);
+        }
+    }
+    /** 服务端推送（带 syncPushPackage 的帧），直到连接关闭；连接出错时抛出。 */
+    async *pushFrames() {
+        for (;;) {
+            while (this.pushes.length)
+                yield this.pushes.shift();
+            if (this.failure)
+                throw this.failure;
+            if (this.closed)
+                return;
+            await new Promise((r) => (this.wake = r));
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        this.socket?.close();
+        this.finish(null);
+    }
+    async read() {
+        try {
+            for await (const raw of this.socket.messages) {
+                let msg;
+                try {
+                    msg = jsonLoads(typeof raw === 'string' ? raw : Buffer.from(raw).toString('utf8'));
+                }
+                catch {
+                    continue;
+                }
+                const h = msg?.headers;
+                if (h && typeof h === 'object')
+                    await this.send(ackFrame(this.p, h)).catch(() => { });
+                this.dispatch(msg);
+            }
+            this.finish(this.closed ? null : new SpecificAIError('NETWORK', '私信长连接已断开', { detail: { kind: 'connect' } }));
+        }
+        catch (err) {
+            this.finish(this.closed ? null : err);
+        }
+    }
+    dispatch(msg) {
+        if (msg.lwp === '/s/vulcan')
+            this.readyResolve();
+        const mid = msg.headers?.mid;
+        if (mid != null && 'code' in msg) {
+            if (mid === this.regMid && msg.code !== 200) {
+                // 注册失败（token 无效等）：等待中的请求和推送都以它结束
+                const err = this.responseError('/reg', msg);
+                this.failure ??= err;
+                this.readyReject(err);
+                this.notify();
+                return;
+            }
+            const waiter = this.pending.get(String(mid));
+            if (waiter) {
+                this.pending.delete(String(mid));
+                waiter.resolve(msg);
+                return;
+            }
+        }
+        if (msg.body?.syncPushPackage) {
+            this.pushes.push(msg);
+            this.notify();
+        }
+    }
+    responseError(lwp, res) {
+        const reason = String(res.body?.reason ?? res.body?.message ?? res.body?.msg ?? '');
+        if (res.code === 401)
+            return authError(this.ctx, `私信登录失败：${reason || res.code}`);
+        return new SpecificAIError('UPSTREAM', `私信请求 ${lwp} 失败：${reason || res.code}`, { detail: { code: res.code, body: res.body ?? null } });
+    }
+    /** 连接结束（主动关闭或断线）：停心跳，等待中的请求和推送都以错误结束。 */
+    finish(err) {
+        if (err && !this.failure)
+            this.failure = err;
+        this.closed = true;
+        // 断线时 read() 先走到这里，之后的 close() 会直接返回，心跳必须在这里停
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = null;
+        const e = this.failure ?? new SpecificAIError('NETWORK', '私信长连接已关闭', { detail: { kind: 'connect' } });
+        for (const w of this.pending.values())
+            w.reject(e);
+        this.pending.clear();
+        this.readyReject(e);
+        this.notify();
+    }
+    notify() {
+        const w = this.wake;
+        this.wake = null;
+        w?.();
+    }
+}
+// ================================================================ 命令里的共同流程
+/**
+ * msg history 截在一页中间时的游标：`<这一页的起始游标>+<N>`，续翻时重取这一页、跳过已经输出的 N 条。
+ * 与 core 的 `<游标>#skip=N` 同义（cli/dispatch 的 runPaged）；写法不同，是因为 core 见到 `#skip=N` 会自己从结果的
+ * 前面丢掉 N 条，而这里的结果是反转过的（从旧到新），要丢的是这一页最新的 N 条，只能由 handler 自己跳过。
+ */
+const RESUME_RE = /^(\d+)\+(\d+)$/;
+/**
+ * msg history：上游 list_all_conversations 在一条连接上按 nextCursor 一直翻到底；这里也在同一条连接上翻，
+ * 翻到 `--limit` 条或（`--all`）没有更多为止，不带时只取一页，不让 core 每页重新取 token、建连接、注册、等 /s/vulcan。
+ * 接口从新到旧给；取最新的那些条，再像上游一样反转成从旧到新。`page.cursor` 接着往更早翻。
+ */
+export async function history(ctx, open, cid, toMessage) {
+    const resume = RESUME_RE.exec(ctx.cursor ?? '');
+    const cursor = resume ? resume[1] : (ctx.cursor ?? FIRST_CURSOR);
+    if (!/^\d+$/.test(cursor))
+        throw new SpecificAIError('USAGE', `--cursor 不对：${ctx.cursor}`, { hint: '用上次输出的 page.cursor' });
+    let skip = resume ? Number(resume[2]) : 0;
+    const { limit, all } = ctx.options;
+    // 不带 --limit / --all 时只取一页
+    const want = limit ?? (all ? Infinity : 0);
+    const im = await open();
+    try {
+        await im.ready();
+        const models = [];
+        const done = (next, more) => paged(models.reverse().map(toMessage), next, more);
+        let start = cursor;
+        let last = null;
+        for await (const page of im.historyPages(cid, cursor)) {
+            const fresh = page.models.slice(skip);
+            if (want > 0 && models.length + fresh.length > want) {
+                // --limit 截在这一页中间：留下最新的，游标指回这一页的起始，续翻时跳过已经输出的
+                const take = want - models.length;
+                models.push(...fresh.slice(0, take));
+                return done(`${start}+${skip + take}`, true);
+            }
+            models.push(...fresh);
+            skip = 0;
+            last = page;
+            if (models.length >= want)
+                break;
+            start = page.nextCursor;
+        }
+        return done(last?.nextCursor, last?.hasMore ?? false);
+    }
+    finally {
+        im.close();
+    }
+}
+/** base64 解开后就是 JSON 文本（以 `{` 开头）：会话唤起（contentType 8）等状态推送，不是 MessagePack。 */
+function isBase64Json(data) {
+    const head = Buffer.from(data.slice(0, 8), 'base64');
+    return head[0] === 0x7b;
+}
+/**
+ * 推送帧里的聊天消息：syncPushPackage.data[].data 是 base64 + MessagePack，用平台的上游 JS 解码成 JSON；
+ * 能直接解析成 JSON 的是状态类推送，跳过（上游 handle_message）。base64 里直接是 JSON 的也是状态推送
+ * （真机 2026-09-29：建连后会收到一批会话唤起），同样跳过，不当成解码失败。
+ */
+export function* pushedPayloads(frame, decrypt, ctx) {
+    for (const entry of frame?.body?.syncPushPackage?.data ?? []) {
+        const data = entry?.data;
+        if (typeof data !== 'string')
+            continue;
+        try {
+            jsonLoads(data);
+            continue;
+        }
+        catch { }
+        if (isBase64Json(data))
+            continue;
+        let decoded;
+        try {
+            decoded = jsonLoads(decrypt(data));
+        }
+        catch (err) {
+            ctx.log.debug(`推送解码失败：${err.message}`);
+            continue;
+        }
+        yield decoded;
+    }
+}
+const isAuthError = (err) => err instanceof SpecificAIError && (err.code === 'AUTH_REQUIRED' || err.code === 'AUTH_EXPIRED');
+/** 登录态失效时不再重连：由重连循环里的连接交出来，在外面抛出。 */
+class Fatal {
+    error;
+    constructor(error) {
+        this.error = error;
+    }
+}
+/**
+ * msg listen：带心跳的长连（上游 main），断线自动重连；登录态失效时直接抛出，不再重连。
+ * messages 从一帧推送里取要输出的消息。
+ */
+export async function* listen(ctx, open, messages) {
+    const stream = reconnecting(ctx, async function* () {
+        let im = null;
+        try {
+            im = await open();
+            for await (const frame of im.pushFrames())
+                yield* messages(frame);
+        }
+        catch (err) {
+            if (!isAuthError(err))
+                throw err;
+            yield new Fatal(err);
+        }
+        finally {
+            im?.close();
+        }
+    });
+    for await (const item of stream) {
+        if (item instanceof Fatal)
+            throw item.error;
+        yield item;
+    }
+}