@seamnet/client 0.12.4

package/lib/plugins/wechat/index.cjs

@@ -0,0 +1,736 @@
+/**
+ * Seam WeChat Plugin — iLink Bot 微信通道
+ *
+ * 契约（Plugin v1）：
+ *   - Actions:
+ *       wechat_send    : 发送微信消息（用当前 context_token）
+ *       wechat_login   : 启动扫码登录流程（生成二维码通过 IM 发给触发者）
+ *       wechat_status  : 查询绑定状态
+ *
+ * 依赖：
+ *   - `im` 插件（通过 hub.get('im') 发送二维码图片）
+ *   - `event-bus` service（订阅 'im.message' 事件触发扫码）
+ *   - `state` service（持久化 binding）
+ *
+ * 错误码：
+ *   - WECHAT_NOT_BOUND          : 未绑定或还没收到首条消息（缺 context_token）
+ *   - WECHAT_QR_FAILED          : 获取二维码失败
+ *   - WECHAT_QR_EXPIRED         : 扫码超时
+ *   - WECHAT_SESSION_FROZEN     : bot 被风控（-14）
+ *   - WECHAT_UNKNOWN_ACTION     : 未知 action
+ */
+
+const crypto = require('node:crypto');
+const path = require('node:path');
+const nodeCrypto = require('node:crypto');
+const { seamError, wrap } = require('../../errors.cjs');
+const { validatePayload } = require('../../contracts/actions.cjs');
+
+/**
+ * 从 item 里解析 AES 密钥（返回 hex string）
+ * - image_item 外层有 aeskey (hex 格式)
+ * - media.aes_key 有两种编码：
+ *   - 图片: base64(raw 16 bytes) → decode 后 16 字节，hex encode
+ *   - 文件/语音/视频: base64(32 char hex string) → decode 后是 hex 字符串
+ */
+function resolveAesKeyHex(item) {
+  if (!item) return null;
+  if (item.aeskey) return item.aeskey;
+  if (item.media?.aes_key) {
+    try {
+      const decoded = Buffer.from(item.media.aes_key, 'base64');
+      if (decoded.length === 32) {
+        // 可能是 hex string 作 UTF-8 写入
+        const asStr = decoded.toString('utf8');
+        if (/^[0-9a-fA-F]{32}$/.test(asStr)) return asStr.toLowerCase();
+      }
+      if (decoded.length === 16) {
+        return decoded.toString('hex');
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * iLink 图片/文件加密下载 + AES-128-ECB 解密
+ * @param {Object} item - image_item 或 file_item（包含 media 和 aeskey 信息）
+ * @returns {Promise<Buffer>} 解密后的二进制数据
+ */
+async function downloadAndDecrypt(item) {
+  const media = item?.media;
+  const aeskeyHex = resolveAesKeyHex(item);
+  if (!media?.full_url) throw new Error('media.full_url missing');
+  if (!aeskeyHex) throw new Error('aeskey missing (no item.aeskey or media.aes_key)');
+  const resp = await fetch(media.full_url);
+  if (!resp.ok) throw new Error(`download failed ${resp.status}`);
+  const encrypted = Buffer.from(await resp.arrayBuffer());
+  const key = Buffer.from(aeskeyHex, 'hex');
+  if (key.length !== 16) throw new Error(`bad aeskey length ${key.length} (hex: ${aeskeyHex})`);
+  const dec = nodeCrypto.createDecipheriv('aes-128-ecb', key, null);
+  return Buffer.concat([dec.update(encrypted), dec.final()]);
+}
+
+const WECHAT_API_BASE = 'https://ilinkai.weixin.qq.com/';
+
+function randomWechatUin() {
+  const uint32 = crypto.randomBytes(4).readUInt32BE(0);
+  return Buffer.from(String(uint32), 'utf-8').toString('base64');
+}
+
+function buildHeaders(token) {
+  const headers = {
+    'Content-Type': 'application/json',
+    AuthorizationType: 'ilink_bot_token',
+    'X-WECHAT-UIN': randomWechatUin(),
+  };
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+async function apiPost(endpoint, body, token, timeoutMs = 15000) {
+  const url = `${WECHAT_API_BASE}${endpoint}`;
+  const bodyStr = JSON.stringify(body);
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        ...buildHeaders(token),
+        'Content-Length': String(Buffer.byteLength(bodyStr)),
+      },
+      body: bodyStr,
+      signal: controller.signal,
+    });
+    clearTimeout(t);
+    const text = await res.text();
+    // 非长轮询的响应打 debug 日志，方便追查
+    if (endpoint !== 'ilink/bot/getupdates' && !res.ok) {
+      console.log(`[wechat-api] ${endpoint} status=${res.status} body=${text.slice(0, 400)}`);
+    }
+    if (!res.ok) throw new Error(`${endpoint} ${res.status}: ${text}`);
+    return JSON.parse(text);
+  } catch (err) {
+    clearTimeout(t);
+    if (err.name === 'AbortError') return { ret: 0, msgs: [], _aborted: true };
+    throw err;
+  }
+}
+
+async function getQrcode() {
+  const url = `${WECHAT_API_BASE}ilink/bot/get_bot_qrcode?bot_type=3`;
+  const res = await fetch(url);
+  return res.json();
+}
+
+async function getQrcodeStatus(qrcode) {
+  const url = `${WECHAT_API_BASE}ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`;
+  const controller = new AbortController();
+  const t = setTimeout(() => controller.abort(), 40000);
+  try {
+    const res = await fetch(url, { signal: controller.signal });
+    clearTimeout(t);
+    return res.json();
+  } catch (err) {
+    clearTimeout(t);
+    if (err.name === 'AbortError') return { status: 'timeout' };
+    throw err;
+  }
+}
+
+async function getUpdates(token, updatesBuf) {
+  return apiPost(
+    'ilink/bot/getupdates',
+    {
+      get_updates_buf: updatesBuf || '',
+      base_info: { channel_version: '1.0.0' },
+    },
+    token,
+    35000
+  );
+}
+
+async function sendWechatMessage(token, toUserId, text, contextToken) {
+  return apiPost(
+    'ilink/bot/sendmessage',
+    {
+      msg: {
+        from_user_id: '',
+        to_user_id: toUserId,
+        client_id: `seam-${nodeCrypto.randomBytes(8).toString('hex')}`,
+        message_type: 2,
+        message_state: 2,
+        item_list: [{ type: 1, text_item: { text } }],
+        context_token: contextToken,
+      },
+      base_info: { channel_version: '1.0.2' },
+    },
+    token
+  );
+}
+
+// 文件扩展名 → media_type：1=图片, 2=视频, 3=文件
+const MEDIA_TYPES_BY_EXT = {
+  '.jpg': 1, '.jpeg': 1, '.png': 1, '.gif': 1, '.webp': 1, '.bmp': 1,
+  '.mp4': 2, '.mov': 2, '.avi': 2, '.mkv': 2,
+  '.pdf': 3, '.txt': 3, '.md': 3, '.docx': 3, '.xlsx': 3, '.pptx': 3,
+  '.zip': 3, '.tar': 3, '.gz': 3, '.json': 3, '.csv': 3, '.log': 3,
+};
+// media_type → item_type（sendmessage 里用的）：1→2, 2→5, 3→4
+const ITEM_TYPE_BY_MEDIA = { 1: 2, 2: 5, 3: 4 };
+
+/**
+ * 上传并发送文件/图片到微信（5 步流程）：
+ * 1. getuploadurl → upload_param
+ * 2. AES-128-ECB (PKCS7) 加密文件
+ * 3. PUT 到 CDN
+ * 4. sendmessage 带 file_key + aes_key
+ * 来源：渡的 Python 实现（角落/skills/wechat-guardian/scripts/send_file.py）
+ */
+const CDN_BASE = 'https://novac2c.cdn.weixin.qq.com/c2c';
+
+async function uploadAndSendFile(token, toUserId, contextToken, filePath) {
+  const fs = require('node:fs');
+  const pathMod = require('node:path');
+  const plaintext = fs.readFileSync(filePath);
+  const ext = pathMod.extname(filePath).toLowerCase();
+  const mediaType = MEDIA_TYPES_BY_EXT[ext] || 3;
+  const rawSize = plaintext.length;
+  const rawFileMd5 = nodeCrypto.createHash('md5').update(plaintext).digest('hex');
+  const filesize = Math.ceil((rawSize + 1) / 16) * 16; // PKCS7 padded size
+  const filekey = nodeCrypto.randomBytes(16).toString('hex');
+  const aesKey = nodeCrypto.randomBytes(16);
+  const aesKeyHex = aesKey.toString('hex');
+  const fileName = pathMod.basename(filePath);
+
+  // Step 1: getuploadurl → upload_param (base64 token string)
+  const up = await apiPost(
+    'ilink/bot/getuploadurl',
+    {
+      filekey,
+      media_type: mediaType,
+      to_user_id: toUserId,
+      rawsize: rawSize,
+      rawfilemd5: rawFileMd5,
+      filesize,
+      no_need_thumb: true,
+      aeskey: aesKeyHex,
+      base_info: { channel_version: '1.0.2' },
+    },
+    token,
+    20000
+  );
+  const uploadParam = up?.upload_param;
+  if (!uploadParam || typeof uploadParam !== 'string') {
+    throw new Error(`getuploadurl bad response: ${JSON.stringify(up).slice(0, 300)}`);
+  }
+
+  // Step 2: AES-128-ECB + PKCS7 加密
+  const cipher = nodeCrypto.createCipheriv('aes-128-ecb', aesKey, null);
+  cipher.setAutoPadding(true);
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+
+  // Step 3: POST 加密数据到 CDN；响应 header 里的 x-encrypted-param 是 download_param
+  const cdnUrl = `${CDN_BASE}/upload?encrypted_query_param=${encodeURIComponent(uploadParam)}&filekey=${encodeURIComponent(filekey)}`;
+  const cdnResp = await fetch(cdnUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/octet-stream' },
+    body: ciphertext,
+  });
+  if (!cdnResp.ok) {
+    const txt = await cdnResp.text();
+    throw new Error(`CDN upload failed ${cdnResp.status}: ${txt.slice(0, 200)}`);
+  }
+  const downloadParam = cdnResp.headers.get('x-encrypted-param');
+  if (!downloadParam) {
+    throw new Error(`CDN response missing x-encrypted-param header`);
+  }
+
+  // Step 4: sendmessage
+  const itemType = ITEM_TYPE_BY_MEDIA[mediaType] || 4;
+  const aesKeyB64 = Buffer.from(aesKeyHex).toString('base64'); // base64 of hex string
+  let item;
+  const media = {
+    encrypt_query_param: downloadParam,
+    aes_key: aesKeyB64,
+    encrypt_type: 1,
+  };
+  if (mediaType === 1) {
+    item = { type: itemType, image_item: { media, mid_size: filesize } };
+  } else if (mediaType === 2) {
+    item = { type: itemType, video_item: { media, video_size: filesize } };
+  } else {
+    item = {
+      type: itemType,
+      file_item: { media, file_name: fileName, len: String(rawSize) },
+    };
+  }
+
+  const clientId = `seam-${nodeCrypto.randomBytes(8).toString('hex')}`;
+  const resp = await apiPost(
+    'ilink/bot/sendmessage',
+    {
+      msg: {
+        from_user_id: '',
+        to_user_id: toUserId,
+        client_id: clientId,
+        message_type: 2,
+        message_state: 2,
+        context_token: contextToken,
+        item_list: [item],
+      },
+      base_info: { channel_version: '1.0.2' },
+    },
+    token
+  );
+  return { ok: true, mediaType, itemType, fileName, bytes: rawSize, response: resp };
+}
+
+function createWechatPlugin() {
+  let log = null;
+  let hub = null;
+  let im = null;
+  let stateScope = null;
+  let binding = null;
+  let running = false;
+
+  function saveBinding() {
+    if (binding && stateScope) {
+      try {
+        stateScope.set('binding', binding);
+      } catch (e) {
+        log.warn('binding_save_failed', { message: e.message });
+      }
+    }
+  }
+
+  async function startLogin(fromUserId) {
+    log.info('qr_login_start', { fromUserId });
+    const qrData = await getQrcode();
+    if (!qrData.qrcode) {
+      throw seamError({
+        code: 'WECHAT_QR_FAILED',
+        message: 'Failed to get QR code from iLink Bot API',
+        docs: 'docs/maintainer-guide.md#WECHAT_QR_FAILED',
+      });
+    }
+
+    const qrUrl = `${WECHAT_API_BASE}ilink/bot/get_bot_qrcode?qrcode=${qrData.qrcode}`;
+    const scanUrl = qrData.qrcode_img_content || qrUrl;
+
+    if (fromUserId && im) {
+      try {
+        const QRCode = require('qrcode');
+        const qrImgPath = path.join(hub.seamDir, 'wechat-qr.png');
+        await QRCode.toFile(qrImgPath, scanUrl, { width: 300, margin: 2 });
+        await im.sendImage(fromUserId, qrImgPath);
+        log.info('qr_image_sent', { fromUserId });
+      } catch (e) {
+        log.warn('qr_image_failed', { message: e.message });
+      }
+      try {
+        await im.sendMessage(
+          fromUserId,
+          `📱 微信绑定二维码已发送（5分钟内有效）。\n\n扫码确认后，在微信里给bot发一条消息完成绑定。`
+        );
+      } catch (e) {
+        log.warn('qr_notice_send_failed', { message: e.message });
+      }
+    }
+
+    hub.inject(`📱 [微信绑定] 二维码已发送给用户`);
+
+    for (let i = 0; i < 30; i++) {
+      const status = await getQrcodeStatus(qrData.qrcode);
+      if (status.status === 'confirmed') {
+        // 绑定的微信就是 inviter 本人（一对一 bot），用 inviter 的昵称作显示名
+        // 避免终端里显示一长串 ilink 用户 ID
+        const displayName =
+          hub.credentials?.inviterName ||
+          hub.credentials?.inviter ||
+          '微信用户';
+        binding = {
+          bot_token: status.bot_token,
+          ilink_bot_id: status.ilink_bot_id,
+          ilink_user_id: status.ilink_user_id,
+          baseurl: status.baseurl || WECHAT_API_BASE,
+          context_token: null,
+          updates_buf: '',
+          status: 'pending_first_message',
+          display_name: displayName,
+          created_at: new Date().toISOString(),
+        };
+        saveBinding();
+        log.info('qr_confirmed', { ilink_user_id: binding.ilink_user_id });
+        hub.inject('📱 [微信绑定] 扫码成功！请在微信里给bot发一条消息完成绑定。');
+        messageLoop();
+        return { ok: true, status: 'confirmed' };
+      } else if (status.status === 'scaned') {
+        log.info('qr_scanned');
+      }
+    }
+
+    throw seamError({
+      code: 'WECHAT_QR_EXPIRED',
+      message: 'QR code expired after 30 polls (~5 min)',
+      hint: '重新触发 wechat_login 或发"绑定微信"',
+      docs: 'docs/maintainer-guide.md#WECHAT_QR_EXPIRED',
+    });
+  }
+
+  async function messageLoop() {
+    if (!binding || !binding.bot_token) return;
+    if (running) return; // avoid double start
+    running = true;
+    log.info('message_loop_started');
+
+    while (running) {
+      try {
+        const bufPreview = (binding.updates_buf || '').slice(0, 40);
+        log.info('poll_begin', { bufPreview });
+        const resp = await getUpdates(binding.bot_token, binding.updates_buf);
+        log.info('poll_end', {
+          msgCount: resp.msgs ? resp.msgs.length : 0,
+          hasNewBuf: resp.get_updates_buf !== undefined,
+          newBufPreview: (resp.get_updates_buf || '').slice(0, 40),
+          aborted: !!resp._aborted,
+          ret: resp.ret,
+        });
+        if (resp.msgs && resp.msgs.length > 0) {
+          for (const msg of resp.msgs) {
+            if (msg.context_token) {
+              binding.context_token = msg.context_token;
+            }
+            let text = '';
+            if (msg.item_list) {
+              for (const item of msg.item_list) {
+                if (item.type === 1 && item.text_item?.text) {
+                  text += item.text_item.text;
+                }
+              }
+            }
+
+            // 优先用 binding.display_name（绑定时从 credentials.inviterName 来），
+            // 否则 iLink 的昵称，最后 fallback 到原 id
+            const sender =
+              binding?.display_name ||
+              msg.from_user_nickname ||
+              msg.from_user_id ||
+              '微信用户';
+            const msgBuf = hub.service('message-buffer');
+            if (text) {
+              log.info('wechat_message_received', {
+                sender,
+                textLength: text.length,
+              });
+              if (msgBuf) {
+                msgBuf.queueText(
+                  `wechat:${sender}`,
+                  text,
+                  (items) => {
+                    const ts = new Date().toTimeString().slice(0, 5);
+                    const joined = items.map((i) => i.content).join('\n');
+                    const prefix = `📱 [微信 ${ts} → wechat_send]`;
+                    if (items.length === 1) {
+                      hub.inject(`${prefix} ${sender}: ${joined}`);
+                    } else {
+                      hub.inject(`${prefix} ${sender}:\n${joined}`);
+                    }
+                  },
+                  { delay: 5000, maxDelay: 15000 }
+                );
+              } else {
+                const ts = new Date().toTimeString().slice(0, 5);
+                hub.inject(`📱 [微信 ${ts} → wechat_send] ${sender}: ${text}`);
+              }
+            } else {
+              // 非文本消息：按 type 分派下载
+              const itemTypes = (msg.item_list || []).map((i) => i.type);
+              const inbox = hub.service('inbox');
+              const ts = new Date().toTimeString().slice(0, 5);
+
+              // 取第一个非文本 item 处理（v1 简化）
+              const firstItem = (msg.item_list || []).find(
+                (i) => i.type !== 1
+              );
+
+              try {
+                if (firstItem?.type === 2 && firstItem.image_item) {
+                  // 图片
+                  const buf = await downloadAndDecrypt(firstItem.image_item);
+                  const p = inbox.save(buf, { ext: 'jpg', src: 'wechat' });
+                  log.info('wechat_image_saved', {
+                    sender,
+                    bytes: buf.length,
+                    path: p,
+                  });
+                  hub.inject(`📱 [微信图片 ${ts} → wechat_send] ${sender} → ${p}`);
+                } else if (firstItem?.type === 3 && firstItem.voice_item) {
+                  // 语音
+                  const buf = await downloadAndDecrypt(firstItem.voice_item);
+                  const p = inbox.save(buf, { ext: 'amr', src: 'wechat' });
+                  log.info('wechat_voice_saved', {
+                    sender,
+                    bytes: buf.length,
+                    path: p,
+                  });
+                  hub.inject(`📱 [微信语音 ${ts} → wechat_send] ${sender} → ${p}`);
+                } else if (firstItem?.type === 5 && firstItem.video_item) {
+                  // 视频
+                  const buf = await downloadAndDecrypt(firstItem.video_item);
+                  const p = inbox.save(buf, { ext: 'mp4', src: 'wechat' });
+                  log.info('wechat_video_saved', {
+                    sender,
+                    bytes: buf.length,
+                    path: p,
+                  });
+                  hub.inject(`📱 [微信视频 ${ts} → wechat_send] ${sender} → ${p}`);
+                } else if (firstItem?.type === 4 && firstItem.file_item) {
+                  // 文件
+                  const fileItem = firstItem.file_item;
+                  const buf = await downloadAndDecrypt(fileItem);
+                  const fileName =
+                    fileItem.file_name ||
+                    fileItem.name ||
+                    fileItem.media?.file_name ||
+                    `file_${Date.now()}`;
+                  const ext = path.extname(fileName).replace(/^\./, '') || 'bin';
+                  const p = inbox.save(buf, { ext, src: 'wechat' });
+                  log.info('wechat_file_saved', {
+                    sender,
+                    bytes: buf.length,
+                    path: p,
+                    fileName,
+                  });
+                  hub.inject(
+                    `📱 [微信文件 ${ts} → wechat_send] ${sender} → ${p} (原名: ${fileName}, ${buf.length} bytes)`
+                  );
+                } else {
+                  // 未实现的类型
+                  log.warn('wechat_message_unhandled_type', {
+                    sender,
+                    itemTypes,
+                    itemKeys: (msg.item_list || [])
+                      .slice(0, 2)
+                      .map((i) => Object.keys(i)),
+                  });
+                  const hint =
+                    firstItem?.type === 3 ? '[语音]' :
+                    firstItem?.type === 5 ? '[链接]' :
+                    firstItem?.type === 6 ? '[表情]' :
+                    `[未知类型 ${JSON.stringify(itemTypes)}]`;
+                  hub.inject(`📱 [微信 ${ts} → wechat_send] ${sender}: ${hint}`);
+                }
+              } catch (e) {
+                log.error('wechat_media_download_failed', e, {
+                  sender,
+                  itemTypes,
+                });
+                hub.inject(
+                  `📱 [微信 ${ts} → wechat_send] ${sender}: [媒体下载失败: ${e.message}]`
+                );
+              }
+            }
+
+            if (binding.status === 'pending_first_message') {
+              binding.status = 'active';
+              log.info('binding_active');
+              hub.inject('📱 [微信绑定] 绑定完成！微信通道已激活。');
+            }
+          }
+        }
+        // 永远更新游标（即使 msgs 为空），避免卡在旧游标
+        if (resp.get_updates_buf !== undefined) {
+          binding.updates_buf = resp.get_updates_buf;
+        }
+        saveBinding();
+      } catch (err) {
+        if (err.message && err.message.includes('-14')) {
+          log.error(
+            'session_frozen',
+            wrap(err, {
+              code: 'WECHAT_SESSION_FROZEN',
+              hint: 'bot 被风控，暂停 1 小时',
+              docs: 'docs/maintainer-guide.md#WECHAT_SESSION_FROZEN',
+            }).toLog()
+          );
+          binding.status = 'frozen';
+          saveBinding();
+          await new Promise((r) => setTimeout(r, 3600000));
+          binding.status = 'active';
+          saveBinding();
+        } else {
+          log.warn('poll_error', { message: err.message });
+          await new Promise((r) => setTimeout(r, 5000));
+        }
+      }
+    }
+    log.info('message_loop_stopped');
+  }
+
+  async function init(h) {
+    hub = h;
+    log = hub.logger('wechat');
+
+    // Service 依赖
+    const state = hub.service('state');
+    const bus = hub.service('event-bus');
+    if (!state) {
+      throw seamError({
+        code: 'WECHAT_MISSING_STATE_SVC',
+        message: 'wechat plugin requires `state` service',
+      });
+    }
+    if (!bus) {
+      throw seamError({
+        code: 'WECHAT_MISSING_EVENT_BUS',
+        message: 'wechat plugin requires `event-bus` service',
+      });
+    }
+    stateScope = state.scope('wechat');
+
+    // Plugin 依赖
+    im = hub.get('im');
+    if (!im) {
+      throw seamError({
+        code: 'WECHAT_MISSING_IM_DEP',
+        message: 'wechat plugin requires `im` plugin loaded first',
+        hint: 'guardian 加载插件时确保 im 在 wechat 之前',
+      });
+    }
+
+    // 订阅 IM 消息：收到"绑定微信" 触发扫码
+    bus.on('im.message', ({ from, text, isGroup }) => {
+      if (isGroup) return;
+      if (String(text).trim() === '绑定微信') {
+        log.info('bind_trigger_received', { from });
+        startLogin(from).catch((e) => {
+          log.error('bind_trigger_failed', e);
+          im.sendMessage(from, `📱 微信绑定失败：${e.message}`).catch(() => {});
+        });
+      }
+    });
+
+    // 恢复已有 binding（从 state）
+    const existing = stateScope.get('binding');
+    if (existing) {
+      binding = existing;
+      // 老 binding 没有 display_name 字段 → 从 credentials 补上
+      if (!binding.display_name) {
+        binding.display_name =
+          hub.credentials?.inviterName ||
+          hub.credentials?.inviter ||
+          '微信用户';
+        saveBinding();
+        log.info('binding_display_name_backfilled', {
+          display_name: binding.display_name,
+        });
+      }
+      log.info('binding_restored', {
+        ilink_user_id: binding.ilink_user_id || 'unknown',
+        status: binding.status,
+        display_name: binding.display_name,
+      });
+      if (binding.bot_token && binding.status !== 'frozen') {
+        messageLoop();
+      }
+    } else {
+      log.info('no_existing_binding');
+    }
+  }
+
+  async function handleRequest(req) {
+    const check = validatePayload(req.action, req);
+    if (!check.ok) {
+      throw seamError({ code: 'WECHAT_BAD_PAYLOAD', message: check.error });
+    }
+    if (req.action === 'wechat_login') {
+      // fromUserId 从 req 里来，没有则不发给任何人
+      return await startLogin(req.fromUserId);
+    }
+    if (req.action === 'wechat_send') {
+      if (!binding || !binding.context_token) {
+        throw seamError({
+          code: 'WECHAT_NOT_BOUND',
+          message: 'WeChat not bound or no context_token',
+          hint: '用户需要先给 bot 发一条消息',
+          docs: 'docs/maintainer-guide.md#WECHAT_NOT_BOUND',
+        });
+      }
+      const resp = await sendWechatMessage(
+        binding.bot_token,
+        binding.ilink_user_id,
+        req.text,
+        binding.context_token
+      );
+      log.info('wechat_send_response', { ret: resp?.ret, msg: resp?.msg, keys: resp && Object.keys(resp) });
+      return { ok: true, response: resp };
+    }
+    if (req.action === 'wechat_send_image' || req.action === 'wechat_send_file') {
+      if (!binding || !binding.context_token) {
+        throw seamError({
+          code: 'WECHAT_NOT_BOUND',
+          message: 'WeChat not bound or no context_token',
+          hint: '用户需要先给 bot 发一条消息',
+        });
+      }
+      if (!req.filePath) {
+        throw seamError({
+          code: 'WECHAT_FILE_PATH_MISSING',
+          message: 'filePath is required',
+        });
+      }
+      const result = await uploadAndSendFile(
+        binding.bot_token,
+        binding.ilink_user_id,
+        binding.context_token,
+        req.filePath
+      );
+      log.info('wechat_file_sent', {
+        fileName: result.fileName,
+        bytes: result.bytes,
+        mediaType: result.mediaType,
+      });
+      return result;
+    }
+    if (req.action === 'wechat_status') {
+      return {
+        ok: true,
+        bound: !!binding,
+        status: binding?.status || 'not_bound',
+        user: binding?.ilink_user_id || null,
+      };
+    }
+    throw seamError({
+      code: 'WECHAT_UNKNOWN_ACTION',
+      message: `unknown action: ${req.action}`,
+    });
+  }
+
+  async function destroy() {
+    running = false;
+    if (log) log.info('destroyed');
+  }
+
+  return {
+    name: 'wechat',
+    description: '微信iLink通道（绑定/发送文本/图片/文件）',
+    actions: [
+      'wechat_send',
+      'wechat_send_image',
+      'wechat_send_file',
+      'wechat_login',
+      'wechat_status',
+    ],
+    init,
+    handleRequest,
+    destroy,
+  };
+}
+
+module.exports = { createWechatPlugin };