foliko 1.0.8 → 1.0.9

package/.claude/settings.local.json

@@ -30,7 +30,11 @@
       "Bash(cd D:/Code/vb-agent && timeout 8 node test-tg.js 2>&1 || true)",
       "Bash(cd D:/Code/vb-agent && timeout 10 node test-tg.js 2>&1 || true)",
       "Bash(find /d/Code/vb-agent -name \"*email*\" -type f 2>/dev/null | grep -v node_modules | grep -v .git)",
-      "Bash(find /d/Code/vb-agent -maxdepth 2 -name \"*.md\" -type f 2>/dev/null | grep -v node_modules)"
+      "Bash(find /d/Code/vb-agent -maxdepth 2 -name \"*.md\" -type f 2>/dev/null | grep -v node_modules)",
+      "Bash(node -c plugins/default-plugins.js && node -c src/core/plugin-manager.js && echo \"Syntax OK\")",
+      "Bash(node -c plugins/install-plugin.js && echo \"Syntax OK\")",
+      "Bash(node -c cli/src/ui/chat-ui.js && echo \"Syntax OK\")",
+      "Bash(node -c plugins/default-plugins.js && echo \"Syntax OK\")"
     ]
   }
 }

package/README.md

@@ -87,8 +87,27 @@ ai_provider: minimax
 
 ### 用户插件（.agent/plugins/）
 
+插件支持两种结构：**文件夹结构**（推荐）和**单文件结构**。
+
+#### 文件夹结构（推荐）
+
+```
+.agent/plugins/my-plugin/
+├── package.json      # 可选，main 字段指定入口
+├── index.js          # 默认入口
+└── node_modules/     # 可选，插件私有依赖
+```
+
+```json
+// package.json 示例
+{
+  "name": "my-plugin",
+  "main": "index.js"
+}
+```
+
 ```javascript
-// .agent/plugins/my-plugin.js
+// .agent/plugins/my-plugin/index.js
 module.exports = function(Plugin) {
   return class MyPlugin extends Plugin {
     constructor(config = {}) {
@@ -117,9 +136,17 @@ module.exports = function(Plugin) {
 }
 ```
 
+#### 单文件结构（兼容）
+
+```
+.agent/plugins/my-plugin.js
+```
+
+如果同时存在文件夹和同名 `.js` 文件，**文件夹优先**。
+
 **注意**：如果插件需要第三方库（如 `zod`），需要先安装：
 
-1. 创建插件文件
+1. 创建插件文件/文件夹
 2. 调用 `install` 工具安装依赖
 3. 热重载插件
 

package/cli/src/ui/chat-ui.js

@@ -22,6 +22,10 @@ class ChatUI extends EventEmitter {
     this.lastKeyTime = 0
     this.pasteBuffer = ''
     this.isPasting = false
+
+    // 多行输入：记录上次 Enter 时间，检测连续两次空回车
+    this.lastEnterTime = 0
+    this.LINE_ENDING_INTERVAL = 800  // 毫秒内连续两次空回车结束输入
   }
 
   /**
@@ -73,14 +77,14 @@ class ChatUI extends EventEmitter {
    */
   printWelcome() {
     console.log(`${colored('Foliko', CYAN)} - 持续对话聊天`)
-    console.log(`${colored('Ctrl+C', DIM)} 退出 | ${colored('Ctrl+Enter', DIM)} 换行 | ${colored('Enter', DIM)} 发送\n`)
+    console.log(`${colored('Ctrl+C', DIM)} 退出 | ${colored('Enter', DIM)} 换行 | ${colored('双Enter', DIM)} 发送\n`)
   }
 
   /**
    * 显示提示符
    */
   prompt() {
-    const prefix = this.isFirstLine ? colored('You: ', GREEN) : colored('> ', DIM)
+    const prefix = this.isFirstLine ? colored('> ', GREEN) : colored('- ', DIM)
     process.stdout.write(`\r${CLEAR_LINE}${prefix}${this.currentLine}`)
   }
 
@@ -157,12 +161,46 @@ class ChatUI extends EventEmitter {
    * 处理发送
    */
   async handleSubmit() {
+    const now = Date.now()
     const content = this.lines.length > 0
       ? [...this.lines, this.currentLine].join('\n')
       : this.currentLine
 
     const trimmed = content.trim()
 
+    // 检测连续两次空回车（多行输入结束）
+    if (this.currentLine.trim() === '' && this.lines.length > 0) {
+      if (now - this.lastEnterTime < this.LINE_ENDING_INTERVAL) {
+        // 第二次空回车，结束输入
+        const finalContent = this.lines.join('\n').trim()
+        this.resetInput()
+        console.log()
+
+        if (!finalContent) {
+          this.prompt()
+          return
+        }
+
+        await this.sendMessage(finalContent)
+        return
+      }
+    }
+    this.lastEnterTime = now
+
+    // 输入 !! 立即结束多行输入
+    if (this.currentLine.trim() === '!!') {
+      const finalContent = this.lines.join('\n').trim()
+      this.resetInput()
+      console.log()
+
+      if (finalContent) {
+        await this.sendMessage(finalContent)
+      } else {
+        this.prompt()
+      }
+      return
+    }
+
     // 显示空行
     console.log()
 
@@ -199,6 +237,7 @@ class ChatUI extends EventEmitter {
     this.pasteId = 0
     this.isPasting = false
     this.pasteBuffer = ''
+    this.lastEnterTime = 0
   }
 
   /**

package/examples/test-chat.js

@@ -52,7 +52,7 @@ async function main() {
       const lines = []
 
       const question = () => {
-        rl.question(lines.length === 0 ? 'You: ' : '> ', (input) => {
+        rl.question(lines.length === 0 ? '> ' : '- ', (input) => {
           // 输入 !! 立即结束
           if (input.trim() === '!!') {
             const result = lines.join('\n').trim()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "1.0.8",
+  "version": "1.0.9",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "bin": {

package/plugins/default-plugins.js

@@ -182,8 +182,29 @@ async function bootstrapDefaults(framework, config = {}) {
   // 合并 AI 配置
   const aiConfig = { ...agentConfig.ai, ...config.aiConfig }
 
+  // 核心插件列表（不能禁用，必须加载）
+  const CORE_PLUGINS = new Set([
+    'install', 'ai', 'storage', 'tools', 'workflow', 'skill-manager',
+    'mcp-executor', 'shell-executor', 'python-executor', 'session',
+    'audit', 'rules', 'scheduler', 'file-system', 'think',
+    'python-plugin-loader', 'telegram'
+  ])
+
+  // 辅助函数：检查插件是否应该加载（核心插件不能禁用）
+  const shouldLoad = (name) => {
+    if (framework.pluginManager.has(name)) {
+      console.log(`[Bootstrap] ${name} Plugin already loaded, skipping`)
+      return false
+    }
+    // 核心插件不能禁用
+    if (CORE_PLUGINS.has(name) && framework.pluginManager.isEnabled(name) === false) {
+      console.log(`[Bootstrap] ${name} is a core plugin, cannot be disabled`)
+    }
+    return true
+  }
+
   // 0. Install 工具插件（最先加载，让其他插件能用到它的 node_modules）
-  if (!framework.pluginManager.has('install')) {
+  if (shouldLoad('install')) {
     const { InstallPlugin } = require('./install-plugin')
     await framework.loadPlugin(new InstallPlugin({ agentDir: agentConfig.agentDir }))
     console.log('[Bootstrap] Install Plugin loaded')
@@ -197,10 +218,10 @@ async function bootstrapDefaults(framework, config = {}) {
 
   console.log('[Bootstrap] Loading default plugins...')
 
-  // 检查是否已经加载
-  if (framework.pluginManager.has('ai')) {
-    console.log('[Bootstrap] AI Plugin already loaded, skipping')
-  } else if (aiConfig.provider || aiConfig.model || aiConfig.apiKey) {
+  // AI 插件（如果已禁用则跳过）
+  if (!shouldLoad('ai') || !(aiConfig.provider || aiConfig.model || aiConfig.apiKey)) {
+    // 跳过或已禁用
+  } else {
     const { AIPlugin } = require('./ai-plugin')
     const aiPlugin = new AIPlugin({
       provider: aiConfig.provider || 'deepseek',
@@ -232,46 +253,38 @@ async function bootstrapDefaults(framework, config = {}) {
   }
 
   // 2. Storage 存储插件
-  if (!framework.pluginManager.has('storage')) {
+  if (shouldLoad('storage')) {
     const { StoragePlugin } = require('./storage-plugin')
     await framework.loadPlugin(new StoragePlugin())
     console.log('[Bootstrap] Storage Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Storage Plugin already loaded, skipping')
   }
 
   // 3. 内置工具插件
-  if (!framework.pluginManager.has('tools')) {
+  if (shouldLoad('tools')) {
     const { ToolsPlugin } = require('./tools-plugin')
     await framework.loadPlugin(new ToolsPlugin())
     console.log('[Bootstrap] Tools Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Tools Plugin already loaded, skipping')
   }
 
   // 4. 工作流插件
-  if (!framework.pluginManager.has('workflow')) {
+  if (shouldLoad('workflow')) {
     const { WorkflowPlugin } = require('../src/capabilities/workflow-engine')
     await framework.loadPlugin(new WorkflowPlugin())
     console.log('[Bootstrap] Workflow Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Workflow Plugin already loaded, skipping')
   }
 
   // 5. Skill 管理器插件
-  if (!framework.pluginManager.has('skill-manager')) {
+  if (shouldLoad('skill-manager')) {
     if (skillsDirs.length > 0) {
       const { SkillManagerPlugin } = require('../src/capabilities/skill-manager')
       // 传递所有 skills 目录
       await framework.loadPlugin(new SkillManagerPlugin({ skillsDirs }))
       console.log('[Bootstrap] Skill Manager loaded')
     }
-  } else {
-    console.log('[Bootstrap] Skill Manager already loaded, skipping')
   }
 
   // 6. MCP 执行器插件（始终加载，确保 mcp_reload 工具可用）
-  if (!framework.pluginManager.has('mcp-executor')) {
+  if (shouldLoad('mcp-executor')) {
     const mcpServers = Object.entries(agentConfig.mcpServers || {})
     const servers = mcpServers.map(([name, cfg]) => ({
       ...cfg,
@@ -285,93 +298,73 @@ async function bootstrapDefaults(framework, config = {}) {
     const { MCPExecutorPlugin } = require('../src/executors/mcp-executor')
     await framework.loadPlugin(new MCPExecutorPlugin({ servers }))
     console.log(`[Bootstrap] MCP Executor loaded${servers.length > 0 ? ` (${servers.length} servers)` : ' (no servers)'}`)
-  } else {
-    console.log('[Bootstrap] MCP Executor already loaded, skipping')
   }
 
   // 7. Shell 执行器插件
-  if (!framework.pluginManager.has('shell-executor')) {
+  if (shouldLoad('shell-executor')) {
     const { ShellExecutorPlugin } = require('./shell-executor-plugin')
     await framework.loadPlugin(new ShellExecutorPlugin())
     console.log('[Bootstrap] Shell Executor loaded')
-  } else {
-    console.log('[Bootstrap] Shell Executor already loaded, skipping')
   }
 
   // 8. Python 执行器插件
-  if (!framework.pluginManager.has('python-executor')) {
+  if (shouldLoad('python-executor')) {
     const { PythonExecutorPlugin } = require('./python-executor-plugin')
     await framework.loadPlugin(new PythonExecutorPlugin())
     console.log('[Bootstrap] Python Executor loaded')
-  } else {
-    console.log('[Bootstrap] Python Executor already loaded, skipping')
   }
 
   // 9. Session 会话管理插件
-  if (!framework.pluginManager.has('session')) {
+  if (shouldLoad('session')) {
     const { SessionPlugin } = require('./session-plugin')
     await framework.loadPlugin(new SessionPlugin())
     console.log('[Bootstrap] Session Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Session Plugin already loaded, skipping')
   }
 
   // 10. Audit 审计日志插件
-  if (!framework.pluginManager.has('audit')) {
+  if (shouldLoad('audit')) {
     const { AuditPlugin } = require('./audit-plugin')
     await framework.loadPlugin(new AuditPlugin())
     console.log('[Bootstrap] Audit Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Audit Plugin already loaded, skipping')
   }
 
   // 10. Rules 规则引擎插件
-  if (!framework.pluginManager.has('rules')) {
+  if (shouldLoad('rules')) {
     const { RulesPlugin } = require('./rules-plugin')
     await framework.loadPlugin(new RulesPlugin())
     console.log('[Bootstrap] Rules Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Rules Plugin already loaded, skipping')
   }
 
   // 11. Scheduler 定时任务插件
-  if (!framework.pluginManager.has('scheduler')) {
+  if (shouldLoad('scheduler')) {
     const { SchedulerPlugin } = require('./scheduler-plugin')
     await framework.loadPlugin(new SchedulerPlugin())
     console.log('[Bootstrap] Scheduler Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Scheduler Plugin already loaded, skipping')
   }
 
   // 11. FileSystem 文件系统插件
-  if (!framework.pluginManager.has('file-system')) {
+  if (shouldLoad('file-system')) {
     const { FileSystemPlugin } = require('./file-system-plugin')
     await framework.loadPlugin(new FileSystemPlugin())
     console.log('[Bootstrap] FileSystem Plugin loaded')
-  } else {
-    console.log('[Bootstrap] FileSystem Plugin already loaded, skipping')
   }
 
   // 12. Think 主动思考插件
-  if (!framework.pluginManager.has('think')) {
+  if (shouldLoad('think')) {
     const { ThinkPlugin } = require('./think-plugin')
     await framework.loadPlugin(new ThinkPlugin())
     console.log('[Bootstrap] Think Plugin loaded')
-  } else {
-    console.log('[Bootstrap] Think Plugin already loaded, skipping')
   }
 
   // 12.5 Python 插件加载器
-  if (!framework.pluginManager.has('python-plugin-loader')) {
+  if (shouldLoad('python-plugin-loader')) {
     const { PythonPluginLoader } = require('./python-plugin-loader')
     await framework.loadPlugin(new PythonPluginLoader({ agentDir: agentConfig.agentDir }))
     console.log('[Bootstrap] Python Plugin Loader loaded')
-  } else {
-    console.log('[Bootstrap] Python Plugin Loader already loaded, skipping')
   }
 
   // 12.6 Telegram 插件（如果配置了Token）
-  if (!framework.pluginManager.has('telegram')) {
+  if (shouldLoad('telegram')) {
     const telegramToken = process.env.TELEGRAM_BOT_TOKEN || agentConfig.telegram?.botToken
     if (telegramToken) {
       const { Plugin } = require('../src/core/plugin-base')
@@ -380,8 +373,6 @@ async function bootstrapDefaults(framework, config = {}) {
       await framework.loadPlugin(new TelegramPlugin({ botToken: telegramToken }))
       console.log('[Bootstrap] Telegram Plugin loaded')
     }
-  } else {
-    console.log('[Bootstrap] Telegram Plugin already loaded, skipping')
   }
 
   // 13. 加载自定义插件
@@ -399,6 +390,80 @@ async function bootstrapDefaults(framework, config = {}) {
   console.log('[Bootstrap] Tools:', framework.getTools().map(t => t.name))
 }
 
+/**
+ * 解析插件路径
+ * 支持两种结构：
+ * 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} 插件路径和类型
+ */
+function 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[]} 插件名称列表
+ */
+function 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)
+}
+
 async function loadCustomPlugins(framework, agentConfig) {
   // 加载 .agent/plugins 目录下的自定义插件
   const pluginsDir = path.resolve(process.cwd(), '.agent', 'plugins')
@@ -407,11 +472,18 @@ async function loadCustomPlugins(framework, agentConfig) {
     return
   }
 
-  const files = fs.readdirSync(pluginsDir).filter(f => f.endsWith('.js'))
+  // 扫描所有插件名称（支持文件夹和单文件）
+  const pluginNames = scanPluginNames(pluginsDir)
 
-  for (const file of files) {
+  for (const pluginName of pluginNames) {
     try {
-      const pluginPath = path.join(pluginsDir, file)
+      const resolved = resolvePluginPath(pluginsDir, pluginName)
+      if (!resolved) {
+        console.warn(`[Bootstrap] Cannot resolve plugin: ${pluginName}`)
+        continue
+      }
+
+      const { path: pluginPath, type } = resolved
 
       // 清除缓存
       delete require.cache[require.resolve(pluginPath)]
@@ -430,18 +502,24 @@ async function loadCustomPlugins(framework, agentConfig) {
       // 获取插件名称
       const tempPlugin = typeof plugin === 'function' && plugin.prototype?.name
         ? new plugin() : plugin
-      const pluginName = tempPlugin.name || file.replace('.js', '')
+      const resolvedPluginName = tempPlugin.name || pluginName
 
       // 如果插件已加载且已启动，跳过
-      if (framework.pluginManager.has(pluginName) &&
-          framework.pluginManager.get(pluginName)?._started) {
+      if (framework.pluginManager.has(resolvedPluginName) &&
+          framework.pluginManager.get(resolvedPluginName)?._started) {
+        continue
+      }
+
+      // 如果插件被禁用（在 state 文件中 enabled: false），跳过
+      if (framework.pluginManager.isEnabled(resolvedPluginName) === false) {
+        console.log(`[Bootstrap] Custom plugin '${resolvedPluginName}' is disabled, skipping`)
         continue
       }
 
-      console.log(`[Bootstrap] Loading custom plugin: ${file}`)
+      console.log(`[Bootstrap] Loading custom plugin: ${pluginName} (${type})`)
       await framework.loadPlugin(plugin)
     } catch (err) {
-      console.error(`[Bootstrap] Failed to load plugin ${file}:`, err.message)
+      console.error(`[Bootstrap] Failed to load plugin ${pluginName}:`, err.message)
     }
   }
 }
@@ -450,5 +528,7 @@ module.exports = {
   DefaultPlugins,
   loadAgentConfig,
   bootstrapDefaults,
-  loadCustomPlugins
+  loadCustomPlugins,
+  resolvePluginPath,
+  scanPluginNames
 }

package/plugins/install-plugin.js

@@ -1,6 +1,6 @@
 /**
  * InstallPlugin - npm 包安装工具
- * 自动安装缺少的 node 模块到 .agent 目录
+ * 自动安装缺少的 node 模块到 .agent 目录或指定目录
  */
 
 const { execSync } = require('child_process')
@@ -14,7 +14,7 @@ class InstallPlugin extends Plugin {
     super()
     this.name = 'install'
     this.version = '1.0.0'
-    this.description = '自动安装 npm 包到 .agent 目录'
+    this.description = '自动安装 npm 包到指定目录'
 
     this._agentDir = config.agentDir || '.agent'
     this._nodeModulesDir = null
@@ -35,35 +35,73 @@ class InstallPlugin extends Plugin {
     // 注册 install 工具
     framework.registerTool({
       name: 'install',
-      description: '安装 npm 包到 .agent 目录，用于解决插件依赖缺失问题',
+      description: '安装 npm 包到指定目录',
       inputSchema: z.object({
-        package: z.string().describe('包名，如 lodash 或 lodash@4.17.21')
+        package: z.string().optional().describe('包名，如 lodash、lodash@4.17.21 或 @scope/package'),
+        path: z.string().optional().describe('安装目标目录，如 .agent/plugins/my-plugin（默认为 .agent）'),
+        file: z.string().optional().describe('本地 package.json 路径，从该文件安装所有依赖')
       }),
       execute: async (args) => {
-        const { package: packageName } = args
-        return this._installPackage(packageName)
+        const { package: packageName, path: targetPath, file: packageJsonPath } = args
+
+        // 优先处理 file 参数（从 package.json 安装）
+        if (packageJsonPath) {
+          const resolvedPath = path.resolve(process.cwd(), packageJsonPath)
+          return this._installFromPackageJson(resolvedPath, targetPath)
+        }
+
+        // package 和 path 都提供
+        if (packageName) {
+          return this._installPackage(packageName, targetPath)
+        }
+
+        // 只有 path，安装该目录的 package.json
+        if (targetPath) {
+          const resolvedPath = path.resolve(process.cwd(), targetPath)
+          const pkgJson = path.join(resolvedPath, 'package.json')
+          if (fs.existsSync(pkgJson)) {
+            return this._installFromPackageJson(pkgJson, targetPath)
+          }
+          return { success: false, error: `package.json not found at ${pkgJson}` }
+        }
+
+        // 什么都不提供，报错
+        return { success: false, error: 'Must provide package name or package.json path' }
       }
     })
 
     return this
   }
 
-  _installPackage(packageName) {
+  /**
+   * 安装单个包到指定目录
+   * @param {string} packageName - 包名
+   * @param {string|null} targetPath - 目标目录，默认为 .agent
+   */
+  _installPackage(packageName, targetPath = null) {
     try {
-      console.log(`[InstallPlugin] Installing ${packageName} to ${this._nodeModulesDir}...`)
+      const installPath = targetPath
+        ? path.resolve(process.cwd(), targetPath)
+        : this._agentDir
+
+      console.log(`[InstallPlugin] Installing ${packageName} to ${installPath}...`)
+
+      // 确保目标目录存在
+      if (!fs.existsSync(installPath)) {
+        fs.mkdirSync(installPath, { recursive: true })
+      }
 
       // 使用 npm install 安装到指定目录
-      // --prefix 确保安装到 .agent/node_modules
-      execSync(`npm install ${packageName} --prefix "${this._agentDir}"`, {
+      execSync(`npm install ${packageName} --prefix "${installPath}"`, {
         stdio: 'inherit',
-        cwd: this._agentDir
+        cwd: installPath
       })
 
       console.log(`[InstallPlugin] Successfully installed ${packageName}`)
 
       return {
         success: true,
-        message: `Successfully installed ${packageName}`
+        message: `Successfully installed ${packageName} to ${installPath}`
       }
     } catch (err) {
       return {
@@ -73,6 +111,61 @@ class InstallPlugin extends Plugin {
     }
   }
 
+  /**
+   * 从 package.json 安装所有依赖
+   * @param {string} packageJsonPath - package.json 路径
+   * @param {string|null} targetPath - 目标目录，默认为 package.json 所在目录
+   */
+  _installFromPackageJson(packageJsonPath, targetPath = null) {
+    try {
+      const resolvedPkgPath = path.resolve(process.cwd(), packageJsonPath)
+      const pkgDir = path.dirname(resolvedPkgPath)
+      const installPath = targetPath
+        ? path.resolve(process.cwd(), targetPath)
+        : pkgDir
+
+      console.log(`[InstallPlugin] Installing dependencies from ${resolvedPkgPath} to ${installPath}...`)
+
+      // 读取 package.json 获取要安装的包
+      const pkg = JSON.parse(fs.readFileSync(resolvedPkgPath, 'utf-8'))
+      const packages = []
+
+      if (pkg.dependencies) {
+        packages.push(...Object.keys(pkg.dependencies))
+      }
+      if (pkg.devDependencies) {
+        packages.push(...Object.keys(pkg.devDependencies))
+      }
+
+      if (packages.length === 0) {
+        return { success: true, message: 'No dependencies to install' }
+      }
+
+      // 确保目标目录存在
+      if (!fs.existsSync(installPath)) {
+        fs.mkdirSync(installPath, { recursive: true })
+      }
+
+      // 使用 npm install 安装
+      execSync(`npm install --prefix "${installPath}" --no-save`, {
+        stdio: 'inherit',
+        cwd: pkgDir
+      })
+
+      console.log(`[InstallPlugin] Successfully installed ${packages.length} packages`)
+
+      return {
+        success: true,
+        message: `Successfully installed ${packages.length} dependencies to ${installPath}`
+      }
+    } catch (err) {
+      return {
+        success: false,
+        error: `Failed to install from package.json: ${err.message}`
+      }
+    }
+  }
+
   /**
    * 获取 node_modules 路径，供其他插件使用
    */
@@ -88,6 +181,16 @@ class InstallPlugin extends Plugin {
       module.paths.unshift(this._nodeModulesDir)
     }
   }
+
+  /**
+   * 添加自定义路径到 module.paths
+   * @param {string} dir - 目录路径
+   */
+  addCustomModulePath(dir) {
+    if (dir && fs.existsSync(dir) && !module.paths.includes(dir)) {
+      module.paths.unshift(dir)
+    }
+  }
 }
 
 module.exports = { InstallPlugin }

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

@@ -8,26 +8,50 @@ This file provides guidance to AI coding agents on how to create plugins for the
 
 User plugins go in `.agent/plugins/` and are **automatically loaded** on bootstrap.
 
+**Recommended: Use folder structure for complex plugins**
+
 ```
 项目目录/
 └── .agent/
     └── plugins/
-        ├── my-plugin.js      ✅ correct
-        └── another-plugin.js ✅ correct
+        ├── my-plugin/              ✅ folder structure (recommended)
+        │   ├── package.json        # optional, main field specifies entry
+        │   ├── index.js            # default entry point
+        │   └── node_modules/       # optional, plugin-private dependencies
+        ├── another-plugin/         ✅ another folder plugin
+        │   └── index.js
+        └── legacy.js               ✅ single-file still supported
 ```
 
+**Why folder structure?**
+- Supports `package.json` with `main` field for custom entry points
+- Supports `node_modules` for plugin-private dependencies
+- Better organization for complex plugins
+
 ### Built-in Plugins: `plugins/` (internal)
 
 Built-in framework plugins are in `plugins/` directory.
 
 ## Plugin Export Formats
 
-###免引入写法 for `.agent/plugins/` ✅
+### Folder structure (recommended for `.agent/plugins/`)
+
+```
+.agent/plugins/my-plugin/
+├── package.json      # optional
+└── index.js         # entry point
+```
 
-User plugins **must** use this format:
+```json
+// package.json example
+{
+  "name": "my-plugin",
+  "main": "index.js"
+}
+```
 
 ```javascript
-// .agent/plugins/my-plugin.js
+// .agent/plugins/my-plugin/index.js
 module.exports = function(Plugin) {
   return class MyPlugin extends Plugin {
     constructor(config = {}) {
@@ -60,10 +84,22 @@ module.exports = function(Plugin) {
 }
 ```
 
+### Single-file structure (still supported)
+
+```javascript
+// .agent/plugins/my-plugin.js
+module.exports = function(Plugin) {
+  return class MyPlugin extends Plugin {
+    // ... same as above
+  }
+}
+```
+
 **Key points:**
 - `Plugin` base class passed automatically by system (no require needed)
 - Factory function returns plugin class
 - Use `require('zod')` inside methods
+- Folder takes priority over single-file if both exist with same name
 
 ### Traditional format for `plugins/` (built-in)
 
@@ -149,14 +185,49 @@ The framework object provides:
 | `framework.registerTool(tool)` | Register tool |
 | `framework.getTools()` | Get all tools |
 | `framework.executeTool(name, args)` | Execute tool |
+| `framework.callTool(name, args)` | Call tool (for installing deps) |
 | `framework.createAgent(config)` | Create Agent |
 | `framework.reloadPlugin(name)` | Reload single plugin |
 | `framework.reloadAllPlugins()` | Reload all plugins |
 
+## Dependency Management
+
+Use the `install` tool to install npm packages:
+
+| Plugin Type | Install Location | Command |
+|-------------|------------------|---------|
+| **Folder plugin** | `.agent/plugins/plugin-name/node_modules/` | `install({ package: "pkg", path: ".agent/plugins/plugin-name" })` |
+| **Single-file plugin** | `.agent/node_modules/` | `install({ package: "pkg" })` |
+
+```javascript
+// Folder plugin - install to plugin directory
+await framework.callTool('install', {
+  package: 'axios',
+  path: '.agent/plugins/my-plugin'
+})
+
+// Single-file plugin - install to .agent
+await framework.callTool('install', {
+  package: 'zod'
+})
+
+// Install from package.json
+await framework.callTool('install', {
+  file: './my-plugin/package.json',
+  path: '.agent/plugins/my-plugin'
+})
+```
+
+**When encountering `Cannot find module 'xxx'` error:**
+1. Identify plugin directory
+2. Call `install` tool with `path` parameter for folder plugins
+3. Reload plugin
+4. Report status to user
+
 ## Common Mistakes
 
-1. ❌ Creating directory `plugins/my-plugin/index.js` - must be single file
-2. ❌ Forgetting `install()` - tools won't be registered
-3. ❌ Forgetting `return this` - chain calls will fail
-4. ❌ Using `parameters` instead of `inputSchema`
-5. ❌ Registering tools outside `install()`
+1. ❌ Forgetting `install()` - tools won't be registered
+2. ❌ Forgetting `return this` - chain calls will fail
+3. ❌ Using `parameters` instead of `inputSchema`
+4. ❌ Registering tools outside `install()`
+5. ❌ Using same name for folder and file - folder takes priority, file will be ignored

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)