ai-helper-agent 1.3.4 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # AI Helper Agent
 
-AI Helper 本地代理服务，为 [AI Helper Chrome 扩展](https://github.com/xiweicheng/ai-helper) 提供本地文件读写和系统命令执行能力。
+AI Helper 代理服务，为 [AI Helper Chrome 扩展](https://github.com/xiweicheng/ai-helper) 提供本地文件读写、系统命令执行、Skill 技能系统和 MCP 协议扩展能力。
 
 ## 安装
 
@@ -24,16 +24,16 @@ ai-helper-agent start -b
 ai-helper-agent start --workdir /path/to/your/project --port 18911
 ```
 
-启动后终端会显示 4 位配对码，在 Chrome 扩展设置页「本地Agent」标签中填入即可完成配对。
+启动后终端会显示 4 位配对码，在 Chrome 扩展设置页「代理」标签中填入即可完成配对。
 
 ## CLI 命令
 
 | 命令 | 说明 |
 |------|------|
-| `start` | 启动 Agent 服务（前台运行，显示实时日志） |
+| `start` | 启动代理服务（前台运行，显示实时日志） |
 | `start --background` / `start -b` | 后台启动（守护进程模式） |
 | `stop` | 停止正在运行的 Agent |
-| `restart` | 重启 Agent 服务（支持 -b 后台重启） |
+| `restart` | 重启代理服务（支持 -b 后台重启） |
 | `status` | 查看运行状态 |
 | `paircode` | 查看配对码提示 |
 | `config` | 查看当前配置 |
@@ -207,7 +207,7 @@ GET /api/logs/dates
 |------|------|------|
 | POST | `/api/pair` | 配对认证 |
 | GET | `/api/status` | 健康检查（版本号、平台信息、搜索工具可用性） |
-| POST | `/api/shutdown` | 关闭 Agent 服务（仅限本地访问） |
+| POST | `/api/shutdown` | 关闭代理服务（仅限本地访问） |
 
 ### 需要认证（Bearer Token）
 
@@ -243,6 +243,120 @@ Agent 内置多层异常保护，防止单个错误导致整个服务崩溃：
 - **文件 I/O 保护**：配置文件读写失败不影响服务运行
 - **进程管理保护**：`SIGTERM`/`SIGKILL` 发送对已退出进程有 try-catch 保护
 
+## Skill 系统
+
+Agent 服务内置 Skill 系统，支持将操作流程沉淀为可复用的技能。
+
+### Skill 类型
+
+| 类型 | 定义格式 | 执行方式 | 用途 |
+|------|----------|----------|------|
+| **Workflow Skill** | JSON/YAML | 直接执行 | 自动化流程，按步骤执行 |
+| **Agent Skill** | SKILL.md | AI 自主调用 | 知识沉淀，在对话中触发 |
+
+### Skill 目录结构
+
+所有 Skill 存储在 `~/.ai-helper-agent/skills/` 目录下：
+
+```
+~/.ai-helper-agent/skills/
+├── workflow-skill.json          # Workflow Skill（JSON 格式）
+├── another-skill.yaml           # Workflow Skill（YAML 格式）
+└── agent-skill/                 # Agent Skill（目录形式）
+    ├── SKILL.md                 # 技能定义文件
+    └── _meta.json               # 元数据（可选）
+```
+
+### SKILL.md 格式
+
+```markdown
+---
+name: <skill-name>
+description: "<简明描述，包含：(1) 技能做什么，(2) 何时触发调用>"
+enabled: true
+---
+
+# <技能标题>
+
+## When to Use This Skill
+
+- 触发条件1
+- 触发条件2
+
+## Core Capabilities
+
+- 能力1
+- 能力2
+
+## Usage
+
+### Step-by-Step
+
+1. 步骤1
+2. 步骤2
+
+## Examples
+
+[具体示例]
+
+## Source
+
+从对话中沉淀，创建日期：YYYY-MM-DD
+```
+
+### 内置技能
+
+- **skill-creator**：元技能，用于从对话中创建和更新其他技能
+
+### Skill API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/skill/list` | 获取所有 Skill 列表 |
+| GET | `/api/skill/:name` | 获取单个 Skill 完整定义 |
+| POST | `/api/skill/import` | 导入新 Skill |
+| POST | `/api/skill/:name/toggle` | 切换启用/停用状态 |
+| DELETE | `/api/skill/:name` | 删除 Skill |
+| POST | `/api/skill/:name/run` | 执行 Workflow Skill |
+
+## MCP 协议扩展
+
+支持 Model Context Protocol（MCP），扩展第三方工具能力。
+
+### MCP Server 配置
+
+配置文件路径：`~/.ai-helper-agent/config.json`
+
+```json
+{
+  "mcpServers": [
+    {
+      "id": "my-mcp-server",
+      "name": "My MCP Server",
+      "command": ["python", "-m", "my_mcp_server"],
+      "enabled": true
+    }
+  ]
+}
+```
+
+### MCP API
+
+| 方法 | 路径 | 说明 |
+|------|------|------|
+| GET | `/api/mcp/status` | 获取所有 MCP Server 状态 |
+| POST | `/api/mcp/:serverId/connect` | 连接指定 MCP Server |
+| POST | `/api/mcp/:serverId/disconnect` | 断开连接 |
+| GET | `/api/mcp/tools` | 获取所有 MCP 工具列表 |
+
+### 工作原理
+
+1. Agent 启动时自动连接所有启用的 MCP Server
+2. 通过 stdio 建立 JSON-RPC 2.0 通信
+3. 自动发现 MCP Server 提供的工具
+4. 工具调用请求通过 Agent 转发到 MCP Server
+5. 工具结果返回给扩展
+
 ## 技术栈
 
 - Node.js >= 18

package/bin/agent.js

@@ -9,6 +9,8 @@ import { homedir } from 'os';
 const AGENT_DIR = join(homedir(), '.ai-helper-agent');
 const CONFIG_FILE = join(AGENT_DIR, 'config.json');
 const PID_FILE = join(AGENT_DIR, 'agent.pid');
+const SKILLS_DIR = join(AGENT_DIR, 'skills');
+const WORKSPACE_DIR = join(AGENT_DIR, 'workspace');
 
 /**
  * 读取 Agent 配置文件
@@ -29,12 +31,18 @@ function readAgentConfig() {
  * 确保 Agent 配置目录存在
  */
 function ensureAgentDir() {
-  if (!existsSync(AGENT_DIR)) {
-    try {
+  try {
+    if (!existsSync(AGENT_DIR)) {
       mkdirSync(AGENT_DIR, { recursive: true });
-    } catch (err) {
-      console.error(`[Agent] 无法创建配置目录 ${AGENT_DIR}: ${err.message}`);
     }
+    // 确保 skills 和 workspace 子目录存在
+    for (const dir of [SKILLS_DIR, WORKSPACE_DIR]) {
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+    }
+  } catch (err) {
+    console.error(`[Agent] 无法创建配置目录 ${AGENT_DIR}: ${err.message}`);
   }
 }
 
@@ -122,10 +130,10 @@ function printHelp() {
   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('  start        启动代理服务（前台运行）');
+  console.log('  stop         停止正在运行的代理');
+  console.log('  restart      重启代理服务');
+  console.log('  status       查看代理运行状态');
   console.log('  paircode     查看当前配对码（需认证状态）');
   console.log('  config       查看当前配置');
   console.log('  help         显示此帮助信息');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-helper-agent",
-  "version": "1.3.4",
-  "description": "AI Helper 本地代理服务 - 为 Chrome 扩展提供本地文件读写和系统命令执行能力",
+  "version": "1.5.0",
+  "description": "AI Helper 代理服务 - 为 Chrome 扩展提供本地文件读写和系统命令执行能力",
   "type": "module",
   "main": "./src/server.js",
   "bin": {
@@ -39,6 +39,6 @@
   },
   "homepage": "",
   "bugs": {
-    "url": ""
+    "url": "https://github.com/xiweicheng/ai-helper/issues"
   }
 }

package/src/auth.js

@@ -6,6 +6,12 @@ import { loadConfig, loadPairings, savePairing } from './config.js';
 let currentPairCode = null;
 let pairCodeTimer = null;
 
+// 最后一次成功认证的时间戳（用于判断是否有活跃连接）
+let lastAuthTime = 0;
+
+// 判定"活跃"的时间窗口：此时间内有过认证则认为仍有扩展连接
+const ACTIVE_WINDOW_MS = 5 * 60 * 1000; // 5 分钟
+
 /**
  * 生成随机配对码（4位数字，使用密码学安全的随机数）
  */
@@ -22,9 +28,28 @@ function getCurrentPairCode() {
 
 /**
  * 启动配对码定时刷新
+ * - 如果有配对记录且最近有活跃认证（5分钟内），跳过刷新
+ * - 否则启动定时刷新，允许新扩展配对
  */
 function startPairCodeRotation() {
   const config = loadConfig();
+  const pairings = loadPairings();
+  const hasPairings = Object.keys(pairings).length > 0;
+  const isRecentlyActive = (Date.now() - lastAuthTime) < ACTIVE_WINDOW_MS;
+
+  // 有配对且最近有活跃连接，无需刷新配对码
+  if (hasPairings && isRecentlyActive) {
+    console.log(`[Agent] 已有 ${Object.keys(pairings).length} 个配对扩展，最近 ${Math.round((Date.now() - lastAuthTime) / 1000)}s 前有认证活动，跳过配对码刷新`);
+    currentPairCode = generatePairCode();
+    console.log(`[Agent] 当前配对码（用于新增配对）: ${currentPairCode}`);
+    return;
+  }
+
+  // 有配对但无活跃连接，给出提示
+  if (hasPairings && !isRecentlyActive) {
+    console.log(`[Agent] 存在配对记录但无活跃连接（超过 ${ACTIVE_WINDOW_MS / 60000} 分钟），恢复配对码刷新`);
+  }
+
   const ttl = (config.pairCodeTTL || 30) * 1000;
 
   currentPairCode = generatePairCode();
@@ -55,6 +80,7 @@ function verifyToken(token) {
   const pairings = loadPairings();
   for (const [extId, pairing] of Object.entries(pairings)) {
     if (pairing.token === token) {
+      lastAuthTime = Date.now();
       return extId;
     }
   }

package/src/config.js

@@ -6,6 +6,8 @@ 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 SKILLS_DIR = join(AGENT_DIR, 'skills');
+const WORKSPACE_DIR = join(AGENT_DIR, 'workspace');
 
 const DEFAULTS = {
   port: 18910,
@@ -37,13 +39,20 @@ function withWriteLock(fn) {
 }
 
 function ensureAgentDir() {
-  if (!existsSync(AGENT_DIR)) {
-    try {
+  try {
+    // 确保 Agent 根目录存在
+    if (!existsSync(AGENT_DIR)) {
       mkdirSync(AGENT_DIR, { recursive: true });
-    } catch (err) {
-      console.error('[Config] 无法创建 Agent 目录:', err.message);
-      throw err;
     }
+    // 确保 skills 和 workspace 子目录存在
+    for (const dir of [SKILLS_DIR, WORKSPACE_DIR]) {
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+    }
+  } catch (err) {
+    console.error('[Config] 无法创建 Agent 目录:', err.message);
+    throw err;
   }
 }
 
@@ -82,13 +91,18 @@ export function loadConfig() {
     const userConfig = JSON.parse(raw);
     configCache = { ...DEFAULTS, ...userConfig };
     configCacheMtime = mtime;
-    return configCache;
   } catch (err) {
     console.error('[Config] 配置文件解析失败:', err.message);
     configCache = { ...DEFAULTS, allowedPaths: [DEFAULTS.workdir] };
     configCacheMtime = 0;
-    return configCache;
   }
+
+  // 自动将 skills 目录加入白名单，确保 AI 可以直接写入 skill 文件
+  if (!configCache.allowedPaths.includes(SKILLS_DIR)) {
+    configCache.allowedPaths.push(SKILLS_DIR);
+  }
+
+  return configCache;
 }
 
 /**

package/src/mcp/client.js

@@ -0,0 +1,244 @@
+// mcp/client.js - MCP Client 核心
+// 管理与单个 MCP Server 的 JSON-RPC 2.0 通信
+import { createStdioTransport } from './transport.js';
+
+let requestIdCounter = 0;
+
+/**
+ * MCP Client 类
+ * 管理与一个 MCP Server 的完整生命周期
+ */
+export class McpClient {
+  constructor(serverConfig) {
+    this.serverId = serverConfig.id;
+    this.serverName = serverConfig.name || serverConfig.id;
+    this.serverConfig = serverConfig;
+    this.transport = null;
+    this.connected = false;
+    this.tools = [];
+    this.serverInfo = null;
+
+    // JSON-RPC 请求管理
+    this.pendingRequests = new Map(); // id → { resolve, reject, timeoutId }
+  }
+
+  /**
+   * 连接到 MCP Server
+   * 流程: 启动子进程 → initialize → tools/list
+   */
+  async connect() {
+    if (this.connected) return { success: true };
+
+    try {
+      // 1. 创建 stdio 传输
+      this.transport = await createStdioTransport(this.serverConfig);
+
+      // 2. 设置响应数据处理器
+      this.transport.onData((line) => this._handleLine(line));
+
+      // 2.5 监听进程崩溃（已连接后）
+      this.transport.onExit((code, signal) => {
+        console.error(`[MCP:${this.serverId}] Server 进程意外退出 (code=${code}, signal=${signal})，标记为断开`);
+        this.connected = false;
+        this.tools = [];
+        // 拒绝所有进行中的请求
+        for (const [id, pending] of this.pendingRequests) {
+          clearTimeout(pending.timeoutId);
+          pending.reject(new Error('MCP Server 进程已退出'));
+        }
+        this.pendingRequests.clear();
+      });
+
+      console.log(`[MCP:${this.serverId}] 子进程已启动`);
+
+      // 3. 发送 initialize 请求
+      const initResult = await this._sendRequest('initialize', {
+        protocolVersion: '2024-11-05',
+        capabilities: {
+          tools: {}
+        },
+        clientInfo: {
+          name: 'ai-helper-agent',
+          version: '1.3.4'
+        }
+      });
+
+      if (!initResult || initResult.error) {
+        throw new Error(`Initialize 失败: ${initResult?.error?.message || '未知错误'}`);
+      }
+
+      this.serverInfo = initResult;
+      console.log(`[MCP:${this.serverId}] Initialize 成功, server:`, initResult.serverInfo?.name);
+
+      // 4. 发送 initialized 通知（MCP 协议要求）
+      this._sendNotification('notifications/initialized', {});
+
+      // 5. 发现工具
+      const toolsResult = await this._sendRequest('tools/list', {});
+      if (toolsResult && toolsResult.tools) {
+        this.tools = toolsResult.tools;
+        console.log(`[MCP:${this.serverId}] 发现 ${this.tools.length} 个工具:`,
+          this.tools.map(t => t.name).join(', '));
+      } else {
+        this.tools = [];
+      }
+
+      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 };
+    }
+  }
+
+  /**
+   * 调用 MCP 工具
+   * @param {string} toolName
+   * @param {Object} args
+   */
+  async callTool(toolName, args) {
+    if (!this.connected) {
+      return { success: false, error: `MCP Server "${this.serverName}" 未连接` };
+    }
+
+    try {
+      const result = await this._sendRequest('tools/call', {
+        name: toolName,
+        arguments: args || {}
+      });
+
+      if (result && result.error) {
+        return { success: false, error: result.error.message || '工具调用失败' };
+      }
+
+      // MCP tools/call 返回 { content: [{ type: 'text', text: '...' }], isError: false }
+      const content = result?.content || [];
+      const textContent = content
+        .filter(c => c.type === 'text')
+        .map(c => c.text)
+        .join('\n');
+
+      return {
+        success: !result?.isError,
+        content: textContent,
+        raw: result
+      };
+    } catch (err) {
+      return { success: false, error: `工具调用异常: ${err.message}` };
+    }
+  }
+
+  /**
+   * 断开连接
+   */
+  disconnect() {
+    this.connected = false;
+    this.tools = [];
+
+    // 清理所有未完成的请求
+    for (const [id, pending] of this.pendingRequests) {
+      clearTimeout(pending.timeoutId);
+      pending.reject(new Error('连接已断开'));
+    }
+    this.pendingRequests.clear();
+
+    if (this.transport) {
+      try { this.transport.close(); } catch {}
+      this.transport = null;
+    }
+
+    console.log(`[MCP:${this.serverId}] 已断开连接`);
+  }
+
+  /**
+   * 获取状态信息
+   */
+  getStatus() {
+    return {
+      id: this.serverId,
+      name: this.serverName,
+      connected: this.connected,
+      toolCount: this.tools.length,
+      serverInfo: this.serverInfo?.serverInfo || null
+    };
+  }
+
+  // ========== 私有方法 ==========
+
+  /**
+   * 处理从 transport 收到的每一行 JSON-RPC 消息
+   */
+  _handleLine(line) {
+    try {
+      const message = JSON.parse(line);
+      const id = message.id;
+
+      if (id !== undefined && id !== null) {
+        // 有 id = 响应
+        const pending = this.pendingRequests.get(id);
+        if (pending) {
+          clearTimeout(pending.timeoutId);
+          this.pendingRequests.delete(id);
+
+          if (message.error) {
+            pending.reject(new Error(message.error.message || 'JSON-RPC Error'));
+          } else {
+            pending.resolve(message.result);
+          }
+        }
+      } else {
+        // 无 id = 通知，仅记录
+        if (message.method) {
+          console.log(`[MCP:${this.serverId}] 通知:`, message.method);
+        }
+      }
+    } catch (err) {
+      // 非 JSON 行，忽略
+    }
+  }
+
+  /**
+   * 发送 JSON-RPC 请求并等待响应
+   */
+  _sendRequest(method, params) {
+    return new Promise((resolve, reject) => {
+      const id = ++requestIdCounter;
+
+      const timeoutId = setTimeout(() => {
+        this.pendingRequests.delete(id);
+        reject(new Error(`MCP 请求超时 (60s): ${method}`));
+      }, 60000);
+
+      this.pendingRequests.set(id, { resolve, reject, timeoutId });
+
+      try {
+        this.transport.send({
+          jsonrpc: '2.0',
+          id,
+          method,
+          params
+        });
+      } catch (err) {
+        clearTimeout(timeoutId);
+        this.pendingRequests.delete(id);
+        reject(err);
+      }
+    });
+  }
+
+  /**
+   * 发送 JSON-RPC 通知（无需响应）
+   */
+  _sendNotification(method, params) {
+    try {
+      this.transport.send({
+        jsonrpc: '2.0',
+        method,
+        params
+      });
+    } catch {
+      // 通知发送失败不抛出
+    }
+  }
+}

package/src/mcp/mcp-config.js

@@ -0,0 +1,124 @@
+// mcp/mcp-config.js - MCP Server 配置管理
+// 复用 agent/config.js 的缓存 + 写锁模式
+import { readFileSync, writeFileSync, existsSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const AGENT_DIR = join(homedir(), '.ai-helper-agent');
+const MCP_CONFIG_FILE = join(AGENT_DIR, 'mcp_servers.json');
+
+// 内存缓存
+let configCache = null;
+let configCacheMtime = 0;
+
+// 写入互斥锁
+let writeLock = Promise.resolve();
+
+function withWriteLock(fn) {
+  const prev = writeLock;
+  let release;
+  writeLock = new Promise(resolve => { release = resolve; });
+  return prev.then(() => fn().finally(release));
+}
+
+function getMtime(filePath) {
+  try { return statSync(filePath).mtimeMs; }
+  catch { return 0; }
+}
+
+/**
+ * 加载 MCP Server 配置（带缓存）
+ * @returns {{ servers: Array }}
+ */
+export function loadMcpConfig() {
+  const mtime = getMtime(MCP_CONFIG_FILE);
+
+  if (configCache && mtime === configCacheMtime) {
+    return configCache;
+  }
+
+  if (!existsSync(MCP_CONFIG_FILE)) {
+    const defaults = { servers: [] };
+    try { writeFileSync(MCP_CONFIG_FILE, JSON.stringify(defaults, null, 2), 'utf-8'); } catch {}
+    configCache = defaults;
+    configCacheMtime = getMtime(MCP_CONFIG_FILE);
+    return defaults;
+  }
+
+  try {
+    const raw = readFileSync(MCP_CONFIG_FILE, 'utf-8');
+    configCache = JSON.parse(raw);
+    if (!configCache.servers) configCache.servers = [];
+    configCacheMtime = mtime;
+    return configCache;
+  } catch (err) {
+    console.error('[MCP Config] 配置文件解析失败:', err.message);
+    configCache = { servers: [] };
+    configCacheMtime = 0;
+    return configCache;
+  }
+}
+
+/**
+ * 保存 MCP Server 配置
+ */
+export async function saveMcpConfig(config) {
+  return withWriteLock(async () => {
+    try {
+      writeFileSync(MCP_CONFIG_FILE, JSON.stringify(config, null, 2), 'utf-8');
+      configCache = JSON.parse(JSON.stringify(config)); // 深拷贝
+      configCacheMtime = getMtime(MCP_CONFIG_FILE);
+    } catch (err) {
+      console.error('[MCP Config] 保存配置失败:', err.message);
+      throw err;
+    }
+  });
+}
+
+/**
+ * 添加或更新 MCP Server
+ * @param {Object} server - { id, name, command, args, env, enabled }
+ */
+export async function addMcpServer(server) {
+  const config = loadMcpConfig();
+  const existingIdx = config.servers.findIndex(s => s.id === server.id);
+
+  if (existingIdx >= 0) {
+    config.servers[existingIdx] = { ...config.servers[existingIdx], ...server };
+  } else {
+    config.servers.push(server);
+  }
+
+  await saveMcpConfig(config);
+  return { success: true };
+}
+
+/**
+ * 删除 MCP Server
+ */
+export async function removeMcpServer(serverId) {
+  const config = loadMcpConfig();
+  const idx = config.servers.findIndex(s => s.id === serverId);
+  if (idx < 0) {
+    return { success: false, error: `MCP Server "${serverId}" 不存在` };
+  }
+  config.servers.splice(idx, 1);
+  await saveMcpConfig(config);
+  return { success: true };
+}
+
+/**
+ * 更新 MCP Server 的启用状态
+ */
+export async function toggleMcpServer(serverId, enabled) {
+  const config = loadMcpConfig();
+  const server = config.servers.find(s => s.id === serverId);
+  if (!server) {
+    return { success: false, error: `MCP Server "${serverId}" 不存在` };
+  }
+  server.enabled = enabled;
+  await saveMcpConfig(config);
+  return { success: true };
+}
+
+export { MCP_CONFIG_FILE };