# Foliko Framework 用户手册

> 简约的插件化 Agent 框架

## 目录

1. [项目概述](#1-项目概述)
2. [快速开始](#2-快速开始)
3. [核心概念](#3-核心概念)
4. [内置插件](#4-内置插件)
5. [插件开发](#5-插件开发)
6. [技能系统](#6-技能系统)
7. [子 Agent 系统](#7-子-agent-系统)
8. [工具路由](#8-工具路由)
9. [配置说明](#9-配置说明)
10. [事件系统](#10-事件系统)
11. [API 参考](#11-api-参考)

---

## 1. 项目概述

Foliko 是一个基于插件的 Agent 框架，具有以下特性：

- **纯 JS 实现** - 无 TypeScript，简单易懂
- **插件化架构** - 通过插件扩展功能
- **工具路由** - 智能选择相关工具，减少 token 消耗
- **多子 Agent 支持** - 支持子 Agent 分工处理
- **热重载** - 支持动态加载/重载插件

### 项目结构

```
foliko/
├── src/                      # 核心源码
│   ├── core/                 # 核心模块
│   │   ├── framework.js      # 框架容器
│   │   ├── agent.js          # Agent 类
│   │   ├── plugin-base.js    # 插件基类
│   │   ├── plugin-manager.js # 插件管理器
│   │   ├── tool-registry.js  # 工具注册表
│   │   ├── tool-router.js    # 工具路由
│   │   └── agent-chat.js      # 聊天处理器
│   ├── capabilities/          # 能力插件
│   │   └── skill-manager.js   # 技能管理器
│   ├── executors/             # 执行器
│   │   └── mcp-executor.js    # MCP 执行器
│   └── utils/                 # 工具模块
├── plugins/                   # 内置插件
├── skills/                    # 技能目录
├── .agent/                    # Agent 配置目录
│   ├── plugins/              # 用户插件目录
│   ├── skills/               # 用户技能目录
│   └── mcp_config.json       # MCP 配置
├── examples/                  # 示例代码
└── test-chat.js              # 聊天测试
```

---

## 2. 快速开始

### 2.1 安装

```bash
npm install
```

### 2.2 创建聊天机器人

```javascript
const { Framework } = require('./src');

async function main() {
  // 创建框架
  const framework = new Framework({ debug: false });

  // Bootstrap（加载所有配置和插件）
  await framework.bootstrap({
    agentDir: './.agent',
    aiConfig: {
      provider: 'deepseek',
      model: 'deepseek-chat',
      apiKey: process.env.DEEPSEEK_API_KEY,
    },
  });

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

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

main().catch(console.error);
```

### 2.3 运行测试聊天

```bash
node test-chat.js
```

---

## 3. 核心概念

### 3.1 Framework（框架）

框架是整个系统的容器，管理插件和工具注册。

```javascript
const framework = new Framework({ debug: false });

// 加载插件
await framework.loadPlugin(myPlugin);

// 创建 Agent
const agent = framework.createAgent(config);

// 执行工具
const result = await framework.executeTool('tool_name', { arg: 'value' });
```

### 3.2 Agent（智能体）

Agent 负责对话和推理，拥有独立的工具集和系统提示。

```javascript
const agent = framework.createAgent({
  name: 'MyAgent', // Agent 名称
  systemPrompt: '你是一个...', // 系统提示
  sharedPrompt: '{{WORK_DIR}}', // 共享提示（支持占位符）
  metadata: {
    // 元数据
    projectName: 'MyProject',
  },
  enableToolRouting: true, // 启用工具路由（默认 true）
});

// 发送消息（非流式）
const result = await agent.chat('你好');

// 发送消息（流式）
for await (const chunk of agent.chatStream('你好')) {
  if (chunk.type === 'text') process.stdout.write(chunk.text);
}
```

### 3.3 Plugin（插件）

插件是功能扩展的基本单元。

```javascript
const { Plugin } = require('./src/core/plugin-base');

class MyPlugin extends Plugin {
  constructor() {
    super();
    this.name = 'my-plugin';
    this.version = '1.0.0';
    this.description = '我的插件';
    this.priority = 10; // 加载优先级（数字越小越先加载）
  }

  install(framework) {
    this._framework = framework;
    // 安装时调用
    return this;
  }

  start(framework) {
    // 注册工具
    framework.registerTool({
      name: 'my_tool',
      description: '我的工具',
      inputSchema: {
        /* zod schema */
      },
      execute: async (args) => {
        return { result: 'done' };
      },
    });
    return this;
  }

  reload(framework) {
    // 热重载时调用
    return this;
  }

  uninstall(framework) {
    // 卸载时调用
    return this;
  }
}

module.exports = MyPlugin;
```

### 3.4 免引入写法

支持更简洁的插件写法：

```javascript
// 直接导出函数
module.exports = function (Plugin) {
  return class extends Plugin {
    constructor() {
      super();
      this.name = 'my-plugin';
      this.description = '我的插件';
    }

    start(framework) {
      framework.registerTool({
        name: 'hello',
        execute: async (args) => `Hello, ${args.name}!`,
      });
      return this;
    }
  };
};
```

---

## 4. 内置插件

### 4.1 AI 插件 (ai-plugin)

提供 AI 对话能力。

```javascript
await framework.loadPlugin(
  new AIPlugin({
    provider: 'deepseek', // AI 提供商
    model: 'deepseek-chat', // 模型名称
    apiKey: 'your-api-key', // API Key
    baseURL: 'https://api.deepseek.com', // 可选：自定义 API 地址
  })
);
```

**热重载支持：** 更新 AI 配置后执行 `reload_plugins('ai')`，所有已有 Agent 会自动使用新的 LLM 设置。

```javascript
// 1. 更新 LLM 配置
await framework.executeTool('update_plugin_config', {
  name: 'ai',
  config: {
    model: 'gpt-4o',
    apiKey: 'new-key',
  },
});

// 2. 热重载 AI 插件
await framework.executeTool('reload_plugins', { pluginName: 'ai' });
```

### 4.2 存储插件 (storage-plugin)

键值对存储，支持 JSON 文件持久化。

```javascript
// 注册的工具
storage_set(key, value); // 存储值
storage_get(key); // 获取值
storage_delete(key); // 删除值
storage_list(); // 列出所有键
storage_clear(); // 清空存储
```

### 4.3 工具插件 (tools-plugin)

内置工具管理功能。

```javascript
// 注册的工具
reload_plugins(pluginName?) // 热重载插件（可选指定插件名）
list_plugins()              // 列出已加载插件
list_tools()                // 列出所有工具
enable_plugin(name)         // 启用指定插件
disable_plugin(name)        // 禁用指定插件
get_plugin_config(name)     // 获取插件当前配置
update_plugin_config(name, config)  // 更新插件配置（持久化）
```

### 4.4 文件系统插件 (file-system-plugin)

文件系统操作。

```javascript
// 注册的工具
read_directory(path)       // 读取目录
create_directory(path)      // 创建目录
read_file(path)            // 读取文件
write_file(path, content)   // 写入文件
delete_file(path)           // 删除文件
modify_file(path, oldText, newText)  // 修改文件
search_file(pattern, path?)  // 搜索文件
execute_command(cmd)         // 执行命令
```

### 4.5 Shell 执行器 (shell-executor-plugin)

执行 Shell 命令。

```javascript
// 注册的工具
shell(command); // 执行 Shell 命令
powershell(command); // 执行 PowerShell（仅 Windows）
```

### 4.6 Python 执行器 (python-executor-plugin)

执行 Python 代码。

```javascript
// 注册的工具
python(code); // 执行 Python 代码
python_script(scriptPath); // 执行 Python 脚本
pip_install(package); // 安装 Python 包
```

### 4.7 MCP 执行器 (mcp-executor)

连接 MCP 服务器。

```json
// .agent/mcp_config.json
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}
```

```javascript
// 注册的工具
mcp_call(server, tool, args); // 调用 MCP 工具
mcp_list_servers(); // 列出已连接的 MCP 服务器
```

### 4.8 会话插件 (session-plugin)

多会话管理。

```javascript
// 注册的工具
session_create(sessionId?)  // 创建会话
session_get(sessionId)       // 获取会话
session_list()                // 列出所有会话
session_delete(sessionId)     // 删除会话
session_history(sessionId)     // 获取会话历史
session_stats()                // 获取会话统计
```

### 4.9 审计插件 (audit-plugin)

记录操作日志。

```javascript
// 注册的工具
audit_query(options); // 查询日志
audit_stats(); // 获取统计
audit_export(format); // 导出日志
```

### 4.10 规则插件 (rules-plugin)

规则引擎，控制工具调用权限。

```javascript
// 注册的工具
rules_list(); // 列出规则
rules_add(rule); // 添加规则
rules_remove(ruleId); // 移除规则
rules_test(input); // 测试规则匹配
rules_stats(); // 获取统计
```

### 4.11 调度插件 (scheduler-plugin)

定时任务。

```javascript
// 注册的工具
schedule_cron(expression, task); // 创建 Cron 任务
schedule_once(datetime, task); // 创建一次性任务
schedule_list(); // 列出所有任务
schedule_cancel(taskId); // 取消任务
schedule_now(taskId); // 立即执行任务
```

### 4.12 子 Agent 插件 (subagent-plugin)

多 Agent 分工，支持独立工具集。

**方式1：配置 `this.agents = []` 自动注册**

```javascript
const { Plugin } = require('../src/core/plugin-base');
const { tool } = require('ai');
const { z } = require('zod');

class MyPlugin extends Plugin {
  name = 'my-plugin';

  // 配置式注册子Agent，插件启动时自动创建
  agents = [
    {
      name: 'code-agent',
      role: '代码专家',
      description: '处理代码开发任务',
      tools: {
        compile: tool({
          description: '编译代码',
          parameters: z.object({
            language: z.string(),
            code: z.string(),
          }),
          execute: async (args) => ({ success: true }),
        }),
      },
      parentTools: ['read_file', 'write_file'], // 从父Agent继承的工具
    },
  ];
}
```

**方式2：手动调用 `this.registerSubAgent()`**

```javascript
const { Plugin } = require('../src/core/plugin-base');
const { tool } = require('ai');
const { z } = require('zod');

class MyPlugin extends Plugin {
  start(framework) {
    // 手动注册子Agent
    this.registerSubAgent({
      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'],
    });
  }
}
```

**子Agent配置说明：**

| 字段          | 类型   | 说明                                            |
| ------------- | ------ | ----------------------------------------------- |
| `name`        | string | 子Agent名称（唯一标识）                         |
| `role`        | string | 角色描述                                        |
| `description` | string | 详细描述（供主Agent智能选择）                   |
| `tools`       | object | 自定义工具 `{ name: toolDef }`，只属于此子Agent |
| `parentTools` | array  | 从父Agent继承的工具名称列表                     |

### 4.13 技能管理器 (skill-manager)

技能加载和管理。

```javascript
// 注册的工具
loadSkill(skill); // 加载指定技能

// 技能存放在 skills/ 或 .agent/skills/ 目录
```

### 4.14 Email 插件 (email-plugin)

邮件收发插件，支持 SMTP 发送和 IMAP 读取。

```javascript
// 配置
await framework.loadPlugin(
  new EmailPlugin({
    smtp_host: 'smtp.gmail.com',
    smtp_port: 587,
    smtp_secure: false,
    smtp_user: 'your-email@gmail.com',
    smtp_pass: 'your-app-password',
    imap_host: 'imap.gmail.com',
    imap_port: 993,
    imap_user: 'your-email@gmail.com',
    imap_pass: 'your-app-password',
    from_email: 'your-email@gmail.com',
  })
);

// 或通过工具配置
email_configure({
  smtp_host: 'smtp.gmail.com',
  smtp_user: 'your-email@gmail.com',
  smtp_pass: 'your-app-password',
});
```

**注册的工具：**

| 工具                 | 说明                 |
| -------------------- | -------------------- |
| `email_send`         | 发送电子邮件         |
| `email_read`         | 读取电子邮件（IMAP） |
| `email_unread_count` | 获取未读邮件数量     |
| `email_mark_read`    | 标记邮件为已读       |
| `email_configure`    | 配置邮箱连接参数     |

```javascript
// 发送邮件
email_send({
  to: 'recipient@example.com',
  subject: '主题',
  body: '正文内容',
  cc: 'cc@example.com', // 可选
  isHtml: false,
});

// 读取邮件
email_read({
  box: 'INBOX',
  limit: 10,
  unreadOnly: false,
});

// 获取未读数量
email_unread_count({ box: 'INBOX' });

// 标记为已读
email_mark_read({ messageId: '12345' });
```

### 4.15 Telegram 插件 (telegram-plugin)

Telegram 对话插件，绑定主 Agent 进行持续对话。

```javascript
// 配置
await framework.loadPlugin(
  new TelegramPlugin({
    botToken: 'YOUR_BOT_TOKEN', // 必需
    allowedChats: ['123456789'], // 可选：允许的聊天ID
    groupMode: false, // 可选：是否启用群组模式
    prefix: '/', // 可选：命令前缀
    systemPrompt: '你是一个有帮助的AI助手。',
  })
);
```

**功能特性：**

- 支持私聊和群组模式
- MarkdownV2 格式支持（自动转义特殊字符）
- 持续对话（基于 sessionId）
- 支持图片和文档接收
- 媒体文件自动保存到 `.agent/data/`

**命令：**

| 命令       | 说明         |
| ---------- | ------------ |
| `/start`   | 显示帮助信息 |
| `/clear`   | 清除对话历史 |
| `/history` | 查看对话状态 |

### 4.16 插件管理扩展

#### 插件启用/禁用

```javascript
// 启用插件
await framework.enablePlugin('telegram');

// 禁用插件
await framework.disablePlugin('telegram');
```

#### 插件配置更新

```javascript
// 更新插件配置（会自动保存到 .agent/data/plugins-state.json）
await framework.executeTool('update_plugin_config', {
  name: 'telegram',
  config: {
    allowedChats: ['123456789', '987654321'],
    groupMode: true,
  },
});

// 获取插件当前配置
await framework.executeTool('get_plugin_config', {
  name: 'telegram',
});
```

**配置持久化：**

- 插件的 `enabled` 状态和 `config` 会自动保存到 `.agent/data/plugins-state.json`
- 重启后自动恢复配置

---

## 5. 插件开发

### 5.1 插件存放位置

| 位置              | 说明     | 加载方式             |
| ----------------- | -------- | -------------------- |
| `plugins/`        | 内置插件 | 框架初始化时加载     |
| `.agent/plugins/` | 用户插件 | Bootstrap 时自动加载 |

### 5.2 开发步骤

1. 创建插件文件 `.agent/plugins/my-plugin.js`
2. 实现插件类
3. 使用 `reload_plugins` 重载插件

### 5.3 完整示例

```javascript
// .agent/plugins/system-info.js
const { Plugin } = require('../../src/core/plugin-base');
const os = require('os');
const { z } = require('zod');

class SystemInfoPlugin extends Plugin {
  constructor() {
    super();
    this.name = 'system-info';
    this.version = '1.0.0';
    this.description = '系统信息查看插件';
    this.priority = 5;
  }

  start(framework) {
    framework.registerTool({
      name: 'get_system_info',
      description: '获取系统基本信息',
      inputSchema: z.object({}),
      execute: async () => {
        return {
          platform: os.platform(),
          hostname: os.hostname(),
          arch: os.arch(),
          homedir: os.homedir(),
          cwd: process.cwd(),
        };
      },
    });

    framework.registerTool({
      name: 'get_memory_usage',
      description: '获取内存使用情况',
      inputSchema: z.object({}),
      execute: async () => {
        const total = os.totalmem();
        const free = os.freemem();
        const used = total - free;
        return {
          total: `${(total / 1024 / 1024 / 1024).toFixed(2)} GB`,
          used: `${(used / 1024 / 1024 / 1024).toFixed(2)} GB`,
          free: `${(free / 1024 / 1024 / 1024).toFixed(2)} GB`,
          percent: `${((used / total) * 100).toFixed(1)}%`,
        };
      },
    });

    return this;
  }
}

module.exports = SystemInfoPlugin;
```

### 5.4 免引入写法

```javascript
// .agent/plugins/my-plugin.js
const { z } = require('zod');

module.exports = function (Plugin) {
  return class extends Plugin {
    constructor() {
      super();
      this.name = 'my-plugin';
      this.description = '我的插件';
    }

    start(framework) {
      framework.registerTool({
        name: 'hello',
        description: '打招呼',
        inputSchema: z.object({
          name: z.string().describe('姓名'),
        }),
        execute: async (args) => {
          return `Hello, ${args.name}!`;
        },
      });
      return this;
    }
  };
};
```

---

## 6. 技能系统

### 6.1 技能目录

| 位置                | 说明                 |
| ------------------- | -------------------- |
| `skills/`           | 项目级技能           |
| `.agent/skills/`    | Agent 专属技能       |
| `~/.agents/skills/` | 全局技能（未来支持） |

### 6.2 技能格式

技能是 Markdown 文件，包含 frontmatter 元数据。

```markdown
---
name: my-skill
description: 我的技能描述
license: MIT
compatibility: foliko >= 1.0.0
metadata:
  author: Your Name
  version: 1.0.0
allowed-tools:
  - read_file
  - write_file
---

# 我的技能

这里是技能的详细说明和使用指南。
```

### 6.3 使用技能

Agent 可以通过 `loadSkill` 工具加载技能：

```
用户: 帮我创建一个系统信息插件
Agent: [调用 loadSkill 技能 foliko-dev]
Agent: [获取插件开发指南后，按照指南创建插件]
```

### 6.4 内置技能

- **foliko-dev** - Foliko 插件开发指南
- **api-patterns** - API 设计模式
- **app-builder** - 应用程序构建
- **architecture** - 架构设计
- ...（共 39+ 技能）

---

## 7. 子 Agent 系统

### 7.1 概念

子 Agent 是主 Agent 的专家分身，专门处理特定领域任务。

```
主 Agent
├── 代码专家 (code-agent)
│   ├── read_file
│   ├── write_file
│   └── execute_command
├── 数据专家 (data-agent)
│   ├── python
│   └── execute_command
└── ...
```

### 7.2 使用方式

```javascript
// 创建子 Agent
await framework.loadPlugin(
  new SubAgentPlugin({
    name: 'code-agent',
    role: '代码专家',
    description: '负责代码开发、调试和重构',
    tools: ['read_file', 'write_file', 'execute_command'],
  })
);

// 主 Agent 自动获得 code-agent 工具
// 使用: "帮我写一个排序算法"
// Agent 自动调用 code-agent 工具
```

### 7.3 系统提示中的子 Agent

```markdown
【子 Agent 分配规则 - 必须遵守】

1. 每个子Agent有固定的专业领域，必须委托给对应的专家：

- code-agent: 代码专家
- data-agent: 数据专家

2. 你需要对任务进行拆分，传递给对应的子Agent执行。

【可委托的子 Agent】

- code-agent: 代码专家
- data-agent: 数据专家

使用相应子Agent名称的工具将任务委托给相应子代理。
```

---

## 8. 工具路由

### 8.1 问题

44 个工具全部传给 LLM 会：

- 消耗大量 token
- 降低推理速度
- 增加成本

### 8.2 解决方案

智能工具路由：根据用户输入选择相关工具。

```javascript
const agent = framework.createAgent({
  name: 'MyAgent',
  enableToolRouting: true, // 默认启用
});
```

### 8.3 意图分类

| 意图              | 关键词           | 工具                         |
| ----------------- | ---------------- | ---------------------------- |
| file_operation    | 文件、读取、写入 | read_file, write_file, ...   |
| code_development  | 代码、开发、插件 | loadSkill, read_file, ...    |
| system_info       | 系统、信息、内存 | get_system_info, ...         |
| plugin_management | 插件、重载       | reload_plugins, list_plugins |

### 8.4 工作原理

```
用户: "查看系统信息"
  ↓
意图分析: system_info (匹配度 100%)
  ↓
工具选择: get_system_info, get_memory_usage, get_cpu_info, ...
  ↓
传给 LLM: 仅 7 个工具（而非全部 44 个）
```

---

## 9. 配置说明

### 9.1 .agent 目录结构

```
.agent/
├── config              # 配置文件（key=value 格式）
├── ai.json            # AI 配置
├── plugins.json        # 插件配置
├── mcp_config.json    # MCP 服务器配置
├── skills/            # Agent 专属技能
└── plugins/          # 用户插件
```

### 9.2 AI 配置

```json
// .agent/ai.json
{
  "provider": "deepseek",
  "model": "deepseek-chat",
  "apiKey": "your-api-key",
  "baseURL": "https://api.deepseek.com"
}
```

### 9.3 MCP 配置

```json
// .agent/mcp_config.json
{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}
```

---

## 10. 事件系统

Foliko 基于 EventEmitter，提供完整的事件系统。

### 10.1 事件基础

```javascript
// 监听事件
agent.on('eventName', (data) => {
  console.log('事件触发:', data);
});

// 监听一次
agent.once('eventName', (data) => {
  console.log('只触发一次');
});

// 移除监听
agent.off('eventName', handler);

// 触发事件
agent.emit('eventName', { key: 'value' });
```

### 10.2 Framework 事件

| 事件名                | 参数        | 说明         |
| --------------------- | ----------- | ------------ |
| `framework:ready`     | `framework` | 框架就绪     |
| `framework:destroyed` | -           | 框架销毁     |
| `plugin:registered`   | `plugin`    | 插件注册     |
| `plugin:loaded`       | `plugin`    | 插件加载完成 |
| `plugin:unloaded`     | `plugin`    | 插件卸载     |
| `plugin:reloaded`     | `plugin`    | 插件重载     |
| `plugin:enabled`      | `plugin`    | 插件启用     |
| `plugin:disabled`     | `plugin`    | 插件禁用     |
| `tool:registered`     | `tool`      | 工具注册     |
| `agent:created`       | `agent`     | Agent 创建   |

```javascript
framework.on('framework:ready', (fw) => {
  console.log('框架就绪');
});

framework.on('plugin:loaded', (plugin) => {
  console.log('插件已加载:', plugin.name);
});

framework.on('tool:registered', (tool) => {
  console.log('工具已注册:', tool.name);
});
```

### 10.3 Agent 事件

| 事件名        | 参数                     | 说明                            |
| ------------- | ------------------------ | ------------------------------- |
| `status`      | `{ status }`             | 状态变化：`idle`/`busy`/`error` |
| `message`     | `msg`                    | 非流式消息响应                  |
| `chunk`       | `chunk`                  | 流式响应片段                    |
| `tool-call`   | `{ name, args }`         | 工具调用                        |
| `tool-result` | `{ name, args, result }` | 工具结果                        |
| `error`       | `{ error }`              | 错误发生                        |
| `destroyed`   | -                        | Agent 销毁                      |

```javascript
// 状态监听
agent.on('status', ({ status }) => {
  console.log('Agent 状态:', status);
});

// 流式输出
agent.on('chunk', (chunk) => {
  if (chunk.type === 'text') {
    process.stdout.write(chunk.text);
  }
});

// 工具调用
agent.on('tool-call', ({ name, args }) => {
  console.log('调用工具:', name, args);
});

agent.on('tool-result', ({ name, result }) => {
  console.log('工具结果:', name, result);
});

// 错误处理
agent.on('error', ({ error }) => {
  console.error('Agent 错误:', error);
});
```

### 10.4 子 Agent 事件

| 事件名                | 参数                                              | 说明              |
| --------------------- | ------------------------------------------------- | ----------------- |
| `subagent:chat:start` | `{ parentAgent, subAgent, subAgentName, task }`   | 子 Agent 开始处理 |
| `subagent:chat:end`   | `{ parentAgent, subAgent, subAgentName, result }` | 子 Agent 完成     |
| `subagent:chunk`      | `{ parentAgent, subAgent, subAgentName, chunk }`  | 子 Agent 流式输出 |
| `subagent:error`      | `{ parentAgent, subAgent, subAgentName, error }`  | 子 Agent 错误     |

```javascript
// 监听所有子 Agent 事件
agent.on('subagent:chat:start', ({ subAgentName, task }) => {
  console.log(`子 Agent ${subAgentName} 开始处理:`, task);
});

agent.on('subagent:chat:end', ({ subAgentName, result }) => {
  console.log(`子 Agent ${subAgentName} 完成:`, result);
});

agent.on('subagent:chunk', ({ subAgentName, chunk }) => {
  console.log(`子 Agent ${subAgentName} 输出:`, chunk);
});

agent.on('subagent:error', ({ subAgentName, error }) => {
  console.error(`子 Agent ${subAgentName} 错误:`, error);
});
```

### 10.5 工具执行事件

| 事件名        | 参数                     | 说明         |
| ------------- | ------------------------ | ------------ |
| `tool:call`   | `{ name, args }`         | 工具被调用   |
| `tool:result` | `{ name, args, result }` | 工具执行结果 |
| `tool:error`  | `{ name, args, error }`  | 工具执行错误 |

```javascript
// 通过 toolRegistry 监听
framework.toolRegistry.on('tool:call', ({ name, args }) => {
  console.log('工具调用:', name, args);
});

framework.toolRegistry.on('tool:result', ({ name, result }) => {
  console.log('工具结果:', name, result);
});

framework.toolRegistry.on('tool:error', ({ name, error }) => {
  console.error('工具错误:', name, error);
});
```

### 10.6 完整示例

```javascript
const { Framework } = require('./src');

async function main() {
  const framework = new Framework({ debug: false });
  await framework.bootstrap({ agentDir: './.agent' });

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

  // 监听所有事件
  framework.on('*', (event, ...args) => {
    console.log(`[Framework Event] ${event}`);
  });

  agent.on('status', ({ status }) => {
    console.log(`[Agent Status] ${status}`);
  });

  agent.on('tool-call', ({ name, args }) => {
    console.log(`[Tool Call] ${name}:`, args);
  });

  agent.on('subagent:*', (event, data) => {
    console.log(`[SubAgent Event] ${event}:`, data);
  });

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

main();
```

### 10.7 Chat Stream Chunk 类型

`chatStream` 返回的 chunk 对象有以下类型：

| type          | 字段                 | 说明     |
| ------------- | -------------------- | -------- |
| `text`        | `text`               | 文本片段 |
| `tool-call`   | `toolName`, `args`   | 工具调用 |
| `tool-result` | `toolName`, `result` | 工具结果 |
| `error`       | `error`              | 错误信息 |

```javascript
for await (const chunk of agent.chatStream('帮我读取文件')) {
  switch (chunk.type) {
    case 'text':
      process.stdout.write(chunk.text);
      break;
    case 'tool-call':
      console.log('调用:', chunk.toolName, chunk.args);
      break;
    case 'tool-result':
      console.log('结果:', chunk.toolName, chunk.result);
      break;
    case 'error':
      console.error('错误:', chunk.error);
      break;
  }
}
```

---

## 11. API 参考

### 11.1 Framework

```javascript
// 创建框架
const framework = new Framework({ debug: false });

// Bootstrap（加载所有配置和插件）
await framework.bootstrap({
  agentDir: './.agent',
  aiConfig: { provider, model, apiKey },
});

// 创建 Agent
const agent = framework.createAgent({
  name,
  systemPrompt,
  sharedPrompt,
  metadata,
  enableToolRouting,
});

// 注册/加载插件
await framework.loadPlugin(plugin);
await framework.reloadPlugin(name);
await framework.reloadAllPlugins();

// 启用/禁用插件
await framework.enablePlugin(name);
await framework.disablePlugin(name);

// 更新插件配置
framework.updatePluginConfig(name, config);

// 执行工具
const result = await framework.executeTool(name, args);

// 获取插件/工具
const plugin = framework.pluginManager.get(name);
const tools = framework.getTools();

// 销毁
await framework.destroy();
```

### 11.2 Agent

```javascript
// 创建（在 framework.createAgent() 后）
const agent = framework.createAgent(config);

// 发送消息
const result = await agent.chat(message);
for await (const chunk of agent.chatStream(message)) {
  // chunk.type: 'text' | 'tool-call' | 'tool-result' | 'error'
}

// 注册工具
agent.registerTool(toolDef);

// 子 Agent
agent.registerSubAgent(name, agent, role, goal);
agent.getSubAgents();

// 元数据
agent.setMetadata(key, value);
agent.getMetadata(key);

// 状态
agent.getStatus(); // 'idle' | 'busy' | 'error'
agent.resetStatus(); // 重置状态

// 清空历史
agent.clearHistory();

// 销毁
agent.destroy();
```

### 11.3 Plugin

```javascript
class MyPlugin extends Plugin {
  constructor() {
    super();
    this.name = 'my-plugin';
    this.version = '1.0.0';
    this.description = '我的插件';
    this.priority = 10;
  }

  install(framework) {
    /* 安装 */ return this;
  }
  start(framework) {
    /* 启动 */ return this;
  }
  reload(framework) {
    /* 重载 */ return this;
  }
  uninstall(framework) {
    /* 卸载 */ return this;
  }
}
```

### 11.4 工具定义

```javascript
{
  name: 'tool_name',
  description: '工具描述',
  inputSchema: z.object({
    arg1: z.string().describe('参数1'),
    arg2: z.number().optional()
  }),
  execute: async (args, framework) => {
    // args: { arg1: '...', arg2: 123 }
    // framework: Framework 实例
    return { success: true, result: '...' }
  }
}
```

---

## 示例代码

### 基础对话

```javascript
const { Framework } = require('./src');

async function main() {
  const framework = new Framework();
  await framework.bootstrap({ agentDir: './.agent' });

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

  const result = await agent.chat('你好');
  console.log(result.message);
}

main();
```

### 带工具的对话

```javascript
const { Framework } = require('./src');

async function main() {
  const framework = new Framework();
  await framework.bootstrap({ agentDir: './.agent' });

  const agent = framework.createAgent({
    systemPrompt: '你是一个有帮助的助手，擅长文件操作。',
  });

  for await (const chunk of agent.chatStream('帮我读取 package.json')) {
    if (chunk.type === 'text') process.stdout.write(chunk.text);
    if (chunk.type === 'tool-call') console.log('调用工具:', chunk.toolName);
    if (chunk.type === 'tool-result') console.log('结果:', chunk.result);
  }
}

main();
```

### 子 Agent 分工

```javascript
const { Framework } = require('./src');
const { SubAgentPlugin } = require('./plugins/subagent-plugin');

async function main() {
  const framework = new Framework();
  await framework.bootstrap({ agentDir: './.agent' });

  // 创建主 Agent
  const mainAgent = framework.createAgent({
    systemPrompt: '你是主 Agent，负责协调子 Agent 工作。',
  });

  // 添加子 Agent
  await framework.loadPlugin(
    new SubAgentPlugin({
      name: 'code-agent',
      role: '代码专家',
      description: '负责代码开发',
      tools: {
        compile: {
          description: '编译代码',
          inputSchema: z.object({ language: z.string(), code: z.string() }),
          execute: async (args) => ({ success: true }),
        },
      },
      parentTools: ['read_file', 'write_file'],
    })
  );

  // 对话
  const result = await mainAgent.chat('帮我创建一个 Hello World 程序');
  console.log(result.message);
}

main();
```

---

## 常见问题

### Q: 如何调试插件？

```javascript
const framework = new Framework({ debug: true });
```

### Q: MCP 连接失败怎么办？

1. 检查 `.agent/mcp_config.json` 配置
2. 确认 MCP 服务器命令已安装
3. 查看日志中的错误信息

### Q: 如何查看所有可用工具？

调用 `list_tools` 工具，或在系统提示中查看【可用工具】部分。

---

## 更新日志

### v1.0.0

- 插件化架构
- 工具注册系统
- 技能管理
- 子 Agent 支持
- 工具路由
- 热重载

---

## License

MIT
