aws-runtime-bridge 1.3.7 → 1.3.9

package/dist/adapter/ClaudeSdkAdapter.d.ts

@@ -92,6 +92,18 @@ export declare class ClaudeSdkAdapter extends EventEmitter implements BaseProvid
      * 支持 Windows / macOS / Linux
      */
     private findClaudeExecutable;
+    /**
+     * 从面板配置的命令行中提取实际可执行文件，避免把参数一起传给 PATH 查找。
+     */
+    private extractExecutableCommand;
+    /**
+     * 按当前 Bridge 进程的 PATH/PATHEXT 直接查找可执行文件，避免依赖 which/where 和 shell 解析。
+     */
+    private resolveExecutableFromPath;
+    private getWindowsPathExtensions;
+    private shouldUseDefaultClaudeFallbacks;
+    private isWindowsWrapperPath;
+    private resolveWindowsWrapper;
     /**
      * 从 wrapper 脚本解析 cli.js 路径
      */

package/dist/adapter/ClaudeSdkAdapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ClaudeSdkAdapter.d.ts","sourceRoot":"","sources":["../../src/adapter/ClaudeSdkAdapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ClaudeSdkAdapter.d.ts","sourceRoot":"","sources":["../../src/adapter/ClaudeSdkAdapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter/ClaudeSdkAdapter.js

@@ -9,11 +9,11 @@
  * - 支持 AskUserQuestion 拦截并转发到聊天面板
  * - 支持 turn_complete 事件精确判断 AI 就绪状态
  */
+import { execSync } from 'child_process';
 import { EventEmitter } from 'events';
-import { v4 as uuidv4 } from 'uuid';
 import * as fs from 'fs';
 import * as path from 'path';
-import { execSync } from 'child_process';
+import { v4 as uuidv4 } from 'uuid';
 import { getToolActionInfo } from './types.js';
 // ============ AsyncIterableQueue ============
 /**
@@ -574,13 +574,25 @@ export class ClaudeSdkAdapter extends EventEmitter {
      * 支持 Windows / macOS / Linux
      */
     findClaudeExecutable(command) {
-        const normalizedCommand = (command || 'claude').trim() || 'claude';
+        const normalizedCommand = this.extractExecutableCommand(command);
         // 1. 如果是绝对路径，直接返回
         if (path.isAbsolute(normalizedCommand) && fs.existsSync(normalizedCommand)) {
+            const resolvedWrapper = this.resolveWindowsWrapper(normalizedCommand);
+            if (resolvedWrapper) {
+                return resolvedWrapper;
+            }
+            if (this.isWindowsWrapperPath(normalizedCommand)) {
+                console.warn(`[ClaudeSdkAdapter] Skipping wrapper script for Claude Code executable: ${normalizedCommand}`);
+                return undefined;
+            }
             return normalizedCommand;
         }
-        // 2. Windows 特定路径（优先级高）
-        if (process.platform === 'win32') {
+        const pathExecutable = this.resolveExecutableFromPath(normalizedCommand);
+        if (pathExecutable) {
+            return pathExecutable;
+        }
+        // 2. Windows 特定路径（作为 claude 默认命令的兜底）
+        if (process.platform === 'win32' && this.shouldUseDefaultClaudeFallbacks(normalizedCommand)) {
             const userProfile = process.env.USERPROFILE || '';
             const localAppData = process.env.LOCALAPPDATA || '';
             const appData = process.env.APPDATA || '';
@@ -607,55 +619,111 @@ export class ClaudeSdkAdapter extends EventEmitter {
                 }
             }
         }
-        // 3. 使用 which/where 查找
-        try {
-            const findCmd = process.platform === 'win32' ? `where ${normalizedCommand}` : `which ${normalizedCommand}`;
-            const result = execSync(findCmd, { encoding: 'utf8', timeout: 5000 }).trim();
-            if (result) {
-                const foundPath = result.split(/\r?\n/)[0].trim();
-                if (fs.existsSync(foundPath)) {
-                    // 如果是 wrapper 脚本，尝试找到实际的 cli.js
-                    if (foundPath.endsWith('.cmd') || foundPath.endsWith('.ps1')) {
-                        const cliJs = this.resolveCliJsFromWrapper(foundPath);
-                        if (cliJs)
-                            return cliJs;
-                    }
-                    return foundPath;
-                }
-            }
-        }
-        catch {
-            // 忽略查找失败
-        }
-        // 4. macOS/Linux 特定路径
+        // 3. macOS/Linux 特定路径（作为 claude 默认命令的兜底）
         const home = process.env.HOME || '';
         const candidates = [
+            path.join(home, '.local', 'bin', 'claude'),
+            path.join(home, '.npm-global', 'bin', 'claude'),
+            path.join(home, '.local', 'share', 'mise', 'shims', 'claude'),
+            path.join(home, '.asdf', 'shims', 'claude'),
+            `/opt/homebrew/bin/claude`,
+            `/usr/local/bin/claude`,
+            `/usr/bin/claude`,
             `/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js`,
             `/usr/lib/node_modules/@anthropic-ai/claude-code/cli.js`,
             path.join(home, '.local', 'share', 'volta', 'tools', 'shared', '@anthropic-ai', 'claude-code', 'cli.js'),
             path.join(home, '.volta', 'tools', 'shared', '@anthropic-ai', 'claude-code', 'cli.js'),
         ];
-        for (const p of candidates) {
-            if (p && fs.existsSync(p)) {
-                console.log(`[ClaudeSdkAdapter] Found Claude Code CLI: ${p}`);
-                return p;
+        if (this.shouldUseDefaultClaudeFallbacks(normalizedCommand)) {
+            for (const p of candidates) {
+                if (p && fs.existsSync(p)) {
+                    console.log(`[ClaudeSdkAdapter] Found Claude Code CLI: ${p}`);
+                    return p;
+                }
             }
         }
-        // 5. 尝试 npm root -g
-        try {
-            const npmRoot = execSync('npm root -g', { encoding: 'utf8', timeout: 5000 }).trim();
-            const cliJs = path.join(npmRoot, '@anthropic-ai', 'claude-code', 'cli.js');
-            if (fs.existsSync(cliJs)) {
-                console.log(`[ClaudeSdkAdapter] Found Claude Code CLI via npm root: ${cliJs}`);
-                return cliJs;
+        // 4. 尝试 npm root -g
+        if (this.shouldUseDefaultClaudeFallbacks(normalizedCommand)) {
+            try {
+                const npmRoot = execSync('npm root -g', { encoding: 'utf8', timeout: 5000 }).trim();
+                const cliJs = path.join(npmRoot, '@anthropic-ai', 'claude-code', 'cli.js');
+                if (fs.existsSync(cliJs)) {
+                    console.log(`[ClaudeSdkAdapter] Found Claude Code CLI via npm root: ${cliJs}`);
+                    return cliJs;
+                }
+            }
+            catch {
+                // 忽略
             }
-        }
-        catch {
-            // 忽略
         }
         console.warn(`[ClaudeSdkAdapter] Claude Code executable not found for command: ${normalizedCommand}`);
         return undefined;
     }
+    /**
+     * 从面板配置的命令行中提取实际可执行文件，避免把参数一起传给 PATH 查找。
+     */
+    extractExecutableCommand(command) {
+        const input = (command || 'claude').trim() || 'claude';
+        const firstToken = input.match(/^\s*(?:"([^"]+)"|'([^']+)'|(\S+))/);
+        return firstToken?.[1] || firstToken?.[2] || firstToken?.[3] || 'claude';
+    }
+    /**
+     * 按当前 Bridge 进程的 PATH/PATHEXT 直接查找可执行文件，避免依赖 which/where 和 shell 解析。
+     */
+    resolveExecutableFromPath(command) {
+        const pathValue = process.env.PATH || '';
+        if (!pathValue) {
+            return undefined;
+        }
+        const commandHasExtension = path.extname(command).length > 0;
+        const extensions = process.platform === 'win32'
+            ? this.getWindowsPathExtensions(commandHasExtension)
+            : [''];
+        for (const directory of pathValue.split(path.delimiter)) {
+            if (!directory) {
+                continue;
+            }
+            for (const extension of extensions) {
+                const candidate = path.join(directory, `${command}${extension}`);
+                if (!fs.existsSync(candidate)) {
+                    continue;
+                }
+                if (this.isWindowsWrapperPath(candidate)) {
+                    const resolvedWrapper = this.resolveWindowsWrapper(candidate);
+                    if (resolvedWrapper) {
+                        return resolvedWrapper;
+                    }
+                    continue;
+                }
+                console.log(`[ClaudeSdkAdapter] Found Claude Code CLI via PATH: ${candidate}`);
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+    getWindowsPathExtensions(commandHasExtension) {
+        if (commandHasExtension) {
+            return [''];
+        }
+        const pathExt = process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM;.PS1';
+        return pathExt
+            .split(';')
+            .map((extension) => extension.trim())
+            .filter((extension) => extension.length > 0);
+    }
+    shouldUseDefaultClaudeFallbacks(command) {
+        return ['claude', 'claude-code', 'claudecode'].includes(command.toLowerCase());
+    }
+    isWindowsWrapperPath(filePath) {
+        const extension = path.extname(filePath).toLowerCase();
+        return ['.cmd', '.bat', '.ps1'].includes(extension);
+    }
+    resolveWindowsWrapper(wrapperPath) {
+        if (!this.isWindowsWrapperPath(wrapperPath)) {
+            return undefined;
+        }
+        return this.resolveCliJsFromWrapper(wrapperPath);
+    }
     /**
      * 从 wrapper 脚本解析 cli.js 路径
      */
@@ -669,6 +737,11 @@ export class ClaudeSdkAdapter extends EventEmitter {
                     return voltaShared;
                 }
             }
+            const wrapperDirectory = path.dirname(wrapperPath);
+            const npmCliJs = path.join(wrapperDirectory, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+            if (fs.existsSync(npmCliJs)) {
+                return npmCliJs;
+            }
         }
         catch {
             // 忽略
@@ -1063,7 +1136,7 @@ export class ClaudeSdkAdapter extends EventEmitter {
                         toolInput = JSON.parse(jsonStr);
                         console.log(`[ClaudeSdkAdapter] Parsed tool input:`, JSON.stringify(toolInput).slice(0, 200));
                     }
-                    catch (e) {
+                    catch {
                         console.warn(`[ClaudeSdkAdapter] Failed to parse tool input JSON:`, jsonStr.slice(0, 100));
                     }
                 }

package/dist/adapter/ClaudeSdkAdapter.test.js

@@ -1,3 +1,6 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { ClaudeSdkAdapter } from './ClaudeSdkAdapter.js';
 describe('ClaudeSdkAdapter', () => {
@@ -5,6 +8,149 @@ describe('ClaudeSdkAdapter', () => {
         vi.useRealTimers();
         vi.restoreAllMocks();
     });
+    it('resolves claude from PATH without shelling out to which or where', () => {
+        const adapter = new ClaudeSdkAdapter();
+        const originalPath = process.env.PATH;
+        const originalPathExt = process.env.PATHEXT;
+        const commandDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-path-'));
+        const commandPath = path.join(commandDirectory, process.platform === 'win32' ? 'claude.EXE' : 'claude');
+        fs.writeFileSync(commandPath, '#!/usr/bin/env node\n');
+        if (process.platform !== 'win32') {
+            fs.chmodSync(commandPath, 0o755);
+        }
+        process.env.PATH = commandDirectory;
+        process.env.PATHEXT = '.EXE;.CMD';
+        try {
+            const result = adapter.findClaudeExecutable('claude');
+            expect(result).toBe(commandPath);
+        }
+        finally {
+            process.env.PATH = originalPath;
+            process.env.PATHEXT = originalPathExt;
+            fs.rmSync(commandDirectory, { recursive: true, force: true });
+        }
+    });
+    it('extracts the executable before resolving commands that include flags', () => {
+        const adapter = new ClaudeSdkAdapter();
+        const originalPath = process.env.PATH;
+        const originalPathExt = process.env.PATHEXT;
+        const commandDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-flags-'));
+        const commandPath = path.join(commandDirectory, process.platform === 'win32' ? 'claude.EXE' : 'claude');
+        const unexpectedCommandWithFlags = path.join(commandDirectory, process.platform === 'win32' ? 'claude --model sonnet.EXE' : 'claude --model sonnet');
+        fs.writeFileSync(commandPath, '#!/usr/bin/env node\n');
+        if (process.platform !== 'win32') {
+            fs.chmodSync(commandPath, 0o755);
+        }
+        process.env.PATH = commandDirectory;
+        process.env.PATHEXT = '.EXE;.CMD';
+        try {
+            const result = adapter.findClaudeExecutable('claude --model sonnet');
+            expect(result).toBe(commandPath);
+            expect(fs.existsSync(unexpectedCommandWithFlags)).toBe(false);
+        }
+        finally {
+            process.env.PATH = originalPath;
+            process.env.PATHEXT = originalPathExt;
+            fs.rmSync(commandDirectory, { recursive: true, force: true });
+        }
+    });
+    it.skipIf(process.platform !== 'win32')('resolves uppercase Windows wrapper extensions before returning PATH candidate', () => {
+        const adapter = new ClaudeSdkAdapter();
+        const originalPath = process.env.PATH;
+        const originalPathExt = process.env.PATHEXT;
+        const originalLocalAppData = process.env.LOCALAPPDATA;
+        const commandDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-wrapper-'));
+        const localAppDataDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-localappdata-'));
+        const wrapperPath = path.join(commandDirectory, 'claude.CMD');
+        const cliPath = path.join(localAppDataDirectory, 'Volta', 'tools', 'shared', '@anthropic-ai', 'claude-code', 'cli.js');
+        fs.mkdirSync(path.dirname(cliPath), { recursive: true });
+        fs.writeFileSync(wrapperPath, 'volta run %~n0 %*\n');
+        fs.writeFileSync(cliPath, '#!/usr/bin/env node\n');
+        process.env.PATH = commandDirectory;
+        process.env.PATHEXT = '.EXE;.CMD;.PS1';
+        process.env.LOCALAPPDATA = localAppDataDirectory;
+        try {
+            const result = adapter.findClaudeExecutable('claude');
+            expect(result).toBe(cliPath);
+        }
+        finally {
+            process.env.PATH = originalPath;
+            process.env.PATHEXT = originalPathExt;
+            process.env.LOCALAPPDATA = originalLocalAppData;
+            fs.rmSync(commandDirectory, { recursive: true, force: true });
+            fs.rmSync(localAppDataDirectory, { recursive: true, force: true });
+        }
+    });
+    it.skipIf(process.platform !== 'win32')('resolves npm command wrappers to the Claude Code cli.js file', () => {
+        const adapter = new ClaudeSdkAdapter();
+        const originalPath = process.env.PATH;
+        const originalPathExt = process.env.PATHEXT;
+        const commandDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-npm-wrapper-'));
+        const wrapperPath = path.join(commandDirectory, process.platform === 'win32' ? 'claude.CMD' : 'claude.ps1');
+        const cliPath = path.join(commandDirectory, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+        fs.mkdirSync(path.dirname(cliPath), { recursive: true });
+        fs.writeFileSync(wrapperPath, '@ECHO off\nnode "%~dp0\\node_modules\\@anthropic-ai\\claude-code\\cli.js" %*\n');
+        fs.writeFileSync(cliPath, '#!/usr/bin/env node\n');
+        process.env.PATH = commandDirectory;
+        process.env.PATHEXT = '.EXE;.CMD;.PS1';
+        try {
+            const result = adapter.findClaudeExecutable('claude');
+            expect(result).toBe(cliPath);
+        }
+        finally {
+            process.env.PATH = originalPath;
+            process.env.PATHEXT = originalPathExt;
+            fs.rmSync(commandDirectory, { recursive: true, force: true });
+        }
+    });
+    it('skips unresolved command wrappers instead of returning them to the SDK', () => {
+        const adapter = new ClaudeSdkAdapter();
+        const originalPath = process.env.PATH;
+        const originalPathExt = process.env.PATHEXT;
+        const commandDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-unresolved-wrapper-'));
+        const wrapperPath = path.join(commandDirectory, 'claude.CMD');
+        fs.writeFileSync(wrapperPath, '@ECHO off\nnode missing-cli.js %*\n');
+        process.env.PATH = commandDirectory;
+        process.env.PATHEXT = '.EXE;.CMD;.PS1';
+        try {
+            const result = adapter.findClaudeExecutable('claude');
+            expect(result).not.toBe(wrapperPath);
+        }
+        finally {
+            process.env.PATH = originalPath;
+            process.env.PATHEXT = originalPathExt;
+            fs.rmSync(commandDirectory, { recursive: true, force: true });
+        }
+    });
+    it('resolves absolute npm command wrappers before passing them to the SDK', () => {
+        const adapter = new ClaudeSdkAdapter();
+        const commandDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-absolute-wrapper-'));
+        const wrapperPath = path.join(commandDirectory, 'claude.cmd');
+        const cliPath = path.join(commandDirectory, 'node_modules', '@anthropic-ai', 'claude-code', 'cli.js');
+        fs.mkdirSync(path.dirname(cliPath), { recursive: true });
+        fs.writeFileSync(wrapperPath, '@ECHO off\nnode "%~dp0\\node_modules\\@anthropic-ai\\claude-code\\cli.js" %*\n');
+        fs.writeFileSync(cliPath, '#!/usr/bin/env node\n');
+        try {
+            const result = adapter.findClaudeExecutable(wrapperPath);
+            expect(result).toBe(cliPath);
+        }
+        finally {
+            fs.rmSync(commandDirectory, { recursive: true, force: true });
+        }
+    });
+    it('does not pass unresolved absolute wrapper scripts to the SDK', () => {
+        const adapter = new ClaudeSdkAdapter();
+        const commandDirectory = fs.mkdtempSync(path.join(os.tmpdir(), 'claude-absolute-unresolved-wrapper-'));
+        const wrapperPath = path.join(commandDirectory, 'claude.bat');
+        fs.writeFileSync(wrapperPath, '@ECHO off\nnode missing-cli.js %*\n');
+        try {
+            const result = adapter.findClaudeExecutable(wrapperPath);
+            expect(result).toBeUndefined();
+        }
+        finally {
+            fs.rmSync(commandDirectory, { recursive: true, force: true });
+        }
+    });
     it('does not auto-wake Claude for my_task-style idle commands', async () => {
         vi.useFakeTimers();
         const adapter = new ClaudeSdkAdapter();

package/dist/routes/instance.d.ts

@@ -10,4 +10,17 @@ export declare function buildConnectionCheckResponse(connectionKeyMd5: string):
         error?: string;
     };
 };
+export interface SchedulerPingFailureResponse {
+    ok: false;
+    error: string;
+    failureStage: "scheduler_ping";
+    runtimeBridge: "healthy";
+    schedulerBaseUrl: string;
+    hint: string;
+}
+/**
+ * 构建调度中心 ping 失败响应。
+ * 主流程：保留底层错误与 scheduler 地址，同时明确 bridge 本身已连通、失败点在 bridge 回连调度中心。
+ */
+export declare function buildSchedulerPingFailureResponse(error: Error, configuredSchedulerBaseUrl: string): SchedulerPingFailureResponse;
 //# sourceMappingURL=instance.d.ts.map

package/dist/routes/instance.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/routes/instance.ts"],"names":[],"mappings":"AA6BA,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/D,IAAI,CAEN;AAED,eAAO,MAAM,cAAc,4CAAW,CAAC;AAyBvC,wBAAgB,4BAA4B,CAAC,gBAAgB,EAAE,MAAM,GAAG;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QACJ,EAAE,EAAE,OAAO,CAAC;QACZ,aAAa,CAAC,EAAE,SAAS,CAAC;QAC1B,oBAAoB,EAAE,OAAO,CAAC;QAC9B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAqCA"}
+{"version":3,"file":"instance.d.ts","sourceRoot":"","sources":["../../src/routes/instance.ts"],"names":[],"mappings":"AA6BA,wBAAgB,qBAAqB,CACnC,EAAE,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAC/D,IAAI,CAEN;AAED,eAAO,MAAM,cAAc,4CAAW,CAAC;AAyBvC,wBAAgB,4BAA4B,CAAC,gBAAgB,EAAE,MAAM,GAAG;IACtE,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE;QACJ,EAAE,EAAE,OAAO,CAAC;QACZ,aAAa,CAAC,EAAE,SAAS,CAAC;QAC1B,oBAAoB,EAAE,OAAO,CAAC;QAC9B,qBAAqB,EAAE,OAAO,CAAC;QAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH,CAqCA;AAED,MAAM,WAAW,4BAA4B;IAC3C,EAAE,EAAE,KAAK,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,gBAAgB,CAAC;IAC/B,aAAa,EAAE,SAAS,CAAC;IACzB,gBAAgB,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,KAAK,EACZ,0BAA0B,EAAE,MAAM,GACjC,4BAA4B,CAiB9B"}

package/dist/routes/instance.js

@@ -72,6 +72,25 @@ export function buildConnectionCheckResponse(connectionKeyMd5) {
         },
     };
 }
+/**
+ * 构建调度中心 ping 失败响应。
+ * 主流程：保留底层错误与 scheduler 地址，同时明确 bridge 本身已连通、失败点在 bridge 回连调度中心。
+ */
+export function buildSchedulerPingFailureResponse(error, configuredSchedulerBaseUrl) {
+    const trimmedSchedulerBaseUrl = configuredSchedulerBaseUrl.trim();
+    const schedulerUrl = trimmedSchedulerBaseUrl || "http://localhost:8080";
+    const isLocalhostScheduler = /^https?:\/\/(localhost|127\.0\.0\.1)(:\d+)?(?:\/|$)/i.test(schedulerUrl);
+    return {
+        ok: false,
+        error: error.message || "scheduler ping failed",
+        failureStage: "scheduler_ping",
+        runtimeBridge: "healthy",
+        schedulerBaseUrl: schedulerUrl,
+        hint: isLocalhostScheduler
+            ? "aws-runtime-bridge 已连通，但它回连调度中心失败。请在 bridge 启动环境中将 AWS_RUNTIME_SCHEDULER_BASE_URL 配置为该实例可访问的调度中心地址，例如 http://<server-host>:7380。"
+            : "aws-runtime-bridge 已连通，但它回连调度中心失败。请确认 AWS_RUNTIME_SCHEDULER_BASE_URL 指向的调度中心地址可从 bridge 机器访问，并且运行时访问令牌仍有效。",
+    };
+}
 instanceRouter.get("/healthz", (_req, res) => {
     res.json({
         ok: true,
@@ -100,11 +119,9 @@ instanceRouter.get("/ping", validateToken, async (_req, res) => {
     }
     catch (error) {
         const err = error;
-        res.status(502).json({
-            ok: false,
-            error: err?.message || "scheduler ping failed",
-            schedulerBaseUrl,
-        });
+        res
+            .status(502)
+            .json(buildSchedulerPingFailureResponse(err, schedulerBaseUrl));
     }
 });
 instanceRouter.post("/init-instance", validateToken, async (req, res) => {

package/dist/routes/instance.test.js

@@ -98,4 +98,25 @@ describe('instance route validation', () => {
             },
         });
     });
+    it('explains localhost scheduler ping failures with environment variable guidance', async () => {
+        const { buildSchedulerPingFailureResponse } = await import('./instance.js');
+        const response = buildSchedulerPingFailureResponse(new Error('connect ECONNREFUSED 127.0.0.1:8080'), 'http://localhost:8080');
+        expect(response).toEqual({
+            ok: false,
+            error: 'connect ECONNREFUSED 127.0.0.1:8080',
+            failureStage: 'scheduler_ping',
+            runtimeBridge: 'healthy',
+            schedulerBaseUrl: 'http://localhost:8080',
+            hint: expect.stringContaining('AWS_RUNTIME_SCHEDULER_BASE_URL'),
+        });
+        expect(response.hint).toContain('http://<server-host>:7380');
+    });
+    it('explains non-localhost scheduler ping failures as reachability or token issues', async () => {
+        const { buildSchedulerPingFailureResponse } = await import('./instance.js');
+        const response = buildSchedulerPingFailureResponse(new Error('Request failed with status code 401'), 'http://10.0.0.8:7380');
+        expect(response.schedulerBaseUrl).toBe('http://10.0.0.8:7380');
+        expect(response.failureStage).toBe('scheduler_ping');
+        expect(response.runtimeBridge).toBe('healthy');
+        expect(response.hint).toContain('运行时访问令牌仍有效');
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aws-runtime-bridge",
-  "version": "1.3.7",
+  "version": "1.3.9",
   "description": "AgentsWorkStudio runtime bridge service for machine-level agent runtime integration",
   "type": "module",
   "main": "dist/index.js",