weaver-work-cli 0.1.40 → 0.1.42

package/dist/internal/e10/auth/xiaoe.js

@@ -5,7 +5,8 @@ import { join } from 'node:path';
 import { CliError, ExitCode } from '../../../core/errors.js';
 import { packagePath } from '../../../core/package-paths.js';
 import { isXiaoERuntime, isXiaoERuntimeAgent } from '../../../core/runtime-agent.js';
-import { buildE10CookieHeader, E10AuthSession, extractRawSetCookie, extractSessionTicket, profileNameFromUrl, readTeamsCheckUserInfo, saveAuthFile, saveProfileConfig, setActiveProfile, } from './session.js';
+import { createTimeoutSignal, isAbortError, isNetworkErrorCode, looksLikeTransportMessage, readErrorCauseCode, } from '../network-error.js';
+import { buildE10CookieHeader, E10_TEAMS_CHECK_TIMEOUT_MS, E10AuthSession, extractRawSetCookie, extractSessionTicket, profileNameFromUrl, readTeamsCheckUserInfo, saveAuthFile, saveProfileConfig, setActiveProfile, } from './session.js';
 export const DEFAULT_E10_BASE_URL = 'https://www.e-cology.com.cn';
 export const XIAOE_AGENT_TYPE = 'XiaoE';
 // `XIAOE_` 是宿主/平台保留前缀（XIAOE_DOMAIN、XIAOE_USER_TOKEN、XIAOE_SKILL_* 等）。
@@ -59,6 +60,109 @@ export const XIAOE_USER_TOKEN_SOURCE = 'XIAOE_USER_TOKEN';
 export const XIAOE_BUNDLED_ENV_SCRIPT_SOURCE = 'bundled scripts/xiaoe_env.py';
 /** 与 XiaoE `tokens.py` 保持一致：换票成功后默认有效 2 小时。 */
 export const XIAOE_ETEAMID_TTL_MS = 7_200_000;
+const XIAOE_DIAGNOSTIC_MAX_LENGTH = 300;
+/** 换票失败原因可能夹带服务端回显，落进结构化错误前先抹掉已知密钥。 */
+function redactXiaoEDiagnostic(message, secrets) {
+    let text = message;
+    for (const secret of secrets) {
+        if (secret && secret.length >= 8 && text.includes(secret)) {
+            text = text.split(secret).join('<redacted>');
+        }
+    }
+    const normalized = text.replace(/\s+/gu, ' ').trim();
+    return normalized.length > XIAOE_DIAGNOSTIC_MAX_LENGTH
+        ? `${normalized.slice(0, XIAOE_DIAGNOSTIC_MAX_LENGTH)}…`
+        : normalized;
+}
+function noteXiaoEStep(diagnostics, step) {
+    diagnostics?.attemptedSteps.push(step);
+}
+function tagXiaoEError(message, tags) {
+    return Object.assign(new CliError(message, ExitCode.AuthError), tags);
+}
+function readTag(error, key, type) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const value = error[key];
+    return typeof value === type ? value : undefined;
+}
+/** 401/403/3xx = 登录态被拒；其余 4xx/5xx 才算服务端 HTTP 异常。 */
+function classifyXiaoEHttpStatus(status) {
+    if (status === 401 || status === 403)
+        return 'credential';
+    if (status >= 300 && status < 400)
+        return 'credential';
+    return status >= 400 ? 'http' : 'credential';
+}
+/**
+ * 把任意异常归成三类。已经带标签的错误直接沿用；原始 fetch 异常则顺着
+ * `error.cause.code`（Node 把真实原因藏在这一层）区分网络错误与协议错误。
+ */
+function classifyXiaoEError(error) {
+    const taggedKind = readTag(error, 'errorKind', 'string');
+    const taggedStatus = readTag(error, 'status', 'number');
+    const taggedCause = readTag(error, 'causeCode', 'string');
+    const causeCode = taggedCause || readErrorCauseCode(error);
+    const withCause = causeCode ? { causeCode } : {};
+    const withStatus = taggedStatus === undefined ? {} : { status: taggedStatus };
+    if (taggedKind)
+        return { kind: taggedKind, ...withCause, ...withStatus };
+    const message = error instanceof Error ? error.message : String(error);
+    if (isAbortError(error))
+        return { kind: 'network', causeCode: causeCode || 'ETIMEDOUT' };
+    if (taggedStatus !== undefined) {
+        return { kind: classifyXiaoEHttpStatus(taggedStatus), ...withCause, status: taggedStatus };
+    }
+    if (causeCode && isNetworkErrorCode(causeCode))
+        return { kind: 'network', causeCode };
+    const httpMatch = /\bHTTP (\d{3})\b/u.exec(message);
+    if (httpMatch) {
+        const status = Number(httpMatch[1]);
+        return { kind: classifyXiaoEHttpStatus(status), ...withCause, status };
+    }
+    if (looksLikeTransportMessage(message))
+        return { kind: 'network', ...withCause };
+    return { kind: 'credential', ...withCause };
+}
+function noteXiaoEError(diagnostics, error, secrets = [], stage = 'e10_session') {
+    if (!diagnostics)
+        return;
+    const message = error instanceof Error ? error.message : String(error);
+    const redacted = redactXiaoEDiagnostic(message, secrets);
+    if (redacted)
+        diagnostics.lastError = redacted;
+    const { kind, causeCode, status } = classifyXiaoEError(error);
+    const failure = {
+        stage: readTag(error, 'stage', 'string') ?? stage,
+        kind,
+        message: redacted,
+        ...(causeCode ? { causeCode } : {}),
+        ...(status === undefined ? {} : { httpStatus: status }),
+    };
+    if (!diagnostics.failures)
+        diagnostics.failures = [];
+    diagnostics.failures.push(failure);
+}
+/**
+ * 一次恢复失败的整体归因：只要出现过明确的凭证拒绝，就按凭证问题报（用户该去
+ * 重新登录）；否则 HTTP 异常优先；只有**所有**失败都是网络错误时，才判定为
+ * 「暂时连不上 E10」，避免把网络抖动说成登录失效。
+ */
+export function summarizeXiaoEFailureKind(diagnostics) {
+    const failures = diagnostics?.failures || [];
+    if (!failures.length)
+        return undefined;
+    if (failures.some((failure) => failure.kind === 'credential'))
+        return 'credential';
+    if (failures.some((failure) => failure.kind === 'http'))
+        return 'http';
+    return failures.every((failure) => failure.kind === 'network') ? 'network' : undefined;
+}
+/** 最后一条失败记录，用于把结构化错误的 `stage` 指向真正卡住的那一步。 */
+export function lastXiaoEFailure(diagnostics) {
+    const failures = diagnostics?.failures || [];
+    return failures.length ? failures[failures.length - 1] : undefined;
+}
 function envString(env, ...keys) {
     for (const key of keys) {
         const value = env[key];
@@ -91,6 +195,18 @@ export function hasXiaoEEnv(env = process.env, options = {}) {
     const explicitAgentType = envString(env, 'WEAVER_AGENT_TYPE');
     return explicitAgentType ? isXiaoERuntimeAgent(explicitAgentType) : false;
 }
+export function resolveXiaoEClientType(env = process.env) {
+    const raw = envString(env, 'XIAOE_CLIENT_TYPE').toLowerCase();
+    if (raw === 'client' || raw === 'desktop' || raw === 'pc')
+        return 'client';
+    if (raw === 'cloud' || raw === 'web' || raw === 'browser')
+        return 'cloud';
+    return undefined;
+}
+/** 网页端运行时没有桌面凭据通道，只有平台票据可换。 */
+export function isXiaoECloudRuntime(env = process.env) {
+    return resolveXiaoEClientType(env) === 'cloud';
+}
 export function describeXiaoECredentialSource(source) {
     // Step 1 is the platform-injected credential (XIAOE_USER_TOKEN + XIAOE_DOMAIN):
     // it is available in every sandbox run and needs no local desktop client.
@@ -706,15 +822,22 @@ export function inspectXiaoEUnifiedLoginSources(options = {}) {
     });
     const platformCredential = hasXiaoEPlatformCredential(env);
     const allowLocalDiscovery = options.allowLocalDiscovery !== false;
-    const tokenScript = options.allowTokenScript !== false
+    const clientType = resolveXiaoEClientType(env);
+    // 网页端/沙箱不存在桌面凭据通道，跳过探测也就不会被机器上别人的
+    // 客户端登录态误命中。
+    const allowDesktopChannels = clientType !== 'cloud';
+    const tokenScript = allowDesktopChannels
+        && options.allowTokenScript !== false
         && hasXiaoETokenScript(env, allowLocalDiscovery);
-    const clientCredential = hasXiaoEClientCredential(env, allowLocalDiscovery);
+    const clientCredential = allowDesktopChannels
+        && hasXiaoEClientCredential(env, allowLocalDiscovery);
     const environmentCredential = Boolean(baseUrl && resolveXiaoEUnifiedLoginCredential(baseUrl, env));
     return {
         platformCredential,
         tokenScript,
         clientCredential,
         environmentCredential,
+        clientType,
         any: platformCredential || tokenScript || clientCredential || environmentCredential,
     };
 }
@@ -741,11 +864,16 @@ async function fetchXiaoEClientEteamId(credential, domain) {
             if (resp.status < 300 || resp.status >= 400)
                 break;
             if (redirects === 5) {
-                throw new CliError('XiaoE client token endpoint redirected too many times.', ExitCode.AuthError);
+                throw tagXiaoEError('XiaoE client token endpoint redirected too many times.', {
+                    errorKind: 'http',
+                });
             }
             const location = resp.headers.get('location');
             if (!location) {
-                throw new CliError('XiaoE client token endpoint returned a redirect without Location.', ExitCode.AuthError);
+                throw tagXiaoEError('XiaoE client token endpoint returned a redirect without Location.', {
+                    errorKind: 'http',
+                    status: resp.status,
+                });
             }
             const next = new URL(location, endpoint);
             const sameOrigin = next.origin === endpoint.origin;
@@ -754,17 +882,32 @@ async function fetchXiaoEClientEteamId(credential, domain) {
                 && next.hostname === endpoint.hostname;
             const safeProtocol = next.protocol === 'http:' || next.protocol === 'https:';
             if (!safeProtocol || next.username || next.password || (!sameOrigin && !sameHostHttpsUpgrade)) {
-                throw new CliError('XiaoE client token endpoint attempted an unsafe cross-origin redirect.', ExitCode.AuthError);
+                throw tagXiaoEError('XiaoE client token endpoint attempted an unsafe cross-origin redirect.', {
+                    errorKind: 'http',
+                    status: resp.status,
+                });
             }
             await resp.body?.cancel().catch(() => undefined);
             endpoint = next;
         }
         if (!resp?.ok) {
-            throw new CliError(`XiaoE client token endpoint returned HTTP ${resp?.status || 0}.`, ExitCode.AuthError);
+            const status = resp?.status || 0;
+            throw tagXiaoEError(`XiaoE client token endpoint returned HTTP ${status}.`, {
+                errorKind: classifyXiaoEHttpStatus(status),
+                status,
+            });
         }
-        const data = await resp.json().catch(() => null);
+        const data = await resp.json().catch((error) => {
+            // 读响应体时被超时打断属于网络错误，不能当成「返回了非法 JSON」。
+            if (isAbortError(error))
+                throw error;
+            return null;
+        });
         if (!data || typeof data !== 'object' || Array.isArray(data)) {
-            throw new CliError('XiaoE client token endpoint returned invalid JSON.', ExitCode.AuthError);
+            throw tagXiaoEError('XiaoE client token endpoint returned invalid JSON.', {
+                errorKind: 'http',
+                status: resp.status,
+            });
         }
         const payload = data;
         const businessCode = payload.code;
@@ -773,10 +916,23 @@ async function fetchXiaoEClientEteamId(credential, domain) {
             : {};
         if ((businessCode !== '0000' && businessCode !== 0 && businessCode !== 200) || !readString(businessData, 'eteamId')) {
             const codeText = businessCode === undefined ? 'missing' : String(businessCode);
-            throw new CliError(`XiaoE client token exchange failed with business code ${codeText}.`, ExitCode.AuthError);
+            throw tagXiaoEError(`XiaoE client token exchange failed with business code ${codeText}.`, {
+                errorKind: 'credential',
+            });
         }
         return payload;
     }
+    catch (error) {
+        if (isAbortError(error)) {
+            throw tagXiaoEError(`XiaoE client token endpoint timed out after ${XIAOE_CLIENT_TOKEN_TIMEOUT_MS} ms.`, { errorKind: 'network', causeCode: 'ETIMEDOUT' });
+        }
+        // 已经带语义的 HTTP / 业务码错误原样上抛，别再包一层网络错误。
+        if (error instanceof CliError)
+            throw error;
+        const causeCode = readErrorCauseCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        throw tagXiaoEError(`XiaoE client token endpoint request failed${causeCode ? ` (${causeCode})` : ''}: ${message}`, { errorKind: 'network', ...(causeCode ? { causeCode } : {}) });
+    }
     finally {
         clearTimeout(timer);
     }
@@ -831,26 +987,62 @@ export function createXiaoEUnifiedLoginUnavailableError(baseUrl = '') {
     });
 }
 async function resolveUserInfo(baseUrl, eteamsId, rawCookie = '', agentType = '') {
-    const resp = await fetch(`${baseUrl}/api/baseserver/layout/teamsCheck?clientType=not_xinchuang&client=WEB&domainName=${encodeURIComponent(baseUrl)}`, {
-        method: 'POST',
-        headers: {
-            accept: 'application/json',
-            'content-type': 'application/json',
-            eteamsid: eteamsId,
-            cookie: buildE10CookieHeader(rawCookie, eteamsId, agentType),
-            'user-agent': agentType ? `AgentType=${agentType},IsAgent=true` : 'weaver-work-cli',
-            origin: baseUrl,
-        },
-        redirect: 'manual',
-    });
-    const data = await resp.json().catch(() => ({}));
-    return { userInfo: readTeamsCheckUserInfo(resp, data), setCookie: extractRawSetCookie(resp) };
+    // teamsCheck 是恢复流程的必经往返：没有超时的话，服务端半开连接会把整条命令挂死。
+    const { signal, clear } = createTimeoutSignal(E10_TEAMS_CHECK_TIMEOUT_MS);
+    try {
+        const resp = await fetch(`${baseUrl}/api/baseserver/layout/teamsCheck?clientType=not_xinchuang&client=WEB&domainName=${encodeURIComponent(baseUrl)}`, {
+            method: 'POST',
+            headers: {
+                accept: 'application/json',
+                'content-type': 'application/json',
+                eteamsid: eteamsId,
+                cookie: buildE10CookieHeader(rawCookie, eteamsId, agentType),
+                'user-agent': agentType ? `AgentType=${agentType},IsAgent=true` : 'weaver-work-cli',
+                origin: baseUrl,
+            },
+            redirect: 'manual',
+            signal,
+        });
+        // 读响应体同样在超时窗口内；中途被 abort 不能当成「空响应」吞掉。
+        const data = await resp.json().catch((error) => {
+            if (isAbortError(error))
+                throw error;
+            return {};
+        });
+        return { userInfo: readTeamsCheckUserInfo(resp, data), setCookie: extractRawSetCookie(resp), status: resp.status };
+    }
+    catch (error) {
+        if (isAbortError(error)) {
+            throw tagXiaoEError(`E10 teamsCheck timed out after ${E10_TEAMS_CHECK_TIMEOUT_MS} ms.`, { errorKind: 'network', stage: 'teams_check', causeCode: 'ETIMEDOUT' });
+        }
+        if (error instanceof CliError)
+            throw error;
+        const causeCode = readErrorCauseCode(error);
+        const message = error instanceof Error ? error.message : String(error);
+        throw tagXiaoEError(`E10 teamsCheck request failed${causeCode ? ` (${causeCode})` : ''}: ${message}`, { errorKind: 'network', stage: 'teams_check', ...(causeCode ? { causeCode } : {}) });
+    }
+    finally {
+        clear();
+    }
 }
 async function saveXiaoEUnifiedLogin(input) {
     const baseUrl = normalizeUrl(input.baseUrl);
-    const { userInfo, setCookie } = await resolveUserInfo(baseUrl, input.eteamsId, input.rawCookie || '', XIAOE_AGENT_TYPE);
+    const { userInfo, setCookie, status } = await resolveUserInfo(baseUrl, input.eteamsId, input.rawCookie || '', XIAOE_AGENT_TYPE);
     if (!userInfo.userId) {
-        throw new CliError('Could not resolve userId. Check whether XiaoE unified login is valid for this E10 domain.', ExitCode.AuthError);
+        // 401/403/3xx 是「票不被接受」，用户该去恢复登录；5xx 则是 E10 侧故障，
+        // 报成凭证问题会把人引向无用的重新登录。
+        const statusText = status || 0;
+        throw classifyXiaoEHttpStatus(statusText) === 'http'
+            ? tagXiaoEError(`E10 teamsCheck returned HTTP ${statusText}.`, {
+                errorKind: 'http',
+                stage: 'teams_check',
+                status: statusText,
+            })
+            : tagXiaoEError('Could not resolve userId. Check whether XiaoE unified login is valid for this E10 domain.', {
+                errorKind: 'credential',
+                stage: 'teams_check',
+                status: statusText,
+            });
     }
     const tenantKey = userInfo.tenantKey || input.tenantKeyFallback || '';
     const profile = input.profileHint || profileNameFromUrl(baseUrl);
@@ -908,19 +1100,32 @@ export async function tryXiaoEUnifiedLogin(options = {}) {
         profileBaseUrl: options.profileBaseUrl,
         env,
     });
-    const mayUseTokenScript = options.allowTokenScript === true;
-    if (!baseUrl && !mayUseTokenScript)
+    // 网页端没有桌面凭据通道：`XIAOE_CLIENT_TYPE=cloud` 时不尝试 tokens.py 与
+    // 本地客户端会话，避免在共享机器上误用他人的客户端登录态。
+    const mayUseTokenScript = options.allowTokenScript === true && !isXiaoECloudRuntime(env);
+    const diagnostics = options.diagnostics;
+    const platformCredentialDetected = hasXiaoEPlatformCredential(env);
+    const secrets = [envString(env, 'XIAOE_USER_TOKEN')];
+    if (diagnostics) {
+        diagnostics.baseUrl = baseUrl;
+        diagnostics.platformCredentialDetected = platformCredentialDetected;
+        diagnostics.clientType = resolveXiaoEClientType(env);
+    }
+    if (!baseUrl && !mayUseTokenScript) {
+        noteXiaoEStep(diagnostics, 'base_url:missing');
         return null;
+    }
     let credential = null;
     // Step 1 — platform-injected credential (XIAOE_USER_TOKEN + XIAOE_DOMAIN).
     // Works in sandboxes: no desktop client, no Python, no developer-machine paths.
-    if (hasXiaoEPlatformCredential(env)) {
+    if (platformCredentialDetected) {
         options.logger?.info('Trying XiaoE platform credential from XIAOE_USER_TOKEN...');
         try {
             credential = await resolveXiaoEPlatformCredential(baseUrl || DEFAULT_E10_BASE_URL, env);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            noteXiaoEError(diagnostics, error, secrets, 'platform_token');
             options.logger?.warn('XiaoE platform credential failed. ' + message);
         }
         if (!credential) {
@@ -929,25 +1134,38 @@ export async function tryXiaoEUnifiedLogin(options = {}) {
                 : 'XiaoE platform credential did not return usable ETEAMSID; will try xiaoeUserData/tokens.py next.');
         }
     }
+    noteXiaoEStep(diagnostics, credential ? 'platform_token:ok' : `platform_token:${platformCredentialDetected ? 'failed' : 'missing'}`);
     // Step 1b — compatibility path used by the reference login package. The
     // script is shipped with the CLI npm package (never with a Skill) and its
     // stdout stays inside this process so credentials are not exposed to agents.
-    if (!credential && options.allowBundledEnvScript && hasXiaoEPlatformCredential(env)) {
-        const scriptPath = xiaoEBundledEnvScriptPath();
-        if (!scriptPath) {
-            options.logger?.warn('CLI-bundled xiaoe_env.py was not found; will try desktop XiaoE credential sources next.');
+    if (!credential) {
+        if (!options.allowBundledEnvScript) {
+            noteXiaoEStep(diagnostics, 'bundled_env_script:disabled');
+        }
+        else if (!platformCredentialDetected) {
+            // 脚本本身也只读 XIAOE_USER_TOKEN/XIAOE_DOMAIN，前置缺失时重跑没有意义。
+            noteXiaoEStep(diagnostics, 'bundled_env_script:missing');
         }
         else {
-            options.logger?.info('Trying CLI-bundled xiaoe_env.py compatibility credential...');
-            try {
-                credential = await resolveXiaoEBundledEnvScriptCredential(baseUrl || DEFAULT_E10_BASE_URL, env);
+            const scriptPath = xiaoEBundledEnvScriptPath();
+            if (!scriptPath) {
+                noteXiaoEStep(diagnostics, 'bundled_env_script:missing');
+                options.logger?.warn('CLI-bundled xiaoe_env.py was not found; will try desktop XiaoE credential sources next.');
             }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                options.logger?.warn('CLI-bundled xiaoe_env.py failed. ' + message);
-            }
-            if (!credential) {
-                options.logger?.warn('CLI-bundled xiaoe_env.py did not return usable ETEAMSID; will try xiaoeUserData/tokens.py next.');
+            else {
+                options.logger?.info('Trying CLI-bundled xiaoe_env.py compatibility credential...');
+                try {
+                    credential = await resolveXiaoEBundledEnvScriptCredential(baseUrl || DEFAULT_E10_BASE_URL, env);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    noteXiaoEError(diagnostics, error, secrets, 'bundled_env_script');
+                    options.logger?.warn('CLI-bundled xiaoe_env.py failed. ' + message);
+                }
+                if (!credential) {
+                    options.logger?.warn('CLI-bundled xiaoe_env.py did not return usable ETEAMSID; will try xiaoeUserData/tokens.py next.');
+                }
+                noteXiaoEStep(diagnostics, `bundled_env_script:${credential ? 'ok' : 'failed'}`);
             }
         }
     }
@@ -955,6 +1173,7 @@ export async function tryXiaoEUnifiedLogin(options = {}) {
     if (!credential && mayUseTokenScript) {
         const tokenScriptPath = xiaoETokenScriptPath(env);
         if (!tokenScriptPath) {
+            noteXiaoEStep(diagnostics, 'token_script:missing');
             options.logger?.warn('XiaoE token script not found. Expected xiaoeUserData/tokens.py; will try the local XiaoE client session next.');
         }
         else {
@@ -964,11 +1183,13 @@ export async function tryXiaoEUnifiedLogin(options = {}) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                noteXiaoEError(diagnostics, error, secrets, 'token_script');
                 options.logger?.warn('XiaoE token script failed. ' + message);
             }
             if (!credential) {
                 options.logger?.warn('XiaoE token script did not return usable ETEAMSID; will try the local XiaoE client session next.');
             }
+            noteXiaoEStep(diagnostics, `token_script:${credential ? 'ok' : 'failed'}`);
         }
         // Step 3 — built-in Node equivalent of tokens.py: reads the local XiaoE
         // client session and exchanges it for an eteamId, so Python availability
@@ -980,20 +1201,32 @@ export async function tryXiaoEUnifiedLogin(options = {}) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
+                noteXiaoEError(diagnostics, error, secrets, 'client_session');
                 options.logger?.warn('Built-in XiaoE client credential failed. ' + message);
             }
             if (!credential) {
                 options.logger?.warn('Built-in XiaoE client credential did not return usable ETEAMSID; will try WEAVER_XIAOE_* credentials next.');
             }
+            noteXiaoEStep(diagnostics, `client_session:${credential ? 'ok' : 'failed'}`);
         }
+        else if (!credential) {
+            noteXiaoEStep(diagnostics, 'client_session:missing');
+        }
+    }
+    else if (!credential) {
+        noteXiaoEStep(diagnostics, 'token_script:disabled');
+        noteXiaoEStep(diagnostics, 'client_session:disabled');
     }
     if (!credential && baseUrl)
         credential = resolveXiaoEUnifiedLoginCredential(baseUrl, env);
-    if (!credential)
+    if (!credential) {
+        noteXiaoEStep(diagnostics, 'environment_map:empty');
         return null;
+    }
+    noteXiaoEStep(diagnostics, `credential_source:${credential.source}`);
     options.logger?.info('Detected XiaoE unified login for this E10 domain. Trying XiaoE auth...');
     try {
-        return await saveXiaoEUnifiedLogin({
+        const login = await saveXiaoEUnifiedLogin({
             baseUrl: credential.baseUrl || baseUrl || DEFAULT_E10_BASE_URL,
             eteamsId: credential.eteamsId,
             rawCookie: credential.rawCookie,
@@ -1002,9 +1235,18 @@ export async function tryXiaoEUnifiedLogin(options = {}) {
             profileHint: options.profileHint,
             credentialSource: describeXiaoECredentialSource(credential.source),
         });
+        noteXiaoEStep(diagnostics, 'e10_session:ok');
+        if (diagnostics) {
+            // 成功换到登录态：前面压着的失败不该再让调用方误判整次恢复失败。
+            delete diagnostics.lastError;
+            delete diagnostics.failures;
+        }
+        return login;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
+        noteXiaoEError(diagnostics, error, secrets, 'e10_session');
+        noteXiaoEStep(diagnostics, 'e10_session:failed');
         options.logger?.warn('XiaoE unified login failed. ' + message);
         return null;
     }

package/dist/internal/e10/auth-recovery.js

@@ -1,6 +1,6 @@
 import { isXiaoERuntimeAgent } from '../../core/runtime-agent.js';
 import { getActiveProfile, readProfileConfig } from './auth/session.js';
-import { hasXiaoEEnv, resolveXiaoEPreferredBaseUrl, tryXiaoEUnifiedLogin } from './auth/xiaoe.js';
+import { hasXiaoEEnv, resolveXiaoEPreferredBaseUrl, tryXiaoEUnifiedLogin, } from './auth/xiaoe.js';
 const AUTH_REQUIRED_CODES = new Set(['-2', '401']);
 const AUTH_REQUIRED_MARKERS = [
     '未登录',
@@ -224,6 +224,24 @@ export function canAutomaticallyRecoverXiaoE(ctx, currentSession) {
         || currentSession?.loginSource === 'xiaoe-unified'
         || isXiaoERuntimeAgent(currentSession?.agentType);
 }
+/**
+ * 透明恢复默认必须零输出：中间登录步骤绝不能漏进 Agent 的 stdout 或 JSON。
+ * 只有显式 `--verbose`（且非 `--json`/`--quiet`）时才把每一步的真实失败原因
+ * 经 debug 通道送到 stderr，供人排查。宿主 logger 若没有 debug（测试替身、
+ * 旧嵌入方）则继续完全静默。
+ */
+function recoveryLogger(ctx) {
+    const options = globalOptions(ctx);
+    if (options.json || options.quiet || options.verbose !== true)
+        return undefined;
+    const adapter = ctx.logger;
+    if (!adapter || typeof adapter.debug !== 'function')
+        return undefined;
+    return {
+        info: (message) => adapter.debug(message),
+        warn: (message) => adapter.debug(message),
+    };
+}
 /**
  * Silently recover a stale or missing XiaoE session. Without a local session,
  * current runtime evidence is required before obtaining credentials.
@@ -232,8 +250,20 @@ export function canAutomaticallyRecoverXiaoE(ctx, currentSession) {
  * does not start a burst of login attempts.
  */
 export async function recoverXiaoEAuthSession(ctx, currentSession) {
+    return (await recoverXiaoEAuthSessionWithDiagnostics(ctx, currentSession)).session;
+}
+/**
+ * `recoverXiaoEAuthSession` 的诊断版：失败时返回本次尝试评估过哪些凭证来源、
+ * 最后一条真实原因，供调用方挂到结构化错误上。并发恢复共享同一份诊断
+ * （同一个 in-flight Promise），因此每个等待者看到的原因一致。
+ */
+export async function recoverXiaoEAuthSessionWithDiagnostics(ctx, currentSession) {
+    const emptyOutcome = () => ({
+        session: null,
+        diagnostics: { attemptedSteps: [] },
+    });
     if (!canAutomaticallyRecoverXiaoE(ctx, currentSession))
-        return null;
+        return emptyOutcome();
     const options = globalOptions(ctx);
     const profile = options.profile || getActiveProfile();
     const config = readProfileConfig(profile);
@@ -246,6 +276,7 @@ export async function recoverXiaoEAuthSession(ctx, currentSession) {
     const existing = recoveryInFlight.get(key);
     if (existing)
         return existing;
+    const diagnostics = { attemptedSteps: [] };
     const recovery = (async () => {
         const login = await tryXiaoEUnifiedLogin({
             env: ctx.env,
@@ -255,10 +286,10 @@ export async function recoverXiaoEAuthSession(ctx, currentSession) {
             allowTokenScript: true,
             tenantKeyFallback: currentSession?.tenantKey || config.tenantKey,
             profileHint: profile,
-            // Intentionally no logger: transparent recovery must not leak an
-            // intermediate "login" step into agent stdout/stderr or JSON output.
+            diagnostics,
+            logger: recoveryLogger(ctx),
         });
-        return login?.session || null;
+        return { session: login?.session || null, diagnostics };
     })();
     recoveryInFlight.set(key, recovery);
     try {

package/dist/internal/e10/context.js

@@ -1,14 +1,55 @@
 import { CliError, ExitCode } from '../../core/errors.js';
-import { E10_AUTH_REQUIRED_MESSAGE, E10_XIAOE_RECOVERY_FAILED_MESSAGE } from './auth/messages.js';
+import { E10_AUTH_REQUIRED_MESSAGE, E10_XIAOE_HOST_CREDENTIAL_MISSING_MESSAGE, E10_XIAOE_NETWORK_UNAVAILABLE_MESSAGE, E10_XIAOE_RECOVERY_FAILED_MESSAGE, } from './auth/messages.js';
+import { lastXiaoEFailure, summarizeXiaoEFailureKind, } from './auth/xiaoe.js';
 import { E10AuthSession } from './auth/session.js';
 import { E10ApiClient } from './client.js';
-import { canAutomaticallyRecoverXiaoE, recoverXiaoEAuthSession } from './auth-recovery.js';
-function xiaoERecoveryFailedError() {
-    return Object.assign(new CliError(E10_XIAOE_RECOVERY_FAILED_MESSAGE, ExitCode.AuthError), {
+import { canAutomaticallyRecoverXiaoE, recoverXiaoEAuthSession, recoverXiaoEAuthSessionWithDiagnostics, } from './auth-recovery.js';
+/**
+ * 把一次失败的静默恢复转成可定位的结构化错误。文案按归因分流：只有网络层
+ * 完全没打通时才提示「稍后重试」（此时登录态根本没被验证过，让人去重新登录
+ * 是误导）；其余情况沿用原文案。诊断放进 `details`：`attemptedSteps` 说明
+ * 评估过哪些凭证通道及各自结果，`failures` 保留每一次失败的阶段、类别和
+ * `error.cause.code`，`lastError` 是最后一条真实原因（已脱敏截断），
+ * `resultSessionExpired` 表示票其实换到了、但被判为已过期。
+ */
+function xiaoERecoveryFailedError(diagnostics, resultSessionExpired = false) {
+    const failureKind = summarizeXiaoEFailureKind(diagnostics);
+    const lastFailure = lastXiaoEFailure(diagnostics);
+    const networkUnavailable = failureKind === 'network';
+    // Web sandboxes only have the platform credential channel. If the runtime
+    // marker survived but the host credential pair did not, asking the user to
+    // log in again is misleading: the sandbox launcher dropped the injection.
+    const hostCredentialMissing = diagnostics?.clientType === 'cloud'
+        && diagnostics.platformCredentialDetected === false
+        && diagnostics.attemptedSteps.includes('platform_token:missing')
+        && diagnostics.attemptedSteps.includes('environment_map:empty');
+    const details = diagnostics
+        ? {
+            ...(diagnostics.baseUrl ? { baseUrl: diagnostics.baseUrl } : {}),
+            ...(diagnostics.clientType ? { clientType: diagnostics.clientType } : {}),
+            ...(diagnostics.platformCredentialDetected === undefined
+                ? {}
+                : { platformCredentialDetected: diagnostics.platformCredentialDetected }),
+            attemptedSteps: diagnostics.attemptedSteps,
+            ...(diagnostics.lastError ? { lastError: diagnostics.lastError } : {}),
+            ...(failureKind ? { errorKind: failureKind } : {}),
+            ...(lastFailure ? { failureStage: lastFailure.stage } : {}),
+            ...(diagnostics.failures?.length ? { failures: diagnostics.failures } : {}),
+            ...(hostCredentialMissing ? { reason: 'host_credential_not_injected' } : {}),
+            ...(resultSessionExpired ? { resultSessionExpired: true } : {}),
+        }
+        : undefined;
+    return Object.assign(new CliError(networkUnavailable
+        ? E10_XIAOE_NETWORK_UNAVAILABLE_MESSAGE
+        : hostCredentialMissing
+            ? E10_XIAOE_HOST_CREDENTIAL_MISSING_MESSAGE
+            : E10_XIAOE_RECOVERY_FAILED_MESSAGE, ExitCode.AuthError), {
         type: 'authentication',
-        subtype: 'xiaoe_credential_unavailable',
-        retryable: false,
-        stage: 'xiaoe_unified_login',
+        subtype: networkUnavailable ? 'xiaoe_network_unavailable' : 'xiaoe_credential_unavailable',
+        // 网络错误是可重试的；凭证缺失/被拒重试也一样失败，不能让调用方空转。
+        retryable: networkUnavailable,
+        stage: lastFailure?.stage || 'xiaoe_unified_login',
+        ...(details ? { details } : {}),
     });
 }
 export async function getE10Session(ctx, load = {}) {
@@ -18,16 +59,19 @@ export async function getE10Session(ctx, load = {}) {
 export async function requireE10Session(ctx, load = {}) {
     let session = await getE10Session(ctx, load);
     if (session?.isExpired() && canAutomaticallyRecoverXiaoE(ctx, session)) {
-        session = await recoverXiaoEAuthSession(ctx, session).catch(() => null);
-        if (!session || session.isExpired())
-            throw xiaoERecoveryFailedError();
+        const outcome = await recoverXiaoEAuthSessionWithDiagnostics(ctx, session).catch(() => null);
+        session = outcome?.session || null;
+        if (!session || session.isExpired()) {
+            throw xiaoERecoveryFailedError(outcome?.diagnostics, session?.isExpired() === true);
+        }
     }
     if (!session && canAutomaticallyRecoverXiaoE(ctx)) {
         // Read-only probes use getE10Session; only a command requiring a session
         // may establish one from the current XiaoE host's credentials.
-        session = await recoverXiaoEAuthSession(ctx).catch(() => null);
+        const outcome = await recoverXiaoEAuthSessionWithDiagnostics(ctx).catch(() => null);
+        session = outcome?.session || null;
         if (!session) {
-            throw xiaoERecoveryFailedError();
+            throw xiaoERecoveryFailedError(outcome?.diagnostics);
         }
     }
     if (!session) {

package/dist/internal/e10/index.js

@@ -1,4 +1,4 @@
 export { E10ApiClient } from './client.js';
 export { getE10Client, getE10Session, requireE10Client, requireE10Session } from './context.js';
 export { E10ApiError, E10RequestRuntime, createE10RequestRuntime } from './request-runtime.js';
-export { canAutomaticallyRecoverXiaoE, isE10AuthenticationRequired, recoverXiaoEAuthSession, } from './auth-recovery.js';
+export { canAutomaticallyRecoverXiaoE, isE10AuthenticationRequired, recoverXiaoEAuthSession, recoverXiaoEAuthSessionWithDiagnostics, } from './auth-recovery.js';