@remixmate/cli 0.9.13 → 0.9.15

package/README.md

@@ -52,7 +52,13 @@ remixmate logout    # remove stored credentials from this machine
 `login` uses the OAuth 2.0 Device Authorization Grant (RFC 8628): the CLI shows a
 device code, you approve it in a browser that is already signed in to the web app, and
 the CLI receives and stores your credential in the OS keychain (or a `0600` file at
-`~/.config/remixmate/credentials.json`). It only runs in an interactive terminal.
+`~/.config/remixmate/credentials.json`).
+
+No TTY is required — the device flow reads no keyboard input, so an agent host
+(Claude Code / Codex) can run it and relay the authorization link into the chat.
+The CLI prints a link with the device code pre-filled, so approving is one click.
+It is refused only where a browser could never be reached: CI, a headless Linux
+session, or `REMIXMATE_NO_BROWSER_AUTH=1`; use `PRIV_TOKEN` there instead.
 
 For CI and agent-embedded hosts (ab-agent / Claude Code), keep using the `PRIV_TOKEN`
 environment variable. Credential resolution precedence is:
@@ -63,6 +69,53 @@ environment variable. Credential resolution precedence is:
 
 When `PRIV_TOKEN` is set, `login` is skipped and the device flow is never auto-triggered.
 
+The credential is resolved once, on the Node side (`src/auth/ensure.ts`), and injected
+into spawned Python skills through their environment — skill scripts never read the
+credential store or the keychain themselves. To give any other command the same
+credential, use `exec`:
+
+```bash
+remixmate exec -- python3 scripts/test-template-pipeline.py
+```
+
+Each skill declares its requirement as `auth` in `skill.json`: `required` (authorize
+when no token is present), `optional` (use a token if there is one, otherwise carry on
+in a degraded mode — `web-record` keeps the file locally), or `none` (purely local, e.g.
+`web-screenshot`).
+
+Exit codes on failure: `4` = authorization needed, `5` = backend unreachable,
+`2` = usage error.
+
+### Non-blocking authorization (agent hosts)
+
+A blocking `login` waits for the device code's full lifetime, which outlives an
+agent's time-bounded tool call. Split it instead:
+
+```bash
+remixmate login --start --json    # returns immediately with the approval link
+remixmate login --wait --timeout 60 --json   # bounded poll; call again while pending
+```
+
+`--start` persists the device code to a `0600` `~/.config/remixmate/pending.json`;
+`--wait` redeems it and clears the file. While the user has not yet approved,
+`--wait` reports `{"status":"pending"}` with exit code 4 and leaves the pending
+state in place, so it is safe to call repeatedly.
+
+### Diagnosing
+
+```bash
+remixmate doctor            # node / python3 / Playwright / credential / backend
+remixmate doctor --offline  # skip the reachability probe
+```
+
+`doctor` exits `4` when the only problem is a missing credential.
+
+### Listing skills
+
+`remixmate --list` prints a human-readable table (name + whether it needs a login
++ summary) and appends the current auth status on stderr, so piping stdout is
+unaffected. For tooling, use `remixmate --list --json`.
+
 ### Automatic browser authorization (local hosts)
 
 When a skill that needs a credential is invoked from a **local third-party host**

package/README.zh-CN.md

@@ -48,7 +48,9 @@ remixmate whoami    # 查看当前身份（绝不打印 token）
 remixmate logout    # 从本机移除已存储的凭证
 ```
 
-`login` 使用 OAuth 2.0 设备授权流程（RFC 8628）：CLI 显示设备码，你在已登录 Web 的浏览器中确认，CLI 随后取回凭证并保存到系统钥匙串（或 `~/.config/remixmate/credentials.json`，权限 `0600`）。仅在交互式终端中可用。
+`login` 使用 OAuth 2.0 设备授权流程（RFC 8628）：CLI 给出一条已预填设备码的授权链接，你在已登录 Web 的浏览器中点一下确认，CLI 随后取回凭证并保存到系统钥匙串（或 `~/.config/remixmate/credentials.json`，权限 `0600`）。
+
+不需要交互式终端 —— 设备流不读键盘输入，agent 宿主（Claude Code / Codex）可以直接执行并把链接转述到聊天里。只有在浏览器根本不可达时才会拒绝：CI、无桌面会话的 Linux、或设置了 `REMIXMATE_NO_BROWSER_AUTH=1`；这些场景请改用 `PRIV_TOKEN`。
 
 CI 与 agent 宿主（ab-agent / Claude Code）继续使用 `PRIV_TOKEN` 环境变量。凭证解析优先级：
 
@@ -58,6 +60,40 @@ CI 与 agent 宿主（ab-agent / Claude Code）继续使用 `PRIV_TOKEN` 环境
 
 设置了 `PRIV_TOKEN` 时，`login` 会跳过，且任何命令都不会自动触发设备登录流程。
 
+凭证只在 CLI 的 Node 侧解析一次（`src/auth/ensure.ts`），再通过环境变量注入给被调起的 Python 技能 —— 技能脚本自己不读凭证库、不读钥匙串。需要让其它命令（如维护脚本）拿到同一份凭证时，用 `exec`：
+
+```bash
+remixmate exec -- python3 scripts/test-template-pipeline.py
+```
+
+每个技能在 `skill.json` 里用 `auth` 声明鉴权需求：`required`（缺 token 就发起授权）、`optional`（有就用，没有则降级继续，如 `web-record` 只保留本地文件）、`none`（纯本地，如 `web-screenshot`）。
+
+失败时的退出码：`4` = 需要授权，`5` = 后端不可达，`2` = 用法错误。
+
+### 非阻塞授权（agent 宿主）
+
+阻塞式 `login` 会一直等到设备码过期（10 分钟），超过 agent 单次工具调用的时长。改用两段式：
+
+```bash
+remixmate login --start --json               # 立刻返回授权链接，不等待
+remixmate login --wait --timeout 60 --json   # 有界轮询；还没授权就再调一次
+```
+
+`--start` 把设备码写入 `0600` 的 `~/.config/remixmate/pending.json`；`--wait` 兑换后清除它。用户尚未确认时 `--wait` 返回 `{"status":"pending"}` 与退出码 4，并保留 pending 状态，可以反复调用。
+
+### 排障
+
+```bash
+remixmate doctor            # 检查 node / python3 / Playwright / 凭证 / 后端
+remixmate doctor --offline  # 跳过联网探测
+```
+
+只有凭证一项有问题时，`doctor` 退出码为 `4`。
+
+### 列出技能
+
+`remixmate --list` 默认输出人类可读表格（技能名 + 是否需登录 + 摘要），末尾附一行当前登录状态（写到 stderr，不干扰管道）。给工具消费请用 `remixmate --list --json`。
+
 > 安全提示：若你此前曾把 `PRIV_TOKEN` 粘贴到聊天框或写进 shell 历史，切换到 `remixmate login` 后建议轮换该 token。
 
 ## 环境

package/dist/auth/auto-login.js

@@ -15,7 +15,16 @@ import { resolvePrivToken } from './resolve.js';
 import { canAutoAuth } from './environment.js';
 import { acquireLock, waitForCredential } from './auth-lock.js';
 import { runDeviceFlow } from './device-flow-runner.js';
-const DEFAULT_WAIT_MS = 25_000;
+/**
+ * How long a skill call waits for the user to approve in the browser.
+ *
+ * 90s, not 25s: when an agent host relays the link into a chat, the clock
+ * includes the user reading the message, switching to a browser and clicking —
+ * 25s reliably expired before a human could react. The ceiling is set by the
+ * host's own tool-call timeout (Claude Code's Bash tool defaults to 120s), so
+ * this must stay comfortably under that or the wait gets truncated anyway.
+ */
+const DEFAULT_WAIT_MS = 90_000;
 /** Extra slack on top of the wait window before a held lock is considered stale. */
 const STALE_SLACK_MS = 10_000;
 /** Resolve the short-wait window from env, falling back to the default. */

package/dist/auth/commands.js

@@ -6,50 +6,198 @@
  */
 import { parseArgv } from '../argv.js';
 import { resolveApiBaseUrl } from '../http.js';
-import { getCredential, removeCredential } from './credential-store.js';
+import { EXIT } from '../errors.js';
+import { getCredential, listCredentials, removeCredential } from './credential-store.js';
 import { resolvePrivToken } from './resolve.js';
-import { runDeviceFlow } from './device-flow-runner.js';
+import { persistApproval, runDeviceFlow, writeAuthPrompt } from './device-flow-runner.js';
+import { openBrowser, pollForToken, requestDeviceCode, DeviceFlowError } from './device-flow.js';
+import { clearPending, getPending, setPending } from './pending-store.js';
+import { canAutoAuth, isAgentHost } from './environment.js';
+/**
+ * Bounded wait used when an agent host runs `login` on the user's behalf. The
+ * device code lives ~10 minutes, but an agent's tool call does not — blocking
+ * that long guarantees the call is killed with nothing persisted. Stop early
+ * and tell the caller it can simply re-run.
+ */
+const AGENT_LOGIN_WAIT_MS = 90_000;
+/**
+ * Explain, when the active backend has no credential, which backends DO have
+ * one. Returns '' when there is nothing useful to add.
+ *
+ * Credentials are keyed by API base URL, so being "logged in" to
+ * http://localhost:2999/api tells you nothing about production — but the bare
+ * message ("not logged in") reads as if `login` had never been run.
+ */
+async function describeOtherBackends(activeApiBaseUrl) {
+    const others = (await listCredentials()).filter((c) => c.apiBaseUrl !== activeApiBaseUrl);
+    if (others.length === 0)
+        return '';
+    const lines = others.map((c) => `     - ${c.apiBaseUrl}${c.userLabel ? `（${c.userLabel}）` : ''}`);
+    return (`ℹ️  当前后端：${activeApiBaseUrl}（无凭证）\n` +
+        `   已存储凭证的后端：\n${lines.join('\n')}\n` +
+        `   要使用其中之一，设置 MM_API_BASE_URL=<该地址>，或加 --api-base-url <该地址>。\n`);
+}
 async function login(apiBaseUrl) {
     // Env token short-circuits the device flow (CI / agent-embedded hosts).
     if ((process.env.PRIV_TOKEN ?? '').trim()) {
         process.stdout.write('ℹ️  PRIV_TOKEN 环境变量已设置，CLI 将直接使用它，无需登录。\n');
-        return 0;
+        return EXIT.OK;
     }
-    // Device flow requires an interactive terminal.
-    if (!process.stdin.isTTY || !process.stdout.isTTY) {
-        process.stderr.write('❌ remixmate login 需要交互式终端；在 CI/无终端环境请改用 PRIV_TOKEN 环境变量。\n');
-        return 1;
+    // The device flow reads no keyboard input, so a TTY is not required — an
+    // agent host can run it and relay the link into chat. What IS required is a
+    // way to reach the user: canAutoAuth() rejects CI / headless, where a browser
+    // could never be opened and blocking would just hang the job.
+    if (!canAutoAuth()) {
+        process.stderr.write('❌ 当前环境无法完成浏览器授权（CI / 无桌面会话 / 已通过 REMIXMATE_NO_BROWSER_AUTH 关闭）。\n' +
+            '   请改用 PRIV_TOKEN 环境变量。\n');
+        return EXIT.NOT_AUTHENTICATED;
     }
     // Already authenticated for this backend?
     const existing = await getCredential(apiBaseUrl);
     if (existing) {
         process.stdout.write(`✅ 已登录（${existing.userLabel ?? 'unknown'}）。如需切换账号请先运行 remixmate logout。\n`);
-        return 0;
+        return EXIT.OK;
     }
-    // Interactive login uses the device code's full lifetime (no short-wait cap)
-    // and routes progress to stdout. Shared orchestration handles persistence.
+    // A human at a terminal can wait out the device code's full lifetime; an
+    // agent tool call cannot (see AGENT_LOGIN_WAIT_MS). Progress goes to stdout.
     const outcome = await runDeviceFlow(apiBaseUrl, {
         write: (msg) => process.stdout.write(msg),
+        maxWaitMs: isAgentHost() ? AGENT_LOGIN_WAIT_MS : undefined,
     });
     switch (outcome.status) {
         case 'approved':
             process.stdout.write(`\n✅ 登录成功：${outcome.userLabel ?? ''}\n`);
             process.stdout.write('🔒 安全提示：若你此前曾把 PrivToken 粘贴到聊天框或写进 shell 历史，建议在控制台轮换该 token。\n');
-            return 0;
+            return EXIT.OK;
         case 'denied':
             process.stderr.write('❌ 授权被拒绝。\n');
-            return 1;
+            return EXIT.NOT_AUTHENTICATED;
         case 'error':
             process.stderr.write(`❌ 登录失败：${outcome.message}\n`);
-            return 1;
+            return EXIT.ERROR;
         case 'timeout':
+            // The wait window closed, not the device code. Authorization may still be
+            // pending in the browser — re-running picks up the approval immediately.
+            process.stderr.write('⏳ 已打开授权页但未在等待窗口内完成。在浏览器点击确认后，重跑 remixmate login（或直接重跑原命令）即可。\n');
+            return EXIT.NOT_AUTHENTICATED;
         case 'expired':
         default:
             process.stderr.write('❌ 设备码已过期或无效，请重新运行 remixmate login。\n');
-            return 1;
+            return EXIT.NOT_AUTHENTICATED;
     }
 }
+/** Default bound for one `login --wait` call, overridable with --timeout <seconds>. */
+const DEFAULT_WAIT_SECONDS = 60;
+/**
+ * `login --start` — request a device code, persist it, print the link, return.
+ *
+ * Deliberately does NOT poll: the caller (an agent, or a script) gets the link
+ * immediately and can surface it while the user takes as long as they need.
+ * Approval is collected later by `login --wait`.
+ */
+async function loginStart(apiBaseUrl, jsonOutput) {
+    const clientLabel = `remixmate-cli (${process.platform} ${process.arch})`;
+    let code;
+    try {
+        code = await requestDeviceCode(apiBaseUrl, clientLabel);
+    }
+    catch (err) {
+        const msg = err instanceof DeviceFlowError ? err.message : err.message;
+        process.stderr.write(`❌ 无法获取设备码：${msg}\n`);
+        return EXIT.BACKEND_UNREACHABLE;
+    }
+    await setPending({
+        apiBaseUrl,
+        deviceCode: code.deviceCode,
+        userCode: code.userCode,
+        verificationUri: code.verificationUri,
+        verificationUriComplete: code.verificationUriComplete,
+        interval: code.interval,
+        expiresAt: Date.now() + code.expiresIn * 1000,
+    });
+    if (jsonOutput) {
+        process.stdout.write(JSON.stringify({
+            status: 'pending',
+            apiBaseUrl,
+            verificationUri: code.verificationUri,
+            verificationUriComplete: code.verificationUriComplete ?? code.verificationUri,
+            userCode: code.userCode,
+            expiresIn: code.expiresIn,
+            // The device_code itself is intentionally omitted — `login --wait` reads
+            // it from the pending file, so it never has to travel through a log or
+            // an agent's context.
+        }) + '\n');
+    }
+    else {
+        writeAuthPrompt((m) => process.stdout.write(m), apiBaseUrl, code);
+        openBrowser(code.verificationUriComplete ?? code.verificationUri);
+        process.stdout.write('完成授权后运行 remixmate login --wait 收取凭证。\n');
+    }
+    return EXIT.OK;
+}
+/**
+ * `login --wait [--timeout N]` — poll a previously started authorization for a
+ * bounded window. Safe to call repeatedly until it reports approved or expired.
+ */
+async function loginWait(apiBaseUrl, timeoutSeconds, jsonOutput) {
+    const emit = (payload, human, code) => {
+        if (jsonOutput)
+            process.stdout.write(JSON.stringify(payload) + '\n');
+        else
+            process.stdout.write(human);
+        return code;
+    };
+    const pending = await getPending(apiBaseUrl);
+    if (!pending) {
+        if (jsonOutput)
+            process.stdout.write(JSON.stringify({ status: 'no_pending', apiBaseUrl }) + '\n');
+        else
+            process.stderr.write(`❌ 没有进行中的授权（或已过期 / 属于别的后端）。请先运行 remixmate login --start。\n`);
+        return EXIT.NOT_AUTHENTICATED;
+    }
+    // Rebuild the shape pollForToken expects; expiresIn is the REMAINING lifetime
+    // so a resumed wait can never poll past the device code's real expiry.
+    const remainingSec = Math.max(1, Math.ceil((pending.expiresAt - Date.now()) / 1000));
+    let result;
+    try {
+        result = await pollForToken(apiBaseUrl, {
+            deviceCode: pending.deviceCode,
+            userCode: pending.userCode,
+            verificationUri: pending.verificationUri,
+            verificationUriComplete: pending.verificationUriComplete,
+            interval: pending.interval,
+            expiresIn: remainingSec,
+        }, { maxWaitMs: timeoutSeconds * 1000 });
+    }
+    catch (err) {
+        const msg = err instanceof DeviceFlowError ? err.message : err.message;
+        if (jsonOutput)
+            process.stdout.write(JSON.stringify({ status: 'error', message: msg }) + '\n');
+        else
+            process.stderr.write(`❌ 轮询失败：${msg}\n`);
+        return EXIT.BACKEND_UNREACHABLE;
+    }
+    if (result.status === 'approved' && result.privToken) {
+        await persistApproval(apiBaseUrl, result.privToken, result.userLabel, (m) => process.stdout.write(m));
+        await clearPending();
+        return emit({ status: 'approved', userLabel: result.userLabel, apiBaseUrl }, `✅ 登录成功：${result.userLabel ?? ''}\n`, EXIT.OK);
+    }
+    if (result.status === 'access_denied') {
+        await clearPending();
+        return emit({ status: 'denied' }, '❌ 授权被拒绝。\n', EXIT.NOT_AUTHENTICATED);
+    }
+    if (result.timedOut) {
+        // The wait window closed, not the device code — the pending state stays put
+        // so the caller can simply poll again.
+        return emit({ status: 'pending', apiBaseUrl, userCode: pending.userCode }, '⏳ 尚未完成授权。在浏览器确认后再次运行 remixmate login --wait。\n', EXIT.NOT_AUTHENTICATED);
+    }
+    await clearPending();
+    return emit({ status: 'expired' }, '❌ 设备码已过期，请重新运行 remixmate login --start。\n', EXIT.NOT_AUTHENTICATED);
+}
 async function logout(apiBaseUrl) {
+    // Drop any half-finished authorization too, so a later `--wait` can't redeem
+    // a device code the user just logged out of.
+    await clearPending();
     const res = await removeCredential(apiBaseUrl);
     const localNote = 'ℹ️  logout 仅清除本地凭证，不会在服务端吊销 PrivToken；如需服务端失效请轮换 token。\n';
     if (!res.removedFile && !res.removedKeychain && !res.fileError && !res.keychainError) {
@@ -96,20 +244,23 @@ async function whoami(apiBaseUrl, flagToken) {
     const resolved = await resolvePrivToken({ flag: flagToken, apiBaseUrl });
     if (!resolved) {
         process.stderr.write('❌ 未登录。运行 remixmate login，或设置 PRIV_TOKEN 环境变量。\n');
-        return 1;
+        const hint = await describeOtherBackends(apiBaseUrl);
+        if (hint)
+            process.stderr.write(hint);
+        return EXIT.NOT_AUTHENTICATED;
     }
     const verdict = await verifyToken(apiBaseUrl, resolved.privToken);
     if (verdict === 'unreachable') {
         process.stderr.write('❌ 无法验证身份：后端不可达或超时（本地凭证未改动）。\n');
-        return 1;
+        return EXIT.BACKEND_UNREACHABLE;
     }
     if (verdict === 'invalid') {
         process.stderr.write(`❌ 凭证无效或已被吊销。来源：${resolved.source}\n`);
-        return 1;
+        return EXIT.NOT_AUTHENTICATED;
     }
     const label = resolved.userLabel ?? '(已认证)';
-    process.stdout.write(`已认证：${label}\n来源：${resolved.source}\n`);
-    return 0;
+    process.stdout.write(`已认证：${label}\n来源：${resolved.source}\n后端：${apiBaseUrl}\n`);
+    return EXIT.OK;
 }
 /** Dispatch an auth verb. Returns a process exit code. */
 export async function runAuthCommand(verb, rest) {
@@ -117,14 +268,23 @@ export async function runAuthCommand(verb, rest) {
     const apiBaseUrl = resolveApiBaseUrl(args.api_base_url);
     const flagToken = args.token;
     switch (verb) {
-        case 'login':
+        case 'login': {
+            const jsonOutput = args.json_output === true || args.json === true;
+            if (args.start === true)
+                return loginStart(apiBaseUrl, jsonOutput);
+            if (args.wait === true || typeof args.wait === 'string') {
+                const raw = Number(args.timeout);
+                const timeout = Number.isFinite(raw) && raw > 0 ? raw : DEFAULT_WAIT_SECONDS;
+                return loginWait(apiBaseUrl, timeout, jsonOutput);
+            }
             return login(apiBaseUrl);
+        }
         case 'logout':
             return logout(apiBaseUrl);
         case 'whoami':
             return whoami(apiBaseUrl, flagToken);
         default:
             process.stderr.write(`❌ unknown auth command: ${verb}\n`);
-            return 2;
+            return EXIT.USAGE;
     }
 }

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

@@ -40,5 +40,21 @@ export declare function setCredential(apiBaseUrl: string, cred: StoredCredential
 }>;
 /** Read a credential for `apiBaseUrl`, or null when none is stored. */
 export declare function getCredential(apiBaseUrl: string): Promise<StoredCredential | null>;
+/** Non-secret summary of one stored entry, for diagnostics (`whoami`, `doctor`). */
+export interface CredentialSummary {
+    apiBaseUrl: string;
+    userLabel?: string;
+    createdAt: number;
+    secret: 'file' | 'keychain';
+}
+/**
+ * List which backends have a stored credential, WITHOUT reading any secret.
+ *
+ * Credentials are keyed by API base URL, so "logged in" is per-backend. Without
+ * this, a credential stored for a local dev backend while the CLI defaults to
+ * production produced a bare "not logged in" — technically true, actively
+ * misleading, and the exact confusion that motivated this work.
+ */
+export declare function listCredentials(): Promise<CredentialSummary[]>;
 /** Remove a credential from both stores; reports per-store outcome. */
 export declare function removeCredential(apiBaseUrl: string): Promise<RemoveResult>;

package/dist/auth/credential-store.js

@@ -99,6 +99,23 @@ export async function getCredential(apiBaseUrl) {
         return null;
     return { privToken, userLabel: entry.userLabel, createdAt: entry.createdAt };
 }
+/**
+ * List which backends have a stored credential, WITHOUT reading any secret.
+ *
+ * Credentials are keyed by API base URL, so "logged in" is per-backend. Without
+ * this, a credential stored for a local dev backend while the CLI defaults to
+ * production produced a bare "not logged in" — technically true, actively
+ * misleading, and the exact confusion that motivated this work.
+ */
+export async function listCredentials() {
+    const store = await readFileStore();
+    return Object.entries(store.credentials).map(([apiBaseUrl, entry]) => ({
+        apiBaseUrl,
+        userLabel: entry.userLabel,
+        createdAt: entry.createdAt,
+        secret: entry.secret,
+    }));
+}
 /** Remove a credential from both stores; reports per-store outcome. */
 export async function removeCredential(apiBaseUrl) {
     const result = { removedFile: false, removedKeychain: false };

package/dist/auth/device-flow-runner.d.ts

@@ -9,6 +9,15 @@
  *
  * Security: the PrivToken value is NEVER written to the provided sink.
  */
+import { type DeviceCodeResponse } from './device-flow.js';
+export declare function renderAuthBlock(apiBaseUrl: string, code: DeviceCodeResponse): string;
+/**
+ * Emit the authorization prompt: a one-click link (device code pre-filled),
+ * the manual fallback, and — for agent hosts — the machine-readable block.
+ * Shared by `runDeviceFlow` and `login --start` so both entry points present
+ * authorization identically.
+ */
+export declare function writeAuthPrompt(write: (msg: string) => void, apiBaseUrl: string, code: DeviceCodeResponse): void;
 export interface DeviceFlowOptions {
     /**
      * Upper bound on how long to poll for approval. When omitted the device
@@ -35,6 +44,12 @@ export type DeviceFlowOutcome = {
     status: 'error';
     message: string;
 };
+/**
+ * Persist an approved PrivToken. Shared by `runDeviceFlow` and `login --wait`
+ * so a credential written by either is indistinguishable. The token value is
+ * never written to `write`.
+ */
+export declare function persistApproval(apiBaseUrl: string, privToken: string, userLabel: string | undefined, write: (msg: string) => void): Promise<void>;
 /**
  * Run one full Device Flow against `apiBaseUrl`. On approval the PrivToken is
  * persisted via setCredential (keychain or file, same as `login`) and only the

package/dist/auth/device-flow-runner.js

@@ -11,9 +11,59 @@
  */
 import { DeviceFlowError, openBrowser, pollForToken, requestDeviceCode, } from './device-flow.js';
 import { setCredential } from './credential-store.js';
+import { isAgentHost } from './environment.js';
+/**
+ * Machine-readable authorization event, emitted alongside the human text when
+ * an agent host is driving the CLI. Delimited by markers (rather than a bare
+ * JSON line) because a skill's own stdout/stderr is interleaved on the same
+ * stream — the host greps for the block, never for prose that may be reworded.
+ */
+const AUTH_BLOCK_OPEN = '<<REMIXMATE_AUTH_REQUIRED';
+const AUTH_BLOCK_CLOSE = 'REMIXMATE_AUTH_REQUIRED>>';
+export function renderAuthBlock(apiBaseUrl, code) {
+    const payload = {
+        apiBaseUrl,
+        verificationUri: code.verificationUri,
+        verificationUriComplete: code.verificationUriComplete ?? code.verificationUri,
+        userCode: code.userCode,
+        expiresIn: code.expiresIn,
+    };
+    return `${AUTH_BLOCK_OPEN}\n${JSON.stringify(payload)}\n${AUTH_BLOCK_CLOSE}\n`;
+}
+/**
+ * Emit the authorization prompt: a one-click link (device code pre-filled),
+ * the manual fallback, and — for agent hosts — the machine-readable block.
+ * Shared by `runDeviceFlow` and `login --start` so both entry points present
+ * authorization identically.
+ */
+export function writeAuthPrompt(write, apiBaseUrl, code) {
+    const openUrl = code.verificationUriComplete ?? code.verificationUri;
+    write(`\n🔐 需要授权 remixmate CLI，请在浏览器中打开：\n  ${openUrl}\n`);
+    if (code.verificationUriComplete) {
+        write(`（若链接无法打开：访问 ${code.verificationUri} 并输入设备码 ${code.userCode}）\n`);
+    }
+    write('\n');
+    if (isAgentHost())
+        write(renderAuthBlock(apiBaseUrl, code));
+}
 function nowSec() {
     return Math.floor(Date.now() / 1000);
 }
+/**
+ * Persist an approved PrivToken. Shared by `runDeviceFlow` and `login --wait`
+ * so a credential written by either is indistinguishable. The token value is
+ * never written to `write`.
+ */
+export async function persistApproval(apiBaseUrl, privToken, userLabel, write) {
+    const { usedKeychain, keychainError } = await setCredential(apiBaseUrl, {
+        privToken,
+        userLabel,
+        createdAt: nowSec(),
+    });
+    if (!usedKeychain && keychainError) {
+        write('（系统钥匙串不可用，凭证已写入受保护的本地文件 ~/.config/remixmate/credentials.json）\n');
+    }
+}
 /**
  * Run one full Device Flow against `apiBaseUrl`. On approval the PrivToken is
  * persisted via setCredential (keychain or file, same as `login`) and only the
@@ -24,27 +74,25 @@ export async function runDeviceFlow(apiBaseUrl, opts = {}) {
     const clientLabel = opts.clientLabel ?? `remixmate-cli (${process.platform} ${process.arch})`;
     try {
         const code = await requestDeviceCode(apiBaseUrl, clientLabel);
+        // The backend pre-fills the user code into verificationUriComplete, so the
+        // user only has to click and confirm. Lead with that link — asking someone
+        // to open a bare URL and transcribe a device code is a different (much
+        // higher) difficulty tier, and the whole point is that a non-technical user
+        // never has to touch a terminal.
         const openUrl = code.verificationUriComplete ?? code.verificationUri;
-        // Always print the URL + user code, even when the browser auto-opens, so a
-        // host (Claude Code / Codex) can relay it to the user.
-        write(`\n请在浏览器中完成授权：\n  ${code.verificationUri}\n设备码：${code.userCode}\n\n`);
+        // Always print the link, even when the browser auto-opens, so a host
+        // (Claude Code / Codex) can relay it into the chat.
+        writeAuthPrompt(write, apiBaseUrl, code);
         if (openBrowser(openUrl)) {
             write('已尝试自动打开浏览器…\n');
         }
         else {
-            write('无法自动打开浏览器，请手动复制上面的地址。\n');
+            write('无法自动打开浏览器，请手动复制上面的链接。\n');
         }
         write('等待授权中（可在浏览器确认）…\n');
         const result = await pollForToken(apiBaseUrl, code, { maxWaitMs: opts.maxWaitMs });
         if (result.status === 'approved' && result.privToken) {
-            const { usedKeychain, keychainError } = await setCredential(apiBaseUrl, {
-                privToken: result.privToken,
-                userLabel: result.userLabel,
-                createdAt: nowSec(),
-            });
-            if (!usedKeychain && keychainError) {
-                write('（系统钥匙串不可用，凭证已写入受保护的本地文件 ~/.config/remixmate/credentials.json）\n');
-            }
+            await persistApproval(apiBaseUrl, result.privToken, result.userLabel, write);
             return { status: 'approved', userLabel: result.userLabel };
         }
         if (result.status === 'access_denied')

package/dist/auth/device-flow.js

@@ -12,17 +12,34 @@ async function postJson(url, body, timeoutMs) {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        const resp = await fetch(url, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
-            body: JSON.stringify(body),
-            signal: controller.signal,
-        });
+        let resp;
+        try {
+            resp = await fetch(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            // A DNS/TCP/TLS failure or an abort rejects with a plain Error. Left
+            // unwrapped it escapes runDeviceFlow's DeviceFlowError handler and
+            // surfaces to the user as a raw stack trace.
+            const reason = err instanceof Error && err.name === 'AbortError'
+                ? `请求超时（${Math.round(timeoutMs / 1000)}s）`
+                : err.message;
+            throw new DeviceFlowError(`无法连接授权服务 ${url}: ${reason}`);
+        }
         const text = await resp.text();
         if (!resp.ok) {
             throw new DeviceFlowError(`HTTP ${resp.status}: ${text.slice(0, 200)}`);
         }
-        return JSON.parse(text);
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new DeviceFlowError(`授权服务返回了非 JSON 响应: ${text.slice(0, 200)}`);
+        }
     }
     finally {
         clearTimeout(timer);