Skip to content

🤖 Open-source, local-first alternative to Grok Bot, OpenAI dots and Claude Duet. Your own AI bots on any model: GPT, Claude, Gemini, Grok, DeepSeek, Kimi, GLM and 70+ more through one Modelflare key. Reach them in the app, WeChat or Feishu; they remember you, work in the background, run commands and use your computer. Pay per use.

20.7 KB
Raw Blame
/*
 * iLink Bot API 客户端(微信官方 ClawBot 通道)。
 * 协议细节移植自 Tencent/openclaw-weixin (src/api/api.ts, src/auth/login-qr.ts, src/cdn/*.ts, src/messaging/send.ts, v2.4.10),
 * 精简并改写为可注入 baseUrl/fetch 的类。
 * Portions Copyright (C) 2026 Tencent. All rights reserved. Licensed under the MIT, see ./LICENSE.openclaw-weixin.
 */
import crypto from "node:crypto";
import fs from "node:fs/promises";
import path from "node:path";
import { t } from "../../i18n/index.js";

export const ILINK_APP_ID = "bot";
export const DEFAULT_ILINK_BASE = "https://ilinkai.weixin.qq.com";
export const DEFAULT_CDN_BASE = "https://novac2c.cdn.weixin.qq.com/c2c";
/** proto: UploadMediaType */
export const UploadMediaType = { IMAGE: 1, VIDEO: 2, FILE: 3 } as const;

const IMAGE_EXT = new Set([".png", ".jpg", ".jpeg", ".gif", ".webp", ".bmp"]);
const VIDEO_EXT = new Set([".mp4", ".mov", ".m4v", ".webm"]);
export function mediaKind(file: string): "image" | "video" | "file" {
  const ext = path.extname(file).toLowerCase();
  return IMAGE_EXT.has(ext) ? "image" : VIDEO_EXT.has(ext) ? "video" : "file";
}

/** AES-128-ECB(PKCS7)加密,CDN 上传要求。 */
export function encryptAesEcb(plain: Buffer, key: Buffer): Buffer {
  const c = crypto.createCipheriv("aes-128-ecb", key, null);
  return Buffer.concat([c.update(plain), c.final()]);
}
export function decryptAesEcb(cipher: Buffer, key: Buffer): Buffer {
  const d = crypto.createDecipheriv("aes-128-ecb", key, null);
  return Buffer.concat([d.update(cipher), d.final()]);
}
export function aesEcbPaddedSize(n: number): number {
  return Math.ceil((n + 1) / 16) * 16;
}

/**
 * CDNMedia.aes_key 有两种编码(移植自 openclaw-weixin src/cdn/pic-decrypt.ts):
 * 图片是 16 字节原始密钥的 base64;文件/语音/视频是 32 位十六进制字符串的 base64。
 */
export function parseAesKey(aesKeyBase64: string): Buffer {
  const decoded = Buffer.from(aesKeyBase64, "base64");
  if (decoded.length === 16) return decoded;
  const ascii = decoded.toString("ascii");
  if (decoded.length === 32 && /^[0-9a-fA-F]{32}$/.test(ascii)) return Buffer.from(ascii, "hex");
  throw new Error(t("channel.aes_key_bad", { len: decoded.length }));
}

export type ImageMime = "image/png" | "image/jpeg" | "image/gif" | "image/webp";
const IMAGE_MIME_EXT: Record<ImageMime, string> = { "image/png": ".png", "image/jpeg": ".jpg", "image/gif": ".gif", "image/webp": ".webp" };

/** 按文件头识别图片格式(微信图片条目不带文件名和 MIME);不认识的返回 undefined。 */
export function sniffImageMime(buf: Buffer): ImageMime | undefined {
  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return "image/jpeg";
  if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return "image/png";
  if (buf.length >= 6 && buf.subarray(0, 4).toString("ascii") === "GIF8") return "image/gif";
  if (buf.length >= 12 && buf.subarray(0, 4).toString("ascii") === "RIFF" && buf.subarray(8, 12).toString("ascii") === "WEBP") return "image/webp";
  return undefined;
}
export function imageExt(mime: string | undefined): string {
  return IMAGE_MIME_EXT[mime as ImageMime] ?? ".jpg";
}

/** 单个入站媒体(解密后)的大小上限 */
export const MAX_INBOUND_MEDIA_BYTES = 50 * 1024 * 1024;
const CDN_TIMEOUT_MS = 60_000;

export interface InboundMedia {
  kind: "image" | "file" | "video";
  data: Buffer;
  /** 文件条目的原始文件名 */
  name?: string;
  /** 图片按文件头识别出的格式 */
  mime?: ImageMime;
}

/** 图片/文件/视频条目带有可下载的 CDN 引用。语音不下载:有转写文字,原始音频是 SILK。 */
export function hasDownloadableMedia(item: MessageItem | undefined): boolean {
  const media =
    item?.type === MessageItemType.IMAGE ? item.image_item?.media : item?.type === MessageItemType.FILE ? item.file_item?.media : item?.type === MessageItemType.VIDEO ? item.video_item?.media : undefined;
  return !!(media?.encrypt_query_param || media?.full_url);
}
export const SESSION_EXPIRED_ERRCODE = -14;
const CHANNEL_VERSION = "0.1.0";
const BOT_AGENT = "AnymodelBot/0.1.0";

export function buildClientVersion(version: string): number {
  const parts = version.split(".").map((p) => parseInt(p, 10));
  const major = parts[0] || 0;
  const minor = parts[1] || 0;
  const patch = parts[2] || 0;
  return ((major & 0xff) << 16) | ((minor & 0xff) << 8) | (patch & 0xff);
}

export function randomWechatUin(): string {
  const uint32 = crypto.randomBytes(4).readUInt32BE(0);
  return Buffer.from(String(uint32), "utf-8").toString("base64");
}

const LOSSLESS_ID_FIELDS = new Set(["message_id", "msg_id", "svr_id"]);

/** 解析前把 uint64 消息 ID 加上引号,避免 JS number 精度丢失(移植自 openclaw-weixin)。 */
export function parseWeixinApiJson<T>(rawText: string): T {
  let output = "";
  let index = 0;
  while (index < rawText.length) {
    if (rawText[index] !== '"') {
      output += rawText[index++];
      continue;
    }
    const stringStart = index;
    index++;
    let escaped = false;
    while (index < rawText.length) {
      const char = rawText[index++];
      if (escaped) escaped = false;
      else if (char === "\\") escaped = true;
      else if (char === '"') break;
    }
    const stringToken = rawText.slice(stringStart, index);
    output += stringToken;
    let cursor = index;
    while (/\s/.test(rawText[cursor] ?? "")) cursor++;
    if (rawText[cursor] !== ":") continue;
    let key: unknown;
    try {
      key = JSON.parse(stringToken);
    } catch {
      continue;
    }
    if (typeof key !== "string" || !LOSSLESS_ID_FIELDS.has(key)) continue;
    output += rawText.slice(index, cursor + 1);
    cursor++;
    while (/\s/.test(rawText[cursor] ?? "")) output += rawText[cursor++];
    const numberStart = cursor;
    if (rawText[cursor] === "-") cursor++;
    while (/\d/.test(rawText[cursor] ?? "")) cursor++;
    if (cursor > numberStart && !(cursor === numberStart + 1 && rawText[numberStart] === "-")) {
      output += `"${rawText.slice(numberStart, cursor)}"`;
      index = cursor;
    } else {
      index = numberStart;
    }
  }
  return JSON.parse(output) as T;
}

// ---------- 协议类型(节选) ----------
export const MessageType = { USER: 1, BOT: 2 } as const;
export const MessageItemType = { TEXT: 1, IMAGE: 2, VOICE: 3, FILE: 4, VIDEO: 5 } as const;

export interface CdnMedia {
  encrypt_query_param?: string;
  aes_key?: string;
  encrypt_type?: number;
  /** 完整下载地址(服务端给出时优先用它,不再自己拼) */
  full_url?: string;
}

export interface MessageItem {
  type?: number;
  text_item?: { text?: string };
  voice_item?: { text?: string; media?: CdnMedia };
  file_item?: { file_name?: string; media?: CdnMedia; len?: string };
  /** aeskey:入站图片的原始密钥(十六进制),优先于 media.aes_key */
  image_item?: { media?: CdnMedia; aeskey?: string; mid_size?: number };
  video_item?: { media?: CdnMedia; video_size?: number };
  ref_msg?: { title?: string; message_item?: MessageItem };
}

export interface WeixinMessage {
  seq?: number;
  message_id?: string;
  from_user_id?: string;
  to_user_id?: string;
  client_id?: string;
  create_time_ms?: number;
  session_id?: string;
  message_type?: number;
  message_state?: number;
  item_list?: MessageItem[];
  context_token?: string;
}

export interface GetUpdatesResp {
  ret?: number;
  errcode?: number;
  errmsg?: string;
  msgs?: WeixinMessage[];
  get_updates_buf?: string;
  longpolling_timeout_ms?: number;
}

export interface QrCodeResp {
  qrcode: string;
  qrcode_img_content: string;
}

export interface QrStatusResp {
  status: "wait" | "scaned" | "confirmed" | "expired" | "scaned_but_redirect" | "need_verifycode" | "verify_code_blocked" | "binded_redirect";
  bot_token?: string;
  ilink_bot_id?: string;
  baseurl?: string;
  ilink_user_id?: string;
  redirect_host?: string;
}

export class WeixinApiError extends Error {
  constructor(message: string, readonly ret?: number, readonly errcode?: number) {
    super(message);
  }
  get sessionExpired(): boolean {
    return this.ret === SESSION_EXPIRED_ERRCODE || this.errcode === SESSION_EXPIRED_ERRCODE;
  }
  /** 服务端明确拒绝(有错误码或 HTTP 4xx):出站队列试几次就放弃;网络错误、5xx 一直重试到过期 */
  get rejected(): boolean {
    if (this.sessionExpired) return false;
    return (this.ret !== undefined && this.ret !== 0) || (this.errcode !== undefined && this.errcode !== 0) || /HTTP 4\d\d/.test(this.message);
  }
}

export interface IlinkClientOptions {
  baseUrl?: string;
  token?: string;
  routeTag?: string;
  fetchImpl?: typeof fetch;
  cdnBaseUrl?: string;
}

export class IlinkClient {
  baseUrl: string;
  token: string;
  private fetchImpl: typeof fetch;
  constructor(private opts: IlinkClientOptions = {}) {
    this.baseUrl = (opts.baseUrl || DEFAULT_ILINK_BASE).replace(/\/+$/, "");
    this.token = opts.token || "";
    this.fetchImpl = opts.fetchImpl || fetch;
  }

  private headers(withBody: boolean): Record<string, string> {
    const h: Record<string, string> = {
      "iLink-App-Id": ILINK_APP_ID,
      "iLink-App-ClientVersion": String(buildClientVersion(CHANNEL_VERSION)),
    };
    if (this.opts.routeTag) h.SKRouteTag = this.opts.routeTag;
    if (withBody) {
      h["Content-Type"] = "application/json";
      h.AuthorizationType = "ilink_bot_token";
      h["X-WECHAT-UIN"] = randomWechatUin();
      if (this.token.trim()) h.Authorization = `Bearer ${this.token.trim()}`;
    }
    return h;
  }

  private baseInfo() {
    return { channel_version: CHANNEL_VERSION, bot_agent: BOT_AGENT };
  }

  private async request(method: "GET" | "POST", endpoint: string, body: unknown, timeoutMs: number, signal?: AbortSignal): Promise<string> {
    const ctrl = new AbortController();
    const t = setTimeout(() => ctrl.abort(new Error("timeout")), timeoutMs);
    const onAbort = () => ctrl.abort(signal?.reason);
    signal?.addEventListener("abort", onAbort);
    try {
      const res = await this.fetchImpl(`${this.baseUrl}/${endpoint}`, {
        method,
        headers: this.headers(method === "POST"),
        body: method === "POST" ? JSON.stringify({ ...(body as object), base_info: this.baseInfo() }) : undefined,
        signal: ctrl.signal,
      });
      const text = await res.text();
      if (!res.ok) throw new WeixinApiError(`${endpoint} HTTP ${res.status}`);
      return text;
    } finally {
      clearTimeout(t);
      signal?.removeEventListener("abort", onAbort);
    }
  }

  // ---------- 登录 ----------
  async getBotQrCode(localTokens: string[] = []): Promise<QrCodeResp> {
    const raw = await this.request("POST", "ilink/bot/get_bot_qrcode?bot_type=3", { local_token_list: localTokens }, 15_000);
    return JSON.parse(raw) as QrCodeResp;
  }

  /** 长轮询二维码状态;超时/网络错误视为 wait。 */
  async getQrCodeStatus(qrcode: string, verifyCode?: string, timeoutMs = 35_000, signal?: AbortSignal): Promise<QrStatusResp> {
    const q = `ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}${verifyCode ? `&verify_code=${encodeURIComponent(verifyCode)}` : ""}`;
    try {
      return JSON.parse(await this.request("GET", q, undefined, timeoutMs, signal)) as QrStatusResp;
    } catch (e) {
      if (signal?.aborted) throw e;
      return { status: "wait" };
    }
  }

  // ---------- 消息 ----------
  /** 长轮询拉取消息;客户端超时返回空结果(正常现象)。 */
  async getUpdates(cursor: string, timeoutMs = 35_000, signal?: AbortSignal): Promise<GetUpdatesResp> {
    let raw: string;
    try {
      raw = await this.request("POST", "ilink/bot/getupdates", { get_updates_buf: cursor }, timeoutMs, signal);
    } catch (e) {
      if (!signal?.aborted && (e as Error).name === "AbortError") return { ret: 0, msgs: [], get_updates_buf: cursor };
      if (!signal?.aborted && /timeout/i.test(String((e as Error).message))) return { ret: 0, msgs: [], get_updates_buf: cursor };
      throw e;
    }
    const resp = parseWeixinApiJson<GetUpdatesResp>(raw);
    if ((resp.ret !== undefined && resp.ret !== 0) || (resp.errcode !== undefined && resp.errcode !== 0)) {
      throw new WeixinApiError(`getupdates ret=${resp.ret} errcode=${resp.errcode} errmsg=${resp.errmsg ?? ""}`, resp.ret, resp.errcode);
    }
    return resp;
  }

  /** clientId:出站队列给的确定 id(同一条消息的同一段每次相同),不给就随机 */
  async sendText(toUserId: string, text: string, contextToken: string, clientId?: string): Promise<void> {
    await this.sendItem(toUserId, { type: MessageItemType.TEXT, text_item: { text } }, contextToken, clientId);
  }

  /**
   * 发送本地文件:getuploadurl → AES-128-ECB 加密后 POST 到 CDN → sendmessage 媒体条目。
   * 移植自 openclaw-weixin src/cdn/upload.ts、src/cdn/cdn-upload.ts、src/messaging/send.ts。
   */
  async sendMedia(toUserId: string, filePath: string, contextToken: string, clientId?: string): Promise<void> {
    const plain = await fs.readFile(filePath);
    const kind = mediaKind(filePath);
    const filekey = crypto.randomBytes(16).toString("hex");
    const aeskey = crypto.randomBytes(16);
    const filesize = aesEcbPaddedSize(plain.length);
    const raw = await this.request(
      "POST",
      "ilink/bot/getuploadurl",
      {
        filekey,
        media_type: kind === "image" ? UploadMediaType.IMAGE : kind === "video" ? UploadMediaType.VIDEO : UploadMediaType.FILE,
        to_user_id: toUserId,
        rawsize: plain.length,
        rawfilemd5: crypto.createHash("md5").update(plain).digest("hex"),
        filesize,
        no_need_thumb: true,
        aeskey: aeskey.toString("hex"),
      },
      15_000,
    );
    const up = parseWeixinApiJson<{ ret?: number; errcode?: number; errmsg?: string; upload_full_url?: string; upload_param?: string }>(raw || "{}");
    if ((up.ret && up.ret !== 0) || (up.errcode && up.errcode !== 0)) {
      throw new WeixinApiError(`getuploadurl ret=${up.ret} errcode=${up.errcode} errmsg=${up.errmsg ?? ""}`, up.ret, up.errcode);
    }
    const url = up.upload_full_url?.trim() || (up.upload_param ? `${this.cdnBase}/upload?encrypted_query_param=${encodeURIComponent(up.upload_param)}&filekey=${encodeURIComponent(filekey)}` : "");
    if (!url) throw new WeixinApiError(`getuploadurl returned no upload url (ret=${up.ret ?? ""})`, up.ret);
    const cipher = encryptAesEcb(plain, aeskey);
    let param = "";
    let lastErr: unknown;
    for (let attempt = 1; attempt <= 3 && !param; attempt++) {
      try {
        const res = await this.fetchImpl(url, { method: "POST", headers: { "Content-Type": "application/octet-stream" }, body: new Uint8Array(cipher), signal: AbortSignal.timeout(CDN_TIMEOUT_MS) });
        await res.arrayBuffer().catch(() => {});
        if (res.status >= 400 && res.status < 500) throw Object.assign(new Error(`CDN upload client error ${res.status} ${res.headers.get("x-error-message") ?? ""}`.trim()), { fatal: true });
        if (res.status !== 200) throw new Error(`CDN upload server error ${res.status}`);
        param = res.headers.get("x-encrypted-param") ?? "";
        if (!param) throw new Error("CDN upload response missing x-encrypted-param");
      } catch (e) {
        lastErr = e;
        if ((e as { fatal?: boolean }).fatal) throw e;
      }
    }
    if (!param) throw lastErr instanceof Error ? lastErr : new Error("CDN upload failed");
    // 与上游一致:aes_key 为十六进制密钥字符串的 base64
    const media = { encrypt_query_param: param, aes_key: Buffer.from(aeskey.toString("hex")).toString("base64"), encrypt_type: 1 };
    const item: MessageItem =
      kind === "image"
        ? { type: MessageItemType.IMAGE, image_item: { media, mid_size: filesize } }
        : kind === "video"
          ? { type: MessageItemType.VIDEO, video_item: { media, video_size: filesize } }
          : { type: MessageItemType.FILE, file_item: { media, file_name: path.basename(filePath), len: String(plain.length) } };
    await this.sendItem(toUserId, item, contextToken, clientId);
  }

  private get cdnBase(): string {
    return (this.opts.cdnBaseUrl || DEFAULT_CDN_BASE).replace(/\/+$/, "");
  }

  /**
   * 下载并解密用户发来的图片/文件/视频(含被引用消息里的)。
   * 移植自 openclaw-weixin src/media/media-download.ts、src/cdn/pic-decrypt.ts、src/cdn/cdn-url.ts。
   */
  async downloadMedia(item: MessageItem, maxBytes = MAX_INBOUND_MEDIA_BYTES): Promise<InboundMedia> {
    let kind: InboundMedia["kind"];
    let media: CdnMedia | undefined;
    let key: Buffer | undefined;
    if (item.type === MessageItemType.IMAGE) {
      kind = "image";
      media = item.image_item?.media;
      // image_item.aeskey(十六进制)优先;两者都没有时图片未加密
      const hex = item.image_item?.aeskey;
      if (hex && /^[0-9a-fA-F]{32}$/.test(hex)) key = Buffer.from(hex, "hex");
      else if (media?.aes_key) key = parseAesKey(media.aes_key);
    } else if (item.type === MessageItemType.FILE || item.type === MessageItemType.VIDEO) {
      kind = item.type === MessageItemType.FILE ? "file" : "video";
      media = kind === "file" ? item.file_item?.media : item.video_item?.media;
      if (!media?.aes_key) throw new Error(t("channel.aes_key_missing"));
      key = parseAesKey(media.aes_key);
    } else {
      throw new Error(t("channel.item_unsupported", { type: item.type }));
    }
    const full = media?.full_url?.trim();
    if (full && !/^https?:\/\//i.test(full)) throw new Error(t("channel.full_url_bad"));
    if (!full && !media?.encrypt_query_param) throw new Error(t("channel.no_cdn_ref"));
    const url = full || `${this.cdnBase}/download?encrypted_query_param=${encodeURIComponent(media!.encrypt_query_param!)}`;

    let raw: Buffer | undefined;
    let lastErr: unknown;
    for (let attempt = 1; attempt <= 3 && !raw; attempt++) {
      try {
        const res = await this.fetchImpl(url, { signal: AbortSignal.timeout(CDN_TIMEOUT_MS) });
        if (!res.ok) {
          await res.arrayBuffer().catch(() => {});
          const err = new Error(t("channel.cdn_failed_http", { status: res.status, message: res.headers.get("x-error-message") ?? "" }).trim());
          throw res.status < 500 ? Object.assign(err, { fatal: true }) : err;
        }
        const declared = Number(res.headers.get("content-length") ?? 0);
        if (declared > maxBytes) {
          await res.body?.cancel().catch(() => {});
          throw Object.assign(new Error(t("channel.too_large", { size: (declared / 1048576).toFixed(1), max: maxBytes / 1048576 })), { fatal: true });
        }
        const buf = Buffer.from(await res.arrayBuffer());
        if (buf.length > maxBytes) throw Object.assign(new Error(t("channel.too_large", { size: (buf.length / 1048576).toFixed(1), max: maxBytes / 1048576 })), { fatal: true });
        raw = buf;
      } catch (e) {
        lastErr = e;
        if ((e as { fatal?: boolean }).fatal) throw e;
      }
    }
    if (!raw) throw lastErr instanceof Error ? lastErr : new Error(t("channel.cdn_failed"));
    let data: Buffer;
    try {
      data = key ? decryptAesEcb(raw, key) : raw;
    } catch {
      throw new Error(t("channel.decrypt_failed"));
    }
    if (kind === "image") return { kind, data, mime: sniffImageMime(data) };
    if (kind === "file") return { kind, data, name: item.file_item?.file_name || "file" };
    return { kind, data };
  }

  private async sendItem(toUserId: string, item: MessageItem, contextToken: string, clientId?: string): Promise<void> {
    const raw = await this.request(
      "POST",
      "ilink/bot/sendmessage",
      {
        msg: {
          from_user_id: "",
          to_user_id: toUserId,
          client_id: clientId ? `amb:${clientId}` : `amb:${Date.now()}-${crypto.randomBytes(4).toString("hex")}`,
          message_type: MessageType.BOT,
          message_state: 2, // FINISH
          context_token: contextToken || undefined,
          item_list: [item],
        },
      },
      15_000,
    );
    const resp = parseWeixinApiJson<{ ret?: number; errcode?: number; errmsg?: string }>(raw || "{}");
    if ((resp.ret && resp.ret !== 0) || (resp.errcode && resp.errcode !== 0)) {
      throw new WeixinApiError(`sendmessage ret=${resp.ret} errmsg=${resp.errmsg ?? ""}`, resp.ret, resp.errcode);
    }
  }

  async getTypingTicket(userId: string, contextToken?: string): Promise<string> {
    const raw = await this.request("POST", "ilink/bot/getconfig", { ilink_user_id: userId, context_token: contextToken }, 10_000);
    const resp = JSON.parse(raw || "{}") as { ret?: number; typing_ticket?: string };
    return resp.typing_ticket || "";
  }

  async sendTyping(userId: string, ticket: string, typing: boolean): Promise<void> {
    await this.request("POST", "ilink/bot/sendtyping", { ilink_user_id: userId, typing_ticket: ticket, status: typing ? 1 : 2 }, 10_000);
  }
}