@tencent-connect/openclaw-qqbot 1.7.2 → 2.0.0

package/index.ts

@@ -1,32 +1,69 @@
-import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
-import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
+/**
+ * @tencent-connect/openclaw-qqbot
+ *
+ * 独立版 QQ Bot 通道插件 — 基于 @tencent-connect/qqbot-nodejs SDK 重构。
+ *
+ * 直接依赖：
+ * - openclaw/plugin-sdk：OpenClaw 插件框架
+ * - @tencent-connect/qqbot-nodejs：QQ 开放平台 Node.js SDK
+ */
+import type { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+import { emptyPluginConfigSchema } from 'openclaw/plugin-sdk';
 
-import { qqbotPlugin } from "./src/channel.js";
-import { setQQBotRuntime } from "./src/runtime.js";
-import { registerChannelTool } from "./src/tools/channel.js";
-import { registerRemindTool } from "./src/tools/remind.js";
+import { qqbotPlugin } from './src/channel.js';
+import { setQQBotRuntime } from './src/runtime.js';
+import { registerPlatformTool } from './src/tools/platform.js';
+import { registerRemindTool } from './src/tools/remind.js';
+import { verifyRuntimeContract } from './src/adapter/contract.js';
+
+let registered = false;
 
 const plugin = {
-  id: "openclaw-qqbot",
-  name: "QQ Bot",
-  description: "QQ Bot channel plugin",
+  id: 'openclaw-qqbot',
+  name: 'QQ Bot',
+  description: 'QQ Bot channel plugin',
   configSchema: emptyPluginConfigSchema(),
   register(api: OpenClawPluginApi) {
     setQQBotRuntime(api.runtime);
+
+    if (!registered) {
+      registered = true;
+      const contract = verifyRuntimeContract(api.runtime);
+      if (!contract.ok) {
+        throw new Error(
+          `openclaw-qqbot incompatible with openclaw ${contract.version}: ` +
+          `missing required APIs: ${contract.missing.join(', ')}. ` +
+          `Please upgrade openclaw or downgrade the plugin.`,
+        );
+      }
+    }
+
     api.registerChannel({ plugin: qqbotPlugin as any });
-    registerChannelTool(api);
+    registerPlatformTool(api);
     registerRemindTool(api);
   },
 };
 
 export default plugin;
 
-export { qqbotPlugin } from "./src/channel.js";
-export { setQQBotRuntime, getQQBotRuntime } from "./src/runtime.js";
-export { qqbotOnboardingAdapter } from "./src/onboarding.js";
-export * from "./src/types.js";
-export * from "./src/api.js";
-export * from "./src/config.js";
-export * from "./src/gateway.js";
-export * from "./src/outbound.js";
-export * from "./src/transport/index.js";
+// ── Public API exports ──
+
+export { qqbotPlugin } from './src/channel.js';
+export { setQQBotRuntime, getQQBotRuntime } from './src/runtime.js';
+export { getBotForAccount, tryGetBotForAccount, buildUserAgent } from './src/bot-instance.js';
+export { qqbotOnboardingAdapter } from './src/features/onboarding.js';
+export { QQBotGateway } from './src/gateway/index.js';
+export { sendText, sendMedia } from './src/outbound/outbound-service.js';
+export { parseTarget } from './src/outbound/target.js';
+export { dispatchToOpenClaw } from './src/dispatch/index.js';
+export {
+  PersistedRefIndexStore,
+  getPersistedRefIndexStore,
+  flushAllRefIndexStores,
+} from './src/features/ref-index-store.js';
+export {
+  StreamingController,
+  shouldUseStreaming,
+} from './src/outbound/streaming-controller.js';
+export * from './src/types.js';
+export * from './src/config.js';

package/openclaw.plugin.json

@@ -4,18 +4,34 @@
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
   "extensions": ["./preload.cjs"],
-  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-media", "skills/qqbot-upgrade"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-upgrade"],
+  "contracts": {
+    "tools": ["qqbot_platform_api", "qqbot_remind"]
+  },
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true
   },
   "configSchema": {
     "type": "object",
-    "additionalProperties": false,
-    "properties": {}
+    "additionalProperties": true,
+    "properties": {
+      "appId": { "type": "string", "description": "QQ Bot AppID" },
+      "clientSecret": { "type": "string", "description": "QQ Bot AppSecret" }
+    }
   },
   "channelConfigs": {
     "qqbot": {
+      "schema": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "appId": { "type": "string", "description": "QQ Bot AppID" },
+          "clientSecret": { "type": "string", "description": "QQ Bot AppSecret" }
+        }
+      },
+      "label": "QQ Bot",
+      "description": "QQ Bot channel configuration with message support, cron jobs, and proactive messaging.",
       "preferOver": ["qqbot"]
     }
   }

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.7.2",
+  "version": "2.0.0",
+  "description": "QQ Bot channel plugin for OpenClaw",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "main": "dist/index.js",
+  "main": "dist/index.cjs",
   "types": "dist/index.d.ts",
   "bin": {
     "openclaw-qqbot": "./bin/qqbot-cli.js",
@@ -20,6 +21,7 @@
     "index.ts",
     "preload.cjs",
     "tsconfig.json",
+    "tsup.config.ts",
     "openclaw.plugin.json"
   ],
   "openclaw": {
@@ -33,38 +35,27 @@
     }
   },
   "scripts": {
-    "build": "tsc || true",
-    "postbuild": "node -e \"const fs=require('fs'),p=require('path'),ext=p.join(require('os').homedir(),'.openclaw/extensions/openclaw-qqbot');if(fs.existsSync(ext)&&!fs.lstatSync(ext).isSymbolicLink()){const d=p.join(ext,'dist'),pr=p.join(ext,'preload.cjs');fs.cpSync('dist',d,{recursive:true});fs.copyFileSync('preload.cjs',pr);console.log('[postbuild] synced to',ext)}\"",
-    "dev": "tsc --watch",
-    "prepack": "npm install --omit=dev",
-    "postinstall": "node scripts/postinstall-link-sdk.js 2>/dev/null || true"
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint:runtime": "npx tsx src/runtime-adapter/lint-runtime-access.ts"
   },
   "dependencies": {
-    "mpg123-decoder": "^1.0.3",
-    "silk-wasm": "^3.7.1",
-    "ws": "^8.18.0"
+    "@tencent-connect/qqbot-connector": "1.2.0",
+    "@tencent-connect/qqbot-nodejs": "^1.0.4"
   },
-  "bundledDependencies": [
-    "mpg123-decoder",
-    "silk-wasm",
-    "ws"
-  ],
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/ws": "^8.5.0",
+    "@types/node": "^20.19.43",
+    "tsup": "^8.5.1",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
+    "@tencent-connect/qqbot-connector": "1.2.0",
     "openclaw": "*"
   },
   "homepage": "https://github.com/tencent-connect/openclaw-qqbot",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/tencent-connect/openclaw-qqbot.git"
-  },
-  "bundleDependencies": [
-    "mpg123-decoder",
-    "silk-wasm",
-    "ws"
-  ]
+  }
 }

package/preload.cjs

@@ -9,25 +9,28 @@
  */
 "use strict";
 
+const path = require("node:path");
+const fs = require("node:fs");
 const { ensurePluginSdkSymlink } = require("./scripts/link-sdk-core.cjs");
 
-// 1) 同步创建 symlink
+// 1) 同步创建 symlink（确保 openclaw/plugin-sdk 可解析）
 ensurePluginSdkSymlink(__dirname, "[preload]");
 
-// 2) Node 22 原生支持 CJS require() 加载 ESM 模块
-//    同步加载插件入口，确保框架同步检查 register/activate 时能找到
-const _pluginModule = require("./dist/index.js");
+// 2) 加载编译产物（向后兼容：优先 .cjs，fallback .js）
+const cjsPath = path.join(__dirname, "dist", "index.cjs");
+const jsPath = path.join(__dirname, "dist", "index.js");
 
-// 3) 展平 default export：框架检查 register/activate 在顶级属性
-//    ESM 的 export default 在 require() 后变成 { default: plugin, ... }
-const _default = _pluginModule.default;
-const merged = Object.assign({}, _pluginModule);
-if (_default && typeof _default === "object") {
-  for (const key of Object.keys(_default)) {
-    if (!(key in merged)) {
-      merged[key] = _default[key];
+if (fs.existsSync(cjsPath)) {
+  module.exports = require(cjsPath);
+} else {
+  // 兼容旧版 tsc 编译产物（ESM .js），需展平 default export
+  const _mod = require(jsPath);
+  const _default = _mod.default;
+  const merged = Object.assign({}, _mod);
+  if (_default && typeof _default === "object") {
+    for (const key of Object.keys(_default)) {
+      if (!(key in merged)) merged[key] = _default[key];
     }
   }
+  module.exports = merged;
 }
-
-module.exports = merged;

package/scripts/link-sdk-core.cjs

@@ -3,12 +3,14 @@
  *
  * 被 preload.cjs 和 postinstall-link-sdk.js 共同使用，避免代码重复。
  * 必须是 CJS 格式，因为 preload.cjs 需要同步 require()。
+ *
+ * 注意：本模块不使用 child_process，避免被 openclaw 安全检查拦截。
  */
 "use strict";
 
 const path = require("node:path");
 const fs = require("node:fs");
-const { execSync } = require("node:child_process");
+const os = require("node:os");
 
 const CLI_NAMES = ["openclaw", "clawdbot", "moltbot"];
 
@@ -27,6 +29,104 @@ function compareVersionGte(version, target) {
   return true;
 }
 
+/**
+ * 获取全局 node_modules 候选目录列表（按优先级排序）。
+ * 不依赖 npm/child_process，通过常用路径推导。
+ */
+function getGlobalNodeModulesDirs() {
+  const dirs = [];
+  const npmPrefix = process.env.npm_config_prefix || process.env.PREFIX;
+  if (npmPrefix) {
+    // macOS: prefix/lib/node_modules; Windows: prefix/node_modules
+    dirs.push(path.join(npmPrefix, "lib", "node_modules"));
+    dirs.push(path.join(npmPrefix, "node_modules"));
+  }
+
+  // nvm / fnm / volta 等版本管理器
+  // process.execPath = .../versions/node/vX.Y.Z/bin/node
+  const execBase = path.dirname(path.dirname(process.execPath));
+  dirs.push(path.join(execBase, "lib", "node_modules"));
+  dirs.push(path.join(execBase, "node_modules"));
+
+  // Homebrew (macOS Intel)
+  dirs.push("/usr/local/lib/node_modules");
+  // Homebrew (macOS Apple Silicon)
+  dirs.push("/opt/homebrew/lib/node_modules");
+  // Linux / macOS 标准路径
+  dirs.push("/usr/lib/node_modules");
+  // pnpm global (XDG)
+  const xdgData = process.env.XDG_DATA_HOME || path.join(os.homedir(), ".local", "share");
+  dirs.push(path.join(xdgData, "pnpm", "global", "5", "node_modules"));
+  dirs.push(path.join(xdgData, "npm", "lib", "node_modules"));
+
+  return dirs;
+}
+
+/**
+ * 在全局 node_modules 目录中查找指定包的 package.json。
+ */
+function findPackageInGlobalDirs(packageName) {
+  for (const dir of getGlobalNodeModulesDirs()) {
+    const pkgPath = path.join(dir, packageName, "package.json");
+    try {
+      if (fs.existsSync(pkgPath)) return pkgPath;
+    } catch {}
+  }
+  return null;
+}
+
+/**
+ * 在 $PATH 中查找 CLI 可执行文件。
+ */
+function findCliInPath(cliName) {
+  const pathEnv = process.env.PATH || "";
+  const ext = process.platform === "win32" ? ".cmd" : "";
+  const dirs = pathEnv.split(path.delimiter);
+
+  for (const dir of dirs) {
+    const binPath = path.join(dir, cliName + ext);
+    try {
+      if (fs.existsSync(binPath)) return fs.realpathSync(binPath);
+    } catch {}
+  }
+  return null;
+}
+
+/**
+ * 从 CLI 二进制路径反查全局 node_modules 中的 package.json。
+ */
+function resolveGlobalRootFromBin(binPath, cliName) {
+  // 方式 A: bin -> ../lib/node_modules/<cli>/package.json
+  const binDir = path.dirname(binPath);
+  const c1 = path.resolve(binDir, "..", "lib", "node_modules", cliName, "package.json");
+  try { if (fs.existsSync(c1)) return c1; } catch {}
+
+  // 方式 B: bin -> ../package.json (如果在 node_modules/.bin 下)
+  const c2 = path.resolve(binDir, "..", "package.json");
+  try {
+    if (fs.existsSync(c2)) {
+      const parentDir = path.dirname(c2);
+      if (fs.existsSync(path.join(parentDir, "plugin-sdk")) || fs.existsSync(path.join(parentDir, "dist", "plugin-sdk"))) {
+        return c2;
+      }
+    }
+  } catch {}
+
+  return null;
+}
+
+/**
+ * 读取 package.json 中的版本号。
+ */
+function readPkgVersion(pkgPath) {
+  try {
+    const v = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
+    return v || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * 检查 openclaw 版本是否 >= 2026.3.22（需要 symlink 的最低版本）。
  * 如果无法检测版本，返回 true（保守策略：宁可多创建也不遗漏）。
@@ -34,29 +134,25 @@ function compareVersionGte(version, target) {
 function isOpenclawVersionRequiresSymlink() {
   const REQUIRED = [2026, 3, 22];
 
-  // Strategy 1: 从全局 openclaw 的 package.json 读取版本
-  try {
-    const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
-    for (const name of CLI_NAMES) {
-      const pkgPath = path.join(globalRoot, name, "package.json");
-      if (fs.existsSync(pkgPath)) {
-        const v = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).version;
-        if (v) return compareVersionGte(v, REQUIRED);
-      }
+  // Strategy 1: 从全局 node_modules 读取 package.json 版本
+  for (const name of CLI_NAMES) {
+    const pkgPath = findPackageInGlobalDirs(name);
+    if (pkgPath) {
+      const v = readPkgVersion(pkgPath);
+      if (v) return compareVersionGte(v, REQUIRED);
     }
-  } catch {}
+  }
 
-  // Strategy 2: 从 CLI 命令获取版本
+  // Strategy 2: 从 CLI 二进制反查到 package.json
   for (const name of CLI_NAMES) {
-    try {
-      const out = execSync(`${name} --version`, {
-        encoding: "utf-8",
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      }).trim();
-      const m = out.match(/(\d+\.\d+\.\d+)/);
-      if (m) return compareVersionGte(m[1], REQUIRED);
-    } catch {}
+    const binPath = findCliInPath(name);
+    if (binPath) {
+      const pkgPath = resolveGlobalRootFromBin(binPath, name);
+      if (pkgPath) {
+        const v = readPkgVersion(pkgPath);
+        if (v) return compareVersionGte(v, REQUIRED);
+      }
+    }
   }
 
   return true;
@@ -64,34 +160,22 @@ function isOpenclawVersionRequiresSymlink() {
 
 /**
  * 查找全局 openclaw 安装路径。
- * 三种策略依次尝试：npm root -g、which <cli>、从 extensions 目录推断。
+ * 三种策略依次尝试：全局 node_modules、$PATH 反查、extensions 目录推断。
  */
 function findOpenclawRoot(pluginRoot) {
-  // Strategy 1: npm root -g
-  try {
-    const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
-    for (const name of CLI_NAMES) {
-      const candidate = path.join(globalRoot, name);
-      if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
-    }
-  } catch {}
+  // Strategy 1: 从全局 node_modules 查找
+  for (const name of CLI_NAMES) {
+    const pkgPath = findPackageInGlobalDirs(name);
+    if (pkgPath) return path.dirname(pkgPath);
+  }
 
-  // Strategy 2: which <cli>
-  const whichCmd = process.platform === "win32" ? "where" : "which";
+  // Strategy 2: 从 $PATH 反查
   for (const name of CLI_NAMES) {
-    try {
-      const bin = execSync(`${whichCmd} ${name}`, {
-        encoding: "utf-8",
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      }).trim().split("\n")[0];
-      if (!bin) continue;
-      const realBin = fs.realpathSync(bin);
-      const c1 = path.resolve(path.dirname(realBin), "..", "lib", "node_modules", name);
-      if (fs.existsSync(path.join(c1, "package.json"))) return c1;
-      const c2 = path.resolve(path.dirname(realBin), "..");
-      if (fs.existsSync(path.join(c2, "package.json")) && fs.existsSync(path.join(c2, "plugin-sdk"))) return c2;
-    } catch {}
+    const binPath = findCliInPath(name);
+    if (binPath) {
+      const pkgPath = resolveGlobalRootFromBin(binPath, name);
+      if (pkgPath) return path.dirname(pkgPath);
+    }
   }
 
   // Strategy 3: 从 extensions 目录推断
@@ -100,11 +184,10 @@ function findOpenclawRoot(pluginRoot) {
   const dataDirName = path.basename(dataDir);
   const cliName = dataDirName.replace(/^\./, "");
   if (cliName) {
-    try {
-      const globalRoot = execSync("npm root -g", { encoding: "utf-8", timeout: 5000 }).trim();
-      const candidate = path.join(globalRoot, cliName);
-      if (fs.existsSync(path.join(candidate, "package.json"))) return candidate;
-    } catch {}
+    for (const dir of getGlobalNodeModulesDirs()) {
+      const pkgPath = path.join(dir, cliName, "package.json");
+      try { if (fs.existsSync(pkgPath)) return path.dirname(pkgPath); } catch {}
+    }
   }
 
   return null;

package/scripts/upgrade-via-npm.sh

@@ -929,22 +929,53 @@ NEW_VERSION=""; [ -f "$TARGET_DIR/package.json" ] && NEW_VERSION="$(read_pkg_ver
 PREFLIGHT_OK=true
 [ -z "$NEW_VERSION" ] && echo "  ❌ 无法读取版本号" && PREFLIGHT_OK=false || echo "  ✅ 版本: $NEW_VERSION"
 
-ENTRY=""; for f in "dist/index.js" "index.js"; do [ -f "$TARGET_DIR/$f" ] && ENTRY="$f" && break; done
+ENTRY=""; for f in "dist/index.cjs" "dist/index.js" "index.js"; do [ -f "$TARGET_DIR/$f" ] && ENTRY="$f" && break; done
 [ -z "$ENTRY" ] && echo "  ❌ 缺少入口文件" && PREFLIGHT_OK=false || echo "  ✅ 入口: $ENTRY"
 
+# 检测构建模式：bundled (tsup dist/index.cjs) vs unbundled (dist/src/ 独立文件)
+# 优先看 dist/src/ 是否存在；存在 → unbundled；否则依赖入口文件大小判断
+IS_BUNDLED=false
 if [ -d "$TARGET_DIR/dist/src" ]; then
-    JS_COUNT=$(find "$TARGET_DIR/dist/src" -name "*.js" -type f 2>/dev/null | wc -l | tr -d ' ')
-    echo "  ✅ dist/src/ 含 ${JS_COUNT} 个 JS"
-    [ "$JS_COUNT" -lt 5 ] && echo "  ❌ JS 数量异常偏少" && PREFLIGHT_OK=false
-else
-    echo "  ❌ 缺少 dist/src/"; PREFLIGHT_OK=false
+    IS_BUNDLED=false
+elif [ -f "$TARGET_DIR/$ENTRY" ]; then
+    BUNDLE_SIZE=$(wc -c < "$TARGET_DIR/$ENTRY" 2>/dev/null || echo "0")
+    # bundled 输出通常 > 200KB，unbundled 入口 < 50KB
+    [ "$BUNDLE_SIZE" -gt 200000 ] 2>/dev/null && IS_BUNDLED=true
 fi
 
-MISS=""
-for m in "dist/src/gateway.js" "dist/src/api.js" "dist/src/admin-resolver.js"; do
-    [ ! -f "$TARGET_DIR/$m" ] && MISS="$MISS $m"
-done
-[ -n "$MISS" ] && echo "  ❌ 缺少:$MISS" && PREFLIGHT_OK=false || echo "  ✅ 关键模块完整"
+if [ "$IS_BUNDLED" = "true" ]; then
+    echo "  ✅ bundled 构建 (${BUNDLE_SIZE} bytes)"
+
+    # 内联验证：bundle 中 grep 关键导出
+    BUNDLE_MISS=""
+    for sig in "GatewayConnection" "dispatchToOpenClaw" "qqbotPlugin" "sendText" "sendMedia"; do
+        if ! grep -qF "$sig" "$TARGET_DIR/$ENTRY" 2>/dev/null; then
+            BUNDLE_MISS="$BUNDLE_MISS $sig"
+        fi
+    done
+    [ -n "$BUNDLE_MISS" ] && echo "  ❌ bundle 缺少签名:$BUNDLE_MISS" && PREFLIGHT_OK=false || echo "  ✅ 关键模块签名完整"
+
+    # ws 依赖应该被 tsup noExternal 打包进 bundle
+    if grep -qF "ws" "$TARGET_DIR/$ENTRY" 2>/dev/null; then
+        echo "  ✅ ws bundled"
+    else
+        echo "  ⚠️  ws 未打包"
+    fi
+else
+    if [ -d "$TARGET_DIR/dist/src" ]; then
+        JS_COUNT=$(find "$TARGET_DIR/dist/src" -name "*.js" -type f 2>/dev/null | wc -l | tr -d ' ')
+        echo "  ✅ dist/src/ 含 ${JS_COUNT} 个 JS"
+        [ "$JS_COUNT" -lt 5 ] && echo "  ❌ JS 数量异常偏少" && PREFLIGHT_OK=false
+    else
+        echo "  ❌ 缺少 dist/src/"; PREFLIGHT_OK=false
+    fi
+
+    MISS=""
+    for m in "dist/src/gateway.js" "dist/src/api.js" "dist/src/admin-resolver.js"; do
+        [ ! -f "$TARGET_DIR/$m" ] && MISS="$MISS $m"
+    done
+    [ -n "$MISS" ] && echo "  ❌ 缺少:$MISS" && PREFLIGHT_OK=false || echo "  ✅ 关键模块完整"
+fi
 
 if [ -d "$TARGET_DIR/node_modules" ]; then
     BOK=true

package/scripts/upgrade-via-source.sh

@@ -319,14 +319,14 @@ find "${TMPDIR:-/tmp}" -maxdepth 1 -name ".openclaw-qqbot-nm-bak-*" -exec rm -rf
 # 导致新增的模块（如 streaming.js）缺失。
 echo "  清空 dist/ 确保全量重新构建..."
 rm -rf "$PROJ_DIR/dist"
-if [ ! -f "$PROJ_DIR/dist/index.js" ]; then
+if [ ! -f "$PROJ_DIR/dist/index.cjs" ] && [ ! -f "$PROJ_DIR/dist/index.js" ]; then
     echo "  dist/ 不存在，先执行构建..."
     if [ ! -d "$PROJ_DIR/node_modules" ]; then
         npm install --prefix "$PROJ_DIR" 2>&1 || true
     fi
     npm run --prefix "$PROJ_DIR" build 2>&1 || true
-    if [ ! -f "$PROJ_DIR/dist/index.js" ]; then
-        echo "  ❌ 构建失败：dist/index.js 未生成"
+    if [ ! -f "$PROJ_DIR/dist/index.cjs" ] && [ ! -f "$PROJ_DIR/dist/index.js" ]; then
+        echo "  ❌ 构建失败：dist/index.cjs 未生成"
         echo "  请手动执行: cd $PROJ_DIR && npm install && npm run build"
         exit 1
     fi
@@ -360,7 +360,7 @@ if [ -n "$_NM_BACKUP" ] && [ -d "$_NM_BACKUP" ]; then
     mv "$_NM_BACKUP" "$PROJ_DIR/node_modules"
     echo "  已恢复源码目录 node_modules"
 fi
-if [ ! -f "$_INSTALL_DIR/dist/index.js" ] || [ ! -f "$_INSTALL_DIR/preload.cjs" ]; then
+if { [ ! -f "$_INSTALL_DIR/dist/index.cjs" ] && [ ! -f "$_INSTALL_DIR/dist/index.js" ]; } || [ ! -f "$_INSTALL_DIR/preload.cjs" ]; then
     echo ""
     echo "❌ 插件安装失败！"
     echo "========================================="

package/skills/qqbot-channel/SKILL.md

@@ -1,12 +1,33 @@
 ---
 name: qqbot-channel
-description: QQ 频道管理技能。查询频道列表、子频道、成员、发帖、公告、日程等操作。使用 qqbot_channel_api 工具代理 QQ 开放平台 HTTP 接口，自动处理 Token 鉴权。当用户需要查看频道、管理子频道、查询成员、发布帖子/公告/日程时使用此技能。
+description: QQ 频道管理技能（非QQ群）。查询频道列表、子频道、成员、发帖、公告、日程等操作。使用 qqbot_platform_api 工具代理 QQ 开放平台 HTTP 接口，自动处理 Token 鉴权。仅用于 QQ 频道（Guild/Channel）。触发条件：用户提到「频道」「子频道」「guild」「channel」「帖子」「日程」「公告」。
 metadata: {"openclaw":{"emoji":"📡","requires":{"config":["channels.qqbot"]}}}
 ---
 
 # QQ 频道 API 请求指导
 
-`qqbot_channel_api` 是一个 QQ 开放平台 HTTP 代理工具，**自动填充鉴权 Token**。你只需要指定 HTTP 方法、API 路径、请求体和查询参数。
+> **本 Skill 仅处理 QQ 频道（Guild/Channel）操作。** 频道 ID 为纯数字，API 路径为 `/guilds/...` 和 `/channels/...`。
+
+`qqbot_platform_api` 是 QQ 开放平台统一 HTTP API 网关，**自动填充鉴权 Token**。你只需要指定 HTTP 方法、API 路径、请求体和查询参数即可调用频道相关接口。
+
+---
+
+## 🔀 适用范围（必读）
+
+QQ 频道是类似 Discord 的社区产品，层级结构为 **频道（Guild） → 子频道（Channel）**：
+
+| 层级 | 中文名 | 英文 | API 路径 | ID 格式 |
+|------|--------|------|----------|---------|
+| 顶层 | 频道 | Guild | `/guilds/{guild_id}` | 纯数字（如 `123456`） |
+| 次级 | 子频道 | Channel | `/channels/{channel_id}` | 纯数字（如 `789012`） |
+
+**核心特征**：
+- 频道内可以创建多个子频道（文字、语音、论坛、直播等）
+- 支持发帖、公告、日程等功能
+- 频道成员通过 `/guilds/{guild_id}/members` 管理
+- ID 为纯数字格式，API 路径以 `/guilds/` 或 `/channels/` 开头
+
+**触发关键词**：频道、子频道、guild、channel、帖子、日程、公告、论坛、频道成员
 
 ## 📚 详细参考文档
 
@@ -251,13 +272,14 @@ metadata: {"openclaw":{"emoji":"📡","requires":{"config":["channels.qqbot"]}}}
 
 ## ⚠️ 注意事项
 
-1. **路径中的占位符**（如 `{guild_id}`、`{channel_id}`）必须替换为实际值
-2. **query 参数的值必须为字符串类型**，如 `{ "limit": "100" }` 而非 `{ "limit": 100 }`
-3. **成员列表翻页**时可能返回重复成员，需按 `user.id` 去重
-4. **公告**的两种类型（消息公告和推荐子频道公告）会互相顶替
-5. **日程**的时间戳为毫秒级字符串
-6. **删除操作不可逆**，请谨慎使用
-7. **论坛操作**仅私域机器人可用
-8. **子频道分组**（type=4）的 `position` 必须 >= 2
-9. **日程操作**有频率限制：单个管理员每天 10 次，单个频道每天 100 次
-10. **头像/图标展示**：成员 `user.avatar` 和频道 `icon` 等图片 URL 必须使用 Markdown 图片语法 `![描述](URL)` 展示，禁止作为纯文本或超链接展示
+1. **适用范围**：本 Skill 仅处理 QQ 频道（Guild/Channel）操作，API 路径以 `/guilds/` 或 `/channels/` 开头，ID 为纯数字
+2. **路径中的占位符**（如 `{guild_id}`、`{channel_id}`）必须替换为实际的纯数字 ID
+3. **query 参数的值必须为字符串类型**，如 `{ "limit": "100" }` 而非 `{ "limit": 100 }`
+4. **成员列表翻页**时可能返回重复成员，需按 `user.id` 去重
+5. **公告**的两种类型（消息公告和推荐子频道公告）会互相顶替
+6. **日程**的时间戳为毫秒级字符串
+7. **删除操作不可逆**，请谨慎使用
+8. **论坛操作**仅私域机器人可用
+9. **子频道分组**（type=4）的 `position` 必须 >= 2
+10. **日程操作**有频率限制：单个管理员每天 10 次，单个频道每天 100 次
+11. **头像/图标展示**：成员 `user.avatar` 和频道 `icon` 等图片 URL 必须使用 Markdown 图片语法 `![描述](URL)` 展示，禁止作为纯文本或超链接展示