ai-helper-agent 1.0.0

package/README.md

@@ -0,0 +1,146 @@
+# AI Helper Agent
+
+AI Helper 本地代理服务，为 [AI Helper Chrome 扩展](https://github.com/xiweicheng/ai-helper) 提供本地文件读写和系统命令执行能力。
+
+## 安装
+
+```bash
+npm install -g ai-helper-agent
+```
+
+要求 Node.js >= 18.0.0。
+
+## 快速开始
+
+```bash
+# 启动 Agent（默认工作目录为当前目录）
+ai-helper-agent start
+
+# 指定工作目录
+ai-helper-agent start --workdir /path/to/your/project
+
+# 指定端口
+ai-helper-agent start --port 18911
+```
+
+启动后终端会显示 4 位配对码，在 Chrome 扩展设置页「本地Agent」标签中填入即可完成配对。
+
+## CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `start` | 启动 Agent 服务 |
+| `stop` | 停止正在运行的 Agent |
+| `restart` | 重启 Agent 服务 |
+| `status` | 查看运行状态 |
+| `paircode` | 查看配对码提示 |
+| `config` | 查看当前配置 |
+| `help` | 显示帮助信息 |
+| `--version` / `-v` | 显示版本号 |
+
+### 启动选项
+
+```
+--port <端口>      监听端口，默认 18910
+--host <地址>      监听地址，默认 127.0.0.1
+--workdir <目录>   工作目录（文件读写限制在此范围内）
+```
+
+## 安全机制
+
+### 文件沙箱
+所有文件操作限制在配置的 `allowedPaths` 白名单目录内。通过 `realpath` 解析防止符号链接绕过，确保物理路径安全。
+
+### 命令分级管控
+
+**黑名单** — 直接拦截，不可绕过：
+
+| 类型 | 示例 |
+|------|------|
+| 磁盘破坏 | `rm -rf /`、`mkfs.*`、`dd if=... of=/dev/...` |
+| 系统文件覆盖 | `> /etc/passwd`、`> /etc/shadow` |
+| 恶意管道执行 | `curl ... \| bash`、`git clone ... \| sh` |
+| Shell 注入 | 反引号、`$()`、`${}` 命令替换 |
+| Fork bomb | `:(){ :\|:& };:` |
+
+**灰名单** — 需要用户确认后才执行：
+
+| 命令模式 | 原因 |
+|----------|------|
+| `sudo ...` | 需要管理员权限 |
+| `npm install -g ...` | 全局安装包 |
+| `pip install/uninstall` | Python 包管理 |
+| `chmod -R 777` | 递归修改权限 |
+| `rm -rf ...` | 递归强制删除 |
+| `git push --force` | 强制推送 |
+| `shutdown/reboot` | 关机/重启 |
+
+### 认证机制
+
+首次配对时用户在扩展中输入终端显示的 4 位配对码完成配对。配对码每 30 秒轮换。配对成功后使用 HMAC token 做后续请求认证，存储在 `~/.ai-helper-agent/pairings.json`。
+
+## 配置
+
+配置文件路径：`~/.ai-helper-agent/config.json`
+
+```json
+{
+  "port": 18910,
+  "host": "127.0.0.1",
+  "workdir": "/path/to/project",
+  "allowedPaths": [],
+  "pairCodeTTL": 30,
+  "commandTimeout": 300000,
+  "fileMaxSize": 52428800
+}
+```
+
+| 字段 | 说明 | 默认值 |
+|------|------|--------|
+| `port` | 监听端口 | 18910 |
+| `host` | 监听地址 | 127.0.0.1 |
+| `workdir` | 默认工作目录 | 启动时当前目录 |
+| `allowedPaths` | 额外允许访问的目录列表 | `[]` |
+| `pairCodeTTL` | 配对码有效期（秒） | 30 |
+| `commandTimeout` | 命令执行超时（毫秒） | 300000（5分钟） |
+| `fileMaxSize` | 文件读写最大字节数 | 52428800（50MB） |
+
+## API 端点
+
+### 无需认证
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/pair` | 配对认证 |
+| GET | `/api/status` | 健康检查（版本号、运行状态） |
+
+### 需要认证（Bearer Token）
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| POST | `/api/fs/read` | 读取文件内容 |
+| POST | `/api/fs/write` | 写入文件 |
+| POST | `/api/fs/list` | 列出目录 |
+| POST | `/api/fs/delete` | 删除文件/目录 |
+| POST | `/api/exec` | 执行系统命令 |
+| POST | `/api/exec/stop` | 停止命令执行 |
+| GET | `/api/exec/running` | 运行中的进程列表 |
+| GET | `/api/status/detail` | 详细信息（含工作目录） |
+| POST | `/api/shutdown` | 关闭 Agent 服务 |
+
+### WebSocket
+
+| 路径 | 说明 |
+|------|------|
+| `ws://127.0.0.1:18910/ws/exec/:execId` | 命令执行实时输出流 |
+
+## 技术栈
+
+- Node.js >= 18
+- 原生 `http` 模块（HTTP 服务）
+- `ws` 库（WebSocket 服务）
+- 零外部框架依赖
+
+## License
+
+MIT

package/bin/agent.js

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+// agent/bin/agent.js - CLI 入口
+// 用法: ai-helper-agent <start|stop|restart|status|paircode|config> [options]
+import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+const AGENT_DIR = join(process.env.HOME || '~', '.ai-helper-agent');
+const CONFIG_FILE = join(AGENT_DIR, 'config.json');
+
+/**
+ * 读取 Agent 配置文件
+ */
+function readAgentConfig() {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      const raw = readFileSync(CONFIG_FILE, 'utf-8');
+      return JSON.parse(raw);
+    }
+  } catch {}
+  return { port: 18910, host: '127.0.0.1' };
+}
+
+/**
+ * 检查 Agent 是否在运行
+ */
+async function isRunning(config) {
+  try {
+    const resp = await fetch(`http://${config.host}:${config.port}/api/status`);
+    return resp.ok;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * 打印帮助信息
+ */
+function printHelp() {
+  console.log('AI Helper Agent - 本地文件读写和命令执行代理');
+  console.log('');
+  console.log('用法: ai-helper-agent <命令> [选项]');
+  console.log('');
+  console.log('命令:');
+  console.log('  start        启动 Agent 服务');
+  console.log('  stop         停止正在运行的 Agent');
+  console.log('  restart      重启 Agent 服务');
+  console.log('  status       查看 Agent 运行状态');
+  console.log('  paircode     查看当前配对码（需认证状态）');
+  console.log('  config       查看当前配置');
+  console.log('  help         显示此帮助信息');
+  console.log('');
+  console.log('启动选项:');
+  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 stop');
+  console.log('  ai-helper-agent restart');
+  console.log('  ai-helper-agent status');
+}
+
+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}`);
+  process.exit(0);
+}
+
+// ==================== start ====================
+if (command === 'start') {
+  const { startServer } = await import('../src/server.js');
+  const { loadConfig } = await import('../src/config.js');
+
+  console.log('[Agent] AI Helper Agent 启动中...');
+
+  const args = process.argv.slice(3);
+  const config = loadConfig();
+
+  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++;
+    }
+  }
+
+  console.log(`[Agent] 工作目录: ${config.workdir}`);
+  console.log(`[Agent] 监听地址: ${config.host}:${config.port}`);
+
+  startServer();
+
+// ==================== stop ====================
+} else if (command === 'stop') {
+  const config = readAgentConfig();
+  console.log('[Agent] 正在停止 Agent...');
+
+  const running = await isRunning(config);
+  if (!running) {
+    console.log('[Agent] Agent 未在运行');
+    process.exit(0);
+  }
+
+  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 可能已退出');
+  }
+
+// ==================== restart ====================
+} else if (command === 'restart') {
+  const config = readAgentConfig();
+  const running = await isRunning(config);
+
+  if (running) {
+    console.log('[Agent] 正在停止 Agent...');
+    try {
+      await fetch(`http://${config.host}:${config.port}/api/shutdown`, { method: 'POST' });
+    } catch {}
+    // 等待进程退出
+    await new Promise(resolve => setTimeout(resolve, 1500));
+  }
+
+  console.log('[Agent] 正在启动 Agent...');
+  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++; }
+  }
+
+  console.log(`[Agent] 工作目录: ${cfg.workdir}`);
+  restartServer();
+
+// ==================== status ====================
+} else if (command === 'status') {
+  const config = readAgentConfig();
+  const running = await isRunning(config);
+
+  console.log('[Agent] ======== Agent 状态 ========');
+  console.log(`[Agent] 监听地址: ${config.host}:${config.port}`);
+  console.log(`[Agent] 运行状态: ${running ? '✅ 运行中' : '❌ 未运行'}`);
+  console.log(`[Agent] 配置文件: ${CONFIG_FILE}`);
+
+  if (running) {
+    try {
+      const resp = await fetch(`http://${config.host}:${config.port}/api/status`);
+      const data = await resp.json();
+      console.log(`[Agent] 版本:     ${data.version}`);
+    } catch {}
+  }
+
+// ==================== paircode ====================
+} else if (command === 'paircode') {
+  const config = readAgentConfig();
+  const running = await isRunning(config);
+
+  if (!running) {
+    console.log('[Agent] Agent 未在运行，请先启动');
+    process.exit(1);
+  }
+
+  // 配对码需要认证，如果没有 token 则直接查看（Agent 启动控制台会打印）
+  console.log('[Agent] 配对码已显示在 Agent 启动终端中');
+  console.log('[Agent] 请在启动 Agent 的终端窗口中查看配对码');
+  console.log('');
+  console.log('[Agent] 或查看状态获取更多信息:');
+  try {
+    const resp = await fetch(`http://${config.host}:${config.port}/api/status`);
+    if (resp.ok) {
+      const data = await resp.json();
+      console.log(`[Agent] 版本: ${data.version}`);
+    }
+  } catch {}
+
+// ==================== config ====================
+} else if (command === 'config') {
+  const config = readAgentConfig();
+  console.log('[Agent] ======== 当前配置 ========');
+  console.log(JSON.stringify(config, null, 2));
+  console.log(`[Agent] 配置文件位置: ${CONFIG_FILE}`);
+
+// ==================== help ====================
+} else {
+  printHelp();
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "ai-helper-agent",
+  "version": "1.0.0",
+  "description": "AI Helper 本地代理服务 - 为 Chrome 扩展提供本地文件读写和系统命令执行能力",
+  "type": "module",
+  "main": "./src/server.js",
+  "bin": {
+    "ai-helper-agent": "./bin/agent.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/agent.js start",
+    "stop": "node bin/agent.js stop",
+    "status": "node bin/agent.js status"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "ai-helper",
+    "local-agent",
+    "chrome-extension",
+    "file-manager",
+    "command-executor",
+    "developer-tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "homepage": "",
+  "bugs": {
+    "url": ""
+  }
+}

package/src/auth.js

@@ -0,0 +1,124 @@
+// agent/src/auth.js - 配对认证模块
+import crypto from 'crypto';
+import { loadConfig, loadPairings, savePairing } from './config.js';
+
+// 当前有效的配对码（30秒刷新一次）
+let currentPairCode = null;
+let pairCodeTimer = null;
+
+/**
+ * 生成随机配对码（4位数字）
+ */
+function generatePairCode() {
+  return String(Math.floor(1000 + Math.random() * 9000));
+}
+
+/**
+ * 生成认证 token（HMAC-SHA256）
+ */
+function generateToken(extensionId) {
+  const secret = crypto.randomBytes(32).toString('hex');
+  const pairings = loadPairings();
+  pairings[extensionId] = {
+    token: secret,
+    pairedAt: Date.now()
+  };
+  // 直接用 secret 作为 token
+  return secret;
+}
+
+/**
+ * 验证 token 是否有效
+ */
+function verifyToken(token) {
+  if (!token) return null;
+  const pairings = loadPairings();
+  for (const [extId, pairing] of Object.entries(pairings)) {
+    if (pairing.token === token) {
+      return extId;
+    }
+  }
+  return null;
+}
+
+/**
+ * 获取当前配对码
+ */
+function getCurrentPairCode() {
+  return currentPairCode;
+}
+
+/**
+ * 启动配对码定时刷新
+ */
+function startPairCodeRotation() {
+  const config = loadConfig();
+  const ttl = (config.pairCodeTTL || 30) * 1000;
+
+  currentPairCode = generatePairCode();
+  console.log(`[Agent] 当前配对码: ${currentPairCode}`);
+
+  if (pairCodeTimer) clearInterval(pairCodeTimer);
+  pairCodeTimer = setInterval(() => {
+    currentPairCode = generatePairCode();
+    console.log(`[Agent] 配对码已更新: ${currentPairCode}`);
+  }, ttl);
+}
+
+/**
+ * 停止配对码定时刷新
+ */
+function stopPairCodeRotation() {
+  if (pairCodeTimer) {
+    clearInterval(pairCodeTimer);
+    pairCodeTimer = null;
+  }
+}
+
+/**
+ * 处理配对请求
+ */
+function handlePairRequest(code, extensionId) {
+  if (!code || !extensionId) {
+    return { success: false, error: '缺少配对码或扩展ID' };
+  }
+  if (code !== currentPairCode) {
+    return { success: false, error: '配对码无效' };
+  }
+  // 检查是否已有配对
+  const pairings = loadPairings();
+  if (pairings[extensionId]) {
+    return { success: true, token: pairings[extensionId].token, message: '已配对，返回现有 token' };
+  }
+  // 生成新 token 并保存
+  const token = crypto.randomBytes(32).toString('hex');
+  savePairing(extensionId, token);
+  return { success: true, token, message: '配对成功' };
+}
+
+/**
+ * Bearer Token 认证中间件（Express）
+ */
+function authMiddleware(req, res, next) {
+  const authHeader = req.headers.authorization;
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({ success: false, error: '未提供认证 token' });
+  }
+  const token = authHeader.slice(7);
+  const extId = verifyToken(token);
+  if (!extId) {
+    return res.status(403).json({ success: false, error: '认证 token 无效' });
+  }
+  req.extensionId = extId;
+  next();
+}
+
+export {
+  generateToken,
+  verifyToken,
+  getCurrentPairCode,
+  startPairCodeRotation,
+  stopPairCodeRotation,
+  handlePairRequest,
+  authMiddleware
+};

package/src/config.js

@@ -0,0 +1,136 @@
+// agent/src/config.js - 配置管理（带内存缓存）
+import { homedir } from 'os';
+import { join } from 'path';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'fs';
+
+const AGENT_DIR = join(homedir(), '.ai-helper-agent');
+const CONFIG_FILE = join(AGENT_DIR, 'config.json');
+const PAIRINGS_FILE = join(AGENT_DIR, 'pairings.json');
+
+const DEFAULTS = {
+  port: 18910,
+  host: '127.0.0.1',
+  workdir: process.cwd(),
+  allowedPaths: [],
+  pairCodeTTL: 30,
+  commandTimeout: 300000,
+  fileMaxSize: 50 * 1024 * 1024
+};
+
+// 内存缓存
+let configCache = null;
+let configCacheMtime = 0;
+
+let pairingsCache = null;
+let pairingsCacheMtime = 0;
+
+function ensureAgentDir() {
+  if (!existsSync(AGENT_DIR)) {
+    mkdirSync(AGENT_DIR, { recursive: true });
+  }
+}
+
+/**
+ * 获取文件的 mtime（ms），不存在返回 0
+ */
+function getMtime(filePath) {
+  try {
+    return statSync(filePath).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * 加载配置（带缓存，仅在文件变化时重新读取）
+ */
+export function loadConfig() {
+  ensureAgentDir();
+
+  if (!existsSync(CONFIG_FILE)) {
+    const defaults = { ...DEFAULTS, allowedPaths: [DEFAULTS.workdir] };
+    saveConfig(defaults);
+    configCache = defaults;
+    configCacheMtime = getMtime(CONFIG_FILE);
+    return defaults;
+  }
+
+  const mtime = getMtime(CONFIG_FILE);
+  if (configCache && mtime === configCacheMtime) {
+    return configCache;
+  }
+
+  try {
+    const raw = readFileSync(CONFIG_FILE, 'utf-8');
+    const userConfig = JSON.parse(raw);
+    configCache = { ...DEFAULTS, ...userConfig };
+    configCacheMtime = mtime;
+    return configCache;
+  } catch {
+    configCache = { ...DEFAULTS, allowedPaths: [DEFAULTS.workdir] };
+    configCacheMtime = 0;
+    return configCache;
+  }
+}
+
+/**
+ * 保存配置（写入磁盘并更新缓存）
+ */
+export function saveConfig(config) {
+  ensureAgentDir();
+  writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
+  configCache = config;
+  configCacheMtime = getMtime(CONFIG_FILE);
+}
+
+/**
+ * 更新单字段配置
+ */
+export function updateConfigField(key, value) {
+  const config = loadConfig();
+  config[key] = value;
+  saveConfig(config);
+  return config;
+}
+
+/**
+ * 读取已配对的扩展列表（带缓存）
+ */
+export function loadPairings() {
+  ensureAgentDir();
+
+  const mtime = getMtime(PAIRINGS_FILE);
+  if (pairingsCache && mtime === pairingsCacheMtime) {
+    return pairingsCache;
+  }
+
+  if (!existsSync(PAIRINGS_FILE)) {
+    pairingsCache = {};
+    pairingsCacheMtime = 0;
+    return {};
+  }
+
+  try {
+    pairingsCache = JSON.parse(readFileSync(PAIRINGS_FILE, 'utf-8'));
+    pairingsCacheMtime = mtime;
+    return pairingsCache;
+  } catch {
+    pairingsCache = {};
+    pairingsCacheMtime = 0;
+    return {};
+  }
+}
+
+/**
+ * 保存配对（写入磁盘并更新缓存）
+ */
+export function savePairing(extensionId, token) {
+  const pairings = loadPairings();
+  pairings[extensionId] = { token, pairedAt: Date.now() };
+  ensureAgentDir();
+  writeFileSync(PAIRINGS_FILE, JSON.stringify(pairings, null, 2), 'utf-8');
+  pairingsCache = pairings;
+  pairingsCacheMtime = getMtime(PAIRINGS_FILE);
+}
+
+export { AGENT_DIR, CONFIG_FILE };

package/src/executor.js

@@ -0,0 +1,191 @@
+// agent/src/executor.js - 命令执行器（child_process + 流式输出）
+import { spawn } from 'child_process';
+import crypto from 'crypto';
+import { loadConfig } from './config.js';
+
+// 运行中的进程映射：execId → { process, wsClients: Set, timeoutId, forceKillId }
+const runningProcesses = new Map();
+
+/**
+ * 生成唯一执行 ID
+ */
+function generateExecId() {
+  return crypto.randomBytes(8).toString('hex');
+}
+
+/**
+ * 执行命令并通过 WebSocket 流式输出
+ * @param {string} command - 完整命令字符串
+ * @param {string} [cwd] - 工作目录
+ * @param {Object} wsClient - 单个 WebSocket 客户端（用于流式输出）
+ * @param {Function} onComplete - 完成回调 ({ execId, exitCode, killed, stdout?, stderr? })
+ * @param {boolean} [collectOutput=false] - 是否收集完整 stdout/stderr 到内存
+ * @returns {string} execId
+ */
+function executeCommand(command, cwd, wsClient, onComplete, collectOutput = false) {
+  const config = loadConfig();
+  const workdir = cwd || config.workdir;
+  const execId = generateExecId();
+  const timeout = config.commandTimeout || 300000;
+
+  const proc = spawn('sh', ['-c', command], {
+    cwd: workdir,
+    env: { ...process.env, TERM: 'dumb', FORCE_COLOR: '0' },
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+
+  const wsClients = new Set();
+  if (wsClient) wsClients.add(wsClient);
+
+  let stdoutCollected = '';
+  let stderrCollected = '';
+  let killed = false;
+  let forceKillId = null; // 追踪 SIGKILL 的 setTimeout
+
+  runningProcesses.set(execId, { process: proc, wsClients });
+
+  // 超时控制
+  const timeoutId = setTimeout(() => {
+    killed = true;
+    killProcess(execId);
+  }, timeout);
+
+  // 广播消息给所有连接的 WS 客户端
+  function broadcast(data) {
+    const msg = JSON.stringify(data);
+    for (const client of wsClients) {
+      if (client.readyState === 1) {
+        client.send(msg);
+      }
+    }
+  }
+
+  // stdout 流式输出
+  proc.stdout.on('data', (chunk) => {
+    const str = chunk.toString();
+    if (collectOutput) stdoutCollected += str;
+    broadcast({ type: 'stdout', data: str, execId });
+  });
+
+  // stderr 流式输出
+  proc.stderr.on('data', (chunk) => {
+    const str = chunk.toString();
+    if (collectOutput) stderrCollected += str;
+    broadcast({ type: 'stderr', data: str, execId });
+  });
+
+  // 清理超时计时器
+  function clearTimers() {
+    clearTimeout(timeoutId);
+    if (forceKillId !== null) {
+      clearTimeout(forceKillId);
+      forceKillId = null;
+    }
+  }
+
+  // 进程结束
+  proc.on('close', (exitCode) => {
+    clearTimers();
+    broadcast({ type: 'exit', exitCode, execId, killed });
+    runningProcesses.delete(execId);
+    if (onComplete) {
+      onComplete({
+        execId, exitCode, killed,
+        stdout: collectOutput ? stdoutCollected : undefined,
+        stderr: collectOutput ? stderrCollected : undefined
+      });
+    }
+  });
+
+  // 进程错误
+  proc.on('error', (err) => {
+    clearTimers();
+    broadcast({ type: 'error', error: err.message, execId });
+    runningProcesses.delete(execId);
+    if (onComplete) {
+      onComplete({
+        execId, exitCode: -1, killed: false,
+        error: err.message,
+        stdout: collectOutput ? stdoutCollected : undefined,
+        stderr: collectOutput ? stderrCollected : undefined
+      });
+    }
+  });
+
+  return execId;
+}
+
+/**
+ * 同步执行命令（阻塞等待完成，返回完整输出）
+ * @returns {Promise<{execId, exitCode, stdout, stderr, killed, error?}>}
+ */
+function executeCommandSync(command, cwd) {
+  return new Promise((resolve, reject) => {
+    const config = loadConfig();
+    const timeout = config.commandTimeout || 300000;
+
+    let resolved = false;
+
+    const execId = executeCommand(command, cwd, null, (result) => {
+      if (!resolved) {
+        resolved = true;
+        resolve(result);
+      }
+    }, true);
+
+    // 超时兜底
+    setTimeout(() => {
+      if (!resolved) {
+        resolved = true;
+        killProcess(execId);
+        resolve({ execId, exitCode: -1, killed: true, stdout: '', stderr: '', error: 'Command timed out' });
+      }
+    }, timeout + 5000);
+  });
+}
+
+/**
+ * 添加 WebSocket 客户端到已有进程的监听中
+ */
+function addWsClient(execId, wsClient) {
+  const entry = runningProcesses.get(execId);
+  if (entry) {
+    entry.wsClients.add(wsClient);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 停止正在运行的命令
+ */
+function killProcess(execId) {
+  const entry = runningProcesses.get(execId);
+  if (entry) {
+    entry.process.kill('SIGTERM');
+    // 5秒后强制 kill，保存 ID 以便后续清理
+    const forceKillId = setTimeout(() => {
+      try {
+        if (entry.process.exitCode === null) {
+          entry.process.kill('SIGKILL');
+        }
+      } catch {}
+    }, 5000);
+    entry.forceKillId = forceKillId;
+    return true;
+  }
+  return false;
+}
+
+/**
+ * 获取运行中的进程列表
+ */
+function getRunningProcesses() {
+  const list = [];
+  for (const [execId] of runningProcesses) {
+    list.push({ execId });
+  }
+  return list;
+}
+
+export { executeCommand, executeCommandSync, addWsClient, killProcess, getRunningProcesses };

package/src/security.js

@@ -0,0 +1,155 @@
+// agent/src/security.js - 安全管控：文件沙箱 + 命令分级
+import { resolve, normalize } from 'path';
+import { realpathSync } from 'fs';
+import { loadConfig } from './config.js';
+
+/**
+ * 检查路径是否在白名单内
+ * 使用 realpathSync 防止符号链接绕过
+ * @returns {{ allowed: boolean, reason?: string, resolved?: string }}
+ */
+function checkPath(pathStr) {
+  if (!pathStr || typeof pathStr !== 'string') {
+    return { allowed: false, reason: '路径无效' };
+  }
+
+  try {
+    const resolved = resolve(pathStr);
+    const normalized = normalize(resolved);
+
+    const config = loadConfig();
+    const allowedPaths = config.allowedPaths.length > 0 ? config.allowedPaths : [config.workdir];
+
+    // 先做前缀检查（快速路径）
+    let prefixMatch = false;
+    let matchedAllowed = null;
+    for (const allowed of allowedPaths) {
+      const allowedResolved = resolve(allowed);
+      if (normalized.startsWith(allowedResolved + '/') || normalized === allowedResolved) {
+        prefixMatch = true;
+        matchedAllowed = allowedResolved;
+        break;
+      }
+    }
+    if (!prefixMatch) {
+      return { allowed: false, reason: `路径不在允许的目录范围内` };
+    }
+
+    // realpath 校验：防止符号链接绕过
+    // 注意：文件可能尚未创建，realpathSync 会抛出 ENOENT
+    let realPath;
+    try {
+      realPath = realpathSync(resolved);
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        // 文件不存在时，检查父目录
+        const parentDir = resolve(resolved, '..');
+        realPath = realpathSync(parentDir) + '/' + normalized.split('/').pop();
+      } else {
+        return { allowed: false, reason: `无法解析路径: ${err.message}` };
+      }
+    }
+
+    // 对 realPath 再次做前缀检查
+    for (const allowed of allowedPaths) {
+      const allowedResolved = resolve(allowed);
+      if (realPath.startsWith(allowedResolved + '/') || realPath === allowedResolved) {
+        return { allowed: true, resolved: normalized };
+      }
+    }
+
+    return { allowed: false, reason: `路径指向了允许范围之外的位置` };
+  } catch (err) {
+    return { allowed: false, reason: `路径检查异常: ${err.message}` };
+  }
+}
+
+// ==================== 命令分级管控 ====================
+
+const BLACKLIST_PATTERNS = [
+  // 高危写入系统目录
+  /^\s*rm\s+-rf\s+\/(\*|\s|$)/,
+  /^\s*rm\s+-rf\s+~(\*|\s|$)/,
+  /^\s*rm\s+-rf\s+\/dev\//,
+  /^\s*rm\s+-rf\s+\/etc\//,
+  /^\s*rm\s+-rf\s+\/proc\//,
+  /^\s*rm\s+-rf\s+\/sys\//,
+  // 格式化/磁盘破坏
+  /^\s*mkfs\./,
+  /^\s*dd\s+if=.*of=\/dev\//,
+  /^\s*>\s*\/dev\/sd/,
+  // 覆盖系统文件
+  /^\s*>\s*\/etc\/passwd/,
+  /^\s*>\s*\/etc\/shadow/,
+  /^\s*>\s*\/etc\/sudoers/,
+  // fork bomb
+  /:\(\)\s*{\s*:\s*\|\s*:\s*&\s*};\s*:/,
+  /#!/,
+  // 恶意管道执行
+  /(curl|wget|lynx|links)\s+.*\|\s*(ba)?sh/,
+  /git\s+clone\s+.*\|\s*(ba)?sh/,
+  // 修改根目录权限
+  /^\s*chmod\s+(-R\s+)?(0?777|a\+rwx)\s+\//,
+  /^\s*chown\s+-R\s+\S+\s+\//,
+  // Shell 命令替换注入
+  /`[^`]*`/,                   // 反引号命令替换
+  /\$\([^)]*\)/,               // $() 命令替换
+  /\$\{[^}]*\}/,               // ${} 变量替换（可能含命令）
+];
+
+const GRAYLIST_PATTERNS = [
+  { pattern: /^\s*sudo\s/, reason: '命令需要管理员权限 (sudo)' },
+  { pattern: /npm\s+(i|install)\s+-g\s/, reason: '全局安装 npm 包' },
+  { pattern: /pip\s+(install|uninstall)\s/, reason: 'pip 安装/卸载包' },
+  { pattern: /^\s*chmod\s+-R\s+777\s/, reason: '递归修改权限为 777' },
+  { pattern: /^\s*rm\s+-rf\s+(?!\/|~)/, reason: '递归强制删除文件/目录' },
+  { pattern: /git\s+push\s+(-f|--force)/, reason: 'Git 强制推送' },
+  { pattern: /^\s*(shutdown|reboot|halt|poweroff)/, reason: '关机或重启系统' },
+  { pattern: /^\s*>\s*\/etc\/hosts/, reason: '修改系统 hosts 文件' },
+  { pattern: /\beval\s+/, reason: '使用 eval 执行命令' },
+];
+
+/**
+ * 检查命令安全性
+ * @param {boolean} [force=false] - 强制放行（用户确认后的调用）
+ * @returns {{ safe: boolean, level: 'allow'|'confirm'|'deny', reason?: string }}
+ */
+function checkCommand(command, force = false) {
+  if (!command || typeof command !== 'string') {
+    return { safe: false, level: 'deny', reason: '命令无效' };
+  }
+
+  const trimmed = command.trim();
+
+  // 强制模式：跳过所有检查
+  if (force) {
+    return { safe: true, level: 'allow' };
+  }
+
+  // 1. 先检查黑名单
+  for (const pattern of BLACKLIST_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return {
+        safe: false,
+        level: 'deny',
+        reason: `高危命令被拦截: "${trimmed.substring(0, 100)}"`
+      };
+    }
+  }
+
+  // 2. 检查灰名单
+  for (const entry of GRAYLIST_PATTERNS) {
+    if (entry.pattern.test(trimmed)) {
+      return {
+        safe: false,
+        level: 'confirm',
+        reason: entry.reason
+      };
+    }
+  }
+
+  // 3. 通过安全检查
+  return { safe: true, level: 'allow' };
+}
+
+export { checkPath, checkCommand };

package/src/server.js

@@ -0,0 +1,319 @@
+// agent/src/server.js - HTTP Router + WebSocket 服务器
+import http from 'http';
+import { WebSocketServer } from 'ws';
+import { readFileSync, writeFileSync, readdirSync, statSync, unlinkSync, rmdirSync, existsSync } from 'fs';
+import { join } from 'path';
+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';
+
+const MAX_BODY_SIZE = 10 * 1024 * 1024; // 10MB
+
+/**
+ * JSON 响应辅助
+ */
+function jsonResponse(res, status, data) {
+  res.writeHead(status, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Access-Control-Allow-Origin': '*',
+    'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+    'Access-Control-Allow-Methods': 'GET, POST, OPTIONS'
+  });
+  res.end(JSON.stringify(data));
+}
+
+/**
+ * 解析请求 body（带大小限制）
+ */
+function parseBody(req) {
+  return new Promise((resolve, reject) => {
+    const contentLength = parseInt(req.headers['content-length'] || '0', 10);
+    if (contentLength > MAX_BODY_SIZE) {
+      reject(new Error('请求体过大'));
+      return;
+    }
+
+    const chunks = [];
+    let totalSize = 0;
+
+    req.on('data', (chunk) => {
+      totalSize += chunk.length;
+      if (totalSize > MAX_BODY_SIZE) {
+        reject(new Error('请求体过大'));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+
+    req.on('end', () => {
+      const body = Buffer.concat(chunks).toString();
+      try { resolve(JSON.parse(body)); }
+      catch { resolve({}); }
+    });
+
+    req.on('error', () => reject(new Error('读取请求失败')));
+  });
+}
+
+/**
+ * 创建并启动服务器
+ */
+export function startServer() {
+  const config = loadConfig();
+  const { port, host } = config;
+
+  // ==================== HTTP Server ====================
+  const server = http.createServer(async (req, res) => {
+    // CORS 预检
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+        'Access-Control-Allow-Methods': 'GET, POST, OPTIONS'
+      });
+      return res.end();
+    }
+
+    const url = new URL(req.url, `http://${host}:${port}`);
+    const pathname = url.pathname;
+
+    // ---------- 无需认证的接口 ----------
+
+    // 配对
+    if (req.method === 'POST' && pathname === '/api/pair') {
+      let body;
+      try { body = await parseBody(req); }
+      catch (err) { return jsonResponse(res, 400, { success: false, error: err.message }); }
+      const result = handlePairRequest(body.code, body.extensionId);
+      return jsonResponse(res, result.success ? 200 : 400, result);
+    }
+
+    // 健康检查（不含敏感信息）
+    if (req.method === 'GET' && pathname === '/api/status') {
+      return jsonResponse(res, 200, {
+        success: true,
+        version: '1.0.0',
+        running: true
+      });
+    }
+
+    // ---------- 需要认证的接口 ----------
+    const authHeader = req.headers.authorization;
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return jsonResponse(res, 401, { success: false, error: '未提供认证 token' });
+    }
+    const token = authHeader.slice(7);
+    const extId = verifyToken(token);
+    if (!extId) {
+      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,
+        version: '1.0.0',
+        pairCode: getCurrentPairCode(),
+        workdir: config.workdir,
+        runningProcesses: getRunningProcesses()
+      });
+    }
+
+    if (req.method === 'POST') {
+      let body;
+      try { body = await parseBody(req); }
+      catch (err) { return jsonResponse(res, 400, { success: false, error: err.message }); }
+
+      // === 文件操作 ===
+
+      // 读取文件
+      if (pathname === '/api/fs/read') {
+        const check = checkPath(body.path);
+        if (!check.allowed) 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 content = readFileSync(check.resolved, 'utf-8');
+        return jsonResponse(res, 200, { success: true, content, size: stat.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 });
+        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');
+        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 });
+        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 entries = readdirSync(check.resolved).map(name => {
+          const fullPath = join(check.resolved, name);
+          try {
+            const s = statSync(fullPath);
+            return { name, type: s.isDirectory() ? 'directory' : 'file', size: s.size, mtime: s.mtimeMs };
+          } catch { return { name, type: 'unknown', size: 0, mtime: 0 }; }
+        });
+        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 (!existsSync(check.resolved)) return jsonResponse(res, 404, { success: false, error: '文件/目录不存在' });
+        const stat = statSync(check.resolved);
+        if (stat.isDirectory()) {
+          rmdirSync(check.resolved, { recursive: true });
+        } else {
+          unlinkSync(check.resolved);
+        }
+        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 参数' });
+
+        // 校验 cwd
+        let resolvedCwd = cwd || config.workdir;
+        const cwdCheck = checkPath(resolvedCwd);
+        if (!cwdCheck.allowed) {
+          return jsonResponse(res, 403, { success: false, error: '执行目录校验失败: ' + cwdCheck.reason });
+        }
+
+        // 安全检查
+        const cmdCheck = checkCommand(command, force);
+        if (cmdCheck.level === 'deny') {
+          return jsonResponse(res, 403, { success: false, error: cmdCheck.reason, level: 'deny' });
+        }
+        if (cmdCheck.level === 'confirm') {
+          return jsonResponse(res, 200, { success: true, level: 'confirm', reason: cmdCheck.reason, command, cwd });
+        }
+
+        // 同步等待模式（用于扩展端获取完整输出）
+        if (wait) {
+          try {
+            const result = await executeCommandSync(command, resolvedCwd);
+            return jsonResponse(res, 200, {
+              success: true,
+              level: 'allow',
+              execId: result.execId,
+              exitCode: result.exitCode,
+              stdout: result.stdout || '',
+              stderr: result.stderr || '',
+              killed: result.killed,
+              error: result.error
+            });
+          } catch (err) {
+            return jsonResponse(res, 500, { success: false, error: `命令执行异常: ${err.message}` });
+          }
+        }
+
+        // 异步模式（返回 execId，适用于 WebSocket 场景）
+        const execId = executeCommand(command, resolvedCwd, null, null);
+        return jsonResponse(res, 200, {
+          success: true,
+          level: 'allow',
+          execId,
+          wsUrl: `ws://${host}:${port}/ws/exec/${execId}`
+        });
+      }
+
+      // 停止命令
+      if (pathname === '/api/exec/stop') {
+        const stopped = killProcess(body.execId);
+        return jsonResponse(res, 200, { success: stopped, execId: body.execId });
+      }
+    }
+
+    // 运行中进程列表（需认证）
+    if (req.method === 'GET' && pathname === '/api/exec/running') {
+      return jsonResponse(res, 200, { success: true, processes: getRunningProcesses() });
+    }
+
+    // Agent 关闭（需认证，POST 方法）
+    if (req.method === 'POST' && pathname === '/api/shutdown') {
+      jsonResponse(res, 200, { success: true, message: 'Agent 正在关闭...' });
+      shutdown();
+      return;
+    }
+
+    // 404
+    jsonResponse(res, 404, { success: false, error: '未知的 API 路径' });
+  });
+
+  // ==================== WebSocket Server ====================
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on('upgrade', (request, socket, head) => {
+    const url = new URL(request.url, `http://${host}:${port}`);
+    const pathParts = url.pathname.split('/');
+
+    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 ')) {
+        token = authHeader.slice(7);
+      } else {
+        token = url.searchParams.get('token');
+      }
+      if (!verifyToken(token)) {
+        socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
+        socket.destroy();
+        return;
+      }
+
+      wss.handleUpgrade(request, socket, head, (ws) => {
+        const added = addWsClient(execId, ws);
+        if (!added) {
+          ws.send(JSON.stringify({ type: 'error', error: '进程不存在或已结束', execId }));
+        }
+      });
+    } else {
+      socket.destroy();
+    }
+  });
+
+  // 启动服务器
+  server.listen(port, host, () => {
+    console.log(`[Agent] HTTP 服务已启动: http://${host}:${port}`);
+    console.log(`[Agent] WebSocket 服务已启动: ws://${host}:${port}`);
+    startPairCodeRotation();
+  });
+
+  // 优雅关闭
+  function shutdown() {
+    console.log('[Agent] 正在关闭...');
+    stopPairCodeRotation();
+    for (const entry of getRunningProcesses()) {
+      killProcess(entry.execId);
+    }
+    wss.close();
+    server.close();
+    process.exit(0);
+  }
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+
+  return { server, wss, shutdown };
+}