@tencent-connect/openclaw-qqbot 1.5.6 → 1.6.0-alpha.1

package/README.md

@@ -6,14 +6,19 @@
 
 # QQ Bot Channel Plugin for OpenClaw
 
+
+
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
+### 🚀 Current Version: `v1.5.7`
+
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
 [![Platform](https://img.shields.io/badge/platform-OpenClaw-orange)](https://github.com/tencent-connect/openclaw-qqbot)
 [![Node.js](https://img.shields.io/badge/Node.js->=18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 
+
 <br/>
 
 **[简体中文](README.zh.md) | English**
@@ -40,6 +45,7 @@ Scan to join the QQ group chat
 | 🔄 **Hot Reload** | Install via npm with seamless hot updates |
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
+| 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
 
 ---
 
@@ -47,6 +53,16 @@ Scan to join the QQ group chat
 
 > **Note:** This plugin serves as a **message channel** only — it relays messages between QQ and OpenClaw. Capabilities like image understanding, voice transcription, drawing, etc. depend on the **AI model** you configure and the **skills** installed in OpenClaw, not on this plugin itself.
 
+### 💬 Quoted Message Context (REFIDX)
+
+QQ quote events carry index keys (e.g. `REFIDX_xxx`) instead of full original message body. The plugin now resolves these indices from a local persistent store and injects quote context into AI input, so replies better understand “which message is being quoted”.
+
+- Inbound and outbound messages with `ref_idx` are automatically indexed.
+- Store path: `~/.openclaw/qqbot/data/ref-index.jsonl` (survives gateway restart).
+- Quote body may include text + media summary (image/voice/video/file).
+
+<img width="360" src="docs/images/ref_msg.png" alt="Quoted Message Context Demo" />
+
 ### 🎙️ Voice Messages (STT)
 
 With STT configured, the plugin automatically transcribes voice messages to text before passing them to AI. The whole process is transparent to the user — sending voice feels as natural as sending text.
@@ -77,7 +93,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 
 <img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="Image Understanding Demo" />
 
-### 🎨 Image Generation
+### 🎨 Image Sending
 
 > **You**: Draw me a cat
 >
@@ -87,7 +103,7 @@ AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Format
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
 
-### 🔊 Voice Reply (TTS)
+### 🔊 Voice Sending
 
 > **You**: Tell me a joke in voice
 >
@@ -164,61 +180,62 @@ AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. La
 
 > For a step-by-step walkthrough with screenshots, see the [official guide](https://cloud.tencent.com/developer/article/2626045).
 
-### Step 2 — Install the Plugin
+### Step 2 — Install / Upgrade the Plugin
 
-**Option A: Install via npm (Recommended)**
+**Option A: Remote One-Liner (Easiest, no clone required)**
 
 ```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
+  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-**Option B: One-Click Install & Run**
-
-```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
+One command does it all: download script → cleanup old plugins → install → configure channel → restart service. Once done, open QQ and start chatting!
 
-The script handles everything: cleanup old plugins → install deps → register plugin → configure channel → start service. Once done, skip to [Step 4](#step-4--start--test).
+> `--appid` and `--secret` are **required for first-time install**. For subsequent upgrades:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
 
-**Option C: Manual Step-by-Step**
+**Option B: Local Script (if you've cloned the repo)**
 
 ```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-npm install --omit=dev
-openclaw plugins install .
+# Via npm
+bash ./scripts/upgrade-via-npm.sh --appid YOUR_APPID --secret YOUR_SECRET
+
+# Or via source
+bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-### Step 3 — Configure OpenClaw
+**Common flags:**
 
-**Option 1: CLI Wizard (Recommended)**
+| Flag | Description |
+|------|-------------|
+| `--appid <id> --secret <secret>` | Configure channel (required for first install, or to change credentials) |
+| `--version <version>` | Install a specific version (npm script only) |
+| `--self-version` | Install the version from local `package.json` (npm script only) |
+| `-h` / `--help` | Show full usage |
 
-```bash
-openclaw channels add --channel qqbot --token "AppID:AppSecret"
-```
+> Environment variables `QQBOT_APPID` / `QQBOT_SECRET` are also supported.
 
-**Option 2: Edit Config File**
+**Option C: Manual Install / Upgrade**
 
-Edit `~/.openclaw/openclaw.json`:
+```bash
+# Uninstall old plugins (skip if first install)
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall openclaw-qqbot
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "enabled": true,
-      "appId": "Your AppID",
-      "clientSecret": "Your AppSecret"
-    }
-  }
-}
-```
+# Install latest
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
 
-### Step 4 — Start & Test
+# Configure channel (first install only)
+openclaw channels add --channel qqbot --token "AppID:AppSecret"
 
-```bash
-openclaw gateway
+# Start / restart
+openclaw gateway restart
 ```
 
+### Step 3 — Test
+
 Open QQ, find your bot, and send a message!
 
 <div align="center">
@@ -366,119 +383,9 @@ STT supports two-level configuration with priority fallback:
 
 ---
 
-## 🔄 Upgrade
-
-### Option 1: Upgrade via npm (Recommended)
-
-Current latest npm version: `1.5.6`
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-The script automatically backs up channel config → uninstalls old plugins → installs new version → restores config → restarts gateway.
-
-```bash
-# Specify exact version
-bash ./scripts/npm-upgrade.sh --version 1.5.6
-```
-
-### Option 2: Upgrade via Source
-
-Run the one-click script to upgrade and restart:
-
-```bash
-bash ./scripts/upgrade-and-run.sh
-```
-
-When no `--appid` / `--secret` is provided, the script reads existing config from `~/.openclaw/openclaw.json` automatically.
-
-```bash
-# First-time or override credentials
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
-
-<details>
-<summary>Full Options</summary>
-
-| Option | Description |
-|--------|-------------|
-| `--appid <id>` | QQ Bot AppID |
-| `--secret <secret>` | QQ Bot AppSecret |
-| `--markdown <yes\|no>` | Enable Markdown format (default: no) |
-| `-h, --help` | Show help |
-
-Environment variables `QQBOT_APPID`, `QQBOT_SECRET`, `QQBOT_TOKEN` (AppID:Secret) are also supported.
-
-</details>
-
----
-
-## 🔀 Migrating from Legacy Plugins
-
-If you previously installed `qqbot`, `@sliverp/qqbot`, `@tencent-connect/qqbot`, or other related legacy plugins, you need to uninstall the old plugin before installing the new version.
-
-### Recommended: Use npm-upgrade Script (Automatic)
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-The script automatically uninstalls all legacy plugin variants (`qqbot`, `@sliverp/qqbot`, `openclaw-qq`, etc.), cleans up residual directories, and backs up/restores channel config.
-
-### Manual Migration
-
-**1. Back up your channel config**
-
-Save the `channels.qqbot` section from `~/.openclaw/openclaw.json` (including `appId`, `clientSecret`, `allowFrom`, etc.) — you'll need to restore it later.
-
-**2. Uninstall old plugins**
-
-Run the appropriate uninstall command(s) based on what you had installed:
-
-```bash
-# Uninstall legacy plugin variants (pick the ones that apply)
-openclaw plugins uninstall qqbot
-openclaw plugins uninstall @sliverp/qqbot
-openclaw plugins uninstall @tencent-connect/qqbot
-openclaw plugins uninstall openclaw-qqbot
-openclaw plugins uninstall openclaw-qq
-```
-
-If `plugins uninstall` doesn't fully clean up, manually remove residual directories:
-
-```bash
-rm -rf ~/.openclaw/extensions/qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qq
-```
-
-**3. Temporarily remove channel config**
-
-> ⚠️ Important: `openclaw plugins install` validates the config file. If `channels.qqbot` exists but no plugin provides that channel, it will fail with `unknown channel id: qqbot`.
-
-Before installing, temporarily remove the `channels.qqbot` section from `~/.openclaw/openclaw.json`.
-
-**4. Install the new version**
-
-```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
-```
-
-**5. Restore channel config**
-
-Write back the previously saved `channels.qqbot` config to `~/.openclaw/openclaw.json`.
-
-**6. Restart the gateway**
-
-```bash
-openclaw gateway restart
-```
-
----
-
 ## 📚 Documentation & Links
 
+- [Upgrade Guide](docs/UPGRADE_GUIDE.md) — full upgrade paths and migration notes
 - [Command Reference](docs/commands.md) — OpenClaw CLI commands
 - [Changelog](CHANGELOG.md) — release notes
 

package/README.zh.md

@@ -6,8 +6,11 @@
 
 # QQ Bot — OpenClaw 渠道插件
 
+
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
+### 🚀 当前版本： `v1.5.7`
+
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
 [![Platform](https://img.shields.io/badge/platform-OpenClaw-orange)](https://github.com/tencent-connect/openclaw-qqbot)
@@ -37,6 +40,7 @@
 | 🔄 **热更新** | 支持 npm 方式安装和无缝热更新 |
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
+| 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
 
 ---
 
@@ -44,6 +48,16 @@
 
 > **说明：** 本插件仅作为**消息通道**，负责在 QQ 和 OpenClaw 之间传递消息。图片理解、语音转录、AI 画图等能力取决于你配置的 **AI 模型**以及在 OpenClaw 中安装的 **skill**，而非插件本身提供。
 
+### 💬 引用消息上下文（REFIDX）
+
+QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返回原始消息全文。插件已支持从本地持久化索引中解析引用内容，并注入 AI 上下文，帮助模型更准确理解“用户引用的是哪条消息”。
+
+- 入站/出站消息中的 `ref_idx` 会自动建立索引。
+- 存储位置：`~/.openclaw/qqbot/data/ref-index.jsonl`（网关重启后仍可恢复）。
+- 引用内容支持文本 + 媒体摘要（图片/语音/视频/文件）。
+
+<img width="360" src="docs/images/ref_msg.png" alt="引用消息上下文演示" />
+
 ### 🎙️ 语音消息（STT）
 
 配置 STT 后，插件会自动将语音转录为文字再交给 AI 处理。整个过程对用户完全透明——发语音就像发文字一样自然，AI 听得懂你在说什么。
@@ -74,7 +88,7 @@
 
 <img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="图片理解演示" />
 
-### 🎨 AI 画图
+### 🎨 图片发送
 
 > **你**：画一只猫咪
 >
@@ -84,7 +98,7 @@ AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
 
-### 🔊 语音回复（TTS）
+### 🔊 语音发送
 
 > **你**：给我讲一个笑话
 >
@@ -161,61 +175,62 @@ AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网
 
 > 详细图文教程请参阅 [官方指南](https://cloud.tencent.com/developer/article/2626045)。
 
-### 第二步 — 安装插件
+### 第二步 — 安装 / 升级插件
 
-**方式一：通过 npm 安装（推荐）**
+**方式一：远程一键执行（最简单，无需 clone 仓库）**
 
 ```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
+curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh \
+  | bash -s -- --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-**方式二：一键安装并启动**
+一行命令搞定：下载脚本 → 清理旧插件 → 安装 → 配置通道 → 启动服务。完成后打开 QQ 即可开始聊天！
 
-```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
-
-脚本会自动完成：清理旧插件 → 安装依赖 → 注册插件 → 配置通道 → 启动服务。完成后可直接跳到[第四步](#第四步--启动并测试)。
+> 首次安装**必须**传 `--appid` 和 `--secret`。后续升级如已有配置：
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
 
-**方式三：手动分步安装**
+**方式二：本地脚本（已 clone 仓库时使用）**
 
 ```bash
-git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot
-npm install --omit=dev
-openclaw plugins install .
+# 通过 npm 安装
+bash ./scripts/upgrade-via-npm.sh --appid YOUR_APPID --secret YOUR_SECRET
+
+# 或通过源码安装
+bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET
 ```
 
-### 第三步 — 配置 OpenClaw
+**常用参数：**
 
-**方式一：通过 Wizard 配置（推荐）**
+| 参数 | 说明 |
+|------|------|
+| `--appid <id> --secret <secret>` | 配置通道（首次安装必填，或更换凭证时使用） |
+| `--version <版本号>` | 安装指定版本（仅 npm 脚本） |
+| `--self-version` | 安装本地 `package.json` 中的版本（仅 npm 脚本） |
+| `-h` / `--help` | 查看完整用法 |
 
-```bash
-openclaw channels add --channel qqbot --token "AppID:AppSecret"
-```
+> 也可通过环境变量 `QQBOT_APPID` / `QQBOT_SECRET` 设置。
 
-**方式二：编辑配置文件**
+**方式三：手动安装 / 升级**
 
-编辑 `~/.openclaw/openclaw.json`：
+```bash
+# 卸载旧插件（首次安装可跳过）
+openclaw plugins uninstall qqbot
+openclaw plugins uninstall openclaw-qqbot
 
-```json
-{
-  "channels": {
-    "qqbot": {
-      "enabled": true,
-      "appId": "你的 AppID",
-      "clientSecret": "你的 AppSecret"
-    }
-  }
-}
-```
+# 安装最新版本
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
 
-### 第四步 — 启动与测试
+# 配置通道（首次安装必做）
+openclaw channels add --channel qqbot --token "AppID:AppSecret"
 
-```bash
-openclaw gateway
+# 启动 / 重启
+openclaw gateway restart
 ```
 
+### 第三步 — 测试
+
 打开 QQ，找到你的机器人，发条消息试试！
 
 <div align="center">
@@ -363,119 +378,9 @@ STT 支持两级配置，按优先级查找：
 
 ---
 
-## 🔄 升级
-
-### 方式一：通过 npm 升级（推荐）
-
-当前最新 npm 版本：`1.5.6`
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-脚本会自动备份通道配置 → 卸载旧插件 → 安装新版本 → 恢复配置 → 重启网关。
-
-```bash
-# 指定版本号
-bash ./scripts/npm-upgrade.sh --version 1.5.6
-```
-
-### 方式二：通过源码升级
-
-运行一键脚本即可升级并重启：
-
-```bash
-bash ./scripts/upgrade-and-run.sh
-```
-
-不传 `--appid` / `--secret` 参数时，脚本会自动读取 `~/.openclaw/openclaw.json` 中已有的配置。
-
-```bash
-# 首次配置或需要覆盖时
-bash ./scripts/upgrade-and-run.sh --appid YOUR_APPID --secret YOUR_SECRET
-```
-
-<details>
-<summary>完整选项</summary>
-
-| 选项 | 说明 |
-|------|------|
-| `--appid <id>` | QQ 机器人 AppID |
-| `--secret <secret>` | QQ 机器人 AppSecret |
-| `--markdown <yes\|no>` | 是否启用 Markdown 消息格式（默认: no） |
-| `-h, --help` | 显示帮助 |
-
-也支持环境变量：`QQBOT_APPID`、`QQBOT_SECRET`、`QQBOT_TOKEN`（AppID:Secret）。
-
-</details>
-
----
-
-## 🔀 从旧版插件迁移
-
-如果你之前安装的是 `qqbot`、`@sliverp/qqbot`、`@tencent-connect/qqbot` 等关联插件，需要先卸载旧插件再安装新版本。
-
-### 推荐：使用 npm-upgrade 脚本（自动处理）
-
-```bash
-bash ./scripts/npm-upgrade.sh
-```
-
-脚本会自动卸载所有历史版本的插件（`qqbot`、`@sliverp/qqbot`、`openclaw-qq` 等）、清理残留目录、备份恢复通道配置。
-
-### 手动迁移
-
-**1. 备份你的通道配置**
-
-先记录 `~/.openclaw/openclaw.json` 中 `channels.qqbot` 的内容（`appId`、`clientSecret`、`allowFrom` 等），后续需要恢复。
-
-**2. 卸载旧插件**
-
-根据你之前安装的插件名，执行对应的卸载命令：
-
-```bash
-# 卸载可能存在的旧版插件（按实际情况选择）
-openclaw plugins uninstall qqbot
-openclaw plugins uninstall @sliverp/qqbot
-openclaw plugins uninstall @tencent-connect/qqbot
-openclaw plugins uninstall openclaw-qqbot
-openclaw plugins uninstall openclaw-qq
-```
-
-如果 `plugins uninstall` 未能完全清理，手动删除残留目录：
-
-```bash
-rm -rf ~/.openclaw/extensions/qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qqbot
-rm -rf ~/.openclaw/extensions/openclaw-qq
-```
-
-**3. 临时移除通道配置**
-
-> ⚠️ 重要：`openclaw plugins install` 会校验配置文件。如果配置中存在 `channels.qqbot` 但对应插件尚未安装，会报 `unknown channel id: qqbot` 错误并拒绝安装。
-
-安装前需要临时从 `~/.openclaw/openclaw.json` 中移除 `channels.qqbot` 配置段。
-
-**4. 安装新版本**
-
-```bash
-openclaw plugins install @tencent-connect/openclaw-qqbot
-```
-
-**5. 恢复通道配置**
-
-将之前备份的 `channels.qqbot` 配置写回 `~/.openclaw/openclaw.json`。
-
-**6. 重启网关**
-
-```bash
-openclaw gateway restart
-```
-
----
-
 ## 📚 文档与链接
 
+- [升级指南](docs/UPGRADE_GUIDE.zh.md) — 完整升级路径与迁移说明
 - [命令参考](docs/commands.md) — OpenClaw CLI 常用命令
 - [更新日志](CHANGELOG.md) — 各版本变更记录
 

package/bin/qqbot-cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * QQBot CLI - 用于升级和管理 QQBot 插件
+ * qqbot CLI - 用于升级和管理 qqbot 插件
  * 
  * 用法:
  *   npx openclaw-qqbot upgrade    # 升级插件
@@ -131,7 +131,7 @@ function runCommand(cmd, args = []) {
 
 // 升级命令
 function upgrade() {
-  console.log('=== QQBot 插件升级脚本 ===');
+  console.log('=== qqbot 插件升级脚本 ===');
 
   let foundInstallation = null;
   let savedConfig = null;
@@ -175,7 +175,7 @@ function upgrade() {
     }
   } else {
     console.log('未找到已保存的 qqbot 配置，请手动配置:');
-    console.log(`  ${foundInstallation} channels add --channel qqbot --token "AppID:AppSecret"`);
+    console.log(`  ${foundInstallation} channels add --channel qqbot --token "appid:appsecret"`);
     return;
   }
 
@@ -186,7 +186,7 @@ function upgrade() {
 
 // 安装命令
 function install() {
-  console.log('=== QQBot 插件安装 ===');
+  console.log('=== qqbot 插件安装 ===');
 
   const cmd = detectInstallation();
   if (!cmd) {
@@ -200,13 +200,13 @@ function install() {
 
   console.log('\n=== 安装完成 ===');
   console.log('\n请配置机器人通道:');
-  console.log(`  ${cmd} channels add --channel qqbot --token "AppID:AppSecret"`);
+  console.log(`  ${cmd} channels add --channel qqbot --token "appid:appsecret"`);
 }
 
 // 显示帮助
 function showHelp() {
   console.log(`
-QQBot CLI - QQ机器人插件管理工具
+qqbot CLI - QQ机器人插件管理工具
 
 用法:
   npx openclaw-qqbot <命令>