foliko 1.0.0

package/docs/user-manual.md

@@ -0,0 +1,1205 @@
+# VB-Agent 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. 项目概述
+
+VB-Agent 是一个基于插件的 Agent 框架，具有以下特性：
+
+- **纯 JS 实现** - 无 TypeScript，简单易懂
+- **插件化架构** - 通过插件扩展功能
+- **工具路由** - 智能选择相关工具，减少 token 消耗
+- **多子 Agent 支持** - 支持子 Agent 分工处理
+- **热重载** - 支持动态加载/重载插件
+
+### 项目结构
+
+```
+vb-agent/
+├── 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 地址
+}))
+```
+
+### 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()               // 列出所有工具
+```
+
+### 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/ 目录
+```
+
+---
+
+## 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: vb-agent >= 1.0.0
+metadata:
+  author: Your Name
+  version: 1.0.0
+allowed-tools:
+  - read_file
+  - write_file
+---
+
+# 我的技能
+
+这里是技能的详细说明和使用指南。
+```
+
+### 6.3 使用技能
+
+Agent 可以通过 `loadSkill` 工具加载技能：
+
+```
+用户: 帮我创建一个系统信息插件
+Agent: [调用 loadSkill 技能 vb-agent-dev]
+Agent: [获取插件开发指南后，按照指南创建插件]
+```
+
+### 6.4 内置技能
+
+- **vb-agent-dev** - VB-Agent 插件开发指南
+- **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. 事件系统
+
+VB-Agent 基于 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` | 插件重载 |
+| `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()
+
+// 执行工具
+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