@zhin.js/adapter-weixin-ilink 1.0.1 → 1.1.2

package/lib/endpoint.js

@@ -1,282 +1,263 @@
 /**
- * 微信 iLink Bot：长轮询入站 + CDN 媒体收发
+ * WeixinIlinkEndpoint — lifecycle, long-poll inbound, outbound send.
  */
-import crypto from "node:crypto";
-import fs from "node:fs";
-import path from "node:path";
-import { Message, segment, } from "zhin.js";
-import { getUpdates, notifyStart, notifyStop, sendTyping } from "./ilink-api.js";
-import { configureIlinkMeta, DEFAULT_API_BASE_URL, DEFAULT_CDN_BASE_URL, } from "./ilink-meta.js";
-import { loadSyncBuf, resolveStateDir, saveSyncBuf, } from "./credentials.js";
-import { resolveCredentials } from "./login.js";
-import { bodyFromItemList, getContextToken, isMediaItem, restoreContextTokens, setContextToken, } from "./context-store.js";
-import { WeixinConfigManager } from "./ilink-config-cache.js";
-import { getRemainingPauseMs, isSessionPaused, pauseSession, SESSION_EXPIRED_ERRCODE, } from "./ilink-session-guard.js";
-import { downloadMediaFromItem } from "./media-download.js";
-import { sendMessageWeixin } from "./weixin-send.js";
-import { sendWeixinMediaFile } from "./weixin-send-media.js";
-import { materializeOutboundMedia, segmentMediaRef } from "./outbound-media.js";
-import { MessageItemType } from "./ilink-types.js";
-import { getExtensionFromMime, sniffMimeFromBuffer } from "./mime.js";
-import { WeixinIlinkTypingIndicatorManager, } from "./typing-indicator.js";
-const DEFAULT_LONG_POLL_TIMEOUT_MS = 35_000;
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Endpoint, } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { getUpdates, notifyStart, notifyStop } from './ilink-api.js';
+import { IlinkClientMetadata } from './ilink-meta.js';
+import { WeixinIlinkStateStore, } from './credentials.js';
+import { resolveCredentials } from './login.js';
+import { WeixinContextTokenStore, } from './context-store.js';
+import { WeixinConfigManager } from './ilink-config-cache.js';
+import { IlinkSessionGuard, SESSION_EXPIRED_ERRCODE, } from './ilink-session-guard.js';
+import { downloadMediaFromItem } from './media-download.js';
+import { sendMessageWeixin } from './weixin-send.js';
+import { materializeOutboundMedia } from './outbound-media.js';
+import { MessageItemType } from './ilink-types.js';
+import { getExtensionFromMime, sniffMimeFromBuffer } from './mime.js';
+import { formatInboundContent, weixinInboundSegments, weixinReplyTo, formatOutboundSegments, inboundMessageId, segmentLocalPath, sleep, weixinIlinkInboundConversation, } from './protocol.js';
+import { WeixinIlinkClient } from './client.js';
 const MAX_CONSECUTIVE_FAILURES = 3;
 const BACKOFF_DELAY_MS = 30_000;
 const RETRY_DELAY_MS = 2_000;
 const WEIXIN_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
-function sleep(ms, signal) {
-    return new Promise((resolve) => {
-        if (signal?.aborted) {
-            resolve();
-            return;
-        }
-        const timer = setTimeout(resolve, ms);
-        signal?.addEventListener("abort", () => {
-            clearTimeout(timer);
-            resolve();
-        }, { once: true });
+/** 入站媒体保留 24h，每小时清扫一次。 */
+const INBOUND_MEDIA_TTL_MS = 24 * 60 * 60 * 1000;
+const MEDIA_SWEEP_INTERVAL_MS = 60 * 60 * 1000;
+export class WeixinIlinkEndpoint extends Endpoint {
+    client;
+    #logger;
+    #options;
+    #resolveCredentials;
+    #notifyStart;
+    #notifyStop;
+    #getUpdates;
+    #sendText;
+    #state;
+    #contextTokens;
+    #sessionGuard;
+    #metadata;
+    #creds = null;
+    #pollAbort;
+    #pollPromise;
+    #loginAbort;
+    #configManager;
+    #mediaSweepTimer;
+    #open = false;
+    #started = false;
+    management = createWeixinIlinkEndpointManagement(() => this.client);
+    control = Object.freeze({
+        typing: async (conversation, active) => {
+            await this.client.sendTyping(conversation.id, active === false ? 2 : 1);
+        },
     });
-}
-function segmentLocalPath(seg) {
-    const ref = segmentMediaRef(seg);
-    if (!ref || ref.startsWith("base64://") || /^data:/.test(ref) || /^https?:\/\//i.test(ref)) {
-        return undefined;
-    }
-    return ref.replace(/^file:\/\//, "");
-}
-export class WeixinIlinkEndpoint {
-    adapter;
-    $config;
-    $connected = false;
-    $typingIndicator;
-    creds = null;
-    pollAbort;
-    pollPromise;
-    configManager;
-    get $id() {
-        return this.$config.name;
+    constructor(options) {
+        super();
+        this.#logger = getAdapterLogger('weixin-ilink', options.config.id);
+        this.#options = options;
+        this.#resolveCredentials = options.resolveCredentials ?? resolveCredentials;
+        this.#notifyStart = options.notifyStart ?? notifyStart;
+        this.#notifyStop = options.notifyStop ?? notifyStop;
+        this.#getUpdates = options.getUpdates ?? getUpdates;
+        this.#sendText = options.sendText ?? sendMessageWeixin;
+        this.#state = options.state
+            ?? new WeixinIlinkStateStore(options.config.id, options.config.dataDir);
+        this.#contextTokens = options.contextTokens ?? new WeixinContextTokenStore(this.#state);
+        this.#sessionGuard = options.sessionGuard ?? new IlinkSessionGuard(options.config.id);
+        this.#metadata = new IlinkClientMetadata({ botAgent: options.config.botAgent });
+        this.client = new WeixinIlinkClient(options.config, this.#metadata, () => this.#creds, () => this.#configManager, this.#sendText, this.#contextTokens);
     }
     get hasCredentials() {
-        return Boolean(this.creds?.botToken);
+        return this.client.authenticated;
     }
-    get pluginLogger() {
-        return this.adapter.plugin.logger;
-    }
-    constructor(adapter, $config) {
-        this.adapter = adapter;
-        this.$config = $config;
-    }
-    apiBaseUrl() {
-        return this.$config.baseUrl ?? this.creds?.baseUrl ?? DEFAULT_API_BASE_URL;
+    async start() {
+        if (this.#started)
+            return;
+        this.#started = true;
+        try {
+            // QR 登录最长 8 分钟：stop() 必须能打断
+            this.#loginAbort = new AbortController();
+            this.#creds = await this.#resolveCredentials(this.#options.config, this.#metadata, this.#state, this.#loginAbort.signal);
+            this.#contextTokens.restore();
+            await this.#notifyStart({
+                baseUrl: this.client.apiBaseUrl,
+                metadata: this.#metadata,
+                token: this.#creds.botToken,
+            });
+            this.#configManager = new WeixinConfigManager({
+                baseUrl: this.client.apiBaseUrl,
+                metadata: this.#metadata,
+                token: this.#creds.botToken,
+            }, (msg) => this.#logger.debug(msg));
+            this.#pollAbort = new AbortController();
+            this.#pollPromise = this.#pollLoop(this.#pollAbort.signal);
+            this.#startMediaSweep();
+            this.#logger.info(formatCompact({
+                op: 'connect',
+                endpoint: this.#options.config.id,
+            }));
+            void this.#emitPlatformEvent('system.online', {
+                account: this.#options.config.id,
+            });
+        }
+        catch (error) {
+            await this.stop();
+            this.#logger.error('Failed to connect weixin-ilink bot:', error);
+            throw error;
+        }
     }
-    cdnBaseUrl() {
-        return this.$config.cdnBaseUrl ?? DEFAULT_CDN_BASE_URL;
+    open() {
+        this.#open = true;
     }
-    async $connect() {
-        configureIlinkMeta({ botAgent: this.$config.botAgent });
-        this.creds = await resolveCredentials(this.adapter.plugin, this.$config);
-        restoreContextTokens(this.$id);
-        await notifyStart({
-            baseUrl: this.apiBaseUrl(),
-            token: this.creds.botToken,
-        });
-        this.configManager = new WeixinConfigManager({ baseUrl: this.apiBaseUrl(), token: this.creds.botToken }, (msg) => this.pluginLogger.debug(msg));
-        if (this.$config.typingIndicator?.enabled !== false) {
-            this.$typingIndicator = new WeixinIlinkTypingIndicatorManager(this, this.$config.typingIndicator);
-        }
-        this.pollAbort = new AbortController();
-        this.pollPromise = this.pollLoop(this.pollAbort.signal);
-        this.$connected = true;
-        this.pluginLogger.info(`weixin-ilink endpoint ${this.$id} connected`);
+    close() {
+        this.#open = false;
     }
-    async $disconnect() {
-        this.pollAbort?.abort();
+    async stop() {
+        this.#open = false;
+        this.#loginAbort?.abort();
+        this.#pollAbort?.abort();
         try {
-            await this.pollPromise;
+            await this.#pollPromise;
         }
         catch {
             /* poll loop exit */
         }
-        if (this.creds?.botToken) {
+        this.#stopMediaSweep();
+        // 防抖中的 context token 落盘，避免 stop 丢尾部写入
+        this.#contextTokens.flush();
+        if (this.#creds?.botToken) {
             try {
-                await notifyStop({ baseUrl: this.apiBaseUrl(), token: this.creds.botToken });
+                await this.#notifyStop({
+                    baseUrl: this.client.apiBaseUrl,
+                    metadata: this.#metadata,
+                    token: this.#creds.botToken,
+                });
             }
             catch (err) {
-                this.pluginLogger.warn(`notifyStop failed: ${String(err)}`);
+                this.#logger.warn(formatCompact({
+                    op: 'notify_stop',
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
             }
         }
-        this.$connected = false;
-        this.pluginLogger.info(`weixin-ilink endpoint ${this.$id} disconnected`);
-    }
-    async sendTypingToUser(userId, status) {
-        if (!this.creds?.botToken || !this.configManager)
-            return;
-        const contextToken = getContextToken(this.$id, userId);
-        const cfg = await this.configManager.getForUser(userId, contextToken);
-        if (!cfg.typingTicket) {
-            this.pluginLogger.debug(`sendTyping: no typing_ticket for user=${userId}`);
-            return;
-        }
-        await sendTyping({
-            baseUrl: this.apiBaseUrl(),
-            token: this.creds.botToken,
-            body: {
-                ilink_user_id: userId,
-                typing_ticket: cfg.typingTicket,
-                status,
-            },
-        });
-    }
-    async $recallMessage(_id) {
-        this.pluginLogger.debug("weixin-ilink does not support message recall");
-    }
-    $formatMessage(msg) {
-        const userId = msg.from_user_id ?? "";
-        const content = this.buildInboundContent(msg);
-        const quoteId = Message.quoteIdFromContent(content);
-        Message.alignReplySegments(content, quoteId);
-        const msgId = String(msg.message_id ?? msg.client_id ?? msg.seq ?? Date.now());
-        return Message.from(msg, {
-            $id: msgId,
-            $adapter: "weixin-ilink",
-            $endpoint: this.$config.name,
-            $sender: {
-                id: userId,
-                name: userId,
-            },
-            $channel: {
-                id: userId,
-                type: "private",
-            },
-            $content: content,
-            $quote_id: quoteId,
-            $raw: bodyFromItemList(msg.item_list),
-            $timestamp: msg.create_time_ms ?? Date.now(),
-            $recall: async () => this.$recallMessage(msgId),
-            $reply: async (replyContent, _quote) => {
-                if (!Array.isArray(replyContent))
-                    replyContent = [replyContent];
-                return this.adapter.sendMessage({
-                    context: "weixin-ilink",
-                    endpoint: this.$config.name,
-                    id: userId,
-                    type: "private",
-                    content: replyContent,
-                });
-            },
+        this.#started = false;
+        void this.#emitPlatformEvent('system.offline', {
+            account: this.#options.config.id,
         });
+        this.#logger.debug(formatCompact({
+            op: 'disconnect',
+        }));
     }
-    buildInboundContent(msg) {
-        const segments = [];
-        const text = bodyFromItemList(msg.item_list);
-        if (text)
-            segments.push(segment.text(text));
-        const media = msg._media;
-        if (media?.decryptedPicPath) {
-            segments.push(segment("image", { file: media.decryptedPicPath }));
+    async send({ conversation, payload }) {
+        if (!this.#creds?.botToken) {
+            throw new Error('weixin-ilink bot not authenticated');
         }
-        else if (media?.decryptedVideoPath) {
-            segments.push(segment("video", { file: media.decryptedVideoPath }));
-        }
-        else if (media?.decryptedFilePath) {
-            segments.push(segment("file", {
-                file: media.decryptedFilePath,
-                name: path.basename(media.decryptedFilePath),
-            }));
-        }
-        else if (media?.decryptedVoicePath) {
-            segments.push(segment("record", { file: media.decryptedVoicePath }));
-        }
-        else if (!text && msg.item_list?.some((i) => isMediaItem(i))) {
-            segments.push(segment.text("[媒体消息]"));
-        }
-        return segments.length ? segments : [segment.text("")];
-    }
-    async $sendMessage(options) {
-        if (!this.creds?.botToken) {
-            throw new Error("weixin-ilink bot not authenticated");
-        }
-        const peerId = options.id;
-        const contextToken = getContextToken(this.$id, peerId);
+        // 个人微信仅 private 会话，对端 user_id 即 conversation.id
+        const target = conversation.id;
+        const contextToken = this.client.contextToken(target);
         if (!contextToken) {
-            this.pluginLogger.warn(`missing context_token for peer ${peerId}, refusing send`);
-            throw new Error(`missing context_token for peer ${peerId}`);
+            this.#logger.warn(formatCompact({
+                op: 'send',
+                ok: false,
+                reason: 'missing_context_token',
+                target,
+            }));
+            throw new Error(`missing context_token for peer ${target}`);
         }
-        const apiOpts = {
-            baseUrl: this.apiBaseUrl(),
-            token: this.creds.botToken,
-            contextToken,
-        };
-        const outboundDir = path.join(resolveStateDir(), "media", "outbound");
-        const materialized = await materializeOutboundMedia(options.content, outboundDir);
+        const outboundDir = this.#state.mediaDirectory('outbound');
+        const wire = formatOutboundSegments(payload);
+        const materialized = await materializeOutboundMedia(wire, outboundDir);
         const segments = Array.isArray(materialized) ? materialized : [materialized];
-        let lastId = "";
-        let pendingText = "";
+        let lastId = '';
+        let pendingText = '';
         for (const raw of segments) {
-            if (typeof raw === "string") {
+            if (typeof raw === 'string') {
                 pendingText += raw;
                 continue;
             }
-            if (typeof raw !== "object" || raw === null || !("type" in raw)) {
+            if (typeof raw !== 'object' || raw === null || !('type' in raw))
                 continue;
-            }
             const seg = raw;
-            if (seg.type === "text" || seg.type === "markdown") {
-                const t = seg.data.text ?? "";
-                pendingText += t;
+            if (seg.type === 'text' || seg.type === 'markdown') {
+                pendingText += String(seg.data?.text ?? '');
                 continue;
             }
             const filePath = segmentLocalPath(seg);
             if (filePath && fs.existsSync(filePath)) {
-                // 微信限制：单条消息不能图文混排 → 先单独发文本，再发纯媒体（不带 caption）
+                // 微信限制：单条消息不能图文混排 → 先单独发文本，再发纯媒体
                 if (pendingText.trim()) {
-                    const textResult = await sendMessageWeixin({
-                        to: peerId,
-                        text: pendingText,
-                        opts: apiOpts,
-                    });
-                    pendingText = "";
+                    const textResult = await this.client.sendText(target, pendingText);
+                    pendingText = '';
                     lastId = textResult.messageId;
                 }
-                const result = await sendWeixinMediaFile({
-                    filePath,
-                    to: peerId,
-                    text: "",
-                    opts: apiOpts,
-                    cdnBaseUrl: this.cdnBaseUrl(),
-                });
+                const result = await this.client.sendMedia(target, filePath);
                 lastId = result.messageId;
                 continue;
             }
-            if (seg.type === "image" || seg.type === "video" || seg.type === "file" || seg.type === "record") {
-                this.pluginLogger.warn(`skip outbound ${seg.type}: no local file path`);
+            if (seg.type === 'image' || seg.type === 'video' || seg.type === 'file' || seg.type === 'record') {
+                this.#logger.warn(formatCompact({
+                    op: 'send',
+                    skip: 'no_local_file',
+                    type: seg.type,
+                }));
             }
         }
         if (pendingText.trim()) {
-            const result = await sendMessageWeixin({
-                to: peerId,
-                text: pendingText,
-                opts: apiOpts,
-            });
+            const result = await this.client.sendText(target, pendingText);
             lastId = result.messageId;
         }
         return lastId || `weixin-ilink-${Date.now()}`;
     }
-    async pollLoop(abortSignal) {
-        if (!this.creds?.botToken)
+    /** Test / internal: admit a parsed message when the endpoint is open. */
+    admit(msg) {
+        if (!this.#open)
+            return;
+        const userId = msg.from_user_id ?? '';
+        if (msg.context_token && userId) {
+            this.#contextTokens.set(userId, msg.context_token);
+        }
+        const conversation = weixinIlinkInboundConversation(String(this.#options.id), userId);
+        const replyTo = weixinReplyTo(msg);
+        void this.emit('message.receive', {
+            conversation,
+            message: { conversation, id: inboundMessageId(msg) },
+            content: formatInboundContent(msg),
+            segments: weixinInboundSegments(msg),
+            ...(replyTo ? { replyTo } : {}),
+            sender: { id: userId },
+            endpointId: this.#options.config.id,
+            metadata: Object.freeze({
+                messageType: msg.message_type,
+                createTimeMs: msg.create_time_ms,
+            }),
+        }).catch((err) => {
+            this.#logger.warn(formatCompact({
+                op: 'weixin_ilink_gateway_receive_failed',
+                target: userId,
+                error: err instanceof Error ? err.message : String(err),
+            }));
+        });
+    }
+    async #pollLoop(abortSignal) {
+        if (!this.#creds?.botToken)
             return;
-        let getUpdatesBuf = loadSyncBuf(this.$id);
-        let nextTimeoutMs = this.$config.longPollTimeoutMs ?? DEFAULT_LONG_POLL_TIMEOUT_MS;
+        let getUpdatesBuf = this.#state.loadSyncBuf();
+        let nextTimeoutMs = this.#options.config.longPollTimeoutMs;
         let consecutiveFailures = 0;
         while (!abortSignal.aborted) {
-            if (isSessionPaused(this.$id)) {
-                await sleep(getRemainingPauseMs(this.$id), abortSignal);
+            if (this.#sessionGuard.paused) {
+                await sleep(this.#sessionGuard.remainingMs, abortSignal);
                 continue;
             }
             try {
-                const resp = await getUpdates({
-                    baseUrl: this.apiBaseUrl(),
-                    token: this.creds.botToken,
+                const resp = await this.#getUpdates({
+                    baseUrl: this.client.apiBaseUrl,
+                    metadata: this.#metadata,
+                    token: this.#creds.botToken,
                     get_updates_buf: getUpdatesBuf,
                     timeoutMs: nextTimeoutMs,
                     abortSignal,
@@ -284,19 +265,19 @@ export class WeixinIlinkEndpoint {
                 if (resp.longpolling_timeout_ms != null && resp.longpolling_timeout_ms > 0) {
                     nextTimeoutMs = resp.longpolling_timeout_ms;
                 }
-                const isApiError = (resp.ret !== undefined && resp.ret !== 0) ||
-                    (resp.errcode !== undefined && resp.errcode !== 0);
+                const isApiError = (resp.ret !== undefined && resp.ret !== 0)
+                    || (resp.errcode !== undefined && resp.errcode !== 0);
                 if (isApiError) {
                     const sessionExpired = resp.errcode === SESSION_EXPIRED_ERRCODE || resp.ret === SESSION_EXPIRED_ERRCODE;
                     if (sessionExpired) {
-                        pauseSession(this.$id);
+                        this.#sessionGuard.pause();
                         consecutiveFailures = 0;
-                        await sleep(getRemainingPauseMs(this.$id), abortSignal);
+                        await sleep(this.#sessionGuard.remainingMs, abortSignal);
                         continue;
                     }
                     consecutiveFailures += 1;
+                    // 退避后不清零：对端持续挂时清零会让重试固定打满 RETRY_DELAY_MS。
                     if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
-                        consecutiveFailures = 0;
                         await sleep(BACKOFF_DELAY_MS, abortSignal);
                     }
                     else {
@@ -305,21 +286,26 @@ export class WeixinIlinkEndpoint {
                     continue;
                 }
                 consecutiveFailures = 0;
-                if (resp.get_updates_buf) {
-                    getUpdatesBuf = resp.get_updates_buf;
-                    saveSyncBuf(this.$id, getUpdatesBuf);
-                }
+                // 先分发再推进 buf：分发途中崩溃时 buf 未推进，下一轮重拉不丢消息。
+                const nextBuf = resp.get_updates_buf;
                 for (const inbound of resp.msgs ?? []) {
-                    await this.handleInboundMessage(inbound);
+                    await this.#handleInboundMessage(inbound);
+                }
+                if (nextBuf) {
+                    getUpdatesBuf = nextBuf;
+                    this.#state.saveSyncBuf(getUpdatesBuf);
                 }
             }
             catch (err) {
                 if (abortSignal.aborted)
                     return;
                 consecutiveFailures += 1;
-                this.pluginLogger.error(`weixin-ilink poll error: ${String(err)}`);
+                this.#logger.error(formatCompact({
+                    op: 'poll',
+                    ok: false,
+                    error: err instanceof Error ? err.message : String(err),
+                }));
                 if (consecutiveFailures >= MAX_CONSECUTIVE_FAILURES) {
-                    consecutiveFailures = 0;
                     await sleep(BACKOFF_DELAY_MS, abortSignal);
                 }
                 else {
@@ -328,56 +314,119 @@ export class WeixinIlinkEndpoint {
             }
         }
     }
-    async handleInboundMessage(full) {
-        const fromUserId = full.from_user_id ?? "";
-        if (full.context_token && fromUserId) {
-            setContextToken(this.$id, fromUserId, full.context_token);
-        }
-        const mediaOpts = await this.downloadInboundMedia(full);
-        // 入站保持单条 message.receive（文字+媒体同条），供 AI context / im_transcripts / agent_messages 组装。
-        // 出站才按微信限制拆分图文（见 sendMessage）。
-        const message = this.$formatMessage({ ...full, _media: mediaOpts });
-        this.adapter.emit("message.receive", message);
-        this.pluginLogger.debug(`${this.$id} recv private(${message.$channel.id}): ${segment.raw(message.$content)}`);
+    async #handleInboundMessage(full) {
+        void this.#emitPlatformEvent(`message.${full.message_type ?? 'unknown'}`, full);
+        const fromUserId = full.from_user_id ?? '';
+        const mediaOpts = await this.#downloadInboundMedia(full);
+        this.admit({ ...full, _media: mediaOpts });
+        this.#logger.debug(formatCompact({
+            op: 'recv',
+            endpoint: this.#options.config.id,
+            target: fromUserId,
+            preview: formatInboundContent({ ...full, _media: mediaOpts }).slice(0, 80),
+        }));
     }
-    async downloadInboundMedia(full) {
+    async #emitPlatformEvent(name, event) {
+        await this.emitPlatform(name, event).catch((error) => {
+            this.#logger.warn(formatCompact({
+                op: 'weixin_ilink_platform_event_failed',
+                event: name,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+        });
+    }
+    async #downloadInboundMedia(full) {
         const hasDownloadableMedia = (m) => Boolean(m?.encrypt_query_param || m?.full_url);
-        const mediaItem = full.item_list?.find((i) => i.type === MessageItemType.IMAGE && hasDownloadableMedia(i.image_item?.media)) ??
-            full.item_list?.find((i) => i.type === MessageItemType.VIDEO && hasDownloadableMedia(i.video_item?.media)) ??
-            full.item_list?.find((i) => i.type === MessageItemType.FILE && hasDownloadableMedia(i.file_item?.media)) ??
-            full.item_list?.find((i) => i.type === MessageItemType.VOICE && hasDownloadableMedia(i.voice_item?.media));
+        const mediaItem = full.item_list?.find((i) => i.type === MessageItemType.IMAGE && hasDownloadableMedia(i.image_item?.media))
+            ?? full.item_list?.find((i) => i.type === MessageItemType.VIDEO && hasDownloadableMedia(i.video_item?.media))
+            ?? full.item_list?.find((i) => i.type === MessageItemType.FILE && hasDownloadableMedia(i.file_item?.media))
+            ?? full.item_list?.find((i) => i.type === MessageItemType.VOICE && hasDownloadableMedia(i.voice_item?.media));
         if (!mediaItem)
             return {};
         return downloadMediaFromItem(mediaItem, {
-            cdnBaseUrl: this.cdnBaseUrl(),
-            saveMedia: (buffer, contentType, subdir, maxBytes, originalFilename) => this.saveInboundMedia(buffer, contentType, subdir, maxBytes, originalFilename),
-            log: (msg) => this.pluginLogger.debug(msg),
-            errLog: (msg) => this.pluginLogger.warn(msg),
-            label: `inbound:${fromUserIdLabel(full)}`,
+            cdnBaseUrl: this.client.cdnBaseUrl,
+            saveMedia: (buffer, contentType, subdir, maxBytes, originalFilename) => this.#saveInboundMedia(buffer, contentType, subdir, maxBytes, originalFilename),
+            log: (msg) => this.#logger.debug(msg),
+            errLog: (msg) => this.#logger.warn(msg),
+            label: `inbound:${full.from_user_id ?? 'unknown'}`,
         });
     }
-    async saveInboundMedia(buffer, contentType, subdir = "inbound", maxBytes = WEIXIN_MEDIA_MAX_BYTES, originalFilename) {
+    async #saveInboundMedia(buffer, contentType, subdir = 'inbound', maxBytes = WEIXIN_MEDIA_MAX_BYTES, originalFilename) {
         if (buffer.length > maxBytes) {
             throw new Error(`media exceeds max size ${maxBytes}`);
         }
-        const dir = path.join(resolveStateDir(), "media", subdir);
+        const dir = this.#state.mediaDirectory(subdir);
         fs.mkdirSync(dir, { recursive: true });
         const resolvedMime = contentType ?? sniffMimeFromBuffer(buffer);
         const ext = originalFilename
             ? path.extname(originalFilename)
             : resolvedMime
                 ? getExtensionFromMime(resolvedMime)
-                : ".bin";
+                : '.bin';
         const base = originalFilename
             ? path.basename(originalFilename, ext)
-            : "media";
-        const fileName = `${base}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}${ext}`;
+            : 'media';
+        const fileName = `${base}-${Date.now()}-${crypto.randomBytes(4).toString('hex')}${ext}`;
         const filePath = path.join(dir, fileName);
         fs.writeFileSync(filePath, buffer);
         return { path: filePath };
     }
+    /** 入站媒体 TTL 清扫：start 时立即扫一次，之后每小时扫一次。 */
+    #startMediaSweep() {
+        this.#stopMediaSweep();
+        const sweep = () => this.#sweepInboundMedia();
+        sweep();
+        this.#mediaSweepTimer = setInterval(sweep, MEDIA_SWEEP_INTERVAL_MS);
+        this.#mediaSweepTimer.unref?.();
+    }
+    #stopMediaSweep() {
+        if (this.#mediaSweepTimer) {
+            clearInterval(this.#mediaSweepTimer);
+            this.#mediaSweepTimer = undefined;
+        }
+    }
+    #sweepInboundMedia() {
+        const dir = this.#state.mediaDirectory('inbound');
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        const now = Date.now();
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            const filePath = path.join(dir, entry.name);
+            try {
+                const stat = fs.statSync(filePath);
+                if (now - stat.mtimeMs <= INBOUND_MEDIA_TTL_MS)
+                    continue;
+                fs.unlinkSync(filePath);
+                this.#logger.debug(formatCompact({
+                    op: 'media_sweep',
+                    endpoint: this.#options.config.id,
+                    file: entry.name,
+                }));
+            }
+            catch {
+                /* 单个文件失败不阻塞整体清扫 */
+            }
+        }
+    }
 }
-function fromUserIdLabel(msg) {
-    return msg.from_user_id ?? "unknown";
+function createWeixinIlinkEndpointManagement(requireClient) {
+    return Object.freeze({
+        // 个人微信无群概念（listGroups/listGroupMembers 不接），也没有通讯录/资料接口。
+        // "好友"只能从会话推导：凡持有 context_token 的对端（来过消息，含重启后从磁盘恢复的）
+        // 即为可达私聊对端；昵称不可得，用 user_id 占位并在 remark 注明来源。
+        async listFriends() {
+            return requireClient().reachableUserIds().map((userId) => ({
+                user_id: userId,
+                nickname: userId,
+                remark: 'ilink: 从会话 context_token 推导，非通讯录',
+            }));
+        },
+    });
 }
-//# sourceMappingURL=endpoint.js.map