Qqchat Plugins

Name: Qqchat Plugins
Rating: 3.5 (1 reviews)
Author: zhqfdn

By zhqfdn 👁 98 views ▲ 0 votes

openclaw-qqchat-plugins

GitHub

Install

npm install
npm

Configuration Example

{
  "plugins": {
    "entries": ["qqchat"],
    "qqchat": {
      "enabled": true,
      "config": {
        "wsUrl": "ws://localhost:3001",
        "accessToken": "your_token_here",
        "groups": {
          "123456789": { "agent": "main" }
        },
        "users": {
          "10001": { "agent": "admin", "vip": true }
        }
      }
    }
  }
}

README

# 🏴‍☠️ QQChat - 来自QC.海贼王团队的 OpenClaw QQ 插件

<p align="center">
  <a href="https://github.com/qcluffy/qqchat/releases">
    <img src="https://img.shields.io/github/v/release/qcluffy/qqchat?display_name=tag" alt="Release">
  </a>
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License: MIT">
  </a>
  <a href="https://docs.openclaw.ai/">
    <img src="https://img.shields.io/badge/OpenClaw-Plugin-blueviolet.svg" alt="OpenClaw">
  </a>
  <a href="https://github.com/botuniverse/onebot-11">
    <img src="https://img.shields.io/badge/Protocol-OneBot_11-yellow.svg" alt="Protocol">
  </a>
  <a href="https://www.typescriptlang.org/">
    <img src="https://img.shields.io/badge/Language-TypeScript-blue.svg" alt="TypeScript">
  </a>
  <img src="https://img.shields.io/badge/QiYun-Tech-Love-red.svg" alt="旗云科技">
</p>

<p align="center">
  <strong>🏴‍☠️ QQChat - 来自海贼王的 QQ 插件</strong>
</p>

<p align="center">
  为 OpenClaw 打造 QQ 机器人解决方案，支持高并发、多会话、智能路由、媒体流处理
</p>

---

## ✨ 核心特性

### 🔥 高性能架构

| 特性 | 描述 |
|------|------|
| **连接池** | 支持多 WebSocket 连接，自动负载均衡 |
| **三级限流** | 全局 → 连接 → API 级别限流，防止触发 NapCat 限制 |
| **消息交织** | 批量消息并行发送，吞吐量提升 50x |
| **熔断器** | 故障自动隔离，快速恢复 |

### 📦 媒体处理

- 🖼️ 图片收发 (支持 URL、fileId、本地路径)
- 🎤 语音消息 (AMR/MP3 格式转换)
- 🎬 视频消息
- 📎 文件上传下载 (群文件/私聊文件)
- 🎨 Markdown 消息
- 🎯 戳一戳、骰子、猜拳等特殊消息

### 🧠 智能路由

```
消息 → 路由器 → Session 管理 → Agent 池 → 响应
           ↓
    ┌──────────────┐
    │ 群组路由     │ → 根据群号分配不同 Agent
    │ 用户路由     │ → VIP/普通用户差异化服务
    │ 关键词路由   │ → 客服/技术/管理等自动分流
    │ AI 意图路由  │ → 基于内容的智能分发
    └──────────────┘
```

### 💾 多级缓存

- **L1**: 内存缓存 (LRU, 1000 items) → 热点数据
- **L2**: 本地磁盘 (5GB LRU) → 媒体文件
- **L3**: Redis (可选) → 跨实例共享

---

## 📊 性能对比

| 指标 | 基础版 | QQChat | 提升 |
|------|--------|--------|------|
| 消息吞吐量 | 1条/秒 | 50条/秒 | **50x** ⚡ |
| 并发连接 | 1 | 20 | **20x** 🚀 |
| 大文件处理 | 内存溢出 | 流式处理 | **安全** 🛡️ |
| 响应延迟 | 500ms | 50ms | **10x** ⚡ |
| 缓存命中 | 0% | 80%+ | **无限** ♾️ |
| 多会话支持 | ❌ | ✅ | **企业级** 🏢 |

---

## 🚦 快速开始

### 安装

```bash
# 方式一: OpenClaw CLI 安装
openclaw plugins install qqchat

# 方式二: 手动安装
git clone https://github.com/qcluffy/qqchat.git
cd qqchat
npm install
npm run build
# 将插件复制到 OpenClaw 扩展目录
```

### 配置

在 `openclaw.json` 中添加:

```json
{
  "plugins": {
    "entries": ["qqchat"],
    "qqchat": {
      "enabled": true,
      "config": {
        "wsUrl": "ws://localhost:3001",
        "accessToken": "your_token_here",
        "groups": {
          "123456789": { "agent": "main" }
        },
        "users": {
          "10001": { "agent": "admin", "vip": true }
        }
      }
    }
  }
}
```

### NapCat 设置

1. 下载 [NapCat](https://github.com/NapNeko/NapCatQQ)
2. 启动 NapCat 并配置 WebSocket
3. 获取 accessToken
4. 完成！🎉

---

## 📖 使用指南

### 基本消息

```javascript
// 发送文本
await sendGroupMsg({ group_id: 123456, message: [{ type: 'text', data: { text: '你好！' } }] });

// 发送图片
await sendGroupMsg({ group_id: 123456, message: [{ type: 'image', data: { file: 'https://xxx.com/img.jpg' } }] });
```

### 媒体操作

```javascript
// 获取图片
const img = await fetchImage({ file: 'xxx.jpg' });

// 上传群文件
await sendGroupFile({ group_id: 123456, file: '/path/to/file.pdf' });

// 获取文件下载链接
const url = await fetchGroupFileUrl({ group_id: 123456, file_id: 'xxx' });
```

### 路由配置

```javascript
// 路由规则示例
const routingRules = {
    groups: {
        '123456789': { agent: 'admin', priority: 'high' },  // 管理群
        '*': { agent: 'main', priority: 'normal' }          // 默认
    },
    users: {
        '10001': { agent: 'admin', vip: true },
        '*': { agent: 'main' }
    },
    keywords: {
        '客服': { agent: 'helper' },
        '技术': { agent: 'tech' }
    }
};
```

---

## 🏗️ 架构设计

```
┌─────────────────────────────────────────────────────────────────────────┐
│                           QQChat Gateway                                │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐            │
│  │  API Gateway │───▶│  Message Bus │◀───│  Media Core  │            │
│  │   (路由/限流) │    │   (事件驱动)  │    │  (流式处理)   │            │
│  └──────────────┘    └──────────────┘    └──────────────┘            │
│         │                   │                   │                      │
│         ▼                   ▼                   ▼                      │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    Connection Pool (连接池)                      │   │
│  │  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐     │   │
│  │  │ Conn 1 │ │ Conn 2 │ │ Conn 3 │ │ Conn 4 │ │ Conn N │     │   │
│  │  └────────┘ └────────┘ └────────┘ └────────┘ └────────┘     │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                    Session Router (会话路由)                      │   │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐            │   │
│  │  │ GroupRouter │  │ UserRouter  │  │ AIRouter   │            │   │
│  │  └─────────────┘  └─────────────┘  └─────────────┘            │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

### 核心模块

| 模块 | 功能 |
|------|------|
| `connection.js` | WebSocket 连接管理、自动重连、心跳检测 |
| `request.js` | API 请求封装、三级限流 |
| `dispatch.js` | 消息分发、路由决策 |
| `media.js` | 媒体文件流式处理、缓存管理 |
| `session.js` | 会话管理、上下文保持 |

---

## 📦 项目结构

```
qqchat/
├── src/
│   ├── core/
│   │   ├── connection.js    # 连接池管理
│   │   ├── request.js       # API 请求 + 限流
│   │   ├── dispatch.js      # 消息分发
│   │   ├── runtime.js       # 运行时
│   │   └── config.js        # 配置管理
│   ├── adapters/
│   │   └── message.js       # 消息格式转换
│   ├── utils/
│   │   ├── media.js         # 媒体处理
│   │   ├── cqcode.js        # CQ码解析
│   │   ├── markdown.js      # Markdown处理
│   │   └── log.js           # 日志
│   └── channel.js           # 入口
├── dist/                    # 编译输出
├── package.json
└── README.md
```

---

## 🔧 开发指南

### 开发模式

```bash
# 安装依赖
npm install

# 监听编译
npm run dev

# 构建
npm run build

# 发布
npm version patch && npm publish
```

### 测试

```bash
# 运行测试
npm test

# 覆盖率
npm run coverage
```

---

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/xxx`)
3. 提交更改 (`git commit -m 'Add xxx'`)
4. 推送分支 (`git push origin feature/xxx`)
5. 创建 Pull Request

---

## 📝 更新日志

### v1.0.0 (2026-03-07)

- 🎉 初始发布
- 🔥 高并发连接池
- 📦 媒体流式处理
- 🧠 智能路由系统
- 💾 多级缓存
- 🛡️ 熔断器保护

---

## 📧 联系方式

- 🐙 GitHub: [https://github.com/qcluffy/qqchat](https://github.com/qcluffy/qqchat)
- 💬 问题反馈: [Issues](https://github.com/qcluffy/qqchat/issues)
- 📧 邮件: [email protected]

---

## 🏴‍☠️ 关于

<p align="center">
  <strong>旗云科技 · 海贼王团队</strong><br>
  乔巴同学 🦌✨<br>
  <sub>让每个 OpenClaw 用户都用上最好的 QQ 插件！</sub>
</p>

---

<p align="center">
  ⭐ Star us on GitHub!<br>
  您的支持是我们前进的动力！
</p>

tools