ai-helper-agent 1.1.0 → 1.3.0

package/README.md

@@ -13,14 +13,15 @@ npm install -g ai-helper-agent
 ## 快速开始
 
 ```bash
-# 启动 Agent（默认工作目录为当前目录）
+# 前台启动（终端显示实时运行日志，适合调试）
 ai-helper-agent start
 
-# 指定工作目录
-ai-helper-agent start --workdir /path/to/your/project
+# 后台启动（守护进程模式，终端立即返回）
+ai-helper-agent start --background
+ai-helper-agent start -b
 
-# 指定端口
-ai-helper-agent start --port 18911
+# 指定工作目录和端口
+ai-helper-agent start --workdir /path/to/your/project --port 18911
 ```
 
 启动后终端会显示 4 位配对码，在 Chrome 扩展设置页「本地Agent」标签中填入即可完成配对。
@@ -29,9 +30,10 @@ ai-helper-agent start --port 18911
 
 | 命令 | 说明 |
 |------|------|
-| `start` | 启动 Agent 服务 |
+| `start` | 启动 Agent 服务（前台运行，显示实时日志） |
+| `start --background` / `start -b` | 后台启动（守护进程模式） |
 | `stop` | 停止正在运行的 Agent |
-| `restart` | 重启 Agent 服务 |
+| `restart` | 重启 Agent 服务（支持 -b 后台重启） |
 | `status` | 查看运行状态 |
 | `paircode` | 查看配对码提示 |
 | `config` | 查看当前配置 |
@@ -41,14 +43,40 @@ ai-helper-agent start --port 18911
 ### 启动选项
 
 ```
---port <端口>      监听端口，默认 18910
---host <地址>      监听地址，默认 127.0.0.1
---workdir <目录>   工作目录（文件读写限制在此范围内）
+--background, -b    后台运行（守护进程模式）
+--port <端口>       监听端口，默认 18910
+--host <地址>       监听地址，默认 127.0.0.1
+--workdir <目录>    工作目录（文件读写限制在此范围内）
 ```
 
+### 前台 vs 后台运行
+
+| 模式 | 命令 | 终端行为 | 适用场景 |
+|------|------|----------|----------|
+| 前台 | `start` | 阻塞终端，实时显示运行日志 | 开发调试、问题排查 |
+| 后台 | `start --background` | 立即返回，终端无日志输出 | 生产环境、日常使用 |
+
+前台运行时，所有文件读写、命令执行、安全拦截等操作日志会以格式化形式实时输出到终端：
+
+```
+[12:30:01] [INFO] [文件:read] path=/project/src/index.js size=2048
+[12:30:05] [INFO] [命令:started] command="npm test" cwd=/project execId=a1b2c3d4
+[12:30:12] [INFO] [命令:completed] execId=a1b2c3d4 exitCode=0 killed=false
+[12:31:00] [WARN] [安全:exec_denied] command="rm -rf /" reason=高危命令被拦截
+```
+
+### 进程管理
+
+Agent 通过 PID 文件（`~/.ai-helper-agent/agent.pid`）管理进程生命周期：
+
+- 启动时自动写入 PID 文件
+- `stop` 命令优先通过 API 优雅关闭，失败则通过 PID 文件 kill 进程
+- 正常关闭时自动清理 PID 文件
+
 ## 安全机制
 
 ### 文件沙箱
+
 所有文件操作限制在配置的 `allowedPaths` 白名单目录内。通过 `realpath` 解析防止符号链接绕过，确保物理路径安全。
 
 ### 命令分级管控
@@ -105,10 +133,32 @@ ai-helper-agent start --port 18911
 | `commandTimeout` | 命令执行超时（毫秒） | 300000（5分钟） |
 | `fileMaxSize` | 文件读写最大字节数 | 52428800（50MB） |
 
+## 文件搜索
+
+Agent 优先使用系统原生搜索工具，不可用时自动回退到 Node.js 实现：
+
+| 引擎 | 用途 | 检测命令 |
+|------|------|----------|
+| `fd` | 文件名搜索（快速） | `fd --version` |
+| `rg` (ripgrep) | 文件内容搜索（快速） | `rg --version` |
+
+状态接口返回当前可用的搜索工具：
+
+```json
+{ "searchTools": { "fd": true, "rg": true } }
+```
+
 ## 审计日志
 
 所有操作自动记录到审计日志中，日志文件位于 `~/.ai-helper-agent/logs/`。
 
+### 双通道输出
+
+- **终端输出**（前台模式）：格式化可读格式，输出到 stderr
+- **文件输出**：JSON Lines 格式，写入日志文件
+
+两种通道同时工作，互不影响。
+
 ### 日志格式
 
 JSON Lines 格式，每行一条记录，文件按日命名 `agent-YYYY-MM-DD.log`。
@@ -124,10 +174,10 @@ JSON Lines 格式，每行一条记录，文件按日命名 `agent-YYYY-MM-DD.lo
 | category | 说明 | 包含的操作 |
 |----------|------|-----------|
 | `auth` | 认证事件 | 配对成功/失败 |
-| `fs` | 文件操作 | read, write, list, delete |
+| `fs` | 文件操作 | read, write, list, delete, search_files, search_content |
 | `exec` | 命令执行 | started, completed, stopped, error |
 | `security` | 安全事件 | deny, confirm, auth 失败, 路径越权拦截 |
-| `system` | 系统事件 | server_start, server_stop, shutdown |
+| `system` | 系统事件 | server_start, server_stop, shutdown, server_error, uncaught_exception, unhandled_rejection |
 
 ### 日志查询 API
 
@@ -156,7 +206,8 @@ GET /api/logs/dates
 | 方法 | 路径 | 说明 |
 |------|------|------|
 | POST | `/api/pair` | 配对认证 |
-| GET | `/api/status` | 健康检查（版本号、运行状态） |
+| GET | `/api/status` | 健康检查（版本号、平台信息、搜索工具可用性） |
+| POST | `/api/shutdown` | 关闭 Agent 服务（仅限本地访问） |
 
 ### 需要认证（Bearer Token）
 
@@ -166,11 +217,12 @@ GET /api/logs/dates
 | POST | `/api/fs/write` | 写入文件 |
 | POST | `/api/fs/list` | 列出目录 |
 | POST | `/api/fs/delete` | 删除文件/目录 |
+| POST | `/api/fs/search_files` | 按文件名模式搜索（glob） |
+| POST | `/api/fs/search_content` | 搜索文件内容（rg 优先，Node.js 回退） |
 | POST | `/api/exec` | 执行系统命令 |
 | POST | `/api/exec/stop` | 停止命令执行 |
 | GET | `/api/exec/running` | 运行中的进程列表 |
-| GET | `/api/status/detail` | 详细信息（含工作目录） |
-| POST | `/api/shutdown` | 关闭 Agent 服务 |
+| GET | `/api/status/detail` | 详细信息（含工作目录、配对码、搜索工具） |
 | GET | `/api/logs` | 查询审计日志（支持 date/category/limit/offset 参数） |
 | GET | `/api/logs/dates` | 获取可用日志日期列表 |
 
@@ -180,12 +232,24 @@ GET /api/logs/dates
 |------|------|
 | `ws://127.0.0.1:18910/ws/exec/:execId` | 命令执行实时输出流 |
 
+## 健壮性
+
+Agent 内置多层异常保护，防止单个错误导致整个服务崩溃：
+
+- **请求级保护**：每个 HTTP 请求处理外层包裹异常捕获，异常时返回 500 而非崩溃
+- **URL 解析保护**：畸形 URL 不会导致进程崩溃，返回 400
+- **服务器级保护**：端口占用等服务器错误有专门处理，优雅报错退出
+- **全局兜底**：`uncaughtException` 和 `unhandledRejection` 全局捕获，记录错误日志但不退出进程
+- **文件 I/O 保护**：配置文件读写失败不影响服务运行
+- **进程管理保护**：`SIGTERM`/`SIGKILL` 发送对已退出进程有 try-catch 保护
+
 ## 技术栈
 
 - Node.js >= 18
 - 原生 `http` 模块（HTTP 服务）
 - `ws` 库（WebSocket 服务）
 - 零外部框架依赖
+- 可选依赖：`fd`、`rg`（ripgrep）— 用于加速文件搜索
 
 ## License
 

package/bin/agent.js

@@ -2,10 +2,13 @@
 // agent/bin/agent.js - CLI 入口
 // 用法: ai-helper-agent <start|stop|restart|status|paircode|config> [options]
 import { join } from 'path';
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from 'fs';
+import { spawn } from 'child_process';
+import { homedir } from 'os';
 
-const AGENT_DIR = join(process.env.HOME || '~', '.ai-helper-agent');
+const AGENT_DIR = join(homedir(), '.ai-helper-agent');
 const CONFIG_FILE = join(AGENT_DIR, 'config.json');
+const PID_FILE = join(AGENT_DIR, 'agent.pid');
 
 /**
  * 读取 Agent 配置文件
@@ -16,22 +19,100 @@ function readAgentConfig() {
       const raw = readFileSync(CONFIG_FILE, 'utf-8');
       return JSON.parse(raw);
     }
-  } catch {}
+  } catch (err) {
+    console.error(`[Agent] 配置文件读取失败: ${err.message}`);
+  }
   return { port: 18910, host: '127.0.0.1' };
 }
 
 /**
- * 检查 Agent 是否在运行
+ * 确保 Agent 配置目录存在
+ */
+function ensureAgentDir() {
+  if (!existsSync(AGENT_DIR)) {
+    try {
+      mkdirSync(AGENT_DIR, { recursive: true });
+    } catch (err) {
+      console.error(`[Agent] 无法创建配置目录 ${AGENT_DIR}: ${err.message}`);
+    }
+  }
+}
+
+/**
+ * 从 PID 文件读取进程 ID（原子化读取，无 TOCTOU）
  */
-async function isRunning(config) {
+function getPidFromFile() {
   try {
-    const resp = await fetch(`http://${config.host}:${config.port}/api/status`);
-    return resp.ok;
+    const raw = readFileSync(PID_FILE, 'utf-8').trim();
+    const pid = parseInt(raw, 10);
+    if (isNaN(pid) || pid <= 0) {
+      console.error(`[Agent] PID 文件内容无效: "${raw}"`);
+      return null;
+    }
+    return pid;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 删除 PID 文件
+ */
+function removePidFile() {
+  try {
+    if (existsSync(PID_FILE)) unlinkSync(PID_FILE);
+  } catch (err) {
+    console.error(`[Agent] 删除 PID 文件失败: ${err.message}`);
+  }
+}
+
+/**
+ * 通过 PID 终止进程
+ */
+function killByPid(pid) {
+  if (!pid || typeof pid !== 'number' || pid <= 0) return false;
+  try {
+    process.kill(pid, 'SIGTERM');
+    return true;
   } catch {
     return false;
   }
 }
 
+/**
+ * 校验端口号
+ */
+function isValidPort(port) {
+  return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+
+/**
+ * 检查 Agent 是否在运行（轮询直到确认）
+ */
+async function isRunning(config, retries = 2) {
+  for (let i = 0; i < retries; i++) {
+    try {
+      const resp = await fetch(`http://${config.host}:${config.port}/api/status`);
+      if (resp.ok) return true;
+    } catch {}
+    if (i < retries - 1) await new Promise(r => setTimeout(r, 300));
+  }
+  return false;
+}
+
+/**
+ * 等待 Agent 退出（轮询端口释放）
+ */
+async function waitForExit(config, timeoutMs = 5000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const alive = await isRunning(config, 1);
+    if (!alive) return true;
+    await new Promise(r => setTimeout(r, 200));
+  }
+  return false;
+}
+
 /**
  * 打印帮助信息
  */
@@ -41,7 +122,7 @@ function printHelp() {
   console.log('用法: ai-helper-agent <命令> [选项]');
   console.log('');
   console.log('命令:');
-  console.log('  start        启动 Agent 服务');
+  console.log('  start        启动 Agent 服务（前台运行）');
   console.log('  stop         停止正在运行的 Agent');
   console.log('  restart      重启 Agent 服务');
   console.log('  status       查看 Agent 运行状态');
@@ -50,51 +131,131 @@ function printHelp() {
   console.log('  help         显示此帮助信息');
   console.log('');
   console.log('启动选项:');
+  console.log('  --background, -b   后台运行（守护进程模式）');
   console.log('  --port <端口>      设置监听端口 (默认: 18910)');
   console.log('  --host <地址>      设置监听地址 (默认: 127.0.0.1)');
   console.log('  --workdir <目录>   设置工作目录 (默认: 当前目录)');
   console.log('');
   console.log('示例:');
   console.log('  ai-helper-agent start');
-  console.log('  ai-helper-agent start --port 18911 --workdir /path/to/project');
+  console.log('  ai-helper-agent start --background');
+  console.log('  ai-helper-agent start -b --port 18911');
   console.log('  ai-helper-agent stop');
-  console.log('  ai-helper-agent restart');
+  console.log('  ai-helper-agent restart -b');
   console.log('  ai-helper-agent status');
 }
 
+/**
+ * 从命令行参数提取端口配置，校验后覆盖 config
+ */
+function applyCliArgs(config, args) {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--port' && args[i + 1]) {
+      const port = parseInt(args[i + 1], 10);
+      if (!isValidPort(port)) {
+        console.error(`[Agent] 无效端口号: ${args[i + 1]}，使用默认端口 ${config.port}`);
+      } else {
+        config.port = port;
+      }
+      i++;
+    } else if (arg === '--host' && args[i + 1]) {
+      config.host = args[i + 1];
+      i++;
+    } else if (arg === '--workdir' && args[i + 1]) {
+      config.workdir = args[i + 1];
+      i++;
+    }
+  }
+  return config;
+}
+
 const command = process.argv[2] || 'help';
 
 // --version / -v
 if (command === '--version' || command === '-v') {
-  const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
-  console.log(`ai-helper-agent v${pkg.version}`);
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf-8'));
+    console.log(`ai-helper-agent v${pkg.version}`);
+  } catch (err) {
+    console.error(`[Agent] 无法读取版本信息: ${err.message}`);
+  }
   process.exit(0);
 }
 
 // ==================== start ====================
 if (command === 'start') {
-  const { startServer } = await import('../src/server.js');
-  const { loadConfig } = await import('../src/config.js');
+  const isBg = process.argv.includes('--background') || process.argv.includes('-b');
 
-  console.log('[Agent] AI Helper Agent 启动中...');
+  // 过滤掉 --background/-b，其余参数传给子进程
+  const passArgs = process.argv.slice(3).filter(a => a !== '--background' && a !== '-b');
 
-  const args = process.argv.slice(3);
-  const config = loadConfig();
+  if (isBg) {
+    ensureAgentDir();
 
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === '--port' && args[i + 1]) {
-      config.port = parseInt(args[i + 1], 10);
-      i++;
-    } else if (arg === '--host' && args[i + 1]) {
-      config.host = args[i + 1];
-      i++;
-    } else if (arg === '--workdir' && args[i + 1]) {
-      config.workdir = args[i + 1];
-      i++;
+    // 检查是否已有 Agent 在运行
+    const existingConfig = readAgentConfig();
+    if (await isRunning(existingConfig)) {
+      console.log('[Agent] Agent 已在运行中，无需重复启动');
+      process.exit(0);
+    }
+
+    // 以 detached 模式启动子进程
+    const child = spawn(process.execPath, [
+      ...process.execArgv,
+      process.argv[1],
+      'start',
+      ...passArgs
+    ], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: process.cwd(),
+      env: { ...process.env }
+    });
+
+    // 监听 spawn 错误
+    let spawnFailed = false;
+    child.on('error', (err) => {
+      spawnFailed = true;
+      console.error(`[Agent] 后台启动失败: ${err.message}`);
+      try { unlinkSync(PID_FILE); } catch {}
+      process.exit(1);
+    });
+
+    // 等待进程启动确认
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    if (!spawnFailed && child.pid) {
+      try {
+        writeFileSync(PID_FILE, String(child.pid));
+      } catch (err) {
+        console.error(`[Agent] PID 文件写入失败: ${err.message}`);
+        process.exit(1);
+      }
+      child.unref();
+      console.log(`[Agent] Agent 已在后台启动 (PID: ${child.pid})`);
+      console.log(`[Agent] 使用 'ai-helper-agent stop' 停止服务`);
+      console.log(`[Agent] 使用 'ai-helper-agent status' 查看状态`);
     }
+
+    process.exit(spawnFailed ? 1 : 0);
+  }
+
+  // 前台模式：写入 PID 文件以便 stop 能找到
+  ensureAgentDir();
+  try {
+    writeFileSync(PID_FILE, String(process.pid));
+  } catch (err) {
+    console.error(`[Agent] PID 文件写入失败: ${err.message}`);
   }
 
+  const { startServer } = await import('../src/server.js');
+  const { loadConfig } = await import('../src/config.js');
+
+  console.log('[Agent] AI Helper Agent 启动中...');
+
+  const config = applyCliArgs(loadConfig(), passArgs);
+
   console.log(`[Agent] 工作目录: ${config.workdir}`);
   console.log(`[Agent] 监听地址: ${config.host}:${config.port}`);
 
@@ -106,23 +267,44 @@ if (command === 'start') {
   console.log('[Agent] 正在停止 Agent...');
 
   const running = await isRunning(config);
-  if (!running) {
-    console.log('[Agent] Agent 未在运行');
-    process.exit(0);
+  if (running) {
+    // 优先通过 API 优雅关闭
+    try {
+      const resp = await fetch(`http://${config.host}:${config.port}/api/shutdown`, {
+        method: 'POST'
+      });
+      if (resp.ok) {
+        const data = await resp.json();
+        console.log(`[Agent] ${data.message || 'Agent 已停止'}`);
+        removePidFile();
+        process.exit(0);
+      }
+    } catch (err) {
+      console.error(`[Agent] API 关闭请求失败: ${err.message}`);
+    }
+    console.log('[Agent] API 关闭失败，尝试通过 PID 终止...');
   }
 
-  try {
-    const resp = await fetch(`http://${config.host}:${config.port}/api/shutdown`, {
-      method: 'POST'
-    });
-    const data = await resp.json();
-    console.log(`[Agent] ${data.message || 'Agent 已停止'}`);
-  } catch {
-    console.log('[Agent] 无法发送停止请求，Agent 可能已退出');
+  // 回退：通过 PID 文件终止
+  const pid = getPidFromFile();
+  if (pid) {
+    if (killByPid(pid)) {
+      console.log(`[Agent] 已向 PID ${pid} 发送终止信号`);
+    } else {
+      console.log(`[Agent] 进程 ${pid} 已不存在`);
+    }
+    removePidFile();
+  } else if (!running) {
+    console.log('[Agent] Agent 未在运行');
   }
 
+  process.exit(0);
+
 // ==================== restart ====================
 } else if (command === 'restart') {
+  const isBg = process.argv.includes('--background') || process.argv.includes('-b');
+
+  // 先停止现有实例
   const config = readAgentConfig();
   const running = await isRunning(config);
 
@@ -130,23 +312,79 @@ if (command === 'start') {
     console.log('[Agent] 正在停止 Agent...');
     try {
       await fetch(`http://${config.host}:${config.port}/api/shutdown`, { method: 'POST' });
-    } catch {}
-    // 等待进程退出
-    await new Promise(resolve => setTimeout(resolve, 1500));
+    } catch (err) {
+      console.error(`[Agent] API 关闭请求失败: ${err.message}`);
+    }
+    // 等待进程退出（轮询而非硬延迟）
+    const exited = await waitForExit(config, 8000);
+    if (!exited) {
+      console.log('[Agent] 等待超时，尝试强制终止...');
+    }
+  }
+
+  // 再通过 PID 兜底
+  const pid = getPidFromFile();
+  if (pid) {
+    killByPid(pid);
+    removePidFile();
+    await new Promise(resolve => setTimeout(resolve, 500));
   }
 
+  // 重新启动
+  if (isBg) {
+    ensureAgentDir();
+    const passArgs = process.argv.slice(3).filter(a => a !== '--background' && a !== '-b');
+
+    const child = spawn(process.execPath, [
+      ...process.execArgv,
+      process.argv[1],
+      'start',
+      ...passArgs
+    ], {
+      detached: true,
+      stdio: 'ignore',
+      cwd: process.cwd(),
+      env: { ...process.env }
+    });
+
+    let spawnFailed = false;
+    child.on('error', (err) => {
+      spawnFailed = true;
+      console.error(`[Agent] 后台重启失败: ${err.message}`);
+      try { unlinkSync(PID_FILE); } catch {}
+      process.exit(1);
+    });
+
+    await new Promise(resolve => setTimeout(resolve, 500));
+
+    if (!spawnFailed && child.pid) {
+      try {
+        writeFileSync(PID_FILE, String(child.pid));
+      } catch (err) {
+        console.error(`[Agent] PID 文件写入失败: ${err.message}`);
+        process.exit(1);
+      }
+      child.unref();
+      console.log(`[Agent] Agent 已在后台重启 (PID: ${child.pid})`);
+      console.log(`[Agent] 使用 'ai-helper-agent stop' 停止服务`);
+    }
+
+    process.exit(spawnFailed ? 1 : 0);
+  }
+
+  // 前台模式
   console.log('[Agent] 正在启动 Agent...');
+  ensureAgentDir();
+  try {
+    writeFileSync(PID_FILE, String(process.pid));
+  } catch (err) {
+    console.error(`[Agent] PID 文件写入失败: ${err.message}`);
+  }
+
   const { startServer: restartServer } = await import('../src/server.js');
   const { loadConfig: restartConfig } = await import('../src/config.js');
-  const cfg = restartConfig();
-
-  // 应用命令行参数
-  const rargs = process.argv.slice(3);
-  for (let i = 0; i < rargs.length; i++) {
-    if (rargs[i] === '--port' && rargs[i + 1]) { cfg.port = parseInt(rargs[i + 1], 10); i++; }
-    else if (rargs[i] === '--host' && rargs[i + 1]) { cfg.host = rargs[i + 1]; i++; }
-    else if (rargs[i] === '--workdir' && rargs[i + 1]) { cfg.workdir = rargs[i + 1]; i++; }
-  }
+  const cfg = applyCliArgs(restartConfig(),
+    process.argv.slice(3).filter(a => a !== '--background' && a !== '-b'));
 
   console.log(`[Agent] 工作目录: ${cfg.workdir}`);
   restartServer();
@@ -166,7 +404,9 @@ if (command === 'start') {
       const resp = await fetch(`http://${config.host}:${config.port}/api/status`);
       const data = await resp.json();
       console.log(`[Agent] 版本:     ${data.version}`);
-    } catch {}
+    } catch (err) {
+      console.error(`[Agent] 获取状态失败: ${err.message}`);
+    }
   }
 
 // ==================== paircode ====================
@@ -179,7 +419,6 @@ if (command === 'start') {
     process.exit(1);
   }
 
-  // 配对码需要认证，如果没有 token 则直接查看（Agent 启动控制台会打印）
   console.log('[Agent] 配对码已显示在 Agent 启动终端中');
   console.log('[Agent] 请在启动 Agent 的终端窗口中查看配对码');
   console.log('');
@@ -190,7 +429,9 @@ if (command === 'start') {
       const data = await resp.json();
       console.log(`[Agent] 版本: ${data.version}`);
     }
-  } catch {}
+  } catch (err) {
+    console.error(`[Agent] 获取状态失败: ${err.message}`);
+  }
 
 // ==================== config ====================
 } else if (command === 'config') {

package/package.json

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