foliko 1.0.8 → 1.0.10

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