@sstar/boardlinker_host 0.2.0

package/dist/index.js

@@ -0,0 +1,1514 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { createAgentClient } from './grpc.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getHostLogger, logHostDebug, LogLevel } from './logger.js';
+const DEBUG_ENABLED = process.env.BOARDLINKER_HOST_DEBUG === '1' || process.env.BOARDLINKER_DEBUG === '1';
+const HOST_INSTANCE_ID = `${os.hostname()}/${process.pid}`;
+function logDebug(...args) {
+    if (!DEBUG_ENABLED)
+        return;
+    // eslint-disable-next-line no-console
+    console.error('[boardlinker-host]', ...args);
+    // 同时写入文件日志
+    logHostDebug('debug', { args });
+}
+// 辅助函数：格式化字节大小
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 Bytes';
+    const k = 1024;
+    const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
+}
+function getLocalAgentConfigPath() {
+    const home = os.homedir();
+    return path.join(home, '.config', 'board_linker', 'agent.json');
+}
+function loadAgentDiscovery() {
+    const p = getLocalAgentConfigPath();
+    if (!fs.existsSync(p)) {
+        throw new Error(`BoardLinker agent.json not found at ${p} (please start boardlinker-agent on this machine first)`);
+    }
+    const raw = fs.readFileSync(p, 'utf8');
+    let j;
+    try {
+        j = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`Failed to parse agent.json at ${p}: ${e?.message || String(e)}`);
+    }
+    const host = j.endpoint?.grpc?.host || '127.0.0.1';
+    const port = j.endpoint?.grpc?.port || j.agent?.hostGrpcPort;
+    const pairCode = j.agent?.pairCode;
+    if (!port || !Number.isFinite(port)) {
+        throw new Error(`Invalid agent grpc port in agent.json at ${p}`);
+    }
+    if (!pairCode) {
+        throw new Error(`Missing pairCode in agent.json at ${p}`);
+    }
+    const tftpInfo = j.services?.tftp;
+    const tftpEnabled = tftpInfo ? tftpInfo.enabled !== false && tftpInfo.mode !== 'disabled' : true;
+    const explicit = process.env.BOARDLINKER_AGENT_ADDR;
+    const addr = (explicit && explicit.trim()) || `${host}:${port}`;
+    logDebug('loadAgentDiscovery', {
+        path: p,
+        addr,
+        agentId: j.agent?.id,
+        pairCode: pairCode.slice(0, 8) + '...',
+    });
+    return { addr, pairCode, id: j.agent?.id, tftpEnabled, tftpMode: tftpInfo?.mode };
+}
+function isNetworkError(err) {
+    const code = (err && err.code) || '';
+    const msg = (err && err.message) || '';
+    const s = String(msg || '').toLowerCase();
+    if (code === 'UNAVAILABLE' || code === 14)
+        return true;
+    if (code === 'ECONNREFUSED' || code === 'ECONNRESET' || code === 'ETIMEDOUT')
+        return true;
+    if (s.includes('connect') || s.includes('unavailable') || s.includes('deadline exceeded')) {
+        return true;
+    }
+    return false;
+}
+let agent;
+let agentAddr;
+let agentPairCode;
+let defaultBoardUartSessionId = null;
+let tftpEnabled = true;
+let hostLogCall = null;
+// 错误类型枚举
+var ConnectionErrorType;
+(function (ConnectionErrorType) {
+    ConnectionErrorType["UNAVAILABLE"] = "UNAVAILABLE";
+    ConnectionErrorType["ECONNREFUSED"] = "ECONNREFUSED";
+    ConnectionErrorType["ECONNRESET"] = "ECONNRESET";
+    ConnectionErrorType["ETIMEDOUT"] = "ETIMEDOUT";
+    ConnectionErrorType["DEADLINE_EXCEEDED"] = "DEADLINE_EXCEEDED";
+})(ConnectionErrorType || (ConnectionErrorType = {}));
+// 友好的提示信息映射
+const getFriendlyErrorMessage = (errorType, toolName, originalError) => {
+    // 如果Agent端提供了错误信息，直接透传
+    const agentMessage = originalError?.message || originalError?.details || '';
+    if (agentMessage) {
+        return agentMessage;
+    }
+    // 只有在完全没有Agent错误信息时，才使用通用的连接错误提示
+    switch (errorType) {
+        case ConnectionErrorType.UNAVAILABLE:
+            return `🔌 Agent连接不可用，需要检查agent侧状态`;
+        case ConnectionErrorType.ECONNREFUSED:
+            return `❌ 连接被拒绝，boardlinker-agent可能未启动或端口配置错误`;
+        case ConnectionErrorType.ETIMEDOUT:
+            return `⏰ 连接超时，网络可能不稳定或Agent响应过慢`;
+        case ConnectionErrorType.DEADLINE_EXCEEDED:
+            return `⏰ 请求超时，Agent响应时间过长`;
+        default:
+            return `🔧 网络连接问题 (${errorType})，请检查Agent服务状态`;
+    }
+};
+// 错误分类函数
+function classifyError(err, toolName) {
+    const code = err?.code;
+    const message = err?.message?.toLowerCase() || '';
+    const details = err?.details?.toLowerCase() || '';
+    // gRPC错误码14对应UNAVAILABLE
+    if (code === 14 || code === 'UNAVAILABLE')
+        return ConnectionErrorType.UNAVAILABLE;
+    if (code === 'ECONNREFUSED')
+        return ConnectionErrorType.ECONNREFUSED;
+    if (code === 'ECONNRESET')
+        return ConnectionErrorType.ECONNRESET;
+    if (code === 'ETIMEDOUT')
+        return ConnectionErrorType.ETIMEDOUT;
+    if (message.includes('deadline exceeded') || details.includes('deadline exceeded'))
+        return ConnectionErrorType.DEADLINE_EXCEEDED;
+    return ConnectionErrorType.UNAVAILABLE; // 默认类型
+}
+// 创建友好的错误对象
+function createFriendlyError(originalError, errorType, toolName) {
+    const friendlyMessage = getFriendlyErrorMessage(errorType, toolName, originalError);
+    // 创建简洁的友好错误
+    const friendlyError = new Error(friendlyMessage);
+    // 附加原始错误信息用于调试，但不显示给用户
+    friendlyError.code = originalError?.code;
+    friendlyError.type = errorType;
+    friendlyError.originalError = originalError;
+    friendlyError.isFriendlyError = true;
+    friendlyError.debugInfo =
+        originalError?.message || originalError?.details || String(originalError);
+    return friendlyError;
+}
+// Control Signal Parser Class
+class ControlSignalParser {
+    // 解析控制信号字符串
+    static parseSignal(input) {
+        const trimmed = input.trim();
+        // 检查是否为长按格式（包含冒号）
+        const colonIndex = trimmed.indexOf(':');
+        if (colonIndex > 0) {
+            const signalName = trimmed.substring(0, colonIndex);
+            const durationStr = trimmed.substring(colonIndex + 1);
+            const duration = this.parseDuration(durationStr);
+            if (isNaN(duration) || duration <= 0) {
+                throw new Error(`无效的持续时间: ${durationStr}`);
+            }
+            return {
+                type: 'hold',
+                signal: this.normalizeSignalName(signalName),
+                duration,
+            };
+        }
+        // 单次信号
+        return {
+            type: 'single',
+            signal: this.normalizeSignalName(trimmed),
+        };
+    }
+    // 将信号名称转换为大写进行匹配
+    static normalizeSignalName(name) {
+        // 处理Ctrl组合键的特殊格式
+        if (name.toLowerCase().startsWith('ctrl+')) {
+            const key = name.substring(5); // 移除 'ctrl+'
+            return 'CTRL+' + key.toUpperCase();
+        }
+        return name.toUpperCase();
+    }
+    // 解析持续时间字符串
+    static parseDuration(durationStr) {
+        const trimmed = durationStr.trim().toLowerCase();
+        // 检查单位后缀
+        if (trimmed.endsWith('s')) {
+            const seconds = parseFloat(trimmed.slice(0, -1));
+            return Math.round(seconds * 1000);
+        }
+        if (trimmed.endsWith('m')) {
+            const minutes = parseFloat(trimmed.slice(0, -1));
+            return Math.round(minutes * 60 * 1000);
+        }
+        // 默认为毫秒
+        const milliseconds = parseFloat(trimmed);
+        return Math.round(milliseconds);
+    }
+    // 将信号转换为字节数据
+    static signalToBytes(signal) {
+        const signalCode = this.SIGNAL_MAP[signal.signal];
+        if (signalCode === undefined) {
+            throw new Error(`不支持的控制信号: ${signal.signal}`);
+        }
+        return [Buffer.from([signalCode])];
+    }
+    // 验证信号名称是否有效
+    static isValidSignal(signalName) {
+        const normalized = this.normalizeSignalName(signalName);
+        return this.SIGNAL_MAP.hasOwnProperty(normalized);
+    }
+}
+// 标准控制信号映射（统一使用大写键名）
+ControlSignalParser.SIGNAL_MAP = {
+    'CTRL+C': 0x03,
+    'CTRL+Z': 0x1a,
+    'CTRL+D': 0x04,
+    HOME: 0x01,
+    END: 0x05,
+    UP: 0x1b5b41,
+    DOWN: 0x1b5b42,
+    LEFT: 0x1b5b44,
+    RIGHT: 0x1b5b43,
+    ESC: 0x1b,
+    TAB: 0x09,
+    BACKSPACE: 0x08,
+    DELETE: 0x7f,
+    ENTER: 0x0d,
+    SPACE: 0x20,
+};
+const PROCEDURES = [
+    // 板卡 UART 多会话与读写
+    {
+        name: 'board_uart-sessions',
+        description: 'List BoardUart (board-side UART) sessions managed by the agent.',
+        params: {},
+    },
+    {
+        name: 'board_uart-run_command',
+        description: 'Write command to BoardUart. ',
+        params: {
+            command: {
+                type: 'string',
+                description: 'Command string (auto-appends newline). Empty string means press ENTER.',
+            },
+            session_id: {
+                type: 'string',
+                optional: true,
+                description: 'Target session id; use default if omitted.',
+            },
+            wait_for: {
+                type: 'string',
+                optional: true,
+                description: 'String pattern to wait for (e.g. "#", ">"). Agent blocks until found.',
+            },
+            timeout_ms: {
+                type: 'number',
+                optional: true,
+                description: 'Max time to wait for pattern (default 5000ms).',
+            },
+        },
+    },
+    {
+        name: 'board_uart-send_signal',
+        description: 'Send control signals to a BoardUart session.',
+        params: {
+            signal: {
+                type: 'string',
+                description: 'Control signal to send, e.g., ENTER, Ctrl+C, ENTER:5000 for 5-second hold.',
+            },
+            session_id: {
+                type: 'string',
+                optional: true,
+                description: 'Target session id; use default if omitted.',
+            },
+            repeat: {
+                type: 'number',
+                optional: true,
+                description: 'Number of times to repeat the signal, default is 1.',
+            },
+        },
+    },
+    {
+        name: 'board_uart-read',
+        description: 'Read from a BoardUart session with quiet and timeout controls.',
+        params: {
+            session_id: {
+                type: 'string',
+                optional: true,
+                description: 'Target session id; use default if omitted.',
+            },
+            max_bytes: {
+                type: 'number',
+                optional: true,
+                description: 'Maximum bytes to read in this call.',
+            },
+            quiet_ms: {
+                type: 'number',
+                optional: true,
+                description: 'Stop when no new data arrives for this many milliseconds.',
+            },
+            timeout_ms: {
+                type: 'number',
+                optional: true,
+                description: 'Overall timeout in milliseconds.',
+            },
+        },
+    },
+    {
+        name: 'board_uart-status',
+        description: 'Inspect BoardUart hardware status and attached tools.You should use `docs-read(board-interaction)` to get the UART SOP.',
+        params: {},
+    },
+    {
+        name: 'files-put',
+        description: 'Upload file or directory to Agent (Host → Agent). `src` must be an absolute path; `dst` must be a path relative to the Agent files root.',
+        params: {
+            src: {
+                type: 'string',
+                description: 'Source file/directory path (must be absolute)',
+            },
+            dst: {
+                type: 'string',
+                description: 'Destination path (relative to Agent files root; default uses source name)',
+                optional: true,
+            },
+            chunk_size: {
+                type: 'number',
+                description: 'Chunk size (bytes, optional, default 65536)',
+                optional: true,
+            },
+            overwrite: {
+                type: 'number',
+                description: 'Whether to overwrite existing files: 1 for overwrite, 0 for not overwrite (default: overwrite)',
+                optional: true,
+            },
+        },
+    },
+    {
+        name: 'files-get',
+        description: 'Download file or directory from Agent (Agent → Host). `src` must be relative to the Agent files root; `dst` must be an absolute path on the host.',
+        params: {
+            src: {
+                type: 'string',
+                description: 'Agent-side file/directory path (relative to Agent files root)',
+            },
+            dst: {
+                type: 'string',
+                description: 'Absolute local save path',
+                optional: true,
+            },
+            chunk_size: {
+                type: 'number',
+                description: 'Chunk size (bytes, optional, default 65536)',
+                optional: true,
+            },
+            skip_hidden: {
+                type: 'number',
+                description: 'Whether to skip hidden files, 1 to skip, 0 not to skip (default: not skip)',
+                optional: true,
+            },
+        },
+    },
+    {
+        name: 'files-list',
+        description: 'List files/directories on Agent files root. `path` must be relative to Agent files root (empty for root).',
+        params: {
+            path: {
+                type: 'string',
+                description: 'Relative path on Agent (optional, defaults to root)',
+                optional: true,
+            },
+            recursive: {
+                type: 'number',
+                description: '1 to list recursively, 0 for non-recursive (default 0)',
+                optional: true,
+            },
+            all: {
+                type: 'number',
+                description: '1 to include hidden files, 0 to skip (default include)',
+                optional: true,
+            },
+            pattern: {
+                type: 'string',
+                description: 'Optional glob-like pattern filter',
+                optional: true,
+            },
+        },
+    },
+    {
+        name: 'files-stat',
+        description: 'Get stat of a path on Agent files root. `path` must be relative to Agent files root.',
+        params: {
+            path: {
+                type: 'string',
+                description: 'Relative path on Agent',
+            },
+        },
+    },
+    {
+        name: 'files-mkdir',
+        description: 'Create directory on Agent files root. `path` must be relative to Agent files root.',
+        params: {
+            path: {
+                type: 'string',
+                description: 'Relative directory path to create',
+            },
+            parents: {
+                type: 'number',
+                description: '1 to create parents recursively (default 0)',
+                optional: true,
+            },
+        },
+    },
+    {
+        name: 'files-rm',
+        description: 'Remove file or directory on Agent files root. `path` must be relative; recursive deletion only if explicitly set.',
+        params: {
+            path: {
+                type: 'string',
+                description: 'Relative path to remove',
+            },
+            recursive: {
+                type: 'number',
+                description: '1 to remove recursively (use with care), 0 to remove non-recursively',
+                optional: true,
+            },
+        },
+    },
+    {
+        name: 'firmware-prepare_images',
+        description: 'Prepare firmware images on the agent by uploading local images directory to the TFTP images_agent subdirectory and returning metadata.',
+        params: {
+            localImagesDir: {
+                type: 'string',
+                description: 'Local directory on the host that contains firmware images/bins and partition_layout configure file.',
+            },
+        },
+    },
+    {
+        name: 'firmware-burn_recover',
+        description: 'Invoke the agent FlashTool-based firmware recovery using explicit segments derived from images metadata.',
+        params: {
+            imagesRoot: {
+                type: 'string',
+                description: 'Relative images root under the agent TFTP directory, e.g. "images_agent"',
+            },
+            args: {
+                type: 'string',
+                description: 'JSON-encoded array of FlashTool CLI arguments. MUST use dosc-read to get the userguide',
+            },
+            timeout_ms: {
+                type: 'number',
+                optional: true,
+                description: 'Optional timeout in milliseconds for the ISP tool; if omitted the agent will apply its own default.',
+            },
+            force: {
+                type: 'string',
+                optional: true,
+                description: 'Optional flag to force recovery, encoded as string (e.g. "true" or "false").',
+            },
+        },
+    },
+    {
+        name: 'agent-status',
+        description: 'Get agent status, version, network interfaces, and share hints (shareUsername/sharePassword/nfsExportPath) for CIFS/NFS mounting.',
+        params: {},
+    },
+    {
+        name: 'docs-list',
+        description: 'List available documentation categories.',
+        params: {},
+    },
+    {
+        name: 'docs-read',
+        description: 'Read a specific documentation by its ID. IDs can be found via `core-docs-list`.',
+        params: {
+            id: {
+                type: 'string',
+                description: 'ID of the documentation to read.',
+            },
+            board: {
+                type: 'string',
+                optional: true,
+                description: 'Optional board model for board_notes doc.',
+            },
+            section: {
+                type: 'string',
+                optional: true,
+                description: 'Optional section for board_notes doc.',
+            },
+        },
+    },
+];
+function listProcedures() {
+    // TFTP/NFS related procedures are removed from here.
+    // The list should now accurately reflect only the exposed procedures.
+    return PROCEDURES;
+}
+function paramsToJsonSchema(params) {
+    const properties = {};
+    const required = [];
+    for (const [key, def] of Object.entries(params)) {
+        const type = def.type;
+        if (!def.optional)
+            required.push(key);
+        const schema = {};
+        if (type === 'number') {
+            schema.type = 'number';
+        }
+        else if (type === 'base64') {
+            schema.type = 'string';
+            schema.contentEncoding = 'base64';
+        }
+        else {
+            schema.type = 'string';
+        }
+        if (def.description)
+            schema.description = def.description;
+        properties[key] = schema;
+    }
+    return {
+        type: 'object',
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+function toMcpToolName(procName) {
+    // 如果已经是新格式（不包含点号），直接返回
+    if (!procName.includes('.')) {
+        return procName;
+    }
+    // OpenAI tools.name 只能使用字母、数字、下划线和中划线
+    const normalized = procName.split('.').join('-');
+    return normalized;
+}
+function fromMcpToolName(toolName) {
+    // 将连字符格式转换为点号格式，用于调用agent端
+    return toolName.split('-').join('.');
+}
+function normalizeBoardUartWriteText(text) {
+    const s = text ?? '';
+    if (!s.length) {
+        return '\r\n';
+    }
+    // 处理尾部转义字符的兼容性
+    const len = s.length;
+    // 处理 ...\\r\\n 的情况（需要至少4个字符：\ r \ n）
+    if (len >= 4 && s.slice(-4) === '\\r\\n') {
+        return s.slice(0, -4) + '\r\n';
+    }
+    // 处理 ...\\n 的情况（需要至少2个字符：\ n）
+    if (len >= 2 && s.slice(-2) === '\\n') {
+        return s.slice(0, -2) + '\n';
+    }
+    // 原有逻辑：如果尾部是 \n，直接返回
+    const last = s.charAt(s.length - 1);
+    if (last === '\n') {
+        return s;
+    }
+    // 否则在尾部添加 \r\n
+    return s + '\r\n';
+}
+// 预编译的正则表达式，提高性能
+const ANSI_ESCAPE_PATTERN = /\x1b(?:[@-Z\\-_]|[[0-?]*[ -/]*[@-~])/g;
+// 处理可能的ANSI转义序列变体（包括ESC字符被省略的情况）
+const ANSI_ESCAPE_VARIANT_PATTERN = /\[(?:[0-9;]*m|[0-9;]*[HJK]|[0-?]*[hl]|[@-Z\\-_])/g;
+/**
+ * 过滤控制字符（ASCII控制字符 + ANSI转义序列）
+ * 保留常用的格式化字符：TAB(\t), LF(\n), CR(\r)
+ * @param data 原始Buffer数据
+ * @returns 过滤后的UTF-8字符串
+ */
+export function filterAsciiControlChars(data) {
+    if (!Buffer.isBuffer(data) || data.length === 0) {
+        return '';
+    }
+    // 将Buffer转换为字符串
+    let text = data.toString('utf8');
+    // 1. 过滤ASCII控制字符（保持原有逻辑）
+    // 过滤范围：0x00-0x08, 0x0B-0x0C, 0x0E-0x1F, 0x7F
+    // 保留常用的格式化字符：TAB(\t), LF(\n), CR(\r)
+    text = text.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '');
+    // 2. 过滤所有ANSI转义序列
+    // 包括颜色控制、光标控制、屏幕清除等所有ANSI序列
+    // 先处理标准的ANSI转义序列（包含ESC字符）
+    text = text.replace(ANSI_ESCAPE_PATTERN, '');
+    // 3. 处理可能的ANSI转义序列变体（ESC字符被省略的情况）
+    // 这能解决类似 [0;0mcmdline[0m 中的颜色控制符问题
+    text = text.replace(ANSI_ESCAPE_VARIANT_PATTERN, '');
+    return text;
+}
+async function callProcedureInternal(name, params) {
+    async function withAgentRetry(stage, fn, toolName) {
+        let attempt = 0;
+        while (true) {
+            try {
+                if (attempt === 0) {
+                    logDebug('call', stage, 'using agent', agentAddr);
+                }
+                else {
+                    logDebug('retry', stage, 'attempt', attempt, 'agent', agentAddr);
+                }
+                return await fn(agent);
+            }
+            catch (err) {
+                const errorType = classifyError(err, toolName);
+                // 如果不是网络错误或重试次数超限，抛出友好的错误信息
+                if (!isNetworkError(err) || attempt >= 8) {
+                    throw createFriendlyError(err, errorType, toolName || stage);
+                }
+                attempt += 1;
+                // 第一次重试时给出用户提示
+                if (attempt === 1) {
+                    logDebug('connection issue detected, will retry', getFriendlyErrorMessage(errorType, toolName || stage, err));
+                }
+                // 简单重试延迟：每次重试等待1秒
+                await new Promise((resolve) => setTimeout(resolve, 1000));
+                try {
+                    const info = loadAgentDiscovery();
+                    agentAddr = info.addr;
+                    agentPairCode = info.pairCode;
+                    agent = createAgentClient(agentAddr, { hostInstanceId: HOST_INSTANCE_ID });
+                    const res = await agent.pairCheck({
+                        pairCode: agentPairCode,
+                        clientId: `boardlinker-host-retry-${stage}`,
+                        timeoutMs: 3000,
+                    });
+                    if (!res.accepted) {
+                        throw createFriendlyError(new Error(`PairCheck failed: ${res.reason || 'PAIR_CODE_MISMATCH'}`), ConnectionErrorType.UNAVAILABLE, toolName || stage);
+                    }
+                }
+                catch (pairErr) {
+                    // ���对失败也使用友好错误
+                    throw createFriendlyError(pairErr, classifyError(pairErr, toolName), toolName || stage);
+                }
+            }
+        }
+    }
+    // 持续信号发送逻辑
+    async function sendHoldSignal(signal, sessionId) {
+        const signalBytes = ControlSignalParser.signalToBytes(signal);
+        if (!signalBytes || signalBytes.length === 0) {
+            return;
+        }
+        const startTime = Date.now();
+        const duration = signal.duration;
+        // 以固定间隔持续发送信号字节
+        while (Date.now() - startTime < duration) {
+            await withAgentRetry('board_uart.send_signal', (cli) => cli.boardUartSessionWrite({
+                sessionId,
+                data: signalBytes[0],
+            }), 'board_uart-send_signal');
+            // 发送间隔，避免过于频繁
+            await new Promise((resolve) => setTimeout(resolve, 50)); // 50ms间隔
+        }
+    }
+    // 主信号发送函数
+    async function boardUartSendSignal(params) {
+        try {
+            // 验证必要参数
+            if (!params.signal || typeof params.signal !== 'string') {
+                return {
+                    ok: false,
+                    details: 'signal���数是必需的字符串',
+                    bytesSent: 0,
+                    remains: 0,
+                };
+            }
+            // 解析控制信号
+            const controlSignal = ControlSignalParser.parseSignal(params.signal);
+            controlSignal.repeat = params.repeat ?? 1;
+            // 验证信号是否有效
+            if (!ControlSignalParser.isValidSignal(controlSignal.signal)) {
+                return {
+                    ok: false,
+                    details: `不支持的控制信号: ${controlSignal.signal}`,
+                    bytesSent: 0,
+                    remains: 0,
+                };
+            }
+            // 获取会话ID
+            let sessionId = params.session_id;
+            if (!sessionId) {
+                if (!defaultBoardUartSessionId) {
+                    const s = await withAgentRetry('board_uart.sessions', (cli) => cli.boardUartListSessions(), 'board_uart-sessions');
+                    const def = s.sessions.find((it) => it.isDefault) || s.sessions[0];
+                    if (!def) {
+                        throw new Error('no board-uart session available for send_signal');
+                    }
+                    defaultBoardUartSessionId = def.id;
+                }
+                sessionId = defaultBoardUartSessionId || undefined;
+            }
+            // 转换为字节数据
+            const signalDataList = ControlSignalParser.signalToBytes(controlSignal);
+            let totalBytesSent = 0;
+            // 按重复次数发送
+            for (let i = 0; i < (controlSignal.repeat || 1); i++) {
+                for (const data of signalDataList) {
+                    const result = await withAgentRetry('board_uart.send_signal', (cli) => cli.boardUartSessionWrite({
+                        sessionId: sessionId,
+                        data: data,
+                    }), 'board_uart-send_signal');
+                    totalBytesSent += result.bytesWritten;
+                    // 如果是持续信号，需要按照持续时间发送
+                    if (controlSignal.type === 'hold' && controlSignal.duration) {
+                        await sendHoldSignal(controlSignal, sessionId);
+                    }
+                }
+            }
+            const logger = getHostLogger();
+            logger.write(LogLevel.INFO, 'control signal sent', {
+                signal: params.signal,
+                sessionId,
+                repeat: controlSignal.repeat,
+                totalBytesSent,
+            });
+            return {
+                ok: true,
+                bytesSent: totalBytesSent,
+                details: `成功发送信号: ${params.signal} (重复${controlSignal.repeat}次)`,
+                remains: 0, // 信号发送操作不会产生待读取数据
+            };
+        }
+        catch (error) {
+            const logger = getHostLogger();
+            logger.write(LogLevel.ERROR, '控制信号发送失败', {
+                signal: params.signal,
+                error: error?.message || String(error),
+            });
+            return {
+                ok: false,
+                bytesSent: 0,
+                details: `发送失败: ${error?.message || String(error)}`,
+                remains: 0, // 错误情况下，剩余数据设为0
+            };
+        }
+    }
+    if (name === 'files-put') {
+        const fs = await import('node:fs');
+        const fsp = await import('node:fs/promises');
+        const path = await import('node:path');
+        const localPath = params.src;
+        const remotePath = params.dst;
+        const chunkSize = typeof params.chunk_size === 'number' && params.chunk_size > 0
+            ? params.chunk_size
+            : 64 * 1024;
+        const overwrite = params.overwrite !== 0 && params.overwrite !== false;
+        if (!path.isAbsolute(localPath)) {
+            return "Parameter 'src' must be an absolute path. Please retry with an absolute src.";
+        }
+        if (remotePath && path.isAbsolute(remotePath)) {
+            return "Parameter 'dst' must be a relative path (relative to Agent files root). Please provide a relative dst.";
+        }
+        if (!fs.existsSync(localPath)) {
+            throw new Error(`本地路径不存在: ${localPath}`);
+        }
+        const stats = fs.lstatSync(localPath);
+        const collectFiles = async (root) => {
+            const entries = await fsp.readdir(root, { withFileTypes: true });
+            const result = [];
+            for (const entry of entries) {
+                const abs = path.join(root, entry.name);
+                const rel = path.relative(localPath, abs).replace(/\\/g, '/');
+                if (entry.isDirectory()) {
+                    const nested = await collectFiles(abs);
+                    result.push(...nested);
+                }
+                else if (entry.isFile()) {
+                    const st = await fsp.stat(abs);
+                    result.push({ relative: rel || entry.name, abs, size: st.size });
+                }
+            }
+            return result;
+        };
+        // 生成唯一请求ID
+        const requestId = `files_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        // 详细记录Host端路径信息
+        logHostDebug('files.put.start', {
+            requestId,
+            operation: 'put',
+            originalSourcePath: localPath, // Host端原始源路径（绝对路径）
+            originalTargetPath: remotePath, // Host端原始目标路径（相对路径）
+            overwrite: overwrite,
+            chunkSize: chunkSize,
+            hostWorkingDirectory: process.cwd(), // Host端工作目录
+            hostUser: process.env.USER, // Host端用户信息
+            timestamp: Date.now(),
+        });
+        const { call, response } = await withAgentRetry('files.putPath', (cli) => Promise.resolve(cli.filesPutPath()), 'files-put');
+        const sendMeta = (meta) => {
+            call.write({
+                meta: {
+                    ...meta,
+                    requestId: requestId,
+                    // 传递路径上下文信息给Agent端
+                    pathContext: {
+                        hostOriginalSourcePath: localPath,
+                        hostOriginalTargetPath: remotePath,
+                        hostTimestamp: Date.now(),
+                        hostUser: process.env.USER,
+                    },
+                },
+            });
+        };
+        const sendFile = async (relativePath, absPath) => new Promise((resolve, reject) => {
+            const rs = fs.createReadStream(absPath, { highWaterMark: chunkSize });
+            rs.on('data', (buf) => {
+                call.write({
+                    data: {
+                        relative_path: relativePath,
+                        content: buf,
+                        is_file_complete: false,
+                    },
+                });
+            });
+            rs.on('end', () => {
+                call.write({
+                    data: {
+                        relative_path: relativePath,
+                        content: Buffer.alloc(0),
+                        is_file_complete: true,
+                    },
+                });
+                resolve();
+            });
+            rs.on('error', reject);
+            call.on('error', reject);
+        });
+        try {
+            if (stats.isDirectory()) {
+                const files = await collectFiles(localPath);
+                const totalBytes = files.reduce((acc, cur) => acc + cur.size, 0);
+                const dstBase = remotePath || path.basename(localPath);
+                sendMeta({
+                    src_type: 2, // DIRECTORY
+                    dst_path: dstBase,
+                    total_files: files.length,
+                    total_bytes: totalBytes,
+                    overwrite,
+                });
+                for (const f of files) {
+                    await sendFile(f.relative, f.abs);
+                }
+            }
+            else {
+                const fileName = remotePath || path.basename(localPath);
+                sendMeta({
+                    src_type: 1, // FILE
+                    dst_path: fileName,
+                    total_files: 1,
+                    total_bytes: stats.size,
+                    overwrite,
+                });
+                await sendFile(path.basename(fileName), localPath);
+            }
+            call.end();
+            const res = await response;
+            // 记录上传成功
+            logHostDebug('files.put.success', {
+                requestId,
+                result: {
+                    success: res.success,
+                    filesWritten: res.files_written,
+                    bytesWritten: res.bytes_written,
+                    failedFiles: res.failed_files,
+                },
+            });
+            // 返回简化的结构化结果
+            const simpleResult = {
+                result: res.success ? 'done' : 'fail',
+                nextstep: '文件已存储在Agent中转站，需通过TFTP或NFS等方式传输到板卡访问，(通过board_linker docs工具获取用法)',
+            };
+            return simpleResult;
+        }
+        catch (err) {
+            // 记录上传失败
+            logHostDebug('files.put.error', {
+                requestId,
+                error: err?.message || String(err),
+                stack: err?.stack,
+            });
+            call.destroy();
+            // 返回失败结果而不是抛出异常
+            let nextstep = '检查文件路径和权限后重试';
+            if (err?.message?.includes('space') || err?.message?.includes('ENOSPC')) {
+                nextstep = '清理Agent侧存储空间后重试';
+            }
+            else if (err?.message?.includes('timeout')) {
+                nextstep = '检查网络连接后重试';
+            }
+            const simpleResult = {
+                result: 'fail',
+                nextstep: nextstep,
+            };
+            return simpleResult;
+        }
+    }
+    if (name === 'files-get') {
+        const fs = await import('node:fs');
+        const fsp = await import('node:fs/promises');
+        const path = await import('node:path');
+        const srcPath = params.src;
+        const dstPath = params.dst;
+        const chunkSize = typeof params.chunk_size === 'number' && params.chunk_size > 0
+            ? params.chunk_size
+            : 64 * 1024;
+        const skipHidden = params.skip_hidden === 1 || params.skip_hidden === true;
+        if (!dstPath || !path.isAbsolute(dstPath)) {
+            return "Parameter 'dst' is required and must be an absolute path. Please provide an absolute dst.";
+        }
+        if (path.isAbsolute(srcPath)) {
+            return "Parameter 'src' must be a relative path (relative to Agent files root). Please provide a relative src.";
+        }
+        // 生成唯一请求ID
+        const requestId = `files_get_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        // 详细记录Host端路径信息
+        logHostDebug('files.get.start', {
+            requestId,
+            operation: 'get',
+            originalSourcePath: srcPath, // Agent端源路径（相对路径）
+            originalTargetPath: dstPath, // Host端目标路径（绝对路径）
+            chunkSize: chunkSize,
+            skipHidden: skipHidden,
+            hostWorkingDirectory: process.cwd(),
+            hostUser: process.env.USER,
+            timestamp: Date.now(),
+        });
+        const call = await withAgentRetry('files.getPath', (cli) => cli.filesGetPath({
+            src_path: srcPath,
+            recursive: true,
+            chunk_size: chunkSize,
+            skip_hidden: skipHidden,
+            // 添加额外字段用于路径追踪
+            ...(requestId && { requestId }),
+            ...(dstPath && {
+                pathContext: {
+                    hostOriginalSourcePath: srcPath,
+                    hostOriginalTargetPath: dstPath,
+                    hostTimestamp: Date.now(),
+                    hostUser: process.env.USER,
+                },
+            }),
+        }), 'files-get');
+        return await new Promise((resolve, reject) => {
+            let srcType = null;
+            let baseDir = dstPath;
+            let rootDisplay = '';
+            let currentWriter = null;
+            let currentRelative = '';
+            let totalBytes = 0;
+            let completedFiles = 0;
+            let totalFiles = 0;
+            let resolved = false;
+            let processing = Promise.resolve();
+            const closeWriter = async () => {
+                if (!currentWriter)
+                    return;
+                await new Promise((res, rej) => currentWriter.end((err) => (err ? rej(err) : res())));
+                currentWriter = null;
+            };
+            const handleError = async (err) => {
+                if (resolved)
+                    return;
+                resolved = true;
+                // 记录下载失败
+                logHostDebug('files.get.error', {
+                    requestId,
+                    error: err?.message || String(err),
+                    stack: err?.stack,
+                });
+                try {
+                    await closeWriter();
+                }
+                catch {
+                    // ignore
+                }
+                // 返回失败结果而不是抛出异常
+                let nextstep = '检查文件路径和权限后重试';
+                if (err?.message?.includes('not found') || err?.message?.includes('ENOENT')) {
+                    nextstep = '检查Agent侧文件路径后重试';
+                }
+                else if (err?.message?.includes('timeout')) {
+                    nextstep = '检查网络连接后重试';
+                }
+                const simpleResult = {
+                    result: 'fail',
+                    nextstep: nextstep,
+                };
+                resolve(simpleResult);
+            };
+            const normalizeSrcType = (v) => {
+                if (v === 2 || v === 'FILE_TYPE_DIRECTORY' || v === 'DIRECTORY')
+                    return 2;
+                if (v === 1 || v === 'FILE_TYPE_FILE' || v === 'FILE')
+                    return 1;
+                return 0;
+            };
+            const processChunk = async (chunk) => {
+                if (!srcType) {
+                    srcType = normalizeSrcType(chunk.src_type);
+                    if (srcType === 2) {
+                        baseDir = baseDir || path.basename(srcPath);
+                        await fsp.mkdir(baseDir, { recursive: true });
+                        rootDisplay = baseDir;
+                    }
+                    else {
+                        const targetFile = dstPath || path.basename(srcPath);
+                        baseDir = path.dirname(targetFile);
+                        await fsp.mkdir(baseDir || '.', { recursive: true });
+                        rootDisplay = targetFile;
+                    }
+                }
+                const relativePath = chunk.relative_path || path.basename(srcPath);
+                totalFiles = chunk.total_files || totalFiles;
+                const targetPath = srcType === 2
+                    ? path.join(baseDir || '.', relativePath)
+                    : dstPath || path.basename(srcPath);
+                if (relativePath !== currentRelative) {
+                    await closeWriter();
+                    const parentDir = path.dirname(targetPath);
+                    await fsp.mkdir(parentDir, { recursive: true });
+                    currentWriter = fs.createWriteStream(targetPath);
+                    currentRelative = relativePath;
+                }
+                if (chunk.content && chunk.content.length > 0) {
+                    const buf = Buffer.from(chunk.content);
+                    currentWriter.write(buf);
+                    totalBytes += buf.length;
+                }
+                if (chunk.is_file_complete) {
+                    await closeWriter();
+                    currentRelative = '';
+                    completedFiles = chunk.files_completed || completedFiles + 1;
+                }
+                const done = chunk.is_directory_complete ||
+                    (srcType === 1 && chunk.is_file_complete) ||
+                    (srcType === 1 && chunk.is_directory_complete);
+                if (done && !resolved) {
+                    resolved = true;
+                    // 记录下载成功
+                    logHostDebug('files.get.success', {
+                        requestId,
+                        result: {
+                            remotePath: srcPath,
+                            localPath: rootDisplay || baseDir || dstPath || path.basename(srcPath),
+                            downloadedFiles: completedFiles || totalFiles || 1,
+                            totalBytes: totalBytes,
+                        },
+                    });
+                    // 返回简化的结构化结果
+                    const simpleResult = {
+                        result: 'done',
+                        nextstep: '文件已下载到本地，可直接访问',
+                    };
+                    resolve(simpleResult);
+                }
+            };
+            call.on('data', (chunk) => {
+                processing = processing.then(() => processChunk(chunk)).catch(handleError);
+            });
+            call.on('error', handleError);
+            call.on('end', () => {
+                processing
+                    .then(async () => {
+                    if (resolved)
+                        return;
+                    resolved = true;
+                    await closeWriter();
+                    // 记录下载成功
+                    logHostDebug('files.get.success', {
+                        requestId,
+                        result: {
+                            remotePath: srcPath,
+                            localPath: rootDisplay || baseDir || dstPath || path.basename(srcPath),
+                            downloadedFiles: completedFiles || totalFiles || 1,
+                            totalBytes: totalBytes,
+                        },
+                    });
+                    // 返回简化的结构化结果
+                    const simpleResult = {
+                        result: 'done',
+                        nextstep: '文件已下载到本地，可直接访问',
+                    };
+                    resolve(simpleResult);
+                })
+                    .catch(handleError);
+            });
+        });
+    }
+    if (name === 'files-list') {
+        const path = await import('node:path');
+        const rel = params.path || '';
+        if (rel && path.isAbsolute(rel)) {
+            return "Parameter 'path' must be relative to Agent files root.";
+        }
+        const recursive = params.recursive === 1 || params.recursive === true;
+        const all = params.all === 1 || params.all === true;
+        const pattern = params.pattern;
+        const res = await withAgentRetry('files.list', (cli) => cli.filesList({ path: rel || undefined, recursive, all, pattern }), 'files-list');
+        return res;
+    }
+    if (name === 'files-stat') {
+        const path = await import('node:path');
+        const rel = params.path;
+        if (!rel) {
+            return "Parameter 'path' is required and must be relative to Agent files root.";
+        }
+        if (path.isAbsolute(rel)) {
+            return "Parameter 'path' must be relative to Agent files root.";
+        }
+        const res = await withAgentRetry('files.stat', (cli) => cli.filesGetStat({ path: rel }), 'files-stat');
+        return res;
+    }
+    if (name === 'files-mkdir') {
+        const path = await import('node:path');
+        const rel = params.path;
+        if (!rel) {
+            return "Parameter 'path' is required and must be relative to Agent files root.";
+        }
+        if (path.isAbsolute(rel)) {
+            return "Parameter 'path' must be relative to Agent files root.";
+        }
+        const parents = params.parents === 1 || params.parents === true;
+        const res = await withAgentRetry('files.mkdir', (cli) => cli.filesMakeDir({ path: rel, parents }), 'files-mkdir');
+        return res;
+    }
+    if (name === 'files-rm') {
+        const path = await import('node:path');
+        const rel = params.path;
+        if (!rel) {
+            return "Parameter 'path' is required and must be relative to Agent files root.";
+        }
+        if (path.isAbsolute(rel)) {
+            return "Parameter 'path' must be relative to Agent files root.";
+        }
+        const recursive = params.recursive === 1 || params.recursive === true;
+        const res = await withAgentRetry('files.rm', (cli) => cli.filesRemove({ path: rel, recursive }), 'files-rm');
+        return res;
+    }
+    if (name === 'board_uart-sessions') {
+        return withAgentRetry('board_uart.sessions', (cli) => cli.boardUartListSessions(), 'board_uart-sessions');
+    }
+    if (name === 'board_uart-run_command') {
+        const hasCommand = params && Object.prototype.hasOwnProperty.call(params, 'command');
+        const hasData = params && Object.prototype.hasOwnProperty.call(params, 'data');
+        if (!hasCommand && !hasData) {
+            throw new Error('board_uart.run_command requires argument `command` (string, can be empty).');
+        }
+        const rawValue = hasCommand ? params.command : params.data;
+        const raw = typeof rawValue === 'string' ? rawValue : String(rawValue ?? '');
+        const normalized = normalizeBoardUartWriteText(raw);
+        const buf = Buffer.from(normalized, 'utf8');
+        // 如果未提供 sessionId，留空（表示 Default Session）
+        // Host 不再做任何智能解析，完全依赖 Agent 端逻辑
+        const sessionId = params.session_id || undefined;
+        const r2 = await withAgentRetry('board_uart.run_command', (cli) => cli.boardUartWrite({
+            sessionId,
+            data: buf,
+            waitFor: params.wait_for,
+            timeoutMs: params.timeout_ms,
+        }), 'board_uart-run_command');
+        return r2;
+    }
+    if (name === 'board_uart-send_signal') {
+        return await boardUartSendSignal(params);
+    }
+    if (name === 'board_uart-read') {
+        const result = await withAgentRetry('board_uart.read', (cli) => cli.boardUartSessionRead({
+            sessionId: params.session_id || defaultBoardUartSessionId || undefined,
+            maxBytes: params.max_bytes,
+            quietMs: params.quiet_ms,
+            timeoutMs: params.timeout_ms,
+        }), 'board_uart-read');
+        // 过滤ASCII控制字符，将Buffer转换为干净的字符串
+        if (result && result.data && Buffer.isBuffer(result.data)) {
+            const filteredText = filterAsciiControlChars(result.data);
+            return {
+                ...result,
+                data: filteredText,
+                // 保留原始bytes信息，但说明数据已被处理
+                originalBytes: result.bytes,
+                filtered: true,
+            };
+        }
+        return result;
+    }
+    if (name === 'board_uart-status') {
+        return withAgentRetry('board_uart.status', (cli) => cli.boardUartStatus(), 'board_uart-status');
+    }
+    if (name === 'firmware-prepare_images') {
+        // Upload local images directory to agent TFTP images_agent subdirectory
+        const fs = await import('node:fs/promises');
+        const pathMod = await import('node:path');
+        const localDir = params.localImagesDir;
+        if (!localDir || typeof localDir !== 'string') {
+            throw new Error('firmware.prepare_images: localImagesDir is required');
+        }
+        const stat = await fs.stat(localDir);
+        if (!stat.isDirectory()) {
+            throw new Error(`firmware.prepare_images: localImagesDir must be a directory, got ${localDir}`);
+        }
+        const imagesRoot = 'images_agent';
+        // 复用 tftp.upload 逻辑将整个目录同步到 agent 端 TFTP_ROOT/images_agent
+        const { default: path } = pathMod;
+        const entries = [];
+        const walk = async (base, dir) => {
+            const full = path.join(base, dir);
+            const items = await fs.readdir(full, { withFileTypes: true });
+            for (const ent of items) {
+                const entPath = path.join(full, ent.name);
+                const rel = path.relative(localDir, entPath);
+                if (ent.isDirectory()) {
+                    await walk(base, path.join(dir, ent.name));
+                }
+                else if (ent.isFile()) {
+                    entries.push({ full: entPath, rel });
+                }
+            }
+        };
+        await walk(localDir, '.');
+        let totalBytes = 0;
+        for (let i = 0; i < entries.length; i += 1) {
+            const ent = entries[i];
+            logDebug('firmware.prepare_images.upload', `${i + 1}/${entries.length}`, ent.rel);
+            const buf = await fs.readFile(ent.full);
+            const remotePath = [imagesRoot, ent.rel].filter(Boolean).join('/');
+            const res = await withAgentRetry('tftp.upload', (cli) => cli.tftpUpload({ fileName: remotePath, content: buf }), 'tftp-upload');
+            totalBytes += res.size;
+        }
+        // 调用 Agent 端 FirmwarePrepareImages，让其解析 images_root 下的元数据
+        const prepareRes = await withAgentRetry('firmware.prepare_images', (cli) => cli.firmwarePrepareImages({ imagesRoot }), 'firmware-prepare_images');
+        return prepareRes.meta;
+    }
+    if (name === 'firmware-burn_recover') {
+        logDebug('firmware-burn_recover.start', {
+            imagesRoot: params.imagesRoot,
+            args: params.args,
+            timeoutMs: params.timeout_ms,
+            force: params.force,
+        });
+        let argsArr = params.args;
+        if (typeof argsArr === 'string') {
+            try {
+                argsArr = JSON.parse(argsArr);
+            }
+            catch (e) {
+                const errorMsg = `firmware.burn_recover: failed to parse args JSON: ${e?.message || String(e)}`;
+                logDebug('firmware-burn_recover.parse_error', { args: params.args, error: errorMsg });
+                throw new Error(errorMsg);
+            }
+        }
+        if (!Array.isArray(argsArr)) {
+            const errorMsg = 'firmware.burn_recover: args must be an array';
+            logDebug('firmware-burn_recover.validate_error', { args: argsArr, error: errorMsg });
+            throw new Error(errorMsg);
+        }
+        const args = [];
+        for (const v of argsArr) {
+            if (typeof v !== 'string') {
+                const errorMsg = 'firmware.burn_recover: every arg must be a string';
+                logDebug('firmware-burn_recover.validate_error', { args: argsArr, error: errorMsg });
+                throw new Error(errorMsg);
+            }
+            args.push(v);
+        }
+        const timeoutMs = typeof params.timeout_ms === 'number' && params.timeout_ms > 0 ? params.timeout_ms : 0;
+        let force = false;
+        if (typeof params.force === 'string') {
+            const v = params.force.toLowerCase();
+            force = v === 'true' || v === '1' || v === 'yes';
+        }
+        logDebug('firmware-burn_recover.calling_agent', {
+            imagesRoot: params.imagesRoot,
+            args,
+            timeoutMs,
+            force,
+            agentAddr,
+        });
+        try {
+            const r = await withAgentRetry('firmware.burn_recover', (cli) => cli.firmwareBurnRecover({
+                imagesRoot: params.imagesRoot,
+                args,
+                timeoutMs,
+                force,
+            }), 'firmware-burn_recover');
+            logDebug('firmware-burn_recover.success', {
+                imagesRoot: params.imagesRoot,
+                result: { ok: r?.ok, exitCode: r?.exitCode, detailsLength: r?.details?.length },
+            });
+            return r;
+        }
+        catch (error) {
+            logDebug('firmware-burn_recover.error', {
+                imagesRoot: params.imagesRoot,
+                error: error?.message || String(error),
+                code: error?.code,
+                details: error?.details,
+                stack: error?.stack,
+            });
+            throw error;
+        }
+    }
+    if (name === 'agent-status') {
+        return withAgentRetry('agent.status', (cli) => cli.status(), 'agent-status');
+    }
+    if (name === 'docs-list') {
+        return [
+            { id: 'tftp-transfer', description: 'TFTP transfer setup and usage guide' },
+            { id: 'nfs-mount', description: 'NFS mounting and troubleshooting' },
+            {
+                id: 'board-interaction',
+                description: 'Board interaction protocol and hardware information',
+            },
+            { id: 'firmware-upgrade', description: 'Firmware lifecycle burn/recover user guide' },
+        ];
+    }
+    if (name === 'docs-read') {
+        const docId = params.id;
+        switch (docId) {
+            case 'tftp-transfer':
+                return withAgentRetry('tftp.userguide', (cli) => cli.tftpUserguide(), 'tftp-userguide');
+            case 'nfs-mount':
+                return withAgentRetry('nfs.userguide', (cli) => cli.nfsUserguide(), 'nfs-userguide');
+            case 'board-interaction':
+                return withAgentRetry('agent.board_notes', (cli) => cli.boardNotes({ board: params.board, section: params.section }), 'agent-board_notes');
+            case 'firmware-upgrade': {
+                const r = await withAgentRetry('docs.read.firmware', (cli) => cli.firmwareUserGuide(), 'docs-read-firmware');
+                return { content: r.json, format: 'markdown' };
+            }
+            default:
+                throw new Error(`Unknown documentation ID: ${docId}`);
+        }
+    }
+    throw new Error(`unknown procedure: ${name}`);
+}
+async function callProcedure(name, params) {
+    try {
+        logDebug('tools/call', name);
+        const logger = getHostLogger();
+        logger.write(LogLevel.DEBUG, 'tools.call.start', { name, params });
+        try {
+            hostLogCall?.write({
+                ts: Date.now(),
+                level: LogLevel.DEBUG,
+                event: 'tools.call.start',
+                data_json: JSON.stringify({ name, params }),
+                pid: process.pid,
+            });
+        }
+        catch { }
+        const result = await callProcedureInternal(name, params);
+        logger.write(LogLevel.DEBUG, 'tools.call.success', { name, resultType: typeof result });
+        try {
+            hostLogCall?.write({
+                ts: Date.now(),
+                level: LogLevel.DEBUG,
+                event: 'tools.call.success',
+                data_json: JSON.stringify({ name, resultType: typeof result }),
+                pid: process.pid,
+            });
+        }
+        catch { }
+        return result;
+    }
+    catch (err) {
+        const raw = (err && (err.message || err.details)) || String(err);
+        logDebug('error in procedure', name, raw);
+        const logger = getHostLogger();
+        logger.write(LogLevel.ERROR, 'tools.call.failed', {
+            name,
+            error: raw,
+            stack: err instanceof Error ? err.stack : undefined,
+        });
+        try {
+            hostLogCall?.write({
+                ts: Date.now(),
+                level: LogLevel.ERROR,
+                event: 'tools.call.failed',
+                data_json: JSON.stringify({
+                    name,
+                    error: raw,
+                    stack: err instanceof Error ? err.stack : undefined,
+                }),
+                pid: process.pid,
+            });
+        }
+        catch { }
+        throw err instanceof Error ? err : new Error(raw);
+    }
+}
+async function main() {
+    // 初始化日志系统
+    const logger = getHostLogger();
+    logDebug('starting host process, pid', process.pid);
+    // 记录启动信息
+    logger.write(LogLevel.INFO, 'host.starting', {
+        pid: process.pid,
+        nodeVersion: process.version,
+        platform: os.platform(),
+        debugEnabled: DEBUG_ENABLED,
+    });
+    const info = loadAgentDiscovery();
+    agentAddr = info.addr;
+    agentPairCode = info.pairCode;
+    tftpEnabled = info.tftpEnabled ?? true;
+    agent = createAgentClient(agentAddr, { hostInstanceId: HOST_INSTANCE_ID });
+    // 记录Agent连接信息
+    logger.write(LogLevel.INFO, 'agent.connecting', {
+        agentAddr,
+        agentId: info.id,
+        pairCode: agentPairCode.slice(0, 8) + '...',
+    });
+    const res = await agent.pairCheck({ pairCode: agentPairCode, timeoutMs: 3000 });
+    if (!res.accepted) {
+        logger.write(LogLevel.ERROR, 'agent.pair_failed', {
+            agentAddr,
+            reason: res.reason || 'PAIR_CODE_MISMATCH',
+        });
+        throw new Error(`PairCheck rejected for agent at ${agentAddr}: ${res.reason || 'PAIR_CODE_MISMATCH'}`);
+    }
+    logger.write(LogLevel.INFO, 'agent.pair_accepted', {
+        agentAddr,
+        agentId: info.id,
+    });
+    // Host -> Agent 日志流（best-effort）
+    try {
+        const s = agent.hostLogStream();
+        hostLogCall = s.call;
+        s.response.catch(() => { });
+    }
+    catch {
+        hostLogCall = null;
+    }
+    logDebug('PairCheck accepted', {
+        agentAddr,
+        agentId: info.id,
+        pairCode: agentPairCode.slice(0, 8) + '...',
+    });
+    const transport = new StdioServerTransport();
+    const server = new Server({
+        name: 'boardlinker-host',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.fallbackRequestHandler = async (request) => {
+        if (request.method === 'tools/list') {
+            const parsed = ListToolsRequestSchema.parse(request);
+            logDebug('tools/list', parsed.params ?? {});
+            const tools = listProcedures().map((p) => ({
+                name: toMcpToolName(p.name),
+                description: p.description ?? '',
+                inputSchema: paramsToJsonSchema(p.params),
+            }));
+            return { tools };
+        }
+        if (request.method === 'tools/call') {
+            const parsed = CallToolRequestSchema.parse(request);
+            const name = parsed.params.name;
+            const args = parsed.params.arguments ?? {};
+            logDebug('tools/call', 'calling', name);
+            const result = await callProcedure(name, args);
+            const formattedResult = {
+                content: [
+                    {
+                        type: 'text',
+                        text: typeof result === 'string' ? result : JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+            return formattedResult;
+        }
+        logDebug('fallback request handler invoked for unknown method', request.method);
+        throw new Error(`Method not found: ${request.method}`);
+    };
+    await server.connect(transport);
+    // 记录服务启动成功
+    logger.write(LogLevel.INFO, 'host.started', {
+        pid: process.pid,
+        agentAddr,
+        agentId: info.id,
+    });
+    // 启动心跳保活循环，确保Agent端能感知到Host在线状态
+    setInterval(() => {
+        agent.status().catch((err) => {
+            // 仅在调试模式记录心跳失败，避免刷屏
+            logDebug('heartbeat failed', err.message);
+        });
+    }, 5000).unref();
+}
+main().catch((err) => {
+    // 记录启动失败
+    try {
+        const logger = getHostLogger();
+        logger.write(LogLevel.ERROR, 'host.start_failed', {
+            error: err?.message || String(err),
+            stack: err instanceof Error ? err.stack : undefined,
+        });
+    }
+    catch (logError) {
+        // 忽略日志错误，优先输出原始错误
+    }
+    // MCP Host 启动失败时直接输出错误并退出
+    // eslint-disable-next-line no-console
+    console.error('boardlinker-host failed to initialize:', err?.message || String(err));
+    process.exit(1);
+});
+// 导出控制信号解析器供测试使用
+export { ControlSignalParser };