@tencent-connect/openclaw-qqbot 1.0.3-alpha.0 → 1.0.5-alpha.stream

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.0.3-alpha.0",
+  "version": "1.0.5-alpha.stream",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/upgrade-via-npm.sh

@@ -13,6 +13,8 @@ PKG_NAME="@tencent-connect/openclaw-qqbot"
 INSTALL_SRC=""
 APPID=""
 SECRET=""
+STREAM=""
+DEBUG=""
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -31,6 +33,8 @@ print_usage() {
     echo "  upgrade-via-npm.sh                              # 升级到 latest（默认）"
     echo "  upgrade-via-npm.sh --version <版本号>            # 升级到指定版本"
     echo "  upgrade-via-npm.sh --appid <appid> --secret <secret>  # 配置通道并启动"
+    echo "  upgrade-via-npm.sh --stream <yes|no>              # 是否启用流式消息（仅C2C私聊生效）"
+    echo "  upgrade-via-npm.sh --debug <yes|no>               # 是否启用 debug 模式"
     if [ -n "$LOCAL_VERSION" ]; then
         echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本（$LOCAL_VERSION）"
     else
@@ -40,6 +44,8 @@ print_usage() {
     echo "也可以通过环境变量设置:"
     echo "  QQBOT_APPID           QQ机器人 appid"
     echo "  QQBOT_SECRET          QQ机器人 secret"
+    echo "  QQBOT_STREAM          是否启用流式消息（yes/no）"
+    echo "  QQBOT_DEBUG           是否启用 debug 模式（yes/no）"
 }
 
 while [[ $# -gt 0 ]]; do
@@ -69,6 +75,16 @@ while [[ $# -gt 0 ]]; do
             SECRET="$2"
             shift 2
             ;;
+        --stream)
+            [ -z "$2" ] && echo "❌ --stream 需要参数" && exit 1
+            STREAM="$2"
+            shift 2
+            ;;
+        --debug)
+            [ -z "$2" ] && echo "❌ --debug 需要参数" && exit 1
+            DEBUG="$2"
+            shift 2
+            ;;
         -h|--help)
             print_usage
             exit 0
@@ -81,6 +97,8 @@ INSTALL_SRC="${INSTALL_SRC:-${PKG_NAME}@latest}"
 # 使用命令行参数或环境变量
 APPID="${APPID:-$QQBOT_APPID}"
 SECRET="${SECRET:-$QQBOT_SECRET}"
+STREAM="${STREAM:-$QQBOT_STREAM}"
+DEBUG="${DEBUG:-$QQBOT_DEBUG}"
 
 # 检测 CLI
 CMD=""
@@ -188,6 +206,114 @@ if [ -n "$APPID" ] && [ -n "$SECRET" ]; then
     fi
 fi
 
+# 配置 stream 选项（仅在明确指定时才配置）
+if [ -n "$STREAM" ]; then
+    echo ""
+    echo "配置 stream 选项..."
+    if [ "$STREAM" = "yes" ] || [ "$STREAM" = "y" ] || [ "$STREAM" = "true" ]; then
+        STREAM_VALUE="true"
+        echo "启用流式消息（仅C2C私聊生效）..."
+    else
+        STREAM_VALUE="false"
+        echo "禁用流式消息..."
+    fi
+
+    CURRENT_STREAM_VALUE=$(node -e "
+      const fs = require('fs');
+      const path = require('path');
+      const home = process.env.HOME;
+      for (const app of ['openclaw', 'clawdbot', 'moltbot']) {
+        const f = path.join(home, '.' + app, app + '.json');
+        if (!fs.existsSync(f)) continue;
+        try {
+          const cfg = JSON.parse(fs.readFileSync(f, 'utf8'));
+          const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
+          for (const key of keys) {
+            const ch = cfg.channels && cfg.channels[key];
+            if (!ch) continue;
+            if (typeof ch.streamSupport === 'boolean') { process.stdout.write(String(ch.streamSupport)); process.exit(0); }
+          }
+        } catch {}
+      }
+    " 2>/dev/null || true)
+
+    if [ "$CURRENT_STREAM_VALUE" = "$STREAM_VALUE" ]; then
+        echo "  ✅ stream 配置已是目标值，跳过写入"
+    elif $CMD config set channels.qqbot.streamSupport "$STREAM_VALUE" 2>&1; then
+        echo "  ✅ stream 配置成功"
+    else
+        echo "  ⚠️  $CMD config set 失败，尝试直接编辑配置文件..."
+        if [ -f "$APP_CONFIG" ] && node -e "
+          const fs = require('fs');
+          const cfg = JSON.parse(fs.readFileSync('$APP_CONFIG', 'utf-8'));
+          if (!cfg.channels) cfg.channels = {};
+          if (!cfg.channels.qqbot) cfg.channels.qqbot = {};
+          const target = $STREAM_VALUE;
+          if (cfg.channels.qqbot.streamSupport === target) process.exit(0);
+          cfg.channels.qqbot.streamSupport = target;
+          fs.writeFileSync('$APP_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
+        " 2>&1; then
+            echo "  ✅ stream 配置成功（直接编辑配置文件）"
+        else
+            echo "  ⚠️  stream 配置设置失败，不影响后续运行"
+        fi
+    fi
+fi
+
+# 配置 debug 选项（仅在明确指定时才配置）
+if [ -n "$DEBUG" ]; then
+    echo ""
+    echo "配置 debug 选项..."
+    if [ "$DEBUG" = "yes" ] || [ "$DEBUG" = "y" ] || [ "$DEBUG" = "true" ]; then
+        DEBUG_VALUE="true"
+        echo "启用 debug 模式..."
+    else
+        DEBUG_VALUE="false"
+        echo "禁用 debug 模式..."
+    fi
+
+    CURRENT_DEBUG_VALUE=$(node -e "
+      const fs = require('fs');
+      const path = require('path');
+      const home = process.env.HOME;
+      for (const app of ['openclaw', 'clawdbot', 'moltbot']) {
+        const f = path.join(home, '.' + app, app + '.json');
+        if (!fs.existsSync(f)) continue;
+        try {
+          const cfg = JSON.parse(fs.readFileSync(f, 'utf8'));
+          const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
+          for (const key of keys) {
+            const ch = cfg.channels && cfg.channels[key];
+            if (!ch) continue;
+            if (typeof ch.debug === 'boolean') { process.stdout.write(String(ch.debug)); process.exit(0); }
+          }
+        } catch {}
+      }
+    " 2>/dev/null || true)
+
+    if [ "$CURRENT_DEBUG_VALUE" = "$DEBUG_VALUE" ]; then
+        echo "  ✅ debug 配置已是目标值，跳过写入"
+    elif $CMD config set channels.qqbot.debug "$DEBUG_VALUE" 2>&1; then
+        echo "  ✅ debug 配置成功"
+    else
+        echo "  ⚠️  $CMD config set 失败，尝试直接编辑配置文件..."
+        if [ -f "$APP_CONFIG" ] && node -e "
+          const fs = require('fs');
+          const cfg = JSON.parse(fs.readFileSync('$APP_CONFIG', 'utf-8'));
+          if (!cfg.channels) cfg.channels = {};
+          if (!cfg.channels.qqbot) cfg.channels.qqbot = {};
+          const target = $DEBUG_VALUE;
+          if (cfg.channels.qqbot.debug === target) process.exit(0);
+          cfg.channels.qqbot.debug = target;
+          fs.writeFileSync('$APP_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
+        " 2>&1; then
+            echo "  ✅ debug 配置成功（直接编辑配置文件）"
+        else
+            echo "  ⚠️  debug 配置设置失败，不影响后续运行"
+        fi
+    fi
+fi
+
 # [4/4] 重启网关
 echo ""
 echo "[4/4] 重启网关..."

package/scripts/upgrade-via-source.sh

@@ -26,6 +26,7 @@ APPID=""
 SECRET=""
 MARKDOWN=""
 STREAM=""
+DEBUG=""
 
 while [[ $# -gt 0 ]]; do
     case $1 in
@@ -45,6 +46,10 @@ while [[ $# -gt 0 ]]; do
             STREAM="$2"
             shift 2
             ;;
+        --debug)
+            DEBUG="$2"
+            shift 2
+            ;;
         -h|--help)
             echo "用法: $0 [选项]"
             echo ""
@@ -53,6 +58,7 @@ while [[ $# -gt 0 ]]; do
             echo "  --secret <secret>     QQ机器人 secret"
             echo "  --markdown <yes|no>   是否启用 markdown 消息格式（默认: no）"
             echo "  --stream <yes|no>     是否启用流式消息（仅C2C私聊生效，默认: no）"
+            echo "  --debug <yes|no>      是否启用 debug 模式（默认: no）"
             echo "  -h, --help            显示帮助信息"
             echo ""
             echo "也可以通过环境变量设置:"
@@ -61,6 +67,7 @@ while [[ $# -gt 0 ]]; do
             echo "  QQBOT_TOKEN           QQ机器人 token (appid:secret)"
             echo "  QQBOT_MARKDOWN        是否启用 markdown（yes/no）"
             echo "  QQBOT_STREAM          是否启用流式消息（yes/no）"
+            echo "  QQBOT_DEBUG           是否启用 debug 模式（yes/no）"
             echo ""
             echo "不带参数时，将使用已有配置直接启动。"
             echo ""
@@ -80,6 +87,7 @@ APPID="${APPID:-$QQBOT_APPID}"
 SECRET="${SECRET:-$QQBOT_SECRET}"
 MARKDOWN="${MARKDOWN:-$QQBOT_MARKDOWN}"
 STREAM="${STREAM:-$QQBOT_STREAM}"
+DEBUG="${DEBUG:-$QQBOT_DEBUG}"
 
 echo "========================================="
 echo "  qqbot 一键更新启动脚本"
@@ -87,9 +95,10 @@ echo "========================================="
 
 # 1. 备份已有 qqbot 通道配置，防止升级过程丢失
 echo ""
-echo "[1/7] 备份已有配置..."
+echo "[1/8] 备份已有配置..."
 SAVED_QQBOT_TOKEN=""
 SAVED_STREAM_SUPPORT=""
+SAVED_DEBUG=""
 for APP_NAME in openclaw clawdbot moltbot; do
     CONFIG_FILE="$HOME/.$APP_NAME/$APP_NAME.json"
     if [ -f "$CONFIG_FILE" ]; then
@@ -116,9 +125,22 @@ for APP_NAME in openclaw clawdbot moltbot; do
                 }
             " 2>/dev/null || true)
         fi
+        # 同时备份 debug 配置
+        if [ -z "$SAVED_DEBUG" ]; then
+            SAVED_DEBUG=$(node -e "
+                const cfg = JSON.parse(require('fs').readFileSync('$CONFIG_FILE', 'utf8'));
+                const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
+                for (const key of keys) {
+                    const ch = cfg.channels && cfg.channels[key];
+                    if (!ch) continue;
+                    if (typeof ch.debug === 'boolean') { process.stdout.write(String(ch.debug)); process.exit(0); }
+                }
+            " 2>/dev/null || true)
+        fi
         if [ -n "$SAVED_QQBOT_TOKEN" ]; then
             echo "已备份 qqbot 通道 token: ${SAVED_QQBOT_TOKEN:0:10}..."
             [ -n "$SAVED_STREAM_SUPPORT" ] && echo "已备份 streamSupport: $SAVED_STREAM_SUPPORT"
+            [ -n "$SAVED_DEBUG" ] && echo "已备份 debug: $SAVED_DEBUG"
             break
         fi
     fi
@@ -179,11 +201,39 @@ if [ -z "$SAVED_QQBOT_TOKEN" ] && [ -d "$HOME/.openclaw" ]; then
             echo "已从 ~/.openclaw/openclaw.json.bak* 找到 streamSupport 备份: $SAVED_STREAM_SUPPORT"
         fi
     fi
+
+    # 同时从备份文件中恢复 debug
+    if [ -z "$SAVED_DEBUG" ]; then
+        SAVED_DEBUG=$(node -e "
+          const fs = require('fs');
+          const path = require('path');
+          const dir = path.join(process.env.HOME, '.openclaw');
+          const files = fs.readdirSync(dir)
+            .filter((n) => /^openclaw\.json\.bak(\.\d+)?$/.test(n))
+            .map((n) => path.join(dir, n))
+            .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+          for (const f of files) {
+            try {
+              const cfg = JSON.parse(fs.readFileSync(f, 'utf8'));
+              const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
+              for (const key of keys) {
+                const ch = cfg.channels && cfg.channels[key];
+                if (!ch) continue;
+                if (typeof ch.debug === 'boolean') { process.stdout.write(String(ch.debug)); process.exit(0); }
+              }
+            } catch {}
+          }
+        " 2>/dev/null || true)
+
+        if [ -n "$SAVED_DEBUG" ]; then
+            echo "已从 ~/.openclaw/openclaw.json.bak* 找到 debug 备份: $SAVED_DEBUG"
+        fi
+    fi
 fi
 
 # 2. 移除老版本
 echo ""
-echo "[2/7] 移除老版本..."
+echo "[2/8] 移除老版本..."
 if [ -f "$PROJ_DIR/scripts/cleanup-legacy-plugins.sh" ]; then
     bash "$PROJ_DIR/scripts/cleanup-legacy-plugins.sh"
 else
@@ -192,7 +242,7 @@ fi
 
 # 3. 安装当前版本
 echo ""
-echo "[3/7] 安装当前版本（源码安装）..."
+echo "[3/8] 安装当前版本（源码安装）..."
 
 echo "检查当前目录: $(pwd)"
 echo "检查openclaw版本: $(openclaw --version 2>/dev/null || echo 'openclaw not found')"
@@ -323,7 +373,7 @@ fi
 
 # 4. 配置机器人通道（仅在需要变更时写入配置，避免无意义覆盖）
 echo ""
-echo "[4/7] 配置机器人通道..."
+echo "[4/8] 配置机器人通道..."
 
 # 读取当前 qqbot token（兼容多 key）
 CURRENT_QQBOT_TOKEN=""
@@ -401,7 +451,7 @@ fi
 
 # 5. 配置 markdown 选项（仅在明确指定时才配置）
 echo ""
-echo "[5/7] 配置 markdown 选项..."
+echo "[5/8] 配置 markdown 选项..."
 
 if [ -n "$MARKDOWN" ]; then
     # 设置 markdown 配置
@@ -462,7 +512,7 @@ fi
 
 # 6. 配置 stream 选项（优先命令行参数，其次自动恢复备份值）
 echo ""
-echo "[6/7] 配置 stream 选项..."
+echo "[6/8] 配置 stream 选项..."
 
 # 如果命令行未指定 --stream，但备份中有 streamSupport 值，则自动恢复
 if [ -z "$STREAM" ] && [ "$SAVED_STREAM_SUPPORT" = "true" ]; then
@@ -557,9 +607,79 @@ else
     echo "未指定 stream 选项，使用已有配置"
 fi
 
-# 7. 启动 openclaw
+# 7. 配置 debug 选项（优先命令行参数，其次自动恢复备份值）
+echo ""
+echo "[7/8] 配置 debug 选项..."
+
+# 如果命令行未指定 --debug，但备份中有 debug 值，则自动恢复
+if [ -z "$DEBUG" ] && [ "$SAVED_DEBUG" = "true" ]; then
+    DEBUG="yes"
+    echo "自动恢复备份的 debug=true 配置..."
+elif [ -z "$DEBUG" ] && [ "$SAVED_DEBUG" = "false" ]; then
+    DEBUG="no"
+    echo "自动恢复备份的 debug=false 配置..."
+fi
+
+if [ -n "$DEBUG" ]; then
+    # 设置 debug 配置
+    if [ "$DEBUG" = "yes" ] || [ "$DEBUG" = "y" ] || [ "$DEBUG" = "true" ]; then
+        DEBUG_VALUE="true"
+        echo "启用 debug 模式..."
+    else
+        DEBUG_VALUE="false"
+        echo "禁用 debug 模式..."
+    fi
+
+    CURRENT_DEBUG_VALUE=$(node -e "
+      const fs = require('fs');
+      const path = require('path');
+      const home = process.env.HOME;
+      for (const app of ['openclaw', 'clawdbot', 'moltbot']) {
+        const f = path.join(home, '.' + app, app + '.json');
+        if (!fs.existsSync(f)) continue;
+        try {
+          const cfg = JSON.parse(fs.readFileSync(f, 'utf8'));
+          const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
+          for (const key of keys) {
+            const ch = cfg.channels && cfg.channels[key];
+            if (!ch) continue;
+            if (typeof ch.debug === 'boolean') { process.stdout.write(String(ch.debug)); process.exit(0); }
+          }
+        } catch {}
+      }
+    " 2>/dev/null || true)
+
+    if [ "$CURRENT_DEBUG_VALUE" = "$DEBUG_VALUE" ]; then
+        echo "✅ debug 配置已是目标值，跳过写入（避免配置覆盖提示）"
+    elif openclaw config set channels.qqbot.debug "$DEBUG_VALUE" 2>&1; then
+        echo "✅ debug配置成功"
+        _config_changed=1
+    else
+        echo "⚠️  openclaw config set 失败，尝试直接编辑配置文件..."
+        OPENCLAW_CONFIG="$HOME/.openclaw/openclaw.json"
+        if [ -f "$OPENCLAW_CONFIG" ] && node -e "
+          const fs = require('fs');
+          const cfg = JSON.parse(fs.readFileSync('$OPENCLAW_CONFIG', 'utf-8'));
+          if (!cfg.channels) cfg.channels = {};
+          if (!cfg.channels.qqbot) cfg.channels.qqbot = {};
+          const target = $DEBUG_VALUE;
+          if (cfg.channels.qqbot.debug === target) process.exit(0);
+          cfg.channels.qqbot.debug = target;
+          fs.writeFileSync('$OPENCLAW_CONFIG', JSON.stringify(cfg, null, 4) + '\n');
+        " 2>&1; then
+            echo "✅ debug配置成功（直接编辑配置文件）"
+            _config_changed=1
+        else
+            echo "⚠️  debug配置设置失败，不影响后续运行"
+        fi
+    fi
+else
+    echo "未指定 debug 选项，使用已有配置"
+fi
+
+# 8. 启动 openclaw
 echo ""
-echo "[7/7] 启动 openclaw..."
+echo "[8/8] 启动 openclaw..."
 echo "========================================="
 
 # 检查openclaw是否可用

package/src/api.ts

@@ -13,12 +13,28 @@ const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
 // 运行时配置
 let currentMarkdownSupport = false;
 
+// 模块级 logger：通过 initApiConfig 注入，未注入时 fallback 到 console
+let apiLog: {
+  info: (msg: string) => void;
+  error: (msg: string) => void;
+} = {
+  info: console.log.bind(console),
+  error: console.error.bind(console),
+};
+
 /**
  * 初始化 API 配置
  * @param options.markdownSupport - 是否支持 markdown 消息（默认 false，需要机器人具备该权限才能启用）
+ * @param options.log - 可选的 logger 接口，注入后 API 日志将通过此 logger 输出（而非 console）
  */
-export function initApiConfig(options: { markdownSupport?: boolean }): void {
+export function initApiConfig(options: {
+  markdownSupport?: boolean;
+  log?: { info: (msg: string) => void; error: (msg: string) => void };
+}): void {
   currentMarkdownSupport = options.markdownSupport === true;
+  if (options.log) {
+    apiLog = options.log;
+  }
 }
 
 /**
@@ -54,7 +70,7 @@ export async function getAccessToken(appId: string, clientSecret: string): Promi
   // Singleflight: 如果当前 appId 已有进行中的 Token 获取请求，复用它
   let fetchPromise = tokenFetchPromises.get(normalizedAppId);
   if (fetchPromise) {
-    console.log(`[qqbot-api:${normalizedAppId}] Token fetch in progress, waiting for existing request...`);
+    apiLog.info(`[qqbot-api:${normalizedAppId}] Token fetch in progress, waiting for existing request...`);
     return fetchPromise;
   }
 
@@ -80,7 +96,9 @@ async function doFetchToken(appId: string, clientSecret: string): Promise<string
   const requestHeaders = { "Content-Type": "application/json" };
   
   // 打印请求信息（隐藏敏感信息）
-  console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL}`);
+  apiLog.info(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL}`);
+  apiLog.info(`[qqbot-api:${appId}] >>> Headers: ${JSON.stringify(requestHeaders, null, 2)}`);
+  apiLog.info(`[qqbot-api:${appId}] >>> Body: ${JSON.stringify({ appId, clientSecret: "***" }, null, 2)}`);
 
   let response: Response;
   try {
@@ -90,7 +108,7 @@ async function doFetchToken(appId: string, clientSecret: string): Promise<string
       body: JSON.stringify(requestBody),
     });
   } catch (err) {
-    console.error(`[qqbot-api:${appId}] <<< Network error:`, err);
+    apiLog.error(`[qqbot-api:${appId}] <<< Network error: ${err instanceof Error ? err.message : String(err)}`);
     throw new Error(`Network error getting access_token: ${err instanceof Error ? err.message : String(err)}`);
   }
 
@@ -99,18 +117,31 @@ async function doFetchToken(appId: string, clientSecret: string): Promise<string
   response.headers.forEach((value, key) => {
     responseHeaders[key] = value;
   });
-  console.log(`[qqbot-api:${appId}] <<< Status: ${response.status} ${response.statusText}`);
+  apiLog.info(`[qqbot-api:${appId}] <<< Status: ${response.status} ${response.statusText}`);
+  apiLog.info(`[qqbot-api:${appId}] <<< Response Headers: ${JSON.stringify(responseHeaders, null, 2)}`);
 
   let data: { access_token?: string; expires_in?: number };
   let rawBody: string;
   try {
     rawBody = await response.text();
-    // 隐藏 token 值
-    const logBody = rawBody.replace(/"access_token"\s*:\s*"[^"]+"/g, '"access_token": "***"');
-    console.log(`[qqbot-api:${appId}] <<< Body:`, logBody);
+    // 脱敏 token 值，格式化打印
+    try {
+      const parsed = JSON.parse(rawBody);
+      const logParsed = { ...parsed };
+      if (typeof logParsed.access_token === "string" && logParsed.access_token.length > 6) {
+        logParsed.access_token = `${logParsed.access_token.slice(0, 6)}***`;
+      } else if (logParsed.access_token) {
+        logParsed.access_token = "***";
+      }
+      apiLog.info(`[qqbot-api:${appId}] <<< Response Body: ${JSON.stringify(logParsed, null, 2)}`);
+    } catch {
+      // raw body 也做脱敏：替换可能的 access_token 值
+      const sanitized = rawBody.replace(/"access_token"\s*:\s*"([^"]{6})[^"]*"/g, '"access_token":"$1***"');
+      apiLog.info(`[qqbot-api:${appId}] <<< Response Body (raw): ${sanitized.slice(0, 2000)}`);
+    }
     data = JSON.parse(rawBody) as { access_token?: string; expires_in?: number };
   } catch (err) {
-    console.error(`[qqbot-api:${appId}] <<< Parse error:`, err);
+    apiLog.error(`[qqbot-api:${appId}] <<< Parse error: ${err instanceof Error ? err.message : String(err)}`);
     throw new Error(`Failed to parse access_token response: ${err instanceof Error ? err.message : String(err)}`);
   }
 
@@ -126,7 +157,7 @@ async function doFetchToken(appId: string, clientSecret: string): Promise<string
     appId,
   });
 
-  console.log(`[qqbot-api:${appId}] Token cached, expires at: ${new Date(expiresAt).toISOString()}`);
+  apiLog.info(`[qqbot-api:${appId}] Token cached, expires at: ${new Date(expiresAt).toISOString()}`);
   return data.access_token;
 }
 
@@ -138,10 +169,10 @@ export function clearTokenCache(appId?: string): void {
   if (appId) {
     const normalizedAppId = String(appId).trim();
     tokenCacheMap.delete(normalizedAppId);
-    console.log(`[qqbot-api:${normalizedAppId}] Token cache cleared manually.`);
+    apiLog.info(`[qqbot-api:${normalizedAppId}] Token cache cleared manually.`);
   } else {
     tokenCacheMap.clear();
-    console.log(`[qqbot-api] All token caches cleared.`);
+    apiLog.info(`[qqbot-api] All token caches cleared.`);
   }
 }
 
@@ -208,13 +239,26 @@ export async function apiRequest<T = unknown>(
     options.body = JSON.stringify(body);
   }
 
-  // 打印请求信息
-  console.log(`[qqbot-api] >>> ${method} ${url} (timeout: ${timeout}ms)`);
+  // 打印请求信息：方法、URL、请求头、请求体（JSON 格式化）
+  apiLog.info(`[qqbot-api] >>> ${method} ${url} (timeout: ${timeout}ms)`);
+  // 脱敏 Authorization 头（只显示前缀 + token 前6位 + ***）
+  const logHeaders = { ...headers };
+  if (logHeaders.Authorization) {
+    const parts = logHeaders.Authorization.split(" ");
+    if (parts.length === 2 && parts[1].length > 6) {
+      logHeaders.Authorization = `${parts[0]} ${parts[1].slice(0, 6)}***`;
+    } else {
+      logHeaders.Authorization = "***";
+    }
+  }
+  apiLog.info(`[qqbot-api] >>> Headers: ${JSON.stringify(logHeaders, null, 2)}`);
   if (body) {
     const logBody = { ...body } as Record<string, unknown>;
+    // 脱敏：base64 文件数据只显示长度
     if (typeof logBody.file_data === "string") {
       logBody.file_data = `<base64 ${(logBody.file_data as string).length} chars>`;
     }
+    apiLog.info(`[qqbot-api] >>> Body: ${JSON.stringify(logBody, null, 2)}`);
   }
 
   let res: Response;
@@ -223,25 +267,34 @@ export async function apiRequest<T = unknown>(
   } catch (err) {
     clearTimeout(timeoutId);
     if (err instanceof Error && err.name === "AbortError") {
-      console.error(`[qqbot-api] <<< Request timeout after ${timeout}ms`);
+      apiLog.error(`[qqbot-api] <<< Request timeout after ${timeout}ms`);
       throw new Error(`Request timeout[${path}]: exceeded ${timeout}ms`);
     }
-    console.error(`[qqbot-api] <<< Network error:`, err);
+    apiLog.error(`[qqbot-api] <<< Network error: ${err instanceof Error ? err.message : String(err)}`);
     throw new Error(`Network error [${path}]: ${err instanceof Error ? err.message : String(err)}`);
   } finally {
     clearTimeout(timeoutId);
   }
 
+  // 打印响应头
   const responseHeaders: Record<string, string> = {};
   res.headers.forEach((value, key) => {
     responseHeaders[key] = value;
   });
-  console.log(`[qqbot-api] <<< Status: ${res.status} ${res.statusText}`);
+  apiLog.info(`[qqbot-api] <<< Status: ${res.status} ${res.statusText}`);
+  apiLog.info(`[qqbot-api] <<< Response Headers: ${JSON.stringify(responseHeaders, null, 2)}`);
 
   let data: T;
   let rawBody: string;
   try {
     rawBody = await res.text();
+    // 打印响应体（尝试 JSON 格式化）
+    try {
+      const parsed = JSON.parse(rawBody);
+      apiLog.info(`[qqbot-api] <<< Response Body: ${JSON.stringify(parsed, null, 2)}`);
+    } catch {
+      apiLog.info(`[qqbot-api] <<< Response Body (raw): ${rawBody.slice(0, 2000)}`);
+    }
     data = JSON.parse(rawBody) as T;
   } catch (err) {
     throw new Error(`Failed to parse response[${path}]: ${err instanceof Error ? err.message : String(err)}`);
@@ -285,7 +338,7 @@ async function apiRequestWithRetry<T = unknown>(
 
       if (attempt < maxRetries) {
         const delay = UPLOAD_BASE_DELAY_MS * Math.pow(2, attempt);
-        console.log(`[qqbot-api] Upload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${errMsg.slice(0, 100)}`);
+        apiLog.info(`[qqbot-api] Upload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${errMsg.slice(0, 100)}`);
         await new Promise(resolve => setTimeout(resolve, delay));
       }
     }
@@ -304,8 +357,6 @@ export async function getGatewayUrl(accessToken: string): Promise<string> {
 export interface MessageResponse {
   id: string;
   timestamp: number | string;
-  /** 流式消息ID，用于后续分片 */
-  stream_id?: string;
 }
 
 function buildMessageBody(
@@ -639,7 +690,7 @@ export function startBackgroundTokenRefresh(
   options?: BackgroundTokenRefreshOptions
 ): void {
   if (backgroundRefreshControllers.has(appId)) {
-    console.log(`[qqbot-api:${appId}] Background token refresh already running`);
+    apiLog.info(`[qqbot-api:${appId}] Background token refresh already running`);
     return;
   }
 

package/src/config.ts

@@ -83,6 +83,7 @@ export function resolveQQBotAccount(
       imageServerBaseUrl: qqbot?.imageServerBaseUrl,
       markdownSupport: qqbot?.markdownSupport ?? true,
       streamSupport: qqbot?.streamSupport,
+      debug: qqbot?.debug,
     };
     appId = normalizeAppId(qqbot?.appId);
   } else {
@@ -120,6 +121,7 @@ export function resolveQQBotAccount(
     imageServerBaseUrl: accountConfig.imageServerBaseUrl || process.env.QQBOT_IMAGE_SERVER_BASE_URL,
     markdownSupport: accountConfig.markdownSupport !== false,
     streamSupport: accountConfig.streamSupport !== false,
+    debug: accountConfig.debug === true,
     config: accountConfig,
   };
 }