@karinjs/adapter-qqbot 1.3.1 → 2.1.0

package/README.md

@@ -1,870 +1,173 @@
 # @karinjs/adapter-qqbot
 
-QQ机器人适配器插件，为 Karin 框架提供 QQ 机器人支持。
-
-## 功能特性
-
-- ✅ 支持 QQ 群聊消息收发
-- ✅ 支持 QQ 好友消息收发
-- ✅ 支持 QQ 频道消息收发
-- ✅ 支持 WebSocket 和 Webhook 两种连接方式
-- ✅ 支持多种 Markdown 模板（原生、图文模板、纯文模板）
-- ✅ 支持沙盒环境和正式环境
-- ✅ 完整的 TypeScript 类型定义
-- ✅ 自动消息签名验证
+Karin 的 QQ 官方机器人适配器。
 
 ## 安装
 
-### 使用 pnpm（推荐）
-
-```bash
-pnpm add @karinjs/adapter-qqbot -w
-```
-
-### 使用 npm
-
 ```bash
-npm install @karinjs/adapter-qqbot
+pnpm add @karinjs/adapter-qqbot
 ```
 
-### 使用 yarn
-
-```bash
-yarn add @karinjs/adapter-qqbot
-```
-
-## 快速开始
-
-### 前置要求
-
-- 已安装并配置好 [Karin 框架](https://github.com/KarinJS/Karin)
-- Node.js >= 16
-- 有QQ开放平台的机器人应用
-
-### 5分钟快速配置
-
-1. **安装插件**
-   ```bash
-   pnpm add @karinjs/adapter-qqbot -w
-   ```
+要求：Node.js >= 22、Karin >= 1.15
 
-2. **获取机器人信息**
-   - 访问 [QQ开放平台](https://bot.q.qq.com/)
-   - 创建机器人应用，获取 AppID 和 Secret
+## 配置
 
-3. **创建配置**
-   ```json
-   [
-     {
-       "appId": "你的AppID",
-       "secret": "你的Secret",
-       "event": { "type": 1 }
-     }
-   ]
-   ```
+首次启动没有 QQBot 配置时，使用**任意已连接的机器人**或在**控制台中**发送 `#QQ登录` 完成扫码授权。
 
-4. **配置回调地址**
-   - 在QQ开放平台设置**统一**回调地址：`https://你的域名/qqbot/webhook`
-   - **必须使用HTTPS协议**，端口必须为443（默认HTTPS端口）
-   - 该地址接收所有事件：群聊、C2C私聊、频道消息等
-
-5. **启动服务**
-   ```bash
-   npm start
-   ```
-
-完成！现在可以邀请机器人到群聊测试了。
-
-## 详细配置指南
-
-### 第一步：获取机器人凭证
-
-1. 访问 [QQ开放平台](https://bot.q.qq.com/)
-2. 登录并创建新的机器人应用
-3. 获取 `AppID` 和 `Secret`
-4. 记录这些信息，后续配置需要用到
-
-### 第二步：创建配置文件
-
-配置文件位置：`@karinjs/@karinjs-adapter-qqbot/config/config.json`
-
-如果文件不存在，插件会自动创建一个空的配置文件。
-
-### 第三步：基本配置
-
-#### 最简配置示例
+也可以访问 Karin WebUI 可视化编辑 或者 手动编辑：`@karinjs-adapter-qqbot/config/config.json`。
 
 ```json
 [
   {
-    "appId": "你的机器人AppID",
-    "secret": "你的机器人Secret"
-  }
-]
-```
-
-#### 完整配置示例
-
-```json
-[
-  {
-    "appId": "你的机器人AppID",
-    "secret": "你的机器人Secret",
-    "prodApi": "https://api.sgroup.qq.com",
-    "sandboxApi": "https://sandbox.api.sgroup.qq.com",
-    "tokenApi": "",
+    "name": "我的机器人",
+    "appId": "1234567890",
+    "secret": "your-secret",
     "sandbox": false,
     "qqEnable": true,
     "guildEnable": true,
     "guildMode": 0,
-    "exclude": [],
-    "regex": [
-      {
-        "reg": "^/",
-        "rep": "#"
-      }
-    ],
-    "markdown": {
-      "mode": 0,
-      "id": "",
-      "kv": [
-        "text_start",
-        "img_dec", 
-        "img_url",
-        "text_end"
-      ]
-    },
-    "event": {
-      "type": 1,
-      "wsUrl": "",
-      "wsToken": ""
-    }
+    "keyboard": { "enable": true },
+    "event": { "type": 2 }
   }
 ]
 ```
 
-### 第四步：选择事件接收方式
-
-#### 方式一：Webhook（推荐）
-
-**适用场景：** 有公网IP或域名的服务器
-
-1. 在配置文件中设置：
-```json
-{
-  "event": {
-    "type": 1
-  }
-}
-```
-
-2. 在QQ开放平台配置回调地址：
-   - 回调地址格式：`https://你的域名/qqbot/webhook`
-   - 例如：`https://your-domain.com/qqbot/webhook`
-   - **⚠️ 重要限制：**
-     - 必须使用 **HTTPS** 协议
-     - 端口必须为 **443**（标准HTTPS端口）
-     - 不支持自定义端口（如:8080、:3000等）
-   
-> **重要说明：** 这是**统一的回调地址**，QQ开放平台会将所有配置的事件类型（群聊、C2C私聊、频道消息等）都发送到这个地址。您不需要为不同的消息类型配置不同的回调地址。
-
-#### 方式二：WebSocket
-
-**适用场景：** 内网环境，需要通过中转服务连接
-
-1. 在配置文件中设置：
-```json
-{
-  "event": {
-    "type": 2,
-    "wsUrl": "wss://your-websocket-server/ws",
-    "wsToken": "你的ws认证token"
-  }
-}
-```
-
-### 第五步：反向代理配置（重要）
-
-> **为什么需要反向代理？**
-> 
-> QQ开放平台对Webhook回调地址有严格要求：
-> - **必须使用HTTPS协议**（不支持HTTP）
-> - **端口必须为443**（标准HTTPS端口，不支持自定义端口）
-> - 必须有有效的SSL证书
-> 
-> 如果你的Karin服务运行在：
-> - 内网服务器（如家用电脑、局域网服务器）
-> - 云服务器的内网端口（如3000端口）
-> - Docker容器内部
-> 
-> 就需要通过反向代理将内网服务暴露到公网的443端口，并配置SSL证书。
-
-#### 反向代理的目标
-
-**反向代理要代理的地址：** `http://127.0.0.1:3000/qqbot/webhook`
-
-这是Karin QQBot适配器监听的统一webhook接收地址，用于接收**所有类型**的QQ机器人事件，包括：
-- 群聊消息（GROUP_AT_MESSAGE_CREATE）
-- C2C私聊消息（C2C_MESSAGE_CREATE）
-- 频道消息（GUILD_MESSAGE_CREATE）
-- 频道私信（DIRECT_MESSAGE_CREATE）
-- 其他机器人事件
-
-QQ开放平台会将所有配置的事件都发送到这个统一的回调地址，然后由适配器内部根据事件类型进行分发处理。
-
-#### 方案一：Nginx 反向代理（推荐）
-
-**1. 安装Nginx**
-```bash
-# Ubuntu/Debian
-sudo apt update && sudo apt install nginx
-
-# CentOS/RHEL
-sudo yum install nginx
-```
-
-**2. 创建配置文件**
-
-创建 `/etc/nginx/sites-available/karin-qqbot`：
-
-```nginx
-server {
-    listen 80;
-    server_name your-domain.com;  # 替换为你的域名或公网IP
-    
-    # QQ机器人webhook接收地址
-    location /qqbot/webhook {
-        # 代理到本地Karin服务
-        proxy_pass http://127.0.0.1:3000/qqbot/webhook;
-        
-        # 必要的代理头设置
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        
-        # 关键配置：保持原始请求体用于签名验证
-        proxy_buffering off;
-        proxy_request_buffering off;
-        proxy_read_timeout 300;
-        proxy_connect_timeout 300;
-        proxy_send_timeout 300;
-    }
-    
-    # 可选：为Karin的其他功能添加代理
-    location /karin/ {
-        proxy_pass http://127.0.0.1:3000/;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-    }
-}
-```
-
-**获取免费SSL证书（Let's Encrypt）：**
-
-```bash
-# 1. 安装certbot
-sudo apt update
-sudo apt install certbot python3-certbot-nginx
-
-# 2. 获取SSL证书（自动配置Nginx）
-sudo certbot --nginx -d your-domain.com
-
-# 3. 测试自动续期
-sudo certbot renew --dry-run
-
-# 4. 设置自动续期（可选）
-sudo crontab -e
-# 添加以下行：
-# 0 12 * * * /usr/bin/certbot renew --quiet
-```
-
-**手动配置SSL证书：**
-
-如果你有其他SSL证书提供商的证书，按以下格式配置：
-
-```nginx
-ssl_certificate /path/to/your/certificate.crt;      # 证书文件
-ssl_certificate_key /path/to/your/private.key;     # 私钥文件
-```
-
-**3. 启用配置**
-```bash
-# 创建软链接启用站点
-sudo ln -s /etc/nginx/sites-available/karin-qqbot /etc/nginx/sites-enabled/
-
-# 测试配置文件语法
-sudo nginx -t
+- `event.type`: `0` 关闭、`1` Webhook、`2` WebSocket（默认）。
+- `guildMode`: `0` 公域，只收 @ 消息；`1` 私域，接收全部频道消息。
 
-# 重载配置
-sudo systemctl reload nginx
+## 按钮
 
-# 确保Nginx开机自启
-sudo systemctl enable nginx
-```
-
-**4. 配置HTTPS（必需）**
-
-> **⚠️ 重要：** QQ开放平台**强制要求**使用HTTPS协议和443端口，以下配置是**必需的**，不是可选的。
-
-```nginx
-server {
-    listen 443 ssl http2;
-    server_name your-domain.com;
-    
-    # SSL证书配置（使用Let's Encrypt免费证书）
-    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
-    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
-    
-    # 如果没有SSL证书，可以使用以下命令获取Let's Encrypt免费证书：
-    # sudo apt install certbot python3-certbot-nginx
-    # sudo certbot --nginx -d your-domain.com
-    
-    # SSL优化配置
-    ssl_protocols TLSv1.2 TLSv1.3;
-    ssl_ciphers EECDH+AESGCM:EDH+AESGCM;
-    ssl_prefer_server_ciphers on;
-    
-    location /qqbot/webhook {
-        proxy_pass http://127.0.0.1:3000/qqbot/webhook;
-        proxy_set_header Host $host;
-        proxy_set_header X-Real-IP $remote_addr;
-        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
-        proxy_set_header X-Forwarded-Proto $scheme;
-        
-        # 保持原始请求体
-        proxy_buffering off;
-        proxy_request_buffering off;
-    }
-}
-
-# HTTP自动跳转HTTPS（推荐配置）
-server {
-    listen 80;
-    server_name your-domain.com;
-    return 301 https://$server_name$request_uri;
-}
-```
-
-#### 方案二：宝塔面板配置
+按钮一般和 Markdown 一起发送，常用有三种：
 
-**1. 创建网站**
-- 域名：填写你的域名
-- 根目录：可以是任意目录（不会用到）
+- 跳转按钮：点击后打开 `link`。
+- 指令按钮：点击后把 `data` 发送成一条普通消息。
+- 回调按钮：点击后不会在聊天框发消息，但适配器会下发一条 Karin 消息事件，消息内容就是 `data`。
 
-**2. 配置SSL证书（必需）**
-- 进入网站设置 → SSL
-- 申请Let's Encrypt免费证书或上传自有证书
-- 开启"强制HTTPS"
+下面这个示例先发送一组按钮，然后分别接住“指令按钮”和“回调按钮”的点击结果：
 
-**3. 添加反向代理**
+```ts
+import karin, { segment } from 'node-karin'
 
-有两种配置方式，选择其一：
+export const buttonDemo = karin.command(/^按钮示例$/, async (e) => {
+  await e.reply([
+    segment.markdown('#### 按钮示例\n请选择一个操作：'),
+    segment.button([
+      { text: '打开文档', link: 'https://bot.q.qq.com/wiki/' },
+      { text: '发送指令', data: '按钮示例 帮助', enter: true },
+      { text: '回调确认', callback: true, data: '按钮示例 确认' },
+    ]),
+  ])
+})
 
-**方式一：代理整个域名到Karin服务**
-- **代理名称：** Karin Service
-- **目标URL：** `http://127.0.0.1:3000`
-- **发送域名：** `$host`
-- **代理目录：** `/`
+export const buttonHelp = karin.command(/^按钮示例 帮助$/, async (e) => {
+  await e.reply('这是指令按钮发送出来的消息。')
+})
 
-**方式二：只代理webhook路径（推荐）**
-- **代理名称：** QQBot Webhook
-- **目标URL：** `http://127.0.0.1:3000/qqbot/webhook`
-- **发送域名：** `$host`
-- **代理目录：** `/qqbot/webhook`
-
-> **推荐使用方式一**，这样整个域名都会指向您的Karin服务，QQ开放平台访问 `https://your-domain.com/qqbot/webhook` 时会被代理到 `http://127.0.0.1:3000/qqbot/webhook`。
-
-**4. 高级设置**
-添加以下配置到反向代理的配置文件中：
-```nginx
-proxy_buffering off;
-proxy_request_buffering off;
+export const buttonConfirm = karin.command(/^按钮示例 确认$/, async (e) => {
+  await e.reply(`收到回调按钮：${e.msg}`)
+})
 ```
 
-> **重要提醒：** 确保网站已启用HTTPS并强制跳转，QQ开放平台只接受HTTPS协议的回调地址。
+如果你希望回复自动带上一组按钮，可以把按钮单独注册出来。下面这个分页示例会根据当前消息生成“上一页 / 下一页”：
 
-#### 方案三：Caddy 服务器
+```ts
+import karin, { segment } from 'node-karin'
 
-**1. 安装Caddy**
-```bash
-# 参考官方文档安装Caddy
-```
+const getPage = (msg = '') => Number(msg.match(/^菜单(?:\s+(\d+))?$/)?.[1] || 1)
 
-**2. 创建Caddyfile**
-```caddy
-your-domain.com {
-    reverse_proxy /qqbot/webhook/* 127.0.0.1:3000
-    
-    # 自动HTTPS
-    tls {
-        on_demand
-    }
-}
-```
-
-#### 方案四：Cloudflare Tunnel（内网穿透）
+export const menuDemo = karin.command(/^菜单(?:\s+\d+)?$/, async (e) => {
+  const page = getPage(e.msg)
+  await e.reply(segment.markdown(`#### 菜单\n当前第 ${page} 页`))
+})
 
-**适用场景：** 没有公网IP，通过Cloudflare暴露服务
+export const menuKeyboard = karin.button(/^菜单(?:\s+\d+)?$/, (next, args) => {
+  const page = getPage(args?.e?.msg)
 
-**1. 安装cloudflared**
-```bash
-# 下载并安装cloudflared
-wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
-sudo dpkg -i cloudflared-linux-amd64.deb
-```
-
-**2. 登录Cloudflare**
-```bash
-cloudflared tunnel login
-```
-
-**3. 创建隧道**
-```bash
-cloudflared tunnel create karin-qqbot
-```
-
-**4. 配置DNS**
-```bash
-cloudflared tunnel route dns karin-qqbot your-subdomain.your-domain.com
-```
-
-**5. 运行隧道**
-```bash
-cloudflared tunnel run --url http://localhost:3000 karin-qqbot
-```
-
-#### 方案五：frp 内网穿透
-
-**适用场景：** 使用自建或第三方frp服务
-
-**客户端配置 (frpc.ini):**
-```ini
-[common]
-server_addr = your-frp-server.com
-server_port = 7000
-token = your_token
-
-[karin-qqbot]
-type = http
-local_ip = 127.0.0.1
-local_port = 3000
-custom_domains = your-domain.com
-```
-
-### 第六步：QQ开放平台回调地址要求
-
-#### 官方限制条件
-
-QQ开放平台对Webhook回调地址有以下**强制要求**：
-
-| 要求项 | 限制 | 说明 |
-|--------|------|------|
-| **协议** | 必须HTTPS | 不支持HTTP协议 |
-| **端口** | 必须443 | 不支持自定义端口（如:8080、:3000等） |
-| **SSL证书** | 必须有效 | 需要被浏览器信任的证书 |
-| **域名** | 必须有域名 | 不支持IP地址直接访问 |
-| **响应时间** | 3秒内 | 超时会重试 |
-
-#### 正确的回调地址格式
-
-✅ **正确格式：**
-- `https://your-domain.com/qqbot/webhook`
-- `https://bot.your-company.com/qqbot/webhook`
-
-❌ **错误格式：**
-- `http://your-domain.com/qqbot/webhook` （不支持HTTP）
-- `https://your-domain.com:3000/qqbot/webhook` （不支持自定义端口）
-- `https://123.456.789.10/qqbot/webhook` （不支持IP地址）
-
-### 第七步：域名和防火墙配置
-
-#### 域名解析配置
-
-确保域名正确解析到你的服务器：
-```bash
-# 检查域名解析
-nslookup your-domain.com
-dig your-domain.com
-```
-
-#### 防火墙配置
-
-**Ubuntu/Debian (ufw):**
-```bash
-# 开放HTTP和HTTPS端口
-sudo ufw allow 80
-sudo ufw allow 443
-
-# 如果直接暴露端口
-sudo ufw allow 3000
-```
-
-**CentOS/RHEL (firewalld):**
-```bash
-# 开放端口
-sudo firewall-cmd --permanent --add-port=80/tcp
-sudo firewall-cmd --permanent --add-port=443/tcp
-sudo firewall-cmd --reload
-```
-
-**云服务器安全组：**
-- 阿里云：安全组规则添加入方向 80、443 端口
-- 腾讯云：防火墙规则添加入站 80、443 端口
-- AWS：Security Group 添加 HTTP、HTTPS 规则
-
-### 第九步：配置参数说明
-
-| 参数 | 说明 | 默认值 |
-|------|------|--------|
-| `appId` | 机器人ID（必填） | "" |
-| `secret` | 机器人密钥（必填） | "" |
-| `sandbox` | 是否使用沙盒环境 | false |
-| `qqEnable` | 是否启用QQ场景 | true |
-| `guildEnable` | 是否启用频道场景 | true |
-| `guildMode` | 频道模式（0公域，1私域） | 0 |
-| `event.type` | 事件接收方式（0关闭，1webhook，2ws） | 0 |
-
-#### Markdown 模式说明
-
-| 模式 | 说明 | 适用场景 |
-|------|------|----------|
-| 0 | 直接发送 | 简单文本和图片消息 |
-| 1 | 原生Markdown | 需要富文本格式 |
-| 3 | 旧图文模板 | 复杂图文混排 |
-| 4 | 纯文模板 | 多段文本消息 |
-| 5 | 自定义处理 | 完全自定义逻辑 |
-
-#### 支持的事件类型
-
-QQ机器人适配器通过统一的webhook地址接收以下事件类型：
-
-| 事件类型 | 说明 | 处理函数 |
-|---------|------|---------|
-| `GROUP_AT_MESSAGE_CREATE` | 群聊@机器人消息 | `onGroupMsg` |
-| `C2C_MESSAGE_CREATE` | C2C私聊消息 | `onFriendMsg` |
-| `GUILD_MESSAGE_CREATE` | 频道消息 | `onChannelMsg` |
-| `DIRECT_MESSAGE_CREATE` | 频道私信 | `onDirectMsg` |
-
-所有这些事件都通过同一个回调地址 `/qqbot/webhook` 接收，适配器内部会根据事件类型自动分发到对应的处理函数。
-
-## 使用说明
-
-### 连接方式说明
-
-#### 1. Webhook 方式
-
-- **优点**：配置简单，不需要额外的中转服务
-- **缺点**：需要有公网IP或域名
-- **适用场景**：有固定服务器或云服务器的用户
-
-配置完成后，需要在 QQ 开放平台配置 Webhook 回调地址。
-
-#### 2. WebSocket 方式
-
-- **优点**：适合内网环境，通过中转服务连接
-- **缺点**：需要额外部署中转服务
-- **适用场景**：没有公网IP的本地开发环境
-
-### 发送模式说明
-
-#### 模式 0：直接发送（推荐）
-
-最简单的模式，直接发送纯文本和图片消息。
-
-#### 模式 1：原生 Markdown
-
-使用 QQ 官方的原生 Markdown 格式发送消息。
-
-#### 模式 3：旧图文模板 Markdown
-
-使用旧版图文混排模板，适合需要复杂排版的场景。
-
-#### 模式 4：纯文模板 Markdown
-
-使用纯文本模板，支持多个文本字段。
-
-#### 模式 5：自定义处理
-
-完全自定义消息处理逻辑。
-
-## 开发指南
-
-### 环境要求
-
-- Node.js >= 16
-- TypeScript >= 5.0
-- Karin 框架
-
-### 本地开发
-
-1. 克隆仓库
-
-```bash
-git clone https://github.com/KarinJS/karin-plugin-adapter-qqbot.git
-cd karin-plugin-adapter-qqbot
+  return segment.keyboard([
+    [
+      { text: '上一页', data: `菜单 ${Math.max(1, page - 1)}`, enter: true },
+      { text: '下一页', data: `菜单 ${page + 1}`, enter: true },
+    ],
+  ])
+})
 ```
 
-2. 安装依赖
+简单理解：`karin.button` 是“自动追加按钮”的规则。适配器回复时会自动用 `buttonHandle(e.msg, { e })` 查找匹配规则，所以用户发送 `菜单 2`，就会命中 `/^菜单(?:\s+\d+)?$/`，按钮函数再通过 `args?.e?.msg` 算出当前页。
 
-```bash
-npm install
-```
+自己调用 `buttonHandle` 时只记三点：
 
-3. 开发模式运行
+- 参数一是匹配文本，通常填 `e.msg`，也可以是 `'菜单'`。
+- 参数二是给按钮函数的上下文，常用 `{ e }`；需要状态可以写 `{ e, page: 2 }`。
+- 一个规则里调用 `next()`，才会继续匹配后面的规则。
 
-```bash
-npm run dev
-```
+回调按钮的 `data` 会变成一条 Karin 消息内容，所以建议直接写成插件能识别的命令，例如 `按钮示例 确认`、`菜单 下一页`。
 
-### 构建项目
+## 发送消息与资源文件
 
-项目使用 `tsup` 进行打包，同时会运行 `tsc` 进行类型检查。
+适配器会尽量帮你发送图片、视频、语音和文件。推荐配置 `fileToUrl` 上传处理器，把本地文件、截图、Base64 等资源上传到你的图床、对象存储或 CDN，并返回一个 QQ 能访问的链接。
 
-```bash
-npm run build
-```
-
-构建产物会输出到 `dist` 目录。
+配置 `fileToUrl` 后：
 
-### 代码检查
+- 本地图片可以正常嵌入 Markdown 消息。
+- 视频、语音和文件会优先使用你返回的链接发送，通常比直接上传给 QQ 更稳定。
+- 如果资源本身已经是 `http` / `https` 链接，适配器会直接使用它。
 
-```bash
-npm run lint
-```
+没有配置 `fileToUrl` 时：
 
-### 发布
+- 单独发送图片、视频、语音、文件时，适配器会尝试直接交给 QQ 发送。
+- 较大的资源会使用 QQ 的大文件上传流程，优先保证消息能发出去。
+- 较大的图片或视频直接交给 QQ 发送时，QQ 客户端可能会把它显示成群文件，而不是图片或视频卡片；配置 `fileToUrl` 后通常可以避免这种显示问题。
+- 直接交给 QQ 只是兜底方案，生产环境仍然建议准备自己的文件服务。
 
-```bash
-# 发布正式版
-npm run pub
-
-# 发布测试版
-npm run pub-beta
-```
+> **注意：Markdown 里的图片必须配置 `fileToUrl`。**
+>
+> 只要你发送的内容包含 Markdown，并且 Markdown 里有图片、本地生成图、Base64 图等资源，就必须配置 `fileToUrl`。因为 Markdown 里的图片只能写成 QQ 能访问的链接，适配器不能把 Markdown 文本里的图片自动当成附件上传。
 
-## 项目结构
+你可以在自己的 Karin 插件中编写并注册 `fileToUrl` Handler：
 
-```
-karin-plugin-adapter-qqbot/
-├── src/
-│   ├── connection/      # 连接层（WebSocket、Webhook、路由）
-│   ├── core/           # 核心功能（适配器、事件处理、API）
-│   ├── types/          # TypeScript 类型定义
-│   └── utils/          # 工具函数
-├── dist/               # 构建产物
-├── config/             # 配置文件目录
-├── package.json
-├── tsconfig.json       # TypeScript 配置
-└── tsup.config.ts      # 打包配置
-```
+```js
+// plugins/karin-plugin-example/fileToUrl.js
+import karin, { common } from 'node-karin'
+import size from 'image-size'
 
-## API 使用示例
+export const uploadResource = karin.handler('fileToUrl', async (args) => {
+  const { file, type, filename } = args
+  const buffer = await common.buffer(file)
 
-### 发送群消息
+  // 由你实现：上传到图床/对象存储，返回可公开访问的 URL。
+  const url = await uploadToYourStorage(buffer, filename || 'file.bin')
 
-```typescript
-import type { AdapterQQBot } from '@karinjs/adapter-qqbot'
+  if (type !== 'image') return { url }
 
-// 在你的插件中使用
-export class MyPlugin extends plugin {
-  async handleGroupMessage(e: KarinMessage) {
-    const bot = e.bot as AdapterQQBot
-    // 发送消息
-    await bot.SendMessage(e.contact, [
-      { type: 'text', text: 'Hello, World!' }
-    ])
+  const dimension = size(buffer) // 获取图片宽高
+  return {
+    url,
+    width: dimension.width || 100,
+    height: dimension.height || 100
   }
-}
+})
 ```
 
-### 撤回消息
-
-```typescript
-await bot.recallMsg(e.contact, messageId)
-```
+> **注意：Handler 插件的 key 必须精确为 `fileToUrl`。**
+>
+> 图片必须返回 `{ url, width, height }`；其他资源返回 `{ url }`。
 
-## 常见问题
+建议生产环境都配置 `fileToUrl`。这样图片、视频和文件都可以先上传到你自己的文件服务，再交给 QQ 发送，成功率和可控性都会更好。
 
-### 第十步：验证配置
+## 事件
 
-#### 1. 检查配置文件
+- 支持 QQ 单聊、群聊、频道、频道私信和按钮回调。
+- 支持 `GROUP_MESSAGE_CREATE` 全量群消息和 `author.member_role` 身份字段。
+- 支持 `GROUP_MEMBER_ADD`、`GROUP_MEMBER_REMOVE` 群成员进退群事件。
+- 单聊同一 `msg_id` 最多回复 4 次；群聊规则保持官方限制。
 
-确保配置文件格式正确：
+## 开发
 
 ```bash
-# 查看配置文件
-cat @karinjs/@karinjs-adapter-qqbot/config/config.json
+pnpm install
+pnpm build
 ```
 
-#### 2. 启动服务
-
-```bash
-# 启动 Karin 服务
-npm start
-# 或者
-node app.js
-```
-
-#### 3. 查看日志
-
-检查日志文件，确认机器人连接成功：
-
-```bash
-# 查看最新日志
-tail -f logs/error/*.log
-```
-
-正常情况下应该看到类似信息：
-- `QQBot [AppID] 连接成功`
-- `Webhook服务已启动，端口: 3000`
-
-#### 4. 测试机器人
-
-1. 将机器人邀请到测试群
-2. 发送消息测试机器人响应
-3. 检查日志确认消息接收正常
-
-### 第十一步：常见问题排查
-
-#### 问题1：Webhook接收不到消息
-
-**检查清单：**
-- [ ] QQ开放平台回调地址配置正确
-- [ ] 服务器防火墙开放对应端口
-- [ ] Nginx反向代理配置正确
-- [ ] 域名解析正确指向服务器IP
-
-**排查命令：**
-```bash
-# 检查端口是否监听
-netstat -tlnp | grep :3000
-
-# 检查防火墙状态
-sudo ufw status
-
-# 测试本地接口
-curl -X POST http://localhost:3000/qqbot/webhook
-```
-
-#### 问题2：签名验证失败
-
-**可能原因：**
-- Secret配置错误
-- 反向代理修改了请求体
-- 时间戳差异过大
-
-**解决方案：**
-```nginx
-# Nginx配置中添加
-proxy_buffering off;
-proxy_request_buffering off;
-```
-
-#### 问题3：消息发送失败
-
-**检查清单：**
-- [ ] AppID和Secret正确
-- [ ] 机器人有发送消息权限
-- [ ] API地址配置正确
-- [ ] 网络连接正常
-
-#### 问题4：频道消息收不到
-
-**可能原因：**
-- 频道机器人权限不足
-- guildEnable配置为false
-- 私域机器人未正确配置
-
-**解决方案：**
-```json
-{
-  "guildEnable": true,
-  "guildMode": 1  // 私域机器人使用1
-}
-```
-
-### 第十二步：进阶配置
-
-#### 多机器人配置
-
-```json
-[
-  {
-    "appId": "机器人1的AppID",
-    "secret": "机器人1的Secret",
-    "event": { "type": 1 }
-  },
-  {
-    "appId": "机器人2的AppID", 
-    "secret": "机器人2的Secret",
-    "event": { "type": 1 }
-  }
-]
-```
-
-#### 环境分离配置
-
-开发环境使用沙盒：
-```json
-{
-  "sandbox": true,
-  "sandboxApi": "https://sandbox.api.sgroup.qq.com"
-}
-```
-
-生产环境使用正式API：
-```json
-{
-  "sandbox": false,
-  "prodApi": "https://api.sgroup.qq.com"
-}
-```
-
-#### 消息过滤配置
-
-```json
-{
-  "exclude": [
-    "https://example.com",
-    "https://trusted-site.com"
-  ],
-  "regex": [
-    {
-      "reg": "^/",
-      "rep": "#"
-    },
-    {
-      "reg": "\\[图片\\]",
-      "rep": ""
-    }
-  ]
-}
-```
-
-## 更新日志
-
-查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本更新历史。
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-
-## 许可证
-
-本项目基于 [项目许可证] 开源。
-
-## 相关链接
-
-- [Karin 框架](https://github.com/KarinJS/Karin)
-- [QQ 机器人开放平台](https://bot.q.qq.com/)
-- [QQ 机器人开发文档](https://bot.q.qq.com/wiki/)
-
-## 技术支持
-
-如有问题，请通过以下方式获取帮助：
+## License
 
-- 提交 [GitHub Issue](https://github.com/KarinJS/karin-plugin-adapter-qqbot/issues)
-- 加入 Karin 开发者社群
+MIT