mozi-bot 1.1.2 → 1.2.0

package/README.md

@@ -2,17 +2,149 @@
 
 **支持国产大模型和国产通讯软件的智能助手框架**
 
-Mozi 是一个轻量级的 AI 助手框架，专注于国产生态。它提供统一的接口对接多种国产 AI 模型（DeepSeek、Qwen、Kimi 等），支持 OpenAI Function Calling，并能在飞书、钉钉、WebChat 等平台上运行。
+Mozi 是一个轻量级的 AI 助手框架，专注于国产生态。它提供统一的接口对接多种国产 AI 模型（DeepSeek、Qwen、Kimi 等），支持 OpenAI Function Calling，并能在飞书、钉钉等平台上运行。
 
 ## 核心特性
 
 - **多模型支持** — DeepSeek、DashScope (Qwen)、智谱AI、Kimi、阶跃星辰、MiniMax，以及 OpenAI/Anthropic 兼容格式
-- **多平台通道** — WebChat、飞书、钉钉，统一的消息处理接口
+- **多平台通道** — 飞书、钉钉、QQ，统一的消息处理接口
 - **Function Calling** — 原生支持 OpenAI tools/tool_choice 参数
 - **17 内置工具** — 文件读写、Bash 执行、代码搜索、网页获取、图像分析、浏览器自动化等
 - **会话管理** — 上下文压缩、会话持久化、多轮对话
 - **可扩展** — 插件系统、Hook 事件、自定义工具、子 Agent
 
+## 为什么选择 Mozi？
+
+Mozi 的架构设计参考了 [Moltbot](https://github.com/moltbot/moltbot)，但专注于不同的使用场景：
+
+| 特性 | Mozi | Moltbot |
+|------|------|---------|
+| **定位** | 国产生态优先的轻量框架 | 全功能个人 AI 助手 |
+| **代码量** | ~16,000 行 (64 文件) | ~516,000 行 (3,137 文件) |
+| **国产模型** | DeepSeek、Qwen、Kimi 等 7+ 家 | 仅 Anthropic、OpenAI |
+| **国产通讯** | 飞书、钉钉、QQ 原生支持 | WhatsApp、Telegram、Slack 等 |
+| **Node.js 版本** | >= 18 | >= 22 |
+| **适用场景** | 企业内部机器人、国内团队协作 | 个人多设备助手、海外平台集成 |
+
+> **Mozi 用 3% 的代码量实现了核心功能**，专注简洁高效，易于理解和二次开发。
+
+## 学习 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
+```
+
+### 消息处理流程
+
+```mermaid
+flowchart TD
+    Start([用户发送消息]) --> Channel[Channel 接收]
+    Channel --> Gateway[Gateway 路由]
+    Gateway --> LoadCtx[加载会话上下文]
+
+    LoadCtx --> BuildCtx[构建 LLM 请求]
+    BuildCtx --> |系统提示词<br/>历史消息<br/>工具列表| CallLLM[调用 LLM]
+
+    CallLLM --> Check{返回类型?}
+
+    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 成对出现
+
 ## 快速开始
 
 ### 环境要求
@@ -43,7 +175,7 @@ mozi onboard
 - **国产模型** — DeepSeek、智谱AI、DashScope、Kimi、阶跃星辰、MiniMax、ModelScope
 - **自定义 OpenAI 兼容接口** — 支持任意 OpenAI API 格式的服务（如 vLLM、Ollama）
 - **自定义 Anthropic 兼容接口** — 支持任意 Claude API 格式的服务
-- **通讯平台** — 飞书、钉钉
+- **通讯平台** — 飞书、钉钉、QQ
 
 配置文件将保存到 `~/.mozi/config.local.json5`。
 
@@ -144,7 +276,7 @@ npm start -- start --web-only
 
 ## 通讯平台接入
 
-飞书和钉钉都支持两种连接模式：
+飞书、钉钉和 QQ 都支持长连接模式：
 
 | 模式 | 说明 | 适用场景 |
 |------|------|----------|
@@ -155,13 +287,52 @@ npm start -- start --web-only
 
 ### 飞书
 
+#### 1. 创建应用
+
 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. 配置完成，启动服务即可
+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
 {
@@ -175,7 +346,7 @@ npm start -- start --web-only
 }
 ```
 
-> Webhook 模式：将步骤 5 的订阅方式改为 HTTP，配置回调地址为 `http://your-server:3000/webhook/feishu`，并设置 `mode: "webhook"`。
+> Webhook 模式：将步骤 2 的订阅方式改为 HTTP，配置回调地址为 `http://your-server:3000/webhook/feishu`，并设置 `mode: "webhook"`。
 
 ### 钉钉
 
@@ -199,6 +370,64 @@ npm start -- start --web-only
 
 > 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/` 目录下。
@@ -242,6 +471,11 @@ npm start -- start --web-only
     dingtalk: {
       appKey: "xxx",
       appSecret: "xxx"
+    },
+    qq: {
+      appId: "xxx",
+      clientSecret: "xxx",
+      sandbox: false  // 沙箱环境设为 true
     }
   },
 
@@ -320,17 +554,18 @@ mozi logs --level error # 只显示错误日志
 
 ```
 src/
-├── agents/        # Agent 核心（会话、上下文压缩）
+├── agents/        # Agent 核心（消息循环、上下文压缩、会话管理）
 ├── channels/      # 通道适配器（飞书、钉钉）
-├── providers/     # 模型提供商
-├── tools/         # 内置工具
-├── sessions/      # 会话存储与管理
+├── providers/     # 模型提供商（统一接口）
+├── tools/         # 内置工具（文件、Bash、网络等）
+├── sessions/      # 会话存储（内存、文件）
 ├── web/           # WebChat 前端
 ├── config/        # 配置加载
-├── gateway/       # HTTP 网关
+├── gateway/       # HTTP/WebSocket 网关
 ├── cli/           # CLI 命令行工具
+├── hooks/         # Hook 事件系统
 ├── utils/         # 工具函数
-└── types/         # 类型定义
+└── types/         # TypeScript 类型定义
 ```
 
 ## API 使用
@@ -363,21 +598,6 @@ npm run build
 npm test
 ```
 
-## 与 Moltbot 对比
-
-Mozi 的架构设计参考了 [Moltbot](https://github.com/moltbot/moltbot)，但专注于不同的使用场景。
-
-| 特性 | Mozi | Moltbot |
-|------|------|---------|
-| **定位** | 国产生态优先的轻量框架 | 全功能个人 AI 助手 |
-| **代码量** | ~16,000 行 (64 文件) | ~516,000 行 (3,137 文件) |
-| **国产模型** | DeepSeek、Qwen、Kimi 等 7+ 家 | 仅 Anthropic、OpenAI |
-| **国产通讯** | 飞书、钉钉原生支持 | WhatsApp、Telegram、Slack 等 |
-| **Node.js 版本** | >= 18 | >= 22 |
-| **适用场景** | 企业内部机器人、国内团队协作 | 个人多设备助手、海外平台集成 |
-
-> Mozi 用 3% 的代码量实现了核心功能，专注简洁高效，易于理解和二次开发。
-
 ## 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)

package/dist/channels/index.d.ts

@@ -4,6 +4,10 @@
 export * from "./common/index.js";
 export * from "./feishu/index.js";
 export * from "./dingtalk/index.js";
+export * from "./qq/index.js";
+export * from "./wecom/index.js";
 export { FeishuApiClient } from "./feishu/api.js";
 export { DingtalkApiClient } from "./dingtalk/api.js";
+export { QQApiClient } from "./qq/api.js";
+export { WeComApiClient } from "./wecom/api.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/channels/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/channels/index.js

@@ -4,6 +4,10 @@
 export * from "./common/index.js";
 export * from "./feishu/index.js";
 export * from "./dingtalk/index.js";
+export * from "./qq/index.js";
+export * from "./wecom/index.js";
 export { FeishuApiClient } from "./feishu/api.js";
 export { DingtalkApiClient } from "./dingtalk/api.js";
+export { QQApiClient } from "./qq/api.js";
+export { WeComApiClient } from "./wecom/api.js";
 //# sourceMappingURL=index.js.map

package/dist/channels/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AAEpC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/channels/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/channels/qq/api.d.ts

@@ -0,0 +1,37 @@
+/**
+ * QQ 机器人 API 客户端
+ * 基于 QQ 官方机器人 API v2
+ */
+import type { QQConfig } from "../../types/index.js";
+/** 发送消息响应 */
+interface SendMessageResponse {
+    id: string;
+    timestamp: number;
+}
+export declare class QQApiClient {
+    private config;
+    private client;
+    private tokenCache;
+    constructor(config: QQConfig);
+    /** 获取 Access Token */
+    getAccessToken(): Promise<string>;
+    /** 获取带鉴权的请求头 */
+    private getAuthHeaders;
+    /** 获取 WebSocket 网关地址 */
+    getGatewayUrl(): Promise<string>;
+    /** 发送私聊消息 */
+    sendDirectMessage(openId: string, content: string, msgId?: string): Promise<SendMessageResponse>;
+    /** 发送群聊消息 */
+    sendGroupMessage(groupOpenId: string, content: string, msgId?: string): Promise<SendMessageResponse>;
+    /** 发送频道消息 */
+    sendChannelMessage(channelId: string, content: string, msgId?: string): Promise<SendMessageResponse>;
+    /** 发送频道私信 */
+    sendDMMessage(guildId: string, content: string, msgId?: string): Promise<SendMessageResponse>;
+    /** 获取用户信息 */
+    getUserInfo(openId: string): Promise<{
+        id: string;
+        username: string;
+    }>;
+}
+export {};
+//# sourceMappingURL=api.d.ts.map

package/dist/channels/qq/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../../src/channels/qq/api.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAiBrD,aAAa;AACb,UAAU,mBAAmB;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,UAAU,CAA2B;gBAEjC,MAAM,EAAE,QAAQ;IAY5B,sBAAsB;IAChB,cAAc,IAAI,OAAO,CAAC,MAAM,CAAC;IA2BvC,gBAAgB;YACF,cAAc;IAQ5B,wBAAwB;IAClB,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAatC,aAAa;IACP,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC;IAmB/B,aAAa;IACP,gBAAgB,CACpB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC;IAmB/B,aAAa;IACP,kBAAkB,CACtB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC;IAmB/B,aAAa;IACP,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,mBAAmB,CAAC;IAmB/B,aAAa;IACP,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CAK7E"}

package/dist/channels/qq/api.js

@@ -0,0 +1,145 @@
+/**
+ * QQ 机器人 API 客户端
+ * 基于 QQ 官方机器人 API v2
+ */
+import axios from "axios";
+import { getChildLogger } from "../../utils/logger.js";
+const logger = getChildLogger("qq-api");
+/** QQ API 基础地址 */
+const QQ_API_BASE = "https://api.sgroup.qq.com";
+const QQ_SANDBOX_API_BASE = "https://sandbox.api.sgroup.qq.com";
+/** Token 获取地址 */
+const QQ_TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
+export class QQApiClient {
+    config;
+    client;
+    tokenCache = null;
+    constructor(config) {
+        this.config = config;
+        const baseURL = config.sandbox ? QQ_SANDBOX_API_BASE : QQ_API_BASE;
+        this.client = axios.create({
+            baseURL,
+            timeout: 30000,
+            headers: {
+                "Content-Type": "application/json",
+            },
+        });
+    }
+    /** 获取 Access Token */
+    async getAccessToken() {
+        // 检查缓存
+        if (this.tokenCache && this.tokenCache.expiresAt > Date.now() + 60000) {
+            return this.tokenCache.accessToken;
+        }
+        try {
+            const response = await axios.post(QQ_TOKEN_URL, {
+                appId: this.config.appId,
+                clientSecret: this.config.clientSecret,
+            });
+            const { access_token, expires_in } = response.data;
+            this.tokenCache = {
+                accessToken: access_token,
+                expiresAt: Date.now() + expires_in * 1000,
+            };
+            logger.debug("Access token refreshed");
+            return access_token;
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to get access token");
+            throw error;
+        }
+    }
+    /** 获取带鉴权的请求头 */
+    async getAuthHeaders() {
+        const token = await this.getAccessToken();
+        return {
+            Authorization: `QQBot ${token}`,
+            "X-Union-Appid": this.config.appId,
+        };
+    }
+    /** 获取 WebSocket 网关地址 */
+    async getGatewayUrl() {
+        const headers = await this.getAuthHeaders();
+        // 先尝试 /gateway，再尝试 /gateway/bot
+        try {
+            const response = await this.client.get("/gateway", { headers });
+            return response.data.url;
+        }
+        catch (error) {
+            // 如果 /gateway 失败，尝试 /gateway/bot
+            const response = await this.client.get("/gateway/bot", { headers });
+            return response.data.url;
+        }
+    }
+    /** 发送私聊消息 */
+    async sendDirectMessage(openId, content, msgId) {
+        const headers = await this.getAuthHeaders();
+        const data = {
+            content,
+            msg_type: 0,
+        };
+        if (msgId) {
+            data.msg_id = msgId;
+        }
+        const response = await this.client.post(`/v2/users/${openId}/messages`, data, {
+            headers,
+        });
+        logger.debug({ openId, messageId: response.data.id }, "Direct message sent");
+        return response.data;
+    }
+    /** 发送群聊消息 */
+    async sendGroupMessage(groupOpenId, content, msgId) {
+        const headers = await this.getAuthHeaders();
+        const data = {
+            content,
+            msg_type: 0,
+        };
+        if (msgId) {
+            data.msg_id = msgId;
+        }
+        const response = await this.client.post(`/v2/groups/${groupOpenId}/messages`, data, {
+            headers,
+        });
+        logger.debug({ groupOpenId, messageId: response.data.id }, "Group message sent");
+        return response.data;
+    }
+    /** 发送频道消息 */
+    async sendChannelMessage(channelId, content, msgId) {
+        const headers = await this.getAuthHeaders();
+        const data = {
+            content,
+            msg_type: 0,
+        };
+        if (msgId) {
+            data.msg_id = msgId;
+        }
+        const response = await this.client.post(`/channels/${channelId}/messages`, data, {
+            headers,
+        });
+        logger.debug({ channelId, messageId: response.data.id }, "Channel message sent");
+        return response.data;
+    }
+    /** 发送频道私信 */
+    async sendDMMessage(guildId, content, msgId) {
+        const headers = await this.getAuthHeaders();
+        const data = {
+            content,
+            msg_type: 0,
+        };
+        if (msgId) {
+            data.msg_id = msgId;
+        }
+        const response = await this.client.post(`/dms/${guildId}/messages`, data, {
+            headers,
+        });
+        logger.debug({ guildId, messageId: response.data.id }, "DM message sent");
+        return response.data;
+    }
+    /** 获取用户信息 */
+    async getUserInfo(openId) {
+        const headers = await this.getAuthHeaders();
+        const response = await this.client.get(`/users/${openId}`, { headers });
+        return response.data;
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/channels/qq/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../../src/channels/qq/api.ts"],"names":[],"mappings":"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"}

package/dist/channels/qq/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * QQ 通道适配器
+ *
+ * 使用 WebSocket 长连接模式，无需公网部署
+ */
+import type { QQConfig, ChannelMeta, OutboundMessage, SendResult } from "../../types/index.js";
+import { BaseChannelAdapter } from "../common/base.js";
+import { QQApiClient } from "./api.js";
+export declare class QQChannel extends BaseChannelAdapter {
+    readonly id: "qq";
+    readonly meta: ChannelMeta;
+    private config;
+    private apiClient;
+    private wsClient;
+    private initialized;
+    constructor(config: QQConfig);
+    /** 初始化通道 */
+    initialize(): Promise<void>;
+    /** 启动 WebSocket 连接 */
+    private startWebSocket;
+    /** 关闭通道 */
+    shutdown(): Promise<void>;
+    /** 发送消息 */
+    sendMessage(message: OutboundMessage): Promise<SendResult>;
+    /** 发送文本消息 */
+    sendText(chatId: string, text: string, replyToId?: string): Promise<SendResult>;
+    /** 检查通道状态 */
+    isHealthy(): Promise<boolean>;
+    /** 获取 API 客户端 */
+    getApiClient(): QQApiClient;
+    /** 检查是否使用长连接 */
+    isUsingWebSocket(): boolean;
+}
+/** 创建 QQ 通道 */
+export declare function createQQChannel(config: QQConfig): QQChannel;
+//# sourceMappingURL=index.d.ts.map

package/dist/channels/qq/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/channels/qq/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,QAAQ,EACR,WAAW,EACX,eAAe,EACf,UAAU,EACX,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAqBvC,qBAAa,SAAU,SAAQ,kBAAkB;IAC/C,QAAQ,CAAC,EAAE,EAAG,IAAI,CAAU;IAC5B,QAAQ,CAAC,IAAI,cAAW;IAExB,OAAO,CAAC,MAAM,CAAW;IACzB,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,WAAW,CAAS;gBAEhB,MAAM,EAAE,QAAQ;IAO5B,YAAY;IACN,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBjC,sBAAsB;YACR,cAAc;IAa5B,WAAW;IACL,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAW/B,WAAW;IACL,WAAW,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,UAAU,CAAC;IA8BhE,aAAa;IACP,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrF,aAAa;IACP,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAgBnC,iBAAiB;IACjB,YAAY,IAAI,WAAW;IAI3B,gBAAgB;IAChB,gBAAgB,IAAI,OAAO;CAG5B;AAED,eAAe;AACf,wBAAgB,eAAe,CAAC,MAAM,EAAE,QAAQ,GAAG,SAAS,CAE3D"}