foliko 1.0.74 → 1.0.76

package/SPEC.md

@@ -49,8 +49,8 @@ class Framework {
 ```javascript
 // 创建 Agent
 const agent = framework.createAgent({
-  name: 'MyAgent',                    // Agent 名称
-  systemPrompt: '你是一个助手',        // 系统提示
+  name: 'MyAgent', // Agent 名称
+  systemPrompt: '你是一个助手', // 系统提示
 
   // 共享提示模板 (支持 {{VAR}} 占位符)
   sharedPrompt: `工作目录: {{WORK_DIR}}`,
@@ -58,16 +58,16 @@ const agent = framework.createAgent({
   // 元数据 (供 sharedPrompt 和自身使用)
   metadata: {
     projectName: 'MyProject',
-    version: '1.0.0'
-  }
-})
+    version: '1.0.0',
+  },
+});
 
 // 运行时元数据操作
-agent.setMetadata('task', '数据分析')      // 设置单个
-agent.setMetadata({ key: 'value' })        // 批量设置
-agent.getMetadata('task')                   // 获取
-agent.deleteMetadata('task')               // 删除
-agent.clearMetadata()                      // 清空
+agent.setMetadata('task', '数据分析'); // 设置单个
+agent.setMetadata({ key: 'value' }); // 批量设置
+agent.getMetadata('task'); // 获取
+agent.deleteMetadata('task'); // 删除
+agent.clearMetadata(); // 清空
 ```
 
 **内置占位符：**
@@ -81,6 +81,7 @@ agent.clearMetadata()                      // 清空
 | `{{DATE}}` | 当前日期 |
 
 **Agent 方法：**
+
 ```javascript
 class Agent {
   constructor(framework, config)    // 创建 Agent
@@ -102,6 +103,7 @@ class Agent {
 ```
 
 **生成的 System Prompt 示例：**
+
 ```
 你是一个助手。
 
@@ -120,14 +122,14 @@ class Agent {
 
 ```javascript
 class Plugin {
-  name           // 插件名称 (必填)
-  version = '1.0.0'
-  description    // 插件描述
-
-  install(framework) { }     // 安装时调用
-  start(framework) { }       // 启动时调用
-  reload(framework) { }      // 热重载时调用
-  uninstall(framework) { }    // 卸载时调用
+  name; // 插件名称 (必填)
+  version = '1.0.0';
+  description; // 插件描述
+
+  install(framework) {} // 安装时调用
+  start(framework) {} // 启动时调用
+  reload(framework) {} // 热重载时调用
+  uninstall(framework) {} // 卸载时调用
 }
 ```
 
@@ -190,14 +192,15 @@ D:\code\foliko\
 
 ```javascript
 // 更新插件配置
-framework.updatePluginConfig('telegram', { allowedChats: ['123'] })
+framework.updatePluginConfig('telegram', { allowedChats: ['123'] });
 
 // 启用/禁用插件
-framework.enablePlugin('telegram')
-framework.disablePlugin('telegram')
+framework.enablePlugin('telegram');
+framework.disablePlugin('telegram');
 ```
 
 **保存的内容：**
+
 - `enabled` - 插件启用状态
 - `config` - 插件配置对象
 
@@ -206,12 +209,14 @@ framework.disablePlugin('telegram')
 ### 4.1 Framework (src/core/framework.js)
 
 **职责**：
+
 - 管理插件生命周期
 - 提供工具注册表
 - 事件总线
 - 初始化协调
 
 **API**：
+
 ```javascript
 const framework = new Framework({
   debug: false
@@ -242,11 +247,13 @@ await framework.ready()
 ### 4.2 Agent (src/core/agent.js)
 
 **职责**：
+
 - 维护对话上下文
 - 调用 AI 进行对话
 - 管理工具调用循环
 
 **API**：
+
 ```javascript
 const agent = framework.createAgent({
   systemPrompt: '你是一个有帮助的助手',
@@ -263,11 +270,13 @@ const response = await agent.chat('你好')
 ### 4.3 PluginManager (src/core/plugin-manager.js)
 
 **职责**：
+
 - 维护已加载插件列表
 - 按优先级排序加载
 - 协调插件生命周期
 
 **生命周期**：
+
 1. `install()` - 注册工具/事件
 2. `start()` - 初始化完成，开始工作
 3. `reload()` - 热重载
@@ -276,11 +285,13 @@ const response = await agent.chat('你好')
 ### 4.4 ToolRegistry (src/core/tool-registry.js)
 
 **职责**：
+
 - 注册工具
 - 调用工具
 - 工具描述管理
 
 **工具格式**：
+
 ```javascript
 {
   name: 'tool_name',
@@ -294,21 +305,21 @@ const response = await agent.chat('你好')
 
 ```javascript
 // 事件列表
-'framework:ready'           // 框架就绪
-'plugin:install'           // 插件安装
-'plugin:start'             // 插件启动
-'plugin:reload'            // 插件重载
-'plugin:uninstall'         // 插件卸载
-'plugin:enabled'           // 插件启用
-'plugin:disabled'          // 插件禁用
-'agent:message'             // Agent消息
-'agent:tool-call'          // Agent调用工具
-'agent:tool-result'        // 工具执行结果
-'notification'            // 统一通知事件（推送用户）
-'scheduler:reminder'       // 定时提醒触发（业务事件）
-'think:thought_completed'  // 思考完成
-'email:received'           // 收到新邮件
-'webhook:received'        // 收到Webhook请求
+'framework:ready'; // 框架就绪
+'plugin:install'; // 插件安装
+'plugin:start'; // 插件启动
+'plugin:reload'; // 插件重载
+'plugin:uninstall'; // 插件卸载
+'plugin:enabled'; // 插件启用
+'plugin:disabled'; // 插件禁用
+'agent:message'; // Agent消息
+'agent:tool-call'; // Agent调用工具
+'agent:tool-result'; // 工具执行结果
+'notification'; // 统一通知事件（推送用户）
+'scheduler:reminder'; // 定时提醒触发（业务事件）
+'think:thought_completed'; // 思考完成
+'email:received'; // 收到新邮件
+'webhook:received'; // 收到Webhook请求
 ```
 
 ### 通知事件 (notification)
@@ -330,36 +341,39 @@ const response = await agent.chat('你好')
 
 业务事件用于触发 Ambient Agent 的目标，不直接通知用户。
 
-| 事件 | 数据 | 说明 |
-|------|------|------|
-| `scheduler:reminder` | `{ taskId, taskName, message, sessionId, llm }` | 定时提醒触发时 |
-| `think:thought_completed` | `thought` | 思考完成时 |
-| `email:received` | `email` | 收到新邮件时 |
-| `webhook:received` | `{ webhook, data, response, sessionId }` | 收到Webhook请求时 |
-| `tool:result` | `{ name, args, result }` | 工具执行结果 |
-| `agent:message` | `{ content }` | Agent发送消息时 |
+| 事件                      | 数据                                            | 说明              |
+| ------------------------- | ----------------------------------------------- | ----------------- |
+| `scheduler:reminder`      | `{ taskId, taskName, message, sessionId, llm }` | 定时提醒触发时    |
+| `think:thought_completed` | `thought`                                       | 思考完成时        |
+| `email:received`          | `email`                                         | 收到新邮件时      |
+| `webhook:received`        | `{ webhook, data, response, sessionId }`        | 收到Webhook请求时 |
+| `tool:result`             | `{ name, args, result }`                        | 工具执行结果      |
+| `agent:message`           | `{ content }`                                   | Agent发送消息时   |
 
 ## 六、热重载机制
 
 ### 设计原则
+
 - **不监测文件变化** - 避免复杂性和性能开销
 - **手动调用重载** - 通过 API 触发
 - **插件自管理** - 插件提供 reload() 方法
 
 ### API
+
 ```javascript
 // 重载单个插件
-await framework.reloadPlugin('my-plugin')
+await framework.reloadPlugin('my-plugin');
 
 // 重载所有插件
-await framework.reloadAllPlugins()
+await framework.reloadAllPlugins();
 
 // 在 Agent 中调用
-agent.chat('请重载 my-plugin 插件')
+agent.chat('请重载 my-plugin 插件');
 // 需要插件提供 reload_plugins 工具
 ```
 
 ### 重载流程
+
 1. 调用 `plugin.reload(framework)`
 2. 插件清理旧资源
 3. 插件重新初始化
@@ -370,10 +384,12 @@ agent.chat('请重载 my-plugin 插件')
 ### 7.1 AI Plugin (plugins/ai-plugin.js)
 
 **功能**：
+
 - AI 对话能力
 - 工具调用循环
 
 **配置**：
+
 ```javascript
 {
   type: 'ai-plugin',
@@ -387,10 +403,12 @@ agent.chat('请重载 my-plugin 插件')
 ### 7.2 Tools Plugin (plugins/tools-plugin.js)
 
 **功能**：
+
 - 内置工具注册
 - 工具调用执行
 
 **内置工具**：
+
 - `reload_plugins` - 热重载插件
 - `list_plugins` - 列出已加载插件
 - `enable_plugin` - 启用插件
@@ -401,10 +419,12 @@ agent.chat('请重载 my-plugin 插件')
 ### 7.3 Email Plugin (plugins/email-plugin.js)
 
 **功能**：
+
 - SMTP 发送邮件
 - IMAP 读取邮件
 
 **工具**：
+
 - `email_send` - 发送邮件
 - `email_read` - 读取邮件
 - `email_unread_count` - 未读数量
@@ -413,6 +433,7 @@ agent.chat('请重载 my-plugin 插件')
 ### 7.4 Telegram Plugin (plugins/telegram-plugin.js)
 
 **功能**：
+
 - Telegram Bot 对话
 - 绑定主 Agent 持续对话
 - 支持 MarkdownV2
@@ -420,9 +441,11 @@ agent.chat('请重载 my-plugin 插件')
 - 监听 `scheduler:reminder` 事件发送定时提醒
 
 **监听事件**：
+
 - `scheduler:reminder` - 接收定时任务提醒并发送到 Telegram
 
 **配置**：
+
 ```javascript
 {
   botToken: '...',
@@ -435,18 +458,21 @@ agent.chat('请重载 my-plugin 插件')
 ### 7.5 Scheduler Plugin (plugins/scheduler-plugin.js)
 
 **功能**：
+
 - 定时任务调度（Cron 表达式、相对时间、绝对时间）
 - 支持 LLM 自动检测（简单提醒直接显示，需要处理的任务启用 LLM）
 - 会话自动检测（自动发送到最近活跃的会话）
 - 事件系统（供其他插件监听和响应）
 
 **工具**：
+
 - `schedule_task` - 创建定时任务
 - `schedule_list` - 列出所有任务
 - `schedule_cancel` - 取消任务
 - `cron_examples` - Cron 表达式示例
 
 **schedule_task 参数**：
+
 ```javascript
 {
   name: '任务名称',           // 可选
@@ -467,14 +493,17 @@ agent.chat('请重载 my-plugin 插件')
 | Cron | `*/5 * * * *`, `0 9 * * *` | Cron 表达式 |
 
 **自动 LLM 检测**：
+
 - 简单提醒（喝水、吃饭）→ 直接显示
 - 查询/分析任务（查看列表、分析数据）→ 启用 LLM
 
 **持久化**：
+
 - 任务自动保存到 `.agent/data/scheduler/tasks.json`
 - 重启后自动恢复 Cron 任务和未执行的一次性任务
 
 **通知**：
+
 - 任务完成/失败/取消时发送 `notification` 事件
 - 消息插件（微信、飞书）自动推送给用户
 
@@ -483,12 +512,14 @@ agent.chat('请重载 my-plugin 插件')
 ### 8.1 Ambient Agent (plugins/ambient-agent-plugin.js)
 
 **功能**：
+
 - 持续后台运行的智能代理
 - 监控事件并主动执行操作
 - 目标（Goal）管理系统
 - 持久化记忆
 
 **支持的事件**：
+
 - `tool:result` - 工具执行结果
 - `scheduler:reminder` - 定时提醒
 - `agent:message` - 代理消息
@@ -497,6 +528,7 @@ agent.chat('请重载 my-plugin 插件')
 - `webhook:received` - 收到Webhook
 
 **工具**：
+
 - `ambient_goals` - 管理目标（列出/创建/更新/删除/激活）
 - `ambient_status` - 获取状态
 - `ambient_think` - 触发主动思考
@@ -504,6 +536,7 @@ agent.chat('请重载 my-plugin 插件')
 - `ambient_control` - 控制循环（暂停/恢复/调整）
 
 **目标结构**：
+
 ```javascript
 {
   title: '目标标题',
@@ -522,6 +555,7 @@ agent.chat('请重载 my-plugin 插件')
 ```
 
 **通知**：
+
 - 目标完成时发送 `notification` 事件（level: 'success'）
 - 目标失败时发送 `notification` 事件（level: 'error'）
 
@@ -530,9 +564,9 @@ agent.chat('请重载 my-plugin 插件')
 ### 9.1 基础用法
 
 ```javascript
-const { Framework } = require('./src')
+const { Framework } = require('./src');
 
-const framework = new Framework({ debug: true })
+const framework = new Framework({ debug: true });
 
 // 注册插件
 framework.registerPlugin({
@@ -541,49 +575,53 @@ framework.registerPlugin({
     f.registerTool({
       name: 'greet',
       description: '打招呼',
-      execute: async (args) => `Hello, ${args.name}!`
-    })
-  }
-})
+      execute: async (args) => `Hello, ${args.name}!`,
+    });
+  },
+});
 
-await framework.ready()
+await framework.ready();
 
 const agent = framework.createAgent({
   systemPrompt: '你是一个助手',
   model: 'deepseek-chat',
-  apiKey: process.env.API_KEY
-})
+  apiKey: process.env.API_KEY,
+});
 
-const response = await agent.chat('你好')
-console.log(response)
+const response = await agent.chat('你好');
+console.log(response);
 ```
 
 ### 9.2 热重载
 
 ```javascript
 // 重载单个插件
-await framework.reloadPlugin('my-plugin')
+await framework.reloadPlugin('my-plugin');
 
 // 重载所有插件
-await framework.reloadAllPlugins()
+await framework.reloadAllPlugins();
 ```
 
 ## 九、代码规范
 
 ### 9.1 文件命名
+
 - 类文件：`小写-连字符.js`，如 `plugin-base.js`
 - 目录：`小写-连字符`，如 `src/core`
 
 ### 9.2 类命名
+
 - 类名：`大写驼峰`，如 `Framework`, `Agent`
 - 方法名：`小写驼峰`，如 `registerTool`, `loadPlugin`
 
 ### 9.3 变量命名
+
 - 类属性：`小写驼峰`
 - 常量：`全大写+下划线`，如 `DEFAULT_PRIORITY`
 - 私有属性：`_下划线前缀`
 
 ### 9.4 注释
+
 ```javascript
 /**
  * 类描述
@@ -594,13 +632,14 @@ class Framework {
    * @param {string} name - 参数描述
    * @returns {Promise<void>}
    */
-  async loadPlugin(name) { }
+  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`)
@@ -609,10 +648,12 @@ class Framework {
 - [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 服务器

package/cli/bin/foliko.js

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