specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/cli/help.js

@@ -0,0 +1,223 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describeOption, flagName } from '../core/options.js';
+import { PACKAGE_ROOT } from '../core/paths.js';
+import { ENDPOINTS, sortCommands } from '../core/registry.js';
+import { PLATFORMS } from '../platforms/index.js';
+/** 帮助（AGENTS 4.10）：内容由注册表生成，写到 stdout。 */
+const WIDE = /[\u1100-\u115f\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/;
+function width(s) {
+    let w = 0;
+    for (const ch of s)
+        w += WIDE.test(ch) ? 2 : 1;
+    return w;
+}
+/** 按显示宽度对齐的多列文本，最后一列不补空格。 */
+function table(rows, indent = '  ') {
+    const widths = [];
+    for (const row of rows)
+        row.forEach((cell, i) => (widths[i] = Math.max(widths[i] ?? 0, width(cell))));
+    return rows
+        .map((row) => {
+        const cells = row.map((cell, i) => (i === row.length - 1 ? cell : cell + ' '.repeat(widths[i] - width(cell))));
+        return (indent + cells.join('  ')).trimEnd();
+    })
+        .join('\n');
+}
+const GLOBAL_OPTIONS = [
+    ['-a, --account <name>', '使用哪个账号'],
+    ['-e, --endpoint <端>', 'web | app | pc，默认 web'],
+    ['-o, --output <格式>', 'json | jsonl，默认 json'],
+    ['    --raw', '用平台原始对象代替归一化对象'],
+    ['    --proxy <url>', '本次调用使用的代理'],
+    ['-v, --verbose', '在 stderr 输出调试日志（已脱敏）'],
+    ['-q, --quiet', '不输出提示和进度，只保留错误'],
+    ['-y, --yes', '跳过危险操作的确认'],
+    ['-h, --help', '帮助'],
+    ['    --version', '版本信息'],
+];
+export function rootHelp() {
+    const banner = readFileSync(join(PACKAGE_ROOT, 'assets', 'banner.txt'), 'utf8').trimEnd();
+    const platforms = PLATFORMS.map((p) => [p.id, p.name, p.aliases.length ? `别名 ${p.aliases.join('、')}` : '']);
+    return [
+        banner,
+        '',
+        '用法:',
+        '  specific-ai <platform> <resource> <action> [参数...] [选项...]',
+        '  specific-ai <全局命令>',
+        '',
+        '平台:',
+        table(platforms),
+        '',
+        '全局命令:',
+        table([
+            ['platforms [platform]', '能力矩阵：平台 × 端 × 命令的状态'],
+            ['doctor', '检查运行环境'],
+            ['auth list', '所有平台、所有端的账号'],
+            ['config get|set|unset|list', '读写配置（~/.specific-ai/config.toml）'],
+            ['version', '版本、Node 版本、系统与架构'],
+        ]),
+        '',
+        '全局选项:',
+        table(GLOBAL_OPTIONS),
+        '',
+        '示例:',
+        '  specific-ai xhs item get "https://www.xiaohongshu.com/explore/<id>?xsec_token=..."',
+        '  specific-ai bilibili item get BV1xx411c7mD',
+        '  specific-ai douyin comment list <item> --limit 100',
+        '  specific-ai xhs auth login',
+        '',
+        '平台的命令：specific-ai <platform> --help',
+    ].join('\n');
+}
+function endpointsLine(platform) {
+    return ENDPOINTS.map((e) => (platform.endpoints[e] === 'planned' ? `${e} ○ planned` : `${e} ✓`)).join(' · ');
+}
+function title(platform) {
+    const aliases = platform.aliases.length ? `   别名：${platform.aliases.join('、')}` : '';
+    return `${platform.name} (${platform.id})${aliases}`;
+}
+/** 请求的端还是 planned 时，列出 web 端的命令作参考。 */
+function listedEndpoint(platform, endpoint) {
+    const ep = platform.endpoints[endpoint];
+    if (ep !== 'planned')
+        return { ep, notice: null };
+    return {
+        ep: platform.endpoints.web,
+        notice: `${endpoint} 端尚未实现，所有命令都返回 NOT_IMPLEMENTED。下面是 web 端的命令。`,
+    };
+}
+export function platformHelp(platform, endpoint) {
+    const { ep, notice } = listedEndpoint(platform, endpoint);
+    const login = ep.login.methods.map((m) => (m === ep.login.default ? `${m}（默认）` : m)).join(' · ');
+    const scopes = ep.login.scopes?.length ? `；子站点：${ep.login.scopes.join('、')}` : '';
+    const groups = new Map();
+    for (const c of sortCommands(ep.commands.values())) {
+        const list = groups.get(c.resource) ?? groups.set(c.resource, []).get(c.resource);
+        list.push(c.status === 'planned' ? `${c.action}○` : c.action);
+    }
+    return [
+        title(platform),
+        `端:   ${endpointsLine(platform)}`,
+        `登录: ${login}${scopes}`,
+        '',
+        `用法: specific-ai ${platform.id} <resource> <action> [参数...] [选项...]`,
+        '',
+        ...(notice ? [notice, ''] : []),
+        '命令（带 ○ 的是规划中，执行时返回 NOT_IMPLEMENTED）:',
+        table([...groups].map(([r, actions]) => [r, actions.join(' ')])),
+        '',
+        `命令详情：specific-ai ${platform.id} <resource> --help`,
+    ].join('\n');
+}
+export function resourceHelp(platform, endpoint, resource) {
+    const { ep, notice } = listedEndpoint(platform, endpoint);
+    const commands = sortCommands([...ep.commands.values()].filter((c) => c.resource === resource));
+    const label = resource === 'item' ? `item（${platform.item}）` : resource;
+    return [
+        `${platform.name} (${platform.id}) · ${label}`,
+        '',
+        ...(notice ? [notice, ''] : []),
+        table(commands.map((c) => [c.action, c.summary, c.status === 'planned' ? '○ 规划中' : ''])),
+        '',
+        `用法: specific-ai ${platform.id} ${resource} <action> [参数...] [选项...]`,
+        `命令详情：specific-ai ${platform.id} ${resource} <action> --help`,
+    ].join('\n');
+}
+const UPSTREAM_TEXT = { full: '✓ 上游已有', partial: '◐ 上游部分支持', none: '○ 上游没有，规划中' };
+function optionUsage(key, command) {
+    const info = describeOption(command.options[key]);
+    const flag = `--${flagName(key)}`;
+    if (info.kind === 'boolean')
+        return flag;
+    if (info.values)
+        return `${flag} <${info.values.join('|')}>`;
+    return `${flag} <${info.kind === 'number' ? 'n' : '值'}>`;
+}
+export function commandHelp(platform, endpoint, command) {
+    const p = platform.id;
+    const e = endpoint === 'web' ? '' : ` -e ${endpoint}`;
+    const argUsage = command.args.map((a) => (a.optional ? `[${a.name}]` : `<${a.name}>`));
+    const optionKeys = Object.keys(command.options);
+    const requiredOptions = optionKeys.filter((k) => describeOption(command.options[k]).required);
+    const endpoints = ENDPOINTS.map((name) => {
+        const ep = platform.endpoints[name];
+        if (ep === 'planned')
+            return `${name} ○ planned`;
+        const c = ep.commands.get(command.key);
+        return !c ? `${name} —` : c.status === 'planned' ? `${name} ○ planned` : `${name} ✓`;
+    });
+    const confirm = command.confirm === true ? '危险操作，执行前需要确认；-y 跳过' : command.confirm ? '部分情况需要确认（见选项）；-y 跳过' : null;
+    const lines = [
+        `用法: specific-ai ${p} ${command.key}${argUsage.map((a) => ' ' + a).join('')}${optionKeys.length ? ' [选项...]' : ''}`,
+        '',
+        command.summary,
+        '',
+        `端:   ${endpoints.join(' · ')}`,
+        `登录: ${command.auth === 'required' ? '需要' : '可选'}`,
+        `上游: ${command.upstream ? UPSTREAM_TEXT[command.upstream] : 'core 实现'}`,
+        ...(command.note ? [`说明: ${command.note}`] : []),
+        ...(confirm ? [`确认: ${confirm}`] : []),
+        `输出: ${command.output}${command.paged ? '，分页' : ''}${command.stream ? '，持续输出 jsonl' : ''}`,
+    ];
+    if (command.args.length) {
+        lines.push('', '参数:');
+        lines.push(table(command.args.map((a) => [a.optional ? `[${a.name}]` : `<${a.name}>`, a.summary])));
+    }
+    lines.push('', '选项:');
+    if (optionKeys.length) {
+        lines.push(table(optionKeys.map((k) => {
+            const info = describeOption(command.options[k]);
+            const notes = [
+                info.required ? '必填' : null,
+                info.default !== undefined ? `默认 ${String(info.default)}` : null,
+                info.kind === 'array' ? '可重复' : null,
+            ].filter(Boolean);
+            return [optionUsage(k, command), `${info.description ?? ''}${notes.length ? `（${notes.join('，')}）` : ''}`];
+        })));
+    }
+    lines.push('  全局选项见 specific-ai --help');
+    const example = [`specific-ai ${p} ${command.key}`, ...command.args.filter((a) => !a.optional).map((a) => `<${a.name}>`)];
+    for (const k of requiredOptions)
+        example.push(optionUsage(k, command));
+    lines.push('', '示例:', `  ${example.join(' ')}${e}`);
+    return lines.join('\n');
+}
+export const GLOBAL_HELP = {
+    platforms: [
+        '用法: specific-ai platforms [platform]',
+        '',
+        '能力矩阵：每个平台的端、命令、登录要求、状态（implemented / planned）和上游支持程度。',
+        '带平台参数时只输出这个平台。',
+    ].join('\n'),
+    doctor: [
+        '用法: specific-ai doctor',
+        '',
+        '逐项检查运行环境：Node 版本、~/.specific-ai 权限、签名 vm、HTTP 库、canvas、onnx、京东模型包、OCR 模型包。',
+        '有检查项不通过时退出码为 1，data 里仍是完整的检查结果。',
+    ].join('\n'),
+    auth: [
+        '用法: specific-ai auth list',
+        '',
+        '列出所有平台、所有端的账号。',
+        '登录、切换、登出请在平台下操作：',
+        '  specific-ai <platform> auth login|status|logout|list|use',
+    ].join('\n'),
+    config: [
+        '用法:',
+        '  specific-ai config get <key>',
+        '  specific-ai config set <key> <value>',
+        '  specific-ai config unset <key>',
+        '  specific-ai config list',
+        '',
+        '配置项:',
+        table([
+            ['proxy', '全局代理，例如 http://127.0.0.1:7890、socks5://127.0.0.1:1080'],
+            ['timeout', '单次请求超时（秒），默认 30'],
+            ['<platform>.proxy', '平台代理，例如 xhs.proxy'],
+        ]),
+        '',
+        '代理的优先级：--proxy > <platform>.proxy > proxy。不读取 HTTP(S)_PROXY 环境变量。',
+    ].join('\n'),
+    version: ['用法: specific-ai version（或 specific-ai --version）', '', '输出 specific-ai 版本、Node 版本、系统与架构。'].join('\n'),
+};

package/dist/cli/hints.js

@@ -0,0 +1,60 @@
+/** 平台原生叫法 → 规范词（AGENTS 4.6）。原生叫法不做别名，只在 UNSUPPORTED 的 hint 里提示。 */
+const RESOURCE_WORDS = {
+    note: 'item',
+    aweme: 'item',
+    video: 'item',
+    photo: 'item',
+    work: 'item',
+    post: 'item',
+    status: 'item',
+    tweet: 'item',
+    goods: 'item',
+    sku: 'item',
+    board: 'folder',
+    collection: (p) => (p === 'tiktok' ? 'folder' : p === 'kuaishou' ? 'series' : 'folder 或 series'),
+    mix: 'series',
+    playlist: 'series',
+    reply: 'comment',
+    评价: 'comment',
+    dm: 'msg',
+    im: 'msg',
+    咚咚: 'msg',
+    location: 'poi',
+    playurl: 'item media',
+};
+const ACTION_WORDS = {
+    digg: 'like',
+    favorite: (p) => (p === 'x' ? 'like' : 'collect'),
+    favour: 'collect',
+    bookmark: 'collect',
+    想要: 'collect',
+    关注商品: 'collect',
+    retweet: 'repost',
+    watch: 'listen',
+    playurl: 'media',
+};
+function lookup(words, word, platform) {
+    // 只认自己的键：valueOf、constructor 这类原型上的名字不算
+    const key = word.toLowerCase();
+    const c = Object.hasOwn(words, key) ? words[key] : undefined;
+    return c == null ? null : typeof c === 'string' ? c : c(platform);
+}
+function canonicalAction(word, platform) {
+    // un- 形式：undigg → unlike、unretweet → unrepost
+    if (word.startsWith('un')) {
+        const base = lookup(ACTION_WORDS, word.slice(2), platform);
+        if (base)
+            return `un${base}`;
+    }
+    return lookup(ACTION_WORDS, word, platform);
+}
+/** 用了原生叫法时，给出改用规范词的建议；没用原生叫法时返回 null。 */
+export function nativeHint(platform, resource, action) {
+    const r = lookup(RESOURCE_WORDS, resource, platform);
+    const a = action == null ? null : canonicalAction(action, platform);
+    if (!r && !a)
+        return null;
+    // playurl 作 resource 时已经带上 action：playurl → item media
+    const words = r?.includes(' ') ? r : [r ?? resource, ...(action == null ? [] : [a ?? action])].join(' ');
+    return words.includes('或') ? `规范词是 ${words}` : `用规范词：specific-ai ${platform} ${words}`;
+}

package/dist/cli/main.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+// 代理只能显式配置（AGENTS 5.5）：在加载 wreq-js 之前关掉它对 HTTP(S)_PROXY 和系统代理的读取。
+process.env.NO_PROXY = process.env.no_proxy = '*,0.0.0.0/0,::/0';
+process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE')
+        process.exit(0);
+    throw err;
+});
+const { run } = await import('./dispatch.js');
+const { closeTransports } = await import('../core/http.js');
+const code = await run(process.argv.slice(2));
+await closeTransports();
+// 原生连接（长连接的 WebSocket 等）可能还挂着句柄：输出写完后直接退出
+const flush = (stream) => new Promise((resolve) => stream.write('', () => resolve()));
+await flush(process.stdout);
+await flush(process.stderr);
+process.exit(code);
+export {};

package/dist/cli/output.js

@@ -0,0 +1,66 @@
+import { RAW } from '../core/schemas.js';
+export const FORMATS = ['json', 'jsonl'];
+/**
+ * 信封输出（AGENTS 6.1）。json：stdout 恰好一个信封；jsonl：stdout 每行一个 data 条目，
+ * 结束时在 stderr 写一行摘要信封（data 为 null）。
+ */
+export class Output {
+    format = 'json';
+    raw = false;
+    meta = { platform: null, endpoint: null, resource: null, action: null, account: null };
+    /** jsonl / 流式命令：立即写一条。 */
+    item(value) {
+        process.stdout.write(JSON.stringify(this.unwrap(value) ?? null) + '\n');
+    }
+    /**
+     * 写结果。`streamed` 为 true 表示条目已经用 {@link item} 写过，这里只写摘要。
+     * doctor 这类命令失败时仍带 data，此时传入 error。
+     */
+    result(data, options = {}) {
+        const { page = null, streamed = false, error } = options;
+        if (this.format === 'jsonl') {
+            if (!streamed)
+                for (const v of Array.isArray(data) ? data : [data])
+                    this.item(v);
+            this.summary(error ?? null, page);
+        }
+        else {
+            this.envelope(process.stdout, { ...this.base(error ?? null), data: this.unwrap(data) ?? null, page });
+        }
+    }
+    fail(error) {
+        if (this.format === 'jsonl')
+            this.summary(error, null);
+        else
+            this.envelope(process.stdout, { ...this.base(error), data: null, page: null });
+    }
+    summary(error, page) {
+        this.envelope(process.stderr, { ...this.base(error), data: null, page });
+    }
+    base(error) {
+        return { ok: error == null, ...this.meta, error: error?.toJSON() ?? null };
+    }
+    envelope(stream, env) {
+        const ordered = {
+            ok: env.ok,
+            platform: env.platform,
+            endpoint: env.endpoint,
+            resource: env.resource,
+            action: env.action,
+            account: env.account,
+            data: env.data,
+            page: env.page,
+            error: env.error,
+        };
+        const pretty = stream === process.stdout && stream.isTTY;
+        stream.write(JSON.stringify(ordered, null, pretty ? 2 : undefined) + '\n');
+    }
+    /** `--raw` 时用平台原始对象代替归一化对象。 */
+    unwrap(value) {
+        if (!this.raw || value == null || typeof value !== 'object')
+            return value;
+        if (Array.isArray(value))
+            return value.map((v) => this.unwrap(v));
+        return RAW in value ? value[RAW] : value;
+    }
+}

package/dist/core/auth-handlers.js

@@ -0,0 +1,41 @@
+import { checkAccountName, deleteCredential, endpointFlag, listAccounts, readCredential, setCurrent, toAccount, } from './auth-store.js';
+import { SpecificAIError } from './errors.js';
+/** core 自动注册到每个平台的 `auth list` / `use` / `logout`。 */
+export async function list(ctx) {
+    return listAccounts(ctx.platform.id, ctx.endpoint);
+}
+export async function use(ctx) {
+    const p = ctx.platform.id;
+    const account = checkAccountName(ctx.args.account);
+    const credential = await readCredential(p, ctx.endpoint, account);
+    if (!credential) {
+        throw new SpecificAIError('AUTH_REQUIRED', `账号 ${account} 不存在`, {
+            hint: `specific-ai ${p} auth login -a ${account}${endpointFlag(ctx.endpoint)}`,
+        });
+    }
+    await setCurrent(p, ctx.endpoint, account);
+    return toAccount(credential, true);
+}
+export async function logout(ctx) {
+    const p = ctx.platform.id;
+    const hint = `specific-ai ${p} auth list${endpointFlag(ctx.endpoint)}`;
+    if (ctx.account == null)
+        throw new SpecificAIError('USAGE', '没有当前账号，请用 -a 指定要登出的账号', { hint });
+    const account = checkAccountName(ctx.account);
+    const found = (await listAccounts(p, ctx.endpoint)).find((a) => a.account === account);
+    if (!found)
+        throw new SpecificAIError('USAGE', `账号 ${account} 不存在`, { hint });
+    const ep = ctx.platform.endpoints[ctx.endpoint];
+    if (ep !== 'planned' && ep.logout && found.user) {
+        try {
+            await (await ep.logout())(ctx);
+        }
+        catch (err) {
+            ctx.log.warn(`服务端登出失败，只删除本地凭证：${err.message}`);
+        }
+    }
+    await deleteCredential(p, ctx.endpoint, account);
+    if (found.current)
+        await setCurrent(p, ctx.endpoint, null);
+    return { ...found, current: false };
+}

package/dist/core/auth-store.js

@@ -0,0 +1,119 @@
+import { readdir, rm } from 'node:fs/promises';
+import { SpecificAIError } from './errors.js';
+import { isoNow, readTextIfExists, writeFileAtomic } from './fsutil.js';
+import { authDir } from './paths.js';
+import { CredentialSchema } from './schemas.js';
+/** 凭证只由 core 读写（AGENTS 5）。目录：auth/<platform>/<endpoint>/<account>.json、guest.json、_current。 */
+export const GUEST = 'guest';
+export const ACCOUNT_RE = /^[a-z0-9][a-z0-9_-]{0,31}$/;
+export function checkAccountName(name, options = {}) {
+    if (!ACCOUNT_RE.test(name)) {
+        throw new SpecificAIError('USAGE', `账号名不合法：${name}`, {
+            hint: '账号名只能用小写字母、数字、_ 和 -，以字母或数字开头，最长 32 位',
+        });
+    }
+    if (name === GUEST && !options.allowGuest)
+        throw new SpecificAIError('USAGE', 'guest 是保留名，表示游客身份');
+    return name;
+}
+/** 给用户看的命令后缀：非 web 端时带上 -e。 */
+export function endpointFlag(endpoint) {
+    return endpoint === 'web' ? '' : ` -e ${endpoint}`;
+}
+function credentialFile(platform, endpoint, account) {
+    return authDir(platform, endpoint, `${account}.json`);
+}
+export async function readCredential(platform, endpoint, account) {
+    const file = credentialFile(platform, endpoint, account);
+    const text = await readTextIfExists(file);
+    if (text == null)
+        return null;
+    let parsed;
+    try {
+        parsed = CredentialSchema.safeParse(JSON.parse(text));
+    }
+    catch {
+        parsed = null;
+    }
+    if (!parsed?.success) {
+        throw new SpecificAIError('ERROR', `凭证文件已损坏：${file}`, {
+            hint: account === GUEST ? `删除该文件后重试` : `specific-ai ${platform} auth logout -a ${account}${endpointFlag(endpoint)}`,
+        });
+    }
+    return parsed.data;
+}
+export async function writeCredential(credential) {
+    const { platform, endpoint, account } = credential;
+    checkAccountName(account, { allowGuest: true });
+    credential.updated_at = isoNow();
+    await writeFileAtomic(credentialFile(platform, endpoint, account), JSON.stringify(credential, null, 2) + '\n');
+}
+export async function deleteCredential(platform, endpoint, account) {
+    await rm(credentialFile(platform, endpoint, account), { force: true });
+}
+export function newCredential(init) {
+    const now = isoNow();
+    return {
+        schema: 1,
+        platform: init.platform,
+        endpoint: init.endpoint,
+        account: init.account,
+        user: init.user ?? null,
+        method: init.method,
+        created_at: now,
+        updated_at: now,
+        scopes: { main: { cookies: [], tokens: {} } },
+        device: {},
+        extra: {},
+    };
+}
+/** 当前账号；`_current` 不存在、不合法或指向已删除的账号时为 null。 */
+export async function getCurrent(platform, endpoint) {
+    const name = (await readTextIfExists(authDir(platform, endpoint, '_current')))?.trim();
+    if (!name || name === GUEST || !ACCOUNT_RE.test(name))
+        return null;
+    const exists = await readTextIfExists(credentialFile(platform, endpoint, name));
+    return exists == null ? null : name;
+}
+export async function setCurrent(platform, endpoint, account) {
+    const file = authDir(platform, endpoint, '_current');
+    if (account == null)
+        await rm(file, { force: true });
+    else
+        await writeFileAtomic(file, account + '\n');
+}
+export function toAccount(credential, current) {
+    return {
+        platform: credential.platform,
+        endpoint: credential.endpoint,
+        account: credential.account,
+        current,
+        user: credential.user,
+        method: credential.method,
+        updated_at: credential.updated_at,
+    };
+}
+/** 某平台某端的账号，按名字排序。损坏的凭证文件也列出来，user / method 为 null。 */
+export async function listAccounts(platform, endpoint) {
+    let files;
+    try {
+        files = await readdir(authDir(platform, endpoint));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    const current = await getCurrent(platform, endpoint);
+    const accounts = [];
+    for (const file of files.sort()) {
+        const name = file.replace(/\.json$/, '');
+        if (name === file || name === GUEST || !ACCOUNT_RE.test(name))
+            continue;
+        const credential = await readCredential(platform, endpoint, name).catch(() => null);
+        accounts.push(credential
+            ? toAccount(credential, name === current)
+            : { platform, endpoint, account: name, current: name === current, user: null, method: null, updated_at: null });
+    }
+    return accounts;
+}