@kzheart_/mc-pilot 0.4.0 → 0.4.1

package/dist/instance/ClientInstanceManager.d.ts

@@ -60,6 +60,8 @@ export declare class ClientInstanceManager {
         inWorld: boolean;
         position: unknown;
     }>;
+    private buildDiagnostics;
+    private formatDiagnostics;
     getClient(name?: string): Promise<ClientRuntimeEntry>;
     loadMeta(clientName: string): Promise<ClientInstanceMeta>;
     updateMeta(clientName: string, updates: Partial<ClientInstanceMeta>): Promise<ClientInstanceMeta>;

package/dist/instance/ClientInstanceManager.js

@@ -190,6 +190,7 @@ export class ClientInstanceManager {
         const requireWorld = options.requireWorld ?? true;
         // 阶段 A：等 WS 连通
         let connected = false;
+        let lastConnectError;
         while (Date.now() < deadline) {
             try {
                 const ws = new WebSocketClient(wsUrl);
@@ -197,12 +198,22 @@ export class ClientInstanceManager {
                 connected = true;
                 break;
             }
-            catch {
+            catch (err) {
+                lastConnectError = err instanceof Error ? err.message : String(err);
                 await new Promise((resolve) => setTimeout(resolve, 500));
             }
         }
         if (!connected) {
-            throw new MctError({ code: "TIMEOUT", message: `Timed out connecting to client ${clientName} on ${wsUrl}` }, 2);
+            const diag = this.buildDiagnostics(entry.pid, entry.wsPort, {
+                wsConnected: false,
+                inWorld: false,
+                lastError: lastConnectError
+            });
+            throw new MctError({
+                code: "TIMEOUT",
+                message: `Timed out after ${timeoutSeconds}s waiting for client ${clientName} (${wsUrl}). ${this.formatDiagnostics(diag)}`,
+                details: diag
+            }, 2);
         }
         if (!requireWorld) {
             return { connected: true, url: wsUrl };
@@ -221,16 +232,47 @@ export class ClientInstanceManager {
                     break;
                 }
             }
-            catch {
-                // 连接瞬断等偶发错误，继续轮询
+            catch (err) {
+                lastErrorCode = err instanceof Error ? `WS_ERROR(${err.message})` : "WS_ERROR";
             }
             await new Promise((resolve) => setTimeout(resolve, 500));
         }
+        const diag = this.buildDiagnostics(entry.pid, entry.wsPort, {
+            wsConnected: true,
+            inWorld: false,
+            lastError: lastErrorCode
+        });
         throw new MctError({
             code: "TIMEOUT",
-            message: `Client ${clientName} connected (${wsUrl}) but did not join a world (last status: ${lastErrorCode}). Tip: try \`mct client reconnect --address <server>\` or \`mct client launch --force\`.`
+            message: `Timed out after ${timeoutSeconds}s waiting for client ${clientName} to join a world (${wsUrl}). ${this.formatDiagnostics(diag)} Tip: try \`mct client reconnect --address <server>\` or \`mct client launch --force\`.`,
+            details: diag
         }, 2);
     }
+    buildDiagnostics(pid, wsPort, extras) {
+        const processAlive = isProcessRunning(pid);
+        const portListening = getListeningPids(wsPort).length > 0;
+        return {
+            pid,
+            processAlive,
+            wsPort,
+            portListening,
+            wsConnected: extras.wsConnected,
+            inWorld: extras.inWorld,
+            lastError: extras.lastError
+        };
+    }
+    formatDiagnostics(diag) {
+        const parts = [
+            `processAlive=${diag.processAlive}`,
+            `portListening=${diag.portListening}`,
+            `wsConnected=${diag.wsConnected}`,
+            `inWorld=${diag.inWorld}`
+        ];
+        if (diag.lastError) {
+            parts.push(`lastError=${diag.lastError}`);
+        }
+        return `Diagnostics: ${parts.join(", ")}.`;
+    }
     async getClient(name) {
         const state = await this.globalState.readClientState();
         const resolvedName = name ?? state.defaultClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kzheart_/mc-pilot",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Minecraft plugin/mod automated testing CLI – control a real Minecraft client to simulate player actions",
   "type": "module",
   "bin": {