@sstar/embedlink_agent 0.1.0

package/README.md

@@ -0,0 +1,107 @@
+# @sstar/embedlink_agent
+
+EmbedLink Agent - 为嵌入式开发提供板卡硬件访问服务的 gRPC 服务器。
+
+## 功能特性
+
+- **板卡 UART 通信**: 支持多会话串口管理和数据传输
+- **文件传输**: 支持 Host 与 Agent 之间的双向文件传输
+- **固件烧录**: 支持 ISP 方式的固件恢复和升级
+- **SSH 隧道**: 支持 SSH 远程访问和端口转发
+- **TFTP 服务**: 内置 TFTP 服务器用于镜像传输
+- **NFS 同步**: 支持 NFS 文件系统同步
+- **Web 管理界面**: 内置 Web UI 用于配置和监控
+- **插件系统**: 支持通过插件扩展功能
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g @sstar/embedlink_agent
+
+# 或使用 pnpm
+pnpm add -g @sstar/embedlink_agent
+```
+
+## 使用
+
+### 启动 Agent
+
+```bash
+# 直接启动
+embedlink
+
+# 带调试信息启动
+embedlink -d
+
+# 启动但不自动打开浏览器
+embedlink --no-open
+```
+
+### 环境变量配置
+
+Agent 支持通过环境变量进行配置：
+
+| 变量名 | 说明 | 默认值 |
+|--------|------|--------|
+| `EMBEDLINK_GRPC_PORT` | gRPC 服务器端口 | `10000` |
+| `EMBEDLINK_WEB_HOST` | Web 服务器主机地址 | `0.0.0.0` |
+| `EMBEDLINK_WEB_PORT` | Web 服务器端口 | `8080` |
+| `EMBEDLINK_TFTP_DIR` | TFTP 文件服务目录 | `~/.local/embed_link/agent_files` |
+| `EMBEDLINK_TFTP_TTL_HOURS` | TFTP 文件保存时间（小时） | `24` |
+| `EMBEDLINK_BOARD_UART_PORT` | 板卡串口设备路径 | 自动检测 |
+| `EMBEDLINK_BOARD_UART_BAUD` | 板卡串口波特率 | `115200` |
+| `EMBEDLINK_LOG_LEVEL` | 日志级别 | `DEBUG` |
+
+### 配置文件
+
+Agent 启动后会创建配置文件：`~/.config/embed_link/agent.json`
+
+```json
+{
+  "agent": {
+    "id": "agent",
+    "version": "0.1.0",
+    "pairCode": "xxx-xxx-xxx",
+    "startupTime": "2024-01-01T00:00:00.000Z"
+  },
+  "endpoint": {
+    "grpc": {
+      "host": "127.0.0.1",
+      "port": 10000,
+      "scheme": "grpc"
+    },
+    "web": {
+      "host": "127.0.0.1",
+      "port": 8080
+    }
+  }
+}
+```
+
+## Web 管理界面
+
+Agent 启动后会自动打开浏览器访问 Web 管理界面（可通过 `--no-open` 禁用）。
+
+默认地址：`http://127.0.0.1:8080`
+
+## 与 Host 配合使用
+
+Agent 需要与 [@sstar/embedlink_host](../host/) 配合使用才能完整发挥功能：
+
+```bash
+# 终端 1: 启动 Agent
+embedlink
+
+# 终端 2: 启动 Host
+npx @sstar/embedlink_host
+```
+
+## 系统要求
+
+- Node.js >= 18.0.0
+- 支持 macOS、Linux、Windows
+
+## 许可证
+
+MIT

package/dist/.platform

@@ -0,0 +1 @@
+linux-x64

package/dist/board/docs.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const CONFIG_DIR = path.join(os.homedir(), '.config', 'embed_link');
+const DOC_DIR = process.env.EMBEDLINK_DOCS_DIR || CONFIG_DIR;
+const DEFAULT_DOC_DIR = process.env.EMBEDLINK_DOCS_DEFAULT_DIR ||
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../resources/docs');
+const DOC_FILES = {
+    'board-interaction': 'board-interaction.md',
+    'tftp-transfer': 'tftp-transfer-guide.md',
+    'nfs-mount': 'nfs-mount-guide.md',
+    'firmware-upgrade': 'firmware-upgrade.md',
+};
+export function getDocsDir() {
+    return DOC_DIR;
+}
+export function getDefaultDocsDir() {
+    return DEFAULT_DOC_DIR;
+}
+async function resolveDefaultDoc(kind, fallback) {
+    const bundledPath = path.join(DEFAULT_DOC_DIR, DOC_FILES[kind]);
+    try {
+        const buf = await fs.readFile(bundledPath, 'utf8');
+        return { content: buf, format: 'markdown' };
+    }
+    catch {
+        // ignore and fallback to built-in template
+    }
+    if (fallback)
+        return { content: fallback.content, format: fallback.format };
+    return { content: '', format: 'markdown' };
+}
+export async function readDoc(kind, fallback) {
+    const file = path.join(DOC_DIR, DOC_FILES[kind]);
+    try {
+        const buf = await fs.readFile(file, 'utf8');
+        return { content: buf, format: 'markdown', path: file };
+    }
+    catch {
+        const def = await resolveDefaultDoc(kind, fallback);
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, def.content ?? '', 'utf8');
+        return { content: def.content, format: def.format, path: file };
+    }
+}
+export async function writeDoc(kind, content) {
+    const file = path.join(DOC_DIR, DOC_FILES[kind]);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, content ?? '', 'utf8');
+    return file;
+}
+export async function resetDoc(kind, fallback) {
+    const file = path.join(DOC_DIR, DOC_FILES[kind]);
+    const def = await resolveDefaultDoc(kind, fallback);
+    await fs.mkdir(path.dirname(file), { recursive: true });
+    await fs.writeFile(file, def.content ?? '', 'utf8');
+    return file;
+}

package/dist/board/notes.js

@@ -0,0 +1,11 @@
+import { readDoc, writeDoc } from './docs.js';
+export async function loadBoardNotes(_cfg, _board, _section) {
+    const doc = await readDoc('board-interaction');
+    return { content: doc.content, format: doc.format };
+}
+export async function loadBoardNotesFromFile() {
+    return await readDoc('board-interaction');
+}
+export async function saveBoardNotes(content) {
+    return writeDoc('board-interaction', content);
+}

package/dist/board_uart/history.js

@@ -0,0 +1,81 @@
+const DEFAULT_MAX_LINES = 5000;
+const HARD_MAX_LINES = 50000;
+const histories = new Map();
+function normalizeSessionId(sessionId) {
+    return (sessionId || '').trim();
+}
+function clampMaxLines(maxLines) {
+    if (!Number.isFinite(maxLines))
+        return DEFAULT_MAX_LINES;
+    const n = Math.floor(maxLines);
+    if (n <= 0)
+        return 0;
+    return Math.min(n, HARD_MAX_LINES);
+}
+function getOrCreate(sessionId) {
+    const id = normalizeSessionId(sessionId);
+    let st = histories.get(id);
+    if (!st) {
+        st = {
+            seq: 0,
+            maxLines: DEFAULT_MAX_LINES,
+            lineBuffer: '',
+            lines: [],
+        };
+        histories.set(id, st);
+    }
+    return st;
+}
+export function setBoardUartHistoryMaxLines(sessionId, maxLines) {
+    const id = normalizeSessionId(sessionId);
+    if (!id)
+        return;
+    const target = clampMaxLines(maxLines);
+    if (target <= 0)
+        return;
+    const st = getOrCreate(id);
+    st.maxLines = target;
+    while (st.lines.length > st.maxLines) {
+        st.lines.shift();
+    }
+}
+export function appendBoardUartHistoryChunk(sessionId, chunk) {
+    const id = normalizeSessionId(sessionId);
+    if (!id)
+        return;
+    if (!Buffer.isBuffer(chunk) || chunk.length === 0)
+        return;
+    const st = getOrCreate(id);
+    const now = Date.now();
+    let text = '';
+    try {
+        text = chunk.toString('utf8');
+    }
+    catch {
+        text = '';
+    }
+    if (!text)
+        return;
+    const parts = (st.lineBuffer + text).split('\n');
+    st.lineBuffer = parts.pop() || '';
+    for (const line of parts) {
+        st.seq += 1;
+        st.lines.push({ seq: st.seq, receivedAtMs: now, text: line });
+    }
+    while (st.lines.length > st.maxLines) {
+        st.lines.shift();
+    }
+}
+export function getBoardUartHistoryLines(sessionId, maxLines) {
+    const id = normalizeSessionId(sessionId);
+    if (!id)
+        return [];
+    const st = histories.get(id);
+    if (!st)
+        return [];
+    const limit = clampMaxLines(maxLines);
+    if (limit <= 0)
+        return [];
+    const start = Math.max(0, st.lines.length - limit);
+    return st.lines.slice(start).map((it) => ({ receivedAtMs: it.receivedAtMs, text: it.text }));
+}

package/dist/board_uart/index.js

@@ -0,0 +1,66 @@
+import { getSharedBoardUartManager } from './manager.js';
+import { addSessionConsumer, buildSessionId, closeSession, hasSession, openManualSession, removeSessionConsumer, writeToSession, } from './sessions.js';
+const manager = getSharedBoardUartManager();
+export async function boardUartWrite(params) {
+    if (params.mock) {
+        return manager.writeOnce({
+            port: params.port,
+            baud: params.baud,
+            data: params.data,
+            mock: params.mock,
+            timeoutMs: params.timeoutMs,
+        });
+    }
+    const sessionId = buildSessionId(params.port, params.baud);
+    if (hasSession(sessionId)) {
+        return writeToSession(sessionId, params.data);
+    }
+    // 对尚未存在的会话使用临时会话写入，写完即关闭，避免长时间占用端口锁
+    const session = await openManualSession({ port: params.port, baud: params.baud });
+    try {
+        return await writeToSession(session.id, params.data);
+    }
+    finally {
+        try {
+            await closeSession(session.id);
+        }
+        catch {
+            // ignore close failure
+        }
+    }
+}
+export async function listBoardUartPorts() {
+    return manager.list();
+}
+export async function boardUartStatus() {
+    const s = await manager.status();
+    return {
+        disabled: s.disabled,
+        hasModule: s.hasModule,
+        ports: s.ports,
+        attachedTools: s.attachedTools,
+        status: s.status,
+    };
+}
+export async function openBoardUartStream(params) {
+    const consumerId = `stream-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const sessionId = buildSessionId(params.port, params.baud);
+    const session = await addSessionConsumer({
+        consumerId,
+        sessionId,
+        port: params.port,
+        baud: params.baud,
+        onData: params.onData,
+        onError: params.onError,
+    });
+    let closed = false;
+    return {
+        write: (data) => writeToSession(session.id, data),
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            removeSessionConsumer(session.id, consumerId);
+        },
+    };
+}

package/dist/board_uart/manager.js

@@ -0,0 +1,313 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { DefaultTimeouts, ErrorCodes, error } from '../core/errors.js';
+function envDisabled() {
+    return process.env.DISABLE_BOARD_UART === '1' || process.env.EMBEDLINK_DISABLE_BOARD_UART === '1';
+}
+function isWindows() {
+    return os.platform() === 'win32';
+}
+function normalizePortPath(p) {
+    if (!p)
+        return p;
+    if (isWindows()) {
+        const m = /^(com)(\d+)$/i.exec(p);
+        if (m)
+            return `COM${m[2]}`;
+    }
+    return p;
+}
+export class BoardUartManager {
+    constructor() {
+        this.mod = null;
+        this.modTried = false;
+        this.runtimeDisabled = false;
+    }
+    setRuntimeDisabled(disabled) {
+        this.runtimeDisabled = !!disabled;
+    }
+    isRuntimeDisabled() {
+        return this.runtimeDisabled;
+    }
+    isDisabled() {
+        return envDisabled() || this.runtimeDisabled;
+    }
+    async loadModule() {
+        if (this.modTried)
+            return this.mod;
+        this.modTried = true;
+        try {
+            const m = await import('serialport');
+            if (m && (m.SerialPort || (m.default && m.default.SerialPort))) {
+                this.mod = { SerialPort: m.SerialPort || m.default.SerialPort };
+            }
+            else if (m) {
+                this.mod = { SerialPort: m.SerialPort };
+            }
+        }
+        catch {
+            this.mod = null;
+        }
+        return this.mod;
+    }
+    async isAvailable() {
+        if (this.isDisabled())
+            return false;
+        const m = await this.loadModule();
+        return !!m;
+    }
+    async list() {
+        if (!(await this.isAvailable()))
+            return [];
+        let ports = [];
+        try {
+            const m = (await this.loadModule());
+            // serialport 的 list() 在某些环境会卡死（例如没有权限/驱动异常）。
+            // 这里必须保证快速返回，不能把整个 Agent/Host 链路拖死。
+            const listPromise = Promise.resolve(m.SerialPort?.list?.());
+            const list = await new Promise((resolve) => {
+                const t = setTimeout(() => resolve([]), 800);
+                listPromise
+                    .then((v) => {
+                    clearTimeout(t);
+                    resolve(Array.isArray(v) ? v : []);
+                })
+                    .catch(() => {
+                    clearTimeout(t);
+                    resolve([]);
+                });
+            });
+            if (Array.isArray(list)) {
+                ports = list.map((p) => ({
+                    path: p.path || p.comName || p.friendlyName || String(p),
+                    friendlyName: p.friendlyName || p.manufacturer,
+                }));
+            }
+        }
+        catch {
+            // ignore
+        }
+        // 在非 Windows 环境下，追加 /dev/pts 下的伪终端，方便配合 socat 做虚拟串口联调
+        if (!isWindows()) {
+            ports = this.appendPseudoTtys(ports);
+        }
+        return ports;
+    }
+    async status() {
+        const disabled = this.isDisabled();
+        const mod = disabled ? null : await this.loadModule();
+        const hasModule = !!mod;
+        const ports = hasModule && !disabled ? await this.list() : [];
+        return { disabled, hasModule, ports };
+    }
+    appendPseudoTtys(existing) {
+        const out = [...existing];
+        const seen = new Set(out.map((p) => p.path));
+        const base = '/dev/pts';
+        try {
+            if (!fs.existsSync(base))
+                return out;
+            const names = fs.readdirSync(base);
+            for (const name of names) {
+                // /dev/pts/N，过滤非数字项（如 ptmx）
+                if (!/^\d+$/.test(name))
+                    continue;
+                const full = path.join(base, name);
+                if (seen.has(full))
+                    continue;
+                try {
+                    const st = fs.statSync(full);
+                    if (!st.isCharacterDevice())
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                out.push({
+                    path: full,
+                    friendlyName: 'virtual-tty (pts)',
+                });
+                seen.add(full);
+            }
+        }
+        catch {
+            // 失败时忽略，保持原有端口列表
+        }
+        return out;
+    }
+    async writeOnce(params) {
+        const { port, baud, data } = params;
+        const timeoutMs = params.timeoutMs ?? DefaultTimeouts.boardUart.write;
+        if (params.mock) {
+            throw error(ErrorCodes.EL_INVALID_PARAMS, 'mock is disabled');
+        }
+        if (this.isDisabled()) {
+            throw error(ErrorCodes.EL_BOARD_UART_DISABLED, 'board-uart is disabled by environment');
+        }
+        const mod = await this.loadModule();
+        if (!mod) {
+            throw error(ErrorCodes.EL_BOARD_UART_MODULE_MISSING, 'serialport module is not installed for board-uart');
+        }
+        const ports = await this.list();
+        if (!ports.length) {
+            throw error(ErrorCodes.EL_BOARD_UART_NO_DEVICE, 'no board-uart device detected');
+        }
+        const path = normalizePortPath(port);
+        return await new Promise((resolve, reject) => {
+            let settled = false;
+            const t = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(error(ErrorCodes.EL_BOARD_UART_WRITE_FAILED, 'board-uart write timeout'));
+            }, timeoutMs);
+            try {
+                const sp = new mod.SerialPort({ path, baudRate: baud, autoOpen: false });
+                sp.open((openErr) => {
+                    if (settled)
+                        return;
+                    if (openErr) {
+                        settled = true;
+                        clearTimeout(t);
+                        return reject(error(ErrorCodes.EL_BOARD_UART_OPEN_FAILED, String(openErr)));
+                    }
+                    sp.write(data, (wErr) => {
+                        if (settled)
+                            return;
+                        if (wErr) {
+                            settled = true;
+                            clearTimeout(t);
+                            sp.close?.(() => { });
+                            return reject(error(ErrorCodes.EL_BOARD_UART_WRITE_FAILED, String(wErr)));
+                        }
+                        sp.drain?.(() => {
+                            sp.close?.(() => {
+                                if (settled)
+                                    return;
+                                settled = true;
+                                clearTimeout(t);
+                                resolve(data.length);
+                            });
+                        });
+                    });
+                });
+                sp.on?.('error', (e) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(t);
+                    reject(error(ErrorCodes.EL_BOARD_UART_WRITE_FAILED, String(e)));
+                });
+            }
+            catch (e) {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(t);
+                reject(error(ErrorCodes.EL_BOARD_UART_OPEN_FAILED, String(e)));
+            }
+        });
+    }
+    async openStream(params) {
+        const { port, baud, onData, onError } = params;
+        if (this.isDisabled()) {
+            throw error(ErrorCodes.EL_BOARD_UART_DISABLED, 'board-uart is disabled by environment');
+        }
+        const mod = await this.loadModule();
+        if (!mod) {
+            throw error(ErrorCodes.EL_BOARD_UART_MODULE_MISSING, 'serialport module is not installed for board-uart');
+        }
+        const ports = await this.list();
+        if (!ports.length) {
+            throw error(ErrorCodes.EL_BOARD_UART_NO_DEVICE, 'no board-uart device detected');
+        }
+        const path = normalizePortPath(port);
+        return await new Promise((resolve, reject) => {
+            const timeoutMs = DefaultTimeouts.boardUart.open;
+            let settled = false;
+            let opened = false;
+            let sp;
+            const finishReject = (e) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(t);
+                try {
+                    sp?.close?.(() => { });
+                }
+                catch { }
+                reject(e);
+            };
+            const finishResolve = (payload) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(t);
+                resolve(payload);
+            };
+            const t = setTimeout(() => {
+                finishReject(error(ErrorCodes.EL_BOARD_UART_OPEN_FAILED, `board-uart open timeout after ${timeoutMs} ms`));
+            }, timeoutMs);
+            try {
+                sp = new mod.SerialPort({ path, baudRate: baud, autoOpen: false });
+                const handleError = (e) => {
+                    try {
+                        onError?.(e);
+                    }
+                    catch { }
+                    if (!opened) {
+                        finishReject(error(ErrorCodes.EL_BOARD_UART_OPEN_FAILED, String(e)));
+                    }
+                };
+                sp.on?.('error', handleError);
+                sp.on?.('data', (chunk) => {
+                    try {
+                        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                        onData(buf);
+                    }
+                    catch { }
+                });
+                sp.open((openErr) => {
+                    if (openErr) {
+                        return finishReject(error(ErrorCodes.EL_BOARD_UART_OPEN_FAILED, String(openErr)));
+                    }
+                    opened = true;
+                    finishResolve({
+                        write: (data) => new Promise((resolveWrite, rejectWrite) => {
+                            try {
+                                sp.write(data, (wErr) => {
+                                    if (wErr) {
+                                        return rejectWrite(error(ErrorCodes.EL_BOARD_UART_WRITE_FAILED, String(wErr)));
+                                    }
+                                    sp.drain?.(() => resolveWrite(data.length));
+                                });
+                            }
+                            catch (e) {
+                                rejectWrite(error(ErrorCodes.EL_BOARD_UART_WRITE_FAILED, String(e)));
+                            }
+                        }),
+                        close: () => new Promise((res) => {
+                            try {
+                                sp.close?.(() => res());
+                            }
+                            catch {
+                                res();
+                            }
+                        }),
+                    });
+                });
+            }
+            catch (e) {
+                finishReject(error(ErrorCodes.EL_BOARD_UART_OPEN_FAILED, String(e)));
+            }
+        });
+    }
+}
+let sharedManager = null;
+export function getSharedBoardUartManager() {
+    if (!sharedManager) {
+        sharedManager = new BoardUartManager();
+    }
+    return sharedManager;
+}