# 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
