@sstar/boardlinker_agent 0.2.0

package/dist/config/index.js

@@ -0,0 +1,341 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import YAML from 'yaml';
+import { DefaultTimeouts } from '../core/errors.js';
+import { LogLevel } from '../logger.js';
+const HOME_CONFIG_PATH = path.join(os.homedir(), '.config', 'board_linker', 'config.json');
+function defaultTftpDir() {
+    return getDefaultAgentFilesDir();
+}
+function defaultShareUsername() {
+    const envUser = process.env.USER || process.env.LOGNAME || process.env.USERNAME;
+    if (envUser && envUser.trim())
+        return envUser.replace(/[\\/]/g, '_');
+    try {
+        const info = os.userInfo();
+        if (info.username && info.username.trim())
+            return info.username.replace(/[\\/]/g, '_');
+    }
+    catch { }
+    return 'user';
+}
+function getDefaultAgentFilesDir() {
+    return path.join(os.homedir(), '.local', 'board_linker', 'agent_files');
+}
+export const DEFAULT_CONFIG = {
+    grpc: { host: '0.0.0.0', port: 10000 },
+    web: { host: '0.0.0.0', port: 8080 },
+    boardUart: {
+        mock: false,
+        port: '',
+        baud: 115200,
+    },
+    network: {},
+    tftp: {
+        dir: getDefaultAgentFilesDir(),
+        server: {
+            enabled: true,
+            mode: 'builtin',
+            host: '0.0.0.0',
+            port: 69,
+        },
+    },
+    nfs: {
+        enabled: true,
+        localPath: getDefaultAgentFilesDir(),
+        exportName: '/shared',
+        description: 'Default NFS export',
+        username: defaultShareUsername(),
+        password: '',
+    },
+    flash: {},
+    ssh: {
+        enablePasswordFallback: true,
+        defaultKeyPath: '',
+    },
+    timeouts: DefaultTimeouts,
+    files: {
+        rootDir: getDefaultAgentFilesDir(),
+        maxFileSize: 100 * 1024 * 1024, // 100MB
+        allowedPaths: [getDefaultAgentFilesDir()],
+        maxTotalBytes: 5 * 1024 * 1024 * 1024, // 5GB
+        maxTotalFiles: 50000,
+        skipHiddenByDefault: false,
+    },
+    logging: {
+        files: {
+            enabled: true,
+            level: LogLevel.DEBUG,
+            includeMetadata: true,
+            maxLogSize: 50 * 1024 * 1024, // 50MB
+            detailedDebug: true,
+            pathResolution: true,
+            securityChecks: true,
+            performanceMetrics: true,
+        },
+    },
+};
+let lastConfigPath = null;
+function defaultKey() {
+    const home = os.homedir();
+    return path.join(home, '.ssh', 'id_rsa');
+}
+function normalize(p) {
+    return path.normalize(p);
+}
+function ensureTftpServerConfig(cfg) {
+    if (!cfg.tftp) {
+        cfg.tftp = {
+            dir: defaultTftpDir(),
+            ttlHours: 24,
+            cleanupIntervalMinutes: 60,
+            server: {
+                enabled: true,
+                mode: 'builtin',
+                host: '0.0.0.0',
+                port: 69,
+                blockSize: 1024, // 1KB块大小（原512字节）
+                timeout: 15000, // 15秒超时（原5000ms）
+                retryCount: 8, // 8次重试（原3次）
+            },
+        };
+        return;
+    }
+    if (!cfg.tftp.server) {
+        cfg.tftp.server = {
+            enabled: true,
+            mode: 'builtin',
+            host: '0.0.0.0',
+            port: 69,
+            blockSize: 512, // 默认 512 字节
+            timeout: 5000, // 默认 5 秒超时
+            retryCount: 3, // 默认 3 次重试
+        };
+    }
+    else {
+        if (typeof cfg.tftp.server.enabled !== 'boolean')
+            cfg.tftp.server.enabled = true;
+        if (!cfg.tftp.server.mode) {
+            cfg.tftp.server.mode = cfg.tftp.server.enabled === false ? 'disabled' : 'builtin';
+        }
+        if (cfg.tftp.server.mode === 'builtin') {
+            if (!cfg.tftp.server.host)
+                cfg.tftp.server.host = '0.0.0.0';
+            if (!cfg.tftp.server.port)
+                cfg.tftp.server.port = 69;
+            if (!cfg.tftp.server.blockSize)
+                cfg.tftp.server.blockSize = 512; // 默认 512 字节
+            if (!cfg.tftp.server.timeout)
+                cfg.tftp.server.timeout = 5000; // 默认 5 秒超时
+            if (!cfg.tftp.server.retryCount)
+                cfg.tftp.server.retryCount = 3; // 默认 3 次重试
+        }
+        if (cfg.tftp.server.mode === 'external') {
+            if (!cfg.tftp.server.externalPort)
+                cfg.tftp.server.externalPort = 69;
+        }
+        if (cfg.tftp.server.mode === 'disabled') {
+            cfg.tftp.server.enabled = false;
+        }
+    }
+}
+function ensureNfsConfig(cfg) {
+    if (!cfg.nfs) {
+        cfg.nfs = {
+            enabled: true,
+            localPath: cfg.tftp?.dir || getDefaultAgentFilesDir(),
+            exportName: '/shared',
+            description: 'Default NFS export',
+            username: defaultShareUsername(),
+            password: '',
+        };
+        return;
+    }
+    if (typeof cfg.nfs.enabled !== 'boolean')
+        cfg.nfs.enabled = true;
+    if (!cfg.nfs.localPath)
+        cfg.nfs.localPath = cfg.tftp?.dir || getDefaultAgentFilesDir();
+    if (!cfg.nfs.exportName)
+        cfg.nfs.exportName = '/shared';
+    if (!cfg.nfs.description)
+        cfg.nfs.description = 'Default NFS export';
+    if (!cfg.nfs.username || !cfg.nfs.username.trim())
+        cfg.nfs.username = defaultShareUsername();
+    if (typeof cfg.nfs.password !== 'string')
+        cfg.nfs.password = '';
+}
+function ensureNetworkConfig(cfg) {
+    if (!cfg.network) {
+        cfg.network = {};
+        return;
+    }
+    if (typeof cfg.network.preferredInterface !== 'string')
+        cfg.network.preferredInterface = '';
+    if (typeof cfg.network.preferredIp !== 'string')
+        cfg.network.preferredIp = '';
+}
+export async function loadConfig() {
+    const cwd = process.cwd();
+    const candidates = [
+        HOME_CONFIG_PATH,
+        path.join(cwd, 'agent.config.yaml'),
+        path.join(cwd, 'agent.config.yml'),
+        path.join(cwd, 'agent.config.json'),
+    ];
+    let cfg = DEFAULT_CONFIG;
+    for (const p of candidates) {
+        try {
+            const raw = await fs.readFile(p, 'utf8');
+            const y = p.endsWith('.json') ? JSON.parse(raw) : YAML.parse(raw);
+            cfg = { ...cfg, ...y };
+            lastConfigPath = p;
+            break;
+        }
+        catch { }
+    }
+    // ENV overrides
+    if (process.env.BOARDLINKER_GRPC_PORT)
+        cfg.grpc.port = Number(process.env.BOARDLINKER_GRPC_PORT);
+    if (process.env.BOARDLINKER_WEB_HOST)
+        cfg.web.host = process.env.BOARDLINKER_WEB_HOST;
+    if (process.env.BOARDLINKER_WEB_PORT)
+        cfg.web.port = Number(process.env.BOARDLINKER_WEB_PORT);
+    if (process.env.BOARDLINKER_TFTP_DIR)
+        cfg.tftp.dir = process.env.BOARDLINKER_TFTP_DIR;
+    if (process.env.BOARDLINKER_TFTP_TTL_HOURS)
+        cfg.tftp.ttlHours = Number(process.env.BOARDLINKER_TFTP_TTL_HOURS);
+    if (process.env.BOARDLINKER_TFTP_CLEANUP_INTERVAL_MIN)
+        cfg.tftp.cleanupIntervalMinutes = Number(process.env.BOARDLINKER_TFTP_CLEANUP_INTERVAL_MIN);
+    ensureTftpServerConfig(cfg);
+    // Board UART defaults / overrides
+    if (process.env.BOARDLINKER_BOARD_UART_PORT)
+        cfg.boardUart.port = process.env.BOARDLINKER_BOARD_UART_PORT;
+    if (process.env.BOARDLINKER_BOARD_UART_BAUD)
+        cfg.boardUart.baud = Number(process.env.BOARDLINKER_BOARD_UART_BAUD);
+    cfg.tftp.dir = normalize(cfg.tftp.dir);
+    ensureNfsConfig(cfg);
+    cfg.nfs.localPath = normalize(cfg.nfs.localPath);
+    // SSH 默认密钥路径：始终基于当前用户主目录计算，可通过环境变量覆盖
+    const envDefaultKey = (process.env.BOARDLINKER_SSH_DEFAULT_KEY || '').trim();
+    if (!cfg.ssh) {
+        cfg.ssh = {
+            enablePasswordFallback: true,
+            defaultKeyPath: envDefaultKey || defaultKey(),
+        };
+    }
+    else {
+        cfg.ssh.enablePasswordFallback =
+            typeof cfg.ssh.enablePasswordFallback === 'boolean' ? cfg.ssh.enablePasswordFallback : true;
+        cfg.ssh.defaultKeyPath = envDefaultKey || defaultKey();
+    }
+    if (!cfg.agent)
+        cfg.agent = { id: defaultAgentId() };
+    if (!cfg.agent.id)
+        cfg.agent.id = makeDefaultAgentId(os.hostname?.() || 'host', cfg.grpc.port);
+    if (process.env.BOARDLINKER_AGENT_ID)
+        cfg.agent.id = process.env.BOARDLINKER_AGENT_ID;
+    ensureNetworkConfig(cfg);
+    // 文件操作日志配置的环境变量支持
+    if (!cfg.logging)
+        cfg.logging = {};
+    if (!cfg.logging.files)
+        cfg.logging.files = DEFAULT_CONFIG.logging.files;
+    // 环境变量覆盖文件操作日志配置
+    if (process.env.BOARDLINKER_FILES_LOG_ENABLED !== undefined && cfg.logging.files) {
+        cfg.logging.files.enabled =
+            process.env.BOARDLINKER_FILES_LOG_ENABLED === '1' ||
+                process.env.BOARDLINKER_FILES_LOG_ENABLED === 'true';
+    }
+    if (process.env.BOARDLINKER_FILES_LOG_LEVEL && cfg.logging.files) {
+        cfg.logging.files.level = process.env.BOARDLINKER_FILES_LOG_LEVEL;
+    }
+    if (process.env.BOARDLINKER_FILES_LOG_INCLUDE_METADATA !== undefined && cfg.logging.files) {
+        cfg.logging.files.includeMetadata =
+            process.env.BOARDLINKER_FILES_LOG_INCLUDE_METADATA === '1' ||
+                process.env.BOARDLINKER_FILES_LOG_INCLUDE_METADATA === 'true';
+    }
+    if (process.env.BOARDLINKER_FILES_LOG_MAX_SIZE && cfg.logging.files) {
+        const sizeStr = process.env.BOARDLINKER_FILES_LOG_MAX_SIZE;
+        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) {
+            const value = parseInt(match[1]);
+            const unit = match[2]?.toUpperCase() || 'B';
+            cfg.logging.files.maxLogSize = value * (units[unit] || 1);
+        }
+    }
+    if (process.env.BOARDLINKER_FILES_LOG_DETAILED_DEBUG !== undefined && cfg.logging.files) {
+        cfg.logging.files.detailedDebug =
+            process.env.BOARDLINKER_FILES_LOG_DETAILED_DEBUG === '1' ||
+                process.env.BOARDLINKER_FILES_LOG_DETAILED_DEBUG === 'true';
+    }
+    if (process.env.BOARDLINKER_FILES_LOG_PATH_RESOLUTION !== undefined && cfg.logging.files) {
+        cfg.logging.files.pathResolution =
+            process.env.BOARDLINKER_FILES_LOG_PATH_RESOLUTION === '1' ||
+                process.env.BOARDLINKER_FILES_LOG_PATH_RESOLUTION === 'true';
+    }
+    if (process.env.BOARDLINKER_FILES_LOG_SECURITY_CHECKS !== undefined && cfg.logging.files) {
+        cfg.logging.files.securityChecks =
+            process.env.BOARDLINKER_FILES_LOG_SECURITY_CHECKS === '1' ||
+                process.env.BOARDLINKER_FILES_LOG_SECURITY_CHECKS === 'true';
+    }
+    if (process.env.BOARDLINKER_FILES_LOG_PERFORMANCE_METRICS !== undefined && cfg.logging.files) {
+        cfg.logging.files.performanceMetrics =
+            process.env.BOARDLINKER_FILES_LOG_PERFORMANCE_METRICS === '1' ||
+                process.env.BOARDLINKER_FILES_LOG_PERFORMANCE_METRICS === 'true';
+    }
+    // 统一文件存储路径：确保 Files 系统使用与 TFTP/NFS 相同的配置路径
+    // 这符合 Settings 页面"Local Artifacts Path"的设计意图
+    if (!cfg.files) {
+        cfg.files = DEFAULT_CONFIG.files;
+    }
+    // 如果用户在 Settings 页面配置了统一的 artifacts 路径（通过 tftp.dir），
+    // 则 Files 系统也使用相同路径，实现统一的文件存储管理
+    if (cfg.tftp && cfg.tftp.dir) {
+        cfg.files.rootDir = cfg.tftp.dir;
+        // 同时更新 allowedPaths，确保 Files 系统可以访问该路径
+        if (!cfg.files.allowedPaths || cfg.files.allowedPaths.length === 0) {
+            cfg.files.allowedPaths = [cfg.tftp.dir];
+        }
+        else if (!cfg.files.allowedPaths.includes(cfg.tftp.dir)) {
+            // 将统一路径添加到 allowedPaths 的开头，优先使用
+            cfg.files.allowedPaths = [
+                cfg.tftp.dir,
+                ...cfg.files.allowedPaths.filter((p) => p !== cfg.tftp.dir),
+            ];
+        }
+    }
+    if (!lastConfigPath)
+        lastConfigPath = HOME_CONFIG_PATH;
+    return cfg;
+}
+export function getConfigPath() {
+    return lastConfigPath || HOME_CONFIG_PATH;
+}
+export async function saveConfig(cfg, targetPath) {
+    const outPath = targetPath || getConfigPath();
+    const content = outPath.endsWith('.json') || outPath.endsWith('.json5')
+        ? JSON.stringify(cfg, null, 2)
+        : YAML.stringify(cfg);
+    await fs.mkdir(path.dirname(outPath), { recursive: true });
+    await fs.writeFile(outPath, content, 'utf8');
+    lastConfigPath = outPath;
+    return outPath;
+}
+function defaultAgentId() {
+    const seed = `${process.cwd()}|${process.pid}|${Date.now()}`;
+    let h = 5381;
+    for (let i = 0; i < seed.length; i++)
+        h = (h << 5) + h + seed.charCodeAt(i);
+    return `agent-${(h >>> 0).toString(16)}`;
+}
+function makeDefaultAgentId(hostname, port) {
+    const raw = `agent-${hostname}-${port}`;
+    return raw.replace(/[^A-Za-z0-9._-]/g, '-');
+}

package/dist/core/activity.js

@@ -0,0 +1,7 @@
+export let lastGrpcActivity = 0;
+export function markGrpcActivity() {
+    lastGrpcActivity = Date.now();
+}
+export function getGrpcLastActivity() {
+    return lastGrpcActivity;
+}

package/dist/core/errors.js

@@ -0,0 +1,45 @@
+export const ErrorCodes = {
+    EL_AGENT_UNAVAILABLE: 'EL_AGENT_UNAVAILABLE',
+    EL_PROCEDURE_TIMEOUT: 'EL_PROCEDURE_TIMEOUT',
+    EL_INVALID_PARAMS: 'EL_INVALID_PARAMS',
+    EL_BOARD_UART_OPEN_FAILED: 'EL_BOARD_UART_OPEN_FAILED',
+    EL_BOARD_UART_WRITE_FAILED: 'EL_BOARD_UART_WRITE_FAILED',
+    EL_BOARD_UART_READ_IN_PROGRESS: 'EL_BOARD_UART_READ_IN_PROGRESS',
+    EL_BOARD_UART_READ_TIMEOUT: 'EL_BOARD_UART_READ_TIMEOUT',
+    EL_BOARD_UART_MODULE_MISSING: 'EL_BOARD_UART_MODULE_MISSING',
+    EL_BOARD_UART_NO_DEVICE: 'EL_BOARD_UART_NO_DEVICE',
+    EL_BOARD_UART_DISABLED: 'EL_BOARD_UART_DISABLED',
+    EL_BOARD_UART_SESSION_NOT_FOUND: 'EL_BOARD_UART_SESSION_NOT_FOUND',
+    EL_BOARD_UART_SESSION_TEMPORARILY_UNAVAILABLE: 'EL_BOARD_UART_SESSION_TEMPORARILY_UNAVAILABLE',
+    EL_BOARD_UART_READONLY_SESSION: 'EL_BOARD_UART_READONLY_SESSION',
+    EL_BOARD_UART_SUSPENDED: 'EL_BOARD_UART_SUSPENDED',
+    EL_TFTP_UPLOAD_FAILED: 'EL_TFTP_UPLOAD_FAILED',
+    EL_TFTP_VERIFY_FAILED: 'EL_TFTP_VERIFY_FAILED',
+    EL_TFTP_DISABLED: 'EL_TFTP_DISABLED',
+    EL_TFTP_SERVER_ALREADY_RUNNING: 'EL_TFTP_SERVER_ALREADY_RUNNING',
+    EL_TFTP_SERVER_START_FAILED: 'EL_TFTP_SERVER_START_FAILED',
+    EL_UBOOT_BREAK_TIMEOUT: 'EL_UBOOT_BREAK_TIMEOUT',
+    EL_UBOOT_CMD_FAILED: 'EL_UBOOT_CMD_FAILED',
+    EL_FLASH_WRITE_FAILED: 'EL_FLASH_WRITE_FAILED',
+    EL_FLASH_VERIFY_FAILED: 'EL_FLASH_VERIFY_FAILED',
+    EL_REBOOT_TIMEOUT: 'EL_REBOOT_TIMEOUT',
+    EL_SSH_CONNECT_FAILED: 'EL_SSH_CONNECT_FAILED',
+    EL_SSH_TUNNEL_BROKEN: 'EL_SSH_TUNNEL_BROKEN',
+    EL_NFS_DISABLED: 'EL_NFS_DISABLED',
+};
+export const DefaultTimeouts = {
+    boardUart: { open: 3000, read: 5000, write: 5000 },
+    tftp: { upload: 120000 },
+    uboot: { break: 5000, cmd: 10000 },
+    flash: { write: 300000 },
+    reboot: { wait: 60000 },
+    ssh: { connect: 15000 },
+};
+export function error(code, message, data) {
+    const fullMessage = `[${code}] ${message}`;
+    const e = new Error(fullMessage);
+    e.code = code;
+    if (data)
+        e.data = data;
+    return e;
+}

package/dist/core/log_stream.js

@@ -0,0 +1,26 @@
+const MAX_LOG_BUFFER = 1000;
+const agentLogBuf = [];
+const hostLogBuf = [];
+const listeners = new Set();
+function pushBounded(buf, entry) {
+    buf.push(entry);
+    if (buf.length > MAX_LOG_BUFFER)
+        buf.splice(0, buf.length - MAX_LOG_BUFFER);
+}
+export function publishAgentLog(entry) {
+    pushBounded(agentLogBuf, entry);
+    for (const l of listeners)
+        l('agent', entry);
+}
+export function publishHostLog(entry) {
+    pushBounded(hostLogBuf, entry);
+    for (const l of listeners)
+        l('host', entry);
+}
+export function getLogSnapshot(source) {
+    return source === 'agent' ? [...agentLogBuf] : [...hostLogBuf];
+}
+export function subscribeLogs(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}

package/dist/files/file_operation_logger.js

@@ -0,0 +1,271 @@
+import path from 'node:path';
+import { LogLevel, logAgentDebug } from '../logger.js';
+// 文件操作日志事件类型
+export var FileOperationEvent;
+(function (FileOperationEvent) {
+    // 通用事件
+    FileOperationEvent["OPERATION_START"] = "files.operation.start";
+    FileOperationEvent["OPERATION_SUCCESS"] = "files.operation.success";
+    FileOperationEvent["OPERATION_ERROR"] = "files.operation.error";
+    // PUT操作事件
+    FileOperationEvent["PUT_VALIDATION_START"] = "files.put.validation.start";
+    FileOperationEvent["PUT_VALIDATION_SUCCESS"] = "files.put.validation.success";
+    FileOperationEvent["PUT_META_SENT"] = "files.put.meta.sent";
+    FileOperationEvent["PUT_FILE_START"] = "files.put.file.start";
+    FileOperationEvent["PUT_FILE_PROGRESS"] = "files.put.file.progress";
+    FileOperationEvent["PUT_FILE_SUCCESS"] = "files.put.file.success";
+    FileOperationEvent["PUT_CLEANUP"] = "files.put.cleanup";
+    // GET操作事件
+    FileOperationEvent["GET_VALIDATION_START"] = "files.get.validation.start";
+    FileOperationEvent["GET_VALIDATION_SUCCESS"] = "files.get.validation.success";
+    FileOperationEvent["GET_REQUEST_SENT"] = "files.get.request.sent";
+    FileOperationEvent["GET_FILE_START"] = "files.get.file.start";
+    FileOperationEvent["GET_FILE_PROGRESS"] = "files.get.file.progress";
+    FileOperationEvent["GET_FILE_SUCCESS"] = "files.get.file.success";
+    // 路径解析和安全检查
+    FileOperationEvent["PATH_RESOLUTION_START"] = "files.path.resolution.start";
+    FileOperationEvent["PATH_RESOLUTION_SUCCESS"] = "files.path.resolution.success";
+    FileOperationEvent["PATH_NORMALIZATION"] = "files.path.normalization";
+    FileOperationEvent["PATH_SECURITY_CHECK"] = "files.path.security_check";
+    FileOperationEvent["PATH_FINAL_CONSTRUCTION"] = "files.path.final_construction";
+    FileOperationEvent["SECURITY_CHECK_START"] = "files.security.check.start";
+    FileOperationEvent["SECURITY_CHECK_SUCCESS"] = "files.security.check.success";
+    FileOperationEvent["SECURITY_CHECK_FAILED"] = "files.security.check.failed";
+    // 文件操作过程
+    FileOperationEvent["COPY_START"] = "files.copy.start";
+    FileOperationEvent["COPY_SUCCESS"] = "files.copy.success";
+    FileOperationEvent["DIRECTORY_CREATED"] = "files.directory.created";
+    // 重试和错误处理
+    FileOperationEvent["RETRY_ATTEMPT"] = "files.retry.attempt";
+    FileOperationEvent["RETRY_SUCCESS"] = "files.retry.success";
+    FileOperationEvent["RETRY_EXHAUSTED"] = "files.retry.exhausted";
+    FileOperationEvent["RESOURCE_CLEANUP"] = "files.resource.cleanup";
+    // 其他操作
+    FileOperationEvent["LIST_START"] = "files.list.start";
+    FileOperationEvent["LIST_SUCCESS"] = "files.list.success";
+    FileOperationEvent["MKDIR_START"] = "files.mkdir.start";
+    FileOperationEvent["MKDIR_SUCCESS"] = "files.mkdir.success";
+    FileOperationEvent["RM_START"] = "files.rm.start";
+    FileOperationEvent["RM_SUCCESS"] = "files.rm.success";
+})(FileOperationEvent || (FileOperationEvent = {}));
+// 文件操作上下文管理
+export class FileOperationContext {
+    constructor(requestId, operation, initialData = {}) {
+        this.completed = false;
+        this.success = false;
+        this.requestId = requestId;
+        this.operation = operation;
+        this.startTime = Date.now();
+        this.agentPid = process.pid;
+        this.data = {
+            ...initialData,
+            operation,
+            requestId,
+            startTime: this.startTime,
+            agentPid: this.agentPid,
+            stage: 'started',
+        };
+    }
+    // 更新上下文数据
+    update(newData) {
+        this.data = { ...this.data, ...newData };
+    }
+    // 标记操作成功
+    markSuccess() {
+        this.completed = true;
+        this.success = true;
+        this.data.duration = Date.now() - this.startTime;
+        this.data.stage = 'success';
+    }
+    // 标记操作失败
+    markError(error) {
+        this.completed = true;
+        this.success = false;
+        this.error = error;
+        this.data.duration = Date.now() - this.startTime;
+        this.data.stage = 'error';
+        this.data.errorCode = error.name;
+        this.data.errorMessage = error.message;
+        this.data.errorStack = error.stack;
+    }
+    // 转换为日志数据格式
+    toLogData() {
+        return {
+            operation: this.operation,
+            requestId: this.requestId,
+            startTime: this.startTime,
+            agentPid: this.agentPid,
+            duration: this.data.duration,
+            stage: this.data.stage || 'unknown',
+            ...this.data,
+        };
+    }
+    // 检查是否已完成
+    isCompleted() {
+        return this.completed;
+    }
+    // 检查是否成功
+    isSuccess() {
+        return this.success;
+    }
+    // 获取错误信息
+    getError() {
+        return this.error;
+    }
+}
+// 文件操作日志记录器
+export class FileOperationLogger {
+    constructor(agentLogger, agentId = 'unknown') {
+        this.activeOperations = new Map();
+        this.agentLogger = agentLogger;
+        this.agentId = agentId;
+    }
+    // 开始操作记录
+    startOperation(operation, data = {}) {
+        const requestId = this.generateRequestId();
+        const context = new FileOperationContext(requestId, operation, {
+            ...data,
+            agentId: this.agentId,
+        });
+        this.activeOperations.set(requestId, context);
+        this.agentLogger.write(LogLevel.DEBUG, FileOperationEvent.OPERATION_START, {
+            ...context.toLogData(),
+            stage: 'start',
+        });
+        return requestId;
+    }
+    // 记录操作成功
+    logSuccess(requestId, data = {}) {
+        const context = this.activeOperations.get(requestId);
+        if (!context) {
+            logAgentDebug('file_operation.logger', {
+                warning: 'Attempted to log success for unknown requestId',
+                requestId,
+            });
+            return;
+        }
+        context.update(data);
+        context.markSuccess();
+        this.agentLogger.write(LogLevel.INFO, FileOperationEvent.OPERATION_SUCCESS, {
+            ...context.toLogData(),
+            stage: 'success',
+        });
+        this.activeOperations.delete(requestId);
+    }
+    // 记录操作失败
+    logError(requestId, error, data = {}) {
+        const context = this.activeOperations.get(requestId);
+        if (!context) {
+            logAgentDebug('file_operation.logger', {
+                warning: 'Attempted to log error for unknown requestId',
+                requestId,
+                errorMessage: error.message,
+            });
+            return;
+        }
+        context.update(data);
+        context.markError(error);
+        this.agentLogger.write(LogLevel.ERROR, FileOperationEvent.OPERATION_ERROR, {
+            ...context.toLogData(),
+            stage: 'error',
+            errorCode: error.name,
+            errorMessage: error.message,
+            errorStack: error.stack,
+        });
+        this.activeOperations.delete(requestId);
+    }
+    // 记录调试信息
+    logDebug(requestId, event, data = {}) {
+        const context = this.activeOperations.get(requestId);
+        if (!context) {
+            logAgentDebug('file_operation.logger', {
+                warning: 'Attempted to log debug for unknown requestId',
+                requestId,
+                event,
+            });
+            return;
+        }
+        context.update(data);
+        this.agentLogger.write(LogLevel.DEBUG, event, {
+            ...context.toLogData(),
+            stage: 'debug',
+        });
+    }
+    // 记录路径转换过程
+    logPathTransformation(requestId, inputPath, rootDir) {
+        const transformation = {
+            input: inputPath,
+            normalized: '',
+            securityChecked: '',
+            final: '',
+        };
+        // 1. 路径标准化
+        transformation.normalized = path.normalize(inputPath);
+        this.logDebug(requestId, FileOperationEvent.PATH_NORMALIZATION, {
+            input: transformation.input,
+            normalized: transformation.normalized,
+            debugInfo: {
+                explanation: 'path.normalize() applied to remove redundant separators and resolve relative references',
+            },
+        });
+        // 2. 安全路径检查
+        transformation.securityChecked = transformation.normalized.replace(/^(\.\.[\/\\])+/, '');
+        this.logDebug(requestId, FileOperationEvent.PATH_SECURITY_CHECK, {
+            normalized: transformation.normalized,
+            securityChecked: transformation.securityChecked,
+            debugInfo: {
+                explanation: 'Removed potential directory traversal patterns',
+            },
+        });
+        // 3. 最终路径构建
+        transformation.final = path.join(rootDir, transformation.securityChecked);
+        this.logDebug(requestId, FileOperationEvent.PATH_FINAL_CONSTRUCTION, {
+            rootDir: rootDir,
+            securityChecked: transformation.securityChecked,
+            final: transformation.final,
+            debugInfo: {
+                explanation: `Joined with root directory: ${rootDir}`,
+            },
+        });
+        return transformation;
+    }
+    // 生成唯一请求ID
+    generateRequestId() {
+        return `files_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    // 获取活跃操作数量
+    getActiveOperationCount() {
+        return this.activeOperations.size;
+    }
+    // 获取指定操作的上下文
+    getOperationContext(requestId) {
+        return this.activeOperations.get(requestId);
+    }
+    // 清理超时操作（防止内存泄漏）
+    cleanupTimeoutOperations(timeoutMs = 300000) {
+        // 默认5分钟超时
+        const now = Date.now();
+        const timeoutIds = [];
+        for (const [requestId, context] of this.activeOperations.entries()) {
+            if (now - context.startTime > timeoutMs) {
+                timeoutIds.push(requestId);
+            }
+        }
+        for (const requestId of timeoutIds) {
+            const context = this.activeOperations.get(requestId);
+            if (context) {
+                this.logDebug(requestId, 'files.operation.timeout', {
+                    warning: 'Operation timed out and cleaned up',
+                    duration: now - context.startTime,
+                });
+                this.activeOperations.delete(requestId);
+            }
+        }
+        if (timeoutIds.length > 0) {
+            logAgentDebug('file_operation.logger', {
+                message: `Cleaned up ${timeoutIds.length} timeout operations`,
+                timeoutIds,
+            });
+        }
+    }
+}