@sstar/embedlink_agent 0.1.0

package/dist/nfs/index.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { ErrorCodes, error } from '../core/errors.js';
+function normalizePosixSubpath(subpath) {
+    if (!subpath)
+        return '';
+    const replaced = subpath.replace(/\\/g, '/');
+    const parts = replaced.split('/').filter((p) => p && p !== '.' && p !== '..');
+    return parts.join('/');
+}
+function resolveUnderRoot(root, subpath) {
+    const rel = normalizePosixSubpath(subpath);
+    if (!rel)
+        return root;
+    const segments = rel.split('/');
+    return path.join(root, ...segments);
+}
+export async function nfsUpload(rootDir, remoteSubpath, content) {
+    try {
+        const full = resolveUnderRoot(rootDir, remoteSubpath);
+        const dir = path.dirname(full);
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(full, content);
+        const st = await fs.stat(full);
+        return { remoteSubpath, size: st.size };
+    }
+    catch (e) {
+        throw error(ErrorCodes.EL_TFTP_UPLOAD_FAILED, e?.message || String(e));
+    }
+}
+export async function nfsDownload(rootDir, remoteSubpath) {
+    const full = resolveUnderRoot(rootDir, remoteSubpath);
+    try {
+        const buf = await fs.readFile(full);
+        const st = await fs.stat(full);
+        return { content: buf, size: st.size };
+    }
+    catch (e) {
+        throw error(ErrorCodes.EL_TFTP_VERIFY_FAILED, e?.message || String(e));
+    }
+}
+export async function nfsList(rootDir, remoteSubpath, mode = 'simple', limit) {
+    const entries = [];
+    let truncated = false;
+    const start = resolveUnderRoot(rootDir, remoteSubpath);
+    const maxEntries = limit || 10000; // 默认上限防止内存问题
+    // 只返回1层，不递归
+    try {
+        const isQueryDir = await fs.stat(start).catch(() => null);
+        if (isQueryDir?.isDirectory()) {
+            // 如果是查询目录，列出其直接子项
+            const children = await fs.readdir(start, { withFileTypes: true }).catch(() => []);
+            for (const ent of children) {
+                if (entries.length >= maxEntries) {
+                    truncated = true;
+                    break;
+                }
+                const childFull = path.join(start, ent.name);
+                const st = await fs.stat(childFull).catch(() => null);
+                if (!st)
+                    continue;
+                const isDir = st.isDirectory();
+                if (mode === 'simple') {
+                    entries.push({
+                        name: ent.name, // 只返回当前层级的名称
+                        isDirectory: isDir,
+                    });
+                }
+                else {
+                    entries.push({
+                        name: ent.name, // 只返回当前层级的名称
+                        isDirectory: isDir,
+                        sizeBytes: isDir ? 0 : st.size,
+                        modifiedAtMs: st.mtimeMs || 0,
+                    });
+                }
+            }
+        }
+        else {
+            // 如果不是目录（例如具体文件），直接返回该文件信息
+            const name = path.basename(start);
+            if (mode === 'simple') {
+                entries.push({
+                    name: name,
+                    isDirectory: false,
+                });
+            }
+            else {
+                const st = await fs.stat(start).catch(() => null);
+                if (st) {
+                    entries.push({
+                        name: name,
+                        isDirectory: false,
+                        sizeBytes: st.size,
+                        modifiedAtMs: st.mtimeMs || 0,
+                    });
+                }
+            }
+        }
+    }
+    catch {
+        // ignore missing dirs or files
+    }
+    return { entries, truncated };
+}

package/dist/plugins/loader.js

@@ -0,0 +1,30 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+export async function loadPlugins(dir) {
+    const abs = path.isAbsolute(dir) ? dir : path.join(process.cwd(), dir);
+    try {
+        const items = await fs.readdir(abs);
+        const loaded = [];
+        for (const f of items) {
+            if (!f.endsWith('.js') && !f.endsWith('.mjs'))
+                continue;
+            try {
+                const mod = await import(path.join(abs, f));
+                const p = mod.default || mod;
+                if (p.init)
+                    await p.init();
+                loaded.push(p);
+            }
+            catch (e) {
+                console.warn('plugin load failed:', f, e);
+            }
+        }
+        for (const p of loaded)
+            if (p.start)
+                await p.start();
+        return loaded;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/proto/agent.proto

@@ -0,0 +1,473 @@
+syntax = "proto3";
+
+package embedlink.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;
+}