@tencent-connect/openclaw-qqbot 1.6.4-alpha.7 → 1.6.4-alpha.9

package/dist/src/slash-commands.js

@@ -65,6 +65,12 @@ function registerCommand(cmd) {
 registerCommand({
     name: "bot-ping",
     description: "测试当前 openclaw 与 QQ 连接的网络延迟",
+    usage: [
+        `/bot-ping`,
+        ``,
+        `测试 OpenClaw 主机与 QQ 服务器之间的网络延迟。`,
+        `返回网络传输耗时和插件处理耗时。`,
+    ].join("\n"),
     handler: (ctx) => {
         const now = Date.now();
         const eventTime = new Date(ctx.eventTimestamp).getTime();
@@ -90,6 +96,12 @@ registerCommand({
 registerCommand({
     name: "bot-version",
     description: "查看插件版本号",
+    usage: [
+        `/bot-version`,
+        ``,
+        `查看当前 QQBot 插件版本和 OpenClaw 框架版本。`,
+        `同时检查是否有新版本可用。`,
+    ].join("\n"),
     handler: () => {
         const frameworkVersion = getFrameworkVersion();
         const lines = [
@@ -116,6 +128,12 @@ registerCommand({
 registerCommand({
     name: "bot-help",
     description: "查看所有指令以及用途",
+    usage: [
+        `/bot-help`,
+        ``,
+        `列出所有可用的 QQBot 插件内置指令及其简要说明。`,
+        `使用 /指令名 ? 可查看某条指令的详细用法。`,
+    ].join("\n"),
     handler: () => {
         const lines = [`### QQBot插件内置调试指令`, ``];
         for (const [name, cmd] of commands) {
@@ -205,6 +223,31 @@ function findBash() {
         return null;
     }
 }
+/**
+ * 将 openclaw.json 中的 qqbot 插件 source 从 "path" 切换为 "npm"。
+ * 用于热更新场景：从 npm 拉取新版本后，确保 openclaw 不再从本地源码加载。
+ */
+function switchPluginSourceToNpm() {
+    try {
+        const homeDir = getHomeDir();
+        for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
+            const cfgPath = path.join(homeDir, `.${cli}`, `${cli}.json`);
+            if (!fs.existsSync(cfgPath))
+                continue;
+            const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+            const inst = cfg?.plugins?.installs?.["openclaw-qqbot"];
+            if (inst && inst.source !== "npm") {
+                inst.source = "npm";
+                delete inst.sourcePath;
+                fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 4) + "\n");
+            }
+            break;
+        }
+    }
+    catch {
+        // 非关键操作，静默忽略
+    }
+}
 /**
  * 执行热更新：执行脚本(--no-restart) → 立即触发 gateway restart
  *
@@ -243,6 +286,11 @@ function fireHotUpgrade(targetVersion) {
             // 文件替换异常，不执行 restart 以保持现有服务
             return;
         }
+        // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
+        // 确保新进程启动时读到的是 npm source，不会被本地源码覆盖。
+        // 必须在 restart 之前同步完成，避免 openclaw 轮询检测到配置变更后
+        // 先于我们的 restart 触发非预期的 reload。
+        switchPluginSourceToNpm();
         // 文件替换成功，立即触发 gateway restart（不再等后续步骤）
         execFile(cli, ["gateway", "restart"], { timeout: 30_000 }, (restartErr) => {
             if (restartErr) {
@@ -270,6 +318,14 @@ let _upgrading = false; // 升级锁
 registerCommand({
     name: "bot-upgrade",
     description: "检查更新并自动热更（失败则返回升级指引）",
+    usage: [
+        `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
+        `/bot-upgrade --latest     确认升级到最新版本`,
+        `/bot-upgrade --version X  升级到指定版本（如 1.6.4-alpha.7）`,
+        `/bot-upgrade --force      强制重新安装当前版本`,
+        ``,
+        `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
+    ].join("\n"),
     handler: async (ctx) => {
         // 升级相关指令仅在私聊中可用
         if (ctx.type !== "c2c") {
@@ -507,6 +563,12 @@ function collectRecentLogFiles(logDirs) {
 registerCommand({
     name: "bot-logs",
     description: "导出本地日志文件",
+    usage: [
+        `/bot-logs`,
+        ``,
+        `导出最近的 OpenClaw 日志文件（最多 4 个）。`,
+        `每个文件最多保留最后 1000 行，以文件形式返回。`,
+    ].join("\n"),
     handler: () => {
         const logDirs = collectCandidateLogDirs();
         const recentFiles = collectRecentLogFiles(logDirs).slice(0, 4);
@@ -577,6 +639,13 @@ export async function matchSlashCommand(ctx) {
     const cmd = commands.get(cmdName);
     if (!cmd)
         return null; // 不是插件级指令，交给框架
+    // /指令 ? — 返回用法说明
+    if (args === "?") {
+        if (cmd.usage) {
+            return `📖 /${cmd.name} 用法：\n\n${cmd.usage}`;
+        }
+        return `/${cmd.name} — ${cmd.description}`;
+    }
     ctx.args = args;
     const result = await cmd.handler(ctx);
     return result;

package/dist/src/update-checker.js

@@ -71,7 +71,7 @@ async function fetchDistTags(log) {
 export function triggerUpdateCheck(log) {
     if (_checking)
         return;
-    const INTERVAL_MS = 30 * 60 * 1000;
+    const INTERVAL_MS = 1 * 60 * 1000;
     if (_lastInfo.checkedAt > 0 && Date.now() - _lastInfo.checkedAt < INTERVAL_MS) {
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.4-alpha.7",
+  "version": "1.6.4-alpha.9",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/upgrade-via-source.sh

@@ -259,6 +259,25 @@ else
     echo "✅ 插件安装命令执行完成"
     echo "安装日志已保存到: $INSTALL_LOG"
 
+    # 确保 openclaw.json 中的 source 为 path（从 npm 切回 path）
+    for _app in openclaw clawdbot moltbot; do
+        _cfg="$HOME/.$_app/$_app.json"
+        if [ -f "$_cfg" ]; then
+            node -e "
+              const fs = require('fs');
+              const cfg = JSON.parse(fs.readFileSync('$_cfg', 'utf8'));
+              const inst = cfg.plugins && cfg.plugins.installs && cfg.plugins.installs['openclaw-qqbot'];
+              if (inst && inst.source !== 'path') {
+                inst.source = 'path';
+                inst.sourcePath = '$PROJ_DIR';
+                fs.writeFileSync('$_cfg', JSON.stringify(cfg, null, 4) + '\n');
+                console.log('  已将 plugins.installs.openclaw-qqbot.source 更新为 path');
+              }
+            " 2>/dev/null || true
+            break
+        fi
+    done
+
     # 验证插件目录是否真正创建（防止 "安装成功" 但目录缺失的情况）
     _plugin_dir_ok=0
     for _candidate_name in openclaw-qqbot qqbot openclaw-qq; do

package/src/slash-commands.ts

@@ -116,6 +116,8 @@ interface SlashCommand {
   name: string;
   /** 简要描述 */
   description: string;
+  /** 详细用法说明（支持多行），用于 /指令 ? 查询 */
+  usage?: string;
   /** 处理函数 */
   handler: (ctx: SlashCommandContext) => SlashCommandResult | Promise<SlashCommandResult>;
 }
@@ -136,6 +138,12 @@ function registerCommand(cmd: SlashCommand): void {
 registerCommand({
   name: "bot-ping",
   description: "测试当前 openclaw 与 QQ 连接的网络延迟",
+  usage: [
+    `/bot-ping`,
+    ``,
+    `测试 OpenClaw 主机与 QQ 服务器之间的网络延迟。`,
+    `返回网络传输耗时和插件处理耗时。`,
+  ].join("\n"),
   handler: (ctx) => {
     const now = Date.now();
     const eventTime = new Date(ctx.eventTimestamp).getTime();
@@ -162,6 +170,12 @@ registerCommand({
 registerCommand({
   name: "bot-version",
   description: "查看插件版本号",
+  usage: [
+    `/bot-version`,
+    ``,
+    `查看当前 QQBot 插件版本和 OpenClaw 框架版本。`,
+    `同时检查是否有新版本可用。`,
+  ].join("\n"),
   handler: () => {
     const frameworkVersion = getFrameworkVersion();
     const lines = [
@@ -187,6 +201,12 @@ registerCommand({
 registerCommand({
   name: "bot-help",
   description: "查看所有指令以及用途",
+  usage: [
+    `/bot-help`,
+    ``,
+    `列出所有可用的 QQBot 插件内置指令及其简要说明。`,
+    `使用 /指令名 ? 可查看某条指令的详细用法。`,
+  ].join("\n"),
   handler: () => {
     const lines = [`### QQBot插件内置调试指令`, ``];
     for (const [name, cmd] of commands) {
@@ -289,6 +309,30 @@ function findBash(): string | null {
   }
 }
 
+/**
+ * 将 openclaw.json 中的 qqbot 插件 source 从 "path" 切换为 "npm"。
+ * 用于热更新场景：从 npm 拉取新版本后，确保 openclaw 不再从本地源码加载。
+ */
+function switchPluginSourceToNpm(): void {
+  try {
+    const homeDir = getHomeDir();
+    for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
+      const cfgPath = path.join(homeDir, `.${cli}`, `${cli}.json`);
+      if (!fs.existsSync(cfgPath)) continue;
+      const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+      const inst = cfg?.plugins?.installs?.["openclaw-qqbot"];
+      if (inst && inst.source !== "npm") {
+        inst.source = "npm";
+        delete inst.sourcePath;
+        fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 4) + "\n");
+      }
+      break;
+    }
+  } catch {
+    // 非关键操作，静默忽略
+  }
+}
+
 /**
  * 执行热更新：执行脚本(--no-restart) → 立即触发 gateway restart
  *
@@ -329,6 +373,12 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
       return;
     }
 
+    // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
+    // 确保新进程启动时读到的是 npm source，不会被本地源码覆盖。
+    // 必须在 restart 之前同步完成，避免 openclaw 轮询检测到配置变更后
+    // 先于我们的 restart 触发非预期的 reload。
+    switchPluginSourceToNpm();
+
     // 文件替换成功，立即触发 gateway restart（不再等后续步骤）
     execFile(cli, ["gateway", "restart"], { timeout: 30_000 }, (restartErr) => {
       if (restartErr) {
@@ -359,6 +409,14 @@ let _upgrading = false; // 升级锁
 registerCommand({
   name: "bot-upgrade",
   description: "检查更新并自动热更（失败则返回升级指引）",
+  usage: [
+    `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
+    `/bot-upgrade --latest     确认升级到最新版本`,
+    `/bot-upgrade --version X  升级到指定版本（如 1.6.4-alpha.7）`,
+    `/bot-upgrade --force      强制重新安装当前版本`,
+    ``,
+    `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
+  ].join("\n"),
   handler: async (ctx) => {
     // 升级相关指令仅在私聊中可用
     if (ctx.type !== "c2c") {
@@ -615,6 +673,12 @@ function collectRecentLogFiles(logDirs: string[]): LogCandidate[] {
 registerCommand({
   name: "bot-logs",
   description: "导出本地日志文件",
+  usage: [
+    `/bot-logs`,
+    ``,
+    `导出最近的 OpenClaw 日志文件（最多 4 个）。`,
+    `每个文件最多保留最后 1000 行，以文件形式返回。`,
+  ].join("\n"),
   handler: () => {
     const logDirs = collectCandidateLogDirs();
     const recentFiles = collectRecentLogFiles(logDirs).slice(0, 4);
@@ -691,6 +755,14 @@ export async function matchSlashCommand(ctx: SlashCommandContext): Promise<Slash
   const cmd = commands.get(cmdName);
   if (!cmd) return null; // 不是插件级指令，交给框架
 
+  // /指令 ? — 返回用法说明
+  if (args === "?") {
+    if (cmd.usage) {
+      return `📖 /${cmd.name} 用法：\n\n${cmd.usage}`;
+    }
+    return `/${cmd.name} — ${cmd.description}`;
+  }
+
   ctx.args = args;
   const result = await cmd.handler(ctx);
   return result;

package/src/update-checker.ts

@@ -84,7 +84,7 @@ export function triggerUpdateCheck(log?: {
   debug?: (msg: string) => void;
 }): void {
   if (_checking) return;
-  const INTERVAL_MS = 30 * 60 * 1000;
+  const INTERVAL_MS = 1 * 60 * 1000;
   if (_lastInfo.checkedAt > 0 && Date.now() - _lastInfo.checkedAt < INTERVAL_MS) {
     return;
   }