foliko 1.1.92 → 2.0.0

package/docs/user-manual.md

@@ -1,1391 +0,0 @@
-# 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/                    # 技能目录
-├── .foliko/                    # Foliko 配置目录
-│   ├── 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: './.foliko',
-    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
-// .foliko/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/ 或 .foliko/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）
-- 支持图片和文档接收
-- 媒体文件自动保存到 `.foliko/data/`
-
-**命令：**
-
-| 命令       | 说明         |
-| ---------- | ------------ |
-| `/start`   | 显示帮助信息 |
-| `/clear`   | 清除对话历史 |
-| `/history` | 查看对话状态 |
-
-### 4.16 插件管理扩展
-
-#### 插件启用/禁用
-
-```javascript
-// 启用插件
-await framework.enablePlugin('telegram');
-
-// 禁用插件
-await framework.disablePlugin('telegram');
-```
-
-#### 插件配置更新
-
-```javascript
-// 更新插件配置（会自动保存到 .foliko/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` 会自动保存到 `.foliko/data/plugins-state.json`
-- 重启后自动恢复配置
-
----
-
-## 5. 插件开发
-
-### 5.1 插件存放位置
-
-| 位置              | 说明     | 加载方式             |
-| ----------------- | -------- | -------------------- |
-| `plugins/`        | 内置插件 | 框架初始化时加载     |
-| `.foliko/plugins/` | 用户插件 | Bootstrap 时自动加载 |
-
-### 5.2 开发步骤
-
-1. 创建插件文件 `.foliko/plugins/my-plugin.js`
-2. 实现插件类
-3. 使用 `reload_plugins` 重载插件
-
-### 5.3 完整示例
-
-```javascript
-// .foliko/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
-// .foliko/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/`           | 项目级技能           |
-| `.foliko/skills/`    | Agent 专属技能       |
-| `~/.folikos/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 .foliko 目录结构
-
-```
-.foliko/
-├── config              # 配置文件（key=value 格式）
-├── ai.json            # AI 配置
-├── plugins.json        # 插件配置
-├── mcp_config.json    # MCP 服务器配置
-├── skills/            # Agent 专属技能
-└── plugins/          # 用户插件
-```
-
-### 9.2 AI 配置
-
-```json
-// .foliko/ai.json
-{
-  "provider": "deepseek",
-  "model": "deepseek-chat",
-  "apiKey": "your-api-key",
-  "baseURL": "https://api.deepseek.com"
-}
-```
-
-### 9.3 MCP 配置
-
-```json
-// .foliko/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: './.foliko' });
-
-  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: './.foliko',
-  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: './.foliko' });
-
-  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: './.foliko' });
-
-  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: './.foliko' });
-
-  // 创建主 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. 检查 `.foliko/mcp_config.json` 配置
-2. 确认 MCP 服务器命令已安装
-3. 查看日志中的错误信息
-
-### Q: 如何查看所有可用工具？
-
-调用 `list_tools` 工具，或在系统提示中查看【可用工具】部分。
-
----
-
-## 更新日志
-
-### v1.0.0
-
-- 插件化架构
-- 工具注册系统
-- 技能管理
-- 子 Agent 支持
-- 工具路由
-- 热重载
-
----
-
-## License
-
-MIT