foliko 1.0.7 → 1.0.9

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/framework.js

@@ -89,6 +89,33 @@ class Framework extends EventEmitter {
     return this
   }
 
+  /**
+   * 启用插件
+   * @param {string} name - 插件名称
+   */
+  async enablePlugin(name) {
+    await this.pluginManager.enable(name)
+    return this
+  }
+
+  /**
+   * 禁用插件
+   * @param {string} name - 插件名称
+   */
+  async disablePlugin(name) {
+    await this.pluginManager.disable(name)
+    return this
+  }
+
+  /**
+   * 更新插件配置
+   * @param {string} name - 插件名称
+   * @param {Object} config - 新配置
+   */
+  updatePluginConfig(name, config) {
+    return this.pluginManager.updatePluginConfig(name, config)
+  }
+
   /**
    * 注册工具
    * @param {Object} tool - 工具定义