@sstar/boardlinker_host 0.2.0

package/dist/logger.js

@@ -0,0 +1,204 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel["DEBUG"] = "debug";
+    LogLevel["INFO"] = "info";
+    LogLevel["WARN"] = "warn";
+    LogLevel["ERROR"] = "error";
+})(LogLevel || (LogLevel = {}));
+export class HostLogger {
+    constructor() {
+        this.logStream = null;
+        this.serviceName = 'host';
+        this.config = this.loadConfig();
+        if (this.config.enabled) {
+            this.initializeLogFile();
+        }
+        this.currentLogFile = '';
+    }
+    loadConfig() {
+        return {
+            enabled: process.env.BOARDLINKER_HOST_DEBUG === '1' || process.env.BOARDLINKER_DEBUG === '1',
+            level: process.env.BOARDLINKER_LOG_LEVEL || LogLevel.DEBUG,
+            dir: process.env.BOARDLINKER_LOG_DIR || this.getDefaultLogDir(),
+            maxSize: this.parseSize(process.env.BOARDLINKER_LOG_MAX_SIZE) || 10 * 1024 * 1024, // 10MB
+            maxFiles: parseInt(process.env.BOARDLINKER_LOG_MAX_FILES || '20'),
+            maxAge: parseInt(process.env.BOARDLINKER_LOG_MAX_AGE || '7'), // days
+        };
+    }
+    getDefaultLogDir() {
+        return path.join(os.homedir(), '.config', 'board_linker', 'logs', 'host');
+    }
+    parseSize(sizeStr) {
+        if (!sizeStr)
+            return 0;
+        const units = {
+            B: 1,
+            KB: 1024,
+            MB: 1024 * 1024,
+            GB: 1024 * 1024 * 1024,
+        };
+        const match = sizeStr.match(/^(\d+)(B|KB|MB|GB)?$/i);
+        if (!match)
+            return 0;
+        const value = parseInt(match[1]);
+        const unit = match[2]?.toUpperCase() || 'B';
+        return value * (units[unit] || 1);
+    }
+    async initializeLogFile() {
+        try {
+            // 确保日志目录存在
+            await fs.promises.mkdir(this.config.dir, { recursive: true });
+            // 生成基于启动时间的日志文件名（使用本地时间）
+            const now = new Date();
+            const year = now.getFullYear();
+            const month = String(now.getMonth() + 1).padStart(2, '0');
+            const day = String(now.getDate()).padStart(2, '0');
+            const hours = String(now.getHours()).padStart(2, '0');
+            const minutes = String(now.getMinutes()).padStart(2, '0');
+            const seconds = String(now.getSeconds()).padStart(2, '0');
+            const timestamp = `${year}-${month}-${day}T${hours}-${minutes}-${seconds}`;
+            this.currentLogFile = path.join(this.config.dir, `${this.serviceName}-${timestamp}.log`);
+            // 创建写入流
+            this.logStream = fs.createWriteStream(this.currentLogFile, { flags: 'a' });
+            // 写入启动标记
+            this.write(LogLevel.INFO, 'logger.initialized', {
+                pid: process.pid,
+                nodeVersion: process.version,
+                platform: os.platform(),
+                logFile: this.currentLogFile,
+            });
+            // 设置错误处理
+            this.logStream.on('error', (error) => {
+                console.error('[boardlinker-host] Logger write error:', error);
+            });
+        }
+        catch (error) {
+            console.error('[boardlinker-host] Failed to initialize logger:', error);
+            this.logStream = null;
+        }
+    }
+    write(level, event, data) {
+        if (!this.config.enabled || !this.logStream) {
+            return;
+        }
+        // 检查日志级别
+        if (!this.shouldLog(level)) {
+            return;
+        }
+        const logEntry = {
+            ts: Date.now(),
+            level,
+            event,
+            data,
+            pid: process.pid,
+        };
+        const logLine = JSON.stringify(logEntry) + '\n';
+        try {
+            this.logStream.write(logLine);
+            // 检查是否需要轮转
+            this.checkRotation().catch((error) => {
+                console.error('[boardlinker-host] Log rotation error:', error);
+            });
+        }
+        catch (error) {
+            console.error('[boardlinker-host] Logger write error:', error);
+        }
+    }
+    shouldLog(level) {
+        const levels = [LogLevel.DEBUG, LogLevel.INFO, LogLevel.WARN, LogLevel.ERROR];
+        const currentLevelIndex = levels.indexOf(this.config.level);
+        const messageLevelIndex = levels.indexOf(level);
+        return messageLevelIndex >= currentLevelIndex;
+    }
+    async checkRotation() {
+        if (!this.currentLogFile || !this.logStream) {
+            return;
+        }
+        try {
+            const stats = await fs.promises.stat(this.currentLogFile);
+            if (stats.size > this.config.maxSize) {
+                await this.rotate();
+            }
+        }
+        catch (error) {
+            // 忽略文件不存在的错误
+        }
+    }
+    async rotate() {
+        if (!this.logStream)
+            return;
+        try {
+            // 关闭当前文件流
+            this.logStream.end();
+            // 创建新的日志文件
+            await this.initializeLogFile();
+            // 清理旧文件
+            await this.cleanupOldFiles();
+        }
+        catch (error) {
+            console.error('[boardlinker-host] Log rotation error:', error);
+        }
+    }
+    async cleanupOldFiles() {
+        try {
+            const files = await fs.promises.readdir(this.config.dir);
+            const logFiles = files
+                .filter((f) => f.startsWith(`${this.serviceName}-`) && f.endsWith('.log'))
+                .map((f) => ({ name: f, path: path.join(this.config.dir, f) }));
+            // 按修改时间排序
+            const fileStats = await Promise.all(logFiles.map(async (f) => ({
+                ...f,
+                mtime: (await fs.promises.stat(f.path)).mtime,
+            })));
+            fileStats.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+            // 删除超出数量限制的文件
+            const filesToDelete = fileStats.slice(this.config.maxFiles);
+            await Promise.all(filesToDelete.map((f) => fs.promises.unlink(f.path).catch(() => {
+                // 忽略删除错误
+            })));
+            // 删除超出时间限制的文件
+            const cutoffDate = new Date(Date.now() - this.config.maxAge * 24 * 60 * 60 * 1000);
+            const oldFiles = fileStats.filter((f) => f.mtime < cutoffDate);
+            await Promise.all(oldFiles.map((f) => fs.promises.unlink(f.path).catch(() => {
+                // 忽略删除错误
+            })));
+        }
+        catch (error) {
+            console.error('[boardlinker-host] Log cleanup error:', error);
+        }
+    }
+    close() {
+        if (this.logStream) {
+            this.write(LogLevel.INFO, 'logger.closed', { reason: 'shutdown' });
+            this.logStream.end();
+            this.logStream = null;
+        }
+    }
+}
+// 单例实例
+let hostLogger = null;
+export function getHostLogger() {
+    if (!hostLogger) {
+        hostLogger = new HostLogger();
+    }
+    return hostLogger;
+}
+// 便捷函数
+export function logHost(level, event, data) {
+    getHostLogger().write(level, event, data);
+}
+export function logHostDebug(event, data) {
+    logHost(LogLevel.DEBUG, event, data);
+}
+export function logHostInfo(event, data) {
+    logHost(LogLevel.INFO, event, data);
+}
+export function logHostWarn(event, data) {
+    logHost(LogLevel.WARN, event, data);
+}
+export function logHostError(event, data) {
+    logHost(LogLevel.ERROR, event, data);
+}

package/dist/proto/agent.proto

@@ -0,0 +1,473 @@
+syntax = "proto3";
+
+package boardlinker.agent.v1;
+
+service AgentService {
+  rpc Status (StatusRequest) returns (StatusResponse);
+  rpc BoardUartWrite (BoardUartWriteRequest) returns (BoardUartWriteResponse);
+  // Host -> Agent: best-effort structured log streaming
+  rpc HostLogStream (stream HostLogEntry) returns (HostLogSummary);
+  // 板卡 UART 会话接口：多 session + 读写
+  rpc BoardUartListSessions (BoardUartListSessionsRequest) returns (BoardUartListSessionsResponse);
+  rpc BoardUartSessionWrite (BoardUartSessionWriteRequest) returns (BoardUartSessionWriteResponse);
+  rpc BoardUartSessionRead (BoardUartSessionReadRequest) returns (BoardUartSessionReadResponse);
+  rpc BoardUartOpenManual (BoardUartOpenManualRequest) returns (BoardUartOpenManualResponse);
+  rpc BoardUartCloseSession (BoardUartCloseSessionRequest) returns (BoardUartCloseSessionResponse);
+  rpc BoardUartStatus (BoardUartStatusRequest) returns (BoardUartStatusResponse);
+  rpc BoardUartForceClose (BoardUartForceCloseRequest) returns (BoardUartForceCloseResponse);
+  rpc TftpUpload (TftpUploadRequest) returns (TftpUploadResponse);
+  rpc TftpDownload (TftpDownloadRequest) returns (TftpDownloadResponse);
+  rpc TftpList (TftpListRequest) returns (TftpListResponse);
+    rpc TftpUserguide (TftpUserguideRequest) returns (TftpUserguideResponse);
+  rpc UBootBreak (UBootBreakRequest) returns (UBootBreakResponse);
+  rpc UBootRunCommand (UBootRunCommandRequest) returns (UBootRunCommandResponse);
+    rpc TunnelStart (TunnelStartRequest) returns (TunnelStartResponse);
+  rpc TunnelStop (TunnelStopRequest) returns (TunnelStopResponse);
+  // Added utility endpoints
+  rpc BoardUartListPorts (BoardUartListPortsRequest) returns (BoardUartListPortsResponse);
+    rpc ListSshCandidates (ListSshCandidatesRequest) returns (ListSshCandidatesResponse);
+  // NFS 文件同步与浏览
+  rpc NfsUpload (NfsUploadRequest) returns (NfsUploadResponse);
+  rpc NfsDownload (NfsDownloadRequest) returns (NfsDownloadResponse);
+  rpc NfsList (NfsListRequest) returns (NfsListResponse);
+  rpc NfsInfo (NfsInfoRequest) returns (NfsInfoResponse);
+  rpc NfsUserguide (NfsUserguideRequest) returns (NfsUserguideResponse);
+  // 板卡环境说明
+  rpc BoardNotes (BoardNotesRequest) returns (BoardNotesResponse);
+  // 固件镜像准备与 ISP 恢复烧录
+  rpc FirmwarePrepareImages (FirmwarePrepareImagesRequest) returns (FirmwarePrepareImagesResponse);
+  rpc FirmwareBurnRecover (FirmwareBurnRecoverRequest) returns (FirmwareBurnRecoverResponse);
+  rpc FirmwareUserGuide (FirmwareUserGuideRequest) returns (FirmwareUserGuideResponse);
+}
+
+// Files Service - 极简文件服务
+service FilesService {
+  // 公开接口 - 对应 MCP 工具
+  rpc PutPath(stream PutPathChunk) returns (PutPathSummary);
+  rpc GetPath(GetPathRequest) returns (stream PathChunk);
+
+  // 内部接口 - 完整 CRUD 实现，但不暴露为 MCP 工具
+  rpc ListFiles(ListFilesRequest) returns (ListFilesResponse);
+  rpc RemoveFiles(RemoveFilesRequest) returns (RemoveFilesResponse);
+  rpc MakeDirectory(MakeDirectoryRequest) returns (MakeDirectoryResponse);
+  rpc GetStat(GetStatRequest) returns (GetStatResponse);
+}
+
+// Pairing service: validate that a given endpoint matches the intended Agent instance
+service PairingService {
+  rpc PairCheck (PairCheckRequest) returns (PairCheckResponse);
+}
+
+message PairCheckRequest {
+  string pairCode = 1;
+  string clientId = 2;
+  int64 timestamp = 3;
+}
+
+message PairCheckResponse {
+  bool accepted = 1;
+  string agentId = 2;
+  string version = 3;
+  string startupTime = 4;
+  string reason = 5;
+}
+
+message StatusRequest {}
+message StatusResponse {
+  string status = 1;
+  string version = 2;
+  int64 timestamp = 3;
+  repeated NetworkInterfaceInfo networkInterfaces = 4;
+  string error = 5;
+  // Network mount (CIFS/NFS) helpers for AI orchestration
+  string shareUsername = 6;
+  string sharePassword = 7;
+  string nfsExportPath = 8;
+  // Platform information
+  string platform = 9;
+  string arch = 10;
+}
+
+message NetworkInterfaceInfo {
+  string ip = 1;
+  string netmask = 2;
+  string broadcast = 3;
+  string gateway = 4;
+  string interface = 5;
+  bool internal = 6;
+}
+
+message BoardUartWriteRequest {
+  string sessionId = 1; // Empty means default session
+  bytes data = 2;
+  bool mock = 3;
+  // New fields for Smart Sync
+  optional string waitFor = 4;
+  optional int64 timeoutMs = 5;
+}
+
+message BoardUartWriteResponse {
+  string status = 1;
+  string output = 2;
+  string nextStep = 3;
+  int64 elapsedMs = 4;
+  int64 lastOutputGapMs = 5;
+  uint32 remains = 6; // 此次返回后，缓冲区中剩余待读取的数据字节数
+}
+
+// 板卡 UART 会话相关
+message BoardUartSessionInfo {
+  string id = 1;
+  string label = 2;
+  string role = 3;
+  bool isDefault = 4;
+  bool canWrite = 5;
+}
+
+message BoardUartListSessionsRequest {}
+message BoardUartListSessionsResponse { repeated BoardUartSessionInfo sessions = 1; }
+
+message BoardUartSessionWriteRequest {
+  string sessionId = 1; // 为空表示默认会话
+  bytes data = 2;
+}
+message BoardUartSessionWriteResponse {
+  uint32 bytesWritten = 1;
+  uint32 remains = 2; // 此次返回后，缓冲区中剩余待读取的数据字节数
+}
+
+message BoardUartSessionReadRequest {
+  string sessionId = 1; // 为空表示默认会话
+  uint32 maxBytes = 2;
+  uint32 quietMs = 3;
+  uint32 timeoutMs = 4;
+}
+message BoardUartSessionReadResponse {
+  bytes data = 1;
+  uint32 bytes = 2;
+  bool timedOut = 3;
+  uint32 remains = 4; // 此次返回后，缓冲区中剩余待读取的数据字节数
+}
+
+message BoardUartOpenManualRequest {
+  string port = 1;
+  uint32 baud = 2;
+}
+message BoardUartOpenManualResponse {
+  BoardUartSessionInfo session = 1;
+}
+
+message BoardUartCloseSessionRequest { string sessionId = 1; }
+message BoardUartCloseSessionResponse { bool closed = 1; }
+
+message BoardUartAttachedTool {
+  string id = 1;
+  string source = 2;
+  string sessionId = 3;
+  string port = 4;
+  uint32 baud = 5;
+  int64 attachedAtMs = 6;
+}
+
+message BoardUartStatusRequest {}
+message BoardUartStatusResponse {
+  string status = 1;
+  bool disabled = 2;
+  bool hasModule = 3;
+  string port = 4;
+  uint32 baud = 5;
+  repeated BoardUartSessionInfo sessions = 6;
+  repeated BoardUartAttachedTool attachedTools = 7;
+  bool suspended = 8;
+  string suspendOwner = 9;
+  int64 suspendedSinceMs = 10;
+  int64 maxSuspendMs = 11;
+  bool autoResumed = 12;
+}
+
+message BoardUartForceCloseRequest {}
+message BoardUartForceCloseResponse { bool ok = 1; }
+
+message BoardUartListPortsRequest {}
+message BoardUartPortInfo { string path = 1; string friendlyName = 2; }
+message BoardUartListPortsResponse { repeated BoardUartPortInfo ports = 1; }
+
+message TftpUploadRequest { string fileName = 1; bytes content = 2; }
+message TftpUploadResponse { string path = 1; uint64 size = 2; string sha256 = 3; }
+
+message TftpDownloadRequest { string path = 1; }
+message TftpDownloadResponse { bytes content = 1; uint64 size = 2; }
+
+message TftpListRequest {
+  string basePath = 1; // 相对 TFTP 根目录的 POSIX 路径，可为空表示根目录
+  uint32 depth = 2;    // 递归深度
+}
+
+
+message TftpListResponse {
+  repeated FileEntry entries = 1;
+  bool truncated = 2;
+}
+
+
+message TftpUserguideRequest {}
+message TftpUserguideResponse {
+  string content = 1;
+  string format = 2;
+}
+
+message UBootBreakRequest { string sessionId = 1; uint32 timeoutMs = 2; bool mock = 3; }
+message UBootBreakResponse { bool ok = 1; string details = 2; }
+
+message UBootRunCommandRequest { string sessionId = 1; string command = 2; uint32 timeoutMs = 3; bool mock = 4; }
+message UBootRunCommandResponse { bool ok = 1; string output = 2; }
+
+
+message TunnelStartRequest { string host = 1; uint32 port = 2; string user = 3; string password = 4; string privateKeyPath = 5; uint32 localPort = 6; string forwardHost = 7; uint32 forwardPort = 8; }
+message TunnelStartResponse { bool connected = 1; string details = 2; }
+
+message TunnelStopRequest {}
+message TunnelStopResponse { bool stopped = 1; }
+
+
+message ListSshCandidatesRequest {}
+message SshCandidate { string label = 1; string host = 2; }
+message ListSshCandidatesResponse { repeated SshCandidate hosts = 1; }
+
+// NFS 相关
+message NfsUploadRequest { string remoteSubpath = 1; bytes content = 2; }
+message NfsUploadResponse { string remoteSubpath = 1; uint64 size = 2; }
+
+message NfsDownloadRequest { string remoteSubpath = 1; }
+message NfsDownloadResponse { bytes content = 1; uint64 size = 2; }
+
+enum NfsListMode {
+  NFS_LIST_MODE_UNSPECIFIED = 0;
+  NFS_LIST_MODE_SIMPLE = 1;
+  NFS_LIST_MODE_DETAILED = 2;
+}
+
+message NfsListRequest {
+  string remoteSubpath = 1;
+  NfsListMode mode = 2;
+  optional uint32 limit = 3;
+}
+message NfsListResponse {
+  repeated FileEntry entries = 1;
+  bool truncated = 2;
+}
+
+message NfsInfoRequest {}
+message NfsInfoResponse {
+  bool enabled = 1;
+  string exportName = 2;
+  string description = 3;
+}
+
+message NfsUserguideRequest {}
+message NfsUserguideResponse {
+  string content = 1;
+  string format = 2;
+}
+
+// 板卡说明文档
+message BoardNotesRequest {
+  string board = 1;
+  string section = 2;
+}
+message BoardNotesResponse {
+  string content = 1;
+  string format = 2;
+}
+
+// Files 相关消息定义
+
+enum FileType {
+  FILE_TYPE_UNSPECIFIED = 0;
+  FILE_TYPE_FILE = 1;
+  FILE_TYPE_DIRECTORY = 2;
+}
+
+// 统一路径传输
+message PutPathChunk {
+  oneof kind {
+    PutPathMeta meta = 1;
+    FileContentChunk data = 2;
+  }
+}
+
+message PutPathMeta {
+  FileType src_type = 1;
+  string dst_path = 2;         // 相对 Agent files 根目录
+  uint32 total_files = 3;
+  uint64 total_bytes = 4;
+  bool overwrite = 5;
+}
+
+message FileContentChunk {
+  string relative_path = 1;    // 目录内的相对路径；单文件时为文件名
+  bytes content = 2;
+  bool is_file_complete = 3;
+}
+
+message PutPathSummary {
+  bool success = 1;
+  uint32 files_written = 2;
+  uint64 bytes_written = 3;
+  repeated string failed_files = 4;
+}
+
+message GetPathRequest {
+  string src_path = 1;         // 相对 Agent files 根目录
+  bool recursive = 2;          // 目录是否递归
+  uint32 chunk_size = 3;       // 可选分块大小
+  bool skip_hidden = 4;        // 是否跳过隐藏文件
+}
+
+message PathChunk {
+  FileType src_type = 1;               // FILE_TYPE_FILE 或 FILE_TYPE_DIRECTORY
+  string relative_path = 2;            // 目录内的相对路径；单文件时为文件名
+  bytes content = 3;
+  bool is_file_complete = 4;           // 当前文件完成
+  bool is_directory_complete = 5;      // 目录全部完成
+  uint32 files_completed = 6;          // 已完成文件数
+  uint32 total_files = 7;              // 总文件数
+}
+
+message FileEntry {
+  string name = 1;
+  string path = 2;
+  FileType type = 3;
+  uint64 size = 4;
+  int64 mtime = 5;
+}
+
+message ListFilesRequest {
+  optional string path = 1;
+  optional bool all = 2;
+  optional bool recursive = 3;
+  optional string pattern = 4;
+}
+
+message ListFilesResponse {
+  repeated FileEntry entries = 1;
+  uint32 total_entries = 2;
+  bool truncated = 3;
+}
+
+message RemoveFilesRequest {
+  string path = 1;
+  optional bool recursive = 2;
+}
+
+message RemoveFilesResponse {
+  bool success = 1;
+  uint32 deleted_count = 2;
+}
+
+message MakeDirectoryRequest {
+  string path = 1;
+  optional bool parents = 2;
+}
+
+message MakeDirectoryResponse {
+  bool success = 1;
+  string path = 2;
+}
+
+message GetStatRequest {
+  string path = 1;
+}
+
+message FileStat {
+  string path = 1;
+  string name = 2;
+  uint64 size = 3;
+  bool is_file = 4;
+  bool is_directory = 5;
+  int64 modified_at = 6;
+  optional string permissions = 7;
+}
+
+message GetStatResponse {
+  bool success = 1;
+  FileStat stat = 2;
+}
+
+// 固件镜像及 ISP 烧录相关
+
+message FirmwarePrepareImagesRequest {
+  // 相对 TFTP 根目录的 images 子目录路径，例如 "images_agent" 或 "images_agent/build123"
+  string imagesRoot = 1;
+}
+
+
+message FirmwarePartitionMeta {
+  string name = 1;
+  // 分区起始地址，字符串形式（例如 "0x0", "0x200000"）
+  string address = 2;
+  uint64 size = 3;
+  // 可选的分组名称（例如 "BOOT", "SYSTEM"）
+  string group = 4;
+}
+
+message FirmwareStrategySegment {
+  string file = 1;
+  string offset = 2;
+}
+
+message FirmwareRecommendedStrategy {
+  string id = 1;
+  string description = 2;
+  repeated FirmwareStrategySegment segments = 3;
+}
+
+message FirmwareImagesMeta {
+  // 整体镜像类型（任意字符串；自动检测失败时为 "unknown"）
+  string imagesType = 1;
+  // 文件列表，每行格式：文件路径 大小
+  string files = 2;
+  repeated FirmwarePartitionMeta partitions = 3;
+  repeated FirmwareRecommendedStrategy recommendedStrategies = 4;
+}
+
+message FirmwarePrepareImagesResponse {
+  string meta = 1;  // 纯字符串格式，包含 TOON 格式分区信息
+}
+
+message FirmwareBurnRecoverRequest {
+  string imagesRoot = 1;
+  // 由 AI 构造的 ISP 工具参数数组（顺序敏感）
+  repeated string args = 2;
+  int64 timeoutMs = 3;
+  bool force = 4;
+}
+
+message FirmwareBurnRecoverResponse {
+  bool ok = 1;
+  int32 exitCode = 2;
+  string details = 3;
+  string logTail = 4;
+}
+
+message FirmwareUserGuideRequest {}
+
+message FirmwareUserGuideResponse {
+  // Markdown 文本，内部 MAY 包含 JSON fenced block（FSM 模板、语义提示等）
+  string json = 1;
+}
+
+// Host -> Agent best-effort structured log streaming
+message HostLogEntry {
+  int64 ts = 1;
+  string level = 2;
+  string event = 3;
+  // JSON string. Agent may parse it for UI rendering.
+  string data_json = 4;
+  int32 pid = 5;
+}
+
+message HostLogSummary {
+  bool accepted = 1;
+  string reason = 2;
+}