foliko 1.0.0

package/SPEC.md

@@ -0,0 +1,452 @@
+# VB-Agent Framework 规划文档
+
+## 一、设计目标
+
+1. **纯 JS 实现** - 无 TypeScript，简明易懂
+2. **架构简约** - 核心仅包含必要组件，通过插件扩展功能
+3. **插件系统与 Agent 分离** - Agent 专注于对话推理，插件提供扩展能力
+4. **手动热重载** - 不监测文件变化，通过 API 手动调用重载
+
+## 二、核心架构
+
+```
+┌─────────────────────────────────────────────────┐
+│                  VB-Agent Framework             │
+├─────────────────────────────────────────────────┤
+│  Framework (容器层)                              │
+│  ├── pluginManager    - 插件加载/卸载/重载       │
+│  ├── toolRegistry    - 工具注册表              │
+│  ├── skillManager    - Skill管理 (可选)        │
+│  └── eventEmitter    - 事件总线                │
+├─────────────────────────────────────────────────┤
+│  Agent (对话层)                                  │
+│  ├── chat()           - 对话接口                 │
+│  ├── tools           - 从 Framework 获取       │
+│  └── events          - 事件监听                │
+└─────────────────────────────────────────────────┘
+```
+
+### 2.1 Framework 类
+
+```javascript
+class Framework {
+  constructor(config = {})
+  registerPlugin(plugin)     // 注册插件
+  loadPlugin(pluginDef)      // 加载插件
+  unloadPlugin(name)         // 卸载插件
+  reloadPlugin(name)         // 重载单个插件
+  reloadAllPlugins()         // 重载所有插件
+  registerTool(tool)         // 注册工具
+  getTools()                 // 获取所有工具
+  on(event, handler)        // 监听事件
+  emit(event, data)         // 触发事件
+  ready()                    // 等待初始化完成
+}
+```
+
+### 2.2 Agent 类
+
+```javascript
+// 创建 Agent
+const agent = framework.createAgent({
+  name: 'MyAgent',                    // Agent 名称
+  systemPrompt: '你是一个助手',        // 系统提示
+
+  // 共享提示模板 (支持 {{VAR}} 占位符)
+  sharedPrompt: `工作目录: {{WORK_DIR}}`,
+
+  // 元数据 (供 sharedPrompt 和自身使用)
+  metadata: {
+    projectName: 'MyProject',
+    version: '1.0.0'
+  }
+})
+
+// 运行时元数据操作
+agent.setMetadata('task', '数据分析')      // 设置单个
+agent.setMetadata({ key: 'value' })        // 批量设置
+agent.getMetadata('task')                   // 获取
+agent.deleteMetadata('task')               // 删除
+agent.clearMetadata()                      // 清空
+```
+
+**内置占位符：**
+| 占位符 | 说明 |
+|--------|------|
+| `{{WORK_DIR}}` | 工作目录 |
+| `{{HOME_DIR}}` | 主目录 |
+| `{{HOST_NAME}}` | 主机名 |
+| `{{PLATFORM}}` | 平台 |
+| `{{TIME}}` | 当前时间 |
+| `{{DATE}}` | 当前日期 |
+
+**Agent 方法：**
+```javascript
+class Agent {
+  constructor(framework, config)    // 创建 Agent
+  chat(message, options)           // 发送消息
+  chatStream(message, options)     // 流式发送消息
+  setSystemPrompt(prompt)          // 设置系统提示
+  registerTool(tool)              // 注册工具
+  getTools()                      // 获取工具列表
+  clearHistory()                  // 清空对话历史
+  getStatus()                     // 获取状态
+  destroy()                       // 销毁 Agent
+
+  // 元数据管理
+  setMetadata(key, value)         // 设置元数据
+  getMetadata(key)                // 获取元数据
+  deleteMetadata(key)              // 删除元数据
+  clearMetadata()                  // 清空元数据
+}
+```
+
+**生成的 System Prompt 示例：**
+```
+你是一个助手。
+
+工作目录: D:\project
+
+【元数据】
+- projectName: MyProject
+- version: 1.0.0
+
+【可用工具】
+- shell: 执行命令
+- python: 执行Python代码
+```
+
+### 2.3 插件基类
+
+```javascript
+class Plugin {
+  name           // 插件名称 (必填)
+  version = '1.0.0'
+  description    // 插件描述
+
+  install(framework) { }     // 安装时调用
+  start(framework) { }       // 启动时调用
+  reload(framework) { }      // 热重载时调用
+  uninstall(framework) { }    // 卸载时调用
+}
+```
+
+## 三、目录结构
+
+```
+D:\code\vb-agent\
+├── src/
+│   ├── core/
+│   │   ├── framework.js     # 核心容器
+│   │   ├── agent.js         # Agent类
+│   │   ├── agent-chat.js    # 聊天处理器
+│   │   ├── plugin-manager.js# 插件管理器
+│   │   ├── plugin-base.js   # 插件基类
+│   │   ├── tool-registry.js # 工具注册表
+│   │   ├── provider.js      # AI Provider 工厂
+│   │   └── index.js         # 统一导出
+│   ├── capabilities/
+│   │   ├── skill-manager.js # Skill 管理器
+│   │   └── workflow-engine.js # 工作流引擎
+│   ├── executors/
+│   │   ├── executor-base.js # 执行器基类
+│   │   └── mcp-executor.js  # MCP 执行器
+│   ├── utils/
+│   │   └── event-emitter.js # 事件发射器
+│   └── index.js
+├── plugins/                  # 内置插件
+│   ├── ai-plugin.js         # AI对话插件
+│   ├── tools-plugin.js       # 内置工具插件
+│   ├── default-plugins.js   # 默认插件加载器
+│   ├── shell-executor-plugin.js # Shell执行器插件
+│   ├── python-executor-plugin.js # Python执行器插件
+│   ├── session-plugin.js    # Session会话管理插件
+│   ├── audit-plugin.js      # Audit审计日志插件
+│   ├── rules-plugin.js      # Rules规则引擎插件
+│   ├── scheduler-plugin.js   # Scheduler定时任务插件
+│   ├── storage-plugin.js     # Storage存储插件
+│   └── subagent-plugin.js    # SubAgent子代理插件
+├── examples/
+│   ├── basic.js              # 基础示例
+│   ├── bootstrap.js          # Bootstrap示例
+│   └── workflow.js           # 工作流示例
+├── .agent/                   # Agent 配置目录
+│   ├── config                # 配置文件
+│   ├── ai.json              # AI 配置
+│   ├── plugins.json         # 插件列表
+│   ├── mcp_config.json      # MCP 服务器配置
+│   └── skills/              # Skill 目录
+├── package.json
+└── SPEC.md
+```
+
+## 四、核心模块
+
+### 4.1 Framework (src/core/framework.js)
+
+**职责**：
+- 管理插件生命周期
+- 提供工具注册表
+- 事件总线
+- 初始化协调
+
+**API**：
+```javascript
+const framework = new Framework({
+  debug: false
+})
+
+// 插件操作
+framework.registerPlugin(myPlugin)
+await framework.loadPlugin({ type: 'ai-plugin', config: {...} })
+await framework.unloadPlugin('my-plugin')
+await framework.reloadPlugin('my-plugin')  // 手动热重载
+await framework.reloadAllPlugins()
+
+// 工具操作
+framework.registerTool({
+  name: 'my_tool',
+  description: '...',
+  execute: async (args) => { ... }
+})
+
+// 事件
+framework.on('plugin:loaded', (plugin) => { ... })
+framework.emit('agent:message', { content: '...' })
+
+// 就绪
+await framework.ready()
+```
+
+### 4.2 Agent (src/core/agent.js)
+
+**职责**：
+- 维护对话上下文
+- 调用 AI 进行对话
+- 管理工具调用循环
+
+**API**：
+```javascript
+const agent = framework.createAgent({
+  systemPrompt: '你是一个有帮助的助手',
+  model: 'deepseek-chat',
+  apiKey: '...'
+})
+
+agent.on('message', (msg) => { ... })
+agent.on('tool-call', (tool) => { ... })
+
+const response = await agent.chat('你好')
+```
+
+### 4.3 PluginManager (src/core/plugin-manager.js)
+
+**职责**：
+- 维护已加载插件列表
+- 按优先级排序加载
+- 协调插件生命周期
+
+**生命周期**：
+1. `install()` - 注册工具/事件
+2. `start()` - 初始化完成，开始工作
+3. `reload()` - 热重载
+4. `uninstall()` - 清理
+
+### 4.4 ToolRegistry (src/core/tool-registry.js)
+
+**职责**：
+- 注册工具
+- 调用工具
+- 工具描述管理
+
+**工具格式**：
+```javascript
+{
+  name: 'tool_name',
+  description: '工具描述',
+  parameters: { ... },  // Zod schema 或 JSON schema
+  execute: async (args, framework) => { ... }
+}
+```
+
+## 五、事件系统
+
+```javascript
+// 事件列表
+'framework:ready'           // 框架就绪
+'plugin:install'           // 插件安装
+'plugin:start'             // 插件启动
+'plugin:reload'            // 插件重载
+'plugin:uninstall'         // 插件卸载
+'agent:message'             // Agent消息
+'agent:tool-call'          // Agent调用工具
+'agent:tool-result'         // 工具执行结果
+```
+
+## 六、热重载机制
+
+### 设计原则
+- **不监测文件变化** - 避免复杂性和性能开销
+- **手动调用重载** - 通过 API 触发
+- **插件自管理** - 插件提供 reload() 方法
+
+### API
+```javascript
+// 重载单个插件
+await framework.reloadPlugin('my-plugin')
+
+// 重载所有插件
+await framework.reloadAllPlugins()
+
+// 在 Agent 中调用
+agent.chat('请重载 my-plugin 插件')
+// 需要插件提供 reload_plugins 工具
+```
+
+### 重载流程
+1. 调用 `plugin.reload(framework)`
+2. 插件清理旧资源
+3. 插件重新初始化
+4. 更新工具注册表
+
+## 七、内置插件
+
+### 7.1 AI Plugin (plugins/ai-plugin.js)
+
+**功能**：
+- AI 对话能力
+- 工具调用循环
+
+**配置**：
+```javascript
+{
+  type: 'ai-plugin',
+  provider: 'deepseek',      // deepseek / openai / anthropic
+  model: 'deepseek-chat',
+  apiKey: '...',
+  baseURL: '...'            // 可选，自定义端点
+}
+```
+
+### 7.2 Tools Plugin (plugins/tools-plugin.js)
+
+**功能**：
+- 内置工具注册
+- 工具调用执行
+
+**内置工具**：
+- `reload_plugins` - 热重载插件
+- `list_plugins` - 列出已加载插件
+
+## 八、使用示例
+
+### 8.1 基础用法
+
+```javascript
+const { Framework } = require('./src')
+
+const framework = new Framework({ debug: true })
+
+// 注册插件
+framework.registerPlugin({
+  name: 'my-plugin',
+  install(f) {
+    f.registerTool({
+      name: 'greet',
+      description: '打招呼',
+      execute: async (args) => `Hello, ${args.name}!`
+    })
+  }
+})
+
+await framework.ready()
+
+const agent = framework.createAgent({
+  systemPrompt: '你是一个助手',
+  model: 'deepseek-chat',
+  apiKey: process.env.API_KEY
+})
+
+const response = await agent.chat('你好')
+console.log(response)
+```
+
+### 8.2 热重载
+
+```javascript
+// 重载单个插件
+await framework.reloadPlugin('my-plugin')
+
+// 重载所有插件
+await framework.reloadAllPlugins()
+```
+
+## 九、代码规范
+
+### 9.1 文件命名
+- 类文件：`小写-连字符.js`，如 `plugin-base.js`
+- 目录：`小写-连字符`，如 `src/core`
+
+### 9.2 类命名
+- 类名：`大写驼峰`，如 `Framework`, `Agent`
+- 方法名：`小写驼峰`，如 `registerTool`, `loadPlugin`
+
+### 9.3 变量命名
+- 类属性：`小写驼峰`
+- 常量：`全大写+下划线`，如 `DEFAULT_PRIORITY`
+- 私有属性：`_下划线前缀`
+
+### 9.4 注释
+```javascript
+/**
+ * 类描述
+ */
+class Framework {
+  /**
+   * 方法描述
+   * @param {string} name - 参数描述
+   * @returns {Promise<void>}
+   */
+  async loadPlugin(name) { }
+}
+```
+
+## 十、已实现功能
+
+### Phase 1 - 核心框架 ✓
+- [x] Framework 核心类 (`src/core/framework.js`)
+- [x] Agent 基础类 (`src/core/agent.js`)
+- [x] 插件系统 (`src/core/plugin-manager.js`, `src/core/plugin-base.js`)
+- [x] 工具注册表 (`src/core/tool-registry.js`)
+- [x] 事件系统 (`src/utils/event-emitter.js`)
+- [x] 热重载 API (`reloadPlugin()`, `reloadAllPlugins()`)
+
+### Phase 2 - 内置插件 ✓
+- [x] AI Plugin (`plugins/ai-plugin.js`) - 对接 Vercel AI SDK
+- [x] 内置工具插件 (`plugins/tools-plugin.js`) - 热重载、列表工具
+
+### Phase 3 - 高级功能 ✓
+- [x] Skill 管理 (`src/capabilities/skill-manager.js`) - 加载和管理 Skill
+- [x] 工作流引擎 (`src/capabilities/workflow-engine.js`) - 支持脚本、条件、循环等
+- [x] MCP 执行器 (`src/executors/mcp-executor.js`) - 连接 MCP 服务器
+- [x] Shell 执行器 (`plugins/shell-executor-plugin.js`) - 执行终端命令
+- [x] Python 执行器 (`plugins/python-executor-plugin.js`) - 执行 Python 代码和脚本
+- [x] Session 管理 (`plugins/session-plugin.js`) - 多会话支持、历史记录
+- [x] Audit 审计日志 (`plugins/audit-plugin.js`) - 操作日志记录和查询
+- [x] Rules 规则引擎 (`plugins/rules-plugin.js`) - 权限控制、内容过滤
+- [x] Scheduler 定时任务 (`plugins/scheduler-plugin.js`) - Cron 调度
+- [x] Storage 存储 (`plugins/storage-plugin.js`) - 键值对持久化存储
+- [x] SubAgent 子Agent (`plugins/subagent-plugin.js`) - 子Agent隔离工具集
+
+## 十一、依赖
+
+```json
+{
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.41",
+    "@ai-sdk/openai-compatible": "^2.0.35",
+    "ai": "^6.0.116",
+    "zod": "^4.3.6"
+  }
+}
+```

package/cli/bin/foliko.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Foliko CLI 入口
+ * Usage: foliko <command> [options]
+ */
+
+// 加载 dotenv
+require('dotenv').config()
+
+const { cli } = require('../src')
+
+cli()

package/cli/src/commands/chat.js

@@ -0,0 +1,75 @@
+/**
+ * Chat 命令实现
+ */
+
+const readline = require('readline')
+const { Framework } = require('../../../src')
+const { ChatUI } = require('../ui/chat-ui')
+
+/**
+ * 解析命令行参数
+ */
+function parseArgs(args) {
+  const options = {
+    model: process.env.FOLIKO_MODEL || 'MiniMax-M2.7',
+    provider: process.env.FOLIKO_PROVIDER || 'minimax',
+    baseURL: process.env.FOLIKO_BASE_URL || 'https://api.minimaxi.com/v1',
+    apiKey: process.env.MINIMAX_API_KEY || process.env.DEEPSEEK_API_KEY
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--model' && args[i + 1]) {
+      options.model = args[++i]
+    } else if (arg === '--provider' && args[i + 1]) {
+      options.provider = args[++i]
+    } else if (arg === '--base-url' && args[i + 1]) {
+      options.baseURL = args[++i]
+    } else if (arg === '--api-key' && args[i + 1]) {
+      options.apiKey = args[++i]
+    }
+  }
+
+  return options
+}
+
+/**
+ * Chat 命令入口
+ */
+async function chatCommand(args) {
+  const options = parseArgs(args)
+
+  console.log('=== Foliko 持续对话 ===\n')
+  console.log('输入 exit 或 quit 退出\n')
+
+  // 初始化框架
+  const framework = new Framework({ debug: false })
+  await framework.bootstrap({
+    agentDir: process.cwd() + '/.agent',
+    aiConfig: {
+      provider: options.provider,
+      model: options.model,
+      baseURL: options.baseURL,
+      apiKey: options.apiKey
+    }
+  })
+
+  // 创建 Agent
+  const agent = framework.createAgent({
+    name: 'FolikoAgent',
+    systemPrompt: '你是一个有帮助的助手，擅长回答问题和执行任务。',
+    sharedPrompt: '工作目录: {{WORK_DIR}}',
+    sharedPrompt: '工作目录: {{WORK_DIR}}',
+    metadata: {
+      WORK_DIR: process.cwd()  // 覆盖内置的 WORK_DIR
+    }
+  })
+
+  // 初始化 UI
+  const ui = new ChatUI(agent)
+
+  // 启动聊天
+  ui.start()
+}
+
+module.exports = { chatCommand }

package/cli/src/index.js

@@ -0,0 +1,64 @@
+/**
+ * Foliko CLI 主逻辑
+ */
+
+const { chatCommand } = require('./commands/chat')
+
+/**
+ * CLI 主入口
+ */
+function cli() {
+  const args = process.argv.slice(2)
+  const command = args[0] || 'chat'
+
+  switch (command) {
+    case 'chat':
+      chatCommand(args.slice(1))
+      break
+
+    case 'help':
+    case '--help':
+    case '-h':
+      printHelp()
+      break
+
+    case 'version':
+    case '--version':
+    case '-v':
+      console.log('foliko v1.0.0')
+      break
+
+    default:
+      console.error(`Unknown command: ${command}`)
+      console.error('Run "foliko help" for usage information')
+      process.exit(1)
+  }
+}
+
+/**
+ * 打印帮助信息
+ */
+function printHelp() {
+  console.log(`
+Foliko CLI - Agent 框架的命令行工具
+
+Usage: foliko <command> [options]
+
+Commands:
+  chat              启动持续对话聊天
+  help              显示帮助信息
+  version           显示版本号
+
+Chat Options:
+  --model <name>    指定 AI 模型
+  --provider <name> 指定 AI 提供商
+  --base-url <url>  指定 API 基础地址
+
+Examples:
+  foliko chat
+  foliko chat --model MiniMax-M2.7
+  foliko chat --provider minimax --base-url https://api.minimaxi.com/v1
+`)
+}
+
+module.exports = { cli }