weaver-work-cli 0.1.39 → 0.1.42

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

@@ -4,8 +4,14 @@ import { dirname, resolve } from 'node:path';
 import { CliError, ExitCode } from '../../../core/errors.js';
 import { isConnectorMode } from '../../../core/connector.js';
 import { writeWithRetry } from '../../../core/write-with-retry.js';
+import { createTimeoutSignal } from '../network-error.js';
 import { encryptAuthData, parseAuthFile } from './crypto.js';
 import { getE10ActiveProfilePath, getE10ProfilesRoot } from './paths.js';
+/**
+ * teamsCheck 与会话探测都是「发业务请求之前的必经往返」，没有上限时一个半开
+ * 连接就能把整条命令挂死。所有这类小请求统一用这个超时。
+ */
+export const E10_TEAMS_CHECK_TIMEOUT_MS = 15_000;
 const RSA_PUBLIC_KEY_PEM = `-----BEGIN PUBLIC KEY-----
 MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCEOk/WyyJKdAHIfMODFnKg7MBoraFBnL3F18hhLx5n01J5g4hCkmpc5+KQFKIQIA/QWk9m7QBzI/OV9ZDFk54LaWm3xP8C+P1TPp7UVGz3iNDLdvgSxuGEYPmML3NaqkbVlvW7/NlNA3ED4Kao7rR5GUYSdFfbaBoxBFae638hzQIDAQAB
 -----END PUBLIC KEY-----`;
@@ -337,6 +343,15 @@ export class E10AuthSession {
     get credentialSourceLabel() {
         return this.data.credentialSourceLabel || '';
     }
+    get expiryTimes() {
+        const value = Number(this.data.expiryTimes);
+        return Number.isFinite(value) && value > 0 ? value : undefined;
+    }
+    /** XiaoE 换取的 ETEAMSID 是否已经超过其明确的失效时间。 */
+    isExpired(now = Date.now()) {
+        const expiryTimes = this.expiryTimes;
+        return expiryTimes !== undefined && now >= expiryTimes;
+    }
     getBaseUrl() {
         return (this.data.baseUrl || '').replace(/\/$/, '');
     }
@@ -389,6 +404,7 @@ export class E10AuthSession {
             stTicket: this.data.stTicket,
             redirectUrl: this.data.redirectUrl,
             cookieSavedAt: this.data.cookieSavedAt,
+            expiryTimes: this.expiryTimes,
             mainUrl: this.data.mainUrl,
             ...sourceInfo,
             hasEteamsId: Boolean(this.eteamsId),
@@ -419,12 +435,14 @@ export class E10AuthSession {
             return null;
         const session = E10AuthSession.fromFile(authPath, baseUrl, passportUrl);
         // 富化只是"刷新/纠偏"：登录时这些字段已落盘。调用方可显式跳过（见 E10SessionLoadOptions）。
-        if (session && !(load.skipProfileEnrichment && hasUsableUserId(session))) {
+        if (session && !session.isExpired() && !(load.skipProfileEnrichment && hasUsableUserId(session))) {
             await session.fetchEmployeeId();
         }
         return session;
     }
     async fetchEmployeeId() {
+        // 富化不是关键路径：超时就放弃，不能让 teamsCheck 无限等待。
+        const { signal, clear } = createTimeoutSignal(E10_TEAMS_CHECK_TIMEOUT_MS);
         try {
             const resp = await fetch(`${this.getBaseUrl()}/api/baseserver/layout/teamsCheck?clientType=not_xinchuang&client=WEB&domainName=${encodeURIComponent(this.getBaseUrl())}`, {
                 method: 'POST',
@@ -436,6 +454,7 @@ export class E10AuthSession {
                     'user-agent': this.uaHeader(),
                     origin: this.getBaseUrl(),
                 },
+                signal,
             });
             const data = await resp.json().catch(() => ({}));
             const userInfo = readTeamsCheckUserInfo(resp, data);
@@ -455,8 +474,12 @@ export class E10AuthSession {
         catch {
             // Non-critical profile enrichment.
         }
+        finally {
+            clear();
+        }
     }
     async checkValid() {
+        const { signal, clear } = createTimeoutSignal(E10_TEAMS_CHECK_TIMEOUT_MS);
         try {
             const resp = await fetch(`${this.getBaseUrl()}/api/ecode/tree/list?parentId=0`, {
                 headers: {
@@ -466,12 +489,16 @@ export class E10AuthSession {
                     'user-agent': this.uaHeader(),
                 },
                 redirect: 'manual',
+                signal,
             });
             return resp.status === 200;
         }
         catch {
             return false;
         }
+        finally {
+            clear();
+        }
     }
     async ensureValid() {
         if (await this.checkValid())

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_* 等）。
@@ -57,6 +58,111 @@ export const XIAOE_SKILL_ETEAMID_API_PATH = '/spec-apps/api/app/rpachat/skill/ex
 export const XIAOE_CLIENT_SETTINGS_SOURCE = 'XiaoE/Robots/user_settings.json';
 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];
@@ -89,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.
@@ -134,6 +252,14 @@ function readString(data, ...keys) {
     }
     return '';
 }
+function readExpiryTimes(data) {
+    for (const key of ['expiryTimes', 'expiryTime', 'expiresAt', 'expires_at']) {
+        const value = Number(data[key]);
+        if (Number.isFinite(value) && value > 0)
+            return Math.trunc(value);
+    }
+    return undefined;
+}
 function cookieString(value) {
     if (!value)
         return '';
@@ -209,7 +335,19 @@ function readXiaoECredentialRecord(value, source, fallbackBaseUrl = '') {
         || cookieValue(rawCookie, 'ETEAMSID');
     if (!baseUrl || !eteamsId)
         return null;
-    return { baseUrl: normalizeUrl(baseUrl), eteamsId, source, rawCookie };
+    const expiryTimes = candidates.map(readExpiryTimes).find((value) => value !== undefined);
+    return {
+        baseUrl: normalizeUrl(baseUrl),
+        eteamsId,
+        source,
+        rawCookie,
+        ...(expiryTimes !== undefined ? { expiryTimes } : {}),
+    };
+}
+function withDefaultXiaoEExpiry(credential) {
+    if (!credential || credential.expiryTimes !== undefined)
+        return credential;
+    return { ...credential, expiryTimes: Date.now() + XIAOE_ETEAMID_TTL_MS };
 }
 function parseXiaoEUnifiedLoginMap(raw, source) {
     const value = raw.trim();
@@ -533,7 +671,7 @@ async function resolveXiaoETokenScriptCredential(baseUrl, env = process.env) {
     const tokenData = await runXiaoETokenScript(baseUrl, env);
     if (!tokenData)
         return null;
-    return readXiaoECredentialRecord(tokenData, 'xiaoeUserData/tokens.py', baseUrl);
+    return withDefaultXiaoEExpiry(readXiaoECredentialRecord(tokenData, 'xiaoeUserData/tokens.py', baseUrl));
 }
 async function resolveXiaoEBundledEnvScriptCredential(baseUrl, env = process.env) {
     const scriptPath = xiaoEBundledEnvScriptPath();
@@ -542,7 +680,7 @@ async function resolveXiaoEBundledEnvScriptCredential(baseUrl, env = process.env
     const tokenData = await runXiaoEPythonCredentialScript(scriptPath, baseUrl, env);
     if (!tokenData)
         return null;
-    return readXiaoECredentialRecord(tokenData, XIAOE_BUNDLED_ENV_SCRIPT_SOURCE, baseUrl);
+    return withDefaultXiaoEExpiry(readXiaoECredentialRecord(tokenData, XIAOE_BUNDLED_ENV_SCRIPT_SOURCE, baseUrl));
 }
 export function xiaoEClientRobotsRoot(env = process.env) {
     if (process.platform === 'win32') {
@@ -684,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,
     };
 }
@@ -719,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;
@@ -732,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;
@@ -751,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);
     }
@@ -766,7 +944,7 @@ async function resolveXiaoETokenCredential(credential, baseUrl) {
     // from the same origin as the token exchange. Newer 0000/200 responses keep
     // the XiaoE service origin separate and use the requested E10 target.
     const resolvedBaseUrl = payload.code === 0 ? credential.erpaUrl : targetBaseUrl;
-    return readXiaoECredentialRecord(payload, credential.source, resolvedBaseUrl);
+    return withDefaultXiaoEExpiry(readXiaoECredentialRecord(payload, credential.source, resolvedBaseUrl));
 }
 async function resolveXiaoEPlatformCredential(baseUrl, env = process.env) {
     const credential = readXiaoEPlatformCredential(env);
@@ -809,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);
@@ -850,6 +1064,7 @@ async function saveXiaoEUnifiedLogin(input) {
         baseUrl,
         passportUrl: baseUrl,
         cookieSavedAt: Date.now(),
+        ...(input.expiryTimes !== undefined ? { expiryTimes: input.expiryTimes } : {}),
         loginSource: 'xiaoe-unified',
         credentialSourceStep: input.credentialSource.credentialSourceStep,
         credentialSourceType: input.credentialSource.credentialSourceType,
@@ -872,6 +1087,7 @@ async function saveXiaoEUnifiedLogin(input) {
             agentType: XIAOE_AGENT_TYPE,
             version: '',
             loginSource: 'xiaoe-unified',
+            ...(input.expiryTimes !== undefined ? { expiryTimes: input.expiryTimes } : {}),
             ...input.credentialSource,
         },
     };
@@ -884,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) {
@@ -905,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);
-            }
-            catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
-                options.logger?.warn('CLI-bundled xiaoe_env.py failed. ' + message);
+            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.');
             }
-            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'}`);
             }
         }
     }
@@ -931,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 {
@@ -940,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
@@ -956,30 +1201,52 @@ 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,
+            expiryTimes: credential.expiryTimes,
             tenantKeyFallback: options.tenantKeyFallback,
             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;
     }