specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/core/login.js

@@ -0,0 +1,191 @@
+import { readFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { text as readStreamText } from 'node:stream/consumers';
+import QRCode from 'qrcode';
+import { endpointFlag, getCurrent, newCredential, readCredential, setCurrent, toAccount, writeCredential } from './auth-store.js';
+import { parseCookieInput } from './cookies.js';
+import { SpecificAIError } from './errors.js';
+import { writeFileAtomic } from './fsutil.js';
+import { cacheDir } from './paths.js';
+import { now, sleep } from './rand.js';
+/** 登录流程的公共部分（AGENTS 5.3）。各平台的 `auth login` handler 调用这些函数。 */
+/** 登录到哪个账号：`-a` > 当前账号 > `default`。 */
+export function loginTarget(ctx) {
+    return ctx.account ?? 'default';
+}
+/**
+ * 登录流程里校验新凭证用的上下文：账号是要登录到的那个（出错时提示里的账号名对得上），凭证是还没落盘的新凭证。
+ */
+export function loginContext(ctx, credential) {
+    return { ...ctx, account: loginTarget(ctx), credential };
+}
+/** 登录方式对应的新凭证（还没落盘）。 */
+export function freshCredential(ctx, method) {
+    return newCredential({ platform: ctx.platform.id, endpoint: ctx.endpoint, account: loginTarget(ctx), method });
+}
+/**
+ * 登录成功后落盘：账号名下已经存了另一个用户时报 USAGE，新凭证不保存；
+ * 还没有当前账号时，把它设为当前账号。
+ */
+export async function finishLogin(ctx, credential, user) {
+    const p = ctx.platform.id;
+    const account = loginTarget(ctx);
+    const existing = await readCredential(p, ctx.endpoint, account).catch(() => null);
+    if (existing?.user && existing.user.id !== user.id) {
+        throw new SpecificAIError('USAGE', `账号名 ${account} 下已经保存了另一个用户（${existing.user.name ?? existing.user.id}）`, {
+            hint: `用 -a <新名字> 登录，或者先 specific-ai ${p} auth logout -a ${account}${endpointFlag(ctx.endpoint)}`,
+        });
+    }
+    credential.account = account;
+    credential.user = user;
+    if (existing)
+        credential.created_at = existing.created_at;
+    await writeCredential(credential);
+    let current = await getCurrent(p, ctx.endpoint);
+    if (!current) {
+        await setCurrent(p, ctx.endpoint, account);
+        current = account;
+    }
+    ctx.log.info(`已登录 ${ctx.platform.name}：${user.name ?? user.id}（账号 ${account}）`);
+    return toAccount(credential, current === account);
+}
+/** `--cookie <str|@file|->`：dispatch 已经把 @file 和 - 读成字符串。 */
+export function cookieCredential(ctx, defaultDomain) {
+    const input = ctx.options.cookie;
+    if (!input?.trim()) {
+        throw new SpecificAIError('USAGE', 'cookie 登录需要 --cookie', { hint: `specific-ai ${ctx.platform.id} auth login --method cookie --cookie "<cookie>"` });
+    }
+    const credential = freshCredential(ctx, 'cookie');
+    try {
+        credential.scopes.main.cookies = parseCookieInput(input, defaultDomain);
+    }
+    catch {
+        throw new SpecificAIError('USAGE', '无法解析 --cookie 的内容', { hint: '传浏览器请求头里的 Cookie 字符串，或导出的 cookie JSON 数组' });
+    }
+    if (!credential.scopes.main.cookies.length)
+        throw new SpecificAIError('USAGE', '--cookie 里没有 cookie');
+    return credential;
+}
+/** 二维码：画到 stderr，同时把 PNG 存到 cache/<p>/qrcode.png。 */
+export async function showQrcode(ctx, content, hint = '请用 App 扫码') {
+    const png = join(cacheDir(ctx.platform.id), 'qrcode.png');
+    await writeFileAtomic(png, await QRCode.toBuffer(content, { margin: 2, scale: 8 }));
+    const art = await QRCode.toString(content, { type: 'terminal', small: true });
+    process.stderr.write(art + '\n');
+    ctx.log.info(`${hint}。二维码图片：${png}`);
+    return png;
+}
+/** 轮询时最多容忍的连续网络错误次数（含最后一次）。 */
+const POLL_NETWORK_RETRIES = 4;
+/** 按间隔轮询，直到返回非 undefined 的值；超时报 AUTH_REQUIRED。 */
+export async function poll(fn, options = {}) {
+    const deadline = now() + (options.timeout ?? 180_000);
+    // 扫码要等几分钟，期间偶发的网络错误（连接被重置、本机地址暂不可用等）不该让整个登录失败；连续失败才放弃
+    let networkErrors = 0;
+    for (;;) {
+        let result;
+        try {
+            result = await fn();
+            networkErrors = 0;
+        }
+        catch (err) {
+            if (!(err instanceof SpecificAIError && err.code === 'NETWORK') || ++networkErrors >= POLL_NETWORK_RETRIES)
+                throw err;
+            process.stderr.write(`[specific-ai] 警告：轮询时网络出错，稍后重试（${networkErrors}/${POLL_NETWORK_RETRIES - 1}）：${err.message}\n`);
+        }
+        if (result !== undefined)
+            return result;
+        if (now() >= deadline)
+            throw new SpecificAIError('AUTH_REQUIRED', `${options.what ?? '登录'}超时`, { hint: '重新执行登录命令' });
+        await sleep(options.interval ?? 2000);
+    }
+}
+/** 是否可以交互输入（stdin 与 stderr 都是 TTY）。 */
+export function interactive() {
+    return Boolean(process.stdin.isTTY && process.stderr.isTTY);
+}
+/** 在 stderr 上提问，读一行。hidden 时不回显（密码）。 */
+export async function prompt(question, options = {}) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    if (options.hidden) {
+        const write = rl._writeToOutput;
+        rl._writeToOutput = (s) => {
+            if (s.startsWith(question))
+                write.call(rl, s);
+        };
+    }
+    try {
+        return await new Promise((resolve) => rl.question(question, resolve));
+    }
+    finally {
+        if (options.hidden)
+            process.stderr.write('\n');
+        rl.close();
+    }
+}
+/** `--password-stdin`：TTY 下隐藏输入，否则读完整个 stdin。 */
+export async function readPassword(ctx) {
+    if (!ctx.options.passwordStdin) {
+        throw new SpecificAIError('USAGE', '密码只从 stdin 读取，请加 --password-stdin', {
+            hint: `specific-ai ${ctx.platform.id} auth login --method password --username <name> --password-stdin`,
+        });
+    }
+    const password = process.stdin.isTTY ? await prompt('密码：', { hidden: true }) : (await readStreamText(process.stdin)).replace(/\r?\n$/, '');
+    if (!password)
+        throw new SpecificAIError('USAGE', '密码为空');
+    return password;
+}
+const SMS_TTL = 10 * 60 * 1000;
+function smsFile(ctx) {
+    return join(cacheDir(ctx.platform.id), `sms-${ctx.endpoint}-${loginTarget(ctx)}.json`);
+}
+/** 短信登录的中间态（非 TTY 分两步时用），10 分钟有效。 */
+export const smsState = {
+    async save(ctx, data) {
+        await writeFileAtomic(smsFile(ctx), JSON.stringify({ saved_at: now(), data }));
+    },
+    async load(ctx) {
+        try {
+            const { saved_at, data } = JSON.parse(await readFile(smsFile(ctx), 'utf8'));
+            return now() - saved_at < SMS_TTL ? data : null;
+        }
+        catch {
+            return null;
+        }
+    },
+    async clear(ctx) {
+        await rm(smsFile(ctx), { force: true });
+    },
+};
+/**
+ * 短信登录的通用流程。平台提供 send（发验证码，返回需要保存的中间态）和 verify（用验证码完成登录）。
+ * TTY 下一步完成；非 TTY 下先 `--phone` 发码，再单独用 `--code` 完成。
+ */
+export async function smsLogin(ctx, flow) {
+    const phone = ctx.options.phone;
+    const code = ctx.options.code;
+    const p = ctx.platform.id;
+    const cmd = `specific-ai ${p} auth login --method sms${ctx.account ? ` -a ${ctx.account}` : ''}${endpointFlag(ctx.endpoint)}`;
+    if (code) {
+        const state = await smsState.load(ctx);
+        if (!state)
+            throw new SpecificAIError('USAGE', '没有找到有效的短信登录中间态（10 分钟内有效）', { hint: `${cmd} --phone <手机号>` });
+        const account = await flow.verify(state, code);
+        await smsState.clear(ctx);
+        return account;
+    }
+    if (!phone) {
+        if (!interactive())
+            throw new SpecificAIError('USAGE', '短信登录需要 --phone', { hint: `${cmd} --phone <手机号>` });
+    }
+    const target = phone ?? (await prompt('手机号：'));
+    const state = await flow.send(target);
+    if (!interactive()) {
+        await smsState.save(ctx, state);
+        ctx.log.info(`验证码已发送到 ${target}。收到后执行：${cmd} --code <验证码>`);
+        return { sent: true, phone: target };
+    }
+    const input = await prompt('验证码：');
+    return flow.verify(state, input.trim());
+}

package/dist/core/mp4.js

@@ -0,0 +1,130 @@
+import { SpecificAIError } from './errors.js';
+/** 第一条视频轨（hdlr 为 vide）。不是 MP4 / MOV 时报 USAGE。 */
+export function mp4VideoTrack(data) {
+    const buf = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+    const boxes = (start, end) => {
+        const out = [];
+        let p = start;
+        while (p + 8 <= end) {
+            let size = buf.readUInt32BE(p);
+            const type = buf.toString('latin1', p + 4, p + 8);
+            let header = 8;
+            if (size === 1) {
+                if (p + 16 > end)
+                    break;
+                size = Number(buf.readBigUInt64BE(p + 8));
+                header = 16;
+            }
+            else if (size === 0)
+                size = end - p;
+            if (size < header || p + size > end)
+                break;
+            out.push({ type, start: p + header, end: p + size });
+            p += size;
+        }
+        return out;
+    };
+    const find = (list, type) => list.find((b) => b.type === type);
+    const moov = find(boxes(0, buf.length), 'moov');
+    if (!moov)
+        throw new SpecificAIError('USAGE', '只支持 MP4 / MOV 视频（找不到 moov）');
+    for (const trak of boxes(moov.start, moov.end).filter((b) => b.type === 'trak')) {
+        const inner = boxes(trak.start, trak.end);
+        const mdia = find(inner, 'mdia');
+        const tkhd = find(inner, 'tkhd');
+        if (!mdia || !tkhd)
+            continue;
+        const mdiaBoxes = boxes(mdia.start, mdia.end);
+        const hdlr = find(mdiaBoxes, 'hdlr');
+        if (!hdlr || buf.toString('latin1', hdlr.start + 8, hdlr.start + 12) !== 'vide')
+            continue;
+        // tkhd 末尾：矩阵 9 × int32，然后宽、高（16.16）
+        const displayWidth = Math.round(buf.readUInt32BE(tkhd.end - 8) / 65536);
+        const displayHeight = Math.round(buf.readUInt32BE(tkhd.end - 4) / 65536);
+        const matrix = tkhd.end - 8 - 36;
+        const a = buf.readInt32BE(matrix) / 65536;
+        const b = buf.readInt32BE(matrix + 4) / 65536;
+        const rotation = (((Math.round((Math.atan2(b, a) * 180) / Math.PI) % 360) + 360) % 360) || 0;
+        const mdhd = find(mdiaBoxes, 'mdhd');
+        let timescale = 0;
+        let duration = 0;
+        if (mdhd) {
+            const v1 = buf[mdhd.start] === 1;
+            timescale = buf.readUInt32BE(mdhd.start + (v1 ? 20 : 12));
+            duration = v1 ? Number(buf.readBigUInt64BE(mdhd.start + 24)) : buf.readUInt32BE(mdhd.start + 16);
+        }
+        const minf = find(mdiaBoxes, 'minf');
+        const stbl = minf && find(boxes(minf.start, minf.end), 'stbl');
+        const stblBoxes = stbl ? boxes(stbl.start, stbl.end) : [];
+        let sttsSamples = 0;
+        let sttsDuration = 0;
+        const stts = find(stblBoxes, 'stts');
+        if (stts) {
+            const n = buf.readUInt32BE(stts.start + 4);
+            for (let i = 0; i < n && stts.start + 16 + i * 8 <= stts.end; i++) {
+                const count = buf.readUInt32BE(stts.start + 8 + i * 8);
+                sttsSamples += count;
+                sttsDuration += count * buf.readUInt32BE(stts.start + 12 + i * 8);
+            }
+        }
+        const stsz = find(stblBoxes, 'stsz');
+        const sampleCount = stsz ? buf.readUInt32BE(stsz.start + 8) : sttsSamples;
+        // stsd：版本 / 标志 4 + 条目数 4，第一个样本项的头 8 + 保留 6 + 引用索引 2 + 预定义 / 保留 16，然后宽、高（uint16）
+        let codedWidth = 0;
+        let codedHeight = 0;
+        const stsd = find(stblBoxes, 'stsd');
+        if (stsd && stsd.start + 8 + 36 <= stsd.end) {
+            codedWidth = buf.readUInt16BE(stsd.start + 8 + 32);
+            codedHeight = buf.readUInt16BE(stsd.start + 8 + 34);
+        }
+        return { displayWidth, displayHeight, codedWidth, codedHeight, rotation, timescale, duration, sttsSamples, sttsDuration, sampleCount };
+    }
+    throw new SpecificAIError('USAGE', '视频里没有可识别的视频轨（尺寸 / 时长）');
+}
+/** libavutil 的 av_reduce：约分，超过 max 时用连分数逼近。 */
+export function avReduce(num, den, max) {
+    const abs = (x) => (x < 0n ? -x : x);
+    const gcd = (x, y) => (y === 0n ? x : gcd(y, x % y));
+    const sign = num < 0n !== den < 0n;
+    const g = gcd(abs(num), abs(den));
+    if (g) {
+        num = abs(num) / g;
+        den = abs(den) / g;
+    }
+    let a0 = [0n, 1n];
+    let a1 = [1n, 0n];
+    if (num <= max && den <= max) {
+        a1 = [num, den];
+        den = 0n;
+    }
+    while (den) {
+        let x = num / den;
+        const next = num - den * x;
+        const a2n = x * a1[0] + a0[0];
+        const a2d = x * a1[1] + a0[1];
+        if (a2n > max || a2d > max) {
+            if (a1[0])
+                x = (max - a0[0]) / a1[0];
+            if (a1[1]) {
+                const y = (max - a0[1]) / a1[1];
+                if (y < x)
+                    x = y;
+            }
+            if (den * (2n * x * a1[1] + a0[1]) > num * a1[1])
+                a1 = [x * a1[0] + a0[0], x * a1[1] + a0[1]];
+            break;
+        }
+        a0 = a1;
+        a1 = [a2n, a2d];
+        num = den;
+        den = next;
+    }
+    return [sign ? -a1[0] : a1[0], a1[1]];
+}
+/** ffmpeg mov 解复用器的 avg_frame_rate：time_scale × 帧数 / 帧时长之和（opencv 的 CAP_PROP_FPS 取它）。 */
+export function mp4AvgFrameRate(t) {
+    if (!(t.sttsDuration > 0 && t.sttsSamples > 0 && t.timescale > 0))
+        return 0;
+    const [num, den] = avReduce(BigInt(t.timescale) * BigInt(t.sttsSamples), BigInt(t.sttsDuration), 0x7fffffffn);
+    return Number(num) / Number(den);
+}

package/dist/core/normalize.js

@@ -0,0 +1,207 @@
+import { isoNow } from './fsutil.js';
+import { now } from './rand.js';
+import { withRaw } from './schemas.js';
+/**
+ * 归一化工具（AGENTS 6.2）：计数、时间、ID 的转换，以及各类型的构造函数。
+ * 构造函数补齐缺省字段（null / []），保证"字段总是存在"；传入 raw 时挂上原始对象供 `--raw` 使用。
+ */
+const UNITS = { 万: 1e4, w: 1e4, W: 1e4, 亿: 1e8, k: 1e3, K: 1e3, m: 1e6, M: 1e6, 千: 1e3 };
+/** 计数转整数：`1.2万` → 12000，`10w+` → 100000，`1,234` → 1234。无法识别时为 null。 */
+export function count(value) {
+    if (value == null || value === '')
+        return null;
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? Math.round(value) : null;
+    if (typeof value === 'bigint')
+        return Number(value);
+    const m = /^\s*([\d.,]+)\s*([万wW亿kKmM千]?)\+?\s*$/.exec(String(value));
+    if (!m)
+        return null;
+    const n = Number(m[1].replaceAll(',', ''));
+    return Number.isFinite(n) ? Math.round(n * (m[2] ? UNITS[m[2]] : 1)) : null;
+}
+/** ID 一律是字符串。 */
+export function id(value) {
+    return value == null ? '' : String(value);
+}
+export function idOrNull(value) {
+    return value == null || value === '' ? null : String(value);
+}
+export function str(value) {
+    return value == null || value === '' ? null : String(value);
+}
+/** 不带时区的日期时间：`2025-08-01 12:00`、`2025-08-01T12:00:00`。 */
+const NAIVE_TIME = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2})(:\d{2}(?:\.\d+)?)?$/;
+/**
+ * 时间转带时区的 ISO 8601。数字按量级判断：小于 1e11 视为秒，小于 1e14 为毫秒，再大是微秒；
+ * 字符串先按数字处理；不带时区的日期时间按北京时间（这些平台给的本地时间都是北京时间，
+ * 不能按运行 specific-ai 的机器所在时区解析）；其余交给 Date 解析。
+ */
+export function time(value) {
+    if (value == null || value === '' || value === 0 || value === '0')
+        return null;
+    let ms;
+    if (typeof value === 'number' || (typeof value === 'string' && /^\d+(\.\d+)?$/.test(value))) {
+        const n = Number(value);
+        ms = n < 1e11 ? n * 1000 : n < 1e14 ? n : Math.floor(n / 1000);
+    }
+    else if (value instanceof Date)
+        ms = value.getTime();
+    else {
+        const s = String(value).trim();
+        const naive = NAIVE_TIME.exec(s);
+        ms = Date.parse(naive ? `${naive[1]}T${naive[2]}${naive[3] ?? ':00'}+08:00` : s);
+    }
+    return Number.isFinite(ms) ? isoNow(new Date(ms)) : null;
+}
+/** 秒数（可带小数）；毫秒请先除以 1000。 */
+export function seconds(value) {
+    if (value == null || value === '')
+        return null;
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+}
+/** `//host/path` 与 `http://` 统一成 `https://`。 */
+export function url(value) {
+    if (value == null || value === '')
+        return null;
+    const s = String(value);
+    if (s.startsWith('//'))
+        return 'https:' + s;
+    if (s.startsWith('http://'))
+        return 'https://' + s.slice(7);
+    return s;
+}
+/** 金额（元）：数字，或 `¥1,099.00`、`总额 -23.28` 这类带符号、千分位的字符串。 */
+export function price(amount, currency = 'CNY') {
+    if (amount == null || amount === '')
+        return null;
+    const m = typeof amount === 'number' ? null : /-?\d[\d,]*(?:\.\d+)?/.exec(String(amount));
+    const n = typeof amount === 'number' ? amount : m ? Number(m[0].replaceAll(',', '')) : NaN;
+    return Number.isFinite(n) ? { amount: n, currency } : null;
+}
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', yen: '¥', middot: '·', hellip: '…', ldquo: '“', rdquo: '”', lsquo: '‘', rsquo: '’', mdash: '—', ndash: '–', times: '×' };
+/** HTML 实体解码（`html.unescape` 的常用子集）：命名实体与 `&#39;` / `&#x27;` 这类数字实体。 */
+export function unescapeHtml(s) {
+    return s.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);?/gi, (m, e) => {
+        if (e[0] === '#') {
+            const code = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+            return Number.isFinite(code) && code <= 0x10ffff ? String.fromCodePoint(code) : m;
+        }
+        return ENTITIES[e.toLowerCase()] ?? m;
+    });
+}
+/**
+ * HTML 片段 → 纯文本：`<br>` 还原成换行，图片（表情）取 alt，其余标签去掉，实体解码。空串为 null。
+ * 用于搜索结果的高亮标签、微博正文等。
+ */
+export function plainText(html) {
+    if (html == null || html === '')
+        return null;
+    const text = unescapeHtml(String(html)
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<img[^>]*?\balt=(["'])(.*?)\1[^>]*>/gi, '$2')
+        .replace(/<[^>]+>/g, ''));
+    return text === '' ? null : text;
+}
+function attach(value, raw) {
+    return raw === undefined ? value : withRaw(value, raw);
+}
+export function userRef(v) {
+    if (!v || v.id == null || v.id === '')
+        return null;
+    return { id: id(v.id), name: str(v.name), url: url(v.url) };
+}
+export function user(v, raw) {
+    return attach({
+        id: v.id,
+        name: v.name ?? null,
+        handle: v.handle ?? null,
+        avatar: v.avatar ?? null,
+        url: v.url ?? null,
+        bio: v.bio ?? null,
+        stats: { followers: null, following: null, items: null, likes: null, ...v.stats },
+    }, raw);
+}
+export function media(v, raw) {
+    return attach({ id: v.id ?? null, type: v.type, url: v.url, width: v.width ?? null, height: v.height ?? null, duration: v.duration ?? null }, raw);
+}
+export function item(v, raw) {
+    return attach({
+        id: v.id,
+        kind: v.kind,
+        url: v.url ?? null,
+        title: v.title ?? null,
+        text: v.text ?? null,
+        author: v.author ?? null,
+        created_at: v.created_at ?? null,
+        cover: v.cover ?? null,
+        media: v.media ?? [],
+        stats: { views: null, likes: null, comments: null, collects: null, shares: null, ...v.stats },
+        price: v.price ?? null,
+        status: v.status ?? null,
+    }, raw);
+}
+export function comment(v, raw) {
+    return attach({
+        id: v.id,
+        item_id: v.item_id,
+        parent_id: v.parent_id ?? null,
+        author: v.author ?? null,
+        text: v.text,
+        created_at: v.created_at ?? null,
+        stats: { likes: null, replies: null, ...v.stats },
+    }, raw);
+}
+export function folder(v, raw) {
+    return attach({ id: v.id, name: v.name, count: v.count ?? null, url: v.url ?? null }, raw);
+}
+export function category(v, raw) {
+    return attach({ id: v.id, name: v.name, parent_id: v.parent_id ?? null }, raw);
+}
+export function keyword(v, raw) {
+    return attach({ text: v.text, heat: v.heat ?? null }, raw);
+}
+export function topic(v, raw) {
+    return attach({ id: v.id, name: v.name, url: v.url ?? null, stats: { views: null, items: null, ...v.stats } }, raw);
+}
+export function poi(v, raw) {
+    return attach({ id: v.id, name: v.name, address: v.address ?? null }, raw);
+}
+export function live(v, raw) {
+    return attach({ id: v.id, url: v.url ?? null, title: v.title ?? null, status: v.status, host: v.host ?? null, cover: v.cover ?? null, stats: { viewers: null, ...v.stats } }, raw);
+}
+export function event(v, raw) {
+    return attach({ type: v.type, time: v.time ?? isoNow(new Date(now())), user: v.user ?? null, text: v.text ?? null, gift: v.gift ?? null }, raw);
+}
+export function gift(v, raw) {
+    return attach({ id: v.id, name: v.name, price: v.price ?? null }, raw);
+}
+export function rank(v, raw) {
+    return attach({ rank: v.rank, user: v.user, score: v.score ?? null }, raw);
+}
+export function conversation(v, raw) {
+    return attach({ id: v.id, peer: v.peer ?? null, unread: v.unread ?? null, last_message: v.last_message ?? null, updated_at: v.updated_at ?? null }, raw);
+}
+export function message(v, raw) {
+    return attach({
+        id: v.id,
+        conversation_id: v.conversation_id,
+        from: v.from ?? null,
+        type: v.type ?? 'text',
+        text: v.text ?? null,
+        media: v.media ?? [],
+        created_at: v.created_at ?? null,
+    }, raw);
+}
+export function notice(v, raw) {
+    return attach({ id: v.id, type: v.type, user: v.user ?? null, target: v.target ?? null, text: v.text ?? null, created_at: v.created_at ?? null }, raw);
+}
+export function noticeCount(v, raw) {
+    const parts = { comment: v.comment ?? null, mention: v.mention ?? null, like: v.like ?? null, follow: v.follow ?? null, system: v.system ?? null };
+    const total = v.total ?? Object.values(parts).reduce((s, n) => s + (n ?? 0), 0);
+    return attach({ total, ...parts }, raw);
+}
+export function file(v) {
+    return v;
+}

package/dist/core/options.js

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+/** 标准选项（AGENTS 4.9）。平台私有选项不能与它们重名。 */
+export const PAGING = {
+    limit: z.number().int().positive().optional().describe('取满 N 条，自动翻页'),
+    cursor: z.string().optional().describe('从上次返回的 page.cursor 继续翻'),
+    all: z.boolean().optional().describe('一直翻到没有更多'),
+};
+export const FILTER_VALUES = {
+    sort: ['general', 'latest', 'popular', 'views', 'comments', 'collects', 'sales', 'price_asc', 'price_desc'],
+    type: ['all', 'video', 'image', 'text', 'article', 'goods'],
+    time: ['all', 'day', 'week', 'month', 'half_year', 'year'],
+    kind: ['recommend', 'hot', 'following'],
+};
+export const LOGIN_METHODS = ['qrcode', 'sms', 'password', 'cookie'];
+export const VISIBILITY_VALUES = ['public', 'private', 'friends', 'fans'];
+/**
+ * 有标准取值的选项。取值是标准值、但平台不支持时报 UNSUPPORTED；不是标准值时报 USAGE。
+ */
+export const STANDARD_VALUES = { ...FILTER_VALUES, method: LOGIN_METHODS, visibility: VISIBILITY_VALUES };
+const FILTER_SUMMARY = { sort: '排序', type: '类型', time: '时间范围', kind: '流的种类' };
+function makeFilter(name, values, preferred) {
+    if (values.length === 0)
+        throw new Error(`filter.${name}() 至少要一个取值`);
+    const schema = z.enum(values).describe(FILTER_SUMMARY[name]);
+    return preferred && values.includes(preferred) ? schema.default(preferred) : schema.optional();
+}
+/** 在注册表里声明平台支持的筛选取值，例如 `filter.sort('general', 'latest')`。 */
+export const filter = {
+    sort: (...values) => makeFilter('sort', values),
+    type: (...values) => makeFilter('type', values),
+    time: (...values) => makeFilter('time', values),
+    kind: (...values) => makeFilter('kind', values, 'recommend'),
+};
+/** `--visibility` 的取值。平台支持的与默认的 public / private / friends 不同时，在注册表里声明，例如 `visibility('public', 'fans')`。 */
+export const visibility = (...values) => z.enum(values).default('public').describe('可见范围');
+export const CATEGORY = z.string().optional().describe('分类 id，取值来自对应的 categories 命令');
+/** `comment list --product`：传纯 ID 时按商品处理，列出商品评价（AGENTS 4.8）。 */
+export const PRODUCT = z.boolean().optional().describe('把参数当作商品，列出商品评价');
+export const PUBLISH = {
+    title: z.string().optional().describe('标题'),
+    text: z.string().optional().describe('正文，@file 表示从文件读取'),
+    image: z.array(z.string()).optional().describe('图片（路径或 URL）'),
+    video: z.string().optional().describe('视频（路径或 URL）'),
+    cover: z.string().optional().describe('封面（路径或 URL）'),
+    tag: z.array(z.string()).optional().describe('标签'),
+    topic: z.array(z.string()).optional().describe('话题'),
+    mention: z.array(z.string()).optional().describe('@ 的用户'),
+    poi: z.string().optional().describe('地点 id'),
+    category: CATEGORY,
+    visibility: visibility('public', 'private', 'friends'),
+    schedule: z.iso.datetime({ offset: true, local: true }).optional().describe('定时发布（ISO 时间）'),
+    price: z.number().positive().optional().describe('商品价格（元）'),
+};
+/**
+ * `--quote <item>`：发成引用（AGENTS 4.9「发布」）。不放进 PUBLISH：目前只有 x 支持，由 x 在注册表里声明，
+ * 其他平台的 item publish 不接受这个选项。
+ */
+export const QUOTE = z.string().optional().describe('引用一条内容：ID 或 URL');
+export const DOWNLOAD = {
+    dir: z.string().optional().describe('下载目录，默认当前目录'),
+    overwrite: z.boolean().optional().describe('覆盖已有文件，默认跳过'),
+};
+const DURATION_RE = /^(\d+(?:\.\d+)?)(s|m|h)?$/;
+export const STREAM = {
+    duration: z.string().regex(DURATION_RE, '格式为秒数，或 30s、10m、1h').optional().describe('运行时长，例如 600、10m、1h'),
+};
+/** `--duration` 转成毫秒。 */
+export function parseDuration(value) {
+    const m = DURATION_RE.exec(value);
+    if (!m)
+        throw new Error(`无效的时长：${value}`);
+    const unit = { s: 1, m: 60, h: 3600 }[(m[2] ?? 's')];
+    return Number(m[1]) * unit * 1000;
+}
+export const STANDARD_OPTIONS = {
+    ...PAGING,
+    ...Object.fromEntries(Object.keys(FILTER_VALUES).map((k) => [k, z.string().optional()])),
+    ...PUBLISH,
+    quote: QUOTE,
+    ...DOWNLOAD,
+    ...STREAM,
+};
+/** 从 zod schema 读出 argv 需要的信息：类型、是否必填、默认值、枚举值、说明。 */
+export function describeOption(schema) {
+    let s = schema;
+    let required = true;
+    let dflt;
+    let description = s.description ?? null;
+    for (;;) {
+        const def = s._zod.def;
+        if (def.type === 'optional' || def.type === 'nullable')
+            required = false;
+        else if (def.type === 'default') {
+            required = false;
+            dflt = def.defaultValue;
+        }
+        else
+            break;
+        s = def.innerType;
+        description ??= s.description ?? null;
+    }
+    const type = s._zod.def.type;
+    const kind = type === 'boolean' ? 'boolean' : type === 'number' ? 'number' : type === 'array' ? 'array' : 'string';
+    const values = type === 'enum' ? s.options : null;
+    return { kind, required, default: dflt, values, description };
+}
+/** camelCase 键名 → kebab-case 选项名。 */
+export function flagName(key) {
+    return key.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+}

package/dist/core/paths.js

@@ -0,0 +1,38 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** 包根目录：从本文件向上找 name 为 specific-ai-cli 的 package.json（src/、dist/ 或其他编译输出目录都适用）。 */
+export const PACKAGE_ROOT = findRoot(dirname(fileURLToPath(import.meta.url)));
+function findRoot(dir) {
+    for (let d = dir;; d = dirname(d)) {
+        try {
+            if (JSON.parse(readFileSync(join(d, 'package.json'), 'utf8')).name === 'specific-ai-cli')
+                return d;
+        }
+        catch { }
+        if (dirname(d) === d)
+            return resolve(dir, '../..');
+    }
+}
+export function packageJson() {
+    return JSON.parse(readFileSync(join(PACKAGE_ROOT, 'package.json'), 'utf8'));
+}
+/** 数据目录：SPECIFIC_AI_HOME 或 ~/.specific-ai。 */
+export function specificAiHome() {
+    const env = process.env.SPECIFIC_AI_HOME;
+    return env ? resolve(env) : join(homedir(), '.specific-ai');
+}
+export function configFile() {
+    return join(specificAiHome(), 'config.toml');
+}
+export function authDir(...parts) {
+    return join(specificAiHome(), 'auth', ...parts);
+}
+export function cacheDir(platform) {
+    return join(specificAiHome(), 'cache', platform);
+}
+/** 上游签名 JS 等静态资源：static/<p>/<file>。 */
+export function staticFile(platform, file) {
+    return join(PACKAGE_ROOT, 'static', platform, file);
+}