foliko 1.0.60 → 1.0.62

package/SPEC.md

@@ -303,34 +303,41 @@ const response = await agent.chat('你好')
 'plugin:disabled'          // 插件禁用
 'agent:message'             // Agent消息
 'agent:tool-call'          // Agent调用工具
-'agent:tool-result'         // 工具执行结果
-'scheduler:task_created'   // 定时任务创建
-'scheduler:task_cancelled'  // 定时任务取消
-'scheduler:task_completed'  // 定时任务完成
-'scheduler:task_failed'     // 定时任务失败
-'scheduler:reminder'       // 定时提醒触发
+'agent:tool-result'        // 工具执行结果
+'notification'            // 统一通知事件（推送用户）
+'scheduler:reminder'       // 定时提醒触发（业务事件）
 'think:thought_completed'  // 思考完成
-'think:reflection_needs_attention'  // 反思需要关注
+'email:received'           // 收到新邮件
+'webhook:received'        // 收到Webhook请求
 ```
 
-### 事件详情
+### 通知事件 (notification)
 
-#### Scheduler 事件
+统一的通知事件，用于向用户发送通知。消息插件（微信、飞书、Telegram）监听此事件并推送给用户。
 
-| 事件 | 数据 | 说明 |
-|------|------|------|
-| `scheduler:task_created` | `{ taskId, taskName, type, scheduleTime, cronExpression }` | 任务创建时触发 |
-| `scheduler:task_cancelled` | `{ taskId, taskName }` | 任务取消时触发 |
-| `scheduler:task_completed` | `{ taskId, taskName, type }` | 任务完成时触发 |
-| `scheduler:task_failed` | `{ taskId, taskName, error }` | 任务失败时触发 |
-| `scheduler:reminder` | `{ taskId, taskName, message, sessionId, llm }` | 提醒触发时触发 |
+```javascript
+{
+  title: '目标完成',           // 通知标题
+  message: '目标 "xxx" 已完成', // 通知内容
+  source: 'ambient',          // 来源：'scheduler' | 'ambient' | 'email' | 'webhook'
+  level: 'success',        // 级别：'info' | 'warning' | 'success' | 'error'
+  sessionId: 'weixin_xxx', // 会话ID（可选）
+  timestamp: new Date()    // 时间戳
+}
+```
 
-#### Think 事件
+### 业务事件
+
+业务事件用于触发 Ambient Agent 的目标，不直接通知用户。
 
 | 事件 | 数据 | 说明 |
 |------|------|------|
-| `think:thought_completed` | `thought` | 思考完成时触发 |
-| `think:reflection_needs_attention` | `{ thought, reason }` | 反思需要关注时触发 |
+| `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发送消息时 |
 
 ## 六、热重载机制
 
@@ -463,18 +470,64 @@ agent.chat('请重载 my-plugin 插件')
 - 简单提醒（喝水、吃饭）→ 直接显示
 - 查询/分析任务（查看列表、分析数据）→ 启用 LLM
 
-**事件**：
-| 事件 | 时机 |
-|------|------|
-| `scheduler:task_created` | 任务创建时 |
-| `scheduler:task_cancelled` | 任务取消时 |
-| `scheduler:task_completed` | 任务完成时 |
-| `scheduler:task_failed` | 任务失败时 |
-| `scheduler:reminder` | 提醒触发时 |
+**持久化**：
+- 任务自动保存到 `.agent/data/scheduler/tasks.json`
+- 重启后自动恢复 Cron 任务和未执行的一次性任务
+
+**通知**：
+- 任务完成/失败/取消时发送 `notification` 事件
+- 消息插件（微信、飞书）自动推送给用户
+
+## 八、Ambient Agent 插件
+
+### 8.1 Ambient Agent (plugins/ambient-agent-plugin.js)
+
+**功能**：
+- 持续后台运行的智能代理
+- 监控事件并主动执行操作
+- 目标（Goal）管理系统
+- 持久化记忆
+
+**支持的事件**：
+- `tool:result` - 工具执行结果
+- `scheduler:reminder` - 定时提醒
+- `agent:message` - 代理消息
+- `think:thought_completed` - 思考完成
+- `email:received` - 收到邮件
+- `webhook:received` - 收到Webhook
+
+**工具**：
+- `ambient_goals` - 管理目标（列出/创建/更新/删除/激活）
+- `ambient_status` - 获取状态
+- `ambient_think` - 触发主动思考
+- `ambient_remember` - 存储/检索记忆
+- `ambient_control` - 控制循环（暂停/恢复/调整）
+
+**目标结构**：
+```javascript
+{
+  title: '目标标题',
+  description: '目标描述',
+  priority: 5,           // 1-10，数值越高越重要
+  actions: [            // 操作列表
+    { type: 'tool', name: 'tool_name', args: {...} },
+    { type: 'message', content: '消息内容' },
+    { type: 'think', mode: 'reflect', topic: '思考主题' }
+  ],
+  conditions: {          // 激活条件（可选）
+    events: ['email:received'],  // 监听的事件类型
+    toolNames: ['email_read']     // 过滤的工具名称
+  }
+}
+```
+
+**通知**：
+- 目标完成时发送 `notification` 事件（level: 'success'）
+- 目标失败时发送 `notification` 事件（level: 'error'）
 
-## 八、使用示例
+## 九、使用示例
 
-### 8.1 基础用法
+### 9.1 基础用法
 
 ```javascript
 const { Framework } = require('./src')
@@ -505,7 +558,7 @@ const response = await agent.chat('你好')
 console.log(response)
 ```
 
-### 8.2 热重载
+### 9.2 热重载
 
 ```javascript
 // 重载单个插件

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foliko",
-  "version": "1.0.60",
+  "version": "1.0.62",
   "description": "简约的插件化 Agent 框架",
   "main": "src/index.js",
   "bin": {