specific-ai-cli 0.0.0-stage → 0.1.1

package/dist/core/capabilities.js

@@ -0,0 +1,163 @@
+import { describeOption, FILTER_VALUES, flagName, PAGING, STANDARD_VALUES } from './options.js';
+import { sortCommands } from './registry.js';
+import { VOCAB } from './vocab.js';
+/** 生成 docs/capabilities.md（web 端能力矩阵）。只由注册表决定，`npm run gen:capabilities` 写盘，测试检查是否最新。 */
+const SYMBOL = { full: '✓', partial: '◐', none: '○' };
+const SECTIONS = [
+    {
+        title: 'auth',
+        resources: ['auth'],
+        intro: (platforms) => `\`login\` 见上表。\`logout\` / \`list\` / \`use\` 由 core 实现，所有平台都有；服务端登出只有 ${platforms
+            .filter((p) => web(p).logout)
+            .map((p) => p.id)
+            .join('、')}。`,
+    },
+    { title: 'user', resources: ['user'] },
+    { title: 'item', resources: ['item'] },
+    {
+        title: 'product 与商品评价',
+        resources: ['product'],
+        outro: '商品评价用 `comment list <product>`（见下节）：传商品 URL 时自动识别，传纯 ID 时加 `--product`。\n\n' +
+            '闲鱼、淘宝、京东的商品本身就是 item：商品详情用 `item get`，商品评价用 `comment list <item>`。',
+    },
+    { title: 'comment', resources: ['comment'] },
+    { title: 'feed 与 keyword', resources: ['feed', 'keyword'] },
+    { title: 'notice 与 msg', resources: ['notice', 'msg'] },
+    { title: 'media、folder、series、history、topic、poi', resources: ['media', 'folder', 'series', 'history', 'topic', 'poi'] },
+    { title: 'live', resources: ['live'] },
+];
+/** 不在命令表里出现的命令：login 有单独的表，list / use / logout 由 core 实现。 */
+const OMITTED = new Set(['auth login', 'auth logout', 'auth list', 'auth use']);
+const FILTERS = Object.keys(FILTER_VALUES);
+function web(platform) {
+    const ep = platform.endpoints.web;
+    if (ep === 'planned')
+        throw new Error(`${platform.id} 的 web 端是 planned`);
+    return ep;
+}
+function row(cells) {
+    return `| ${cells.join(' | ')} |`;
+}
+function header(first, platforms) {
+    return [row([first, ...platforms.map((p) => p.id)]), '|' + '---|'.repeat(platforms.length + 1)];
+}
+function loginTable(platforms) {
+    const logins = platforms.map((p) => web(p).login);
+    const lines = [...header('', platforms)];
+    for (const method of ['qrcode', 'sms', 'password', 'cookie']) {
+        lines.push(row([method, ...logins.map((l) => (l.methods.includes(method) ? '✓' : ''))]));
+    }
+    lines.push(row(['默认', ...logins.map((l) => l.default)]));
+    if (logins.some((l) => l.scopes?.length))
+        lines.push(row(['子站点', ...logins.map((l) => (l.scopes ?? []).join('、'))]));
+    return lines;
+}
+function commandRows(platforms, resources) {
+    const rows = [];
+    for (const key of Object.keys(VOCAB)) {
+        const [resource, action] = key.split(' ');
+        if (!resources.includes(resource) || OMITTED.has(key))
+            continue;
+        const commands = platforms.map((p) => web(p).commands.get(key));
+        const cells = commands.map((c) => (c?.upstream ? SYMBOL[c.upstream] : '—'));
+        const notes = commands.map((c) => c?.note ?? null);
+        const prev = rows.at(-1);
+        // 同一 resource 下相邻、各平台状态和说明都相同的命令合并成一行，例如 user followers / following
+        if (prev && prev.keys[0].startsWith(resource + ' ') && prev.cells.join() === cells.join() && prev.notes.join() === notes.join()) {
+            prev.keys.push(key);
+            prev.label += ` / ${action}`;
+        }
+        else {
+            rows.push({ label: key, keys: [key], cells, notes });
+        }
+    }
+    return rows;
+}
+/** 表下的补充：◐ 的说明、筛选取值、平台私有选项。 */
+function footnotes(platforms, rows) {
+    const lines = [];
+    for (const r of rows) {
+        r.notes.forEach((note, i) => {
+            if (note)
+                lines.push(`- ${platforms[i].id} \`${r.label}\`：${note}`);
+        });
+    }
+    for (const r of rows) {
+        for (const key of r.keys) {
+            const commands = platforms.map((p) => [p, web(p).commands.get(key)]).filter(([, c]) => c);
+            // 词表给了、平台不支持的标准选项（用了报 UNSUPPORTED）
+            const without = commands.filter(([, c]) => c.unsupported.length);
+            if (without.length) {
+                lines.push(`- \`${key}\` 不支持的标准选项：${without.map(([p, c]) => `${p.id} ${c.unsupported.map((o) => `--${flagName(o)}`).join(' ')}`).join('；')}`);
+            }
+            // 有标准取值、平台只支持其中一部分的选项（例如 --visibility）
+            for (const option of Object.keys(VOCAB[key].options).filter((o) => STANDARD_VALUES[o] && o !== 'method')) {
+                const dflt = describeOption(VOCAB[key].options[option]).values;
+                const differ = commands.filter(([, c]) => option in c.options && describeOption(c.options[option]).values?.join() !== dflt?.join());
+                if (!differ.length)
+                    continue;
+                const values = differ.map(([p, c]) => `${p.id} ${describeOption(c.options[option]).values?.join(' / ')}`);
+                lines.push(`- \`${key} --${flagName(option)}\` 取值：默认 ${dflt?.join(' / ')}；${values.join('；')}`);
+            }
+            const base = new Set([...Object.keys(VOCAB[key].options), ...Object.keys(PAGING)]);
+            const extra = [...new Set(commands.flatMap(([, c]) => Object.keys(c.options)))].filter((o) => !base.has(o));
+            for (const option of extra) {
+                const has = commands.filter(([, c]) => option in c.options);
+                if (FILTERS.includes(option) || (STANDARD_VALUES[option] && option !== 'method')) {
+                    const values = has.map(([p, c]) => `${p.id} ${describeOption(c.options[option]).values?.join(' / ')}`);
+                    lines.push(`- \`${key} --${flagName(option)}\` 取值：${values.join('；')}`);
+                }
+                else {
+                    lines.push(`- \`${key} --${flagName(option)}\`：${has.map(([p]) => p.id).join('、')}`);
+                }
+            }
+        }
+    }
+    return lines;
+}
+function extensions(platforms) {
+    const lines = [row(['平台', '命令']), '|---|---|'];
+    for (const p of platforms) {
+        const ext = sortCommands(web(p).commands.values()).filter((c) => c.extension);
+        if (ext.length)
+            lines.push(row([p.id, ext.map((c) => `\`${c.key}\` ${SYMBOL[c.upstream]}`).join(' · ')]));
+    }
+    return lines;
+}
+export function renderCapabilities(platforms) {
+    const out = [
+        '# 能力矩阵',
+        '',
+        '各平台 web 端的能力。命令规范见 [AGENTS.md](../AGENTS.md) 第 4 节，上游代码位置见 [upstream-map.md](upstream-map.md)。',
+        '',
+        '- 本文件由注册表（`src/platforms/<p>/index.ts`）生成：`npm run gen:capabilities`。不要手改，测试会检查它是否最新。',
+        '- app / pc 端目前全部是 planned，不在本表列出。',
+        '',
+        '| 符号 | 含义 | 注册表 status | 执行结果 |',
+        '|---|---|---|---|',
+        '| ✓ | 上游已有 | implemented | 正常执行 |',
+        '| ◐ | 上游部分支持，限制写在注册表的 `note` 里 | implemented | 正常执行 |',
+        '| ○ | 平台有这个概念，上游没有，规划中 | planned | `NOT_IMPLEMENTED`，退出码 4 |',
+        '| — | 平台没有这个概念 | 不注册 | `UNSUPPORTED`，退出码 2 |',
+        '',
+        `列顺序：${platforms.map((p) => p.id).join(' · ')}。`,
+        '',
+        '## 登录方式',
+        '',
+        ...loginTable(platforms),
+    ];
+    for (const s of SECTIONS) {
+        const rows = commandRows(platforms, s.resources);
+        out.push('', `## ${s.title}`, '');
+        if (s.intro)
+            out.push(typeof s.intro === 'function' ? s.intro(platforms) : s.intro, '');
+        out.push(...header('命令', platforms), ...rows.map((r) => row([r.label, ...r.cells])));
+        const notes = footnotes(platforms, rows);
+        if (notes.length)
+            out.push('', ...notes);
+        if (s.outro)
+            out.push('', s.outro);
+    }
+    out.push('', '## 平台扩展', '', '命令定义见 AGENTS.md 4.7。', '', ...extensions(platforms));
+    return out.join('\n') + '\n';
+}

package/dist/core/config.js

@@ -0,0 +1,121 @@
+import { parse, stringify } from 'smol-toml';
+import { SpecificAIError } from './errors.js';
+import { readTextIfExists, writeFileAtomic } from './fsutil.js';
+import { configFile } from './paths.js';
+/** config.toml（AGENTS 5.5）：proxy、timeout、<platform>.proxy。 */
+export const DEFAULT_TIMEOUT = 30;
+const PROXY_SCHEMES = ['http:', 'https:', 'socks4:', 'socks5:', 'socks5h:'];
+const KEYS_HINT = '可用的配置项：proxy、timeout、<platform>.proxy';
+export function checkProxy(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new SpecificAIError('USAGE', `代理地址不合法：${value}`, { hint: '例如 http://127.0.0.1:7890 或 socks5://127.0.0.1:1080' });
+    }
+    if (!PROXY_SCHEMES.includes(url.protocol)) {
+        throw new SpecificAIError('USAGE', `不支持的代理协议：${url.protocol}`, { hint: '支持 http、https、socks4、socks5、socks5h' });
+    }
+    return value;
+}
+function checkTimeout(value) {
+    const n = typeof value === 'string' ? Number(value) : value;
+    if (typeof n !== 'number' || !Number.isFinite(n) || n <= 0) {
+        throw new SpecificAIError('USAGE', `timeout 必须是大于 0 的秒数：${String(value)}`);
+    }
+    return n;
+}
+/**
+ * 解析配置键，平台段用规范 id。`resolvePlatform` 把平台 id 或别名映射成规范 id。
+ */
+export function parseKey(key, resolvePlatform) {
+    if (key === 'proxy' || key === 'timeout')
+        return [key];
+    const m = /^([^.]+)\.proxy$/.exec(key);
+    const id = m && resolvePlatform(m[1]);
+    if (!id)
+        throw new SpecificAIError('USAGE', `未知的配置项：${key}`, { hint: KEYS_HINT });
+    return [id, 'proxy'];
+}
+export async function loadConfig() {
+    const file = configFile();
+    const text = await readTextIfExists(file);
+    if (text == null)
+        return {};
+    try {
+        return parse(text);
+    }
+    catch (err) {
+        throw new SpecificAIError('ERROR', `config.toml 格式错误：${err.message.split('\n')[0]}`, { hint: file });
+    }
+}
+async function saveConfig(config) {
+    await writeFileAtomic(configFile(), stringify(config) + '\n');
+}
+function lookup(config, path) {
+    let v = config;
+    for (const k of path)
+        v = v && typeof v === 'object' ? v[k] : undefined;
+    return v ?? null;
+}
+export async function getConfig(path) {
+    return lookup(await loadConfig(), path);
+}
+export async function setConfig(path, raw) {
+    const key = path.join('.');
+    const value = key === 'timeout' ? checkTimeout(raw) : checkProxy(raw);
+    const config = await loadConfig();
+    if (path.length === 1)
+        config[path[0]] = value;
+    else {
+        const table = config[path[0]];
+        config[path[0]] = { ...(table && typeof table === 'object' ? table : {}), [path[1]]: value };
+    }
+    await saveConfig(config);
+    return { key, value };
+}
+export async function unsetConfig(path) {
+    const config = await loadConfig();
+    if (path.length === 1)
+        delete config[path[0]];
+    else {
+        const table = config[path[0]];
+        if (table && typeof table === 'object') {
+            delete table[path[1]];
+            if (Object.keys(table).length === 0)
+                delete config[path[0]];
+        }
+    }
+    await saveConfig(config);
+    return { key: path.join('.'), value: null };
+}
+/** 所有已设置的项，键用点号展开，例如 `{ "proxy": "...", "xhs.proxy": "..." }`。 */
+export async function listConfig() {
+    const out = {};
+    const walk = (table, prefix) => {
+        for (const [k, v] of Object.entries(table)) {
+            if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date))
+                walk(v, `${prefix}${k}.`);
+            else
+                out[prefix + k] = v;
+        }
+    };
+    walk(await loadConfig(), '');
+    return out;
+}
+/** 一次调用的网络设置。代理优先级：--proxy > <platform>.proxy > proxy；不读 HTTP(S)_PROXY。 */
+export async function resolveNetwork(platform, cliProxy) {
+    const config = await loadConfig();
+    const fromFile = (path) => {
+        const v = lookup(config, path);
+        if (v == null)
+            return null;
+        if (typeof v !== 'string')
+            throw new SpecificAIError('ERROR', `config.toml 里的 ${path.join('.')} 必须是字符串`, { hint: configFile() });
+        return checkProxy(v);
+    };
+    const proxy = cliProxy != null ? checkProxy(cliProxy) : (fromFile([platform, 'proxy']) ?? fromFile(['proxy']));
+    const t = lookup(config, ['timeout']);
+    return { proxy, timeout: t == null ? DEFAULT_TIMEOUT : checkTimeout(t) };
+}

package/dist/core/cookies.js

@@ -0,0 +1,164 @@
+import { nowSeconds } from './rand.js';
+/**
+ * Cookie 罐：直接读写凭证文件里某个 scope 的 cookie 数组，所以请求中更新的 cookie
+ * 会随凭证一起由 core 落盘（AGENTS 5.3「自动刷新」）。
+ *
+ * domain 以 `.` 开头表示对子域名生效；不带点表示只对该主机生效（host-only）。
+ */
+export class CookieJar {
+    cookies;
+    constructor(cookies = []) {
+        this.cookies = cookies;
+    }
+    /** 对某个 URL 生效、未过期的 cookie，按存入顺序。 */
+    forUrl(url) {
+        const u = typeof url === 'string' ? new URL(url) : url;
+        const now = nowSeconds();
+        return this.cookies.filter((c) => domainMatch(u.hostname, c.domain) && pathMatch(u.pathname, c.path) && (c.expires == null || c.expires > now));
+    }
+    /** 按名字取值；有多个同名 cookie 时，指定 domain 可以消歧，否则取第一个。 */
+    get(name, domain) {
+        return this.find(name, domain)?.value;
+    }
+    has(name) {
+        return this.cookies.some((c) => c.name === name);
+    }
+    /** 写入或覆盖（同名、同 domain、同 path 视为同一个）。 */
+    set(name, value, domain, options = {}) {
+        const path = options.path ?? '/';
+        const existing = this.cookies.find((c) => c.name === name && c.domain === domain && c.path === path);
+        if (existing) {
+            existing.value = value;
+            if (options.expires !== undefined)
+                existing.expires = options.expires;
+        }
+        else {
+            this.cookies.push({ name, value, domain, path, expires: options.expires ?? null });
+        }
+        return this;
+    }
+    delete(name, domain) {
+        for (let i = this.cookies.length - 1; i >= 0; i--) {
+            const c = this.cookies[i];
+            if (c.name === name && (domain == null || c.domain === domain))
+                this.cookies.splice(i, 1);
+        }
+        return this;
+    }
+    /** 按名字的顺序表重排；表外的排在最后，保持相对顺序。 */
+    sort(order) {
+        const index = new Map(order.map((n, i) => [n, i]));
+        const ranked = this.cookies.map((c, i) => ({ c, i, r: index.get(c.name) ?? order.length }));
+        ranked.sort((a, b) => a.r - b.r || a.i - b.i);
+        this.cookies.splice(0, this.cookies.length, ...ranked.map((x) => x.c));
+        return this;
+    }
+    /** Cookie 请求头：对 url 生效的 cookie（不给 url 时为全部），按存入顺序拼成 `a=1; b=2`。 */
+    header(url) {
+        return (url ? this.forUrl(url) : this.cookies).map((c) => `${c.name}=${c.value}`).join('; ');
+    }
+    /** 名字 → 值；同名时取第一个。 */
+    toObject(url) {
+        const out = {};
+        for (const c of url ? this.forUrl(url) : this.cookies)
+            if (!(c.name in out))
+                out[c.name] = c.value;
+        return out;
+    }
+    /** 处理响应的 Set-Cookie。 */
+    applySetCookie(url, headers) {
+        const host = new URL(url).hostname;
+        for (const header of headers) {
+            const parsed = parseSetCookie(header, host);
+            // Domain 属性必须覆盖当前主机（RFC 6265 5.3），否则丢弃
+            if (!parsed || !domainMatch(host, parsed.domain))
+                continue;
+            const { name, value, domain, path, expires } = parsed;
+            if (expires != null && expires <= nowSeconds()) {
+                const i = this.cookies.findIndex((c) => c.name === name && c.domain === domain && c.path === path);
+                if (i >= 0)
+                    this.cookies.splice(i, 1);
+            }
+            else
+                this.set(name, value, domain, { path, expires });
+        }
+    }
+    find(name, domain) {
+        return this.cookies.find((c) => c.name === name && (domain == null || c.domain === domain));
+    }
+}
+function domainMatch(host, domain) {
+    if (!domain)
+        return true;
+    if (domain.startsWith('.')) {
+        const d = domain.slice(1);
+        return host === d || host.endsWith(domain);
+    }
+    return host === domain;
+}
+function pathMatch(path, cookiePath) {
+    if (!cookiePath || cookiePath === '/')
+        return true;
+    return path === cookiePath || path.startsWith(cookiePath.endsWith('/') ? cookiePath : cookiePath + '/');
+}
+/** 解析一条 Set-Cookie。domain 属性统一规范成带点的形式，没有 domain 属性时为 host-only。 */
+export function parseSetCookie(header, host) {
+    const [pair, ...attrs] = header.split(';');
+    const i = pair.indexOf('=');
+    if (i <= 0)
+        return null;
+    const cookie = { name: pair.slice(0, i).trim(), value: pair.slice(i + 1).trim(), domain: host, path: '/', expires: null };
+    let maxAge = null;
+    for (const attr of attrs) {
+        const j = attr.indexOf('=');
+        const key = (j < 0 ? attr : attr.slice(0, j)).trim().toLowerCase();
+        const val = j < 0 ? '' : attr.slice(j + 1).trim();
+        if (key === 'domain' && val)
+            cookie.domain = '.' + val.replace(/^\./, '').toLowerCase();
+        else if (key === 'path' && val.startsWith('/'))
+            cookie.path = val;
+        else if (key === 'max-age' && /^-?\d+$/.test(val))
+            maxAge = Number(val);
+        else if (key === 'expires') {
+            const t = Date.parse(val);
+            if (!Number.isNaN(t))
+                cookie.expires = Math.floor(t / 1000);
+        }
+    }
+    if (maxAge != null)
+        cookie.expires = nowSeconds() + maxAge;
+    return cookie;
+}
+/**
+ * 解析用户导入的 cookie 字符串（`a=1; b=2`），也接受浏览器导出的 JSON 数组
+ * （`[{name, value, domain, path, expirationDate}]`）。domain 缺省时取平台默认域。
+ */
+export function parseCookieInput(input, defaultDomain) {
+    const text = input.trim();
+    if (text.startsWith('[')) {
+        const list = JSON.parse(text);
+        return list.map((c) => ({
+            name: c.name,
+            value: c.value,
+            domain: c.domain ? (c.domain.startsWith('.') ? c.domain : '.' + c.domain.replace(/^www\./, '')) : defaultDomain,
+            path: c.path ?? '/',
+            expires: c.expirationDate ?? c.expires ?? null,
+        }));
+    }
+    const out = [];
+    for (const part of text.replace(/^cookie:\s*/i, '').split(';')) {
+        const i = part.indexOf('=');
+        if (i <= 0)
+            continue;
+        const name = part.slice(0, i).trim();
+        if (!name)
+            continue;
+        const existing = out.find((c) => c.name === name);
+        const value = part.slice(i + 1).trim();
+        if (existing)
+            existing.value = value;
+        else
+            out.push({ name, value, domain: defaultDomain, path: '/', expires: null });
+    }
+    return out;
+}

package/dist/core/errors.js

@@ -0,0 +1,37 @@
+/** 退出码（AGENTS 6.4）。 */
+export const EXIT_CODES = {
+    ERROR: 1,
+    USAGE: 2,
+    UNSUPPORTED: 2,
+    CONFIRM_REQUIRED: 2,
+    AUTH_REQUIRED: 3,
+    AUTH_EXPIRED: 3,
+    NOT_IMPLEMENTED: 4,
+    RISK_CONTROL: 5,
+    NETWORK: 6,
+    UPSTREAM: 7,
+};
+export class SpecificAIError extends Error {
+    code;
+    hint;
+    detail;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.name = 'SpecificAIError';
+        this.code = code;
+        this.hint = options.hint ?? null;
+        this.detail = options.detail ?? null;
+    }
+    get exitCode() {
+        return EXIT_CODES[this.code];
+    }
+    toJSON() {
+        return { code: this.code, message: this.message, hint: this.hint, detail: this.detail };
+    }
+}
+export function toSpecificAIError(err) {
+    if (err instanceof SpecificAIError)
+        return err;
+    const message = err instanceof Error ? err.message : String(err);
+    return new SpecificAIError('ERROR', message, { cause: err });
+}

package/dist/core/files.js

@@ -0,0 +1,89 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, readFile, rename, rm, stat } from 'node:fs/promises';
+import { basename, extname, join, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { SpecificAIError } from './errors.js';
+/** `item download` 与发布时的本地文件（AGENTS 4.9「下载」「发布」）。 */
+const EXT_BY_TYPE = {
+    'image/jpeg': 'jpg',
+    'image/png': 'png',
+    'image/webp': 'webp',
+    'image/gif': 'gif',
+    'image/avif': 'avif',
+    'image/heic': 'heic',
+    'video/mp4': 'mp4',
+    'video/quicktime': 'mov',
+    'video/webm': 'webm',
+    'audio/mp4': 'm4a',
+    'audio/mpeg': 'mp3',
+};
+const TYPE_BY_EXT = Object.fromEntries(Object.entries(EXT_BY_TYPE).map(([t, e]) => [e, t]));
+Object.assign(TYPE_BY_EXT, { jpeg: 'image/jpeg', m4s: 'video/mp4', flv: 'video/x-flv', mkv: 'video/x-matroska' });
+function extFromUrl(url) {
+    try {
+        const ext = extname(new URL(url).pathname).slice(1).toLowerCase();
+        return /^[a-z0-9]{2,5}$/.test(ext) ? ext : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function contentTypeOf(name) {
+    return TYPE_BY_EXT[extname(name).slice(1).toLowerCase()] ?? 'application/octet-stream';
+}
+/**
+ * 把一组媒体下载到 `--dir`，文件名 `<platform>_<id>_<序号>.<ext>`；已有文件默认跳过，`--overwrite` 时覆盖。
+ */
+export async function downloadMedia(ctx, http, itemId, media, options = {}) {
+    const dir = resolve(ctx.options.dir ?? '.');
+    const overwrite = Boolean(ctx.options.overwrite);
+    await mkdir(dir, { recursive: true });
+    const files = [];
+    for (const [i, m] of media.entries()) {
+        if (!m.url) {
+            ctx.log.warn(`第 ${i + 1} 个媒体没有可下载的地址，跳过`);
+            continue;
+        }
+        const ext = options.ext?.(m, i) ?? extFromUrl(m.url) ?? (m.type === 'image' ? 'jpg' : m.type === 'audio' ? 'm4a' : 'mp4');
+        const path = join(dir, `${ctx.platform.id}_${itemId}_${i + 1}.${ext}`);
+        const existing = await stat(path).catch(() => null);
+        if (existing && !overwrite) {
+            ctx.log.info(`已存在，跳过：${path}`);
+            files.push({ path, type: m.type, url: m.url, size: existing.size });
+            continue;
+        }
+        ctx.log.info(`下载 ${i + 1}/${media.length}：${basename(path)}`);
+        const res = await http.request({ url: m.url, headers: options.headers });
+        if (!res.ok)
+            throw new SpecificAIError('UPSTREAM', `下载失败：HTTP ${res.status}`, { detail: { status: res.status, url: m.url } });
+        const tmp = `${path}.part`;
+        try {
+            if (res.body)
+                await pipeline(Readable.fromWeb(res.body), createWriteStream(tmp));
+            else
+                await pipeline(Readable.from([Buffer.from(await res.arrayBuffer())]), createWriteStream(tmp));
+            await rename(tmp, path);
+        }
+        catch (err) {
+            await rm(tmp, { force: true });
+            throw err;
+        }
+        files.push({ path, type: m.type, url: m.url, size: (await stat(path)).size });
+    }
+    return files;
+}
+/** 发布时的 `--image` / `--video` / `--cover`：本地路径直接读，URL 先下载。 */
+export async function readMedia(http, input, headers) {
+    if (/^https?:\/\//i.test(input)) {
+        const res = await http.request({ url: input, headers, cookies: false });
+        if (!res.ok)
+            throw new SpecificAIError('USAGE', `下载失败：HTTP ${res.status} ${input}`);
+        const filename = basename(new URL(input).pathname) || 'file';
+        return { data: new Uint8Array(await res.arrayBuffer()), filename, contentType: res.headers.get('content-type')?.split(';')[0] ?? contentTypeOf(filename) };
+    }
+    const data = await readFile(input).catch(() => {
+        throw new SpecificAIError('USAGE', `读取文件失败：${input}`);
+    });
+    return { data: new Uint8Array(data), filename: basename(input), contentType: contentTypeOf(input) };
+}

package/dist/core/fsutil.js

@@ -0,0 +1,52 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+/** 目录 0700（Windows 依赖用户目录本身的 ACL）。 */
+export async function ensureDir(dir) {
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+}
+/** 原子写入：先写同目录的临时文件（0600），再 rename 覆盖。 */
+export async function writeFileAtomic(file, data) {
+    await ensureDir(dirname(file));
+    const tmp = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
+    await writeFile(tmp, data, { mode: 0o600 });
+    try {
+        // Windows 上目标文件被其他进程短暂占用时 rename 会失败，重试几次。
+        for (let i = 0;; i++) {
+            try {
+                await rename(tmp, file);
+                return;
+            }
+            catch (err) {
+                const code = err.code;
+                if (i >= 5 || (code !== 'EPERM' && code !== 'EBUSY' && code !== 'EACCES'))
+                    throw err;
+                await sleep(20 * (i + 1));
+            }
+        }
+    }
+    catch (err) {
+        await rm(tmp, { force: true });
+        throw err;
+    }
+}
+export async function readTextIfExists(file) {
+    try {
+        return await readFile(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/** 带本地时区偏移的 ISO 8601，例如 2026-09-27T12:00:00+08:00。 */
+export function isoNow(date = new Date()) {
+    const pad = (n) => String(Math.trunc(Math.abs(n))).padStart(2, '0');
+    const offset = -date.getTimezoneOffset();
+    const sign = offset >= 0 ? '+' : '-';
+    return (`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+        `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+        `${sign}${pad(offset / 60)}:${pad(offset % 60)}`);
+}

package/dist/core/hash.js

@@ -0,0 +1,4 @@
+import { createHash, createHmac } from 'node:crypto';
+export const md5Hex = (data) => createHash('md5').update(data).digest('hex');
+export const sha256Hex = (data) => createHash('sha256').update(data).digest('hex');
+export const hmacSha256Hex = (key, data) => createHmac('sha256', key).update(data).digest('hex');