foliko 1.1.0 → 1.1.2

package/README.md

@@ -1,441 +1,441 @@
-# Foliko
-
-简约的插件化 Agent 框架
-
-## 特性
-
-- **插件化架构** - 核心简单，通过插件扩展功能
-- **流式输出** - 支持实时流式输出
-- **多 AI 支持** - 支持 Anthropic、DeepSeek、MiniMax 等
-- **内置工具** - Shell、Python、MCP、文件系统等
-- **技能系统** - 可扩展的 Skill 管理
-- **会话管理** - 支持多会话切换
-- **规则引擎** - 可配置的行为规则
-- **子 Agent** - 支持多子 Agent 分工协作
-- **Ambient Agent** - 持续后台运行，监控事件主动执行
-- **统一通知** - 微信、飞书、Telegram 消息推送
-
-## 安装
-
-```bash
-# 方式一：npm 安装
-npm install -g foliko
-
-# 方式二：Windows 一键脚本安装
-irm https://folikoai.com/install.ps1 | iex
-
-# 方式三：Mac/Linux 一键脚本安装
-curl -fsSL https://folikoai.com/install.sh | bash
-```
-
-## 快速开始
-
-```bash
-# 全局安装后
-foliko chat
-```
-
-## CLI 命令
-
-```bash
-# 聊天模式（使用 .env 中的配置）
-foliko chat
-
-# 指定完整配置
-foliko chat --provider deepseek --model deepseek-chat --base-url https://api.deepseek.com/v1 --api-key sk-xxx
-
-# 只指定 provider（使用 provider 默认 model 和 baseURL）
-foliko chat --provider deepseek --api-key sk-xxx
-
-# 列出所有子Agent配置
-foliko list
-```
-
-### 聊天内命令
-
-在 `foliko chat` 的对话界面中，可以直接输入自然语言来控制框架：
-
-**插件管理**
-
-```
-开启微信插件
-开启飞书插件
-开启telegram插件
-关闭微信插件
-列出所有插件
-重载所有插件
-```
-
-**定时任务**
-
-```
-10分钟后提醒我喝水
-每天早上9点提醒我查看邮件
-设置一个定时任务：2小时后提醒我开会
-列出所有定时任务
-取消定时任务
-```
-
-**会话管理**
-
-```
-创建一个新会话
-列出所有会话
-删除某个会话
-获取会话历史
-```
-
-**Ambient Agent**
-
-```
-查看 Ambient Agent 状态
-创建一个目标：监控新邮件
-暂停 Ambient Agent
-恢复 Ambient Agent
-存储记忆：用户喜欢在早上处理邮件
-检索记忆
-```
-
-**子 Agent**
-
-```
-列出所有子Agent
-调用 backend-specialist 处理任务
-重新加载子Agent配置
-```
-
-**系统操作**
-
-```
-执行 shell 命令：ls -la
-安装 npm 包：lodash
-执行 Python 代码
-查看审计日志
-清除当前会话历史
-```
-
-这些命令会通过 Agent 调用相应的工具来执行。
-
-```
-foliko/
-├── cli/                 # 命令行入口
-│   └── bin/foliko.js    # CLI 入口
-├── src/                 # 核心框架
-│   ├── core/            # 核心组件
-│   ├── capabilities/     # 能力插件
-│   └── executors/       # 执行器
-├── plugins/             # 内置插件
-├── skills/              # 技能目录
-└── examples/            # 示例
-```
-
-## 配置
-
-### 环境变量配置 (.env)
-
-在项目根目录创建 `.env` 文件：
-
-```bash
-# ========== AI Configuration ==========
-# AI Provider: minimax, deepseek, openai, anthropic 等
-FOLIKO_PROVIDER=minimax
-
-# AI Model（如果未设置，使用 provider 默认值）
-# MiniMax: MiniMax-M2.7
-# DeepSeek: deepseek-chat, deepseek-coder 等
-FOLIKO_MODEL=MiniMax-M2.7
-
-# API Base URL（如果未设置，使用 provider 默认值）
-# MiniMax: https://api.minimaxi.com/v1
-# DeepSeek: https://api.deepseek.com/v1
-FOLIKO_BASE_URL=https://api.minimaxi.com/v1
-
-# API Key（通用，如果未设置则尝试 provider 专用 key）
-FOLIKO_API_KEY=sk-your-api-key
-
-# Provider 专用 API Key（可选，如果 FOLIKO_API_KEY 未设置则使用这些）
-DEEPSEEK_API_KEY=sk-your-deepseek-api-key
-MINIMAX_API_KEY=sk-your-minimax-api-key
-
-# ========== Email Configuration ==========
-# SMTP Settings (for sending emails)
-SMTP_HOST=smtp.gmail.com
-SMTP_PORT=587
-SMTP_SECURE=false
-SMTP_USER=your-email@gmail.com
-SMTP_PASS=your-app-password
-
-# IMAP Settings (for reading emails)
-IMAP_HOST=imap.gmail.com
-IMAP_PORT=993
-IMAP_USER=your-email@gmail.com
-IMAP_PASS=your-app-password
-
-# Default sender email address
-FROM_EMAIL=your-email@gmail.com
-
-# ========== Telegram Bot (optional) ==========
-TELEGRAM_BOT_TOKEN=your-telegram-bot-token
-
-# ========== Feishu Bot (optional) ==========
-FEISHU_APP_ID=cli_xxxxxxxxxxx
-FEISHU_APP_SECRET=app_secret
-
-# ========== Web Server (optional) ==========
-# Web 服务端口，默认 8088
-WEB_PORT=3000
-
-# Web 服务主机，默认 127.0.0.1
-WEB_HOST=127.0.0.1
-
-# 公网访问的 base URL（用于生成 webhook URL 等），不设置则使用 host:port，最好部署在docker中可以暴露自定义域名
-WEB_BASE_URL=https://your-domain.com
-
-```
-
-**配置优先级**：命令行参数 > .env配置 > provider默认值
-
-### .agent 目录结构
-
-```
-.agent/
-├── config              # 配置文件
-├── ai.json            # AI 配置
-├── mcp_config.json    # MCP 服务器配置
-├── agents/            # 子Agent配置目录
-├── plugins/           # 用户插件目录
-├── skills/            # 用户技能目录
-└── data/              # 数据目录
-```
-
-### 子 Agent 配置 (.agent/agents/)
-
-在 `.agent/agents/` 目录下放置子 Agent 配置文件，支持 `.js`、`.json`、`.md` 格式：
-
-```
-.agent/agents/
-├── backend-specialist.md
-├── frontend-specialist.md
-└── database-architect.md
-```
-
-#### JSON 格式
-
-```json
-{
-  "name": "backend-specialist",
-  "role": "Backend Specialist",
-  "description": "Expert in backend development",
-  "parentTools": ["read_file", "run_command"]
-}
-```
-
-#### Markdown 格式
-
-````markdown
-# Backend Specialist
-
-```json
-{
-  "name": "backend-specialist",
-  "role": "Backend Specialist",
-  "description": "Expert in backend development",
-  "parentTools": ["read_file", "run_command"]
-}
-```
-````
-
-````
-
-### ai.json 格式
-
-```json
-{
-  "provider": "minimax",
-  "model": "MiniMax-M2.7",
-  "apiKey": "your-api-key",
-  "baseURL": "https://api.minimaxi.com/v1"
-}
-````
-
-### mcp_config.json 格式
-
-```json
-{
-  "mcpServers": {
-    "fetch": {
-      "command": "npx",
-      "args": ["-y", "@modelcontextprotocol/server-fetch"]
-    }
-  }
-}
-```
-
-## 开发插件
-
-### 用户插件（.agent/plugins/）
-
-插件支持两种结构：**文件夹结构**（推荐）和**单文件结构**。
-
-#### 文件夹结构（推荐）
-
-```
-.agent/plugins/my-plugin/
-├── package.json      # 可选，main 字段指定入口
-├── index.js          # 默认入口
-└── node_modules/     # 可选，插件私有依赖
-```
-
-```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;
-    }
-  };
-};
-```
-
-#### 单文件结构（兼容）
-
-```
-.agent/plugins/my-plugin.js
-```
-
-如果同时存在文件夹和同名 `.js` 文件，**文件夹优先**。
-
-**注意**：如果插件需要第三方库（如 `zod`），需要先安装：
-
-1. 创建插件文件/文件夹
-2. 调用 `install` 工具安装依赖
-3. 热重载插件
-
-### 技能开发
-
-在 `.agent/skills/` 下创建技能：
-
-```
-.agent/skills/my-skill/
-└── SKILL.md
-```
-
-SKILL.md 格式：
-
-```markdown
----
-name: my-skill
-description: 技能描述
-allowed-tools: tool1,tool2
----
-
-技能内容...
-```
-
-## 内置工具
-
-### 通用工具
-
-| 工具             | 说明                 |
-| ---------------- | -------------------- |
-| `loadSkill`      | 加载技能             |
-| `list_plugins`   | 列出所有插件         |
-| `list_tools`     | 列出所有工具         |
-| `reload_plugins` | 重载插件             |
-| `shell`          | 执行 Shell 命令      |
-| `powershell`     | 执行 PowerShell 命令 |
-| `python-execute` | 执行 Python 代码     |
-| `python_script`  | 执行 Python 脚本     |
-| `pip_install`    | 安装 Python 包       |
-| `install`        | 安装 npm 包          |
-| `mcp_reload`     | 重载 MCP 服务器      |
-| `audit_query`    | 查询审计日志         |
-
-### 子 Agent 管理工具
-
-| 工具              | 说明                      |
-| ----------------- | ------------------------- |
-| `subagent_list`   | 列出所有子Agent           |
-| `subagent_call`   | 调用指定的子Agent处理任务 |
-| `subagent_reload` | 重新加载子Agent配置       |
-
-### 会话工具
-
-| 工具              | 说明         |
-| ----------------- | ------------ |
-| `session_create`  | 创建会话     |
-| `session_get`     | 获取会话     |
-| `session_list`    | 列出所有会话 |
-| `session_delete`  | 删除会话     |
-| `session_history` | 获取会话历史 |
-
-### 定时任务工具
-
-| 工具              | 说明           |
-| ----------------- | -------------- |
-| `schedule_task`   | 创建定时任务   |
-| `schedule_list`   | 列出定时任务   |
-| `schedule_cancel` | 取消定时任务   |
-| `cron_examples`   | 显示 cron 示例 |
-
-### Ambient Agent 工具
-
-| 工具               | 说明                                 |
-| ------------------ | ------------------------------------ |
-| `ambient_goals`    | 管理目标（列出/创建/更新/删除/激活） |
-| `ambient_status`   | 获取 Ambient Agent 状态              |
-| `ambient_think`    | 触发主动思考                         |
-| `ambient_remember` | 存储/检索记忆                        |
-| `ambient_control`  | 控制循环（暂停/恢复/调整）           |
-
-### 通知事件
-
-消息插件（微信、飞书、Telegram）监听 `notification` 事件推送通知给用户：
-
-```javascript
-{
-  title: '目标完成',
-  message: '目标 "xxx" 已完成',
-  source: 'scheduler',  // 来源
-  level: 'success',    // info | warning | success | error
-  sessionId: 'weixin_xxx'
-}
-```
-
-## 工作目录
-
-CLI 工作目录默认使用执行命令的目录。
-
-- `.agent/` 目录会创建在工作目录下
-- 配置文件、插件、技能等都放在工作目录的 `.agent/` 下
-
-## 许可证
-
-MIT
+# Foliko
+
+简约的插件化 Agent 框架
+
+## 特性
+
+- **插件化架构** - 核心简单，通过插件扩展功能
+- **流式输出** - 支持实时流式输出
+- **多 AI 支持** - 支持 Anthropic、DeepSeek、MiniMax 等
+- **内置工具** - Shell、Python、MCP、文件系统等
+- **技能系统** - 可扩展的 Skill 管理
+- **会话管理** - 支持多会话切换
+- **规则引擎** - 可配置的行为规则
+- **子 Agent** - 支持多子 Agent 分工协作
+- **Ambient Agent** - 持续后台运行，监控事件主动执行
+- **统一通知** - 微信、飞书、Telegram 消息推送
+
+## 安装
+
+```bash
+# 方式一：npm 安装
+npm install -g foliko
+
+# 方式二：Windows 一键脚本安装
+irm https://folikoai.com/install.ps1 | iex
+
+# 方式三：Mac/Linux 一键脚本安装
+curl -fsSL https://folikoai.com/install.sh | bash
+```
+
+## 快速开始
+
+```bash
+# 全局安装后
+foliko chat
+```
+
+## CLI 命令
+
+```bash
+# 聊天模式（使用 .env 中的配置）
+foliko chat
+
+# 指定完整配置
+foliko chat --provider deepseek --model deepseek-chat --base-url https://api.deepseek.com/v1 --api-key sk-xxx
+
+# 只指定 provider（使用 provider 默认 model 和 baseURL）
+foliko chat --provider deepseek --api-key sk-xxx
+
+# 列出所有子Agent配置
+foliko list
+```
+
+### 聊天内命令
+
+在 `foliko chat` 的对话界面中，可以直接输入自然语言来控制框架：
+
+**插件管理**
+
+```
+开启微信插件
+开启飞书插件
+开启telegram插件
+关闭微信插件
+列出所有插件
+重载所有插件
+```
+
+**定时任务**
+
+```
+10分钟后提醒我喝水
+每天早上9点提醒我查看邮件
+设置一个定时任务：2小时后提醒我开会
+列出所有定时任务
+取消定时任务
+```
+
+**会话管理**
+
+```
+创建一个新会话
+列出所有会话
+删除某个会话
+获取会话历史
+```
+
+**Ambient Agent**
+
+```
+查看 Ambient Agent 状态
+创建一个目标：监控新邮件
+暂停 Ambient Agent
+恢复 Ambient Agent
+存储记忆：用户喜欢在早上处理邮件
+检索记忆
+```
+
+**子 Agent**
+
+```
+列出所有子Agent
+调用 backend-specialist 处理任务
+重新加载子Agent配置
+```
+
+**系统操作**
+
+```
+执行 shell 命令：ls -la
+安装 npm 包：lodash
+执行 Python 代码
+查看审计日志
+清除当前会话历史
+```
+
+这些命令会通过 Agent 调用相应的工具来执行。
+
+```
+foliko/
+├── cli/                 # 命令行入口
+│   └── bin/foliko.js    # CLI 入口
+├── src/                 # 核心框架
+│   ├── core/            # 核心组件
+│   ├── capabilities/     # 能力插件
+│   └── executors/       # 执行器
+├── plugins/             # 内置插件
+├── skills/              # 技能目录
+└── examples/            # 示例
+```
+
+## 配置
+
+### 环境变量配置 (.env)
+
+在项目根目录创建 `.env` 文件：
+
+```bash
+# ========== AI Configuration ==========
+# AI Provider: minimax, deepseek, openai, anthropic 等
+FOLIKO_PROVIDER=minimax
+
+# AI Model（如果未设置，使用 provider 默认值）
+# MiniMax: MiniMax-M2.7
+# DeepSeek: deepseek-chat, deepseek-coder 等
+FOLIKO_MODEL=MiniMax-M2.7
+
+# API Base URL（如果未设置，使用 provider 默认值）
+# MiniMax: https://api.minimaxi.com/v1
+# DeepSeek: https://api.deepseek.com/v1
+FOLIKO_BASE_URL=https://api.minimaxi.com/v1
+
+# API Key（通用，如果未设置则尝试 provider 专用 key）
+FOLIKO_API_KEY=sk-your-api-key
+
+# Provider 专用 API Key（可选，如果 FOLIKO_API_KEY 未设置则使用这些）
+DEEPSEEK_API_KEY=sk-your-deepseek-api-key
+MINIMAX_API_KEY=sk-your-minimax-api-key
+
+# ========== Email Configuration ==========
+# SMTP Settings (for sending emails)
+SMTP_HOST=smtp.gmail.com
+SMTP_PORT=587
+SMTP_SECURE=false
+SMTP_USER=your-email@gmail.com
+SMTP_PASS=your-app-password
+
+# IMAP Settings (for reading emails)
+IMAP_HOST=imap.gmail.com
+IMAP_PORT=993
+IMAP_USER=your-email@gmail.com
+IMAP_PASS=your-app-password
+
+# Default sender email address
+FROM_EMAIL=your-email@gmail.com
+
+# ========== Telegram Bot (optional) ==========
+TELEGRAM_BOT_TOKEN=your-telegram-bot-token
+
+# ========== Feishu Bot (optional) ==========
+FEISHU_APP_ID=cli_xxxxxxxxxxx
+FEISHU_APP_SECRET=app_secret
+
+# ========== Web Server (optional) ==========
+# Web 服务端口，默认 8088
+WEB_PORT=3000
+
+# Web 服务主机，默认 127.0.0.1
+WEB_HOST=127.0.0.1
+
+# 公网访问的 base URL（用于生成 webhook URL 等），不设置则使用 host:port，最好部署在docker中可以暴露自定义域名
+WEB_BASE_URL=https://your-domain.com
+
+```
+
+**配置优先级**：命令行参数 > .env配置 > provider默认值
+
+### .agent 目录结构
+
+```
+.agent/
+├── config              # 配置文件
+├── ai.json            # AI 配置
+├── mcp_config.json    # MCP 服务器配置
+├── agents/            # 子Agent配置目录
+├── plugins/           # 用户插件目录
+├── skills/            # 用户技能目录
+└── data/              # 数据目录
+```
+
+### 子 Agent 配置 (.agent/agents/)
+
+在 `.agent/agents/` 目录下放置子 Agent 配置文件，支持 `.js`、`.json`、`.md` 格式：
+
+```
+.agent/agents/
+├── backend-specialist.md
+├── frontend-specialist.md
+└── database-architect.md
+```
+
+#### JSON 格式
+
+```json
+{
+  "name": "backend-specialist",
+  "role": "Backend Specialist",
+  "description": "Expert in backend development",
+  "parentTools": ["read_file", "run_command"]
+}
+```
+
+#### Markdown 格式
+
+````markdown
+# Backend Specialist
+
+```json
+{
+  "name": "backend-specialist",
+  "role": "Backend Specialist",
+  "description": "Expert in backend development",
+  "parentTools": ["read_file", "run_command"]
+}
+```
+````
+
+````
+
+### ai.json 格式
+
+```json
+{
+  "provider": "minimax",
+  "model": "MiniMax-M2.7",
+  "apiKey": "your-api-key",
+  "baseURL": "https://api.minimaxi.com/v1"
+}
+````
+
+### mcp_config.json 格式
+
+```json
+{
+  "mcpServers": {
+    "fetch": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-fetch"]
+    }
+  }
+}
+```
+
+## 开发插件
+
+### 用户插件（.agent/plugins/）
+
+插件支持两种结构：**文件夹结构**（推荐）和**单文件结构**。
+
+#### 文件夹结构（推荐）
+
+```
+.agent/plugins/my-plugin/
+├── package.json      # 可选，main 字段指定入口
+├── index.js          # 默认入口
+└── node_modules/     # 可选，插件私有依赖
+```
+
+```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;
+    }
+  };
+};
+```
+
+#### 单文件结构（兼容）
+
+```
+.agent/plugins/my-plugin.js
+```
+
+如果同时存在文件夹和同名 `.js` 文件，**文件夹优先**。
+
+**注意**：如果插件需要第三方库（如 `zod`），需要先安装：
+
+1. 创建插件文件/文件夹
+2. 调用 `install` 工具安装依赖
+3. 热重载插件
+
+### 技能开发
+
+在 `.agent/skills/` 下创建技能：
+
+```
+.agent/skills/my-skill/
+└── SKILL.md
+```
+
+SKILL.md 格式：
+
+```markdown
+---
+name: my-skill
+description: 技能描述
+allowed-tools: tool1,tool2
+---
+
+技能内容...
+```
+
+## 内置工具
+
+### 通用工具
+
+| 工具             | 说明                 |
+| ---------------- | -------------------- |
+| `loadSkill`      | 加载技能             |
+| `list_plugins`   | 列出所有插件         |
+| `list_tools`     | 列出所有工具         |
+| `reload_plugins` | 重载插件             |
+| `shell`          | 执行 Shell 命令      |
+| `powershell`     | 执行 PowerShell 命令 |
+| `python-execute` | 执行 Python 代码     |
+| `python_script`  | 执行 Python 脚本     |
+| `pip_install`    | 安装 Python 包       |
+| `install`        | 安装 npm 包          |
+| `mcp_reload`     | 重载 MCP 服务器      |
+| `audit_query`    | 查询审计日志         |
+
+### 子 Agent 管理工具
+
+| 工具              | 说明                      |
+| ----------------- | ------------------------- |
+| `subagent_list`   | 列出所有子Agent           |
+| `subagent_call`   | 调用指定的子Agent处理任务 |
+| `subagent_reload` | 重新加载子Agent配置       |
+
+### 会话工具
+
+| 工具              | 说明         |
+| ----------------- | ------------ |
+| `session_create`  | 创建会话     |
+| `session_get`     | 获取会话     |
+| `session_list`    | 列出所有会话 |
+| `session_delete`  | 删除会话     |
+| `session_history` | 获取会话历史 |
+
+### 定时任务工具
+
+| 工具              | 说明           |
+| ----------------- | -------------- |
+| `schedule_task`   | 创建定时任务   |
+| `schedule_list`   | 列出定时任务   |
+| `schedule_cancel` | 取消定时任务   |
+| `cron_examples`   | 显示 cron 示例 |
+
+### Ambient Agent 工具
+
+| 工具               | 说明                                 |
+| ------------------ | ------------------------------------ |
+| `ambient_goals`    | 管理目标（列出/创建/更新/删除/激活） |
+| `ambient_status`   | 获取 Ambient Agent 状态              |
+| `ambient_think`    | 触发主动思考                         |
+| `ambient_remember` | 存储/检索记忆                        |
+| `ambient_control`  | 控制循环（暂停/恢复/调整）           |
+
+### 通知事件
+
+消息插件（微信、飞书、Telegram）监听 `notification` 事件推送通知给用户：
+
+```javascript
+{
+  title: '目标完成',
+  message: '目标 "xxx" 已完成',
+  source: 'scheduler',  // 来源
+  level: 'success',    // info | warning | success | error
+  sessionId: 'weixin_xxx'
+}
+```
+
+## 工作目录
+
+CLI 工作目录默认使用执行命令的目录。
+
+- `.agent/` 目录会创建在工作目录下
+- 配置文件、插件、技能等都放在工作目录的 `.agent/` 下
+
+## 许可证
+
+MIT