ai-helper-agent 1.11.0 → 1.12.0

package/bin/agent.js

@@ -399,6 +399,128 @@ if (command === 'start') {
   console.log(`[Agent] 工作目录: ${cfg.workdir}`);
   restartServer();
 
+// ==================== _restart-helper（内部命令，两阶段重启包装器） ====================
+} else if (command === '_restart-helper') {
+  // 由 /api/agent/restart 和 /api/agent/update 调用，detached 运行
+  // 职责：等待老进程退出 + 端口释放后，再以 --background 模式启动新进程
+  // 解决直接 spawn 新进程时 isRunning 检查劝退、端口 EADDRINUSE 的时序问题
+  const helperConfig = applyCliArgs({ port: 18910, host: '127.0.0.1' }, process.argv.slice(3));
+  const oldPidIdx = process.argv.indexOf('--old-pid');
+  const oldPid = oldPidIdx > -1 ? parseInt(process.argv[oldPidIdx + 1], 10) : 0;
+  const scriptIdx = process.argv.indexOf('--script');
+  const agentScript = scriptIdx > -1 ? process.argv[scriptIdx + 1] : process.argv[1];
+
+  const port = helperConfig.port;
+  const host = helperConfig.host;
+  const workdir = helperConfig.workdir || process.cwd();
+
+  const log = (msg) => console.log(`[Agent Restart Helper] ${msg}`);
+  log(`等待老进程 ${oldPid} 退出...`);
+
+  // 1. 等待老进程退出（轮询 PID 探活，process.kill(pid,0) 不发信号只检测存在性）
+  const waitForOldExit = (pid, timeoutMs = 15000) => new Promise((resolve) => {
+    if (!pid) return resolve(true);
+    const start = Date.now();
+    const timer = setInterval(() => {
+      try {
+        process.kill(pid, 0);
+      } catch {
+        clearInterval(timer);
+        resolve(true);
+        return;
+      }
+      if (Date.now() - start > timeoutMs) {
+        clearInterval(timer);
+        log('等待老进程退出超时，尝试强制终止...');
+        try { process.kill(pid, 'SIGKILL'); } catch {}
+        resolve(false);
+      }
+    }, 200);
+  });
+
+  // 2. 等待端口释放（fetch /api/status 失败即视为释放）
+  const waitForPortRelease = async (host, port, timeoutMs = 10000) => {
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+      try {
+        const resp = await fetch(`http://${host}:${port}/api/status`);
+        if (resp.ok) {
+          await new Promise(r => setTimeout(r, 300));
+          continue;
+        }
+      } catch {
+        return true;
+      }
+    }
+    return false;
+  };
+
+  (async () => {
+    await waitForOldExit(oldPid);
+    await waitForPortRelease(host, port);
+    // 额外等待，确保 socket 完全回收
+    await new Promise(r => setTimeout(r, 500));
+
+    log('老进程已退出，端口已释放，启动新进程...');
+
+    // 清理旧 PID 文件，避免新进程 isRunning 检查误判
+    removePidFile();
+    ensureAgentDir();
+
+    // 直接以前台模式启动服务进程（不经过 --background 中间层）
+    // 原因：--background 会多 spawn 一层中间进程，中间进程退出后其 PID 会被
+    //   本 helper 覆盖写入 PID 文件，导致 stop/restart 读到已死的中间进程 PID。
+    //   前台模式下 child.pid 就是服务进程 PID，与服务进程自身写入的 PID 一致。
+    //   前台 start 不会 isRunning 检查，但本 helper 已确保老进程退出 + 端口释放。
+    const child = spawn(process.execPath, [
+      ...process.execArgv,
+      agentScript,
+      'start',
+      '--port', String(port),
+      '--host', host,
+      '--workdir', workdir
+    ], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: process.cwd(),
+      env: { ...process.env },
+      windowsHide: true
+    });
+
+    let spawnFailed = false;
+    child.on('error', (err) => {
+      spawnFailed = true;
+      log(`启动失败: ${err.message}`);
+      process.exit(1);
+    });
+
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    // 健康检查：确认服务进程已成功监听端口，避免写入已崩溃进程的 PID
+    // （若端口意外未释放导致 EADDRINUSE，服务进程会崩溃，此时不应写错误 PID）
+    let healthy = false;
+    if (!spawnFailed && child.pid) {
+      try {
+        const resp = await fetch(`http://${host}:${port}/api/status`);
+        healthy = resp.ok;
+      } catch {}
+    }
+
+    if (healthy && child.pid) {
+      try {
+        writeFileSync(PID_FILE, String(child.pid));
+      } catch (err) {
+        log(`PID 文件写入失败: ${err.message}`);
+      }
+      child.unref();
+      log(`新进程已启动 (PID: ${child.pid})`);
+    } else if (!spawnFailed && child.pid) {
+      log(`警告：新进程健康检查失败，未更新 PID 文件（可能端口仍被占用或进程已崩溃）`);
+    }
+
+    process.exit(spawnFailed ? 1 : 0);
+  })();
+
 // ==================== status ====================
 } else if (command === 'status') {
   const config = readAgentConfig();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-helper-agent",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "AI Helper 代理服务 - 为 Chrome 扩展提供本地文件读写和系统命令执行能力",
   "type": "module",
   "main": "./src/server.js",
@@ -23,6 +23,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "archiver": "^8.0.0",
     "ws": "^8.18.0",
+    "xlsx": "^0.18.5",
     "zod": "^4.4.3"
   },
   "engines": {

package/src/executor.js

@@ -54,8 +54,25 @@ function getShellForExec() {
 // 运行中的进程映射：execId → { process, wsClients: Set, timeoutId, forceKillId, stdoutBuf, stderrBuf }
 const runningProcesses = new Map();
 
-// 已完成进程缓存（解决竞态条件：进程完成太快，WebSocket 客户端来不及连接）
-// execId → { stdoutBuf, stderrBuf, exitCode, killed, cleanupTimeout }
+// 输出缓冲区上限（5MB），防止长时间命令内存无限增长
+const MAX_OUTPUT_BUFFER = 5 * 1024 * 1024;
+
+/**
+ * 安全追加字符串到缓冲区，超过上限时截断并标记
+ * @param {string} buf - 当前缓冲区
+ * @param {string} chunk - 要追加的字符串
+ * @param {object} truncState - 截断状态对象 { truncated: boolean }
+ * @returns {string} 更新后的缓冲区
+ */
+function appendWithLimit(buf, chunk, truncState) {
+  if (truncState.truncated) return buf;
+  if (buf.length + chunk.length > MAX_OUTPUT_BUFFER) {
+    truncState.truncated = true;
+    const remaining = MAX_OUTPUT_BUFFER - buf.length;
+    return buf + (remaining > 0 ? chunk.slice(0, remaining) : '');
+  }
+  return buf + chunk;
+}
 const completedProcesses = new Map();
 const COMPLETED_CACHE_TTL = 30000; // 30秒后清理
 
@@ -120,6 +137,7 @@ function executeCommand(command, cwd, wsClient, onComplete, collectOutput = fals
     cwd: workdir,
     env: buildSafeEnv(),
     stdio: ['ignore', 'pipe', 'pipe'],
+    detached: true,       // 独立进程组，防止 kill 父进程后子进程成为孤儿
     windowsHide: true
   });
 
@@ -133,7 +151,8 @@ function executeCommand(command, cwd, wsClient, onComplete, collectOutput = fals
 
   // 存储到 entry 中供 clearTimers 读取
   // stdoutBuf/stderrBuf 始终收集，用于回放给延迟连接的 WS 客户端
-  const entry = { process: proc, wsClients, stdoutBuf: '', stderrBuf: '' };
+  // command/startTime 用于状态详情面板展示运行中进程
+  const entry = { process: proc, wsClients, stdoutBuf: '', stderrBuf: '', truncStdout: false, truncStderr: false, command, startTime: Date.now() };
   runningProcesses.set(execId, entry);
 
   // 超时控制
@@ -166,7 +185,12 @@ function executeCommand(command, cwd, wsClient, onComplete, collectOutput = fals
   proc.stdout.on('data', (chunk) => {
     const str = chunk.toString();
     if (collectOutput) stdoutCollected += str;
-    entry.stdoutBuf += str;
+    const truncState = { truncated: entry.truncStdout };
+    entry.stdoutBuf = appendWithLimit(entry.stdoutBuf, str, truncState);
+    entry.truncStdout = truncState.truncated;
+    if (truncState.truncated) {
+      broadcast({ type: 'stdout_truncated', message: 'stdout 输出超过 5MB 上限，已截断', execId });
+    }
     broadcast({ type: 'stdout', data: str, execId });
   });
 
@@ -174,7 +198,12 @@ function executeCommand(command, cwd, wsClient, onComplete, collectOutput = fals
   proc.stderr.on('data', (chunk) => {
     const str = chunk.toString();
     if (collectOutput) stderrCollected += str;
-    entry.stderrBuf += str;
+    const truncState = { truncated: entry.truncStderr };
+    entry.stderrBuf = appendWithLimit(entry.stderrBuf, str, truncState);
+    entry.truncStderr = truncState.truncated;
+    if (truncState.truncated) {
+      broadcast({ type: 'stderr_truncated', message: 'stderr 输出超过 5MB 上限，已截断', execId });
+    }
     broadcast({ type: 'stderr', data: str, execId });
   });
 
@@ -326,9 +355,9 @@ function disconnectWsClient(execId, wsClient) {
 }
 
 /**
- * 停止正在运行的命令（跨平台兼容）
- * - macOS/Linux: SIGTERM（优雅终止）→ 5s → SIGKILL（强制杀）
- * - Windows: taskkill /PID（优雅终止）→ 5s → taskkill /F /PID（强制杀）
+ * 停止正在运行的命令（跨平台兼容，递归终止全部子进程）
+ * - macOS/Linux: SIGTERM to process group（-pid）→ 5s → SIGKILL to process group
+ * - Windows: taskkill /T /PID（递归终止进程树）→ 5s → taskkill /F /T /PID
  */
 function killProcess(execId) {
   const entry = runningProcesses.get(execId);
@@ -340,18 +369,20 @@ function killProcess(execId) {
   const pid = entry.process.pid;
 
   if (isWin) {
-    // Windows: taskkill 支持优雅终止（/PID 发送 WM_CLOSE）和强制终止（/F）
-    exec(`taskkill /PID ${pid}`, (err) => {
+    // Windows: /T 递归终止整个进程树
+    exec(`taskkill /T /PID ${pid}`, (err) => {
       if (err) {
-        // 尝试强制杀
-        exec(`taskkill /F /PID ${pid}`, () => {});
+        exec(`taskkill /F /T /PID ${pid}`, () => {});
       }
     });
   } else {
-    // macOS/Linux: SIGTERM 优雅终止
+    // Unix: 负 PID 表示杀整个进程组（detached + 未调用 setsid 时有效）
     try {
-      entry.process.kill('SIGTERM');
-    } catch {}
+      process.kill(-pid, 'SIGTERM');
+    } catch {
+      // 回退到单进程
+      try { entry.process.kill('SIGTERM'); } catch {}
+    }
   }
 
   // 清理旧的定时器
@@ -363,14 +394,15 @@ function killProcess(execId) {
     clearTimeout(entry.forceKillId);
   }
 
-  // 5秒后强制杀（绑定到 entry 对象防止闭包引用旧变量）
+  // 5秒后强制杀整个进程组
   entry.forceKillId = setTimeout(() => {
     try {
       if (entry.process.exitCode === null) {
         if (isWin) {
-          exec(`taskkill /F /PID ${pid}`, () => {});
+          exec(`taskkill /F /T /PID ${pid}`, () => {});
         } else {
-          entry.process.kill('SIGKILL');
+          try { process.kill(-pid, 'SIGKILL'); }
+          catch { try { entry.process.kill('SIGKILL'); } catch {} }
         }
       }
     } catch {}
@@ -382,11 +414,19 @@ function killProcess(execId) {
 
 /**
  * 获取运行中的进程列表
+ * 返回每个进程的 execId、pid、command、startTime、duration（已运行毫秒数）
  */
 function getRunningProcesses() {
+  const now = Date.now();
   const list = [];
-  for (const [execId] of runningProcesses) {
-    list.push({ execId });
+  for (const [execId, entry] of runningProcesses) {
+    list.push({
+      execId,
+      pid: entry.process && entry.process.pid ? entry.process.pid : null,
+      command: entry.command || '',
+      startTime: entry.startTime || null,
+      duration: entry.startTime ? now - entry.startTime : 0
+    });
   }
   return list;
 }

package/src/mcp/client.js

@@ -99,7 +99,6 @@ export class McpClient {
       this.connected = true;
       return { success: true, toolCount: this.tools.length };
     } catch (err) {
-      console.error(`[MCP:${this.serverId}] 连接失败:`, err.message);
       this.disconnect();
       return { success: false, error: err.message };
     }

package/src/mcp/registry.js

@@ -32,10 +32,8 @@ export async function initializeMcpRegistry() {
 
   if (config.servers.length > 0) {
     if (failed > 0) {
-      console.log(`[MCP] ${connected}/${config.servers.length} 已连接`);
-      for (const fs of failedServers) {
-        console.error(`[MCP] ${fs.id} 连接失败: ${fs.error}`);
-      }
+      const failedList = failedServers.map(fs => `${fs.id}(${fs.error})`).join(', ');
+      console.warn(`[MCP] ${connected}/${config.servers.length} 已连接，${failed} 个失败: ${failedList}`);
     } else if (connected > 0) {
       console.log(`[MCP] ${connected} 个 Server 已连接`);
     }

package/src/search.js

@@ -112,11 +112,12 @@ function searchWithFd(rootPath, filePattern, recursive, maxResults) {
       const output = Buffer.concat(stdout).toString('utf-8').trim();
       const lines = output ? output.split('\n').filter(Boolean) : [];
       const results = lines.map(p => {
+        const absPath = join(rootPath, p);
         try {
-          const s = statSync(p);
-          return { path: p, name: basename(p), type: s.isDirectory() ? 'directory' : 'file', size: s.size, mtime: s.mtimeMs };
+          const s = statSync(absPath);
+          return { path: absPath, name: basename(p), type: s.isDirectory() ? 'directory' : 'file', size: s.size, mtime: s.mtimeMs };
         } catch {
-          return { path: p, name: basename(p), type: 'file', size: 0, mtime: 0 };
+          return { path: absPath, name: basename(p), type: 'file', size: 0, mtime: 0 };
         }
       });
       resolve(results);

package/src/security.js

@@ -28,6 +28,9 @@ const HARD_BLOCKED_PATHS = [
   join(AGENT_DIR, 'pairings.json'),   // 配对记录
   join(AGENT_DIR, 'mcp_servers.json'),// MCP 服务器配置
   join(AGENT_DIR, 'logs') + sep,      // 日志目录
+  join(AGENT_DIR, '.trash') + sep,    // 回收站目录（通过 /api/trash 端点管理）
+  join(AGENT_DIR, 'builtin_skills_state.json'), // 内置技能状态
+  join(AGENT_DIR, 'disabled_skills.json'),      // 停用技能状态
 ];
 
 /**

package/src/server.js

@@ -1,9 +1,9 @@
 // agent/src/server.js - HTTP Router + WebSocket 服务器
 import http from 'http';
 import { WebSocketServer } from 'ws';
-import { readFileSync, createWriteStream, statSync, existsSync } from 'fs';
+import { readFileSync, createWriteStream, createReadStream, statSync, existsSync } from 'fs';
 import { readFile, writeFile, readdir, stat, unlink, rmdir, chmod, mkdir, rename } from 'fs/promises';
-import { join, dirname, basename } from 'path';
+import { join, dirname, basename, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import { ZipArchive } from 'archiver';
 import { homedir, tmpdir } from 'os';
@@ -13,8 +13,9 @@ import os from 'os';
 import { loadConfig } from './config.js';
 import { verifyToken, startPairCodeRotation, stopPairCodeRotation, handlePairRequest } from './auth.js';
 import { checkPath, checkCommand } from './security.js';
+import { moveToTrash, restoreFromTrash, listTrash, startPeriodicCleanup, stopPeriodicCleanup } from './trash.js';
 import { executeCommand, executeCommandSync, addWsClient, disconnectWsClient, killProcess, getRunningProcesses } from './executor.js';
-import { setConsoleOutput, logAuth, logFs, logExec, logSecurity, logSystem, logError } from './logger.js';
+import { setConsoleOutput, logAuth, logFs, logExec, logSecurity, logSystem, logError, queryLogs, getLogDates } from './logger.js';
 import { initSearchTools, getSearchToolsAvailable, searchFiles, searchContent } from './search.js';
 import {
   initializeMcpRegistry,
@@ -43,9 +44,11 @@ import {
   getSkillsDir
 } from './skill/registry.js';
 import { saveMarkdownSkill, importMarkdownSkillFromZip, importMarkdownSkillFromUrl } from './skill/loader.js';
+import XLSX from 'xlsx';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const AGENT_VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8')).version;
+const AGENT_START_TIME = Date.now();
 
 /**
  * 跨平台 ZIP 打包（使用 archiver，替换 spawn zip）
@@ -88,10 +91,11 @@ async function createZipBuffer(sourceNames, cwd, outputPath) {
   });
 }
 
-const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
+const MAX_BODY_SIZE = 200 * 1024 * 1024; // 200MB（JSON body 解析上限，旧 base64 上传受此限制）
 const MAX_SEARCH_RESULTS = 5000;         // 单次搜索最大结果数
 const PID_FILE = join(homedir(), '.ai-helper-agent', 'agent.pid');
-const DEFAULT_MAX_SIZE = 50 * 1024 * 1024; // 文件默认大小限制
+const DEFAULT_MAX_SIZE = 50 * 1024 * 1024; // 文件默认大小限制（read/list 等读取操作）
+const MAX_UPLOAD_SIZE = 200 * 1024 * 1024; // 流式上传最大 200MB（与 MAX_BODY_SIZE 一致，流式无 base64 膨胀，实际可传 200MB 原文件）
 
 function detectShell() {
   const platform = os.platform();
@@ -356,6 +360,10 @@ export function startServer() {
 
   // 防止 shutdown 并发执行
   let shuttingDown = false;
+  // restart/update/shutdown 防重入 + 频率限制
+  let agentOperationInProgress = false;
+  let lastOperationTime = 0;
+  const OPERATION_COOLDOWN_MS = 10000; // 10s 冷却，防 DoS
 
   // ==================== HTTP Server ====================
   const server = http.createServer((req, res) => {
@@ -431,24 +439,178 @@ export function startServer() {
       return jsonResponse(res, 403, { success: false, error: '认证 token 无效' });
     }
 
-    // Agent 关闭（需认证 + 仅限本地来源，防止远程无认证关闭 Agent 造成 DoS）
+    // Agent 关闭（需认证）
     if (req.method === 'POST' && pathname === '/api/shutdown') {
-      const remoteAddr = req.socket.remoteAddress || '';
-      const isLocal = remoteAddr === '127.0.0.1' || remoteAddr === '::1' || remoteAddr === '::ffff:127.0.0.1';
-      if (!isLocal) {
-        logSecurity('shutdown_remote_blocked', { remoteAddr, extId });
-        return jsonResponse(res, 403, { success: false, error: '关闭 Agent 仅允许本地请求' });
+      if (agentOperationInProgress) {
+        return jsonResponse(res, 409, { success: false, error: '已有操作正在进行中，请稍后再试' });
       }
+      if (Date.now() - lastOperationTime < OPERATION_COOLDOWN_MS) {
+        const wait = Math.ceil((OPERATION_COOLDOWN_MS - (Date.now() - lastOperationTime)) / 1000);
+        return jsonResponse(res, 429, { success: false, error: `操作过于频繁，请 ${wait} 秒后再试` });
+      }
+      agentOperationInProgress = true;
+      lastOperationTime = Date.now();
       logSystem('shutdown', { reason: 'api_request', extId });
       jsonResponse(res, 200, { success: true, message: 'Agent 正在关闭...' });
       shutdown();
       return;
     }
 
+    // 重启 Agent（需认证）
+    if (req.method === 'POST' && pathname === '/api/agent/restart') {
+      if (agentOperationInProgress) {
+        return jsonResponse(res, 409, { success: false, error: '已有操作正在进行中，请稍后再试' });
+      }
+      if (Date.now() - lastOperationTime < OPERATION_COOLDOWN_MS) {
+        const wait = Math.ceil((OPERATION_COOLDOWN_MS - (Date.now() - lastOperationTime)) / 1000);
+        return jsonResponse(res, 429, { success: false, error: `操作过于频繁，请 ${wait} 秒后再试` });
+      }
+      agentOperationInProgress = true;
+      lastOperationTime = Date.now();
+      logSystem('restart', { reason: 'api_request', extId });
+      jsonResponse(res, 200, { success: true, message: 'Agent 正在重启...' });
+
+      // 转成绝对路径，避免相对路径在 detached 子进程中失效
+      const agentScript = resolve(process.argv[1]);
+      const restartPort = config.port || 18910;
+      const restartHost = config.host || '127.0.0.1';
+      const restartWorkdir = resolve(config.workdir || process.cwd());
+      const currentPid = process.pid;
+
+      // spawn 两阶段重启包装器（detached，独立于老进程存活）
+      // 包装器会先等老进程退出 + 端口释放，再启动新进程
+      const child = spawn(process.execPath, [
+        ...process.execArgv,
+        agentScript,
+        '_restart-helper',
+        '--old-pid', String(currentPid),
+        '--port', String(restartPort),
+        '--host', restartHost,
+        '--workdir', restartWorkdir,
+        '--script', agentScript
+      ], {
+        detached: true,
+        stdio: 'ignore',
+        cwd: process.cwd(),
+        env: { ...process.env },
+        windowsHide: true
+      });
+
+      child.on('error', (err) => {
+        logError('restart_spawn_failed', err.message);
+      });
+      child.unref();
+
+      // 延迟后关闭当前进程，让 _restart-helper 接管
+      setTimeout(() => shutdown(), 500);
+      return;
+    }
+
+    // 更新并重启 Agent（需认证）
+    if (req.method === 'POST' && pathname === '/api/agent/update') {
+      if (agentOperationInProgress) {
+        return jsonResponse(res, 409, { success: false, error: '已有操作正在进行中，请稍后再试' });
+      }
+      if (Date.now() - lastOperationTime < OPERATION_COOLDOWN_MS) {
+        const wait = Math.ceil((OPERATION_COOLDOWN_MS - (Date.now() - lastOperationTime)) / 1000);
+        return jsonResponse(res, 429, { success: false, error: `操作过于频繁，请 ${wait} 秒后再试` });
+      }
+      agentOperationInProgress = true;
+      lastOperationTime = Date.now();
+      logSystem('update', { reason: 'api_request', extId });
+
+      const agentScript = resolve(process.argv[1]);
+      const restartPort = config.port || 18910;
+      const restartHost = config.host || '127.0.0.1';
+      const restartWorkdir = resolve(config.workdir || process.cwd());
+      const currentPid = process.pid;
+
+      // 同步执行 npm 全局安装，完成后才返回结果（前端能收到真实成功/失败）
+      (async () => {
+        let npmSuccess = false;
+        let npmError = '';
+        const npmOutput = [];
+
+        try {
+          // npm install -g ai-helper-agent@latest
+          // 不指定 --registry，继承用户环境配置（公司内网/外网自适应）
+          const result = await new Promise((resolvePromise) => {
+            const npm = spawn('npm', ['install', '-g', 'ai-helper-agent@latest', '--no-audit', '--no-fund'], {
+              shell: true,
+              env: { ...process.env }
+            });
+            npm.stdout.on('data', d => npmOutput.push(d.toString().trim()));
+            npm.stderr.on('data', d => npmOutput.push(d.toString().trim()));
+            npm.on('error', (err) => resolvePromise({ success: false, error: err.message }));
+
+            // 超时保护（90s），防止 npm 卡住导致前端长等待
+            const timer = setTimeout(() => {
+              try { npm.kill('SIGTERM'); } catch {}
+              resolvePromise({ success: false, error: 'npm install 超时（90s）' });
+            }, 90000);
+            timer.unref();
+
+            npm.on('close', (code) => {
+              clearTimeout(timer);
+              resolvePromise({ success: code === 0, code });
+            });
+          });
+          npmSuccess = result.success;
+          if (!npmSuccess) {
+            npmError = result.error || `npm install 退出码: ${result.code}`;
+          }
+        } catch (err) {
+          npmError = err.message;
+        }
+
+        if (!npmSuccess) {
+          // 更新失败：不重启，保持老进程运行，提示用户手动执行
+          agentOperationInProgress = false; // 重置防重入标志，允许后续重试
+          logError('update_npm_failed', npmError + ' | output: ' + npmOutput.join('\n').slice(-500));
+          jsonResponse(res, 200, {
+            success: false,
+            error: '更新失败，请手动执行：npm install -g ai-helper-agent@latest'
+          });
+          return;
+        }
+
+        // 更新成功：返回响应并触发两阶段重启
+        logSystem('update_success', { output: npmOutput.join('\n').slice(-500) });
+        jsonResponse(res, 200, { success: true, message: '更新成功，Agent 正在重启...' });
+
+        // spawn 两阶段重启包装器
+        const child = spawn(process.execPath, [
+          ...process.execArgv,
+          agentScript,
+          '_restart-helper',
+          '--old-pid', String(currentPid),
+          '--port', String(restartPort),
+          '--host', restartHost,
+          '--workdir', restartWorkdir,
+          '--script', agentScript
+        ], {
+          detached: true,
+          stdio: 'ignore',
+          cwd: process.cwd(),
+          env: { ...process.env },
+          windowsHide: true
+        });
+
+        child.on('error', (err) => {
+          logError('update_restart_spawn_failed', err.message);
+        });
+        child.unref();
+
+        setTimeout(() => shutdown(), 500);
+      })();
+      return;
+    }
+
     const maxSize = config.fileMaxSize || DEFAULT_MAX_SIZE;
 
     // 认证后的状态信息（不再下发 pairCode：配对码仅用于一次性配对，避免已配对端横向获取）
     if (req.method === 'GET' && pathname === '/api/status/detail') {
+      const mem = process.memoryUsage();
       return jsonResponse(res, 200, {
         success: true,
         version: AGENT_VERSION,
@@ -456,8 +618,17 @@ export function startServer() {
         workdir: config.workdir,
         allowedPaths: config.allowedPaths,
         commandTimeout: config.commandTimeout,
-        fileMaxSize: config.fileMaxSize,
+        fileMaxSize: config.fileMaxSize,       // 读取大小限制（/api/fs/read、/api/fs/download）
+        uploadMaxSize: MAX_UPLOAD_SIZE,        // 上传大小限制（/api/fs/upload-stream，流式不占内存可更大）
         runningProcesses: getRunningProcesses(),
+        resourceUsage: {
+          memoryUsedMB: Math.round(mem.heapUsed / 1024 / 1024 * 100) / 100,
+          memoryTotalMB: Math.round(mem.heapTotal / 1024 / 1024 * 100) / 100,
+          memoryRssMB: Math.round(mem.rss / 1024 / 1024 * 100) / 100,
+          uptimeSeconds: Math.round((Date.now() - AGENT_START_TIME) / 1000),
+          cpuUser: process.cpuUsage().user,
+          cpuSystem: process.cpuUsage().system
+        },
         ...PLATFORM_INFO,
         searchTools: getSearchToolsAvailable()
       });
@@ -468,8 +639,8 @@ export function startServer() {
       try {
         const { fileBuffer, fileName, mimeType } = await parseMultipartBody(req);
 
-        // 安全检查：过滤文件名中的危险字符
-        const safeName = fileName.replace(/[/\\:*?"<>|]/g, '_');
+        // 安全检查：过滤危险字符 + basename 防路径穿越（.. 等）
+        const safeName = basename(fileName.replace(/[/\\:*?"<>|]/g, '_')) || 'unnamed_file';
         const destPath = join(config.workdir, safeName);
 
         // 去重：如果文件已存在，添加后缀
@@ -504,6 +675,78 @@ export function startServer() {
       }
     }
 
+    // === 流式文件上传（raw binary body，目标路径通过 query 传递，避免 base64 膨胀） ===
+    // 必须在通用 JSON body 解析之前拦截，因为 body 是二进制而非 JSON
+    if (req.method === 'POST' && pathname === '/api/fs/upload-stream') {
+      const targetPath = url.searchParams.get('path');
+      if (!targetPath || typeof targetPath !== 'string') {
+        return jsonResponse(res, 400, { success: false, error: '缺少 path 参数' });
+      }
+      const check = await checkPath(targetPath);
+      if (!check.allowed) {
+        logSecurity('fs_upload_stream_blocked', { path: targetPath, reason: check.reason });
+        return jsonResponse(res, 403, { success: false, error: check.reason });
+      }
+
+      const maxSize = MAX_UPLOAD_SIZE;
+      const declaredSize = parseInt(req.headers['content-length'] || '0', 10);
+      if (declaredSize > maxSize) {
+        return jsonResponse(res, 400, { success: false, error: `文件过大 (${declaredSize} > ${maxSize})` });
+      }
+
+      await mkdir(dirname(check.resolved), { recursive: true });
+
+      try {
+        const written = await new Promise((resolve, reject) => {
+          const ws = createWriteStream(check.resolved);
+          let totalWritten = 0;
+          let aborted = false;
+
+          // 计数 + 超限保护（防止 Content-Length 造假或缺失）
+          const onReqData = (chunk) => {
+            totalWritten += chunk.length;
+            if (totalWritten > maxSize) {
+              aborted = true;
+              try { ws.destroy(); } catch {}
+              try { req.destroy(); } catch {}
+              reject(new Error(`文件过大 (已接收 ${totalWritten} > ${maxSize})`));
+            }
+          };
+          req.on('data', onReqData);
+          req.on('error', (err) => {
+            if (aborted) return;
+            aborted = true;
+            try { ws.destroy(); } catch {}
+            reject(err);
+          });
+          ws.on('error', (err) => {
+            if (aborted) return;
+            aborted = true;
+            reject(err);
+          });
+          ws.on('finish', () => {
+            if (aborted) return;
+            resolve(totalWritten);
+          });
+
+          req.pipe(ws);
+        });
+
+        // 脚本文件剥离执行权限
+        const SCRIPT_EXT_RE = /\.(sh|bash|zsh|py|js|mjs|rb|pl|php|lua)$/i;
+        if (SCRIPT_EXT_RE.test(check.resolved)) {
+          try { await chmod(check.resolved, 0o644); } catch {}
+        }
+
+        logFs('upload_stream', { path: check.resolved, size: written });
+        return jsonResponse(res, 200, { success: true, size: written, path: check.resolved });
+      } catch (err) {
+        logError('fs', 'upload_stream_error', { path: check.resolved, error: err.message });
+        try { await unlink(check.resolved); } catch {}  // 清理半成品文件
+        return jsonResponse(res, 400, { success: false, error: `上传失败: ${err.message}` });
+      }
+    }
+
     if (['POST', 'PUT', 'DELETE'].includes(req.method)) {
       let body;
       try { body = await parseBody(req); }
@@ -581,23 +824,32 @@ export function startServer() {
           return jsonResponse(res, 403, { success: false, error: check.reason });
         }
         const rawContent = 'content' in body ? String(body.content) : '';
-        const buf = Buffer.from(rawContent, 'utf-8');
+        const encoding = body.encoding === 'base64' ? 'base64' : 'utf-8';
+        // base64 编码：先解码为二进制 Buffer 再写入，避免把 base64 字符串当文本写入导致文件损坏
+        const buf = encoding === 'base64'
+          ? Buffer.from(rawContent, 'base64')
+          : Buffer.from(rawContent, 'utf-8');
         if (buf.length > maxSize) return jsonResponse(res, 400, { success: false, error: `内容过大 (${buf.length} > ${maxSize})` });
         // 确保父目录存在
         await mkdir(dirname(check.resolved), { recursive: true });
-        await writeFile(check.resolved, rawContent, 'utf-8');
+        if (encoding === 'base64') {
+          // 二进制内容直接写入 Buffer
+          await writeFile(check.resolved, buf);
+        } else {
+          await writeFile(check.resolved, rawContent, 'utf-8');
+        }
 
         // 如果写入的是脚本文件，剥离执行权限防止直接运行
         const SCRIPT_EXT_RE = /\.(sh|bash|zsh|py|js|mjs|rb|pl|php|lua)$/i;
         const isScriptExt = SCRIPT_EXT_RE.test(check.resolved);
-        const hasShebang = rawContent.startsWith('#!');
+        const hasShebang = encoding === 'utf-8' && rawContent.startsWith('#!');
         if (isScriptExt || hasShebang) {
           try {
             await chmod(check.resolved, 0o644);
           } catch {}
         }
 
-        logFs('write', { path: check.resolved, size: buf.length });
+        logFs('write', { path: check.resolved, size: buf.length, encoding });
         return jsonResponse(res, 200, { success: true, size: buf.length, path: check.resolved });
       }
 
@@ -624,7 +876,39 @@ export function startServer() {
         return jsonResponse(res, 200, { success: true, entries, path: check.resolved });
       }
 
-      // 删除文件/目录
+      // 获取文件详细信息（权限、创建/访问/修改时间、MIME 类型等）
+      if (pathname === '/api/fs/stat') {
+        const check = await checkPath(body.path);
+        if (!check.allowed) {
+          logSecurity('fs_stat_blocked', { path: body.path, reason: check.reason });
+          return jsonResponse(res, 403, { success: false, error: check.reason });
+        }
+        if (!await exists(check.resolved)) {
+          return jsonResponse(res, 404, { success: false, error: '文件/目录不存在' });
+        }
+        const s = await stat(check.resolved);
+        const info = {
+          name: basename(check.resolved),
+          path: check.resolved,
+          type: s.isDirectory() ? 'directory' : 'file',
+          size: s.size,
+          mtime: s.mtimeMs,
+          ctime: s.birthtimeMs || s.ctimeMs,
+          atime: s.atimeMs,
+          mode: s.mode,
+          isDirectory: s.isDirectory(),
+          isFile: s.isFile(),
+          isSymbolicLink: s.isSymbolicLink()
+        };
+        // Windows 没有 uid/gid
+        if (s.uid !== undefined) info.uid = s.uid;
+        if (s.gid !== undefined) info.gid = s.gid;
+        if (info.isFile) info.mimeType = getMimeType(check.resolved);
+        logFs('stat', { path: check.resolved, type: info.type, size: info.size });
+        return jsonResponse(res, 200, { success: true, info });
+      }
+
+      // 删除文件/目录（移至回收站，7天后自动清理）
       if (pathname === '/api/fs/delete') {
         const check = await checkPath(body.path);
         if (!check.allowed) {
@@ -634,13 +918,13 @@ export function startServer() {
         if (!await exists(check.resolved)) return jsonResponse(res, 404, { success: false, error: '文件/目录不存在' });
         const fstat2 = await stat(check.resolved);
         const isDir = fstat2.isDirectory();
-        if (isDir) {
-          await rmdir(check.resolved, { recursive: true });
-        } else {
-          await unlink(check.resolved);
+        const trashResult = await moveToTrash(check.resolved);
+        if (!trashResult.success) {
+          logError('fs', 'trash_error', { path: check.resolved, error: trashResult.error });
+          return jsonResponse(res, 500, { success: false, error: trashResult.error });
         }
-        logFs('delete', { path: check.resolved, type: isDir ? 'directory' : 'file', size: fstat2.size });
-        return jsonResponse(res, 200, { success: true, path: check.resolved });
+        logFs('delete', { path: check.resolved, type: isDir ? 'directory' : 'file', size: fstat2.size, trashId: trashResult.trashId });
+        return jsonResponse(res, 200, { success: true, path: check.resolved, trashId: trashResult.trashId, message: '已移至回收站（7天后自动清理）' });
       }
 
       // 下载文件/目录（返回 base64 内容，目录自动打包为 zip）
@@ -765,15 +1049,39 @@ export function startServer() {
         const targetPath = body.path;
         const paths = body.paths;
 
-        // 辅助：设置下载响应头并返回二进制
+        // 辅助：设置下载响应头并分块流式返回二进制
+        // 分块写入避免一次性 res.end(buffer) 导致客户端进度条瞬间跳到 100%
         const sendBinary = (buffer, filename, mimeType) => {
           const encodedName = encodeURIComponent(filename);
           res.writeHead(200, {
             'Content-Type': mimeType || 'application/octet-stream',
             'Content-Disposition': `attachment; filename="${encodedName}"; filename*=UTF-8''${encodedName}`,
-            'Content-Length': buffer.length
+            'Content-Length': buffer.length,
+            'Cache-Control': 'no-cache'
           });
-          res.end(buffer);
+
+          // 分块写入：每块 64KB，写完一块让出事件循环，让 TCP 有机会发送数据
+          // 客户端 reader.read() 会持续拿到 64KB 左右的 chunk，进度条平滑更新
+          const CHUNK_SIZE = 64 * 1024;
+          let offset = 0;
+          const writeNext = () => {
+            if (res.writableEnded) return;
+            if (offset >= buffer.length) {
+              res.end();
+              return;
+            }
+            const end = Math.min(offset + CHUNK_SIZE, buffer.length);
+            const chunk = buffer.subarray(offset, end);
+            offset = end;
+            if (res.write(chunk)) {
+              // 缓冲区未满，用 setImmediate 让出事件循环，让 TCP 有机会发送
+              setImmediate(writeNext);
+            } else {
+              // 缓冲区满了，等待 drain 事件再继续
+              res.once('drain', writeNext);
+            }
+          };
+          writeNext();
         };
 
         try {
@@ -837,11 +1145,23 @@ export function startServer() {
                 try { await unlink(tmpFile); } catch {}
               }
             } else {
-              // 单文件直接返回（不受 maxSize 限制，流式传输）
-              const buf = await readFile(check.resolved);
+              // 单文件：用 createReadStream 流式传输，避免 readFile 把整个文件读入内存导致 OOM
               const mimeType = getMimeType(check.resolved);
-              logFs('download_stream', { path: check.resolved, type: 'file', size: buf.length });
-              return sendBinary(buf, basename(check.resolved), mimeType);
+              const encodedName = encodeURIComponent(basename(check.resolved));
+              res.writeHead(200, {
+                'Content-Type': mimeType || 'application/octet-stream',
+                'Content-Disposition': `attachment; filename="${encodedName}"; filename*=UTF-8''${encodedName}`,
+                'Content-Length': fstat.size,
+                'Cache-Control': 'no-cache'
+              });
+              const rs = createReadStream(check.resolved);
+              rs.on('error', (err) => {
+                logError('fs', 'download_stream_read_error', { path: check.resolved, error: err.message });
+                try { res.destroy(); } catch {}
+              });
+              logFs('download_stream', { path: check.resolved, type: 'file', size: fstat.size });
+              rs.pipe(res);
+              return;
             }
           } else {
             return jsonResponse(res, 400, { success: false, error: '缺少 path 或 paths 参数' });
@@ -852,6 +1172,63 @@ export function startServer() {
         }
       }
 
+      // XLSX 预览（服务端解析前 500 行，返回 JSON，避免前端引入 SheetJS）
+      if (pathname === '/api/fs/preview-xlsx') {
+        const filePath = body.path;
+        if (!filePath || typeof filePath !== 'string') {
+          return jsonResponse(res, 400, { success: false, error: '缺少 path 参数' });
+        }
+        const check = await checkPath(filePath);
+        if (!check.allowed) {
+          logSecurity('fs_preview_xlsx_blocked', { path: filePath, reason: check.reason });
+          return jsonResponse(res, 403, { success: false, error: check.reason });
+        }
+        try {
+          const buffer = await readFile(check.resolved);
+          const workbook = XLSX.read(buffer, { type: 'buffer', sheetRows: 2001 });
+          const sheets = workbook.SheetNames.map((name, idx) => {
+            const sheet = workbook.Sheets[name];
+            const range = XLSX.utils.decode_range(sheet['!ref'] || 'A1');
+            const maxRow = Math.min(range.e.r, 2000);
+            const rows = [];
+            for (let r = range.s.r; r <= maxRow && r <= range.e.r; r++) {
+              const row = [];
+              for (let c = range.s.c; c <= range.e.c; c++) {
+                const addr = XLSX.utils.encode_cell({ r, c });
+                const cell = sheet[addr];
+                row.push(cell ? String(cell.w ?? cell.v ?? '') : '');
+              }
+              rows.push(row);
+            }
+
+            // 裁剪：去掉尾部全空行和尾部全空列（避免仅设置了边框的空单元格撑爆 DOM）
+            let lastDataRow = -1;
+            let lastDataCol = -1;
+            for (let ri = 0; ri < rows.length; ri++) {
+              for (let ci = 0; ci < rows[ri].length; ci++) {
+                if (rows[ri][ci] !== '') {
+                  lastDataRow = Math.max(lastDataRow, ri);
+                  lastDataCol = Math.max(lastDataCol, ci);
+                }
+              }
+            }
+
+            const trimmedRows = lastDataRow >= 0
+              ? rows.slice(0, lastDataRow + 1).map(r => r.slice(0, lastDataCol + 1))
+              : [];
+            const colCount = lastDataCol >= 0 ? lastDataCol + 1 : 0;
+            const totalRows = range.e.r - range.s.r + 1;
+
+            return { name, index: idx, colCount, totalRows, rows: trimmedRows };
+          });
+          logFs('preview_xlsx', { path: check.resolved, sheets: sheets.length });
+          return jsonResponse(res, 200, { success: true, data: { sheets } });
+        } catch (err) {
+          logError('fs', 'preview_xlsx_error', { path: filePath, error: err.message });
+          return jsonResponse(res, 500, { success: false, error: `解析失败: ${err.message}` });
+        }
+      }
+
       // 创建目录
       if (pathname === '/api/fs/mkdir') {
         const dirPath = body.path;
@@ -1075,6 +1452,40 @@ export function startServer() {
 
       // === Skill 操作（需要 body） ===
 
+      // 回收站恢复
+      if (pathname === '/api/trash/restore') {
+        if (!body.trashId) return jsonResponse(res, 400, { success: false, error: '缺少 trashId 参数' });
+        const result = await restoreFromTrash(body.trashId);
+        if (result.success) {
+          logFs('trash_restore', { trashId: body.trashId, restoredPath: result.restoredPath });
+        } else {
+          logSecurity('trash_restore_failed', { trashId: body.trashId, reason: result.error });
+        }
+        return jsonResponse(res, result.success ? 200 : 400, result);
+      }
+
+      // 审计日志查询
+      if (pathname === '/api/logs/query') {
+        const limit = Math.min(body.limit || 200, 500); // 单次最多 500 条
+        const cat = body.category || null;
+        // 默认只查询最近 7 天的日志
+        const today = new Date();
+        const dates = [];
+        for (let i = 0; i < 7; i++) {
+          const d = new Date(today);
+          d.setDate(d.getDate() - i);
+          dates.push(d.toISOString().slice(0, 10));
+        }
+        let allEntries = [];
+        for (const date of dates) {
+          const result = queryLogs({ date, category: cat, limit: limit - allEntries.length, offset: 0 });
+          allEntries = allEntries.concat(result.entries);
+          if (allEntries.length >= limit) break;
+        }
+        allEntries = allEntries.slice(0, limit);
+        return jsonResponse(res, 200, { success: true, entries: allEntries, total: allEntries.length, dates });
+      }
+
       // 执行 Skill
       if (pathname === '/api/skill/run') {
         if (!body.name) return jsonResponse(res, 400, { success: false, error: '缺少 name 参数' });
@@ -1205,6 +1616,21 @@ export function startServer() {
         if (!isHttp && !body.command) {
           return jsonResponse(res, 400, { success: false, error: 'stdio 传输需要提供 command' });
         }
+        // stdio 传输：对 command + args 做安全校验，防止 MCP 成为命令管控后门
+        if (!isHttp) {
+          const fullCmd = body.args?.length > 0
+            ? `${body.command} ${body.args.join(' ')}`
+            : body.command;
+          const cmdCheck = checkCommand(fullCmd, false);
+          if (cmdCheck.level === 'deny') {
+            logSecurity('mcp_stdio_denied', { command: fullCmd, reason: cmdCheck.reason });
+            return jsonResponse(res, 403, { success: false, error: `MCP 命令被拦截: ${cmdCheck.reason}` });
+          }
+          if (cmdCheck.level === 'confirm') {
+            logSecurity('mcp_stdio_confirm_required', { command: fullCmd, reason: cmdCheck.reason });
+            return jsonResponse(res, 200, { success: true, level: 'confirm', reason: cmdCheck.reason, message: `MCP 命令需要确认: ${cmdCheck.reason}` });
+          }
+        }
         const result = await addMcpServer(body);
         logSystem('mcp_server_add', { serverId: body.id });
         return jsonResponse(res, result.success ? 200 : 400, result);
@@ -1339,6 +1765,12 @@ export function startServer() {
 
     // ========== MCP 管理接口（仅 GET 路由） ==========
 
+    // 回收站列表
+    if (req.method === 'GET' && pathname === '/api/trash/list') {
+      const result = await listTrash();
+      return jsonResponse(res, 200, result);
+    }
+
     // MCP Servers 列表
     if (req.method === 'GET' && pathname === '/api/mcp/servers') {
       return jsonResponse(res, 200, getMcpServersStatus());
@@ -1428,6 +1860,9 @@ export function startServer() {
     console.log(`[Agent] WebSocket 服务已启动: ws://${host}:${port}`);
     startPairCodeRotation();
 
+    // 启动回收站定期清理（每6小时）+ 启动时清理一次过期文件
+    startPeriodicCleanup();
+
     // 后台异步初始化 MCP 和 Skill，不阻塞主流程
     (async () => {
       try {
@@ -1458,6 +1893,7 @@ export function startServer() {
     forceExitTimer.unref();
 
     stopPairCodeRotation();
+    stopPeriodicCleanup();
 
     // 终止所有运行中的进程
     for (const entry of getRunningProcesses()) {

package/src/trash.js

@@ -0,0 +1,211 @@
+// agent/src/trash.js - 文件回收站模块
+// 删除文件时先移动到回收站，7天后自动清理
+import { mkdir, rename, readFile, writeFile, readdir, stat, unlink, rmdir } from 'fs/promises';
+import { join, basename } from 'path';
+import { homedir } from 'os';
+import { existsSync } from 'fs';
+
+const AGENT_DIR = join(homedir(), '.ai-helper-agent');
+const TRASH_DIR = join(AGENT_DIR, '.trash');
+const TRASH_META_FILE = join(TRASH_DIR, 'metadata.json');
+const TRASH_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 天
+const PERIODIC_CLEAN_INTERVAL_MS = 6 * 60 * 60 * 1000; // 每 6 小时执行一次定期清理
+let periodicCleanTimer = null;
+
+/**
+ * 确保回收站目录存在
+ */
+async function ensureTrashDir() {
+  try {
+    if (!existsSync(TRASH_DIR)) {
+      await mkdir(TRASH_DIR, { recursive: true });
+    }
+  } catch (err) {
+    console.error('[Trash] 无法创建回收站目录:', err.message);
+    throw err;
+  }
+}
+
+/**
+ * 读取回收站元数据
+ * @returns {Promise<Array>} [{ id, originalPath, name, size, deletedAt }]
+ */
+async function loadMetadata() {
+  try {
+    if (existsSync(TRASH_META_FILE)) {
+      const raw = await readFile(TRASH_META_FILE, 'utf-8');
+      return JSON.parse(raw).entries || [];
+    }
+  } catch {}
+  return [];
+}
+
+/**
+ * 保存回收站元数据
+ */
+async function saveMetadata(entries) {
+  await writeFile(TRASH_META_FILE, JSON.stringify({ entries }, null, 2), 'utf-8');
+}
+
+/**
+ * 清理过期回收站条目（超过7天）
+ * 同时在文件系统上删除对应文件/目录
+ */
+async function cleanExpiredTrash() {
+  await ensureTrashDir();
+  const entries = await loadMetadata();
+  const now = Date.now();
+  const expired = entries.filter(e => (now - e.deletedAt) > TRASH_TTL_MS);
+  const kept = entries.filter(e => (now - e.deletedAt) <= TRASH_TTL_MS);
+
+  for (const entry of expired) {
+    const trashPath = join(TRASH_DIR, entry.id);
+    try {
+      const s = await stat(trashPath);
+      if (s.isDirectory()) {
+        await rmdir(trashPath, { recursive: true });
+      } else {
+        await unlink(trashPath);
+      }
+    } catch { /* 文件可能已被手动清理 */ }
+  }
+
+  if (expired.length > 0) {
+    await saveMetadata(kept);
+    console.log(`[Trash] 清理了 ${expired.length} 个过期回收站条目`);
+  }
+}
+
+/**
+ * 将文件/目录移动到回收站
+ * @param {string} sourcePath - 源文件/目录的绝对路径
+ * @returns {Promise<{success: boolean, trashId?: string, error?: string}>}
+ */
+export async function moveToTrash(sourcePath) {
+  await ensureTrashDir();
+
+  // 每次删除前先清理过期条目（投机式清理，无需定时器）
+  await cleanExpiredTrash();
+
+  try {
+    const ts = Date.now();
+    const randomSuffix = Math.random().toString(36).slice(2, 8);
+    const id = `${ts}_${randomSuffix}`;
+    const name = basename(sourcePath);
+    const trashPath = join(TRASH_DIR, id);
+
+    // 获取文件信息
+    let size = 0;
+    try {
+      const s = await stat(sourcePath);
+      size = s.size;
+    } catch {}
+
+    // 移动到回收站
+    await rename(sourcePath, trashPath);
+
+    // 记录元数据
+    const entries = await loadMetadata();
+    entries.push({
+      id,
+      originalPath: sourcePath,
+      name,
+      size,
+      deletedAt: ts
+    });
+    await saveMetadata(entries);
+
+    console.log(`[Trash] 已移至回收站: ${sourcePath} -> ${trashPath}`);
+    return { success: true, trashId: id };
+  } catch (err) {
+    return { success: false, error: `移至回收站失败: ${err.message}` };
+  }
+}
+
+/**
+ * 从回收站恢复文件
+ * @param {string} trashId - 回收站条目 ID
+ * @returns {Promise<{success: boolean, error?: string}>}
+ */
+export async function restoreFromTrash(trashId) {
+  const entries = await loadMetadata();
+  const idx = entries.findIndex(e => e.id === trashId);
+  if (idx === -1) {
+    return { success: false, error: '回收站条目不存在或已过期' };
+  }
+
+  const entry = entries[idx];
+  const trashPath = join(TRASH_DIR, entry.id);
+
+  if (!existsSync(trashPath)) {
+    // 文件已不在回收站，清理元数据
+    entries.splice(idx, 1);
+    await saveMetadata(entries);
+    return { success: false, error: '回收站文件已不存在' };
+  }
+
+  try {
+    // 检查原路径是否已被占用
+    if (existsSync(entry.originalPath)) {
+      return { success: false, error: `原位置已有文件: ${entry.originalPath}` };
+    }
+
+    await rename(trashPath, entry.originalPath);
+    entries.splice(idx, 1);
+    await saveMetadata(entries);
+
+    console.log(`[Trash] 已恢复: ${entry.originalPath}`);
+    return { success: true, restoredPath: entry.originalPath };
+  } catch (err) {
+    return { success: false, error: `恢复失败: ${err.message}` };
+  }
+}
+
+/**
+ * 获取回收站条目列表（不包含清理逻辑，用于前端展示）
+ * @returns {Promise<{success: boolean, entries: Array}>}
+ */
+export async function listTrash() {
+  await ensureTrashDir();
+  // 前先清理一次过期条目，保持视图清爽
+  await cleanExpiredTrash();
+  const entries = await loadMetadata();
+  return { success: true, entries };
+}
+
+/**
+ * 获取回收站目录路径（用于配置 etc）
+ */
+export function getTrashDir() {
+  return TRASH_DIR;
+}
+
+/**
+ * 启动定期清理定时器（每6小时执行一次过期清理）
+ * 配合 moveToTrash/listTrash 中的投机式清理，确保即使长期不操作也能清理过期文件
+ */
+export function startPeriodicCleanup() {
+  if (periodicCleanTimer) return; // 防止重复启动
+  periodicCleanTimer = setInterval(async () => {
+    try {
+      await cleanExpiredTrash();
+    } catch (err) {
+      console.error('[Trash] 定期清理出错:', err.message);
+    }
+  }, PERIODIC_CLEAN_INTERVAL_MS);
+  // 允许进程退出（不阻止事件循环），Node 会在退出时自动清理
+  if (periodicCleanTimer.unref) periodicCleanTimer.unref();
+  console.log('[Trash] 定期清理已启动（间隔6小时）');
+}
+
+/**
+ * 停止定期清理定时器
+ */
+export function stopPeriodicCleanup() {
+  if (periodicCleanTimer) {
+    clearInterval(periodicCleanTimer);
+    periodicCleanTimer = null;
+  }
+}
+
+export { TRASH_DIR, TRASH_TTL_MS };