@sstar/embedlink_agent 0.1.0

package/dist/server/grpc.js

@@ -0,0 +1,1069 @@
+import path from 'node:path';
+import fsSync from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { Server, ServerCredentials, loadPackageDefinition } from '@grpc/grpc-js';
+import { loadSync } from '@grpc/proto-loader';
+import { downloadFromExternalTftp, downloadFromTftp, listTftpEntries, uploadToExternalTftp, uploadToTftp, } from '../tftp/index.js';
+import { ubootBreak, ubootRunCommand } from '../uboot/index.js';
+import { ErrorCodes, error, DefaultTimeouts } from '../core/errors.js';
+import fs from 'node:fs/promises';
+import { gatherSshCandidates } from '../ssh/candidates.js';
+import { listBoardUartPorts } from '../board_uart/index.js';
+import { SshTunnel } from '../ssh/tunnel.js';
+import { readPasswordFromEnv, eraseSecret } from '../secrets/index.js';
+import { nfsDownload, nfsList, nfsUpload } from '../nfs/index.js';
+import { getNetworkInfo } from '../utils/network.js';
+import { getPlatformInfo } from '../utils/platform.js';
+import { loadBoardNotes } from '../board/notes.js';
+import { readDoc } from '../board/docs.js';
+import { closeSession, listBoardUartSessions, openManualSession, setDefaultBoardUartHint, } from '../board_uart/sessions.js';
+import { getBoardUartResourceManager } from '../board_uart/resource.js';
+import { firmwarePrepareImages } from '../firmware/prepare_images.js';
+import { firmwareBurnRecover } from '../firmware/burn_recover.js';
+import { getFirmwareUserGuideMarkdown } from '../firmware/user_guide.js';
+import { FilesManager } from '../files/files_manager.js';
+import { FileType } from '../files/types.js';
+import { getAgentLogger, LogLevel } from '../logger.js';
+import { markGrpcActivity } from '../core/activity.js';
+import { publishHostLog } from '../core/log_stream.js';
+const PROTO_FILE_TYPE_FILE = 1;
+const PROTO_FILE_TYPE_DIRECTORY = 2;
+const PROTO_FILE_TYPE_UNSPECIFIED = 0;
+const DEFAULT_CHUNK_SIZE = 64 * 1024;
+function getHostInstanceIdFromCall(call) {
+    try {
+        const md = call?.metadata;
+        const vals = md?.get?.('x-embedlink-host-instance-id');
+        const first = Array.isArray(vals) && vals.length > 0 ? vals[0] : undefined;
+        const raw = Buffer.isBuffer(first) ? first.toString('utf8') : String(first || '');
+        return raw.trim();
+    }
+    catch {
+        return '';
+    }
+}
+function normalizeProtoFileType(v) {
+    if (v === PROTO_FILE_TYPE_FILE || v === 'FILE_TYPE_FILE' || v === 'FILE') {
+        return PROTO_FILE_TYPE_FILE;
+    }
+    if (v === PROTO_FILE_TYPE_DIRECTORY || v === 'FILE_TYPE_DIRECTORY' || v === 'DIRECTORY') {
+        return PROTO_FILE_TYPE_DIRECTORY;
+    }
+    return PROTO_FILE_TYPE_UNSPECIFIED;
+}
+// 注意：移除了有害的端口清理功能
+// Agent现在会自动随机选择可用端口，不会干扰其他应用程序
+// 获取当前文件的目录路径（兼容ES模块）
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export async function startGrpcServer(cfg, identity) {
+    // 创建gRPC服务器，配置端口复用选项
+    const server = new Server({
+        // 启用端口复用，解决Agent异常退出后端口占用问题
+        'grpc.max_receive_message_length': -1, // 无限制消息大小
+        'grpc.max_send_message_length': -1, // 无限制消息大小
+    });
+    // 智能端口分配 - 如果默认端口被占用，尝试随机端口
+    const candidates = [
+        // 优先：构建输出目录中的 proto (dist/proto/agent.proto)
+        path.join(__dirname, '..', 'proto', 'agent.proto'),
+        // 尝试相对于当前文件的路径解析 (开发环境或旧模式)
+        path.join(__dirname, '..', '..', 'proto', 'agent.proto'),
+        path.join(process.cwd(), 'packages', 'proto', 'agent.proto'),
+        path.join(process.cwd(), 'proto', 'agent.proto'),
+        path.join(__dirname, '..', '..', '..', 'packages', 'proto', 'agent.proto'),
+    ];
+    const protoPath = candidates.find((p) => fsSync.existsSync(p)) || candidates[0];
+    const def = loadSync(protoPath, {
+        longs: String,
+        enums: String,
+        defaults: true,
+        oneofs: true,
+        keepCase: true,
+    });
+    const pkg = loadPackageDefinition(def);
+    const svc = pkg.embedlink.agent.v1.AgentService;
+    const pairingSvc = pkg.embedlink.agent.v1.PairingService;
+    const filesSvc = pkg.embedlink.agent.v1.FilesService;
+    // 提前告知板卡 UART 会话管理默认端口/波特率（可能在首次使用时才真正打开）
+    setDefaultBoardUartHint(cfg.boardUart.port, cfg.boardUart.baud ?? DefaultTimeouts.boardUart.write);
+    // 初始化 FilesManager
+    const agentLogger = getAgentLogger();
+    const filesManager = new FilesManager({
+        rootDir: cfg.files?.rootDir || './files',
+        maxFileSize: cfg.files?.maxFileSize,
+        allowedPaths: cfg.files?.allowedPaths,
+        maxTotalBytes: cfg.files?.maxTotalBytes,
+        maxTotalFiles: cfg.files?.maxTotalFiles,
+        skipHiddenByDefault: cfg.files?.skipHiddenByDefault,
+    }, agentLogger, cfg);
+    const streamFile = async (call, fullPath, relativePath, chunkSize, srcTypeProto, totalFiles, completedFiles, isLastFile) => new Promise((resolve, reject) => {
+        const readStream = fsSync.createReadStream(fullPath, { highWaterMark: chunkSize });
+        readStream.on('data', (chunk) => {
+            const buf = typeof chunk === 'string' ? Buffer.from(chunk) : chunk;
+            call.write({
+                src_type: srcTypeProto,
+                relative_path: relativePath,
+                content: buf,
+                is_file_complete: false,
+                is_directory_complete: false,
+                files_completed: completedFiles,
+                total_files: totalFiles,
+            });
+        });
+        readStream.on('end', () => {
+            const nextCompleted = completedFiles + 1;
+            call.write({
+                src_type: srcTypeProto,
+                relative_path: relativePath,
+                content: Buffer.alloc(0),
+                is_file_complete: true,
+                is_directory_complete: isLastFile,
+                files_completed: nextCompleted,
+                total_files: totalFiles,
+            });
+            resolve(nextCompleted);
+        });
+        readStream.on('error', (err) => reject(err));
+    });
+    let sshTunnel;
+    const sshPasswordSecret = readPasswordFromEnv();
+    server.addService(svc.service, {
+        Status: async (call, cb) => {
+            const shareUsername = (cfg.nfs?.username || identity.originUser || '').trim();
+            const sharePassword = cfg.nfs?.password || '';
+            const nfsExportPath = cfg.nfs?.exportName || '';
+            try {
+                markGrpcActivity();
+                const hostInstanceId = getHostInstanceIdFromCall(call);
+                if (hostInstanceId) {
+                    try {
+                        getBoardUartResourceManager().updateHostHeartbeat(hostInstanceId);
+                    }
+                    catch {
+                        // ignore heartbeat tracking errors
+                    }
+                }
+                const networkInfo = await getNetworkInfo();
+                const platformInfo = getPlatformInfo();
+                const preferredIp = (cfg.network?.preferredIp || '').trim();
+                const preferredInterface = (cfg.network?.preferredInterface || '').trim();
+                const preferredMatch = preferredIp && preferredInterface
+                    ? networkInfo.find((n) => n.ip === preferredIp && n.interface === preferredInterface)
+                    : undefined;
+                const reportedNetworkInfo = preferredMatch ? [preferredMatch] : [];
+                const reportError = preferredIp && preferredInterface
+                    ? preferredMatch
+                        ? undefined
+                        : `preferred network not available: interface=${preferredInterface}, ip=${preferredIp}`
+                    : 'preferred network not configured (set network.preferredInterface/preferredIp)';
+                cb(null, {
+                    status: 'ok',
+                    version: '0.1.0',
+                    timestamp: Date.now(),
+                    shareUsername,
+                    sharePassword,
+                    nfsExportPath,
+                    networkInterfaces: reportedNetworkInfo.map((info) => ({
+                        ip: info.ip,
+                        netmask: info.netmask,
+                        broadcast: info.broadcast || null,
+                        gateway: info.gateway || null,
+                        interface: info.interface,
+                        internal: info.internal,
+                    })),
+                    error: reportError,
+                    platform: platformInfo.platform,
+                    arch: platformInfo.arch,
+                });
+            }
+            catch (error) {
+                // 如果获取网络信息失败，返回基本状态和平台信息
+                const platformInfo = getPlatformInfo();
+                cb(null, {
+                    status: 'ok',
+                    version: '0.1.0',
+                    timestamp: Date.now(),
+                    shareUsername,
+                    sharePassword,
+                    nfsExportPath,
+                    networkInterfaces: [],
+                    error: 'Failed to get network info',
+                    platform: platformInfo.platform,
+                    arch: platformInfo.arch,
+                });
+            }
+        },
+        HostLogStream: (call, cb) => {
+            markGrpcActivity();
+            const hostInstanceId = getHostInstanceIdFromCall(call);
+            if (!hostInstanceId) {
+                cb(error(ErrorCodes.EL_INVALID_PARAMS, 'missing hostInstanceId (metadata: x-embedlink-host-instance-id)'));
+                return;
+            }
+            call.on('data', (msg) => {
+                try {
+                    markGrpcActivity();
+                    try {
+                        getBoardUartResourceManager().updateHostHeartbeat(hostInstanceId);
+                    }
+                    catch {
+                        // ignore
+                    }
+                    const tsRaw = msg?.ts;
+                    const ts = typeof tsRaw === 'number' ? tsRaw : Number(tsRaw || Date.now());
+                    const level = String(msg?.level || 'info');
+                    const event = String(msg?.event || 'host.log');
+                    const pidRaw = msg?.pid;
+                    const pid = typeof pidRaw === 'number' ? pidRaw : Number(pidRaw || 0);
+                    const dataJson = msg?.data_json ?? msg?.dataJson ?? '';
+                    let data = undefined;
+                    if (typeof dataJson === 'string' && dataJson) {
+                        try {
+                            data = JSON.parse(dataJson);
+                        }
+                        catch {
+                            data = { raw: dataJson };
+                        }
+                    }
+                    publishHostLog({ ts: Number.isFinite(ts) ? ts : Date.now(), level, event, data, pid, hostInstanceId });
+                }
+                catch {
+                    // best-effort
+                }
+            });
+            call.on('error', () => {
+                // ignore
+            });
+            call.on('end', () => {
+                cb(null, { accepted: true, reason: '' });
+            });
+        },
+        BoardUartWrite: async (call, cb) => {
+            try {
+                markGrpcActivity();
+                const { sessionId, data, mock, waitFor, timeoutMs } = call.request;
+                const hostInstanceId = getHostInstanceIdFromCall(call);
+                if (!hostInstanceId) {
+                    throw error(ErrorCodes.EL_INVALID_PARAMS, 'missing hostInstanceId (metadata: x-embedlink-host-instance-id)');
+                }
+                const mgr = getBoardUartResourceManager();
+                await mgr.touchHostIo({ hostInstanceId, sessionId });
+                const result = await mgr.writeCommand({
+                    command: data.toString(),
+                    sessionId,
+                    waitFor,
+                    timeoutMs,
+                });
+                cb(null, {
+                    status: result.status,
+                    output: result.output,
+                    nextStep: result.nextStep,
+                    elapsedMs: result.elapsedMs,
+                    lastOutputGapMs: result.lastOutputGapMs,
+                    remains: result.remains,
+                });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartListSessions: async (_call, cb) => {
+            try {
+                const sessions = await listBoardUartSessions();
+                cb(null, { sessions });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartSessionWrite: async (call, cb) => {
+            try {
+                markGrpcActivity();
+                const { sessionId, data } = call.request;
+                const mgrWrite = getBoardUartResourceManager();
+                const hostInstanceId = getHostInstanceIdFromCall(call);
+                if (!hostInstanceId) {
+                    throw error(ErrorCodes.EL_INVALID_PARAMS, 'missing hostInstanceId (metadata: x-embedlink-host-instance-id)');
+                }
+                await mgrWrite.touchHostIo({ hostInstanceId, sessionId });
+                const bytesWritten = await mgrWrite.write({
+                    sessionId,
+                    data: Buffer.from(data || Buffer.alloc(0)),
+                });
+                // 获取当前会话的缓冲区剩余数据量
+                // 对于 write 操作，我们无法直接获取缓冲区状态，设为 0
+                // 用户可以通过后续的 read 操作获取剩余数据
+                const remains = 0;
+                cb(null, { bytesWritten, remains });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartSessionRead: async (call, cb) => {
+            try {
+                markGrpcActivity();
+                const { sessionId, maxBytes, quietMs, timeoutMs } = call.request;
+                const mgrRead = getBoardUartResourceManager();
+                const hostInstanceId = getHostInstanceIdFromCall(call);
+                if (!hostInstanceId) {
+                    throw error(ErrorCodes.EL_INVALID_PARAMS, 'missing hostInstanceId (metadata: x-embedlink-host-instance-id)');
+                }
+                const r = await mgrRead.readForHost({
+                    hostInstanceId,
+                    sessionId,
+                    maxBytes,
+                    quietMs,
+                    timeoutMs,
+                });
+                cb(null, { data: r.data, bytes: r.bytes, timedOut: r.timedOut, remains: r.remains });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartOpenManual: async (call, cb) => {
+            try {
+                const { port, baud } = call.request;
+                const session = await openManualSession({ port, baud });
+                cb(null, { session });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartCloseSession: async (call, cb) => {
+            try {
+                const { sessionId } = call.request;
+                const closed = await closeSession(sessionId);
+                cb(null, { closed });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartStatus: async (_call, cb) => {
+            try {
+                markGrpcActivity();
+                const mgr = getBoardUartResourceManager();
+                const st = await mgr.getStatus();
+                cb(null, {
+                    status: st.status,
+                    disabled: st.disabled,
+                    hasModule: st.hasModule,
+                    port: st.port ?? '',
+                    baud: st.baud ?? 0,
+                    sessions: st.sessions,
+                    attachedTools: st.attachedTools.map((t) => ({
+                        id: t.id,
+                        source: t.source || '',
+                        sessionId: t.sessionId,
+                        port: t.port,
+                        baud: t.baud,
+                        attachedAtMs: t.attachedAt,
+                    })),
+                    suspended: st.suspended,
+                    suspendOwner: st.suspendOwner ?? '',
+                    suspendedSinceMs: st.suspendedSinceMs ?? 0,
+                    maxSuspendMs: st.maxSuspendMs ?? 0,
+                    autoResumed: st.autoResumed,
+                });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartForceClose: async (_call, cb) => {
+            try {
+                const mgr = getBoardUartResourceManager();
+                await mgr.forceCloseHardware();
+                cb(null, { ok: true });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        TftpUpload: async (call, cb) => {
+            try {
+                const { fileName, content } = call.request;
+                const mode = cfg.tftp.server?.mode || 'builtin';
+                const enabled = cfg.tftp.server?.enabled !== false && mode !== 'disabled';
+                if (!enabled) {
+                    throw error(ErrorCodes.EL_TFTP_DISABLED, 'TFTP is disabled');
+                }
+                const timeoutMs = cfg.timeouts?.tftp?.upload ?? DefaultTimeouts.tftp.upload;
+                if (mode === 'external') {
+                    const host = cfg.tftp.server?.externalHost;
+                    const port = cfg.tftp.server?.externalPort || 69;
+                    if (!host || !host.trim()) {
+                        throw error(ErrorCodes.EL_TFTP_UPLOAD_FAILED, 'external TFTP host is not configured');
+                    }
+                    const r = await Promise.race([
+                        uploadToExternalTftp(host, port, fileName, Buffer.from(content)),
+                        new Promise((_, reject) => setTimeout(() => reject(error(ErrorCodes.EL_TFTP_UPLOAD_FAILED, `tftp.upload timeout after ${timeoutMs} ms`)), timeoutMs)),
+                    ]);
+                    cb(null, { path: r.remoteSubpath, size: r.size, sha256: r.sha256 });
+                }
+                else {
+                    const r = await Promise.race([
+                        uploadToTftp(cfg.tftp.dir, fileName, Buffer.from(content)),
+                        new Promise((_, reject) => setTimeout(() => reject(error(ErrorCodes.EL_TFTP_UPLOAD_FAILED, `tftp.upload timeout after ${timeoutMs} ms`)), timeoutMs)),
+                    ]);
+                    cb(null, r);
+                }
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        TftpDownload: async (call, cb) => {
+            try {
+                const { path: relPath } = call.request;
+                const mode = cfg.tftp.server?.mode || 'builtin';
+                const enabled = cfg.tftp.server?.enabled !== false && mode !== 'disabled';
+                if (!enabled) {
+                    throw error(ErrorCodes.EL_TFTP_DISABLED, 'TFTP is disabled');
+                }
+                if (mode === 'external') {
+                    const host = cfg.tftp.server?.externalHost;
+                    const port = cfg.tftp.server?.externalPort || 69;
+                    if (!host || !host.trim()) {
+                        throw error(ErrorCodes.EL_TFTP_VERIFY_FAILED, 'external TFTP host is not configured');
+                    }
+                    const r = await downloadFromExternalTftp(host, port, relPath);
+                    cb(null, { content: r.content, size: r.size });
+                }
+                else {
+                    const r = await downloadFromTftp(cfg.tftp.dir, relPath);
+                    cb(null, { content: r.content, size: r.size });
+                }
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        TftpList: async (call, cb) => {
+            try {
+                const { basePath, depth } = call.request;
+                const d = typeof depth === 'number' && depth >= 0 ? depth : 1;
+                const r = await listTftpEntries(cfg.tftp.dir, basePath, d);
+                // 转换为新的 FileEntry 结构
+                const protoEntries = r.entries.map((entry) => ({
+                    name: entry.name,
+                    path: entry.path,
+                    type: entry.isDirectory ? 2 : 1, // FILE_TYPE_DIRECTORY = 2, FILE_TYPE_FILE = 1
+                    size: entry.sizeBytes,
+                    mtime: entry.modifiedAtMs,
+                }));
+                cb(null, { entries: protoEntries, truncated: r.truncated });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        TftpUserguide: async (_call, cb) => {
+            try {
+                const doc = await readDoc('tftp-transfer');
+                cb(null, { content: doc.content, format: doc.format });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        NfsUpload: async (call, cb) => {
+            try {
+                if (!cfg.nfs || !cfg.nfs.enabled || !cfg.nfs.localPath) {
+                    throw error(ErrorCodes.EL_NFS_DISABLED, 'NFS is not configured or disabled');
+                }
+                const { remoteSubpath, content } = call.request;
+                const r = await nfsUpload(cfg.nfs.localPath, remoteSubpath, Buffer.from(content || Buffer.alloc(0)));
+                cb(null, { remoteSubpath: r.remoteSubpath, size: r.size });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        NfsDownload: async (call, cb) => {
+            try {
+                if (!cfg.nfs || !cfg.nfs.enabled || !cfg.nfs.localPath) {
+                    throw error(ErrorCodes.EL_NFS_DISABLED, 'NFS is not configured or disabled');
+                }
+                const { remoteSubpath } = call.request;
+                const r = await nfsDownload(cfg.nfs.localPath, remoteSubpath);
+                cb(null, { content: r.content, size: r.size });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        NfsList: async (call, cb) => {
+            try {
+                if (!cfg.nfs || !cfg.nfs.enabled || !cfg.nfs.localPath) {
+                    throw error(ErrorCodes.EL_NFS_DISABLED, 'NFS is not configured or disabled');
+                }
+                const { remoteSubpath, mode, limit } = call.request;
+                const listMode = mode === 2 ? 'detailed' : 'simple'; // 2 = NFS_LIST_MODE_DETAILED
+                const r = await nfsList(cfg.nfs.localPath, remoteSubpath, listMode, limit);
+                // 转换为新的 FileEntry 结构
+                const protoEntries = r.entries.map((entry) => ({
+                    name: entry.name,
+                    path: entry.name, // NFS 没有相对路径概念，使用 name
+                    type: entry.isDirectory ? 2 : 1, // FILE_TYPE_DIRECTORY = 2, FILE_TYPE_FILE = 1
+                    size: listMode === 'detailed' ? entry.sizeBytes : 0,
+                    mtime: listMode === 'detailed' ? entry.modifiedAtMs : Date.now(),
+                }));
+                cb(null, { entries: protoEntries, truncated: r.truncated });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        NfsInfo: async (_call, cb) => {
+            try {
+                if (!cfg.nfs || !cfg.nfs.enabled || !cfg.nfs.localPath) {
+                    cb(null, { enabled: false, exportName: '', description: '' });
+                    return;
+                }
+                cb(null, {
+                    enabled: true,
+                    exportName: cfg.nfs.exportName,
+                    description: cfg.nfs.description || '',
+                });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        NfsUserguide: async (_call, cb) => {
+            try {
+                const doc = await readDoc('nfs-mount');
+                cb(null, { content: doc.content, format: doc.format });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardNotes: async (call, cb) => {
+            try {
+                const { board, section } = call.request;
+                const r = await loadBoardNotes(cfg, board, section);
+                cb(null, r);
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        UBootBreak: async (call, cb) => {
+            try {
+                const { sessionId, timeoutMs, mock } = call.request;
+                const r = await ubootBreak({
+                    sessionId,
+                    timeoutMs: timeoutMs || cfg.timeouts.uboot.break,
+                    mock: mock ?? cfg.boardUart.mock,
+                });
+                cb(null, r);
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        UBootRunCommand: async (call, cb) => {
+            try {
+                const { sessionId, command, timeoutMs, mock } = call.request;
+                const r = await ubootRunCommand({
+                    sessionId,
+                    command,
+                    timeoutMs: timeoutMs || cfg.timeouts.uboot.cmd,
+                    mock: mock ?? cfg.boardUart.mock,
+                });
+                cb(null, r);
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        FirmwarePrepareImages: async (call, cb) => {
+            try {
+                const { imagesRoot } = call.request;
+                const meta = await firmwarePrepareImages({
+                    cfg,
+                    imagesRoot,
+                });
+                cb(null, { meta }); // 只返回纯字符串
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        FirmwareBurnRecover: async (call, cb) => {
+            try {
+                const { imagesRoot, args, timeoutMs, force } = call.request;
+                const r = await firmwareBurnRecover({
+                    cfg,
+                    imagesRoot,
+                    args,
+                    timeoutMs,
+                    force,
+                });
+                cb(null, r);
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        FirmwareUserGuide: async (_call, cb) => {
+            try {
+                const json = await getFirmwareUserGuideMarkdown();
+                cb(null, { json });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        TunnelStart: async (call, cb) => {
+            try {
+                const { host, port, user, password, privateKeyPath, localPort, forwardHost, forwardPort } = call.request;
+                if (!host || !user) {
+                    throw error(ErrorCodes.EL_INVALID_PARAMS, 'missing host/user for TunnelStart');
+                }
+                const sshPort = port && port > 0 ? port : 22;
+                const bindPort = localPort && localPort > 0 ? localPort : 23745;
+                const dstPort = forwardPort && forwardPort > 0 ? forwardPort : cfg.grpc.port;
+                const dstHost = forwardHost || '127.0.0.1';
+                let privateKey;
+                if (privateKeyPath) {
+                    try {
+                        privateKey = await fs.readFile(privateKeyPath);
+                    }
+                    catch (e) {
+                        throw error(ErrorCodes.EL_SSH_CONNECT_FAILED, `failed to read private key: ${e?.message || String(e)}`);
+                    }
+                }
+                if (sshTunnel) {
+                    await sshTunnel.stop().catch(() => { });
+                }
+                sshTunnel = new SshTunnel();
+                await sshTunnel.start({
+                    host,
+                    port: Number(sshPort),
+                    user,
+                    password: password || sshPasswordSecret.value,
+                    privateKey,
+                    bindAddr: '127.0.0.1',
+                    bindPort: Number(bindPort),
+                    dstHost,
+                    dstPort: Number(dstPort),
+                });
+                cb(null, {
+                    connected: true,
+                    details: `ssh://${user}@${host} remote ${bindPort} -> ${dstHost}:${dstPort}`,
+                });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        TunnelStop: async (_call, cb) => {
+            try {
+                if (sshTunnel) {
+                    await sshTunnel.stop().catch(() => { });
+                    sshTunnel = undefined;
+                    // 任务结束后清理内存中的口令引用
+                    eraseSecret(sshPasswordSecret);
+                }
+                cb(null, { stopped: true });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        BoardUartListPorts: async (_call, cb) => {
+            try {
+                const ports = await listBoardUartPorts();
+                cb(null, { ports });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+        ListSshCandidates: async (_call, cb) => {
+            try {
+                const hosts = await gatherSshCandidates();
+                cb(null, { hosts });
+            }
+            catch (e) {
+                cb(e);
+            }
+        },
+    });
+    // Pairing service: simple pairCode-based identity check
+    server.addService(pairingSvc.service, {
+        PairCheck: (call, cb) => {
+            markGrpcActivity();
+            const req = call.request;
+            const ok = !!req.pairCode && req.pairCode === identity.pairCode;
+            if (ok) {
+                cb(null, {
+                    accepted: true,
+                    agentId: identity.id,
+                    version: identity.version,
+                    startupTime: identity.startupTime,
+                    reason: '',
+                });
+            }
+            else {
+                cb(null, {
+                    accepted: false,
+                    agentId: identity.id,
+                    version: identity.version,
+                    startupTime: identity.startupTime,
+                    reason: 'PAIR_CODE_MISMATCH',
+                });
+            }
+        },
+    });
+    // Files Service 注册
+    server.addService(filesSvc.service, {
+        PutPath: (call, cb) => {
+            const limits = filesManager.getLimits();
+            const writers = new Map();
+            let meta = null;
+            let requestId;
+            let filesWritten = 0;
+            let bytesWritten = 0;
+            const failedFiles = [];
+            let processing = Promise.resolve();
+            let finished = false;
+            const closeAll = async () => {
+                const closers = Array.from(writers.values()).map((w) => new Promise((resolve) => {
+                    w.stream.end(() => resolve());
+                }));
+                writers.clear();
+                await Promise.all(closers);
+            };
+            const handleError = async (err) => {
+                if (finished)
+                    return;
+                finished = true;
+                // 记录错误信息
+                if (requestId) {
+                    agentLogger.write(LogLevel.ERROR, 'grpc.put_path.error', {
+                        requestId,
+                        pathContext: meta?.pathContext,
+                        error: err?.message || String(err),
+                        stack: err?.stack,
+                    });
+                }
+                await closeAll().catch(() => { });
+                cb(err);
+                call.destroy(err);
+            };
+            const resolveUploadPath = (m, relativePath) => {
+                const base = m.src_type === PROTO_FILE_TYPE_DIRECTORY
+                    ? path.join(m.dst_path || '', relativePath)
+                    : m.dst_path && m.dst_path.trim()
+                        ? m.dst_path
+                        : relativePath;
+                return filesManager.resolvePath(base || relativePath);
+            };
+            const processChunk = async (chunk) => {
+                if (chunk.meta) {
+                    if (meta) {
+                        throw new Error('PutPath meta already received');
+                    }
+                    const srcType = normalizeProtoFileType(chunk.meta.src_type);
+                    const chunkRequestId = chunk.meta.requestId ||
+                        `files_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+                    requestId = chunkRequestId;
+                    meta = {
+                        src_type: srcType,
+                        dst_path: chunk.meta.dst_path,
+                        total_files: chunk.meta.total_files,
+                        total_bytes: chunk.meta.total_bytes,
+                        overwrite: chunk.meta.overwrite,
+                        requestId: chunkRequestId,
+                        pathContext: chunk.meta.pathContext,
+                    };
+                    // 记录接收到的路径上下���
+                    agentLogger.write(LogLevel.DEBUG, 'grpc.put_path.received', {
+                        requestId: chunkRequestId,
+                        pathContext: chunk.meta.pathContext,
+                        agentReceivedTargetPath: chunk.meta.dst_path,
+                        agentTimestamp: Date.now(),
+                        agentId: identity.id,
+                    });
+                    if (meta.src_type !== PROTO_FILE_TYPE_FILE &&
+                        meta.src_type !== PROTO_FILE_TYPE_DIRECTORY) {
+                        throw new Error('Invalid src_type for PutPath');
+                    }
+                    if (meta.dst_path && path.isAbsolute(meta.dst_path)) {
+                        throw new Error('dst_path must be relative to Agent files root');
+                    }
+                    if (meta.src_type === PROTO_FILE_TYPE_DIRECTORY && meta.dst_path) {
+                        const targetRoot = filesManager.resolvePath(meta.dst_path);
+                        if (fsSync.existsSync(targetRoot)) {
+                            const st = fsSync.statSync(targetRoot);
+                            if (st.isFile()) {
+                                throw new Error(`Type mismatch: destination '${meta.dst_path}' is a file, source is DIRECTORY`);
+                            }
+                        }
+                    }
+                    if (meta.total_files && limits.maxTotalFiles && meta.total_files > limits.maxTotalFiles) {
+                        throw new Error(`Total files ${meta.total_files} exceed limit ${limits.maxTotalFiles}`);
+                    }
+                    if (meta.total_bytes && limits.maxTotalBytes && meta.total_bytes > limits.maxTotalBytes) {
+                        throw new Error(`Total bytes ${meta.total_bytes} exceed limit ${limits.maxTotalBytes}`);
+                    }
+                    return;
+                }
+                if (!meta) {
+                    throw new Error('PutPath meta must be sent before data');
+                }
+                const data = chunk.data;
+                if (!data || !data.relative_path) {
+                    throw new Error('Missing data.relative_path');
+                }
+                if (path.isAbsolute(data.relative_path)) {
+                    throw new Error('relative_path must be relative (not absolute)');
+                }
+                const targetPath = resolveUploadPath(meta, data.relative_path);
+                const overwrite = meta.overwrite !== false;
+                let writer = writers.get(data.relative_path);
+                if (!writer) {
+                    if (fsSync.existsSync(targetPath)) {
+                        const st = fsSync.statSync(targetPath);
+                        if (st.isDirectory()) {
+                            failedFiles.push(data.relative_path);
+                            throw new Error(`Type mismatch: destination '${data.relative_path}' is a directory, source is FILE`);
+                        }
+                        if (!overwrite) {
+                            throw new Error(`Target exists and overwrite=false: ${data.relative_path}`);
+                        }
+                    }
+                    await filesManager.ensureDirectory(path.dirname(targetPath));
+                    writer = {
+                        stream: fsSync.createWriteStream(targetPath, { flags: 'w' }),
+                        bytes: 0,
+                        targetPath,
+                    };
+                    writers.set(data.relative_path, writer);
+                }
+                const buf = data.content ? Buffer.from(data.content) : Buffer.alloc(0);
+                if (buf.length > 0) {
+                    writer.stream.write(buf);
+                    writer.bytes += buf.length;
+                    bytesWritten += buf.length;
+                }
+                if (limits.maxFileSize && writer.bytes > limits.maxFileSize) {
+                    failedFiles.push(data.relative_path);
+                    throw new Error(`File ${data.relative_path} exceeds size limit ${limits.maxFileSize}`);
+                }
+                if (limits.maxTotalBytes && bytesWritten > limits.maxTotalBytes) {
+                    failedFiles.push(data.relative_path);
+                    throw new Error(`Total bytes ${bytesWritten} exceed limit ${limits.maxTotalBytes}`);
+                }
+                if (data.is_file_complete) {
+                    await new Promise((resolve, reject) => writer.stream.end((err) => err ? reject(err) : resolve()));
+                    writers.delete(data.relative_path);
+                    filesWritten += 1;
+                    if (limits.maxTotalFiles && filesWritten > limits.maxTotalFiles) {
+                        failedFiles.push(data.relative_path);
+                        throw new Error(`Files count ${filesWritten} exceed limit ${limits.maxTotalFiles}`);
+                    }
+                }
+            };
+            call.on('data', (chunk) => {
+                processing = processing.then(() => processChunk(chunk)).catch(handleError);
+            });
+            call.on('error', handleError);
+            call.on('end', () => {
+                processing
+                    .then(async () => {
+                    if (finished)
+                        return;
+                    finished = true;
+                    await closeAll().catch(() => { });
+                    // 记录操作完成结果
+                    if (requestId) {
+                        agentLogger.write(LogLevel.DEBUG, 'grpc.put_path.completed', {
+                            requestId,
+                            result: {
+                                success: failedFiles.length === 0,
+                                filesProcessed: filesWritten,
+                                totalBytes: bytesWritten,
+                                failedFiles: failedFiles,
+                            },
+                        });
+                    }
+                    cb(null, {
+                        success: failedFiles.length === 0,
+                        files_written: filesWritten,
+                        bytes_written: bytesWritten,
+                        failed_files: failedFiles,
+                    });
+                })
+                    .catch(handleError);
+            });
+        },
+        GetPath: async (call) => {
+            const requestId = call.request.requestId ||
+                `files_get_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            try {
+                const req = call.request;
+                // 记录接收到的路径上下文
+                agentLogger.write(LogLevel.DEBUG, 'grpc.get_path.received', {
+                    requestId,
+                    pathContext: req.pathContext,
+                    agentReceivedSourcePath: req.src_path,
+                    agentTimestamp: Date.now(),
+                    agentId: identity.id,
+                });
+                const chunkSize = typeof req.chunk_size === 'number' && req.chunk_size > 0
+                    ? req.chunk_size
+                    : DEFAULT_CHUNK_SIZE;
+                const skipHidden = typeof req.skip_hidden === 'boolean' ? req.skip_hidden : cfg.files?.skipHiddenByDefault;
+                const stat = await filesManager.getStat(req.src_path);
+                const isDirectory = stat.isDirectory;
+                const srcTypeProto = isDirectory ? PROTO_FILE_TYPE_DIRECTORY : PROTO_FILE_TYPE_FILE;
+                if (!isDirectory) {
+                    const fullPath = filesManager.resolvePath(stat.path);
+                    const relativePath = path.basename(fullPath);
+                    await streamFile(call, fullPath, relativePath, chunkSize, srcTypeProto, 1, 0, true);
+                    call.end();
+                    return;
+                }
+                const entries = await filesManager.listDir(req.src_path, {
+                    recursive: req.recursive !== false,
+                    all: !skipHidden,
+                });
+                const fileEntries = entries.filter((e) => e.type === FileType.FILE);
+                const totalFiles = fileEntries.length;
+                let completedFiles = 0;
+                const baseDir = path.normalize(req.src_path);
+                for (const entry of fileEntries) {
+                    const fullPath = filesManager.resolvePath(entry.path);
+                    const relInDir = path.relative(baseDir, entry.path) || path.basename(entry.path);
+                    completedFiles = await streamFile(call, fullPath, relInDir, chunkSize, srcTypeProto, totalFiles, completedFiles, completedFiles + 1 === totalFiles);
+                }
+                // 记录操作完成
+                agentLogger.write(LogLevel.DEBUG, 'grpc.get_path.completed', {
+                    requestId,
+                    success: true,
+                });
+                call.end();
+            }
+            catch (error) {
+                // 记录错误信息
+                agentLogger.write(LogLevel.ERROR, 'grpc.get_path.error', {
+                    requestId,
+                    error: error?.message || String(error),
+                    stack: error?.stack,
+                });
+                call.destroy(error);
+            }
+        },
+        ListFiles: async (call, cb) => {
+            try {
+                const req = call.request;
+                const entries = await filesManager.listDir(req.path, {
+                    all: req.all,
+                    recursive: req.recursive,
+                    pattern: req.pattern,
+                });
+                cb(null, {
+                    entries: entries.map((entry) => ({
+                        name: entry.name,
+                        path: entry.path,
+                        type: entry.type === FileType.FILE ? PROTO_FILE_TYPE_FILE : PROTO_FILE_TYPE_DIRECTORY,
+                        size: entry.size,
+                        mtime: entry.mtime,
+                    })),
+                    total_entries: entries.length,
+                    truncated: false,
+                });
+            }
+            catch (error) {
+                cb(error);
+            }
+        },
+        RemoveFiles: async (call, cb) => {
+            try {
+                const req = call.request;
+                await filesManager.remove(req.path, req.recursive);
+                cb(null, {
+                    success: true,
+                    deleted_count: 1,
+                });
+            }
+            catch (error) {
+                cb(error);
+            }
+        },
+        MakeDirectory: async (call, cb) => {
+            try {
+                const req = call.request;
+                await filesManager.makeDir(req.path, req.parents);
+                cb(null, {
+                    success: true,
+                    path: req.path,
+                });
+            }
+            catch (error) {
+                cb(error);
+            }
+        },
+        GetStat: async (call, cb) => {
+            try {
+                const req = call.request;
+                const stat = await filesManager.getStat(req.path);
+                cb(null, {
+                    success: true,
+                    stat: {
+                        path: stat.path,
+                        name: stat.name,
+                        size: stat.size,
+                        is_file: stat.isFile,
+                        is_directory: stat.isDirectory,
+                        modified_at: stat.modifiedAt,
+                        permissions: stat.permissions,
+                    },
+                });
+            }
+            catch (error) {
+                cb(error);
+            }
+        },
+    });
+    // 智能端口绑定 - 尝试配置端口，如果被占用则随机选择
+    await new Promise((resolve, reject) => {
+        const credentials = ServerCredentials.createInsecure();
+        const tryBindPort = (port, isRandom = false) => {
+            server.bindAsync(`${cfg.grpc.host}:${port}`, credentials, (err) => {
+                if (err) {
+                    if (!isRandom) {
+                        // 配置的端口被占用，尝试随机端口
+                        console.log(`Port ${port} occupied, trying random port...`);
+                        const randomPort = Math.floor(Math.random() * 10000) + 50000; // 50000-59999
+                        setTimeout(() => tryBindPort(randomPort, true), 100);
+                    }
+                    else {
+                        // 随机端口也失败
+                        reject(error(ErrorCodes.EL_AGENT_UNAVAILABLE, String(err)));
+                    }
+                }
+                else {
+                    // 绑定成功
+                    if (isRandom) {
+                        console.log(`Using random port ${port}`);
+                        // 更新配置中的实际端口
+                        cfg.grpc.port = port;
+                    }
+                    resolve();
+                }
+            });
+        };
+        tryBindPort(cfg.grpc.port);
+    });
+    return server;
+}