@nanhara/hara 0.70.0 → 0.89.0

package/dist/gateway/weixin.js

@@ -0,0 +1,590 @@
+// WeChat (personal) adapter for `hara gateway`, via Tencent's official iLink bot API
+// (ilinkai.weixin.qq.com). Text-DM happy path: QR login → long-poll getupdates → sendmessage.
+// Ported from the documented iLink wire protocol. Built-in fetch; QR rendering uses the optional
+// `qrcode-terminal` dep (graceful fallback to printing the URL). No encryption is needed on the text path
+// (iLink only uses crypto for media upload/download, which v1 doesn't do).
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { basename } from "node:path";
+import { randomBytes, randomUUID, createHash, createCipheriv, createDecipheriv } from "node:crypto";
+import { chunkText } from "./telegram.js";
+const ILINK_BASE_URL = "https://ilinkai.weixin.qq.com";
+const CHANNEL_VERSION = "2.2.0";
+const ILINK_APP_ID = "bot";
+const ILINK_APP_CLIENT_VERSION = String((2 << 16) | (2 << 8) | 0); // 131584
+const WEIXIN_CDN_BASE_URL = "https://novac2c.cdn.weixin.qq.com/c2c";
+const EP = {
+    getUpdates: "ilink/bot/getupdates",
+    sendMessage: "ilink/bot/sendmessage",
+    getBotQr: "ilink/bot/get_bot_qrcode",
+    getQrStatus: "ilink/bot/get_qrcode_status",
+    getUploadUrl: "ilink/bot/getuploadurl",
+};
+const LONG_POLL_TIMEOUT_MS = 35_000;
+const API_TIMEOUT_MS = 15_000;
+const QR_TIMEOUT_MS = 35_000;
+const SESSION_EXPIRED = -14;
+const RATE_LIMIT = -2;
+const MSG_TYPE_BOT = 2;
+const MSG_STATE_FINISH = 2;
+const ITEM_TEXT = 1;
+const ITEM_IMAGE = 2;
+const ITEM_VOICE = 3;
+const ITEM_FILE = 4; // item.type for a file attachment (audio is sent as a file — iLink voice bubbles unreliable)
+const MEDIA_IMAGE = 1; // media_type for getuploadurl when sending an image (inline)
+const MEDIA_FILE = 3; // media_type for getuploadurl when sending a file/audio
+const WEIXIN_CDN_ALLOWLIST = new Set([
+    "novac2c.cdn.weixin.qq.com",
+    "ilinkai.weixin.qq.com",
+    "wx.qlogo.cn",
+    "thirdwx.qlogo.cn",
+    "res.wx.qq.com",
+    "mmbiz.qpic.cn",
+    "mmbiz.qlogo.cn",
+]);
+const IMAGE_EXTS = new Set(["jpg", "jpeg", "png", "gif", "webp", "bmp"]);
+const INBOUND_MEDIA_MAX = 128 * 1024 * 1024; // 128 MiB cap, per the reference
+const num = (v) => (typeof v === "number" ? v : 0);
+const str = (v) => (v == null ? "" : String(v));
+// ── pure protocol helpers (unit-tested) ──────────────────────────────────────
+/** X-WECHAT-UIN: base64 of the decimal string of a random uint32 (regenerated per request). */
+export function randomWechatUin() {
+    const v = randomBytes(4).readUInt32BE(0);
+    return Buffer.from(String(v), "utf-8").toString("base64");
+}
+function ilinkHeaders(token, body) {
+    const h = {
+        "Content-Type": "application/json",
+        AuthorizationType: "ilink_bot_token",
+        "Content-Length": String(Buffer.byteLength(body, "utf-8")),
+        "X-WECHAT-UIN": randomWechatUin(),
+        "iLink-App-Id": ILINK_APP_ID,
+        "iLink-App-ClientVersion": ILINK_APP_CLIENT_VERSION,
+    };
+    if (token)
+        h.Authorization = `Bearer ${token}`;
+    return h;
+}
+/** Every POST body is compact JSON with base_info merged in. */
+export function envelope(payload) {
+    return JSON.stringify({ ...payload, base_info: { channel_version: CHANNEL_VERSION } });
+}
+/** The `sendmessage` body for a text DM (context_token omitted when falsy). */
+export function buildSendBody(to, text, contextToken, clientId) {
+    const msg = {
+        from_user_id: "",
+        to_user_id: to,
+        client_id: clientId,
+        message_type: MSG_TYPE_BOT,
+        message_state: MSG_STATE_FINISH,
+        item_list: [{ type: ITEM_TEXT, text_item: { text } }],
+    };
+    if (contextToken)
+        msg.context_token = contextToken;
+    return { msg };
+}
+/** iLink wants the AES key as base64 of the key's HEX-string ASCII bytes — NOT base64 of the raw key bytes.
+ *  (Getting this wrong = the receiver can't decrypt → unplayable/grey media.) */
+export function apiAesKey(keyHex) {
+    return Buffer.from(keyHex, "ascii").toString("base64");
+}
+/** The sendmessage item for a file attachment (audio/zip/pdf/doc/… — anything not shown inline). */
+export function audioFileItem(encryptQueryParam, aesKeyForApi, rawsize, filename) {
+    return {
+        type: ITEM_FILE,
+        file_item: {
+            media: { encrypt_query_param: encryptQueryParam, aes_key: aesKeyForApi, encrypt_type: 1 },
+            file_name: filename,
+            len: String(rawsize), // plaintext size, as a STRING (a file_item quirk — image uses ciphertext size as int)
+        },
+    };
+}
+/** The sendmessage item for an inline image (shows in the chat, not as a file). mid_size = CIPHERTEXT size (int). */
+export function imageInlineItem(encryptQueryParam, aesKeyForApi, ciphertextSize) {
+    return {
+        type: ITEM_IMAGE,
+        image_item: {
+            media: { encrypt_query_param: encryptQueryParam, aes_key: aesKeyForApi, encrypt_type: 1 },
+            mid_size: ciphertextSize,
+        },
+    };
+}
+/** First text item's text (iLink puts text under item_list[].text_item.text; voice falls back to type 3). */
+export function extractText(itemList) {
+    if (!Array.isArray(itemList))
+        return "";
+    for (const item of itemList) {
+        if (item?.type === ITEM_TEXT)
+            return str(item?.text_item?.text);
+        if (item?.type === 3)
+            return str(item?.voice_item?.text);
+    }
+    return "";
+}
+/** DM vs group: a room id (or a non-self to_user with msg_type 1) means group; else DM keyed by from_user_id. */
+export function guessChatType(msg, accountId) {
+    const roomId = str(msg?.room_id ?? msg?.chat_room_id).trim();
+    const toUserId = str(msg?.to_user_id).trim();
+    const isGroup = !!roomId || (!!toUserId && !!accountId && toUserId !== accountId && msg?.msg_type === 1);
+    if (isGroup)
+        return { kind: "group", id: roomId || toUserId || str(msg?.from_user_id) };
+    return { kind: "dm", id: str(msg?.from_user_id) };
+}
+/** Parse one inbound iLink message → InboundMsg + its context_token. null = skip (own echo / group / non-text). */
+export function parseWeixinMessage(msg, accountId) {
+    const from = str(msg?.from_user_id).trim();
+    if (!from || from === accountId)
+        return null; // missing sender, or our own echo
+    if (guessChatType(msg, accountId).kind !== "dm")
+        return null; // v1 = text DM only
+    const items = Array.isArray(msg?.item_list) ? msg.item_list : [];
+    const text = extractText(items);
+    if (!text)
+        return null;
+    // A voice message arrives as iLink's server-side transcription (voice_item.text). Prefix an explicit note —
+    // NOT a bare "[voice message]" label, which hara misreads as raw audio it must process (and then disclaims).
+    // This tells it the text is already transcribed so it just answers.
+    const isVoice = !items.some((i) => i?.type === ITEM_TEXT) && items.some((i) => i?.type === 3);
+    const tagged = isVoice ? `(The user sent this as a voice message; it is already transcribed to text below — just reply to it normally, you don't have or need the audio.)\n\n${text}` : text;
+    return { inbound: { chatId: from, userId: from, userName: from, text: tagged }, contextToken: str(msg?.context_token).trim() };
+}
+/** iLink signals expiry via -14, or -2 + errmsg "unknown error" (a stale-session masquerading as rate-limit). */
+export function isSessionExpired(ret, errcode, errmsg) {
+    if (ret === SESSION_EXPIRED || errcode === SESSION_EXPIRED)
+        return true;
+    if (ret !== RATE_LIMIT && errcode !== RATE_LIMIT)
+        return false;
+    return (errmsg || "").toLowerCase() === "unknown error";
+}
+// ── HTTP + state ──────────────────────────────────────────────────────────────
+const sleep = (ms, signal) => new Promise((res) => {
+    if (signal?.aborted)
+        return res();
+    const t = setTimeout(() => res(), ms);
+    signal?.addEventListener?.("abort", () => { clearTimeout(t); res(); }, { once: true });
+});
+function combineSignals(timeoutMs, external) {
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const anyFn = AbortSignal.any;
+    return external && typeof anyFn === "function" ? anyFn([timeout, external]) : timeout;
+}
+async function apiPost(baseUrl, endpoint, payload, token, timeoutMs, external) {
+    const body = envelope(payload);
+    const url = `${baseUrl.replace(/\/+$/, "")}/${endpoint}`;
+    const res = await fetch(url, { method: "POST", body, headers: ilinkHeaders(token, body), signal: combineSignals(timeoutMs, external) });
+    const raw = await res.text();
+    if (!res.ok)
+        throw new Error(`iLink POST ${endpoint} HTTP ${res.status}: ${raw.slice(0, 200)}`);
+    return JSON.parse(raw);
+}
+async function apiGet(baseUrl, endpoint, timeoutMs) {
+    const url = `${baseUrl.replace(/\/+$/, "")}/${endpoint}`;
+    const headers = { "iLink-App-Id": ILINK_APP_ID, "iLink-App-ClientVersion": ILINK_APP_CLIENT_VERSION };
+    const res = await fetch(url, { headers, signal: AbortSignal.timeout(timeoutMs) });
+    const raw = await res.text();
+    if (!res.ok)
+        throw new Error(`iLink GET ${endpoint} HTTP ${res.status}: ${raw.slice(0, 200)}`);
+    return JSON.parse(raw);
+}
+const weixinDir = () => join(homedir(), ".hara", "weixin");
+const credsFile = () => join(weixinDir(), "creds.json");
+export function loadWeixinCreds() {
+    try {
+        return existsSync(credsFile()) ? JSON.parse(readFileSync(credsFile(), "utf8")) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveWeixinCreds(c) {
+    mkdirSync(weixinDir(), { recursive: true });
+    writeFileSync(credsFile(), JSON.stringify(c, null, 2), { mode: 0o600 });
+}
+// get_updates_buf cursor — persisted so a restart resumes the message stream where it left off.
+function loadCursor(accountId) {
+    try {
+        const f = join(weixinDir(), `${accountId}.cursor`);
+        return existsSync(f) ? readFileSync(f, "utf8") : "";
+    }
+    catch {
+        return "";
+    }
+}
+function saveCursor(accountId, buf) {
+    try {
+        mkdirSync(weixinDir(), { recursive: true });
+        writeFileSync(join(weixinDir(), `${accountId}.cursor`), buf);
+    }
+    catch {
+        /* best-effort */
+    }
+}
+// Per-peer context_token: every reply must echo the latest token iLink sent for that peer.
+class TokenStore {
+    accountId;
+    cache = {};
+    constructor(accountId) {
+        this.accountId = accountId;
+        try {
+            if (existsSync(this.file()))
+                this.cache = JSON.parse(readFileSync(this.file(), "utf8"));
+        }
+        catch {
+            this.cache = {};
+        }
+    }
+    file() {
+        return join(weixinDir(), `${this.accountId}.context-tokens.json`);
+    }
+    persist() {
+        try {
+            mkdirSync(weixinDir(), { recursive: true });
+            writeFileSync(this.file(), JSON.stringify(this.cache));
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    get(peer) {
+        return this.cache[peer] || undefined;
+    }
+    set(peer, token) {
+        if (token) {
+            this.cache[peer] = token;
+            this.persist();
+        }
+    }
+    del(peer) {
+        delete this.cache[peer];
+        this.persist();
+    }
+}
+async function renderQr(data) {
+    try {
+        const spec = "qrcode-terminal"; // optional dep; variable specifier so tsc doesn't require it at build time
+        const mod = (await import(spec));
+        const qr = mod.default ?? mod;
+        console.error("\nScan this QR with WeChat (Me → … or Discover → Scan):\n");
+        await new Promise((res) => qr.generate(data, { small: true }, (s) => { console.error(s); res(); }));
+    }
+    catch {
+        console.error(`\nScan this as a QR with WeChat — install 'qrcode-terminal' to render it inline, or paste this URL into any QR generator:\n${data}\n`);
+    }
+}
+/** Interactive QR login → saves {account_id, token, base_url, user_id} to ~/.hara/weixin/creds.json. */
+export async function weixinLogin(timeoutSeconds = 480) {
+    let qr = await apiGet(ILINK_BASE_URL, `${EP.getBotQr}?bot_type=3`, QR_TIMEOUT_MS);
+    let qrcodeValue = str(qr.qrcode);
+    await renderQr(str(qr.qrcode_img_content) || qrcodeValue);
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let baseUrl = ILINK_BASE_URL;
+    let refreshes = 0;
+    let lastStatus = "";
+    while (Date.now() < deadline) {
+        let st;
+        try {
+            st = await apiGet(baseUrl, `${EP.getQrStatus}?qrcode=${encodeURIComponent(qrcodeValue)}`, QR_TIMEOUT_MS);
+        }
+        catch {
+            await sleep(1000);
+            continue;
+        }
+        const status = str(st.status) || "wait";
+        if (status !== lastStatus && status === "scaned")
+            console.error("weixin login: scanned — confirm on your phone…");
+        lastStatus = status;
+        if (status === "confirmed") {
+            const creds = {
+                account_id: str(st.ilink_bot_id),
+                token: str(st.bot_token),
+                base_url: str(st.baseurl) || ILINK_BASE_URL,
+                user_id: str(st.ilink_user_id),
+            };
+            if (!creds.account_id || !creds.token) {
+                console.error("weixin login: confirmed but missing account_id/token");
+                return null;
+            }
+            saveWeixinCreds(creds);
+            console.error(`weixin login: ✓ logged in as ${creds.account_id} (base ${creds.base_url})`);
+            return creds;
+        }
+        if (status === "scaned_but_redirect") {
+            const host = str(st.redirect_host);
+            if (host)
+                baseUrl = `https://${host}`; // subsequent calls use the redirected host
+        }
+        else if (status === "expired") {
+            if (++refreshes > 3) {
+                console.error("weixin login: QR expired too many times — aborting");
+                return null;
+            }
+            qr = await apiGet(ILINK_BASE_URL, `${EP.getBotQr}?bot_type=3`, QR_TIMEOUT_MS);
+            qrcodeValue = str(qr.qrcode);
+            baseUrl = ILINK_BASE_URL;
+            await renderQr(str(qr.qrcode_img_content) || qrcodeValue);
+        }
+        await sleep(1000);
+    }
+    console.error("weixin login: timed out");
+    return null;
+}
+async function sendChunk(creds, tokenStore, peer, text) {
+    const clientId = `hara-weixin-${randomUUID().replace(/-/g, "")}`; // reused across the -14 retry for dedup
+    const post = (ctx) => apiPost(creds.base_url, EP.sendMessage, buildSendBody(peer, text, ctx, clientId), creds.token, API_TIMEOUT_MS).catch((e) => ({ ret: 1, errmsg: String(e?.message ?? e) }));
+    let resp = await post(tokenStore.get(peer));
+    let [ret, errcode, errmsg] = [num(resp.ret), num(resp.errcode), str(resp.errmsg ?? resp.msg)];
+    if (isSessionExpired(ret, errcode, errmsg)) {
+        tokenStore.del(peer); // stale → drop it and retry once tokenless (iLink accepts that, degraded)
+        resp = await post(undefined);
+        [ret, errcode, errmsg] = [num(resp.ret), num(resp.errcode), str(resp.errmsg ?? resp.msg)];
+    }
+    if (ret !== 0 || errcode !== 0)
+        console.error(`weixin send: ret=${ret} errcode=${errcode} errmsg=${errmsg}`);
+}
+function aes128EcbEncrypt(plaintext, key) {
+    const c = createCipheriv("aes-128-ecb", key, null); // PKCS7 auto-padding (Node default) matches iLink
+    return Buffer.concat([c.update(plaintext), c.final()]);
+}
+// ── inbound media (receive a file/image/voice the user sent) ──────────────────
+/** Parse an inbound `media.aes_key`: base64 → 16 raw bytes, OR base64 → 32-char ascii hex → hex-decode. */
+export function parseAesKey(aesKeyB64) {
+    const decoded = Buffer.from(aesKeyB64, "base64");
+    if (decoded.length === 16)
+        return decoded;
+    if (decoded.length === 32 && /^[0-9a-fA-F]{32}$/.test(decoded.toString("ascii")))
+        return Buffer.from(decoded.toString("ascii"), "hex");
+    throw new Error(`unexpected aes_key format (${decoded.length} bytes)`);
+}
+function aes128EcbDecrypt(ciphertext, key) {
+    const d = createDecipheriv("aes-128-ecb", key, null);
+    d.setAutoPadding(false); // iLink's strip is conditional (tolerates non-PKCS7) — replicate it ourselves
+    const padded = Buffer.concat([d.update(ciphertext), d.final()]);
+    if (!padded.length)
+        return padded;
+    const pad = padded[padded.length - 1];
+    if (pad >= 1 && pad <= 16 && padded.length >= pad) {
+        let ok = true;
+        for (let i = padded.length - pad; i < padded.length; i++)
+            if (padded[i] !== pad)
+                ok = false;
+        if (ok)
+            return padded.subarray(0, padded.length - pad);
+    }
+    return padded;
+}
+/** Downloadable media items in an inbound message (pure). Skips voice that already carries a transcription. */
+export function inboundMediaRefs(itemList) {
+    const items = Array.isArray(itemList) ? itemList : [];
+    const out = [];
+    for (const it of items) {
+        if (it?.type === ITEM_IMAGE) {
+            const media = it.image_item?.media ?? {};
+            // image key hack: prefer image_item.aeskey (hex) re-encoded as base64(ascii(hex)); else media.aes_key
+            const hex = str(it.image_item?.aeskey);
+            const aesKeyB64 = (hex && Buffer.from(hex, "ascii").toString("base64")) || str(media.aes_key) || undefined;
+            out.push({ kind: "image", encryptQueryParam: str(media.encrypt_query_param) || undefined, fullUrl: str(media.full_url) || undefined, aesKeyB64 });
+        }
+        else if (it?.type === ITEM_FILE) {
+            const media = it.file_item?.media ?? {};
+            out.push({ kind: "file", encryptQueryParam: str(media.encrypt_query_param) || undefined, fullUrl: str(media.full_url) || undefined, aesKeyB64: str(media.aes_key) || undefined, fileName: str(it.file_item?.file_name) || "document.bin" });
+        }
+        else if (it?.type === ITEM_VOICE && !str(it.voice_item?.text)) {
+            const media = it.voice_item?.media ?? {};
+            out.push({ kind: "voice", encryptQueryParam: str(media.encrypt_query_param) || undefined, fullUrl: str(media.full_url) || undefined, aesKeyB64: str(media.aes_key) || undefined });
+        }
+    }
+    return out;
+}
+const cdnDownloadUrl = (param) => `${WEIXIN_CDN_BASE_URL}/download?encrypted_query_param=${encodeURIComponent(param)}`;
+const mediaDir = () => join(weixinDir(), "media");
+const sanitizeName = (name) => name.replace(/[^\w.\- ]+/g, "_").slice(-80) || "file.bin";
+function assertCdnHost(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error(`unparseable media URL: ${url}`);
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:")
+        throw new Error(`disallowed scheme ${u.protocol}`);
+    if (!WEIXIN_CDN_ALLOWLIST.has(u.hostname))
+        throw new Error(`host ${u.hostname} not in WeChat CDN allowlist (SSRF guard)`);
+}
+/** Download (+ AES-decrypt if keyed) an inbound media item to a local file. Returns its path + mime, or null. */
+export async function downloadInboundMedia(ref) {
+    try {
+        let url;
+        if (ref.encryptQueryParam)
+            url = cdnDownloadUrl(ref.encryptQueryParam);
+        else if (ref.fullUrl) {
+            assertCdnHost(ref.fullUrl);
+            url = ref.fullUrl;
+        }
+        else
+            return null;
+        const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+        if (!res.ok)
+            throw new Error(`media download HTTP ${res.status}`);
+        const ab = await res.arrayBuffer();
+        if (ab.byteLength > INBOUND_MEDIA_MAX)
+            throw new Error("media exceeds size cap");
+        let buf = Buffer.from(ab);
+        if (ref.aesKeyB64)
+            buf = aes128EcbDecrypt(buf, parseAesKey(ref.aesKeyB64));
+        if (!buf.length)
+            return null;
+        mkdirSync(mediaDir(), { recursive: true });
+        const tag = randomUUID().slice(0, 8);
+        const name = ref.kind === "image" ? `img_${tag}.jpg` : ref.kind === "voice" ? `audio_${tag}.silk` : `${tag}_${sanitizeName(ref.fileName || "document.bin")}`;
+        const path = join(mediaDir(), name);
+        writeFileSync(path, buf);
+        return { path, mime: ref.kind === "image" ? "image/jpeg" : ref.kind === "voice" ? "audio/silk" : "application/octet-stream" };
+    }
+    catch (e) {
+        console.error(`weixin inbound media (${ref.kind}): ${e?.message ?? e}`);
+        return null;
+    }
+}
+async function cdnUpload(uploadUrl, ciphertext) {
+    const res = await fetch(uploadUrl, { method: "POST", body: new Uint8Array(ciphertext), headers: { "Content-Type": "application/octet-stream" }, signal: AbortSignal.timeout(120_000) });
+    await res.arrayBuffer().catch(() => undefined); // drain body
+    if (!res.ok)
+        throw new Error(`CDN upload HTTP ${res.status}`);
+    const ep = res.headers.get("x-encrypted-param");
+    if (!ep)
+        throw new Error("CDN upload missing x-encrypted-param header");
+    return ep;
+}
+/** Send a local file to a peer. Images go inline (image_item); everything else (audio/zip/pdf/doc/…) goes as a
+ *  file attachment (file_item) carrying the filename. Ported byte-exact from iLink's media protocol:
+ *  getuploadurl → AES-128-ECB encrypt → CDN POST → sendmessage(item). */
+export async function sendMediaFile(creds, tokenStore, peer, filePath) {
+    try {
+        const plaintext = readFileSync(filePath);
+        const rawsize = plaintext.length;
+        const isImage = IMAGE_EXTS.has((filePath.split(".").pop() || "").toLowerCase());
+        const rawfilemd5 = createHash("md5").update(plaintext).digest("hex");
+        const filekey = randomBytes(16).toString("hex");
+        const key = randomBytes(16);
+        const keyHex = key.toString("hex");
+        const filesize = Math.ceil((rawsize + 1) / 16) * 16; // AES-padded size == ciphertext length
+        const up = await apiPost(creds.base_url, EP.getUploadUrl, { filekey, media_type: isImage ? MEDIA_IMAGE : MEDIA_FILE, to_user_id: peer, rawsize, rawfilemd5, filesize, no_need_thumb: true, aeskey: keyHex }, creds.token, API_TIMEOUT_MS);
+        const ciphertext = aes128EcbEncrypt(plaintext, key);
+        const fullUrl = str(up.upload_full_url);
+        const param = str(up.upload_param);
+        const uploadUrl = fullUrl || (param ? `${WEIXIN_CDN_BASE_URL}/upload?encrypted_query_param=${encodeURIComponent(param)}&filekey=${encodeURIComponent(filekey)}` : "");
+        if (!uploadUrl)
+            throw new Error("getuploadurl returned neither upload_full_url nor upload_param");
+        const encryptedParam = await cdnUpload(uploadUrl, ciphertext);
+        const item = isImage
+            ? imageInlineItem(encryptedParam, apiAesKey(keyHex), ciphertext.length)
+            : audioFileItem(encryptedParam, apiAesKey(keyHex), rawsize, basename(filePath));
+        const clientId = `hara-weixin-${randomUUID().replace(/-/g, "")}`; // reused across the -14 retry for dedup
+        const send = (ctx) => {
+            const msg = { from_user_id: "", to_user_id: peer, client_id: clientId, message_type: MSG_TYPE_BOT, message_state: MSG_STATE_FINISH, item_list: [item] };
+            if (ctx)
+                msg.context_token = ctx;
+            return apiPost(creds.base_url, EP.sendMessage, { msg }, creds.token, API_TIMEOUT_MS);
+        };
+        let res = await send(tokenStore.get(peer));
+        let [ret, errcode, errmsg] = [num(res.ret), num(res.errcode), str(res.errmsg ?? res.msg)];
+        if (isSessionExpired(ret, errcode, errmsg)) {
+            tokenStore.del(peer);
+            res = await send(undefined); // tokenless retry (degraded fallback iLink accepts)
+            [ret, errcode, errmsg] = [num(res.ret), num(res.errcode), str(res.errmsg ?? res.msg)];
+        }
+        if (ret !== 0 || errcode !== 0) {
+            console.error(`weixin sendMedia: ret=${ret} errcode=${errcode} errmsg=${errmsg}`);
+            return false;
+        }
+        return true;
+    }
+    catch (e) {
+        console.error(`weixin sendMedia: ${e?.message ?? e}`);
+        return false;
+    }
+}
+export function weixinAdapter(creds) {
+    const tokenStore = new TokenStore(creds.account_id);
+    // Reuse parseWeixinMessage for text/voice-transcription, then download any image/file/voice media and append
+    // a `[kind: localpath]` reference so hara can read the file. Handles media-only messages (no text) too.
+    const buildInbound = async (msg) => {
+        const parsed = parseWeixinMessage(msg, creds.account_id);
+        const from = str(msg?.from_user_id).trim();
+        if (!from || from === creds.account_id)
+            return null;
+        if (guessChatType(msg, creds.account_id).kind !== "dm")
+            return null;
+        let text = parsed?.inbound.text ?? "";
+        const images = [];
+        for (const ref of inboundMediaRefs(msg?.item_list)) {
+            const dl = await downloadInboundMedia(ref);
+            if (!dl)
+                continue;
+            if (ref.kind === "image") {
+                // images go through as real attachments (seen/described downstream); leave only a light marker in text
+                images.push(dl.path);
+                text += `${text ? "\n" : ""}[图片]`;
+            }
+            else {
+                const label = ref.kind === "voice" ? "语音" : `文件 ${ref.fileName ?? ""}`.trim();
+                text += `${text ? "\n" : ""}[${label}: ${dl.path}]`;
+            }
+        }
+        text = text.trim();
+        if (!text && !images.length)
+            return null;
+        tokenStore.set(from, parsed?.contextToken || str(msg?.context_token).trim());
+        return { chatId: from, userId: from, userName: from, text: text || "[图片]", images: images.length ? images : undefined };
+    };
+    return {
+        name: "weixin",
+        async send(chatId, text) {
+            const peer = String(chatId);
+            for (const part of chunkText(text || "(empty)"))
+                await sendChunk(creds, tokenStore, peer, part);
+        },
+        async sendFile(chatId, filePath) {
+            await sendMediaFile(creds, tokenStore, String(chatId), filePath);
+        },
+        async start(onMessage, signal) {
+            let buf = loadCursor(creds.account_id);
+            let pollMs = LONG_POLL_TIMEOUT_MS;
+            while (!signal.aborted) {
+                let resp;
+                try {
+                    // client timeout is a touch longer than the server long-poll so an empty batch returns before we abort
+                    resp = await apiPost(creds.base_url, EP.getUpdates, { get_updates_buf: buf }, creds.token, pollMs + 5_000, signal);
+                }
+                catch {
+                    if (signal.aborted)
+                        break;
+                    await sleep(2000, signal); // timeout (normal) or network blip → re-poll
+                    continue;
+                }
+                const ret = num(resp.ret);
+                const errcode = num(resp.errcode);
+                if (isSessionExpired(ret, errcode, str(resp.errmsg))) {
+                    console.error("weixin: session expired — re-login with `hara gateway --platform weixin --login`. backing off 600s.");
+                    await sleep(600_000, signal);
+                    continue;
+                }
+                if (ret !== 0 || errcode !== 0) {
+                    await sleep(2000, signal);
+                    continue;
+                }
+                buf = str(resp.get_updates_buf) || buf;
+                saveCursor(creds.account_id, buf);
+                for (const msg of Array.isArray(resp.msgs) ? resp.msgs : []) {
+                    const inbound = await buildInbound(msg);
+                    if (inbound)
+                        await onMessage(inbound).catch(() => { });
+                }
+                const lp = num(resp.longpolling_timeout_ms);
+                pollMs = lp > 0 ? lp : LONG_POLL_TIMEOUT_MS;
+            }
+        },
+    };
+}