@sstar/embedlink_agent 0.1.0

package/dist/firmware/burn_recover.js

@@ -0,0 +1,733 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { error, ErrorCodes } from '../core/errors.js';
+import { getBoardUartResourceManager } from '../board_uart/resource.js';
+import { getAgentLogger, LogLevel } from '../logger.js';
+const require = createRequire(import.meta.url);
+function tailUtf8(text, maxBytes) {
+    if (!text)
+        return { tail: '', truncated: false };
+    const buf = Buffer.from(text, 'utf8');
+    if (buf.length <= maxBytes) {
+        return { tail: text, truncated: false };
+    }
+    const slice = buf.subarray(buf.length - maxBytes);
+    return { tail: slice.toString('utf8'), truncated: true };
+}
+function buildCombinedLog(stdout, stderr) {
+    return stdout + (stderr ? `\n[STDERR]\n${stderr}` : '');
+}
+/**
+ * 清理FlashTool日志，仅移除ANSI颜色控制符等，保留所有原始内容和格式
+ */
+function cleanFlashToolLog(rawLog) {
+    if (!rawLog)
+        return '';
+    // 移除ANSI转义序列（颜色、光标控制等）
+    const ansiRegex = /\x1b\[[0-9;?]*[A-Za-z]/g;
+    let cleaned = rawLog.replace(ansiRegex, '');
+    // 移除其他常见的控制序列（但保留\t\n\r等格式控制符）
+    const controlRegex = /\x0f|\x1b[=>]|\x1b\(B|\x1b\)0/g;
+    cleaned = cleaned.replace(controlRegex, '');
+    return cleaned;
+}
+/**
+ * 解析和验证 Windows FlashTool 参数
+ * @param args 参数数组
+ * @param imagesRootAbs 镜像根目录绝对路径
+ * @returns 解析后的参数对象
+ */
+function parseAndValidateWindowsFlashToolArgs(args, imagesRootAbs) {
+    const params = {};
+    const errors = [];
+    // 检查必选参数
+    const hasSpinor = args.includes('-spinor');
+    const hasSpinand = args.includes('-spinand');
+    if (!hasSpinor && !hasSpinand) {
+        errors.push('缺少 Flash 类型参数：必须指定 -spinor 或 -spinand');
+    }
+    else if (hasSpinor && hasSpinand) {
+        errors.push('Flash 类型冲突：不能同时指定 -spinor 和 -spinand');
+    }
+    else {
+        params.flashType = hasSpinor ? 'spinor' : 'spinand';
+    }
+    // 解析起始地址
+    const startAddrIndex = args.findIndex((arg, index) => arg === '-s' && index + 1 < args.length);
+    if (startAddrIndex === -1) {
+        errors.push('缺少起始地址参数：必须使用 -s {hex_address} 指定烧录地址');
+    }
+    else {
+        const address = args[startAddrIndex + 1];
+        if (!isValidHexAddress(address)) {
+            errors.push(`无效的起始地址格式：${address}，必须是有效的十六进制地址（如 0x140000）`);
+        }
+        else {
+            params.startAddress = address;
+        }
+    }
+    // 解析文件路径
+    const fileIndex = args.findIndex((arg, index) => arg === '-f' && index + 1 < args.length);
+    if (fileIndex === -1) {
+        errors.push('缺少文件路径参数：必须使用 -f {file_path} 指定烧录文件');
+    }
+    else {
+        const filePath = args[fileIndex + 1];
+        params.filePath = filePath;
+    }
+    // 检查是否有 run 参数
+    params.run = args.includes('-run');
+    if (!params.run) {
+        errors.push('缺少执行标志：必须包含 -run 参数来执行烧录');
+    }
+    // 解析可选参数：校验标志
+    const verifyIndex = args.findIndex((arg, index) => arg === '-v' && index + 1 < args.length);
+    if (verifyIndex !== -1) {
+        const verifyValue = args[verifyIndex + 1];
+        if (verifyValue !== '0' && verifyValue !== '1') {
+            errors.push(`无效的校验标志：${verifyValue}，必须是 0（不校验）或 1（校验）`);
+        }
+        else {
+            params.verify = verifyValue === '0' ? 0 : 1;
+        }
+    }
+    // 解析可选参数：擦除类型
+    const eraseIndex = args.findIndex((arg, index) => arg === '-e' && index + 1 < args.length);
+    if (eraseIndex !== -1) {
+        const eraseValue = args[eraseIndex + 1];
+        if (eraseValue !== '0' && eraseValue !== '1') {
+            errors.push(`无效的擦除类型：${eraseValue}，必须是 0（擦除整个flash）或 1（仅擦除file area）`);
+        }
+        else {
+            params.eraseType = eraseValue === '0' ? 0 : 1;
+        }
+    }
+    // 如果有错误，抛出异常
+    if (errors.length > 0) {
+        const errorMessage = errors.join('; ');
+        throw error(ErrorCodes.EL_INVALID_PARAMS, `Windows FlashTool 参数验证失败：${errorMessage}`, {
+            details: { errors, params },
+        });
+    }
+    return params;
+}
+/**
+ * 验证十六进制地址格式
+ * @param address 地址字符串
+ * @returns 是否为有效的十六进制地址
+ */
+function isValidHexAddress(address) {
+    if (!address || typeof address !== 'string') {
+        return false;
+    }
+    // 支持格式：0x140000 或 140000
+    const hexPattern = /^(0x)?[0-9a-fA-F]+$/;
+    if (!hexPattern.test(address)) {
+        return false;
+    }
+    // 检查是否为合理的地址范围（不能太大）
+    const numericValue = parseInt(address.replace(/^0x/, ''), 16);
+    return numericValue >= 0 && numericValue <= 0xffffffff;
+}
+/**
+ * 解析和验证 Linux ISP Tool 参数
+ * @param args 参数数组
+ * @param imagesRootAbs 镜像根目录绝对路径
+ * @returns 解析后的参数对象
+ */
+function parseAndValidateLinuxIspArgs(args, imagesRootAbs) {
+    const params = {};
+    const errors = [];
+    // 解析Flash类型
+    const flashTypeIndex = args.findIndex((arg, index) => arg === '-t' && index + 1 < args.length);
+    if (flashTypeIndex !== -1) {
+        const flashTypeValue = args[flashTypeIndex + 1];
+        if (flashTypeValue === '0' || flashTypeValue === '1') {
+            params.flashType = flashTypeValue === '0' ? 0 : 1;
+        }
+        else {
+            errors.push(`无效的Flash类型：${flashTypeValue}，必须是 0（SPINOR）或 1（SPINAND）`);
+        }
+    }
+    // 解析Debug Board ID
+    const debugBoardIndex = args.findIndex((arg, index) => arg === '-i' && index + 1 < args.length);
+    if (debugBoardIndex !== -1) {
+        params.debugBoardId = args[debugBoardIndex + 1];
+    }
+    // 解析文件路径和地址对 (-a address, -p file)
+    const addressFilePairs = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '-a' && i + 1 < args.length) {
+            const address = args[i + 1];
+            if (!isValidHexAddress(address)) {
+                errors.push(`无效的地址格式：${address}，必须是有效的十六进制地址（如 0x140000）`);
+            }
+            else {
+                if (addressFilePairs.length === 0) {
+                    addressFilePairs.push({ address });
+                }
+                else {
+                    const lastPair = addressFilePairs[addressFilePairs.length - 1];
+                    if (!lastPair.address) {
+                        lastPair.address = address;
+                    }
+                    else {
+                        addressFilePairs.push({ address });
+                    }
+                }
+            }
+            i++; // 跳过地址值
+        }
+        else if (args[i] === '-p' && i + 1 < args.length) {
+            const file = args[i + 1];
+            if (addressFilePairs.length === 0) {
+                addressFilePairs.push({ file });
+            }
+            else {
+                const lastPair = addressFilePairs[addressFilePairs.length - 1];
+                if (!lastPair.file) {
+                    lastPair.file = file;
+                }
+                else {
+                    addressFilePairs.push({ file });
+                }
+            }
+            i++; // 跳过文件路径
+        }
+    }
+    // 检查是否有有效的地址文件对
+    if (addressFilePairs.length > 0) {
+        const firstValidPair = addressFilePairs.find((pair) => pair.address && pair.file);
+        if (firstValidPair) {
+            params.address = firstValidPair.address;
+            params.filePath = firstValidPair.file;
+        }
+    }
+    // 解析可选参数：擦除模式
+    const eraseModeIndex = args.findIndex((arg, index) => arg === '-e' && index + 1 < args.length);
+    if (eraseModeIndex !== -1) {
+        const eraseModeValue = args[eraseModeIndex + 1];
+        if (eraseModeValue === '0' || eraseModeValue === '1') {
+            params.eraseMode = eraseModeValue === '0' ? 0 : 1;
+        }
+        else {
+            errors.push(`无效的擦除模式：${eraseModeValue}，必须是 0（擦除指定地址）或 1（擦除全部）`);
+        }
+    }
+    // 解析可选参数：坏块检查
+    const badBlockIndex = args.findIndex((arg, index) => arg === '-b' && index + 1 < args.length);
+    if (badBlockIndex !== -1) {
+        const badBlockValue = args[badBlockIndex + 1];
+        if (badBlockValue === '1' || badBlockValue.toLowerCase() === 'true') {
+            params.badBlockCheck = true;
+        }
+    }
+    // 如果有错误，抛出异常
+    if (errors.length > 0) {
+        const errorMessage = errors.join('; ');
+        throw error(ErrorCodes.EL_INVALID_PARAMS, `Linux ISP Tool 参数验证失败：${errorMessage}`, {
+            details: { errors, params },
+        });
+    }
+    return params;
+}
+/**
+ * 验证 Windows FlashTool 参数并检查文件存在性
+ * @param args 参数数组
+ * @param imagesRootAbs 镜像根目录绝对路径
+ * @returns 验证结果对象
+ */
+async function validateWindowsFlashToolParams(args, imagesRootAbs) {
+    // 检查是否看起来像 Windows FlashTool 参数
+    const hasFlashTypeFlags = args.some((arg) => arg === '-spinor' || arg === '-spinand');
+    const hasWindowsSpecificFlags = args.some((arg) => ['-run', '-s', '-f', '-v', '-e'].includes(arg));
+    // 如果不是 Windows FlashTool 参数，跳过检查
+    if (!hasFlashTypeFlags && !hasWindowsSpecificFlags) {
+        return { isValid: true };
+    }
+    try {
+        // 解析和验证参数
+        const params = parseAndValidateWindowsFlashToolArgs(args, imagesRootAbs);
+        // 检查文件存在性
+        if (params.filePath) {
+            let fullPath;
+            // 如果是绝对路径，直接使用
+            if (path.isAbsolute(params.filePath)) {
+                fullPath = params.filePath;
+            }
+            else {
+                // 相对路径需要与 imagesRootAbs 组合
+                fullPath = path.join(imagesRootAbs, params.filePath);
+            }
+            try {
+                const fileStat = await fs.stat(fullPath);
+                if (!fileStat.isFile()) {
+                    return {
+                        isValid: false,
+                        errorMessage: `FlashTool 文件路径不是常规文件：${params.filePath}`,
+                        details: { parsedPath: fullPath, args },
+                    };
+                }
+                // 检查文件大小是否合理（0 < size < 1GB）
+                if (fileStat.size === 0) {
+                    return {
+                        isValid: false,
+                        errorMessage: `FlashTool 文件为空：${params.filePath}`,
+                        details: { parsedPath: fullPath, fileSize: fileStat.size, args },
+                    };
+                }
+                const maxSize = 1024 * 1024 * 1024; // 1GB
+                if (fileStat.size > maxSize) {
+                    return {
+                        isValid: false,
+                        errorMessage: `FlashTool 文件过大：${params.filePath} (${fileStat.size} bytes > ${maxSize} bytes)`,
+                        details: { parsedPath: fullPath, fileSize: fileStat.size, maxSize, args },
+                    };
+                }
+            }
+            catch (e) {
+                if (e.code === 'ENOENT') {
+                    return {
+                        isValid: false,
+                        errorMessage: `FlashTool 文件不存在：${params.filePath}`,
+                        details: { parsedPath: fullPath, args, originalError: e.message },
+                    };
+                }
+                if (e.code === 'EACCES') {
+                    return {
+                        isValid: false,
+                        errorMessage: `FlashTool 文件无访问权限：${params.filePath}`,
+                        details: { parsedPath: fullPath, args, originalError: e.message },
+                    };
+                }
+                // 其他文件系统错误
+                return {
+                    isValid: false,
+                    errorMessage: `FlashTool 文件检查失败：${params.filePath} (${e.code || 'UNKNOWN'}: ${e.message || String(e)})`,
+                    details: { parsedPath: fullPath, args, originalError: e.message, errorCode: e.code },
+                };
+            }
+        }
+        return { isValid: true, details: { parsedParams: params } };
+    }
+    catch (e) {
+        // 参数解析或格式验证失败
+        return {
+            isValid: false,
+            errorMessage: e.message || 'Windows FlashTool 参数验证失败',
+            details: { args, originalError: e },
+        };
+    }
+}
+/**
+ * 验证 Linux ISP Tool 参数并检查文件存在性
+ * @param args 参数数组
+ * @param imagesRootAbs 镜像根目录绝对路径
+ * @returns 验证结果对象
+ */
+async function validateLinuxIspParams(args, imagesRootAbs) {
+    // 检查是否看起来像 Linux ISP Tool 参数
+    const hasLinuxFlags = args.some((arg) => ['-t', '-i', '-a', '-p', '-e', '-b'].includes(arg));
+    // 如果不是 Linux ISP Tool 参数，跳过检查
+    if (!hasLinuxFlags) {
+        return { isValid: true };
+    }
+    try {
+        // 解析和验证参数
+        const params = parseAndValidateLinuxIspArgs(args, imagesRootAbs);
+        // 检查文件存在性（Linux ISP Tool 可以同时有多个文件，检查所有）
+        const filesToCheck = [];
+        // 收集所有 -p 参数指定的文件
+        for (let i = 0; i < args.length; i++) {
+            if (args[i] === '-p' && i + 1 < args.length) {
+                filesToCheck.push(args[i + 1]);
+                i++; // 跳过文件路径
+            }
+        }
+        // 检查所有文件
+        for (const filePath of filesToCheck) {
+            let fullPath;
+            // 如果是绝对路径，直接使用
+            if (path.isAbsolute(filePath)) {
+                fullPath = filePath;
+            }
+            else {
+                // 相对路径需要与 imagesRootAbs 组合
+                fullPath = path.join(imagesRootAbs, filePath);
+            }
+            try {
+                const fileStat = await fs.stat(fullPath);
+                if (!fileStat.isFile()) {
+                    return {
+                        isValid: false,
+                        errorMessage: `Linux ISP Tool 文件路径不是常规文件：${filePath}`,
+                        details: { parsedPath: fullPath, args, allFiles: filesToCheck },
+                    };
+                }
+                // 检查文件大小是否合理（0 < size < 1GB）
+                if (fileStat.size === 0) {
+                    return {
+                        isValid: false,
+                        errorMessage: `Linux ISP Tool 文件为空：${filePath}`,
+                        details: {
+                            parsedPath: fullPath,
+                            fileSize: fileStat.size,
+                            args,
+                            allFiles: filesToCheck,
+                        },
+                    };
+                }
+                const maxSize = 1024 * 1024 * 1024; // 1GB
+                if (fileStat.size > maxSize) {
+                    return {
+                        isValid: false,
+                        errorMessage: `Linux ISP Tool 文件过大：${filePath} (${fileStat.size} bytes > ${maxSize} bytes)`,
+                        details: {
+                            parsedPath: fullPath,
+                            fileSize: fileStat.size,
+                            maxSize,
+                            args,
+                            allFiles: filesToCheck,
+                        },
+                    };
+                }
+            }
+            catch (e) {
+                if (e.code === 'ENOENT') {
+                    return {
+                        isValid: false,
+                        errorMessage: `Linux ISP Tool 文件不存在：${filePath}`,
+                        details: {
+                            parsedPath: fullPath,
+                            args,
+                            allFiles: filesToCheck,
+                            originalError: e.message,
+                        },
+                    };
+                }
+                if (e.code === 'EACCES') {
+                    return {
+                        isValid: false,
+                        errorMessage: `Linux ISP Tool 文件无访问权限：${filePath}`,
+                        details: {
+                            parsedPath: fullPath,
+                            args,
+                            allFiles: filesToCheck,
+                            originalError: e.message,
+                        },
+                    };
+                }
+                // 其他文件系统错误
+                return {
+                    isValid: false,
+                    errorMessage: `Linux ISP Tool 文件检查失败：${filePath} (${e.code || 'UNKNOWN'}: ${e.message || String(e)})`,
+                    details: {
+                        parsedPath: fullPath,
+                        args,
+                        allFiles: filesToCheck,
+                        originalError: e.message,
+                        errorCode: e.code,
+                    },
+                };
+            }
+        }
+        return { isValid: true, details: { parsedParams: params, checkedFiles: filesToCheck } };
+    }
+    catch (e) {
+        // 参数解析或格式验证失败
+        return {
+            isValid: false,
+            errorMessage: e.message || 'Linux ISP Tool 参数验证失败',
+            details: { args, originalError: e },
+        };
+    }
+}
+export async function firmwareBurnRecover(params) {
+    try {
+        const { cfg } = params;
+        const imagesRoot = params.imagesRoot && params.imagesRoot.length > 0 ? params.imagesRoot : 'images_agent';
+        const imagesRootAbs = path.join(cfg.tftp.dir, imagesRoot);
+        let st;
+        try {
+            st = await fs.stat(imagesRootAbs);
+        }
+        catch (e) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: imagesRoot directory not found: ${imagesRootAbs}`, { cause: e });
+        }
+        if (!st.isDirectory()) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: imagesRoot must be a directory, got ${imagesRootAbs}`);
+        }
+        const rawArgs = Array.isArray(params.args) ? params.args.slice() : [];
+        if (!rawArgs.length) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, 'firmware.burn_recover: args must be a non-empty string array');
+        }
+        // 将 AI 传来的参数视为 POSIX 风格，尽量转换为本平台可用形式，并做简单的文件存在性检查
+        const normalizedArgs = [];
+        for (const arg of rawArgs) {
+            if (typeof arg !== 'string') {
+                throw error(ErrorCodes.EL_INVALID_PARAMS, 'firmware.burn_recover: every arg must be a string');
+            }
+            // 保留原字符串，但将内部的 / 替换为当前平台的分隔符，便于本地工具识别
+            const converted = path.sep === '/' ? arg : arg.replace(/\//g, path.sep).replace(/\\/g, path.sep);
+            normalizedArgs.push(converted);
+        }
+        // ISP Tool 参数验证 - 先尝试 Linux ISP Tool，再尝试 Windows FlashTool
+        let validationResult = await validateLinuxIspParams(normalizedArgs, imagesRootAbs);
+        if (validationResult.isValid) {
+            // 如果 Linux 验证通过，不再尝试 Windows 验证
+        }
+        else {
+            // 如果不是 Linux ISP Tool 参数，尝试 Windows FlashTool 验证
+            validationResult = await validateWindowsFlashToolParams(normalizedArgs, imagesRootAbs);
+        }
+        if (!validationResult.isValid) {
+            // 返回验证失败的结果给AI，而不是抛出异常
+            return {
+                ok: false,
+                exitCode: -1,
+                details: `参数验证失败: ${validationResult.errorMessage}`,
+                logTail: validationResult.errorMessage || '参数验证失败',
+            };
+        }
+        // 尝试对"看起来像相对路径"的参数做存在性检查（不以 - 开头且不含 :）
+        for (const arg of rawArgs) {
+            if (!arg || arg.startsWith('-') || arg.includes(':'))
+                continue;
+            // 将传入的 POSIX 风格路径归一化后再组合工作目录
+            const relPosix = arg.replace(/\\/g, '/');
+            const candidate = path.join(imagesRootAbs, relPosix);
+            try {
+                const s = await fs.stat(candidate);
+                if (!s.isFile()) {
+                    // 不是 regular file 就当作普通参数忽略
+                    // eslint-disable-next-line no-continue
+                    continue;
+                }
+            }
+            catch {
+                // 不强制当作错误，避免误伤类似 boardId/serial 等值
+                // 将缺失信息留给 FlashTool 工具自身报错
+            }
+        }
+        // NOTE: 串口资源释放与挂起机制在 board_uart.resource 中统一处理；
+        // 这里仅专注于调用 FlashTool 工具并收集日志。
+        const timeoutMs = typeof params.timeoutMs === 'number' && params.timeoutMs > 0
+            ? params.timeoutMs
+            : cfg.timeouts.flash.write;
+        const ispExe = (cfg.firmware?.flashtool?.binaryPath || '').trim();
+        if (!ispExe) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, 'firmware.burn_recover: FlashTool未配置。请在Agent配置文件中设置 firmware.flashtool.binaryPath');
+        }
+        // 检查文件是否存在
+        try {
+            const stExe = await fs.stat(ispExe);
+            const isFile = typeof stExe.isFile === 'function' ? stExe.isFile() : !stExe.isDirectory();
+            if (!isFile) {
+                // 区分文件不存在和路径指向目录的情况
+                if (stExe.isDirectory()) {
+                    throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool路径指向目录而非可执行文件: ${ispExe}`);
+                }
+                else {
+                    throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool不是常规文件: ${ispExe}`);
+                }
+            }
+            // 检查文件权限
+            const hasExecutePermission = (stExe.mode & 0o111) !== 0;
+            const hasReadPermission = (stExe.mode & 0o444) !== 0;
+            if (!hasReadPermission) {
+                throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool文件无读取权限: ${ispExe} (当前权限: ${(stExe.mode & 0o777).toString(8)})`);
+            }
+            if (!hasExecutePermission && process.platform !== 'win32') {
+                throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool文件无执行权限: ${ispExe} (当前权限: ${(stExe.mode & 0o777).toString(8)}, 运行: chmod +x "${ispExe}")`);
+            }
+        }
+        catch (e) {
+            if (e && e.code === ErrorCodes.EL_INVALID_PARAMS) {
+                throw e; // 重新抛出我们自己的结构化错误
+            }
+            if (e.code === 'ENOENT') {
+                throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool文件不存在: ${ispExe}`);
+            }
+            if (e.code === 'EACCES') {
+                throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool文件权限不足: ${ispExe} (请检查文件读取和执行权限)`);
+            }
+            if (e.code === 'EPERM') {
+                throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool文件访问被拒绝: ${ispExe} (可能需要管理员权限)`);
+            }
+            // 其他文件系统错误
+            throw error(ErrorCodes.EL_INVALID_PARAMS, `firmware.burn_recover: FlashTool文件检查失败: ${ispExe} (${e.code || 'UNKNOWN'}: ${e.message || String(e)})`);
+        }
+        const logger = getAgentLogger();
+        const mgr = getBoardUartResourceManager();
+        let exitCode = -1;
+        let log = '';
+        try {
+            await mgr.suspendForFirmware(timeoutMs + 30000);
+            logger.write(LogLevel.INFO, 'firmware.burn_recover.start', {
+                imagesRoot,
+                exe: ispExe,
+                args: normalizedArgs,
+                timeoutMs,
+            });
+            const { exitCode: ec, stdout: out, stderr: err, } = await new Promise((resolve) => {
+                const spawnWithPipes = () => {
+                    const child = spawn(ispExe, normalizedArgs, {
+                        cwd: imagesRootAbs,
+                        stdio: ['ignore', 'pipe', 'pipe'],
+                    });
+                    let stdout = '';
+                    let stderr = '';
+                    child.stdout?.on('data', (buf) => {
+                        stdout += buf.toString('utf8');
+                    });
+                    child.stderr?.on('data', (buf) => {
+                        stderr += buf.toString('utf8');
+                    });
+                    let finished = false;
+                    const effectiveTimeout = timeoutMs > 0 ? timeoutMs : 0;
+                    const timer = effectiveTimeout > 0
+                        ? setTimeout(() => {
+                            if (finished)
+                                return;
+                            finished = true;
+                            child.kill('SIGKILL');
+                            resolve({ exitCode: -1, stdout: `${stdout}\n[FlashTool TIMEOUT]\n`, stderr });
+                        }, effectiveTimeout)
+                        : null;
+                    child.on('error', (e) => {
+                        if (finished)
+                            return;
+                        finished = true;
+                        if (timer)
+                            clearTimeout(timer);
+                        const msg = e?.message || String(e);
+                        resolve({ exitCode: -1, stdout: `${stdout}\n[FlashTool ERROR] ${msg}\n`, stderr });
+                    });
+                    child.on('close', (code) => {
+                        if (finished)
+                            return;
+                        finished = true;
+                        if (timer)
+                            clearTimeout(timer);
+                        const exit = typeof code === 'number' ? code : -1;
+                        resolve({ exitCode: exit, stdout, stderr });
+                    });
+                };
+                // Windows 下某些 FlashTool 工具会直接写 Console（绕过 stdout/stderr pipe），
+                // 因此必须使用 ConPTY 捕获控制台输出。
+                // 约束：@homebridge/node-pty-prebuilt-multiarch 在 Windows 下是必需依赖；不可用时必须显式失败，避免 stdout/stderr 为空误导上层。
+                if (process.platform === 'win32') {
+                    try {
+                        // 使用 require 来避免 TypeScript 编译时的模块解析错误
+                        const nodePty = require('@homebridge/node-pty-prebuilt-multiarch');
+                        const ptySpawn = nodePty?.spawn;
+                        if (typeof ptySpawn !== 'function') {
+                            resolve({
+                                exitCode: -1,
+                                stdout: '',
+                                stderr: '[FlashTool ERROR] @homebridge/node-pty-prebuilt-multiarch.spawn is not available (required for Windows console capture)',
+                            });
+                            return;
+                        }
+                        let stdout = '';
+                        const stderr = '';
+                        const term = ptySpawn(ispExe, normalizedArgs, {
+                            cwd: imagesRootAbs,
+                            name: 'xterm-256color',
+                            cols: 120,
+                            rows: 40,
+                            env: process.env,
+                            encoding: 'utf8',
+                            useConpty: true,
+                        });
+                        let finished = false;
+                        const effectiveTimeout = timeoutMs > 0 ? timeoutMs : 0;
+                        const timer = effectiveTimeout > 0
+                            ? setTimeout(() => {
+                                if (finished)
+                                    return;
+                                finished = true;
+                                try {
+                                    term.kill();
+                                }
+                                catch {
+                                    // ignore
+                                }
+                                resolve({
+                                    exitCode: -1,
+                                    stdout: `${stdout}\n[FlashTool TIMEOUT]\n`,
+                                    stderr,
+                                });
+                            }, effectiveTimeout)
+                            : null;
+                        term.onData((data) => {
+                            stdout += data;
+                        });
+                        term.onExit(({ exitCode: code }) => {
+                            if (finished)
+                                return;
+                            finished = true;
+                            if (timer)
+                                clearTimeout(timer);
+                            const exit = typeof code === 'number' ? code : -1;
+                            resolve({ exitCode: exit, stdout, stderr });
+                        });
+                    }
+                    catch (e) {
+                        const msg = e?.message || String(e);
+                        resolve({
+                            exitCode: -1,
+                            stdout: '',
+                            stderr: `[FlashTool ERROR] @homebridge/node-pty-prebuilt-multiarch is required on Windows to capture FlashTool console output: ${msg}`,
+                        });
+                    }
+                    return;
+                }
+                spawnWithPipes();
+            });
+            exitCode = ec;
+            // stdout/stderr：为上层语义判定提供尽可能完整的证据；超大输出时截断
+            const outTail = tailUtf8(out, 8192);
+            const errTail = tailUtf8(err, 8192);
+            // logTail 只用于人类快速查看，不需要保存完整输出，避免额外内存膨胀
+            const combinedLog = buildCombinedLog(outTail.tail, errTail.tail);
+            // 清理日志，移除控制符和无关内容
+            log = cleanFlashToolLog(combinedLog);
+            logger.write(LogLevel.INFO, 'firmware.burn_recover.done', {
+                imagesRoot,
+                exe: ispExe,
+                args: normalizedArgs,
+                timeoutMs,
+                exitCode,
+            });
+        }
+        finally {
+            try {
+                await mgr.resumeFromFirmware();
+            }
+            catch {
+                // ignore resume errors here; 状态会通过 BoardUartStatus 反映
+            }
+        }
+        const { tail } = tailUtf8(log, 8192);
+        const ok = exitCode === 0;
+        return {
+            ok,
+            exitCode,
+            logTail: tail,
+            details: `FlashTool run over, you should check the log get ValidationResult.`,
+        };
+    }
+    catch (e) {
+        // 捕获所有异常，确保不会导致程序崩溃
+        const errorMessage = e?.message || String(e);
+        return {
+            ok: false,
+            exitCode: -1,
+            details: `烧录过程中发生异常: ${errorMessage}`,
+            logTail: `ERROR: ${errorMessage}`,
+        };
+    }
+}