@remixmate/cli 0.9.13 → 0.9.15

package/dist/auth/ensure.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The single authorization entry point for every skill invocation.
+ *
+ * Before this module the CLI resolved PrivTokens in three unrelated places:
+ * `resolveHttpContext` (4 TS handlers, with credential store + auto device
+ * login), `registry_loader.py` (1 Python skill, with its own credential-file
+ * reader), and plain `os.environ["PRIV_TOKEN"]` (the other 7 Python skills,
+ * which therefore ignored `remixmate login` entirely). Auto browser auth only
+ * ever covered the first group.
+ *
+ * Now `runner.ts` calls `ensureAuth()` once, before dispatch, for every skill —
+ * so the credential store, the OS keychain and the device flow exist in exactly
+ * one place (Node), and Python scripts only ever read an injected `PRIV_TOKEN`.
+ */
+import { type CredentialSource } from './resolve.js';
+/**
+ * Per-skill authorization requirement, declared as `auth` in skill.json.
+ *
+ *  - `required`: no token → run the device flow; still no token → abort (exit 4).
+ *  - `optional`: inject a token when one is already available, otherwise carry
+ *                on silently. Never opens a browser — these skills degrade to a
+ *                reduced mode (e.g. web-record keeps the file locally instead of
+ *                uploading), and popping an auth window for that would be rude.
+ *  - `none`:     purely local, never touches ab-api (e.g. web-screenshot).
+ */
+export type AuthMode = 'required' | 'optional' | 'none';
+export declare const AUTH_MODE_VALUES: readonly ["required", "optional", "none"];
+export interface AuthPreflight {
+    /** Backend the invocation is bound to; injected so Python derives the same one. */
+    apiBaseUrl: string;
+    /** Absent only for `none`, or for `optional` with no credential available. */
+    token?: string;
+    source?: CredentialSource;
+    userLabel?: string;
+}
+/**
+ * Resolve (and if necessary acquire) a PrivToken for one skill invocation.
+ * Throws SkillError(exit 4) when `mode === 'required'` and no token could be
+ * obtained; the message is the shared NOT_AUTHENTICATED_HINT.
+ */
+export declare function ensureAuth(opts: {
+    mode: AuthMode;
+    apiBaseUrl?: string;
+    flagToken?: string;
+}): Promise<AuthPreflight>;
+/**
+ * Environment overrides handed to a spawned Python skill.
+ *
+ * `MM_API_BASE_URL` is always set so the child resolves the same backend the
+ * preflight authenticated against — otherwise a `--api-base-url` flag or a
+ * credential bound to a staging backend would silently disagree with the URL
+ * the Python side derives. `PRIV_TOKEN` is only set when non-empty, so an
+ * `optional` skill without a credential keeps inheriting whatever the host set.
+ */
+export declare function authChildEnv(pre: AuthPreflight): Record<string, string>;

package/dist/auth/ensure.js

@@ -0,0 +1,62 @@
+/**
+ * The single authorization entry point for every skill invocation.
+ *
+ * Before this module the CLI resolved PrivTokens in three unrelated places:
+ * `resolveHttpContext` (4 TS handlers, with credential store + auto device
+ * login), `registry_loader.py` (1 Python skill, with its own credential-file
+ * reader), and plain `os.environ["PRIV_TOKEN"]` (the other 7 Python skills,
+ * which therefore ignored `remixmate login` entirely). Auto browser auth only
+ * ever covered the first group.
+ *
+ * Now `runner.ts` calls `ensureAuth()` once, before dispatch, for every skill —
+ * so the credential store, the OS keychain and the device flow exist in exactly
+ * one place (Node), and Python scripts only ever read an injected `PRIV_TOKEN`.
+ */
+import { resolveApiBaseUrl } from '../http.js';
+import { EXIT, SkillError } from '../errors.js';
+import { resolvePrivToken, NOT_AUTHENTICATED_HINT } from './resolve.js';
+import { attemptAutoLogin } from './auto-login.js';
+export const AUTH_MODE_VALUES = ['required', 'optional', 'none'];
+/**
+ * Resolve (and if necessary acquire) a PrivToken for one skill invocation.
+ * Throws SkillError(exit 4) when `mode === 'required'` and no token could be
+ * obtained; the message is the shared NOT_AUTHENTICATED_HINT.
+ */
+export async function ensureAuth(opts) {
+    const apiBaseUrl = resolveApiBaseUrl(opts.apiBaseUrl);
+    if (opts.mode === 'none')
+        return { apiBaseUrl };
+    let resolved = await resolvePrivToken({ flag: opts.flagToken, apiBaseUrl });
+    // Browser authorization is only ever attempted for `required`. attemptAutoLogin
+    // self-gates on CI / headless / kill-switch, so the env-injected cloud path
+    // returns here untouched.
+    if (!resolved && opts.mode === 'required') {
+        resolved = await attemptAutoLogin(apiBaseUrl);
+    }
+    if (!resolved) {
+        if (opts.mode === 'optional')
+            return { apiBaseUrl };
+        throw new SkillError(NOT_AUTHENTICATED_HINT, EXIT.NOT_AUTHENTICATED);
+    }
+    return {
+        apiBaseUrl,
+        token: resolved.privToken,
+        source: resolved.source,
+        userLabel: resolved.userLabel,
+    };
+}
+/**
+ * Environment overrides handed to a spawned Python skill.
+ *
+ * `MM_API_BASE_URL` is always set so the child resolves the same backend the
+ * preflight authenticated against — otherwise a `--api-base-url` flag or a
+ * credential bound to a staging backend would silently disagree with the URL
+ * the Python side derives. `PRIV_TOKEN` is only set when non-empty, so an
+ * `optional` skill without a credential keeps inheriting whatever the host set.
+ */
+export function authChildEnv(pre) {
+    const env = { MM_API_BASE_URL: pre.apiBaseUrl };
+    if (pre.token)
+        env.PRIV_TOKEN = pre.token;
+    return env;
+}

package/dist/auth/environment.d.ts

@@ -23,3 +23,16 @@ export declare function isHeadless(): boolean;
  * AND the environment can plausibly open a browser for the user.
  */
 export declare function canAutoAuth(): boolean;
+/**
+ * Whether the CLI is being driven by an agent host (Claude Code / Codex /
+ * ab-agent) rather than typed by a human at a terminal.
+ *
+ * Used to decide (a) whether to emit the machine-readable AUTH_REQUIRED block
+ * alongside the human text, and (b) whether an interactive `login` may block
+ * for the device code's full lifetime — an agent's tool call is time-bounded,
+ * so it must get a bounded, resumable wait instead.
+ *
+ * Detection is deliberately loose: a piped stdout is the reliable signal, the
+ * env markers just make the intent explicit for hosts that allocate a pty.
+ */
+export declare function isAgentHost(): boolean;

package/dist/auth/environment.js

@@ -46,3 +46,24 @@ export function isHeadless() {
 export function canAutoAuth() {
     return !autoAuthDisabled() && !isHeadless();
 }
+/**
+ * Whether the CLI is being driven by an agent host (Claude Code / Codex /
+ * ab-agent) rather than typed by a human at a terminal.
+ *
+ * Used to decide (a) whether to emit the machine-readable AUTH_REQUIRED block
+ * alongside the human text, and (b) whether an interactive `login` may block
+ * for the device code's full lifetime — an agent's tool call is time-bounded,
+ * so it must get a bounded, resumable wait instead.
+ *
+ * Detection is deliberately loose: a piped stdout is the reliable signal, the
+ * env markers just make the intent explicit for hosts that allocate a pty.
+ */
+export function isAgentHost() {
+    const e = process.env;
+    if ((e.CLAUDECODE ?? '').trim() || (e.CLAUDE_CODE ?? '').trim() || (e.CODEX_SANDBOX ?? '').trim()) {
+        return true;
+    }
+    if ((e.AGENT_NAME ?? '').trim())
+        return true;
+    return !process.stdout.isTTY;
+}

package/dist/auth/pending-store.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pending device-authorization state, at ~/.config/remixmate/pending.json.
+ *
+ * Exists so authorization can outlive a single process. `login --start` requests
+ * a device code, persists it and returns immediately; `login --wait` picks it up
+ * and polls with a bounded window, as many times as needed. That split is what
+ * makes authorization workable from an agent host, whose tool calls are
+ * time-bounded and cannot sit on a 10-minute blocking poll.
+ *
+ * The device_code IS a short-lived bearer secret (it can be exchanged for the
+ * PrivToken until it expires or is used), so the file is written 0600 like the
+ * credential store, and is deleted as soon as it is redeemed or found expired.
+ */
+export declare const PENDING_FILE: string;
+export interface PendingAuth {
+    apiBaseUrl: string;
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    /** Poll interval in seconds, as instructed by the backend. */
+    interval: number;
+    /** Absolute epoch-ms deadline after which the device code is dead. */
+    expiresAt: number;
+}
+export declare function setPending(pending: PendingAuth): Promise<void>;
+/**
+ * Read the pending authorization for `apiBaseUrl`. Returns null when absent,
+ * unreadable, bound to a different backend, or already expired — callers then
+ * tell the user to run `login --start` again.
+ */
+export declare function getPending(apiBaseUrl: string): Promise<PendingAuth | null>;
+export declare function clearPending(): Promise<void>;

package/dist/auth/pending-store.js

@@ -0,0 +1,45 @@
+/**
+ * Pending device-authorization state, at ~/.config/remixmate/pending.json.
+ *
+ * Exists so authorization can outlive a single process. `login --start` requests
+ * a device code, persists it and returns immediately; `login --wait` picks it up
+ * and polls with a bounded window, as many times as needed. That split is what
+ * makes authorization workable from an agent host, whose tool calls are
+ * time-bounded and cannot sit on a 10-minute blocking poll.
+ *
+ * The device_code IS a short-lived bearer secret (it can be exchanged for the
+ * PrivToken until it expires or is used), so the file is written 0600 like the
+ * credential store, and is deleted as soon as it is redeemed or found expired.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+const PENDING_DIR = join(homedir(), '.config', 'remixmate');
+export const PENDING_FILE = join(PENDING_DIR, 'pending.json');
+export async function setPending(pending) {
+    await fs.mkdir(PENDING_DIR, { recursive: true, mode: 0o700 });
+    await fs.writeFile(PENDING_FILE, JSON.stringify(pending, null, 2), { mode: 0o600 });
+    await fs.chmod(PENDING_FILE, 0o600);
+}
+/**
+ * Read the pending authorization for `apiBaseUrl`. Returns null when absent,
+ * unreadable, bound to a different backend, or already expired — callers then
+ * tell the user to run `login --start` again.
+ */
+export async function getPending(apiBaseUrl) {
+    let parsed;
+    try {
+        parsed = JSON.parse(await fs.readFile(PENDING_FILE, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (!parsed?.deviceCode || parsed.apiBaseUrl !== apiBaseUrl)
+        return null;
+    if (!(parsed.expiresAt > Date.now()))
+        return null;
+    return parsed;
+}
+export async function clearPending() {
+    await fs.rm(PENDING_FILE, { force: true });
+}

package/dist/billing.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Billing capture — makes credit consumption visible to whoever ran the skill.
+ *
+ * Credits are deducted server-side and used to be invisible here: a run printed
+ * its image/video URL and nothing else, so the first time a user noticed the
+ * credit system at all was the `insufficient_credits` error after the balance
+ * had already run out. ab-api now attaches a `billing` object to the envelope of
+ * every response that charged something (see core.Success / credits_billing.go);
+ * this module accumulates those across all the calls a single skill run makes —
+ * a gen-image run polls, a gen-video run polls, and each may charge once — and
+ * renders one footer at the end.
+ *
+ * Two outputs, two audiences, both on stdout:
+ *   - a human-readable footer, which is what the agent relays to the user.
+ *   - one `__progress__` line (phase `billing`) — the existing machine protocol,
+ *     already parsed by ab-agent's executor and skipped by the line-scanning
+ *     parsers in render_video.py, so a nested pipeline caller can aggregate a
+ *     whole run's spend without a new stdout contract.
+ *
+ * Both go to stdout rather than stderr (where the auth footer lives) because
+ * ab-agent hands the LLM `result.stdout || result.stderr` (mcp-tools.ts) — a
+ * stderr-only footer would be invisible in the hosted agent, visible only when
+ * a local host like codex shows both streams. Adding stdout lines is safe:
+ * emitProgress already writes NDJSON there, so no consumer can be treating
+ * stdout as a single JSON document.
+ */
+export interface BillingItem {
+    credits: number;
+    bizType?: string;
+    detail?: string;
+}
+/** The `billing` object ab-api attaches to a charged response. */
+export interface Billing {
+    credits: number;
+    balance: number;
+    items?: BillingItem[];
+}
+/** Accumulate one response's billing object; no-ops on responses that charged nothing. */
+export declare function recordBilling(billing: Billing | undefined | null): void;
+/** Everything charged so far in this process, or null when nothing was. */
+export declare function billingSummary(): Billing | null;
+export declare function emitBillingFooter(): void;
+/** Test seam — resets the accumulator between runs in-process. */
+export declare function resetBilling(): void;

package/dist/billing.js

@@ -0,0 +1,76 @@
+/**
+ * Billing capture — makes credit consumption visible to whoever ran the skill.
+ *
+ * Credits are deducted server-side and used to be invisible here: a run printed
+ * its image/video URL and nothing else, so the first time a user noticed the
+ * credit system at all was the `insufficient_credits` error after the balance
+ * had already run out. ab-api now attaches a `billing` object to the envelope of
+ * every response that charged something (see core.Success / credits_billing.go);
+ * this module accumulates those across all the calls a single skill run makes —
+ * a gen-image run polls, a gen-video run polls, and each may charge once — and
+ * renders one footer at the end.
+ *
+ * Two outputs, two audiences, both on stdout:
+ *   - a human-readable footer, which is what the agent relays to the user.
+ *   - one `__progress__` line (phase `billing`) — the existing machine protocol,
+ *     already parsed by ab-agent's executor and skipped by the line-scanning
+ *     parsers in render_video.py, so a nested pipeline caller can aggregate a
+ *     whole run's spend without a new stdout contract.
+ *
+ * Both go to stdout rather than stderr (where the auth footer lives) because
+ * ab-agent hands the LLM `result.stdout || result.stderr` (mcp-tools.ts) — a
+ * stderr-only footer would be invisible in the hosted agent, visible only when
+ * a local host like codex shows both streams. Adding stdout lines is safe:
+ * emitProgress already writes NDJSON there, so no consumer can be treating
+ * stdout as a single JSON document.
+ */
+import { emitProgress } from './progress.js';
+let creditsCharged = 0;
+let latestBalance = null;
+const chargedItems = [];
+/** Accumulate one response's billing object; no-ops on responses that charged nothing. */
+export function recordBilling(billing) {
+    if (!billing || typeof billing.credits !== 'number' || billing.credits <= 0)
+        return;
+    creditsCharged += billing.credits;
+    if (typeof billing.balance === 'number')
+        latestBalance = billing.balance;
+    for (const item of billing.items ?? []) {
+        if (item && typeof item.credits === 'number' && item.credits > 0)
+            chargedItems.push(item);
+    }
+}
+/** Everything charged so far in this process, or null when nothing was. */
+export function billingSummary() {
+    if (creditsCharged <= 0)
+        return null;
+    return { credits: creditsCharged, balance: latestBalance ?? 0, items: [...chargedItems] };
+}
+/**
+ * Emit the footer for what this process charged. Safe to call on the error path
+ * too: a run can fail after a successful (already billed) generation step, and
+ * that spend still needs to be reported.
+ *
+ * Idempotent — only the first call prints, so a handler and the dispatcher can
+ * both reach for it without doubling the number the user sees.
+ */
+let emitted = false;
+export function emitBillingFooter() {
+    if (emitted)
+        return;
+    const summary = billingSummary();
+    if (!summary)
+        return;
+    emitted = true;
+    emitProgress({ phase: 'billing', credits: summary.credits, balance: summary.balance, items: summary.items });
+    const balance = summary.balance.toLocaleString('en-US');
+    const credits = summary.credits.toLocaleString('en-US');
+    process.stdout.write(`\n💳 Charged ${credits} credits · balance ${balance}\n`);
+}
+/** Test seam — resets the accumulator between runs in-process. */
+export function resetBilling() {
+    creditsCharged = 0;
+    latestBalance = null;
+    chargedItems.length = 0;
+    emitted = false;
+}

package/dist/cli.js

@@ -15,6 +15,10 @@ import { loadSkills, SKILLS_DIR } from './registry.js';
 import { parseArgv } from './argv.js';
 import { runSkill } from './runner.js';
 import { runAuthCommand } from './auth/commands.js';
+import { runExec } from './exec.js';
+import { authStatusLine, runDoctor } from './doctor.js';
+import { padDisplay } from './text.js';
+import { EXIT, SkillError } from './errors.js';
 /** Reserved auth verbs handled before skill dispatch. */
 const AUTH_VERBS = new Set(['login', 'logout', 'whoami']);
 /**
@@ -46,9 +50,12 @@ function printUsage() {
     const skills = loadSkills(resolveBaseDir());
     process.stdout.write('Usage:\n');
     process.stdout.write('  remixmate --list                      List all skills\n');
+    process.stdout.write('  remixmate doctor                      Diagnose environment, credentials, backend\n');
     process.stdout.write('  remixmate login                       Authorize this CLI via the browser\n');
+    process.stdout.write('  remixmate login --start | --wait      Non-blocking authorization (for agent hosts)\n');
     process.stdout.write('  remixmate logout                      Remove stored credentials\n');
     process.stdout.write('  remixmate whoami                      Show the current identity\n');
+    process.stdout.write('  remixmate exec -- <cmd> [args...]     Run a command with credentials injected\n');
     process.stdout.write('  remixmate <name> [--flag value ...]   Invoke a skill\n');
     process.stdout.write('  remixmate <name> --help               Show skill-specific help\n');
     process.stdout.write('\nAvailable skills:\n');
@@ -57,30 +64,83 @@ function printUsage() {
         process.stdout.write(`  ${s.name.padEnd(22)} ${s.entry.type.padEnd(8)} ${summary}\n`);
     }
 }
-function printList() {
-    for (const s of loadSkills(resolveBaseDir())) {
-        process.stdout.write(`${s.name}\t${s.toolName}\t${s.entry.type}\t${describeEntryTail(s)}\n`);
+/** Human-facing note on what a skill's auth mode means in practice. */
+const AUTH_NOTE = {
+    required: '需登录',
+    optional: '可选',
+    none: '免登录',
+};
+/**
+ * List skills.
+ *
+ * The default output is for a person: what each skill is and whether it needs a
+ * credential. The previous tab-separated form leaked internals (toolName, entry
+ * type, script path) that only tooling cares about — that shape now lives behind
+ * `--json`, which is a stabler contract for tooling anyway.
+ */
+function printList(json) {
+    const skills = loadSkills(resolveBaseDir());
+    if (json) {
+        process.stdout.write(JSON.stringify(skills.map((s) => ({
+            name: s.name,
+            toolName: s.toolName,
+            runtime: s.entry.type,
+            auth: s.auth,
+            entry: describeEntryTail(s),
+            description: s.description.split('\n')[0],
+        }))) + '\n');
+        return;
+    }
+    for (const s of skills) {
+        const summary = s.description.split('\n')[0].slice(0, 58);
+        process.stdout.write(`  ${s.name.padEnd(22)} ${padDisplay(AUTH_NOTE[s.auth], 8)}${summary}\n`);
+    }
+}
+/**
+ * Auth status footer for the listing commands, on stderr so stdout stays clean
+ * for anything piping the list. A fresh install used to say nothing at all about
+ * credentials until a skill failed.
+ */
+async function printAuthFooter() {
+    try {
+        process.stderr.write(`\n${await authStatusLine()}\n`);
+    }
+    catch {
+        // A diagnostic footer must never be the reason a listing command fails.
     }
 }
 async function main() {
     const argv = process.argv.slice(2);
     if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h') {
         printUsage();
-        process.exit(0);
+        await printAuthFooter();
+        process.exit(EXIT.OK);
     }
     if (argv[0] === '--list' || argv[0] === 'list') {
-        printList();
-        process.exit(0);
+        const json = argv.includes('--json') || argv.includes('--json-output');
+        printList(json);
+        if (!json)
+            await printAuthFooter();
+        process.exit(EXIT.OK);
+    }
+    if (argv[0] === 'doctor') {
+        const code = await runDoctor({ skipNetwork: argv.includes('--offline') });
+        process.exit(code);
     }
     // Auth verbs are handled before skill dispatch so they never collide with skill names.
     if (AUTH_VERBS.has(argv[0])) {
         const code = await runAuthCommand(argv[0], argv.slice(1));
         process.exit(code);
     }
+    if (argv[0] === 'exec') {
+        // Raw argv (not parsed) — everything after `--` belongs to the child command.
+        const code = await runExec(argv.slice(1));
+        process.exit(code);
+    }
     if (argv[0].startsWith('-')) {
         process.stderr.write(`❌ unknown option: ${argv[0]}\n`);
         printUsage();
-        process.exit(2);
+        process.exit(EXIT.USAGE);
     }
     const skillName = argv[0];
     const rest = argv.slice(1);
@@ -92,6 +152,13 @@ async function main() {
     process.exit(code);
 }
 main().catch((err) => {
+    // A SkillError is an expected, already-worded failure (most often "not
+    // authenticated", exit 4) — print the message and honor its exit code rather
+    // than dumping a stack trace the user can do nothing with.
+    if (err instanceof SkillError) {
+        process.stderr.write(err.message + '\n');
+        process.exit(err.exitCode);
+    }
     process.stderr.write(`❌ fatal: ${err?.stack ?? err?.message ?? String(err)}\n`);
-    process.exit(1);
+    process.exit(EXIT.ERROR);
 });

package/dist/doctor.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `remixmate doctor` — one command that answers "why isn't this working?".
+ *
+ * The failure modes this package actually produces in the field are: no
+ * credential, a credential bound to a different backend, a missing python3, a
+ * missing Playwright, and an unreachable backend. Each of those used to surface
+ * only as a downstream error from whichever skill happened to be run first, in
+ * that skill's own wording. Checking them up front, in one place, turns a
+ * scavenger hunt into a list.
+ *
+ * Also exports the one-line status shown under `--list` / `--help`, so a first
+ * run says "you are not logged in" instead of leaving the user to find out by
+ * invoking a skill.
+ */
+/**
+ * Short auth status suitable for a footer. Never performs network I/O — a
+ * listing command must stay instant and work offline.
+ */
+export declare function authStatusLine(): Promise<string>;
+export declare function runDoctor(opts?: {
+    skipNetwork?: boolean;
+}): Promise<number>;

package/dist/doctor.js

@@ -0,0 +1,142 @@
+/**
+ * `remixmate doctor` — one command that answers "why isn't this working?".
+ *
+ * The failure modes this package actually produces in the field are: no
+ * credential, a credential bound to a different backend, a missing python3, a
+ * missing Playwright, and an unreachable backend. Each of those used to surface
+ * only as a downstream error from whichever skill happened to be run first, in
+ * that skill's own wording. Checking them up front, in one place, turns a
+ * scavenger hunt into a list.
+ *
+ * Also exports the one-line status shown under `--list` / `--help`, so a first
+ * run says "you are not logged in" instead of leaving the user to find out by
+ * invoking a skill.
+ */
+import { spawnSync } from 'node:child_process';
+import { resolveApiBaseUrl } from './http.js';
+import { EXIT } from './errors.js';
+import { resolvePrivToken } from './auth/resolve.js';
+import { listCredentials } from './auth/credential-store.js';
+import { canAutoAuth, isHeadless } from './auth/environment.js';
+import { padDisplay } from './text.js';
+/**
+ * Short auth status suitable for a footer. Never performs network I/O — a
+ * listing command must stay instant and work offline.
+ */
+export async function authStatusLine() {
+    const apiBaseUrl = resolveApiBaseUrl();
+    const resolved = await resolvePrivToken({ apiBaseUrl });
+    if (resolved) {
+        const who = resolved.userLabel ? `${resolved.userLabel} ` : '';
+        return `✅ 已登录 ${who}@ ${apiBaseUrl}（来源：${resolved.source}）`;
+    }
+    const others = await listCredentials();
+    if (others.length > 0) {
+        return (`⚠️  当前后端 ${apiBaseUrl} 未登录；` +
+            `已有凭证的后端：${others.map((c) => c.apiBaseUrl).join(', ')}`);
+    }
+    return `⚠️  未登录（${apiBaseUrl}）→ 运行 remixmate login`;
+}
+const ICON = { ok: '✅', warn: '⚠️ ', fail: '❌' };
+/** Probe a command's presence and version line without failing on absence. */
+function probe(cmd, args) {
+    try {
+        const res = spawnSync(cmd, args, { encoding: 'utf8', timeout: 10_000 });
+        if (res.error || res.status !== 0)
+            return null;
+        return (res.stdout || res.stderr || '').trim().split('\n')[0] || null;
+    }
+    catch {
+        return null;
+    }
+}
+async function checkBackend(apiBaseUrl) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 8_000);
+    try {
+        // The device-code endpoint is public, so reachability can be probed without
+        // a credential — and without side effects, since we never redeem the code.
+        const resp = await fetch(`${apiBaseUrl}/auth/device/code`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ clientLabel: 'remixmate-doctor' }),
+            signal: controller.signal,
+        });
+        return {
+            name: '后端可达性',
+            status: resp.ok ? 'ok' : 'warn',
+            detail: `${apiBaseUrl} → HTTP ${resp.status}`,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error && err.name === 'AbortError' ? '超时' : err.message;
+        return { name: '后端可达性', status: 'fail', detail: `${apiBaseUrl} 不可达（${reason}）` };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export async function runDoctor(opts = {}) {
+    const apiBaseUrl = resolveApiBaseUrl();
+    const checks = [];
+    const major = Number(process.versions.node.split('.')[0]);
+    checks.push({
+        name: 'Node',
+        status: major >= 18 ? 'ok' : 'fail',
+        detail: `v${process.versions.node}${major >= 18 ? '' : '（需要 >= 18）'}`,
+    });
+    const py = probe('python3', ['--version']);
+    checks.push({
+        name: 'python3',
+        status: py ? 'ok' : 'fail',
+        detail: py ?? '未找到 —— 12 个 skill 中的 8 个需要 python3 >= 3.10',
+    });
+    const playwright = py ? probe('python3', ['-c', 'import playwright; print(playwright.__version__)']) : null;
+    checks.push({
+        name: 'Playwright',
+        status: playwright ? 'ok' : 'warn',
+        detail: playwright ?? '当前解释器下未安装 —— 仅 web-screenshot / web-record 需要，首次运行会自动装',
+    });
+    checks.push({ name: '后端地址', status: 'ok', detail: apiBaseUrl });
+    const resolved = await resolvePrivToken({ apiBaseUrl });
+    const stored = await listCredentials();
+    if (resolved) {
+        checks.push({
+            name: '凭证',
+            status: 'ok',
+            detail: `${resolved.userLabel ?? '(已认证)'}（来源：${resolved.source}）`,
+        });
+    }
+    else if (stored.length > 0) {
+        checks.push({
+            name: '凭证',
+            status: 'fail',
+            detail: `当前后端无凭证；已存储：${stored.map((c) => c.apiBaseUrl).join(', ')}。` +
+                ' 设置 MM_API_BASE_URL 指向其中之一，或重新 remixmate login',
+        });
+    }
+    else {
+        checks.push({ name: '凭证', status: 'fail', detail: '未登录 → 运行 remixmate login' });
+    }
+    checks.push({
+        name: '浏览器授权',
+        status: canAutoAuth() ? 'ok' : 'warn',
+        detail: canAutoAuth()
+            ? '可用（缺凭证时会自动打开授权页）'
+            : `不可用（${isHeadless() ? 'CI / 无桌面会话' : '已被 REMIXMATE_NO_BROWSER_AUTH 关闭'}）→ 请用 PRIV_TOKEN`,
+    });
+    if (!opts.skipNetwork)
+        checks.push(await checkBackend(apiBaseUrl));
+    for (const c of checks) {
+        process.stdout.write(`${ICON[c.status]} ${padDisplay(c.name, 14)}${c.detail}\n`);
+    }
+    const failed = checks.filter((c) => c.status === 'fail');
+    if (failed.length === 0) {
+        process.stdout.write('\n一切正常。\n');
+        return EXIT.OK;
+    }
+    process.stdout.write(`\n${failed.length} 项需要处理：${failed.map((c) => c.name).join('、')}\n`);
+    // A missing credential is the single most common cause and has a dedicated
+    // exit code, so a host can act on it without parsing the report.
+    return failed.some((c) => c.name === '凭证') ? EXIT.NOT_AUTHENTICATED : EXIT.ERROR;
+}