foliko 1.0.8 → 1.0.10

package/skills/vb-agent-dev/SKILL.md

@@ -18,14 +18,26 @@ VB-Agent 是一个基于插件的 Agent 框架，核心简单，通过插件扩
 
 用户自定义插件放在项目根目录的 `.agent/plugins/` 下，**自动加载**，无需手动注册。
 
+**推荐使用文件夹结构**（适合复杂插件）：
+
 ```
 项目目录/
 └── .agent/
     └── plugins/
-        ├── my-plugin.js      ✅ 正确
-        └── another-plugin.js ✅ 正确
+        ├── my-plugin/              ✅ 文件夹结构（推荐）
+        │   ├── package.json        # 可选，main 字段指定入口
+        │   ├── index.js            # 默认入口
+        │   └── node_modules/       # 可选，插件私有依赖
+        ├── another-plugin/         ✅ 另一个文件夹插件
+        │   └── index.js
+        └── legacy.js               ✅ 单文件仍支持
 ```
 
+**文件夹结构的优势：**
+- 支持 `package.json` 的 `main` 字段自定义入口
+- 支持 `node_modules` 存放插件私有依赖
+- 更适合复杂插件的代码组织
+
 ### `plugins/` 目录（内置插件）
 
 框架内置插件位于 `plugins/` 目录。
@@ -36,6 +48,69 @@ VB-Agent 是一个基于插件的 Agent 框架，核心简单，通过插件扩
 
 **必须使用免引入写法**：
 
+### 文件夹结构（推荐）
+
+```
+.agent/plugins/my-plugin/
+├── package.json      # 可选
+└── index.js          # 入口
+```
+
+```json
+// package.json 示例
+{
+  "name": "my-plugin",
+  "main": "index.js"
+}
+```
+
+```javascript
+// .agent/plugins/my-plugin/index.js
+module.exports = function(Plugin) {
+  return class MyPlugin extends Plugin {
+    constructor(config = {}) {
+      super()
+      this.name = 'my-plugin'
+      this.version = '1.0.0'
+      this.description = '我的工具插件'
+      this.priority = 10
+    }
+
+    install(framework) {
+      const { z } = require('zod')
+      framework.registerTool({
+        name: 'my_tool',
+        description: '我的工具',
+        inputSchema: z.object({
+          param: z.string().describe('参数描述')
+        }),
+        execute: async (args, framework) => {
+          return { success: true, result: args.param }
+        }
+      })
+      return this
+    }
+
+    uninstall(framework) {
+      // 清理资源
+    }
+  }
+}
+```
+
+### 单文件结构（仍支持）
+
+```javascript
+// .agent/plugins/my-plugin.js
+module.exports = function(Plugin) {
+  return class MyPlugin extends Plugin {
+    // ... 与上面相同
+  }
+}
+```
+
+**注意**：如果文件夹和同名 `.js` 文件同时存在，**文件夹优先**。
+
 ```javascript
 // .agent/plugins/my-plugin.js
 module.exports = function(Plugin) {
@@ -70,8 +145,10 @@ module.exports = function(Plugin) {
 }
 ```
 **插件开发流程：**
-1. **创建插件文件**（暂不加载）
-2. **安装依赖**：`install { package: "包名" }`
+1. **创建插件**（优先使用文件夹结构）
+2. **安装依赖**：
+   - 文件夹插件：`install { package: "包名", path: ".agent/plugins/插件名" }`
+   - 单文件插件：`install { package: "包名" }`
 3. **热重载**：`reload_plugins`
 4. **检查加载状态**
 
@@ -85,27 +162,69 @@ module.exports = function(Plugin) {
 
 ## 依赖管理
 
-当插件需要使用第三方 npm 包（如 `zod`、`axios` 等）时，必须自动安装到 `.agent/node_modules`：
+当插件需要使用第三方 npm 包（如 `zod`、`axios` 等）时，根据插件类型选择安装位置：
+
+| 插件类型 | 安装位置 | 说明 |
+|----------|----------|------|
+| **文件夹插件** | `.agent/plugins/插件名/node_modules/` | 插件自包含，可独立迁移 |
+| **单文件插件** | `.agent/node_modules/` | 共享依赖 |
 
 ### 自动安装工具
 
-框架提供了 `install` 工具，可以自动安装 npm 包：
+框架提供了 `install` 工具，支持以下用法：
 
 ```javascript
-// 在 execute 中调用 install 工具
-execute: async (args, framework) => {
-  // 安装缺失的包
-  const installResult = await framework.callTool('install', {
-    package: 'zod'  // 或 'zod@4.3.6' 指定版本
-  })
+// 安装到默认位置 .agent/node_modules
+install({ package: "zod" })
 
-  if (!installResult.success) {
-    return { success: false, error: installResult.error }
-  }
+// 安装到指定目录（用于文件夹插件）
+install({ package: "axios", path: ".agent/plugins/my-plugin" })
 
-  // 安装成功后可以正常 require
-  const { z } = require('zod')
-  // ... 继续执行
+// 从 package.json 安装所有依赖到默认位置
+install({ file: "./package.json" })
+
+// 从 package.json 安装所有依赖到指定目录
+install({ file: "./my-plugin/package.json", path: ".agent/plugins/my-plugin" })
+
+// 仅指定路径，安装该目录下的 package.json 依赖
+install({ path: ".agent/plugins/my-plugin" })
+```
+
+### 文件夹插件的依赖安装示例
+
+```javascript
+// .agent/plugins/my-plugin/index.js
+module.exports = function(Plugin) {
+  return class MyPlugin extends Plugin {
+    constructor(config = {}) {
+      super()
+      this.name = 'my-plugin'
+    }
+
+    install(framework) {
+      framework.registerTool({
+        name: 'fetch_data',
+        description: '获取远程数据',
+        inputSchema: z.object({
+          url: z.string().describe('API URL')
+        }),
+        execute: async (args, framework) => {
+          // 安装到插件自己的目录
+          const pluginDir = '.agent/plugins/my-plugin'
+          await framework.callTool('install', {
+            package: 'axios',
+            path: pluginDir
+          })
+
+          // 引入插件目录下的 node_modules
+          const axios = require(`${pluginDir}/node_modules/axios`)
+          const response = await axios.get(args.url)
+          return { success: true, data: response.data }
+        }
+      })
+      return this
+    }
+  }
 }
 ```
 
@@ -113,15 +232,18 @@ execute: async (args, framework) => {
 
 当 LLM 检测到 `Cannot find module 'xxx'` 错误时，必须：
 
-1. **立即调用 `install` 工具** 安装缺失的包
-2. **安装完成后** 重新加载插件
-3. **返回状态** 给用户
+1. **确定插件目录**：如果插件是文件夹结构，安装到插件目录
+2. **调用 `install` 工具** 安装缺失的包
+3. **安装完成后** 重新加载插件
+4. **返回状态** 给用户
 
-示例流程：
+示例流程（文件夹插件）：
 ```
 错误: Cannot find module 'axios'
 ↓
-自动安装: install { package: "axios" }
+确定插件目录: .agent/plugins/my-plugin
+↓
+自动安装: install { package: "axios", path: ".agent/plugins/my-plugin" }
 ↓
 重新加载插件
 ↓
@@ -130,7 +252,8 @@ execute: async (args, framework) => {
 
 ### 重要提醒
 
-- **不要尝试手动 require 全局安装的包** - 必须在 `.agent/node_modules` 中安装
+- **文件夹插件优先安装到插件目录** - 使用 `path` 参数指定插件目录
+- **不要尝试手动 require 全局安装的包** - 必须在指定目录中安装
 - **使用 `install` 工具自动处理** - 让 LLM 知道如何处理缺失依赖
 - **插件加载失败时检查依赖** - 优先安装缺失的包再重试
 
@@ -223,10 +346,11 @@ install(framework) {
 
 | 规则 | 说明 |
 |------|------|
-| **禁止创建目录！** | **必须是单个 `.js` 文件！** |
+| **优先使用文件夹结构** | 复杂插件推荐用文件夹，便于管理依赖和代码 |
 | **必须用 inputSchema** | `inputSchema: z.object({})`（不是 parameters!） |
 | **必须用 zod 定义参数** | `param: z.string().describe('描述')` |
 | **install 必须返回 this** | 确保链式调用 |
+| **文件夹与文件重名时** | 文件夹优先，同名 `.js` 文件会被忽略 |
 
 ## 开发完成后注意事项
 

package/src/core/plugin-manager.js

@@ -257,28 +257,108 @@ class PluginManager {
     await this.startAll()
   }
 
+  /**
+   * 解析插件路径
+   * 支持两种结构：
+   * 1. 文件夹结构: .agent/plugins/my-plugin/index.js
+   * 2. 单文件结构: .agent/plugins/my-plugin.js
+   * @param {string} pluginsDir - 插件目录
+   * @param {string} name - 插件名称
+   * @returns {{path: string, type: 'folder'|'file'}|null} 插件路径和类型
+   * @private
+   */
+  _resolvePluginPath(pluginsDir, name) {
+    const folderPath = path.join(pluginsDir, name)
+    const filePath = path.join(pluginsDir, `${name}.js`)
+
+    // 文件夹优先
+    if (fs.existsSync(folderPath) && fs.statSync(folderPath).isDirectory()) {
+      const pkgPath = path.join(folderPath, 'package.json')
+      if (fs.existsSync(pkgPath)) {
+        try {
+          const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'))
+          const main = pkg.main || 'index.js'
+          const mainPath = path.join(folderPath, main)
+          if (fs.existsSync(mainPath)) {
+            return { path: mainPath, type: 'folder' }
+          }
+        } catch (err) {
+          console.warn(`[_resolvePluginPath] Failed to parse package.json for ${name}:`, err.message)
+        }
+      }
+      // 默认加载 index.js
+      const indexPath = path.join(folderPath, 'index.js')
+      if (fs.existsSync(indexPath)) {
+        return { path: indexPath, type: 'folder' }
+      }
+      console.warn(`[_resolvePluginPath] No entry point found for plugin folder: ${name}`)
+      return null
+    }
+
+    // 单文件回退
+    if (fs.existsSync(filePath)) {
+      return { path: filePath, type: 'file' }
+    }
+
+    return null
+  }
+
+  /**
+   * 扫描插件目录，返回所有插件名称
+   * @param {string} pluginsDir - 插件目录
+   * @returns {string[]} 插件名称列表
+   * @private
+   */
+  _scanPluginNames(pluginsDir) {
+    if (!fs.existsSync(pluginsDir)) {
+      return []
+    }
+
+    const names = new Set()
+    const entries = fs.readdirSync(pluginsDir, { withFileTypes: true })
+
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        // 文件夹插件
+        names.add(entry.name)
+      } else if (entry.isFile() && entry.name.endsWith('.js')) {
+        // 单文件插件（排除与文件夹同名的）
+        const baseName = entry.name.replace(/\.js$/, '')
+        if (!names.has(baseName)) {
+          names.add(baseName)
+        }
+      }
+    }
+
+    return Array.from(names)
+  }
+
   /**
    * 发现并加载自定义插件
    * @private
    */
   async _discoverCustomPlugins() {
-    const fs = require('fs')
-    const path = require('path')
-
     const pluginsDir = path.resolve(process.cwd(), '.agent', 'plugins')
     if (!fs.existsSync(pluginsDir)) {
       return
     }
 
-    const files = fs.readdirSync(pluginsDir).filter(f => f.endsWith('.js'))
+    // 扫描所有插件名称（支持文件夹和单文件）
+    const pluginNames = this._scanPluginNames(pluginsDir)
 
     // 从 pluginsDir 推导 agentDir（pluginsDir = <agentDir>/plugins）
     const agentDir = path.dirname(pluginsDir)
     const agentNodeModules = path.join(agentDir, 'node_modules')
 
-    for (const file of files) {
+    for (const pluginName of pluginNames) {
       try {
-        const pluginPath = path.join(pluginsDir, file)
+        const resolved = this._resolvePluginPath(pluginsDir, pluginName)
+        if (!resolved) {
+          console.warn(`[PluginManager] Cannot resolve plugin: ${pluginName}`)
+          continue
+        }
+
+        const { path: pluginPath, type } = resolved
 
         // 添加模块路径到搜索路径（优先级从高到低）
         const modulePathsToAdd = [
@@ -305,24 +385,24 @@ class PluginManager {
         }
 
         // 获取插件名称
-        let pluginName
+        let resolvedPluginName
         try {
           const tempPlugin = plugin.prototype instanceof require('./plugin-base')
             ? new plugin() : (typeof plugin === 'function' ? plugin() : plugin)
-          pluginName = tempPlugin.name || file.replace('.js', '')
+          resolvedPluginName = tempPlugin.name || pluginName
         } catch {
-          pluginName = file.replace('.js', '')
+          resolvedPluginName = pluginName
         }
 
         // 如果插件已加载且已启动，跳过
-        if (this.has(pluginName) && this.get(pluginName)?._started) {
+        if (this.has(resolvedPluginName) && this.get(resolvedPluginName)?._started) {
           continue
         }
 
-        console.log(`[PluginManager] Loading new plugin: ${file}`)
+        console.log(`[PluginManager] Loading new plugin: ${pluginName} (${type})`)
         await this.load(plugin)
       } catch (err) {
-        console.error(`[PluginManager] Failed to load plugin ${file}:`, err.message)
+        console.error(`[PluginManager] Failed to load plugin ${pluginName}:`, err.message)
       }
     }
   }
@@ -385,15 +465,21 @@ class PluginManager {
 
     entry.enabled = true
 
-    // 如果插件已加载但未启动，启动它
-    if (entry.status === 'loaded' && !entry.instance._started) {
+    // 如果插件已加载，尝试重新启动（reload 会调用 start）
+    if (entry.status === 'loaded') {
       try {
-        if (typeof entry.instance.start === 'function') {
-          await entry.instance.start(this.framework)
-          entry.instance._started = true
+        // 如果之前已经启动过，先调用 stop 停止旧实例
+        if (entry.instance._started) {
+          if (typeof entry.instance.stop === 'function') {
+            await entry.instance.stop()
+          } else if (typeof entry.instance.stopBot === 'function') {
+            await entry.instance.stopBot()
+          }
         }
+        // 调用 reload 让插件重新初始化（会调用 install 和 start）
+        await this.reload(name)
       } catch (err) {
-        console.error(`[PluginManager] Start failed for '${name}':`, err.message)
+        console.error(`[PluginManager] Enable/reload failed for '${name}':`, err.message)
       }
     }
 
@@ -428,9 +514,6 @@ class PluginManager {
         } else if (typeof entry.instance.stopBot === 'function') {
           await entry.instance.stopBot()
         }
-        if (typeof entry.instance.uninstall === 'function') {
-          await entry.instance.uninstall(this.framework)
-        }
         entry.instance._started = false
       } catch (err) {
         console.error(`[PluginManager] Stop failed for '${name}':`, err.message)