# qq-bot

**Repository Path**: zhaoStore/qq-bot

## Basic Information

- **Project Name**: qq-bot
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-02
- **Last Updated**: 2026-03-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: demo

## README

# QQ 机器人（C2C & 群聊）- 喜报/悲报生成器

一个基于 `express` 和 `qq-guild-bot` 的 QQ 机器人示例项目，目前仅支持 **C2C 私聊** 和 **群聊 @ 机器人**，可以根据用户输入生成 **喜报 / 悲报** 图片并返回给用户。

## 功能简介

- **私聊消息**
  - 输入 `你好`：机器人会回复「你好，我是小助手」
  - 输入 `/生成喜报 XXX`：生成一张「喜报」图片并返回
  - 输入 `/生成悲报 XXX`：生成一张「悲报」图片并返回

- **群聊 @ 机器人消息**
  - 发送空内容（只 @ 机器人）：返回功能说明
  - 发送 `你好`：机器人会回复「你好，我是小助手」
  - 发送 `/生成喜报 XXX` 或 `/生成悲报 XXX`：生成对应图片并在群里回复

## 环境要求

- Node.js 18+（推荐与当前 LTS 版本保持一致）
- 已在 QQ 频道机器人开放平台创建机器人，并获取：
  - `AppID`
  - `ClientSecret`
  - 并配置好回调 URL（指向本服务的 `/bot-callback` 路由）

## 安装

```bash
pnpm install
# 或
npm install
```

## 配置

1. 复制配置模版：

```bash
cp src/config.example.js src/config.js
```

2. 修改 `src/config.js` 中的以下字段：

- **`appId`**：你的机器人 `AppID`
- **`clientSecret`**：你的机器人 `ClientSecret`
- **`baseURL`**：默认 `https://api.sgroup.qq.com`，一般无需修改
- **`publicBaseUrl`**：静态资源公网基址，例如 `https://your-domain.com`
- **`publicRoutePrefix`**：静态资源在服务里的挂载前缀，例如 `/botPublic`

> `publicUrlPrefix = publicBaseUrl + publicRoutePrefix`，用于机器人发送图片时拼接访问地址。

## 运行与调试

### 开发环境启动

```bash
pnpm dev
# 或
npm run dev
```

默认会在 `0.0.0.0:9010` 启动服务，并暴露：

- 机器人回调接口：`POST /bot-callback`
- 静态资源：挂载在 `config.publicRoutePrefix` 对应的路径下，目录为项目根目录下的 `public` 文件夹。

请将 QQ 频道机器人平台上的回调地址设置为：

```text
https://你的域名/bot-callback
```

（如果是本地测试，可以通过内网穿透工具把 `http://127.0.0.1:9010` 暴露出去）

### 打包与生产启动

如果你已配置好 `build.mjs`，可以使用：

```bash
pnpm build
pnpm start
```

对应的 npm 命令为：

```bash
npm run build
npm start
```

## 回调逻辑概览

- **OP = 13**：平台的签名校验阶段，使用 `tweetnacl` 对 `plain_token` + `event_ts` 做签名并回传
- **OP = 0**：正式事件
  - `C2C_MESSAGE_CREATE`：处理私聊消息（`UserSender`）
  - `GROUP_AT_MESSAGE_CREATE`：处理在群聊中 @ 机器人的消息（`GroupSender`）

所有回调最终都会返回 HTTP `200` 状态码，告知平台已成功处理。

## 目录结构（简要）

```text
qq-bot/
  ├─ src/
  │  ├─ index.js           # 服务入口，express & 回调路由
  │  ├─ config.js          # 配置文件（从 config.example.js 复制修改）
  │  ├─ config.example.js  # 配置示例
  │  ├─ openapi/           # 封装的开放平台调用（UserSender / GroupSender 等）
  │  ├─ services/
  │  │   └─ xibaoService.js  # 喜报/悲报生成逻辑
  │  └─ utils/             # 工具函数
  ├─ public/               # 静态资源目录（生成的图片会放在这里）
  ├─ package.json
  └─ README.md
```

## 开发计划

- 使用nest.js等成熟框架进行重构优化

- 接入大模型



## 许可协议

当前使用 `ISC` 协议，你可以在此基础上修改和二次开发。