# Foliko 快速参考

## 启动框架

```javascript
const framework = new Framework({ debug: false });
await framework.bootstrap({
  agentDir: './.agent',
  aiConfig: { provider: 'deepseek', model: 'deepseek-chat', apiKey: '...' },
});
```

## 创建 Agent

```javascript
const agent = framework.createAgent({
  name: 'MyAgent',
  systemPrompt: '你是一个有帮助的助手。',
});
```

## 发送消息

```javascript
// 流式
for await (const chunk of agent.chatStream('你好')) {
  if (chunk.type === 'text') process.stdout.write(chunk.text);
}

// 非流式
const result = await agent.chat('你好');
```

## 常用工具

| 工具                   | 用途         |
| ---------------------- | ------------ |
| `list_tools`           | 列出所有工具 |
| `loadSkill`            | 加载技能     |
| `reload_plugins`       | 重载插件     |
| `read_file`            | 读取文件     |
| `write_file`           | 写入文件     |
| `execute_command`      | 执行命令     |
| `schedule_once`        | 定时任务     |
| `think_now`            | 主动思考     |
| `email_send`           | 发送邮件     |
| `email_read`           | 读取邮件     |
| `enable_plugin`        | 启用插件     |
| `disable_plugin`       | 禁用插件     |
| `update_plugin_config` | 更新插件配置 |

## 插件位置

- 内置插件：`plugins/`
- 用户插件：`.agent/plugins/`

## 插件管理

```javascript
// 重启插件
await framework.executeTool('reload_plugins', {});
await framework.executeTool('reload_plugins', { pluginName: 'telegram' });

// 启用/禁用插件
await framework.executeTool('enable_plugin', { name: 'telegram' });
await framework.executeTool('disable_plugin', { name: 'telegram' });

// 更新插件配置（持久化）
await framework.executeTool('update_plugin_config', {
  name: 'telegram',
  config: { allowedChats: ['123'], groupMode: true },
});
await framework.executeTool('get_plugin_config', { name: 'telegram' });
```

## 事件监听

```javascript
// Framework 事件
framework.on('framework:ready', (fw) => {});
framework.on('plugin:loaded', (plugin) => {});
framework.on('tool:registered', (tool) => {});

// Agent 事件
agent.on('status', ({ status }) => {}); // idle/busy/error
agent.on('chunk', (chunk) => {}); // 流式输出
agent.on('tool-call', ({ name, args }) => {});
agent.on('tool-result', ({ name, result }) => {});

// 子 Agent 事件
agent.on('subagent:chat:start', (data) => {});
agent.on('subagent:chat:end', (data) => {});
agent.on('subagent:error', (data) => {});
```

## 子 Agent 注册

```javascript
const { tool } = require('ai')
const { z } = require('zod')

// 方式1：配置 agents 数组自动注册
class MyPlugin extends Plugin {
  agents = [
    {
      name: 'code-agent',
      role: '代码专家',
      tools: {
        compile: tool({
          description: '编译',
          parameters: z.object({ language: z.string(), code: z.string() }),
          execute: async (args) => ({ success: true })
        })
      },
      parentTools: ['read_file', 'write_file']
    }
  ]
}

// 方式2：手动调用
this.registerSubAgent({ name: 'code-agent', role: '代码专家', tools: {...}, parentTools: [...] })
```

## 系统提示中的部分

```
【可用工具】
- tool1: 描述
- tool2: 描述

【可用技能】
- skill1: 描述
- skill2: 描述

【子 Agent 分配规则】
- code-agent: 代码专家

【系统能力】
- ai: AI 对话能力
- storage: 存储
```

## 状态管理

```javascript
agent.getStatus(); // 'idle' | 'busy' | 'error'
agent.resetStatus(); // 重置状态
agent.clearHistory(); // 清空历史
```

## 配置持久化

插件配置自动保存到 `.agent/data/plugins-state.json`

| 文件                              | 用途                |
| --------------------------------- | ------------------- |
| `.agent/data/plugins-state.json`  | 插件启用状态和配置  |
| `.agent/data/storage.json`        | 键值存储数据        |
| `.agent/data/telegram_images/`    | Telegram 接收的图片 |
| `.agent/data/telegram_documents/` | Telegram 接收的文档 |
