foliko 1.0.0

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

@@ -0,0 +1,162 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents on how to create plugins for the VB-Agent Framework system.
+
+## Plugin File Location
+
+### User Plugins: `.agent/plugins/` (auto-loaded)
+
+User plugins go in `.agent/plugins/` and are **automatically loaded** on bootstrap.
+
+```
+项目目录/
+└── .agent/
+    └── plugins/
+        ├── my-plugin.js      ✅ correct
+        └── another-plugin.js ✅ correct
+```
+
+### Built-in Plugins: `plugins/` (internal)
+
+Built-in framework plugins are in `plugins/` directory.
+
+## Plugin Export Formats
+
+###免引入写法 for `.agent/plugins/` ✅
+
+User plugins **must** use this format:
+
+```javascript
+// .agent/plugins/my-plugin.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) {
+      // cleanup
+    }
+  }
+}
+```
+
+**Key points:**
+- `Plugin` base class passed automatically by system (no require needed)
+- Factory function returns plugin class
+- Use `require('zod')` inside methods
+
+### Traditional format for `plugins/` (built-in)
+
+```javascript
+// plugins/my-plugin.js
+const { Plugin } = require('../src/core/plugin-base')
+const { z } = require('zod')
+
+class MyPlugin extends Plugin {
+  constructor(config = {}) {
+    super()
+    this.name = 'my-plugin'
+    this.version = '1.0.0'
+    this.description = '我的插件'
+    this.priority = 10
+  }
+
+  install(framework) {
+    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) { }
+}
+
+module.exports = { MyPlugin }
+```
+
+## Plugin Properties
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `name` | string | ✅ | Unique name |
+| `version` | string | ❌ | Version, default '1.0.0' |
+| `description` | string | ❌ | Description |
+| `priority` | number | ❌ | Load priority, default 10 |
+
+## Lifecycle Methods
+
+| Method | Called When | Required |
+|--------|-------------|----------|
+| `install(framework)` | Plugin installed | ✅ |
+| `start(framework)` | Plugin started | Recommended |
+| `reload(framework)` | Hot reload | Optional |
+| `uninstall(framework)` | Plugin uninstalled | Recommended |
+
+## Tool Registration
+
+In `install()` method, register tools using `framework.registerTool()`:
+
+```javascript
+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
+}
+```
+
+## Framework Object
+
+The framework object provides:
+
+| Method | Description |
+|--------|-------------|
+| `framework.registerTool(tool)` | Register tool |
+| `framework.getTools()` | Get all tools |
+| `framework.executeTool(name, args)` | Execute tool |
+| `framework.createAgent(config)` | Create Agent |
+| `framework.reloadPlugin(name)` | Reload single plugin |
+| `framework.reloadAllPlugins()` | Reload all plugins |
+
+## 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()`

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

@@ -0,0 +1,370 @@
+---
+name: vb-agent-dev
+description: VB-Agent Framework 插件开发指南。当用户说"创建插件"、"开发插件"时立即调用此 skill。
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+---
+
+# VB-Agent Plugin Development Guide
+
+## 概述
+
+VB-Agent 是一个基于插件的 Agent 框架，核心简单，通过插件扩展功能。
+
+---
+
+## 插件存放位置
+
+### `.agent/plugins/` 目录（用户插件，自动加载）
+
+用户自定义插件放在项目根目录的 `.agent/plugins/` 下，**自动加载**，无需手动注册。
+
+```
+项目目录/
+└── .agent/
+    └── plugins/
+        ├── my-plugin.js      ✅ 正确
+        └── another-plugin.js ✅ 正确
+```
+
+### `plugins/` 目录（内置插件）
+
+框架内置插件位于 `plugins/` 目录。
+
+---
+
+## 用户插件写法（`.agent/plugins/`）
+
+**必须使用免引入写法**：
+
+```javascript
+// .agent/plugins/my-plugin.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) {
+      // 清理资源
+    }
+  }
+}
+```
+**插件开发流程：**
+1. **创建插件文件**（暂不加载）
+2. **安装依赖**：`install { package: "包名" }`
+3. **热重载**：`reload_plugins`
+4. **检查加载状态**
+
+
+**关键点：**
+- `Plugin` 基类由系统自动传入（无需 require）
+- 函数直接返回插件类
+- 在 `install(framework)` 中通过 `framework` 注册工具
+
+---
+
+## 依赖管理
+
+当插件需要使用第三方 npm 包（如 `zod`、`axios` 等）时，必须自动安装到 `.agent/node_modules`：
+
+### 自动安装工具
+
+框架提供了 `install` 工具，可以自动安装 npm 包：
+
+```javascript
+// 在 execute 中调用 install 工具
+execute: async (args, framework) => {
+  // 安装缺失的包
+  const installResult = await framework.callTool('install', {
+    package: 'zod'  // 或 'zod@4.3.6' 指定版本
+  })
+
+  if (!installResult.success) {
+    return { success: false, error: installResult.error }
+  }
+
+  // 安装成功后可以正常 require
+  const { z } = require('zod')
+  // ... 继续执行
+}
+```
+
+### 安装步骤
+
+当 LLM 检测到 `Cannot find module 'xxx'` 错误时，必须：
+
+1. **立即调用 `install` 工具** 安装缺失的包
+2. **安装完成后** 重新加载插件
+3. **返回状态** 给用户
+
+示例流程：
+```
+错误: Cannot find module 'axios'
+↓
+自动安装: install { package: "axios" }
+↓
+重新加载插件
+↓
+成功
+```
+
+### 重要提醒
+
+- **不要尝试手动 require 全局安装的包** - 必须在 `.agent/node_modules` 中安装
+- **使用 `install` 工具自动处理** - 让 LLM 知道如何处理缺失依赖
+- **插件加载失败时检查依赖** - 优先安装缺失的包再重试
+
+---
+
+## 内置插件写法（`plugins/` 目录）
+
+内置插件使用传统写法，需要 `require` Plugin 基类：
+
+```javascript
+// plugins/my-plugin.js
+const { Plugin } = require('../src/core/plugin-base')
+const { z } = require('zod')
+
+class MyPlugin extends Plugin {
+  constructor(config = {}) {
+    super()
+    this.name = 'my-plugin'
+    this.version = '1.0.0'
+    this.description = '我的工具插件'
+    this.priority = 10
+  }
+
+  install(framework) {
+    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) { }
+}
+
+module.exports = { MyPlugin }
+```
+
+---
+
+## 插件属性
+
+| 属性 | 类型 | 必须 | 说明 |
+|------|------|------|------|
+| `name` | string | ✅ | 唯一名称 |
+| `version` | string | ❌ | 版本号，默认 '1.0.0' |
+| `description` | string | ❌ | 插件描述 |
+| `priority` | number | ❌ | 加载优先级，默认 10 |
+
+---
+
+## 生命周期
+
+| 方法 | 调用时机 | 必须实现 |
+|------|----------|---------|
+| `install(framework)` | 插件安装时 | ✅ |
+| `start(framework)` | 插件启动时 | 推荐 |
+| `reload(framework)` | 热重载时 | 可选 |
+| `uninstall(framework)` | 卸载时 | 推荐 |
+
+---
+
+## 注册工具
+
+```javascript
+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
+}
+```
+
+---
+
+## 核心规则
+
+| 规则 | 说明 |
+|------|------|
+| **禁止创建目录！** | **必须是单个 `.js` 文件！** |
+| **必须用 inputSchema** | `inputSchema: z.object({})`（不是 parameters!） |
+| **必须用 zod 定义参数** | `param: z.string().describe('描述')` |
+| **install 必须返回 this** | 确保链式调用 |
+
+## 开发完成后注意事项
+
+### 引入第三方库时
+
+**必须先安装依赖，再热重载！**
+
+如果插件需要使用第三方 npm 包（如 `zod`、`axios`），按以下顺序操作：
+
+1. **创建插件文件**（暂不加载）
+2. **安装依赖**：`install { package: "包名" }`
+3. **热重载**：`reload_plugins`
+4. **检查加载状态**
+
+示例：
+```
+创建插件 my-plugin.js（需要 zod）
+↓
+install { package: "zod" }
+↓
+reload_plugins
+↓
+成功加载
+```
+
+### 其他注意事项
+--**开发完成重载成功后检测有没有加载新的插件，不需要进行过多测试步骤，直接告知用户状态即可**
+
+---
+
+## 内置占位符
+
+Agent 支持 `sharedPrompt` 中的占位符替换：
+
+| 占位符 | 说明 |
+|--------|------|
+| `{{WORK_DIR}}` | 工作目录 |
+| `{{HOME_DIR}}` | 主目录 |
+| `{{HOST_NAME}}` | 主机名 |
+| `{{PLATFORM}}` | 平台 |
+| `{{TIME}}` | 当前时间 |
+| `{{DATE}}` | 当前日期 |
+
+---
+
+## 创建 Agent
+
+```javascript
+const agent = framework.createAgent({
+  name: 'MyAgent',
+  systemPrompt: '你是一个助手',
+  sharedPrompt: '工作目录: {{WORK_DIR}}\n项目: {{projectName}}',
+  metadata: {
+    projectName: 'MyProject',
+    version: '1.0.0'
+  }
+})
+```
+
+---
+
+## 热重载
+
+```javascript
+// 重载单个插件
+await framework.reloadPlugin('my-plugin')
+
+// 重载所有插件
+await framework.reloadAllPlugins()
+```
+
+---
+
+## 子 Agent 注册
+
+插件可以通过 `this.agents = []` 配置或 `this.registerSubAgent()` 方法注册子Agent。
+
+### 方式1：配置 `agents` 数组
+
+```javascript
+// plugins/my-plugin.js
+const { Plugin } = require('../src/core/plugin-base')
+const { tool } = require('ai')
+const { z } = require('zod')
+
+class MyPlugin extends Plugin {
+  constructor(config = {}) {
+    super()
+    this.name = 'my-plugin'
+  }
+
+  // 配置式注册子Agent，插件启动时自动创建
+  agents = [
+    {
+      name: 'code-agent',
+      role: '代码专家',
+      description: '处理代码开发任务',
+      tools: {
+        compile: tool({
+          description: '编译代码',
+          parameters: z.object({
+            language: z.string(),
+            code: z.string()
+          }),
+          execute: async (args) => ({ success: true })
+        })
+      },
+      parentTools: ['read_file', 'write_file']
+    }
+  ]
+}
+```
+
+### 方式2：手动调用 `registerSubAgent()`
+
+```javascript
+start(framework) {
+  this.registerSubAgent({
+    name: 'code-agent',
+    role: '代码专家',
+    tools: {
+      compile: tool({
+        description: '编译代码',
+        parameters: z.object({ language: z.string(), code: z.string() }),
+        execute: async (args) => ({ success: true })
+      })
+    },
+    parentTools: ['read_file', 'write_file']
+  })
+}
+```
+
+### 子Agent配置说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `name` | string | 子Agent名称（唯一标识） |
+| `role` | string | 角色描述 |
+| `description` | string | 详细描述 |
+| `tools` | object | 自定义工具 `{ name: toolDef }`，只属于此子Agent |
+| `parentTools` | array | 从父Agent继承的工具名称列表 |

package/src/capabilities/index.js

@@ -0,0 +1,11 @@
+/**
+ * Capabilities 能力模块导出
+ */
+
+const { SkillManagerPlugin } = require('./skill-manager')
+const { WorkflowPlugin } = require('./workflow-engine')
+
+module.exports = {
+  SkillManagerPlugin,
+  WorkflowPlugin
+}