@tuuject/surowan-utils 0.0.0-stage → 0.0.1

package/dist/credentials.js

@@ -0,0 +1,172 @@
+import { Buffer } from 'node:buffer';
+import { randomBytes } from 'node:crypto';
+import { lstat, mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { basename, dirname, join } from 'node:path';
+import { isRecord, parseEndpoint } from "./client.js";
+import { CliError, usageError } from "./errors.js";
+/** A credentials file is tiny; anything larger is not one this tool wrote. */
+export const MAX_CREDENTIALS_BYTES = 16 * 1024;
+const MAX_API_KEY_LENGTH = 4096;
+/** Whitespace (including Unicode spaces) and control characters. */
+const FORBIDDEN_API_KEY_CHARACTERS = /[\p{White_Space}\p{Cc}]/u;
+const INVALID_CREDENTIALS = 'invalid_credentials';
+/**
+ * `~/.config/surowan-utils/credentials.json` on every platform, Windows
+ * included: one documented location beats an XDG/AppData guess that would hide
+ * the file from users who followed the guide.
+ */
+export function credentialsPath(homeDir = homedir()) {
+    return join(homeDir, '.config', 'surowan-utils', 'credentials.json');
+}
+/**
+ * A key is an opaque token: no `pwk_` prefix is required, and synthetic keys
+ * (including ones ending in a backslash) must round-trip unchanged. Only what
+ * would corrupt a header or a log line is refused.
+ */
+export function validateApiKey(value) {
+    if (value.length < 1 || value.length > MAX_API_KEY_LENGTH || FORBIDDEN_API_KEY_CHARACTERS.test(value)) {
+        throw usageError('invalid_api_key', `API key must be 1 to ${MAX_API_KEY_LENGTH} characters with no whitespace or control characters`);
+    }
+    return value;
+}
+/**
+ * Reads the stored credentials, or `undefined` when nothing is stored yet.
+ * Every other anomaly fails fast with a fixed `CliError`: a JSON parse error
+ * quotes the surrounding text, and that text is the key.
+ */
+export async function readCredentials(path) {
+    const info = await inspectCredentialsFile(path);
+    if (info === undefined) {
+        return undefined;
+    }
+    if (info.size > MAX_CREDENTIALS_BYTES) {
+        throw invalidCredentials(path, `credentials file must not exceed ${MAX_CREDENTIALS_BYTES} bytes`);
+    }
+    await assertCredentialsDirectory(dirname(path), path);
+    let text;
+    try {
+        text = await readFile(path, 'utf8');
+    }
+    catch {
+        throw invalidCredentials(path, 'credentials file could not be read');
+    }
+    return parseStoredCredentials(text, path);
+}
+/**
+ * Writes the complete pair over whatever was stored before. The bytes land in
+ * a freshly created 0600 file that is renamed into place, so a failed write
+ * leaves the old file byte-for-byte intact. An existing symlink or an
+ * over-permissive file or directory is refused rather than replaced. No lock
+ * is taken: two concurrent logins are last-writer-wins.
+ */
+export async function writeCredentials(path, credentials) {
+    const endpoint = parseEndpoint(credentials.endpoint).href;
+    const apiKey = validateApiKey(credentials.apiKey);
+    const text = `${JSON.stringify({ endpoint, apiKey })}\n`;
+    if (Buffer.byteLength(text) > MAX_CREDENTIALS_BYTES) {
+        throw usageError('credentials_too_large', `credentials must not exceed ${MAX_CREDENTIALS_BYTES} bytes`);
+    }
+    const directory = dirname(path);
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        await assertCredentialsDirectory(directory, path);
+        await inspectCredentialsFile(path);
+        const temporary = join(directory, `.${basename(path)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+        try {
+            const handle = await open(temporary, 'wx', 0o600);
+            try {
+                await handle.writeFile(text, 'utf8');
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await rename(temporary, path);
+        }
+        catch (error) {
+            await unlink(temporary).catch(() => undefined);
+            throw error;
+        }
+    }
+    catch (error) {
+        if (error instanceof CliError) {
+            throw error;
+        }
+        // The filesystem message is dropped: it can name the temporary file, and
+        // the caller only ever needs to know that the write did not happen.
+        throw new CliError('credentials_write_failed', `credentials file could not be written: ${path}`);
+    }
+}
+/**
+ * In-place inspection shared by both directions. `undefined` means nothing is
+ * stored; anything that is present must be a regular file that group and other
+ * cannot read or write (POSIX modes; on Windows the home ACL is inherited).
+ */
+async function inspectCredentialsFile(path) {
+    const info = await lstat(path).catch((error) => {
+        if (isErrno(error, 'ENOENT')) {
+            return undefined;
+        }
+        throw invalidCredentials(path, 'credentials file could not be inspected');
+    });
+    if (info === undefined) {
+        return undefined;
+    }
+    if (info.isSymbolicLink()) {
+        throw invalidCredentials(path, 'credentials file must not be a symbolic link');
+    }
+    if (!info.isFile()) {
+        throw invalidCredentials(path, 'credentials file must be a regular file');
+    }
+    if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) {
+        throw invalidCredentials(path, 'credentials file permissions must be 0600 or narrower');
+    }
+    return info;
+}
+/** The containing directory must be real (not a symlink) and not group/other accessible. */
+async function assertCredentialsDirectory(directory, path) {
+    const info = await lstat(directory).catch(() => undefined);
+    if (info === undefined || !info.isDirectory()) {
+        throw invalidCredentials(path, 'credentials directory must be a real directory');
+    }
+    if (process.platform !== 'win32' && (info.mode & 0o077) !== 0) {
+        throw invalidCredentials(path, 'credentials directory permissions must be 0700 or narrower');
+    }
+}
+function parseStoredCredentials(text, path) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw invalidCredentials(path, 'credentials file is not valid JSON');
+    }
+    if (!isRecord(parsed)) {
+        throw invalidCredentials(path, 'credentials file must contain exactly "endpoint" and "apiKey" strings');
+    }
+    const { endpoint: rawEndpoint, apiKey: rawApiKey } = parsed;
+    if (Object.keys(parsed).length !== 2 || typeof rawEndpoint !== 'string' || typeof rawApiKey !== 'string') {
+        throw invalidCredentials(path, 'credentials file must contain exactly "endpoint" and "apiKey" strings');
+    }
+    let endpoint;
+    try {
+        endpoint = parseEndpoint(rawEndpoint).href;
+    }
+    catch {
+        throw invalidCredentials(path, 'credentials file endpoint is invalid');
+    }
+    try {
+        validateApiKey(rawApiKey);
+    }
+    catch {
+        throw invalidCredentials(path, 'credentials file API key is invalid');
+    }
+    return { endpoint, apiKey: rawApiKey };
+}
+function invalidCredentials(path, reason) {
+    return new CliError(INVALID_CREDENTIALS, `${reason}: ${path}`);
+}
+function isErrno(error, code) {
+    return error instanceof Error && error.code === code;
+}

package/dist/errors.d.ts

@@ -0,0 +1,10 @@
+/** A failure with a stable machine-readable code and a process exit code. */
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    constructor(code: string, message: string, options?: {
+        readonly exitCode?: number;
+    });
+}
+/** Bad invocation input: exit code 2, like conventional CLI usage errors. */
+export declare function usageError(code: string, message: string): CliError;

package/dist/errors.js

@@ -0,0 +1,15 @@
+/** A failure with a stable machine-readable code and a process exit code. */
+export class CliError extends Error {
+    code;
+    exitCode;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = 'CliError';
+        this.code = code;
+        this.exitCode = options.exitCode ?? 1;
+    }
+}
+/** Bad invocation input: exit code 2, like conventional CLI usage errors. */
+export function usageError(code, message) {
+    return new CliError(code, message, { exitCode: 2 });
+}

package/dist/login.d.ts

@@ -0,0 +1,2 @@
+export declare function promptLoginField(label: string, secret: boolean, timeoutMs: number): Promise<string>;
+export declare function readLoginKey(timeoutMs: number): Promise<string>;

package/dist/login.js

@@ -0,0 +1,65 @@
+import { Buffer } from 'node:buffer';
+import { createInterface } from 'node:readline/promises';
+import { Writable } from 'node:stream';
+import { CliError, usageError } from "./errors.js";
+export async function promptLoginField(label, secret, timeoutMs) {
+    if (process.stdin.isTTY !== true || process.stderr.isTTY !== true) {
+        throw usageError('login_input_required', 'login requires a terminal or an explicit endpoint and API key; use --api-key-stdin for piped keys');
+    }
+    // readline still handles editing and terminal raw-mode restoration, but none
+    // of the secret input (including paste and backspace) reaches its output.
+    const output = secret ? new Writable({ write: (_chunk, _encoding, callback) => callback() }) : process.stderr;
+    const terminal = createInterface({ input: process.stdin, output, terminal: true, historySize: 0 });
+    const cancelled = new AbortController();
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const cancel = () => cancelled.abort();
+    terminal.on('SIGINT', cancel);
+    terminal.on('close', cancel);
+    process.stderr.write(label);
+    try {
+        return await terminal.question('', { signal: AbortSignal.any([cancelled.signal, timeout]) });
+    }
+    catch {
+        if (timeout.aborted) {
+            throw new CliError('timeout', `login input timed out after ${timeoutMs}ms; no credentials were saved`);
+        }
+        throw usageError('login_cancelled', 'login was cancelled; no credentials were saved');
+    }
+    finally {
+        terminal.removeListener('SIGINT', cancel);
+        terminal.removeListener('close', cancel);
+        terminal.close();
+        if (secret) {
+            process.stderr.write('\n');
+            output.destroy();
+        }
+    }
+}
+export async function readLoginKey(timeoutMs) {
+    if (process.stdin.isTTY === true) {
+        throw usageError('stdin_required', '--api-key-stdin requires a piped API key, not a terminal');
+    }
+    const timer = setTimeout(() => {
+        process.stdin.destroy(new CliError('timeout', `stdin timed out after ${timeoutMs}ms; no credentials were saved`));
+    }, timeoutMs);
+    const chunks = [];
+    let total = 0;
+    try {
+        for await (const chunk of process.stdin) {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buffer.byteLength;
+            // Permit the usual trailing CRLF without increasing the 4 KiB key cap.
+            if (total > 4_098) {
+                process.stdin.destroy();
+                throw usageError('invalid_api_key', 'API key input exceeds 4 KiB');
+            }
+            chunks.push(buffer);
+        }
+        return Buffer.concat(chunks)
+            .toString('utf8')
+            .replace(/\r?\n$/, '');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/media.d.ts

@@ -0,0 +1,9 @@
+import type { MediaCommand } from './args.ts';
+import type { AdminClient } from './client.ts';
+import type { CommandContext } from './commands.ts';
+/** Bounds for one `invocation media` run; requests are sequential and bounded by these. */
+export declare const MAX_MEDIA_ITEMS = 32;
+export declare const MAX_MEDIA_FILE_BYTES: number;
+export declare const MAX_MEDIA_TOTAL_BYTES: number;
+export declare const MANIFEST_FILE_NAME = "manifest.json";
+export declare function runMedia(command: MediaCommand, context: CommandContext, client: AdminClient): Promise<number>;

package/dist/media.js

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { isRecord } from "./client.js";
+import { CliError } from "./errors.js";
+/** Bounds for one `invocation media` run; requests are sequential and bounded by these. */
+export const MAX_MEDIA_ITEMS = 32;
+export const MAX_MEDIA_FILE_BYTES = 20 * 1024 * 1024;
+export const MAX_MEDIA_TOTAL_BYTES = 100 * 1024 * 1024;
+export const MANIFEST_FILE_NAME = 'manifest.json';
+/**
+ * Known MIME types and the extension used for the saved file. Content types
+ * outside this table (but syntactically valid) are stored as `.bin`; a value
+ * that is not a MIME type at all is refused.
+ */
+const MEDIA_EXTENSIONS = new Map([
+    ['image/jpeg', 'jpg'],
+    ['image/png', 'png'],
+    ['image/webp', 'webp'],
+    ['image/gif', 'gif'],
+    ['image/bmp', 'bmp'],
+    ['image/tiff', 'tiff'],
+    ['video/mp4', 'mp4'],
+    ['video/webm', 'webm'],
+    ['video/quicktime', 'mov'],
+    ['audio/ogg', 'ogg'],
+    ['audio/mpeg', 'mp3'],
+    ['audio/mp4', 'm4a'],
+    ['audio/wav', 'wav'],
+    ['audio/x-wav', 'wav'],
+    ['audio/flac', 'flac'],
+    ['application/pdf', 'pdf'],
+    ['application/zip', 'zip'],
+    ['application/json', 'json'],
+    ['application/octet-stream', 'bin'],
+    ['application/x-tgsticker', 'tgs'],
+    ['text/plain', 'txt'],
+]);
+const MEDIA_ID_PATTERN = /^\d{1,19}$/;
+const MIME_PATTERN = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
+export async function runMedia(command, context, client) {
+    const invocationId = command.id;
+    const items = parseMediaList(await client.get(`api/invocations/${invocationId}/media`), invocationId);
+    if (items.length > MAX_MEDIA_ITEMS) {
+        throw new CliError('media_too_many_items', `media list has ${items.length} items; at most ${MAX_MEDIA_ITEMS} can be downloaded`);
+    }
+    const declaredBytes = items.reduce((total, item) => total + (item.file_size ?? 0), 0);
+    if (declaredBytes > MAX_MEDIA_TOTAL_BYTES) {
+        throw new CliError('media_total_too_large', `media list declares ${declaredBytes} bytes; the total limit is ${MAX_MEDIA_TOTAL_BYTES}`);
+    }
+    const directory = await mkdtemp(join(tmpdir(), 'surowan-media-'));
+    const records = [];
+    let totalBytes = 0;
+    for (const item of items) {
+        const outcome = await downloadItem(item, {
+            invocationId,
+            variant: command.variant,
+            directory,
+            client,
+            budgetBytes: MAX_MEDIA_TOTAL_BYTES - totalBytes,
+        });
+        totalBytes += outcome.bytes;
+        records.push(outcome.record);
+    }
+    const manifest = { invocation_id: invocationId, variant: command.variant, directory, items: records };
+    const failures = records.filter((record) => record.status === 'failed');
+    const manifestJson = context.redact(JSON.stringify(manifest, null, 2));
+    if (records.length > 0 && failures.length === records.length) {
+        await rm(directory, { recursive: true, force: true });
+        printManifest(manifest, manifestJson, context);
+        throw mediaFailure(failures, records.length);
+    }
+    try {
+        await writeFile(join(directory, MANIFEST_FILE_NAME), `${manifestJson}\n`, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        await rm(directory, { recursive: true, force: true });
+        throw new CliError('media_manifest_write_failed', `could not write ${MANIFEST_FILE_NAME}: ${messageOf(error)}`);
+    }
+    printManifest(manifest, manifestJson, context);
+    if (failures.length > 0) {
+        throw mediaFailure(failures, records.length);
+    }
+    return 0;
+}
+async function downloadItem(item, options) {
+    if (!item.variants.includes(options.variant)) {
+        return {
+            record: failureRecord(item, 'variant_not_available', `variant ${options.variant} is not available for this item`),
+            bytes: 0,
+        };
+    }
+    if (item.file_size !== null && item.file_size > MAX_MEDIA_FILE_BYTES) {
+        return {
+            record: failureRecord(item, 'media_file_too_large', `item declares ${item.file_size} bytes; the per-file limit is ${MAX_MEDIA_FILE_BYTES}`),
+            bytes: 0,
+        };
+    }
+    if (item.file_size !== null && item.file_size > options.budgetBytes) {
+        return { record: budgetFailure(item, options.budgetBytes), bytes: 0 };
+    }
+    const cap = Math.min(MAX_MEDIA_FILE_BYTES, options.budgetBytes);
+    let download;
+    try {
+        download = await options.client.getMedia(`api/invocations/${options.invocationId}/media/${item.id}/content`, new URLSearchParams({ variant: options.variant }), cap);
+    }
+    catch (error) {
+        if (error instanceof CliError && error.code === 'media_file_too_large' && cap < MAX_MEDIA_FILE_BYTES) {
+            return { record: budgetFailure(item, options.budgetBytes), bytes: 0 };
+        }
+        return { record: failureRecord(item, errorCode(error), messageOf(error)), bytes: 0 };
+    }
+    if (download.variant !== options.variant) {
+        return {
+            record: failureRecord(item, 'invalid_response', `media content did not confirm variant ${options.variant}`),
+            bytes: 0,
+        };
+    }
+    const contentType = download.contentType;
+    if (contentType !== null && !MIME_PATTERN.test(contentType)) {
+        return { record: failureRecord(item, 'invalid_response', 'media content type is not a valid MIME type'), bytes: 0 };
+    }
+    const extension = contentType === null ? 'bin' : (MEDIA_EXTENSIONS.get(contentType) ?? 'bin');
+    const path = join(options.directory, `${item.id}.${extension}`);
+    try {
+        await writeFile(path, download.bytes, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        await rm(path, { force: true }).catch(() => undefined);
+        return { record: failureRecord(item, 'media_write_failed', messageOf(error)), bytes: 0 };
+    }
+    const bytes = download.bytes.byteLength;
+    return {
+        record: {
+            id: item.id,
+            message_id: item.message_id,
+            revision_id: item.revision_id,
+            kind: item.kind,
+            status: 'downloaded',
+            path,
+            mime_type: contentType,
+            bytes,
+            sha256: createHash('sha256').update(download.bytes).digest('hex'),
+            error: null,
+        },
+        bytes,
+    };
+}
+function failureRecord(item, code, message) {
+    return {
+        id: item.id,
+        message_id: item.message_id,
+        revision_id: item.revision_id,
+        kind: item.kind,
+        status: 'failed',
+        path: null,
+        mime_type: item.mime_type,
+        bytes: null,
+        sha256: null,
+        error: { code, message },
+    };
+}
+function budgetFailure(item, budgetBytes) {
+    return failureRecord(item, 'media_total_too_large', `this item does not fit in the remaining ${budgetBytes} bytes of the ${MAX_MEDIA_TOTAL_BYTES} byte total`);
+}
+function printManifest(manifest, manifestJson, context) {
+    context.io.stdout(context.json ? `${JSON.stringify(manifest)}\n` : `${manifestJson}\n`);
+}
+function mediaFailure(failures, total) {
+    const details = failures
+        .slice(0, 3)
+        .map((item) => `${item.id}: ${item.error?.code ?? 'failed'}${item.error?.message ? ` (${item.error.message})` : ''}`)
+        .join('; ');
+    const remaining = failures.length > 3 ? `; +${failures.length - 3} more` : '';
+    return new CliError('media_download_failed', `${failures.length} of ${total} media items failed: ${details}${remaining}`);
+}
+function errorCode(error) {
+    return error instanceof CliError ? error.code : 'internal_error';
+}
+function messageOf(error) {
+    if (error instanceof Error && error.message.length > 0) {
+        return error.message;
+    }
+    return 'unexpected failure';
+}
+function parseMediaList(raw, invocationId) {
+    if (!isRecord(raw) || raw.invocation_id !== invocationId || !Array.isArray(raw.items)) {
+        throw new CliError('invalid_response', 'media list response has an unexpected shape');
+    }
+    return raw.items.map((item) => parseMediaItem(item));
+}
+function parseMediaItem(raw) {
+    if (!isRecord(raw) ||
+        typeof raw.id !== 'string' ||
+        !MEDIA_ID_PATTERN.test(raw.id) ||
+        !isNonEmptyString(raw.message_id) ||
+        !isNonEmptyString(raw.revision_id) ||
+        !isNonEmptyString(raw.kind) ||
+        !(raw.mime_type === null || typeof raw.mime_type === 'string') ||
+        !(raw.file_size === null ||
+            (typeof raw.file_size === 'number' && Number.isSafeInteger(raw.file_size) && raw.file_size >= 0)) ||
+        !Array.isArray(raw.variants) ||
+        raw.variants.length === 0 ||
+        !raw.variants.every((variant) => variant === 'original' || variant === 'preview')) {
+        throw new CliError('invalid_response', 'media list item has an unexpected shape');
+    }
+    return {
+        id: raw.id,
+        message_id: raw.message_id,
+        revision_id: raw.revision_id,
+        kind: raw.kind,
+        mime_type: raw.mime_type,
+        file_size: raw.file_size,
+        variants: raw.variants,
+    };
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}

package/dist/run.d.ts

@@ -0,0 +1,14 @@
+import { type CliIo } from './commands.ts';
+export declare const USAGE = "surowan-utils - Plastic Wan Admin API \u5DE5\u5177\u5BA2\u6237\u7AEF\n\n\u7528\u6CD5:\n  surowan-utils login [--endpoint <url>] [--api-key-stdin] [--json]\n  surowan-utils doctor [--json]\n  surowan-utils models list [--json]\n  surowan-utils config show [--source active|file] [--json]\n  surowan-utils prompt get global [--source active|file] [--json]\n  surowan-utils prompt get group --chat <id> [--source active|file] [--json]\n  surowan-utils invocation list [--limit N] [--cursor ID] [--state STATE] [--chat ID] [--search <keyword>] [--at <time>] [--from <time>] [--to <time>] [--json]\n  surowan-utils invocation get <id> [--json]\n  surowan-utils invocation prompts <id> [--json]\n  surowan-utils invocation preflight <id> [--before-send <send-id>] [--provider <alias> --model <id>] [--thinking-level <level>] [--json]\n  surowan-utils invocation media <id> [--variant original|preview] [--json]\n  surowan-utils invocation replay <id> [--before-send <send-id> --confirm-paid] [--provider <alias> --model <id>] [--thinking-level <level>] [--global-prompt <file|->] [--group-prompt <file|->] [--json]\n\n\u5168\u5C40\u9009\u9879:\n  --endpoint <url>    Admin Panel \u57FA\u5730\u5740\uFF08\u8986\u76D6\u73AF\u5883\u53D8\u91CF\u4E0E\u767B\u5F55\u6587\u4EF6\uFF09\uFF1B\u660E\u6587 http \u4EC5\u5141\u8BB8 loopback\n  --api-key <key>     API key\uFF08\u8986\u76D6 SUROWAN_API_KEY \u4E0E\u767B\u5F55\u6587\u4EF6\uFF1B\u5EFA\u8BAE\u9690\u85CF\u8F93\u5165\u3001stdin \u6216\u5B89\u5168\u73AF\u5883\u6CE8\u5165\uFF09\n  --api-key-stdin     \u4EC5 login\uFF1A\u8BFB\u53D6\u6807\u51C6\u8F93\u5165\u81F3 EOF\uFF0C\u63A5\u53D7\u5355\u884C API key\uFF0C\u4E0D\u56DE\u663E\n  --source <active|file>  config show / prompt get\uFF1A\u8BFB\u53D6\u8FD0\u884C\u65F6\u751F\u6548\u914D\u7F6E\u6216\u914D\u7F6E\u6587\u4EF6\uFF08\u9ED8\u8BA4 active\uFF09\n  --variant <original|preview>  \u4EC5 invocation media\uFF1A\u4E0B\u8F7D\u539F\u59CB\u6587\u4EF6\u6216\u9884\u89C8\uFF08\u9ED8\u8BA4 original\uFF09\n  --provider <alias> --model <id>  \u4EC5 invocation preflight/replay\uFF1A\u4E34\u65F6\u9009\u7528\u5DF2\u542F\u7528\u6A21\u578B\uFF0C\u4E24\u9879\u5FC5\u987B\u6210\u5BF9\n  --thinking-level <level>  \u4EC5 invocation preflight/replay\uFF1A\u4E34\u65F6\u601D\u8003\u7EA7\u522B\uFF08off|minimal|low|medium|high|xhigh|max\uFF09\n  --global-prompt <file|->  \u4EC5 invocation replay\uFF1A\u66FF\u6362 global prompt\uFF1B- \u8868\u793A stdin\n  --group-prompt <file|->   \u4EC5 invocation replay\uFF1A\u66FF\u6362 group prompt\uFF08\u5141\u8BB8\u7A7A\uFF09\uFF1B- \u8868\u793A stdin\n  --search <keyword>  \u4EC5 invocation list\uFF1A\u6309\u5B57\u9762\u5173\u952E\u8BCD\u8FC7\u6EE4\u6D88\u606F\uFF081-100 \u5B57\u7B26\uFF0C\u4E0D\u89E3\u91CA\u901A\u914D\u7B26\uFF09\n  --at <time>         \u4EC5 invocation list\uFF1A\u7B5B\u9009\u8BE5\u65F6\u523B\u7684 Invocation\uFF0C\u4E0E --from/--to \u4E92\u65A5\n  --from <time> / --to <time>  \u4EC5 invocation list\uFF1A\u7B5B\u9009\u65F6\u95F4\u8303\u56F4\n  --before-send <send-id>  \u4EC5 invocation preflight/replay\uFF1A\u4ECE\u8BE5 telegram_sends \u5185\u90E8 id\uFF08\u5DF2\u6210\u529F\u53D1\u9001\uFF09\u4E4B\u524D\u5F00\u59CB\u56DE\u653E\n  --confirm-paid      \u4EC5 invocation replay\uFF1A\u5207\u7247\u91CD\u653E\uFF08--before-send\uFF09\u4F1A\u771F\u5B9E\u8C03\u7528\u6A21\u578B\u5E76\u8BA1\u8D39\uFF0C\u9700\u663E\u5F0F\u786E\u8BA4\uFF0C\u5426\u5219\u5728\u53D1\u8BF7\u6C42\u524D\u62D2\u7EDD\n  --timeout-ms <ms>   \u8BF7\u6C42/\u6BCF\u6B21\u8F93\u5165\u8D85\u65F6\uFF1B\u9ED8\u8BA4\u975E replay \u547D\u4EE4 30000\uFF0Creplay 300000\uFF0C\u4E0D\u81EA\u52A8\u91CD\u8BD5\n  --json              \u8F93\u51FA\u7A33\u5B9A JSON\n  -h, --help          \u663E\u793A\u672C\u5E2E\u52A9\n\n\u65F6\u95F4\u683C\u5F0F: YYYY-MM-DD[ |T]HH:mm[:ss[.1-3\u4F4D]][Z|\u00B1HH:mm]\uFF1B\u65E5\u671F\u5FC5\u987B\u6709\u6548\u3002\u4E0D\u5E26 Z/offset \u65F6\u7531\u670D\u52A1\u7AEF\u6309 --chat \u5BF9\u5E94\u7FA4\u6216\u5168\u5C40\u65F6\u533A\u89E3\u91CA\u3002\n\u767B\u5F55\u6587\u4EF6: ~/.config/surowan-utils/credentials.json\uFF08\u672A\u52A0\u5BC6\uFF0C\u5305\u542B API key\uFF09\u3002\nlogin \u53EA\u4FDD\u5B58\u51ED\u636E\uFF1Bdoctor \u7528\u53EA\u8BFB\u8BF7\u6C42\u9A8C\u8BC1\u8FDE\u63A5\u4E0E\u9274\u6743\uFF0C\u4E0D\u8C03\u7528\u6A21\u578B\u3002\nconfig show \u4E0E prompt get \u53EA\u8BFB\u53D6\u8131\u654F\u540E\u7684\u914D\u7F6E\u4E0E prompt\uFF0C\u4E0D\u4FEE\u6539\u670D\u52A1\u7AEF\u72B6\u6001\u3002\nmodels list \u53EA\u5217\u5F53\u524D\u751F\u6548\u3001\u5DF2\u6CE8\u518C\u4E14\u63A5\u53D7\u6587\u672C\u7684\u6A21\u578B\u53CA\u652F\u6301\u7684 thinking_levels\uFF0C\u4E0D\u63A2\u6D4B\u4E0A\u6E38\u6216\u8C03\u7528\u6A21\u578B\u3002\n\u4E34\u65F6\u6A21\u578B\u548C\u601D\u8003\u7EA7\u522B\u4E0D\u5199\u914D\u7F6E\uFF1B\u6307\u5B9A\u6A21\u578B\u4F46\u672A\u6307\u5B9A thinking-level \u65F6\u7528\u76EE\u6807\u6A21\u578B\u652F\u6301\u7684\u6700\u4F4E\u7EA7\u522B\u3002\u9884\u68C0\u4E0E POST \u4F7F\u7528\u540C\u4E00\u6A21\u578B\u9009\u62E9\uFF0C\u672A\u8986\u76D6\u65F6\u7EE7\u627F\u5F53\u524D\u7FA4\u914D\u7F6E\u3002\ninvocation media \u987A\u5E8F\u4E0B\u8F7D\u5230 mkdtemp \u65B0\u5EFA\u76EE\u5F55\uFF0Cstdout \u8F93\u51FA manifest\uFF0C\u6BCF\u4E2A\u6587\u4EF6\u4E0D\u8D85\u8FC7 20MiB\u3001\u603B\u8BA1\u4E0D\u8D85\u8FC7 100MiB \u4E14\u81F3\u591A 32 \u9879\u3002\ninvocation list \u9ED8\u8BA4\u4FDD\u6301\u65E7\u8F93\u51FA\uFF1B\u670D\u52A1\u7AEF\u8FD4\u56DE matched_messages \u65F6\u4EBA\u7C7B\u53EF\u8BFB\u8F93\u51FA\u4F1A\u8FFD\u52A0\u547D\u4E2D\u6458\u8981\u3002\ninvocation replay \u5148\u8BF7\u6C42 replay-preflight\uFF1B\u4E0D\u53EF\u91CD\u653E\u6216\u4E0D\u5141\u8BB8 prompt \u8986\u76D6\u65F6\u4E0D\u53D1\u9001 replay \u8BF7\u6C42\uFF1B--before-send \u53EA\u9009\u62E9\u56DE\u653E\u8FB9\u754C\uFF0C\u4E0D\u5C5E\u4E8E prompt \u8986\u76D6\u3002\u5207\u7247\u91CD\u653E\u5FC5\u987B\u663E\u5F0F\u7ED9\u51FA --confirm-paid\uFF1A\u7F3A\u5931\u65F6\u5728\u8BFB\u53D6 stdin \u4E0E\u53D1\u9001\u4EFB\u4F55\u8BF7\u6C42\u524D\u4EE5 confirm_paid_required\uFF08\u9000\u51FA\u7801 2\uFF09\u62D2\u7EDD\uFF1B\u672A\u5207\u7247\u7684 replay \u65E0\u9700\u8BE5 flag\u3002\n\u9000\u51FA\u7801: 0 \u6210\u529F\uFF1B1 \u8BF7\u6C42\u3001replay\u3001\u8D85\u65F6\u6216\u51ED\u636E\u6587\u4EF6\u5931\u8D25\uFF1B2 \u53C2\u6570/\u8F93\u5165/\u51ED\u636E\u4E0D\u5408\u6CD5\u3002\u9519\u8BEF\u4EE5 JSON \u5199\u5230 stderr\u3002";
+export interface RunOptions {
+    readonly env?: Record<string, string | undefined>;
+    readonly io?: CliIo;
+    readonly homeDir?: string;
+}
+export declare function runCli(argv: readonly string[], options?: RunOptions): Promise<number>;
+/**
+ * The API key must never appear in output, even if a server echoes it back.
+ * Also used for files the CLI persists (the media manifest), so both stdout and
+ * on-disk metadata share one redaction contract.
+ */
+export declare function redactSecrets(text: string, secrets: readonly (string | undefined)[]): string;