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

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) {
@@ -270,6 +288,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 +533,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 +609,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/package.json

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

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) {
@@ -359,6 +379,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 +643,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 +725,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;