mozi-bot 1.1.1 → 1.2.0

package/README.md

@@ -2,47 +2,148 @@
 
 **支持国产大模型和国产通讯软件的智能助手框架**
 
-Mozi 是一个轻量级的 AI 助手框架，专注于国产生态。它提供统一的接口对接多种国产 AI 模型（DeepSeek、Qwen、Kimi 等），支持 OpenAI Function Calling，并能在飞书、钉钉、WebChat 等平台上运行。
+Mozi 是一个轻量级的 AI 助手框架，专注于国产生态。它提供统一的接口对接多种国产 AI 模型（DeepSeek、Qwen、Kimi 等），支持 OpenAI Function Calling，并能在飞书、钉钉等平台上运行。
 
-## 与 Moltbot 对比
+## 核心特性
+
+- **多模型支持** — DeepSeek、DashScope (Qwen)、智谱AI、Kimi、阶跃星辰、MiniMax，以及 OpenAI/Anthropic 兼容格式
+- **多平台通道** — 飞书、钉钉、QQ，统一的消息处理接口
+- **Function Calling** — 原生支持 OpenAI tools/tool_choice 参数
+- **17 内置工具** — 文件读写、Bash 执行、代码搜索、网页获取、图像分析、浏览器自动化等
+- **会话管理** — 上下文压缩、会话持久化、多轮对话
+- **可扩展** — 插件系统、Hook 事件、自定义工具、子 Agent
+
+## 为什么选择 Mozi？
 
-Mozi 的架构设计参考了 [Moltbot](https://github.com/moltbot/moltbot)，但专注于不同的使用场景。
+Mozi 的架构设计参考了 [Moltbot](https://github.com/moltbot/moltbot)，但专注于不同的使用场景：
 
 | 特性 | Mozi | Moltbot |
 |------|------|---------|
 | **定位** | 国产生态优先的轻量框架 | 全功能个人 AI 助手 |
 | **代码量** | ~16,000 行 (64 文件) | ~516,000 行 (3,137 文件) |
-| **国产模型** | ✅ DeepSeek、Qwen、Kimi、阶跃星辰、MiniMax | ❌ 仅 Anthropic、OpenAI |
-| **国产通讯** | ✅ 飞书、钉钉原生支持 | ❌ WhatsApp、Telegram、Slack 等海外平台 |
-| **Node.js 版本** | ≥18 | ≥22 |
-| **资源占用** | 轻量 | 较重（菜单栏应用、语音唤醒等） |
+| **国产模型** | DeepSeek、Qwen、Kimi 等 7+ 家 | 仅 Anthropic、OpenAI |
+| **国产通讯** | 飞书、钉钉、QQ 原生支持 | WhatsApp、Telegram、Slack 等 |
+| **Node.js 版本** | >= 18 | >= 22 |
 | **适用场景** | 企业内部机器人、国内团队协作 | 个人多设备助手、海外平台集成 |
 
 > **Mozi 用 3% 的代码量实现了核心功能**，专注简洁高效，易于理解和二次开发。
 
-### 选择 Mozi 的理由
+## 学习 Agent 原理
+
+如果你想了解 AI Agent 的工作原理，Mozi 是一个很好的学习项目。相比动辄几十万行代码的大型框架，Mozi 只有约 16,000 行代码，但实现了完整的 Agent 核心功能：
+
+- **消息循环** — 用户输入 → LLM 推理 → 工具调用 → 结果反馈
+- **上下文管理** — 会话历史、Token 压缩、多轮对话
+- **工具系统** — 函数定义、参数校验、结果处理
+- **流式输出** — SSE/WebSocket 实时响应
+- **失败重试** — 模型调用失败自动切换备选模型
+
+代码结构清晰，注释完善，适合阅读源码学习 Agent 架构设计。
+
+## 架构设计
+
+```mermaid
+flowchart TB
+    subgraph Input["📥 输入层"]
+        Feishu["🔵 飞书\nWebSocket 长连接"]
+        Dingtalk["🟢 钉钉\nStream 长连接"]
+        QQ["🟣 QQ\nWebSocket 长连接"]
+        WebChat["🟡 WebChat\nHTTP + WebSocket"]
+    end
+
+    subgraph Server["🚀 服务层"]
+        Gateway["Gateway 网关\nHTTP/WebSocket 路由"]
+    end
+
+    subgraph Core["⚙️ 核心层"]
+        Agent["Agent 引擎"]
+
+        subgraph AgentInner[" "]
+            MsgLoop["📨 消息循环\nUser → LLM → Tool → Result"]
+            CtxMgr["📚 上下文管理\n历史压缩 / Token 控制"]
+            Session["💾 会话存储\nMemory / File"]
+        end
+    end
+
+    subgraph External["🔗 外部依赖"]
+        subgraph Providers["模型提供商"]
+            P1["DeepSeek"]
+            P2["DashScope"]
+            P3["智谱AI"]
+            P4["Kimi"]
+            P5["OpenAI"]
+            P6["Anthropic"]
+        end
+
+        subgraph Tools["工具系统"]
+            T1["📁 文件操作\nread/write/edit/glob/grep"]
+            T2["⌨️ Bash 执行\n命令行 / 进程管理"]
+            T3["🌐 网络请求\nsearch/fetch"]
+            T4["🖼️ 多媒体\n图像分析 / 浏览器"]
+            T5["🤖 子 Agent\n复杂任务分解"]
+        end
+    end
+
+    Feishu --> Gateway
+    Dingtalk --> Gateway
+    QQ --> Gateway
+    WebChat --> Gateway
+    Gateway --> Agent
+    Agent --> MsgLoop
+    MsgLoop <--> CtxMgr
+    MsgLoop <--> Session
+    MsgLoop <-->|"调用模型"| Providers
+    MsgLoop <-->|"执行工具"| Tools
+```
 
-- **国产模型一站式支持** — 无需翻墙，直接对接 DeepSeek、通义千问等国产大模型
-- **飞书/钉钉开箱即用** — 原生支持国内主流办公平台，配置简单
-- **轻量快速** — 专注核心功能，无冗余依赖，启动快、资源占用少
-- **低门槛** — 一个 API Key + 三行配置即可运行，适合快速验证和部署
-- **企业友好** — 适合国内企业内网环境，无外部依赖
+### 消息处理流程
 
-### 选择 Moltbot 的理由
+```mermaid
+flowchart TD
+    Start([用户发送消息]) --> Channel[Channel 接收]
+    Channel --> Gateway[Gateway 路由]
+    Gateway --> LoadCtx[加载会话上下文]
 
-- 需要 WhatsApp、Telegram、Discord 等海外平台支持
-- 需要语音唤醒、Live Canvas 等高级交互功能
-- 需要多设备同步、macOS/iOS 深度集成
-- 个人使用场景，设备控制需求
+    LoadCtx --> BuildCtx[构建 LLM 请求]
+    BuildCtx --> |系统提示词<br/>历史消息<br/>工具列表| CallLLM[调用 LLM]
 
-## 核心特性
+    CallLLM --> Check{返回类型?}
 
-- **多模型支持** — DeepSeek、ModelScope (Qwen)、Kimi、阶跃星辰、MiniMax，以及 OpenAI/Anthropic 兼容格式
-- **多平台通道** — WebChat、飞书、钉钉，统一的消息处理接口
-- **Function Calling** — 原生支持 OpenAI tools/tool_choice 参数
-- **15+ 内置工具** — 文件读写、Bash 执行、代码搜索、网页获取等
-- **会话管理** — 上下文压缩、会话持久化、Memory 向量记忆
-- **可扩展** — 插件系统、Hook 事件、自定义工具
+    Check --> |纯文本| Response[返回响应]
+    Check --> |工具调用| ExecTool[执行工具]
+
+    ExecTool --> ToolResult[工具返回结果]
+    ToolResult --> |加入上下文| CallLLM
+
+    Response --> SaveCtx[保存会话]
+    SaveCtx --> Send[Channel 发送]
+    Send --> End([用户收到回复])
+
+    style Start fill:#e1f5fe
+    style End fill:#e8f5e9
+    style CallLLM fill:#fff3e0
+    style ExecTool fill:#fce4ec
+```
+
+### 核心模块
+
+| 模块 | 目录 | 职责 |
+|------|------|------|
+| **Agent** | `src/agents/` | 核心消息循环、上下文压缩、会话管理、模型失败重试 |
+| **Providers** | `src/providers/` | 统一的模型调用接口，支持 OpenAI/Anthropic 兼容格式 |
+| **Tools** | `src/tools/` | 工具注册、参数校验、执行引擎，支持自定义扩展 |
+| **Channels** | `src/channels/` | 通道适配器，统一消息格式，支持长连接和 Webhook |
+| **Sessions** | `src/sessions/` | 会话持久化，支持内存/文件存储，Transcript 记录 |
+| **Gateway** | `src/gateway/` | HTTP/WebSocket 服务，路由分发 |
+
+### 上下文压缩策略
+
+当对话历史超过 Token 限制时，Mozi 使用智能压缩：
+
+1. **保留策略** — 始终保留系统提示词和最近 N 轮对话
+2. **摘要压缩** — 将早期对话压缩为摘要，保留关键信息
+3. **工具结果裁剪** — 截断过长的工具返回结果
+4. **配对验证** — 确保 tool_call 和 tool_result 成对出现
 
 ## 快速开始
 
@@ -54,7 +155,7 @@ Mozi 的架构设计参考了 [Moltbot](https://github.com/moltbot/moltbot)，
 ### 1. 安装
 
 ```bash
-# 一键安装（推荐）
+# 全局安装（推荐）
 npm install -g mozi-bot
 
 # 或者克隆项目开发
@@ -70,38 +171,20 @@ cd mozi && npm install && npm run build
 mozi onboard
 ```
 
-向导支持配置：
+向导会引导你完成以下配置：
 - **国产模型** — DeepSeek、智谱AI、DashScope、Kimi、阶跃星辰、MiniMax、ModelScope
 - **自定义 OpenAI 兼容接口** — 支持任意 OpenAI API 格式的服务（如 vLLM、Ollama）
 - **自定义 Anthropic 兼容接口** — 支持任意 Claude API 格式的服务
-- **通讯平台** — 飞书、钉钉
-
-自定义接口支持配置 API Endpoint、API Key、模型列表（包含上下文窗口、最大 Token 等参数）。
+- **通讯平台** — 飞书、钉钉、QQ
 
 配置文件将保存到 `~/.mozi/config.local.json5`。
 
-或者使用环境变量（简单场景）：
+也可以直接使用环境变量（快速体验）：
 
 ```bash
 export DEEPSEEK_API_KEY=sk-your-key
 ```
 
-也可以手动创建配置文件 `~/.mozi/config.local.json5`：
-
-```json5
-{
-  providers: {
-    deepseek: {
-      apiKey: "sk-your-deepseek-key"
-    }
-  },
-  agent: {
-    defaultProvider: "deepseek",
-    defaultModel: "deepseek-chat"
-  }
-}
-```
-
 ### 3. 启动
 
 ```bash
@@ -117,14 +200,6 @@ npm start -- start --web-only
 
 打开浏览器访问 `http://localhost:3000` 即可开始对话。
 
-### 4. 连接通讯平台（可选）
-
-如需连接飞书或钉钉，在 `mozi onboard` 中配置或手动添加配置后，启动完整服务：
-
-```bash
-mozi start
-```
-
 ## 支持的模型提供商
 
 ### 国产模型
@@ -156,45 +231,13 @@ mozi start
 
 ### 自定义接口
 
-支持配置任意 OpenAI/Anthropic 兼容的 API 接口，详见「模型提供商配置」章节。
-
-## 配置说明
-
-支持 `config.local.json5`、`config.json5`、`config.yaml` 等格式，优先级从高到低。
-
-### 模型提供商配置
-
-所有内置提供商都支持自定义模型配置：
+支持配置任意 OpenAI 或 Anthropic 兼容的 API 接口。通过 `mozi onboard` 向导配置，或手动添加到配置文件：
 
 ```json5
 {
   providers: {
-    // 内置提供商 - 直接配置 apiKey 即可使用预设模型
-    deepseek: {
-      apiKey: "sk-xxx"
-    },
-
-    // 内置提供商 + 自定义模型列表
-    dashscope: {
-      apiKey: "sk-xxx",
-      models: [
-        {
-          id: "qwen-max-latest",
-          name: "通义千问 Max",
-          contextWindow: 32768,
-          maxTokens: 8192
-        },
-        {
-          id: "qwen-plus-latest",
-          name: "通义千问 Plus",
-          contextWindow: 131072,
-          maxTokens: 8192
-        }
-      ]
-    },
-
-    // 自定义 OpenAI 兼容接口
-    "custom-provider": {
+    // 自定义 OpenAI 兼容接口（如 vLLM、LiteLLM 等）
+    "custom-openai": {
       id: "my-provider",
       name: "My Provider",
       baseUrl: "https://api.example.com/v1",
@@ -209,73 +252,230 @@ mozi start
           supportsTools: true
         }
       ]
+    },
+
+    // 自定义 Anthropic 兼容接口
+    "custom-anthropic": {
+      id: "my-anthropic",
+      name: "My Anthropic",
+      baseUrl: "https://api.example.com",
+      apiKey: "xxx",
+      apiVersion: "2023-06-01",
+      models: [
+        {
+          id: "claude-3-5-sonnet",
+          name: "Claude 3.5 Sonnet",
+          contextWindow: 200000,
+          maxTokens: 8192
+        }
+      ]
     }
   }
 }
 ```
 
-### 通讯平台配置
+## 通讯平台接入
 
-飞书和钉钉都支持两种连接模式：
+飞书、钉钉和 QQ 都支持长连接模式：
 
 | 模式 | 说明 | 适用场景 |
 |------|------|----------|
 | **长连接（默认）** | WebSocket/Stream 主动连接，无需公网 IP | 内网部署、本地开发 |
 | Webhook | 被动接收回调，需要公网可访问地址 | 公网服务器部署 |
 
+> **推荐使用长连接模式**：无需公网 IP，无需配置回调地址，启动即可接收消息。
+
+### 飞书
+
+#### 1. 创建应用
+
+1. 登录 [飞书开放平台](https://open.feishu.cn/)，创建企业自建应用
+2. 获取 App ID 和 App Secret
+3. 在应用管理页左侧导航栏，找到「应用能力」，启用「机器人」能力
+
+#### 2. 事件配置
+
+1. 在应用管理页左侧导航栏，找到「事件与回调」，点击进入
+2. 订阅方式选择「长连接」，点击「保存」
+   > ⚠️ 如果提示"未建立长连接"，需要先完成「Mozi 配置」并启动服务（`mozi start`），再回来保存长连接
+3. 点击「添加事件」，在弹出列表中选择「消息与群组」分类，勾选「接收消息」（`im.message.receive_v1`），点击「确定」
+
+#### 3. 权限配置
+
+1. 在应用管理页左侧导航栏，找到「权限管理」，点击进入
+2. 点击「批量导入权限」按钮，将以下 JSON 粘贴到输入框中，点击「导入」：
+
+```json
+{
+  "scopes": {
+    "tenant": [
+      "contact:user.base:readonly",
+      "im:chat",
+      "im:chat:read",
+      "im:chat:update",
+      "im:message",
+      "im:message.group_at_msg:readonly",
+      "im:message.p2p_msg:readonly",
+      "im:message:send_as_bot",
+      "im:resource"
+    ],
+    "user": []
+  }
+}
+```
+
+3. 页面显示「导入成功」即为完成
+
+#### 4. 发布应用
+
+1. 在应用管理页左侧导航栏，找到「版本管理与发布」
+2. 点击右上角「新建版本」，填写版本号与描述
+3. 保存并发布，等待审核通过
+
+#### 5. Mozi 配置
+
 ```json5
 {
   channels: {
-    // 飞书配置
     feishu: {
       appId: "cli_xxx",
       appSecret: "xxx",
-      mode: "websocket"  // "websocket"（默认）或 "webhook"
-    },
+      mode: "websocket"  // 默认值，可省略
+    }
+  }
+}
+```
+
+> Webhook 模式：将步骤 2 的订阅方式改为 HTTP，配置回调地址为 `http://your-server:3000/webhook/feishu`，并设置 `mode: "webhook"`。
 
-    // 钉钉配置
+### 钉钉
+
+1. 登录 [钉钉开放平台](https://open.dingtalk.com/)，创建企业内部应用
+2. 获取 AppKey 和 AppSecret
+3. 添加「机器人」能力
+4. 在机器人配置页面，消息接收模式选择「Stream 模式」
+5. 配置完成，启动服务即可
+
+```json5
+{
+  channels: {
     dingtalk: {
       appKey: "xxx",
       appSecret: "xxx",
-      mode: "stream"  // "stream"（默认）或 "webhook"
+      mode: "stream"  // 默认值，可省略
     }
   }
 }
 ```
 
-> **推荐使用长连接模式**：无需公网 IP，无需配置回调地址，启动即可接收消息。
+> Webhook 模式：将步骤 4 改为 HTTP 模式，配置消息接收地址为 `http://your-server:3000/webhook/dingtalk`，并设置 `mode: "webhook"`。
+
+### QQ
+
+#### 1. 注册并创建应用
+
+1. 访问 [QQ 开放平台](https://q.qq.com/#/apps) 并完成注册
+2. 点击「创建机器人」，填写机器人信息
+   > 个人使用无需企业资质，可选择「指定用户、指定群聊可访问」
+
+#### 2. 获取凭证
+
+1. 点击机器人头像进入管理界面
+2. 在「开发设置」页面获取 App ID 和 App Secret
+   > 管理页面地址：https://q.qq.com/qqbot/#/developer/developer-setting
+
+#### 3. 配置 IP 白名单（重要）
 
-### 完整配置示例
+1. 在「开发设置」页面找到「IP 白名单」
+2. 添加服务器的公网 IP 地址
+   ```bash
+   # 获取服务器公网 IP
+   curl -s ip.sb
+   ```
+   > 未配置白名单会导致连接失败，提示 "接口访问源IP不在白名单"
+
+#### 4. 配置沙箱（可选）
+
+正式上线前，机器人只能在沙箱范围内使用：
+
+1. 访问 [沙箱配置页面](https://q.qq.com/qqbot/#/developer/sandbox)
+2. 添加测试用户或测试群
+
+#### 5. Mozi 配置
 
 ```json5
 {
-  // 模型提供商配置
+  channels: {
+    qq: {
+      appId: "your-app-id",
+      clientSecret: "your-app-secret",
+      sandbox: false  // 沙箱环境设为 true
+    }
+  }
+}
+```
+
+环境变量方式：
+
+```bash
+export QQ_APP_ID=your-app-id
+export QQ_CLIENT_SECRET=your-app-secret
+export QQ_SANDBOX=false  # 可选，默认 false
+```
+
+#### 6. 添加机器人
+
+1. 在机器人管理页面，扫描「添加成员」旁边的二维码
+2. 将机器人添加到聊天界面或拉入群聊
+
+## 配置参考
+
+配置文件支持 `config.local.json5`、`config.json5`、`config.yaml` 等格式，优先级从高到低。存放在 `~/.mozi/` 目录下。
+
+<details>
+<summary>完整配置示例</summary>
+
+```json5
+{
+  // 模型提供商
   providers: {
     deepseek: {
       apiKey: "sk-xxx"
     },
     dashscope: {
-      apiKey: "sk-xxx"  // 阿里云灵积 API Key
+      apiKey: "sk-xxx",
+      // 可选：自定义模型列表（覆盖预设）
+      models: [
+        {
+          id: "qwen-max-latest",
+          name: "通义千问 Max",
+          contextWindow: 32768,
+          maxTokens: 8192
+        }
+      ]
     },
     zhipu: {
-      apiKey: "xxx"  // 智谱 API Key
+      apiKey: "xxx"
     },
     modelscope: {
       apiKey: "ms-xxx"
     }
   },
 
-  // 通讯平台配置（长连接模式，无需公网）
+  // 通讯平台（长连接模式，无需公网）
   channels: {
     feishu: {
       appId: "cli_xxx",
-      appSecret: "xxx",
-      mode: "websocket"  // 默认值，可省略
+      appSecret: "xxx"
     },
     dingtalk: {
       appKey: "xxx",
-      appSecret: "xxx",
-      mode: "stream"  // 默认值，可省略
+      appSecret: "xxx"
+    },
+    qq: {
+      appId: "xxx",
+      clientSecret: "xxx",
+      sandbox: false  // 沙箱环境设为 true
     }
   },
 
@@ -301,6 +501,8 @@ mozi start
 }
 ```
 
+</details>
+
 ## 内置工具
 
 | 类别 | 工具 | 说明 |
@@ -316,119 +518,34 @@ mozi start
 | | `process` | 管理后台进程 |
 | 网络 | `web_search` | 网络搜索 |
 | | `web_fetch` | 获取网页内容 |
-| 其他 | `current_time` | 获取当前时间 |
+| 多媒体 | `image_analyze` | 图像分析（需要视觉模型） |
+| | `browser` | 浏览器自动化（需安装 Playwright） |
+| 系统 | `current_time` | 获取当前时间 |
 | | `calculator` | 数学计算 |
-
-## 平台配置
-
-### 飞书
-
-#### 长连接模式（推荐）
-
-无需公网 IP，适合内网部署和本地开发：
-
-1. 登录 [飞书开放平台](https://open.feishu.cn/)，创建企业自建应用
-2. 获取 App ID 和 App Secret
-3. 启用「机器人」能力
-4. 添加权限：`im:message`、`im:message.group_at_msg`
-5. 进入「事件订阅」，将订阅方式设置为「使用长连接接收事件」
-6. 添加事件：`im.message.receive_v1`（接收消息）
-7. 配置完成，启动服务即可
-
-```json5
-{
-  channels: {
-    feishu: {
-      appId: "cli_xxx",
-      appSecret: "xxx"
-      // mode: "websocket" 是默认值，可省略
-    }
-  }
-}
-```
-
-#### Webhook 模式
-
-需要公网可访问地址：
-
-1. 完成上述步骤 1-4
-2. 配置事件订阅地址：`http://your-server:3000/webhook/feishu`
-3. 订阅事件：`im.message.receive_v1`
-
-```json5
-{
-  channels: {
-    feishu: {
-      appId: "cli_xxx",
-      appSecret: "xxx",
-      mode: "webhook"
-    }
-  }
-}
-```
-
-### 钉钉
-
-#### 长连接模式（推荐）
-
-无需公网 IP，使用官方 Stream SDK：
-
-1. 登录 [钉钉开放平台](https://open.dingtalk.com/)，创建企业内部应用
-2. 获取 AppKey 和 AppSecret
-3. 添加「机器人」能力
-4. 在机器人配置页面，消息接收模式选择「Stream 模式」
-5. 配置完成，启动服务即可
-
-```json5
-{
-  channels: {
-    dingtalk: {
-      appKey: "xxx",
-      appSecret: "xxx"
-      // mode: "stream" 是默认值，可省略
-    }
-  }
-}
-```
-
-#### Webhook 模式
-
-需要公网可访问地址：
-
-1. 完成上述步骤 1-3
-2. 配置消息接收地址：`http://your-server:3000/webhook/dingtalk`
-
-```json5
-{
-  channels: {
-    dingtalk: {
-      appKey: "xxx",
-      appSecret: "xxx",
-      mode: "webhook"
-    }
-  }
-}
-```
+| | `delay` | 延时等待 |
+| Agent | `subagent` | 创建子 Agent 执行复杂任务 |
 
 ## CLI 命令
 
 ```bash
+# 配置
+mozi onboard            # 配置向导（支持国产模型/自定义接口）
+mozi check              # 检查配置
+mozi models             # 列出可用模型
+
 # 启动服务
 mozi start              # 完整服务（含飞书/钉钉）
 mozi start --web-only   # 仅 WebChat
 mozi start --port 8080  # 指定端口
 
-# 查看日志
+# 聊天
+mozi chat               # 命令行聊天
+
+# 日志
 mozi logs               # 查看最新日志（默认 50 行）
 mozi logs -n 100        # 查看最新 100 行
 mozi logs -f            # 实时跟踪日志（类似 tail -f）
 mozi logs --level error # 只显示错误日志
-
-# 其他命令
-mozi onboard            # 配置向导（支持国产模型/自定义接口）
-mozi check              # 检查配置
-mozi models             # 列出可用模型
-mozi chat               # 命令行聊天
 ```
 
 > 日志文件存储在 `~/.mozi/logs/` 目录下，按日期自动轮转。
@@ -437,20 +554,24 @@ mozi chat               # 命令行聊天
 
 ```
 src/
-├── agents/        # Agent 核心（会话、上下文压缩）
+├── agents/        # Agent 核心（消息循环、上下文压缩、会话管理）
 ├── channels/      # 通道适配器（飞书、钉钉）
-├── providers/     # 模型提供商
-├── tools/         # 内置工具
+├── providers/     # 模型提供商（统一接口）
+├── tools/         # 内置工具（文件、Bash、网络等）
+├── sessions/      # 会话存储（内存、文件）
 ├── web/           # WebChat 前端
 ├── config/        # 配置加载
-├── gateway/       # HTTP 网关
-└── types/         # 类型定义
+├── gateway/       # HTTP/WebSocket 网关
+├── cli/           # CLI 命令行工具
+├── hooks/         # Hook 事件系统
+├── utils/         # 工具函数
+└── types/         # TypeScript 类型定义
 ```
 
 ## API 使用
 
 ```typescript
-import { loadConfig, initializeProviders, getProvider } from "mozi";
+import { loadConfig, initializeProviders, getProvider } from "mozi-bot";
 
 const config = loadConfig();
 initializeProviders(config);
@@ -464,23 +585,23 @@ const response = await provider.chat({
 console.log(response.content);
 ```
 
-## Star History
-
-[![Star History Chart](https://api.star-history.com/svg?repos=King-Chau/mozi&type=Date)](https://star-history.com/#King-Chau/mozi&Date)
-
 ## 开发
 
 ```bash
 # 开发模式（自动重启）
 npm run dev -- start --web-only
 
-# 类型检查
-npm run typecheck
-
 # 构建
 npm run build
+
+# 测试
+npm test
 ```
 
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=King-Chau/mozi&type=Date)](https://star-history.com/#King-Chau/mozi&Date)
+
 ## License
 
 Apache 2.0