ai-helper-agent 1.0.0 → 1.1.0

package/README.md

@@ -105,6 +105,50 @@ ai-helper-agent start --port 18911
 | `commandTimeout` | 命令执行超时（毫秒） | 300000（5分钟） |
 | `fileMaxSize` | 文件读写最大字节数 | 52428800（50MB） |
 
+## 审计日志
+
+所有操作自动记录到审计日志中，日志文件位于 `~/.ai-helper-agent/logs/`。
+
+### 日志格式
+
+JSON Lines 格式，每行一条记录，文件按日命名 `agent-YYYY-MM-DD.log`。
+
+```json
+{"timestamp":"2026-01-15T10:30:00.123Z","level":"info","category":"fs","action":"read","path":"/home/user/project/src/index.js","size":2048}
+{"timestamp":"2026-01-15T10:30:05.456Z","level":"info","category":"exec","action":"completed","command":"npm test","cwd":"/home/user/project","execId":"a1b2c3d4","exitCode":0,"killed":false,"stdoutLen":1024,"stderrLen":0}
+{"timestamp":"2026-01-15T10:31:00.789Z","level":"warn","category":"security","action":"exec_denied","command":"rm -rf /","reason":"高危命令被拦截"}
+```
+
+### 日志分类
+
+| category | 说明 | 包含的操作 |
+|----------|------|-----------|
+| `auth` | 认证事件 | 配对成功/失败 |
+| `fs` | 文件操作 | read, write, list, delete |
+| `exec` | 命令执行 | started, completed, stopped, error |
+| `security` | 安全事件 | deny, confirm, auth 失败, 路径越权拦截 |
+| `system` | 系统事件 | server_start, server_stop, shutdown |
+
+### 日志查询 API
+
+```
+GET /api/logs?date=2026-01-15&category=security&limit=50&offset=0
+GET /api/logs/dates
+```
+
+- `date` - 日期筛选 (YYYY-MM-DD)，不传默认今天
+- `category` - 分类筛选，不传返回全部
+- `limit` - 返回条数上限，默认 200
+- `offset` - 分页偏移
+
+返回按时间倒序排列（最新的在前）。
+
+### 自动清理
+
+- 最多保留 30 个日志文件
+- 单文件超过 10MB 自动删除
+- 每次写入日志时触发检查
+
 ## API 端点
 
 ### 无需认证
@@ -127,6 +171,8 @@ ai-helper-agent start --port 18911
 | GET | `/api/exec/running` | 运行中的进程列表 |
 | GET | `/api/status/detail` | 详细信息（含工作目录） |
 | POST | `/api/shutdown` | 关闭 Agent 服务 |
+| GET | `/api/logs` | 查询审计日志（支持 date/category/limit/offset 参数） |
+| GET | `/api/logs/dates` | 获取可用日志日期列表 |
 
 ### WebSocket
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-helper-agent",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "AI Helper 本地代理服务 - 为 Chrome 扩展提供本地文件读写和系统命令执行能力",
   "type": "module",
   "main": "./src/server.js",

package/src/logger.js

@@ -0,0 +1,149 @@
+// agent/src/logger.js - 审计日志模块（JSON Lines 格式，按日轮转，自动清理）
+import { appendFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const LOG_DIR = join(homedir(), '.ai-helper-agent', 'logs');
+const MAX_LOG_FILES = 30;          // 最多保留 30 个日志文件
+const MAX_LOG_SIZE = 10 * 1024 * 1024; // 单文件最大 10MB
+
+function ensureLogDir() {
+  if (!existsSync(LOG_DIR)) {
+    mkdirSync(LOG_DIR, { recursive: true });
+  }
+}
+
+/**
+ * 获取当天日志文件路径
+ */
+function getLogFile() {
+  const now = new Date();
+  const date = now.toISOString().slice(0, 10); // YYYY-MM-DD
+  return join(LOG_DIR, `agent-${date}.log`);
+}
+
+/**
+ * 清理旧日志文件（保留最近 MAX_LOG_FILES 个，删除超大文件）
+ */
+function cleanOldLogs() {
+  try {
+    const files = readdirSync(LOG_DIR)
+      .filter(f => f.endsWith('.log'))
+      .map(f => {
+        const path = join(LOG_DIR, f);
+        const stat = statSync(path);
+        return { name: f, path, mtime: stat.mtimeMs, size: stat.size };
+      })
+      .sort((a, b) => b.mtime - a.mtime); // 最新的在前面
+
+    let deleted = 0;
+    for (let i = 0; i < files.length; i++) {
+      const f = files[i];
+      // 超过保留数量，或单文件超过大小限制
+      if (i >= MAX_LOG_FILES || f.size > MAX_LOG_SIZE) {
+        try { unlinkSync(f.path); deleted++; } catch {}
+      }
+    }
+    if (deleted > 0) {
+      console.log(`[Logger] 清理了 ${deleted} 个旧日志文件`);
+    }
+  } catch {}
+}
+
+/**
+ * 写入一条日志
+ * @param {'info'|'warn'|'error'} level - 日志级别
+ * @param {'auth'|'fs'|'exec'|'security'|'system'} category - 日志分类
+ * @param {string} action - 操作名称
+ * @param {Object} details - 详细信息
+ */
+function log(level, category, action, details = {}) {
+  try {
+    ensureLogDir();
+    cleanOldLogs(); // 每次写入时顺便清理（频率不高，影响可忽略）
+
+    const entry = {
+      timestamp: new Date().toISOString(),
+      level,
+      category,
+      action,
+      ...details
+    };
+
+    appendFileSync(getLogFile(), JSON.stringify(entry) + '\n', 'utf-8');
+  } catch (err) {
+    // 日志写入失败不应影响主流程
+    console.error('[Logger] 日志写入失败:', err.message);
+  }
+}
+
+// ==================== 便捷方法 ====================
+
+function logAuth(action, details) { log('info', 'auth', action, details); }
+function logFs(action, details) { log('info', 'fs', action, details); }
+function logExec(action, details) { log('info', 'exec', action, details); }
+function logSecurity(action, details) { log('warn', 'security', action, details); }
+function logSystem(action, details) { log('info', 'system', action, details); }
+function logError(category, action, details) { log('error', category, action, details); }
+
+/**
+ * 查询日志（用于 /api/logs 端点）
+ * @param {Object} options - 查询选项
+ * @param {string} [options.date] - 日期 (YYYY-MM-DD)
+ * @param {string} [options.category] - 分类过滤
+ * @param {number} [options.limit=200] - 返回条数上限
+ * @param {number} [options.offset=0] - 偏移量
+ * @returns {{ entries: Array, total: number }}
+ */
+function queryLogs(options = {}) {
+  const { date, category, limit = 200, offset = 0 } = options;
+
+  let filePath;
+  if (date) {
+    filePath = join(LOG_DIR, `agent-${date}.log`);
+  } else {
+    filePath = getLogFile();
+  }
+
+  let entries = [];
+  try {
+    if (existsSync(filePath)) {
+      const raw = readFileSync(filePath, 'utf-8');
+      const lines = raw.trim().split('\n');
+      for (const line of lines) {
+        try {
+          const entry = JSON.parse(line);
+          if (category && entry.category !== category) continue;
+          entries.push(entry);
+        } catch {}
+      }
+    }
+  } catch {}
+
+  // 按时间倒序（最新的在前）
+  entries.sort((a, b) => b.timestamp.localeCompare(a.timestamp));
+
+  const total = entries.length;
+  entries = entries.slice(offset, offset + limit);
+
+  return { entries, total };
+}
+
+/**
+ * 获取可用日志日期列表
+ */
+function getLogDates() {
+  try {
+    ensureLogDir();
+    const files = readdirSync(LOG_DIR)
+      .filter(f => f.match(/^agent-\d{4}-\d{2}-\d{2}\.log$/))
+      .map(f => f.replace('agent-', '').replace('.log', ''))
+      .sort()
+      .reverse();
+    return files;
+  } catch {
+    return [];
+  }
+}
+
+export { log, logAuth, logFs, logExec, logSecurity, logSystem, logError, queryLogs, getLogDates };

package/src/server.js

@@ -7,6 +7,7 @@ import { loadConfig } from './config.js';
 import { verifyToken, getCurrentPairCode, startPairCodeRotation, stopPairCodeRotation, handlePairRequest } from './auth.js';
 import { checkPath, checkCommand } from './security.js';
 import { executeCommand, executeCommandSync, addWsClient, killProcess, getRunningProcesses } from './executor.js';
+import { logAuth, logFs, logExec, logSecurity, logSystem, logError, queryLogs, getLogDates } from './logger.js';
 
 const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
 
@@ -64,6 +65,8 @@ export function startServer() {
   const config = loadConfig();
   const { port, host } = config;
 
+  logSystem('server_start', { port, host, workdir: config.workdir });
+
   // ==================== HTTP Server ====================
   const server = http.createServer(async (req, res) => {
     // CORS 预检
@@ -87,10 +90,15 @@ export function startServer() {
       try { body = await parseBody(req); }
       catch (err) { return jsonResponse(res, 400, { success: false, error: err.message }); }
       const result = handlePairRequest(body.code, body.extensionId);
+      if (result.success) {
+        logAuth('pair_success', { extensionId: body.extensionId });
+      } else {
+        logAuth('pair_failed', { extensionId: body.extensionId, reason: result.error });
+      }
       return jsonResponse(res, result.success ? 200 : 400, result);
     }
 
-    // 健康检查（不含敏感信息）
+    // 健康检查
     if (req.method === 'GET' && pathname === '/api/status') {
       return jsonResponse(res, 200, {
         success: true,
@@ -102,17 +110,19 @@ export function startServer() {
     // ---------- 需要认证的接口 ----------
     const authHeader = req.headers.authorization;
     if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      logSecurity('auth_missing', { path: pathname });
       return jsonResponse(res, 401, { success: false, error: '未提供认证 token' });
     }
     const token = authHeader.slice(7);
     const extId = verifyToken(token);
     if (!extId) {
+      logSecurity('auth_invalid', { path: pathname });
       return jsonResponse(res, 403, { success: false, error: '认证 token 无效' });
     }
 
     const maxSize = config.fileMaxSize;
 
-    // 认证后的状态信息（含敏感信息）
+    // 认证后的状态信息
     if (req.method === 'GET' && pathname === '/api/status/detail') {
       return jsonResponse(res, 200, {
         success: true,
@@ -133,32 +143,44 @@ export function startServer() {
       // 读取文件
       if (pathname === '/api/fs/read') {
         const check = checkPath(body.path);
-        if (!check.allowed) return jsonResponse(res, 403, { success: false, error: check.reason });
+        if (!check.allowed) {
+          logSecurity('fs_read_blocked', { path: body.path, reason: check.reason });
+          return jsonResponse(res, 403, { success: false, error: check.reason });
+        }
         if (!existsSync(check.resolved)) return jsonResponse(res, 404, { success: false, error: '文件不存在' });
-        const stat = statSync(check.resolved);
-        if (stat.isDirectory()) return jsonResponse(res, 400, { success: false, error: '路径是目录' });
-        if (stat.size > maxSize) return jsonResponse(res, 400, { success: false, error: `文件过大 (${stat.size} > ${maxSize})` });
+        const fstat = statSync(check.resolved);
+        if (fstat.isDirectory()) return jsonResponse(res, 400, { success: false, error: '路径是目录' });
+        if (fstat.size > maxSize) return jsonResponse(res, 400, { success: false, error: `文件过大 (${fstat.size} > ${maxSize})` });
         const content = readFileSync(check.resolved, 'utf-8');
-        return jsonResponse(res, 200, { success: true, content, size: stat.size, path: check.resolved });
+        logFs('read', { path: check.resolved, size: fstat.size });
+        return jsonResponse(res, 200, { success: true, content, size: fstat.size, path: check.resolved });
       }
 
       // 写入文件
       if (pathname === '/api/fs/write') {
         const check = checkPath(body.path);
-        if (!check.allowed) return jsonResponse(res, 403, { success: false, error: check.reason });
+        if (!check.allowed) {
+          logSecurity('fs_write_blocked', { path: body.path, reason: check.reason });
+          return jsonResponse(res, 403, { success: false, error: check.reason });
+        }
         const buf = Buffer.from(body.content || '', 'utf-8');
         if (buf.length > maxSize) return jsonResponse(res, 400, { success: false, error: `内容过大 (${buf.length} > ${maxSize})` });
         writeFileSync(check.resolved, body.content || '', 'utf-8');
+        logFs('write', { path: check.resolved, size: buf.length });
         return jsonResponse(res, 200, { success: true, size: buf.length, path: check.resolved });
       }
 
       // 列出目录
       if (pathname === '/api/fs/list') {
-        const check = checkPath(body.path || '.');
-        if (!check.allowed) return jsonResponse(res, 403, { success: false, error: check.reason });
+        const dirPath = body.path || '.';
+        const check = checkPath(dirPath);
+        if (!check.allowed) {
+          logSecurity('fs_list_blocked', { path: dirPath, reason: check.reason });
+          return jsonResponse(res, 403, { success: false, error: check.reason });
+        }
         if (!existsSync(check.resolved)) return jsonResponse(res, 404, { success: false, error: '目录不存在' });
-        const stat = statSync(check.resolved);
-        if (!stat.isDirectory()) return jsonResponse(res, 400, { success: false, error: '路径不是目录' });
+        const dstat = statSync(check.resolved);
+        if (!dstat.isDirectory()) return jsonResponse(res, 400, { success: false, error: '路径不是目录' });
         const entries = readdirSync(check.resolved).map(name => {
           const fullPath = join(check.resolved, name);
           try {
@@ -166,26 +188,31 @@ export function startServer() {
             return { name, type: s.isDirectory() ? 'directory' : 'file', size: s.size, mtime: s.mtimeMs };
           } catch { return { name, type: 'unknown', size: 0, mtime: 0 }; }
         });
+        logFs('list', { path: check.resolved, entryCount: entries.length });
         return jsonResponse(res, 200, { success: true, entries, path: check.resolved });
       }
 
       // 删除文件/目录
       if (pathname === '/api/fs/delete') {
         const check = checkPath(body.path);
-        if (!check.allowed) return jsonResponse(res, 403, { success: false, error: check.reason });
+        if (!check.allowed) {
+          logSecurity('fs_delete_blocked', { path: body.path, reason: check.reason });
+          return jsonResponse(res, 403, { success: false, error: check.reason });
+        }
         if (!existsSync(check.resolved)) return jsonResponse(res, 404, { success: false, error: '文件/目录不存在' });
-        const stat = statSync(check.resolved);
-        if (stat.isDirectory()) {
+        const fstat2 = statSync(check.resolved);
+        const isDir = fstat2.isDirectory();
+        if (isDir) {
           rmdirSync(check.resolved, { recursive: true });
         } else {
           unlinkSync(check.resolved);
         }
+        logFs('delete', { path: check.resolved, type: isDir ? 'directory' : 'file', size: fstat2.size });
         return jsonResponse(res, 200, { success: true, path: check.resolved });
       }
 
       // === 命令执行 ===
 
-      // 发起命令执行
       if (pathname === '/api/exec') {
         const { command, cwd, wait, force } = body;
         if (!command) return jsonResponse(res, 400, { success: false, error: '缺少 command 参数' });
@@ -194,22 +221,34 @@ export function startServer() {
         let resolvedCwd = cwd || config.workdir;
         const cwdCheck = checkPath(resolvedCwd);
         if (!cwdCheck.allowed) {
+          logSecurity('exec_cwd_blocked', { command, cwd: resolvedCwd, reason: cwdCheck.reason });
           return jsonResponse(res, 403, { success: false, error: '执行目录校验失败: ' + cwdCheck.reason });
         }
 
         // 安全检查
         const cmdCheck = checkCommand(command, force);
         if (cmdCheck.level === 'deny') {
+          logSecurity('exec_denied', { command, reason: cmdCheck.reason });
           return jsonResponse(res, 403, { success: false, error: cmdCheck.reason, level: 'deny' });
         }
         if (cmdCheck.level === 'confirm') {
+          logSecurity('exec_confirm_required', { command, reason: cmdCheck.reason });
           return jsonResponse(res, 200, { success: true, level: 'confirm', reason: cmdCheck.reason, command, cwd });
         }
 
-        // 同步等待模式（用于扩展端获取完整输出）
+        // 同步等待模式
         if (wait) {
           try {
             const result = await executeCommandSync(command, resolvedCwd);
+            logExec('completed', {
+              command,
+              cwd: resolvedCwd,
+              execId: result.execId,
+              exitCode: result.exitCode,
+              killed: result.killed,
+              stdoutLen: (result.stdout || '').length,
+              stderrLen: (result.stderr || '').length
+            });
             return jsonResponse(res, 200, {
               success: true,
               level: 'allow',
@@ -221,12 +260,22 @@ export function startServer() {
               error: result.error
             });
           } catch (err) {
+            logError('exec', 'error', { command, error: err.message });
             return jsonResponse(res, 500, { success: false, error: `命令执行异常: ${err.message}` });
           }
         }
 
-        // 异步模式（返回 execId，适用于 WebSocket 场景）
-        const execId = executeCommand(command, resolvedCwd, null, null);
+        // 异步模式
+        const execId = executeCommand(command, resolvedCwd, null, (result) => {
+          logExec('completed', {
+            command,
+            cwd: resolvedCwd,
+            execId: result.execId,
+            exitCode: result.exitCode,
+            killed: result.killed
+          });
+        });
+        logExec('started', { command, cwd: resolvedCwd, execId });
         return jsonResponse(res, 200, {
           success: true,
           level: 'allow',
@@ -238,6 +287,7 @@ export function startServer() {
       // 停止命令
       if (pathname === '/api/exec/stop') {
         const stopped = killProcess(body.execId);
+        logExec('stopped', { execId: body.execId, success: stopped });
         return jsonResponse(res, 200, { success: stopped, execId: body.execId });
       }
     }
@@ -247,8 +297,24 @@ export function startServer() {
       return jsonResponse(res, 200, { success: true, processes: getRunningProcesses() });
     }
 
-    // Agent 关闭（需认证，POST 方法）
+    // 日志查询（需认证）
+    if (req.method === 'GET' && pathname === '/api/logs') {
+      const date = url.searchParams.get('date') || undefined;
+      const category = url.searchParams.get('category') || undefined;
+      const limit = parseInt(url.searchParams.get('limit') || '200', 10);
+      const offset = parseInt(url.searchParams.get('offset') || '0', 10);
+      const result = queryLogs({ date, category, limit, offset });
+      return jsonResponse(res, 200, { success: true, ...result });
+    }
+
+    // 日志日期列表（需认证）
+    if (req.method === 'GET' && pathname === '/api/logs/dates') {
+      return jsonResponse(res, 200, { success: true, dates: getLogDates() });
+    }
+
+    // Agent 关闭
     if (req.method === 'POST' && pathname === '/api/shutdown') {
+      logSystem('shutdown', { reason: 'api_request' });
       jsonResponse(res, 200, { success: true, message: 'Agent 正在关闭...' });
       shutdown();
       return;
@@ -268,7 +334,6 @@ export function startServer() {
     if (pathParts[1] === 'ws' && pathParts[2] === 'exec') {
       const execId = pathParts[3];
 
-      // Token 验证（从 Authorization header 或 query param）
       const authHeader = request.headers.authorization;
       let token = null;
       if (authHeader && authHeader.startsWith('Bearer ')) {
@@ -277,6 +342,7 @@ export function startServer() {
         token = url.searchParams.get('token');
       }
       if (!verifyToken(token)) {
+        logSecurity('ws_auth_invalid', { execId });
         socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
         socket.destroy();
         return;
@@ -309,6 +375,7 @@ export function startServer() {
     }
     wss.close();
     server.close();
+    logSystem('server_stop', { reason: 'shutdown' });
     process.exit(0);
   }