@henryxiaoyang/wechat-access-unqclawed 1.0.14 → 1.0.16

package/auth/device-bind.ts

@@ -0,0 +1,151 @@
+/**
+ * @file device-bind.ts
+ * @description 设备绑定流程：生成企微客服链接 → 用户在微信中打开 → 轮询绑定状态
+ *
+ * 登录拿到 token 后，微信里还看不到对话入口。
+ * 必须通过客服链接完成设备绑定，微信中才会出现聊天入口。
+ */
+
+import type { QClawAPI } from "./qclaw-api.js";
+import { nested } from "./utils.js";
+
+/** 默认的企微客服 open_kfid */
+const DEFAULT_OPEN_KFID = "wkzLlJLAAAfbxEV3ZcS-lHZxkaKmpejQ";
+
+/** 轮询间隔（毫秒） */
+const POLL_INTERVAL_MS = 2000;
+
+/** 默认超时（毫秒） */
+const DEFAULT_TIMEOUT_MS = 300_000; // 5 分钟
+
+export interface DeviceBindOptions {
+  /** 已认证的 QClawAPI 实例 */
+  api: QClawAPI;
+  /** 企微客服 open_kfid（可选，有默认值） */
+  openKfId?: string;
+  /** 轮询超时（毫秒） */
+  timeoutMs?: number;
+  /** 日志输出 */
+  log?: {
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+  };
+  /** 显示二维码（终端场景用，传入 URL 后在终端渲染 QR） */
+  showQr?: (url: string) => Promise<void>;
+}
+
+export interface DeviceBindResult {
+  /** 是否绑定成功 */
+  success: boolean;
+  /** 客服链接 URL（即使未成功也可能有值） */
+  contactUrl?: string;
+  /** 绑定成功时的微信昵称 */
+  nickname?: string;
+  /** 描述信息 */
+  message: string;
+}
+
+/**
+ * 在终端显示二维码的默认实现
+ */
+async function defaultShowQr(url: string): Promise<void> {
+  try {
+    const qrterm = await import("qrcode-terminal");
+    const generate = qrterm.default?.generate ?? qrterm.generate;
+    generate(url, { small: true }, (qrcode: string) => {
+      console.log(qrcode);
+    });
+  } catch {
+    // qrcode-terminal 不可用，静默跳过
+  }
+}
+
+/**
+ * 执行设备绑定流程
+ *
+ * 步骤：
+ * 1. 调用 4018 接口生成企微客服链接
+ * 2. 展示链接（终端 QR / URL）供用户在微信中打开
+ * 3. 轮询 4019 接口等待绑定完成
+ */
+export async function performDeviceBinding(options: DeviceBindOptions): Promise<DeviceBindResult> {
+  const {
+    api,
+    openKfId = DEFAULT_OPEN_KFID,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    log = { info: console.log, warn: console.warn, error: console.error },
+    showQr = defaultShowQr,
+  } = options;
+
+  // 1. 生成企微客服链接
+  log.info("[device-bind] 生成企微客服链接...");
+  let linkResult;
+  try {
+    linkResult = await api.generateContactLink(openKfId);
+  } catch (e) {
+    const msg = `生成客服链接失败: ${e instanceof Error ? e.message : String(e)}`;
+    log.warn(`[device-bind] ${msg}`);
+    return { success: false, message: msg };
+  }
+
+  if (!linkResult.success) {
+    const msg = `生成客服链接失败: ${linkResult.message ?? "未知错误"}`;
+    log.warn(`[device-bind] ${msg}`);
+    return { success: false, message: msg };
+  }
+
+  const linkData = linkResult.data as Record<string, unknown>;
+  const contactUrl =
+    (nested(linkData, "url") as string) ||
+    (nested(linkData, "data", "url") as string) ||
+    (nested(linkData, "resp", "url") as string) ||
+    "";
+
+  if (!contactUrl) {
+    const msg = "服务端未返回客服链接 URL";
+    log.warn(`[device-bind] ${msg}`);
+    return { success: false, message: msg };
+  }
+
+  // 2. 展示链接
+  console.log("\n" + "=".repeat(60));
+  console.log("  请用「控制端微信」打开下方链接，完成设备绑定");
+  console.log("  绑定后微信中会出现对话入口");
+  console.log("=".repeat(60));
+  await showQr(contactUrl);
+  console.log(`\n链接: ${contactUrl}\n`);
+
+  // 3. 轮询绑定状态
+  log.info("[device-bind] 等待设备绑定...");
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+    try {
+      const status = await api.queryDeviceByGuid();
+      if (status.success) {
+        const sd = status.data as Record<string, unknown>;
+        const nickname =
+          (nested(sd, "nickname") as string) ||
+          (nested(sd, "data", "nickname") as string);
+        const externalUserId =
+          (nested(sd, "external_user_id") as string) ||
+          (nested(sd, "data", "external_user_id") as string);
+
+        if (nickname || externalUserId) {
+          const msg = `设备绑定成功!${nickname ? ` 微信昵称: ${nickname}` : ""}`;
+          log.info(`[device-bind] ${msg}`);
+          return { success: true, contactUrl, nickname: nickname || undefined, message: msg };
+        }
+      }
+    } catch {
+      // 轮询失败不中断，继续重试
+    }
+  }
+
+  return {
+    success: false,
+    contactUrl,
+    message: "设备绑定超时。请确认已在微信中打开上方链接，然后重启 Gateway 重试。",
+  };
+}

package/auth/index.ts

@@ -17,5 +17,7 @@ export { QClawAPI } from "./qclaw-api.js";
 export { loadState, saveState, clearState } from "./state-store.js";
 export { performLogin } from "./wechat-login.js";
 export type { PerformLoginOptions } from "./wechat-login.js";
+export { performDeviceBinding } from "./device-bind.js";
+export type { DeviceBindOptions, DeviceBindResult } from "./device-bind.js";
 export { buildAuthUrl, fetchQrUuid, fetchQrImageDataUrl, pollQrStatus } from "./wechat-qr-poll.js";
 export type { QrPollResult } from "./wechat-qr-poll.js";

package/auth/qclaw-api.ts

@@ -70,9 +70,14 @@ export class QClawAPI {
     }
 
     if (ret === 0 || commonCode === 0) {
+      // 匹配 Python 的 or 语义：空对象 {} 视为 falsy 跳过
+      const nonEmpty = (v: unknown): unknown =>
+        v != null && typeof v === "object" && !Array.isArray(v) && Object.keys(v as Record<string, unknown>).length === 0
+          ? undefined
+          : v;
       const respData =
-        nested(data, "data", "resp", "data") ??
-        nested(data, "data", "data") ??
+        nonEmpty(nested(data, "data", "resp", "data")) ??
+        nonEmpty(nested(data, "data", "data")) ??
         data.data ??
         data;
       return { success: true, data: respData as Record<string, unknown> };

package/auth/wechat-login.ts

@@ -11,6 +11,7 @@ import type { QClawEnvironment, LoginCredentials, PersistedAuthState } from "./t
 import { QClawAPI } from "./qclaw-api.js";
 import { saveState } from "./state-store.js";
 import { nested } from "./utils.js";
+import { performDeviceBinding } from "./device-bind.js";
 
 /** 构造微信 OAuth2 授权 URL */
 const buildAuthUrl = (state: string, env: QClawEnvironment): string => {
@@ -234,5 +235,18 @@ export const performLogin = async (options: PerformLoginOptions): Promise<LoginC
   saveState(persistedState, authStatePath);
   info("[Login] 登录态已保存");
 
+  // 设备绑定：生成企微客服链接，用户在微信中打开后才有对话入口
+  info("[Login] 开始设备绑定...");
+  const bindResult = await performDeviceBinding({
+    api,
+    log: log ?? { info: console.log, warn: console.warn, error: console.error },
+  });
+  if (bindResult.success) {
+    info(`[Login] ${bindResult.message}`);
+  } else {
+    warn(`[Login] ${bindResult.message}`);
+    warn("[Login] 可稍后重新执行登录命令完成绑定。");
+  }
+
   return credentials;
 };

package/index.ts

@@ -3,7 +3,7 @@ import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { WechatAccessWebSocketClient, handlePrompt, handleCancel } from "./websocket/index.js";
 // import { handleSimpleWecomWebhook } from "./http/webhook.js";
 import { setWecomRuntime, getWecomRuntime } from "./common/runtime.js";
-import { performLogin, loadState, clearState, saveState, getDeviceGuid, getEnvironment, QClawAPI, TokenExpiredError, buildAuthUrl, fetchQrUuid, fetchQrImageDataUrl, pollQrStatus } from "./auth/index.js";
+import { performLogin, performDeviceBinding, loadState, clearState, saveState, getDeviceGuid, getEnvironment, QClawAPI, TokenExpiredError, buildAuthUrl, fetchQrUuid, fetchQrImageDataUrl, pollQrStatus } from "./auth/index.js";
 import type { QClawEnvironment, PersistedAuthState } from "./auth/index.js";
 import { nested } from "./auth/utils.js";
 
@@ -211,65 +211,29 @@ const tencentAccessPlugin = {
           }
         } catch { /* non-fatal */ }
 
-        // 7. 生成企微客服链接，等待设备绑定（非致命，token 已拿到）
+        // 7. 设备绑定：生成企微客服链接，用户在微信中打开后才有对话入口
         try {
-          const OPEN_KFID = "wkzLlJLAAAfbxEV3ZcS-lHZxkaKmpejQ";
-          runtime.log("\n[wechat-access] 生成企微客服链接...");
-          const linkResult = await api.generateContactLink(OPEN_KFID);
-
-          if (!linkResult.success) {
-            runtime.log(`[wechat-access] 生成链接失败: ${linkResult.message ?? "未知错误"}（跳过设备绑定）`);
-          } else {
-            const linkData = linkResult.data as Record<string, unknown>;
-            const contactUrl =
-              (nested(linkData, "url") as string) ||
-              (nested(linkData, "data", "url") as string) ||
-              "";
-
-            if (!contactUrl) {
-              runtime.log("[wechat-access] 返回数据中没有 URL（跳过设备绑定）");
-            } else {
-              runtime.log("=".repeat(60));
-              runtime.log("  用微信扫描下方二维码，进入客服对话完成设备绑定");
-              runtime.log("=".repeat(60));
-
+          const runtimeLog = {
+            info: (...args: unknown[]) => runtime.log(...args),
+            warn: (...args: unknown[]) => runtime.log(...args),
+            error: (...args: unknown[]) => runtime.log(...args),
+          };
+          const bindResult = await performDeviceBinding({
+            api,
+            log: runtimeLog,
+            showQr: async (url: string) => {
               try {
                 const qrterm = await import("qrcode-terminal");
                 const generate = qrterm.default?.generate ?? qrterm.generate;
-                generate(contactUrl, { small: true }, (qrcode: string) => {
+                generate(url, { small: true }, (qrcode: string) => {
                   runtime.log("\n" + qrcode);
                 });
               } catch {
                 runtime.log("(qrcode-terminal 不可用)");
               }
-              runtime.log(`\n或手动打开: ${contactUrl}\n`);
-
-              // 轮询等待绑定
-              runtime.log("[wechat-access] 等待微信扫码绑定 (超时 5 分钟)...");
-              const bindDeadline = Date.now() + 300_000;
-              let deviceBound = false;
-              while (Date.now() < bindDeadline) {
-                await new Promise((r) => setTimeout(r, 2000));
-                try {
-                  const status = await api.queryDeviceByGuid();
-                  if (status.success) {
-                    const sd = status.data as Record<string, unknown>;
-                    const nick =
-                      (nested(sd, "nickname") as string) ||
-                      (nested(sd, "data", "nickname") as string);
-                    if (nick) {
-                      runtime.log(`[wechat-access] 设备绑定成功! 微信昵称: ${nick}`);
-                      deviceBound = true;
-                      break;
-                    }
-                  }
-                } catch { /* continue polling */ }
-              }
-              if (!deviceBound) {
-                runtime.log("[wechat-access] 设备绑定超时，可稍后重新执行 channels login");
-              }
-            }
-          }
+            },
+          });
+          runtime.log(`[wechat-access] ${bindResult.message}`);
         } catch (e) {
           runtime.log(`[wechat-access] 设备绑定失败（非致命）: ${e instanceof Error ? e.message : String(e)}`);
         }
@@ -282,6 +246,7 @@ const tencentAccessPlugin = {
           channels["wechat-access-unqclawed"] = {
             ...(channels["wechat-access-unqclawed"] ?? {}),
             token: channelToken,
+            wsUrl: env.wechatWsUrl,
           };
           const nextCfg: Record<string, unknown> = { ...fullCfg, channels };
           if (apiKey) {
@@ -608,9 +573,30 @@ const tencentAccessPlugin = {
           // 备份到独立文件（兜底）
           saveState({ jwtToken, channelToken, apiKey, guid, userInfo, savedAt: Date.now() }, authStatePath);
 
+          // 生成设备绑定链接（非致命）
+          let bindUrl = "";
+          try {
+            const OPEN_KFID = "wkzLlJLAAAfbxEV3ZcS-lHZxkaKmpejQ";
+            const linkResult = await api.generateContactLink(OPEN_KFID);
+            if (linkResult.success) {
+              const linkData = linkResult.data as Record<string, unknown>;
+              bindUrl =
+                (nested(linkData, "url") as string) ||
+                (nested(linkData, "data", "url") as string) ||
+                "";
+            }
+          } catch { /* non-fatal */ }
+
           pendingQrLogin = null;
           const nickname = (userInfo.nickname as string) ?? "用户";
-          return { connected: true, message: `登录成功! 欢迎 ${nickname}，请重启 Gateway 生效。` };
+          const bindHint = bindUrl
+            ? `\n\n⚠️ 请在微信中打开以下链接完成设备绑定（绑定后才有对话入口）：\n${bindUrl}`
+            : "";
+          return {
+            connected: true,
+            bindUrl: bindUrl || undefined,
+            message: `登录成功! 欢迎 ${nickname}，请重启 Gateway 生效。${bindHint}`,
+          };
         }
 
         // error 或其他未知状态

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@henryxiaoyang/wechat-access-unqclawed",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "type": "module",
   "description": "OpenClaw 微信通路插件 — 扫码登录 + AGP WebSocket 双向通信",
   "author": "HenryXiaoYang",