From fa93b2dd58463dbd8c7755d1e1a449c03bd830fd Mon Sep 17 00:00:00 2001 From: rianli Date: Wed, 11 Mar 2026 13:59:33 +0800 Subject: [PATCH] docs: clarify upgrade script usage and source-run constraints --- CHANGELOG.zh.md | 2 +- README.md | 33 +++++++++++++++++++++++++-------- README.zh.md | 35 ++++++++++++++++++++++++++--------- docs/UPGRADE_GUIDE.md | 19 ++++++++++++++++--- docs/UPGRADE_GUIDE.zh.md | 19 ++++++++++++++++--- scripts/upgrade-via-npm.sh | 2 +- 6 files changed, 85 insertions(+), 25 deletions(-) diff --git a/CHANGELOG.zh.md b/CHANGELOG.zh.md index f73ac9a..29dcade 100644 --- a/CHANGELOG.zh.md +++ b/CHANGELOG.zh.md @@ -24,7 +24,7 @@ - 新增 `npm-upgrade.sh` 脚本，支持通过 npm 包安装和升级插件。 - 支持 `--tag` 和 `--version` 选项，默认安装 `@alpha`。 - - 自动处理通道配置备份/恢复、旧插件清理（包括 `qqbot`、`@sliverp/qqbot` 等历史版本）、网关重启。 + - 自动处理通道配置备份/恢复、旧插件清理（包括 `qqbot`、`@sliverp/qqbot`、`openclaw-qqbot`、"@tencent-connect/openclaw-qqbot" 等历史版本）、网关重启。 - 安装前临时移除 `channels.qqbot` 配置，避免 `unknown channel id` 校验错误。 ### 修复 diff --git a/README.md b/README.md index 5e471db..d21581e 100644 --- a/README.md +++ b/README.md @@ -176,7 +176,10 @@ openclaw plugins install @tencent-connect/openclaw-qqbot ```bash git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot +# First-time install/config (appid and secret are required) bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET +# Subsequent upgrades (existing config) +bash ./scripts/upgrade-via-source.sh ``` 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). @@ -370,7 +373,7 @@ STT supports two-level configuration with priority fallback: ### Option 1: Upgrade via npm (Recommended) -Current latest npm version: `1.5.6` +Check latest npm version: `npm view @tencent-connect/openclaw-qqbot version` ```bash bash ./scripts/upgrade-via-npm.sh @@ -380,12 +383,24 @@ The script automatically backs up channel config → uninstalls old plugins → ```bash # Specify exact version -bash ./scripts/upgrade-via-npm.sh --version 1.5.6 +bash ./scripts/upgrade-via-npm.sh --version +``` + +If `--version` is not provided, the script installs `latest` by default. + +You can also download and run the npm upgrade script directly (without cloning the whole repository): + +```bash +curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh -o /tmp/upgrade-via-npm.sh +bash /tmp/upgrade-via-npm.sh +# or: bash /tmp/upgrade-via-npm.sh --version ``` ### Option 2: Upgrade via Source -Run the one-click script to upgrade and restart: +Run the one-click script to upgrade and restart. + +Note: this script must be executed inside this repository (it installs from local source via `openclaw plugins install .`). ```bash bash ./scripts/upgrade-via-source.sh @@ -416,7 +431,11 @@ Environment variables `QQBOT_APPID`, `QQBOT_SECRET`, `QQBOT_TOKEN` (AppID:Secret ## 🔀 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. +Common legacy plugin migrations include: +- `qqbot` (npm package: `@sliverp/qqbot`) +- `openclaw-qqbot` (npm package: `@tencent-connect/openclaw-qqbot`) + +If you previously installed any of these (or other similar legacy variants), uninstall the old plugin before installing the new version. ### Recommended: Use upgrade-via-npm Script (Automatic) @@ -424,7 +443,7 @@ If you previously installed `qqbot`, `@sliverp/qqbot`, `@tencent-connect/qqbot`, bash ./scripts/upgrade-via-npm.sh ``` -The script automatically uninstalls all legacy plugin variants (`qqbot`, `@sliverp/qqbot`, etc.), cleans up residual directories, and backs up/restores channel config. +The script automatically uninstalls legacy variants of these two plugin IDs (`qqbot`, `openclaw-qqbot`), cleans up residual directories, and backs up/restores channel config. ### Manual Migration @@ -437,10 +456,8 @@ Save the `channels.qqbot` section from `~/.openclaw/openclaw.json` (including `a Run the appropriate uninstall command(s) based on what you had installed: ```bash -# Uninstall legacy plugin variants (pick the ones that apply) +# Uninstall legacy plugin IDs (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 ``` diff --git a/README.zh.md b/README.zh.md index dd1e464..76c9c75 100644 --- a/README.zh.md +++ b/README.zh.md @@ -173,7 +173,10 @@ openclaw plugins install @tencent-connect/openclaw-qqbot ```bash git clone https://github.com/tencent-connect/openclaw-qqbot.git && cd openclaw-qqbot +# 首次安装/首次配置（需要提供 appid 和 secret） bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET +# 后续升级（已有配置） +bash ./scripts/upgrade-via-source.sh ``` 脚本会自动完成：清理旧插件 → 安装依赖 → 注册插件 → 配置通道 → 启动服务。完成后可直接跳到[第四步](#第四步--启动并测试)。 @@ -367,7 +370,7 @@ STT 支持两级配置，按优先级查找： ### 方式一：通过 npm 升级（推荐） -当前最新 npm 版本：`1.5.6` +查看最新 npm 版本：`npm view @tencent-connect/openclaw-qqbot version` ```bash bash ./scripts/upgrade-via-npm.sh @@ -377,12 +380,24 @@ bash ./scripts/upgrade-via-npm.sh ```bash # 指定版本号 -bash ./scripts/upgrade-via-npm.sh --version 1.5.6 +bash ./scripts/upgrade-via-npm.sh --version +``` + +不传 `--version` 时，脚本默认安装 `latest`。 + +也可以不拉完整仓库，直接下载并执行 npm 升级脚本： + +```bash +curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh -o /tmp/upgrade-via-npm.sh +bash /tmp/upgrade-via-npm.sh +# 或：bash /tmp/upgrade-via-npm.sh --version ``` ### 方式二：通过源码升级 -运行一键脚本即可升级并重启： +运行一键脚本即可升级并重启。 + +注意：该脚本必须在当前仓库内执行（通过 `openclaw plugins install .` 从本地源码安装）。 ```bash bash ./scripts/upgrade-via-source.sh @@ -402,7 +417,7 @@ bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET |------|------| | `--appid ` | QQ 机器人 AppID | | `--secret ` | QQ 机器人 AppSecret | -| `--markdown ` | 是否启用 Markdown 消息格式（默认: no） | +| `--markdown ` | 是否启用 Markdown 消息格式（默认: yes） | | `-h, --help` | 显示帮助 | 也支持环境变量：`QQBOT_APPID`、`QQBOT_SECRET`、`QQBOT_TOKEN`（AppID:Secret）。 @@ -413,7 +428,11 @@ bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET ## 🔀 从旧版插件迁移 -如果你之前安装的是 `qqbot`、`@sliverp/qqbot`、`@tencent-connect/qqbot` 等关联插件，需要先卸载旧插件再安装新版本。 +常见需要迁移的历史插件包括： +- `qqbot`（npm 包：`@sliverp/qqbot`） +- `openclaw-qqbot`（npm 包：`@tencent-connect/openclaw-qqbot`） + +如果你之前安装过其中任意一个（或其他同类历史变体），都需要先卸载旧插件再安装新版本。 ### 推荐：使用 upgrade-via-npm 脚本（自动处理） @@ -421,7 +440,7 @@ bash ./scripts/upgrade-via-source.sh --appid YOUR_APPID --secret YOUR_SECRET bash ./scripts/upgrade-via-npm.sh ``` -脚本会自动卸载所有历史版本的插件（`qqbot`、`@sliverp/qqbot` 等）、清理残留目录、备份恢复通道配置。 +脚本会自动卸载这两条历史线相关的旧插件变体（`qqbot`、`openclaw-qqbot`），并清理残留目录、备份恢复通道配置。 ### 手动迁移 @@ -434,10 +453,8 @@ bash ./scripts/upgrade-via-npm.sh 根据你之前安装的插件名，执行对应的卸载命令： ```bash -# 卸载可能存在的旧版插件（按实际情况选择） +# 卸载可能存在的旧插件 ID（按实际情况选择） openclaw plugins uninstall qqbot -openclaw plugins uninstall @sliverp/qqbot -openclaw plugins uninstall @tencent-connect/qqbot openclaw plugins uninstall openclaw-qqbot ``` diff --git a/docs/UPGRADE_GUIDE.md b/docs/UPGRADE_GUIDE.md index 4ed8c30..a5a0d61 100644 --- a/docs/UPGRADE_GUIDE.md +++ b/docs/UPGRADE_GUIDE.md @@ -11,11 +11,23 @@ If you previously installed qqbot but are not familiar with `openclaw plugins` c bash ./scripts/upgrade-via-npm.sh # Upgrade to a specific version -bash ./scripts/upgrade-via-npm.sh --version 1.5.6 +bash ./scripts/upgrade-via-npm.sh --version ``` +> If `--version` is omitted, `latest` is used by default. + +> You can also download and run this script directly (without cloning the whole repository): +> +> ```bash +> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh -o /tmp/upgrade-via-npm.sh +> bash /tmp/upgrade-via-npm.sh +> # or: bash /tmp/upgrade-via-npm.sh --version +> ``` + ### 2) One-click upgrade from local source and restart +> Note: this script must be run inside this repository (it installs via `openclaw plugins install .`). + ```bash # Run directly if you already have config bash ./scripts/upgrade-via-source.sh @@ -24,7 +36,7 @@ bash ./scripts/upgrade-via-source.sh bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret ``` -> Note: For first-time installation, you must provide `appid` and `secret` (or set `QQBOT_APPID` / `QQBOT_SECRET`). +> Note: For first-time installation, you must provide `appid` and `secret` (or set `QQBOT_APPID` / `QQBOT_SECRET`); for subsequent upgrades with existing config, run `bash ./scripts/upgrade-via-source.sh` directly. --- @@ -36,6 +48,7 @@ bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret # Optional: uninstall old plugins first (based on your actual installation) # Run `openclaw plugins list` to check installed plugin IDs # Common legacy plugin IDs: qqbot / openclaw-qqbot +# Corresponding npm packages: @sliverp/qqbot / @tencent-connect/openclaw-qqbot openclaw plugins uninstall qqbot openclaw plugins uninstall openclaw-qqbot @@ -46,7 +59,7 @@ openclaw plugins uninstall openclaw-qqbot openclaw plugins install @tencent-connect/openclaw-qqbot@latest # Or install a specific version -openclaw plugins install @tencent-connect/openclaw-qqbot@1.5.6 +openclaw plugins install @tencent-connect/openclaw-qqbot@ ``` ### B. Install from source directory diff --git a/docs/UPGRADE_GUIDE.zh.md b/docs/UPGRADE_GUIDE.zh.md index 6b44d59..0af0e51 100644 --- a/docs/UPGRADE_GUIDE.zh.md +++ b/docs/UPGRADE_GUIDE.zh.md @@ -11,11 +11,23 @@ bash ./scripts/upgrade-via-npm.sh # 指定版本 -bash ./scripts/upgrade-via-npm.sh --version 1.5.6 +bash ./scripts/upgrade-via-npm.sh --version ``` +> 不传 `--version` 时，默认使用 `latest`。 + +> 也可以不拉完整仓库，直接下载并执行该脚本： +> +> ```bash +> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh -o /tmp/upgrade-via-npm.sh +> bash /tmp/upgrade-via-npm.sh +> # 或：bash /tmp/upgrade-via-npm.sh --version +> ``` + ### 2) 通过源码一键升级并重启 +> 注意：该脚本必须在当前仓库内执行（通过 `openclaw plugins install .` 安装本地源码）。 + ```bash # 已有配置时可直接执行 bash ./scripts/upgrade-via-source.sh @@ -24,7 +36,7 @@ bash ./scripts/upgrade-via-source.sh bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret ``` -> 注意：首次安装必须设置 `appid` 和 `secret`（或设置环境变量 `QQBOT_APPID` / `QQBOT_SECRET`）。 +> 注意：首次安装必须设置 `appid` 和 `secret`（或设置环境变量 `QQBOT_APPID` / `QQBOT_SECRET`）；后续升级如已有配置可直接执行 `bash ./scripts/upgrade-via-source.sh`。 --- @@ -36,6 +48,7 @@ bash ./scripts/upgrade-via-source.sh --appid your_appid --secret your_secret # 可选：先卸载旧插件（按实际安装情况执行） # 可先执行 `openclaw plugins list` 查看已安装插件 ID # 常见历史插件 ID：qqbot / openclaw-qqbot +# 对应 npm 包：@sliverp/qqbot / @tencent-connect/openclaw-qqbot openclaw plugins uninstall qqbot openclaw plugins uninstall openclaw-qqbot @@ -46,7 +59,7 @@ openclaw plugins uninstall openclaw-qqbot openclaw plugins install @tencent-connect/openclaw-qqbot@latest # 或安装指定版本 -openclaw plugins install @tencent-connect/openclaw-qqbot@1.5.6 +openclaw plugins install @tencent-connect/openclaw-qqbot@ ``` ### B. 从源码目录安装 diff --git a/scripts/upgrade-via-npm.sh b/scripts/upgrade-via-npm.sh index eb16c20..d7222f2 100755 --- a/scripts/upgrade-via-npm.sh +++ b/scripts/upgrade-via-npm.sh @@ -4,7 +4,7 @@ # # 用法: # upgrade-via-npm.sh # 升级到 latest（默认） -# upgrade-via-npm.sh --version 1.5.6 # 升级到指定版本 +# upgrade-via-npm.sh --version # 升级到指定版本 # upgrade-via-npm.sh --self-version # 升级到当前仓库 package.json 版本 set -eo pipefail