evolcore 0.0.2 → 0.0.4

package/dist/channels/wecom.js

@@ -1,21 +1,500 @@
 import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import { logger } from '../utils/logger.js';
 import { requireOptional } from '../utils/npm-ops.js';
 import { middleOutputModePolicy, resolveShowActivities, showActivitiesPolicy } from '../core/channel-loader.js';
 import { formatItemsAsText } from '../core/message/items-formatter.js';
+import { createSendFileMarkerPattern } from '../core/message/file-markers.js';
 import { initWelcomeManager, sendWelcomeIfNeeded } from '../utils/welcome.js';
+import { bufferToInboundImage, sanitizeFileName, saveToUploads, validateUrl } from '../utils/media-cache.js';
+import { agentDataDir } from '../paths.js';
+import { atomicReadJson, atomicWriteJson } from '../utils/atomic-write.js';
+import { ContactBindCodeRegistry, handleExplicitContactBindCommand, } from '../config/contact-bind-code.js';
+function wecomErrorCode(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const direct = error.errcode;
+    if (typeof direct === 'number')
+        return direct;
+    const responseCode = error.response?.data?.errcode;
+    return typeof responseCode === 'number' ? responseCode : undefined;
+}
+function isWecomAuthError(error) {
+    return error.code === 'WS_AUTH_FAILURE_EXHAUSTED'
+        || /^Authentication failed:/i.test(error.message);
+}
+function sanitizeWecomSdkLog(message) {
+    return message
+        .replace(/("(?:aeskey|secret)"\s*:\s*")[^"]*(")/gi, '$1<redacted>$2')
+        .replace(/("url"\s*:\s*")[^"]*(")/gi, '$1<redacted>$2')
+        .replace(/(url=)https?:\/\/\S+/gi, '$1<redacted>');
+}
+function validateWecomMediaUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error('WeCom media URL is invalid');
+    }
+    if (parsed.protocol !== 'https:')
+        throw new Error(`WeCom media URL must use HTTPS: ${parsed.protocol}`);
+    if (parsed.username || parsed.password)
+        throw new Error('WeCom media URL must not contain credentials');
+    const host = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (host === 'localhost'
+        || host.endsWith('.localhost')
+        || host.endsWith('.local')
+        || host === '::1'
+        || /^(?:fc|fd|fe8|fe9|fea|feb)/i.test(host)) {
+        throw new Error(`WeCom media URL rejected: local host ${host}`);
+    }
+    const validation = validateUrl(url, { allowedHosts: new Set() });
+    if (!validation.ok)
+        throw new Error(`WeCom media URL rejected: ${validation.reason}`);
+}
+function truncateUtf8Bytes(value, maxBytes) {
+    const input = Buffer.from(value, 'utf8');
+    if (input.length <= maxBytes)
+        return value;
+    let end = maxBytes;
+    while (end > 0 && (input[end] & 0xc0) === 0x80)
+        end--;
+    return input.subarray(0, end).toString('utf8');
+}
+function splitUtf8Bytes(value, maxBytes) {
+    if (!value)
+        return [];
+    const chunks = [];
+    let remaining = value;
+    while (Buffer.byteLength(remaining, 'utf8') > maxBytes) {
+        let chunk = truncateUtf8Bytes(remaining, maxBytes);
+        const paragraphBreak = chunk.lastIndexOf('\n\n');
+        const lineBreak = chunk.lastIndexOf('\n');
+        const splitAt = paragraphBreak > Math.floor(chunk.length / 2)
+            ? paragraphBreak
+            : lineBreak > Math.floor(chunk.length / 2)
+                ? lineBreak
+                : chunk.length;
+        chunk = chunk.slice(0, splitAt);
+        if (!chunk)
+            chunk = truncateUtf8Bytes(remaining, maxBytes);
+        chunks.push(chunk);
+        remaining = remaining.slice(chunk.length);
+    }
+    if (remaining)
+        chunks.push(remaining);
+    return chunks;
+}
+const wecomContactBinds = new ContactBindCodeRegistry({
+    channelType: 'wecom',
+    displayName: '企微',
+    initCommand: 'ec init wecom',
+});
+export function registerPendingWecomContactBind(req) {
+    return wecomContactBinds.register(req);
+}
+export function handlePendingWecomContactBindMessage(ctx) {
+    return handleExplicitContactBindCommand(wecomContactBinds, ctx);
+}
+export function getPendingWecomContactBind(selfAid, channelName, primaryId) {
+    return wecomContactBinds.get(selfAid, channelName, primaryId);
+}
+export function clearPendingWecomContactBinds() {
+    wecomContactBinds.clear();
+}
+// ── Persistent channel state ──────────────────────────────────────────────────
+const STORE_VERSION = 1;
+const DEFAULT_DEDUP_TTL_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_CARD_RETENTION_MS = 24 * 60 * 60 * 1000;
+function writePrivateJson(filePath, value) {
+    atomicWriteJson(filePath, value);
+    try {
+        fs.chmodSync(filePath, 0o600);
+    }
+    catch { /* best effort on non-POSIX filesystems */ }
+}
+export class PersistentWecomDeduper {
+    filePath;
+    channelKey;
+    entries = new Map();
+    ttlMs;
+    maxEntries;
+    constructor(filePath, channelKey, opts) {
+        this.filePath = filePath;
+        this.channelKey = channelKey;
+        this.ttlMs = opts?.ttlMs ?? DEFAULT_DEDUP_TTL_MS;
+        this.maxEntries = opts?.maxEntries ?? 20_000;
+        this.load();
+    }
+    checkAndMark(messageId, now = Date.now()) {
+        this.evict(now);
+        const seenAt = this.entries.get(messageId);
+        if (seenAt !== undefined && now - seenAt <= this.ttlMs)
+            return true;
+        this.entries.set(messageId, now);
+        this.trimToLimit();
+        this.flush();
+        return false;
+    }
+    get size() {
+        return this.entries.size;
+    }
+    load() {
+        if (!this.filePath)
+            return;
+        try {
+            const stored = atomicReadJson(this.filePath);
+            if (!stored || stored.version !== STORE_VERSION || stored.channelKey !== this.channelKey)
+                return;
+            for (const [id, timestamp] of Object.entries(stored.entries ?? {})) {
+                if (id && Number.isFinite(timestamp))
+                    this.entries.set(id, timestamp);
+            }
+            const before = this.entries.size;
+            this.evict(Date.now());
+            this.trimToLimit();
+            if (this.entries.size !== before)
+                this.flush();
+        }
+        catch (error) {
+            logger.warn(`[WeCom] Ignoring unreadable dedup store for ${this.channelKey}: ${String(error)}`);
+            this.entries.clear();
+        }
+    }
+    evict(now) {
+        for (const [id, timestamp] of this.entries) {
+            if (now - timestamp > this.ttlMs)
+                this.entries.delete(id);
+        }
+    }
+    trimToLimit() {
+        if (this.entries.size <= this.maxEntries)
+            return;
+        const oldest = [...this.entries.entries()].sort((a, b) => a[1] - b[1]);
+        for (let i = 0; i < oldest.length - this.maxEntries; i++) {
+            this.entries.delete(oldest[i][0]);
+        }
+    }
+    flush() {
+        writePrivateJson(this.filePath, {
+            version: STORE_VERSION,
+            channelKey: this.channelKey,
+            entries: Object.fromEntries(this.entries),
+        });
+    }
+}
+export class PersistentWecomCardStore {
+    filePath;
+    channelKey;
+    records = new Map();
+    constructor(filePath, channelKey) {
+        this.filePath = filePath;
+        this.channelKey = channelKey;
+        if (filePath)
+            this.load();
+    }
+    set(record) {
+        this.records.set(record.taskId, record);
+        this.cleanup();
+        this.flush();
+    }
+    get(taskId) {
+        this.cleanup();
+        return this.records.get(taskId);
+    }
+    findByInteractionId(interactionId) {
+        this.cleanup();
+        return [...this.records.values()].find(record => record.interaction.id === interactionId);
+    }
+    listPendingByChat(chatId) {
+        this.cleanup();
+        return [...this.records.values()].filter(record => (record.chatId === chatId
+            && record.status === 'pending'
+            && (!record.expiresAt || record.expiresAt >= Date.now())));
+    }
+    resolve(taskId, action) {
+        const record = this.records.get(taskId);
+        if (!record)
+            return undefined;
+        record.status = 'resolved';
+        record.resolution = action;
+        record.updatedAt = Date.now();
+        this.flush();
+        return record;
+    }
+    invalidateByInteractionId(interactionId, reason) {
+        const record = this.findByInteractionId(interactionId);
+        if (!record || record.status === 'resolved')
+            return record;
+        record.status = 'invalidated';
+        record.invalidationReason = reason;
+        record.updatedAt = Date.now();
+        this.flush();
+        return record;
+    }
+    load() {
+        if (!this.filePath)
+            return;
+        try {
+            const stored = atomicReadJson(this.filePath);
+            if (!stored || stored.version !== STORE_VERSION || stored.channelKey !== this.channelKey)
+                return;
+            for (const record of stored.records ?? []) {
+                if (record?.taskId && record?.interaction?.id)
+                    this.records.set(record.taskId, record);
+            }
+            this.cleanup(true);
+        }
+        catch (error) {
+            logger.warn(`[WeCom] Ignoring unreadable card store for ${this.channelKey}: ${String(error)}`);
+            this.records.clear();
+        }
+    }
+    cleanup(flushWhenChanged = false) {
+        const now = Date.now();
+        let changed = false;
+        for (const [taskId, record] of this.records) {
+            const terminalExpiry = record.updatedAt + DEFAULT_CARD_RETENTION_MS;
+            const pendingExpiry = (record.expiresAt ?? record.createdAt + 7 * DEFAULT_CARD_RETENTION_MS)
+                + DEFAULT_CARD_RETENTION_MS;
+            const expiresAt = record.status === 'pending' ? pendingExpiry : terminalExpiry;
+            if (now > expiresAt) {
+                this.records.delete(taskId);
+                changed = true;
+            }
+        }
+        if (changed && flushWhenChanged)
+            this.flush();
+    }
+    flush() {
+        if (!this.filePath)
+            return;
+        writePrivateJson(this.filePath, {
+            version: STORE_VERSION,
+            channelKey: this.channelKey,
+            records: [...this.records.values()],
+        });
+    }
+}
+export function wecomChannelDataPaths(agentAid, channelKey) {
+    const safeKey = encodeURIComponent(channelKey);
+    const dir = path.join(agentDataDir(agentAid), 'channels', safeKey);
+    return {
+        dedupFile: path.join(dir, 'wecom-message-dedup.json'),
+        cardFile: path.join(dir, 'wecom-cards.json'),
+    };
+}
+export function createWecomCardTaskId(channelKey, interactionId) {
+    const hash = crypto.createHash('sha256').update(`${channelKey}\0${interactionId}`).digest('hex').slice(0, 32);
+    return `ec_${hash}`;
+}
+// ── Template cards ────────────────────────────────────────────────────────────
+function truncate(value, max) {
+    if (!value)
+        return undefined;
+    const chars = [...value.trim()];
+    return chars.length <= max ? value.trim() : `${chars.slice(0, Math.max(1, max - 1)).join('')}...`;
+}
+function buttonStyle(style) {
+    if (style === 'primary')
+        return 2;
+    if (style === 'danger')
+        return 3;
+    return 1;
+}
+export function buildWecomInteractionCard(interaction, taskId) {
+    const bodyParts = [];
+    if (interaction.kind.body)
+        bodyParts.push(interaction.kind.body);
+    if (interaction.kind.kind === 'action' && interaction.kind.checkers?.length) {
+        bodyParts.push(interaction.kind.checkers.map((item, index) => `${index + 1}. ${item.label}`).join('\n'));
+    }
+    return {
+        card_type: 'button_interaction',
+        task_id: taskId,
+        main_title: {
+            title: truncate(interaction.kind.title, 26),
+            desc: truncate(bodyParts.join('\n\n'), 120),
+        },
+        button_list: interaction.kind.buttons
+            .map((button, index) => ({ button, index }))
+            .filter(({ button }) => !('disabled' in button) || !button.disabled)
+            .slice(0, 6)
+            .map(({ button, index }) => ({
+            text: truncate(button.label, 10) || `选项 ${index + 1}`,
+            style: buttonStyle(button.style),
+            key: interaction.kind.kind === 'command-card' ? `cmd_${index}` : `act_${index}`,
+        })),
+    };
+}
+export function parseWecomCardResponse(record, event, operatorId) {
+    const eventKey = String(event.event_key ?? '').trim();
+    const match = /^(cmd|act)_(\d+)$/.exec(eventKey);
+    if (!match)
+        return null;
+    const index = Number(match[2]);
+    if (record.interaction.kind.kind === 'command-card') {
+        const button = record.interaction.kind.buttons[index];
+        if (!button || button.disabled)
+            return null;
+        return { command: button.command };
+    }
+    const button = record.interaction.kind.buttons[index];
+    if (!button)
+        return null;
+    const values = {};
+    const selectedItems = event.selected_items?.selected_item;
+    if (Array.isArray(selectedItems)) {
+        for (const selected of selectedItems) {
+            const questionKey = String(selected?.question_key ?? '').trim();
+            const optionIds = selected?.option_ids?.option_id;
+            if (questionKey && Array.isArray(optionIds))
+                values[questionKey] = optionIds.filter(Boolean);
+        }
+    }
+    return {
+        response: {
+            type: 'interaction.response',
+            id: record.interaction.id,
+            action: button.key,
+            values: Object.keys(values).length > 0 ? values : undefined,
+            operatorId,
+        },
+    };
+}
+export function buildWecomTerminalCard(record, status, detail) {
+    const statusText = status === 'resolved'
+        ? `已处理${detail ? `：${detail}` : ''}`
+        : status === 'rejected'
+            ? '仅卡片发起者可操作'
+            : status === 'unavailable'
+                ? '处理服务暂不可用，请重新发起'
+                : `卡片已失效${detail ? `：${detail}` : ''}`;
+    return {
+        card_type: 'text_notice',
+        task_id: record.taskId,
+        main_title: {
+            title: truncate(record.interaction.kind.title, 26),
+            desc: truncate(statusText, 120),
+        },
+        sub_title_text: truncate(record.interaction.kind.body, 120),
+    };
+}
+export function buildWecomUnknownCard(taskId) {
+    return {
+        card_type: 'text_notice',
+        task_id: taskId,
+        main_title: {
+            title: '卡片已失效',
+            desc: '本地状态不存在，请重新发起操作',
+        },
+    };
+}
+// ── QR onboarding ─────────────────────────────────────────────────────────────
+const WECOM_QR_GENERATE_URL = 'https://work.weixin.qq.com/ai/qc/generate';
+const WECOM_QR_QUERY_URL = 'https://work.weixin.qq.com/ai/qc/query_result';
+const WECOM_QR_PAGE_URL = 'https://work.weixin.qq.com/ai/qc/gen';
+function platformCode() {
+    if (os.platform() === 'darwin')
+        return 1;
+    if (os.platform() === 'win32')
+        return 2;
+    if (os.platform() === 'linux')
+        return 3;
+    return 0;
+}
+async function fetchJson(url, fetchImpl, signal) {
+    const timeoutSignal = AbortSignal.timeout(15_000);
+    const response = await fetchImpl(url, {
+        headers: { Accept: 'application/json' },
+        signal: signal ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal,
+    });
+    if (!response.ok)
+        throw new Error(`企微扫码服务请求失败: HTTP ${response.status}`);
+    return response.json();
+}
+export async function createWecomQrSession(fetchImpl = fetch) {
+    const url = new URL(WECOM_QR_GENERATE_URL);
+    url.searchParams.set('source', 'wecom-cli');
+    url.searchParams.set('plat', String(platformCode()));
+    const payload = await fetchJson(url, fetchImpl);
+    const scode = String(payload?.data?.scode ?? '').trim();
+    const authUrl = String(payload?.data?.auth_url ?? '').trim();
+    if (!scode || !authUrl)
+        throw new Error('企微扫码服务未返回 scode 或授权地址');
+    const browserUrl = new URL(WECOM_QR_PAGE_URL);
+    browserUrl.searchParams.set('source', 'wecom-cli');
+    browserUrl.searchParams.set('scode', scode);
+    return { scode, authUrl, browserUrl: browserUrl.toString() };
+}
+export async function pollWecomQrCredentials(scode, opts) {
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const timeoutMs = opts?.timeoutMs ?? 5 * 60 * 1000;
+    const intervalMs = opts?.intervalMs ?? 3_000;
+    const deadline = Date.now() + timeoutMs;
+    const url = new URL(WECOM_QR_QUERY_URL);
+    url.searchParams.set('scode', scode);
+    let previousStatus = '';
+    while (Date.now() < deadline) {
+        if (opts?.signal?.aborted)
+            throw new Error('企微扫码已取消');
+        const payload = await fetchJson(url, fetchImpl, opts?.signal);
+        const status = String(payload?.data?.status ?? 'waiting');
+        if (status !== previousStatus) {
+            opts?.onStatus?.(status);
+            previousStatus = status;
+        }
+        if (status === 'success') {
+            const botId = String(payload?.data?.bot_info?.botid ?? '').trim();
+            const secret = String(payload?.data?.bot_info?.secret ?? '').trim();
+            if (!botId || !secret)
+                throw new Error('扫码成功，但企微未返回 Bot ID 或 Secret');
+            return { botId, secret };
+        }
+        if (status === 'expired' || status === 'cancelled' || status === 'rejected') {
+            throw new Error(`企微扫码未完成: ${status}`);
+        }
+        await new Promise((resolve, reject) => {
+            const finish = () => {
+                opts?.signal?.removeEventListener('abort', onAbort);
+                resolve();
+            };
+            const timer = setTimeout(finish, intervalMs);
+            const onAbort = () => {
+                clearTimeout(timer);
+                opts?.signal?.removeEventListener('abort', onAbort);
+                reject(new Error('企微扫码已取消'));
+            };
+            opts?.signal?.addEventListener('abort', onAbort, { once: true });
+            if (opts?.signal?.aborted)
+                onAbort();
+        });
+    }
+    throw new Error('企微扫码超时，请重新生成二维码');
+}
 // ── WecomChannel ───────────────────────────────────────────────────────────────
 export class WecomChannel {
     agentAid;
     channelName;
     config;
     client = null;
-    connected = false;
+    connectionState = 'idle';
+    lastConnectionError;
     messageHandler = null;
     seenMessages = new Map();
+    persistentDeduper;
+    cardStore;
     cleanupInterval = null;
     projectPathProvider = null;
-    // Stream reply state: reqId → { streamId, frame }
+    interactionCallback;
+    interactionInvalidationCallback;
+    channelKey;
+    cardCallbacksInFlight = new Set();
+    interactionSendTails = new Map();
+    connectPromise;
     activeStreams = new Map();
     // Welcome message manager
     welcomeManager;
@@ -23,6 +502,13 @@ export class WecomChannel {
         this.agentAid = agentAid;
         this.channelName = channelName;
         this.config = config;
+        this.channelKey = channelName || `wecom#${agentAid || 'standalone'}#main`;
+        this.cardStore = new PersistentWecomCardStore(undefined, this.channelKey);
+        if (agentAid && channelName) {
+            const paths = wecomChannelDataPaths(agentAid, channelName);
+            this.persistentDeduper = new PersistentWecomDeduper(paths.dedupFile, channelName);
+            this.cardStore = new PersistentWecomCardStore(paths.cardFile, channelName);
+        }
         // 初始化 welcomeManager（使用共享帮助函数）
         if (agentAid && channelName) {
             this.welcomeManager = initWelcomeManager('wecom', agentAid, channelName);
@@ -30,51 +516,143 @@ export class WecomChannel {
     }
     // ── Public helpers (testable) ─────────────────────────────────────────────
     isDuplicate(msgId) {
+        if (this.persistentDeduper)
+            return this.persistentDeduper.checkAndMark(msgId);
         if (this.seenMessages.has(msgId))
             return true;
         this.seenMessages.set(msgId, Date.now());
         return false;
     }
     resolveChatId(chattype, chatid, userid) {
-        return chattype === 'group' && chatid ? chatid : userid;
+        return chattype === 'group' ? (chatid || '') : userid;
     }
     // ── Lifecycle ─────────────────────────────────────────────────────────────
     async connect() {
+        if (this.connectionState === 'authenticated' && this.client)
+            return;
+        if (this.connectPromise)
+            return this.connectPromise;
+        if (this.client)
+            return this.waitForAuthentication(this.client, 20_000);
+        const pending = this.connectOnce();
+        this.connectPromise = pending;
+        try {
+            await pending;
+        }
+        finally {
+            if (this.connectPromise === pending)
+                this.connectPromise = undefined;
+        }
+    }
+    async connectOnce() {
         const { botId, secret } = this.config;
         if (!botId || !secret) {
             throw new Error('WeCom botId/secret not configured');
         }
-        const { WSClient } = await requireOptional('@wecom/aibot-node-sdk');
-        this.client = new WSClient({ botId, secret });
+        const sdk = await requireOptional('@wecom/aibot-node-sdk');
+        this.connectionState = 'connecting';
+        this.lastConnectionError = undefined;
+        const client = new sdk.WSClient({
+            botId,
+            secret,
+            heartbeatInterval: 30_000,
+            maxReconnectAttempts: 10,
+            maxAuthFailureAttempts: 5,
+            requestTimeout: 15_000,
+            logger: {
+                debug: (message) => logger.debug(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`),
+                info: (message, ...args) => logger.info(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`, ...args),
+                warn: (message, ...args) => logger.warn(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`, ...args),
+                error: (message, ...args) => logger.error(`[WeCom SDK] ${sanitizeWecomSdkLog(message)}`, ...args),
+            },
+        });
+        this.client = client;
         // Message events
-        this.client.on('message', (frame) => {
+        client.on('message', (frame) => {
+            if (this.client !== client)
+                return;
             this.handleIncoming(frame).catch((err) => {
                 logger.error('[WeCom] Failed to process incoming message:', err);
             });
         });
         // Event callbacks (enter_chat, etc.)
-        this.client.on('event.enter_chat', (frame) => {
+        client.on('event.enter_chat', (frame) => {
+            if (this.client !== client)
+                return;
             const body = frame?.body;
             if (body) {
                 logger.debug(`[WeCom] User entered chat: userid=${body.from?.userid} chattype=${body.chattype}`);
             }
         });
         // Lifecycle events
-        this.client.on('authenticated', () => {
+        client.on('authenticated', () => {
+            if (this.client !== client)
+                return;
+            this.connectionState = 'authenticated';
+            this.lastConnectionError = undefined;
             logger.info('[WeCom] WebSocket authenticated');
         });
-        this.client.on('disconnected', (reason) => {
+        client.on('disconnected', (reason) => {
+            if (this.client !== client)
+                return;
             logger.warn(`[WeCom] WebSocket disconnected: ${reason}`);
-            this.connected = false;
+            if (this.connectionState !== 'kicked')
+                this.connectionState = 'disconnected';
+            this.lastConnectionError = reason;
+            this.expireActiveStreams();
         });
-        this.client.on('reconnecting', (attempt) => {
+        client.on('reconnecting', (attempt) => {
+            if (this.client !== client)
+                return;
+            this.connectionState = 'reconnecting';
+            this.expireActiveStreams();
             logger.info(`[WeCom] Reconnecting (attempt ${attempt})...`);
         });
-        this.client.on('error', (error) => {
+        client.on('error', (error) => {
+            if (this.client !== client)
+                return;
+            this.lastConnectionError = error.message;
+            if (isWecomAuthError(error))
+                this.connectionState = 'auth_failed';
+            else if (error.code === 'WS_RECONNECT_EXHAUSTED')
+                this.connectionState = 'disconnected';
             logger.error('[WeCom] WebSocket error:', error);
         });
-        this.client.connect();
-        this.connected = true;
+        client.on('event.template_card_event', (frame) => {
+            if (this.client !== client)
+                return;
+            this.handleTemplateCardEvent(frame).catch(error => {
+                logger.error('[WeCom] Failed to process template card event:', error);
+            });
+        });
+        client.on('event.disconnected_event', () => {
+            if (this.client !== client)
+                return;
+            this.connectionState = 'kicked';
+            this.lastConnectionError = 'A newer connection subscribed with the same Bot ID';
+            this.expireActiveStreams();
+            logger.error(`[WeCom] Connection kicked for channel ${this.channelKey}; another client is using this Bot ID`);
+        });
+        client.connect();
+        try {
+            await this.waitForAuthentication(client, 20_000);
+        }
+        catch (error) {
+            const wasCurrentClient = this.client === client;
+            if (wasCurrentClient)
+                this.client = null;
+            try {
+                client.disconnect();
+            }
+            catch { /* ignore */ }
+            if (wasCurrentClient) {
+                const failedState = this.connectionState;
+                if (failedState !== 'auth_failed')
+                    this.connectionState = 'disconnected';
+                this.lastConnectionError = error instanceof Error ? error.message : String(error);
+            }
+            throw error;
+        }
         // Hourly cleanup of old dedup entries
         this.cleanupInterval = setInterval(() => {
             const cutoff = Date.now() - 24 * 60 * 60 * 1000;
@@ -82,29 +660,39 @@ export class WecomChannel {
                 if (ts < cutoff)
                     this.seenMessages.delete(id);
             }
+            this.cleanupStreams();
         }, 60 * 60 * 1000);
         logger.info('[WeCom] Channel connected');
     }
     async disconnect() {
-        this.connected = false;
+        this.connectionState = 'idle';
         if (this.cleanupInterval) {
             clearInterval(this.cleanupInterval);
             this.cleanupInterval = null;
         }
-        if (this.client) {
+        const client = this.client;
+        this.client = null;
+        if (client) {
             try {
-                this.client.disconnect();
+                client.disconnect();
             }
             catch { /* ignore */ }
-            this.client = null;
         }
+        this.activeStreams.clear();
         logger.info('[WeCom] Channel disconnected');
     }
     onMessage(handler) {
         this.messageHandler = handler;
     }
+    onProjectPathRequest(provider) {
+        this.projectPathProvider = provider;
+    }
     getStatus() {
-        return { connected: this.connected };
+        return {
+            connected: this.connectionState === 'authenticated',
+            state: this.connectionState,
+            error: this.lastConnectionError,
+        };
     }
     async reconnect() {
         await this.disconnect();
@@ -116,11 +704,144 @@ export class WecomChannel {
             return `重连失败: ${err instanceof Error ? err.message : String(err)}`;
         }
     }
+    onInteraction(callback) {
+        this.interactionCallback = callback;
+    }
+    onInteractionInvalidated(callback) {
+        this.interactionInvalidationCallback = callback;
+    }
+    invalidateInteraction(interactionId, reason = 'cancelled') {
+        this.cardStore?.invalidateByInteractionId(interactionId, reason);
+    }
+    async withInteractionSendLock(chatId, run) {
+        const previous = this.interactionSendTails.get(chatId) ?? Promise.resolve();
+        let release;
+        const current = new Promise(resolve => { release = resolve; });
+        this.interactionSendTails.set(chatId, current);
+        await previous.catch(() => undefined);
+        try {
+            return await run();
+        }
+        finally {
+            release();
+            if (this.interactionSendTails.get(chatId) === current)
+                this.interactionSendTails.delete(chatId);
+        }
+    }
+    async invalidateSupersededCards(records) {
+        for (const record of records) {
+            if (this.interactionInvalidationCallback) {
+                try {
+                    await this.interactionInvalidationCallback(record.interaction.id, 'superseded');
+                }
+                catch (error) {
+                    logger.warn(`[WeCom] Failed to cancel superseded interaction ${record.interaction.id}: ${String(error)}`);
+                }
+            }
+            this.cardStore?.invalidateByInteractionId(record.interaction.id, 'superseded');
+        }
+    }
+    async waitForAuthentication(client, timeoutMs) {
+        if (this.connectionState === 'authenticated')
+            return;
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const finish = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                client.off('authenticated', onAuthenticated);
+                client.off('error', onError);
+                client.off('disconnected', onDisconnected);
+                if (error)
+                    reject(error);
+                else
+                    resolve();
+            };
+            const onAuthenticated = () => finish();
+            const onError = (error) => {
+                if (isWecomAuthError(error))
+                    finish(error);
+            };
+            const onDisconnected = (reason) => finish(new Error(`WeCom disconnected before authentication: ${reason}`));
+            const timer = setTimeout(() => {
+                finish(new Error(`WeCom authentication timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            client.on('authenticated', onAuthenticated);
+            client.on('error', onError);
+            client.on('disconnected', onDisconnected);
+            if (this.connectionState === 'authenticated')
+                finish();
+        });
+    }
+    cleanupStreams(now = Date.now()) {
+        const cutoff = now - 30 * 60 * 1000;
+        for (const [reqId, stream] of this.activeStreams) {
+            if (stream.finished || stream.lastUpdatedAt < cutoff)
+                this.activeStreams.delete(reqId);
+        }
+    }
+    expireActiveStreams() {
+        for (const stream of this.activeStreams.values())
+            stream.expired = true;
+    }
+    createReplyContext(frame, chatId, messageId) {
+        const reqId = String(frame.headers?.req_id ?? '').trim();
+        const streamId = crypto.randomUUID();
+        if (reqId) {
+            this.activeStreams.set(reqId, {
+                reqId,
+                streamId,
+                frame: { headers: { ...frame.headers, req_id: reqId } },
+                chatId,
+                messageId,
+                accumulatedText: '',
+                createdAt: Date.now(),
+                lastUpdatedAt: Date.now(),
+                started: false,
+                finished: false,
+                expired: false,
+            });
+        }
+        return {
+            replyToMessageId: messageId,
+            metadata: {
+                wecomReqId: reqId,
+                wecomStreamId: streamId,
+                wecomMessageId: messageId,
+            },
+        };
+    }
+    streamFromReplyContext(replyContext) {
+        const reqId = replyContext?.metadata?.wecomReqId;
+        if (typeof reqId !== 'string' || !reqId)
+            return undefined;
+        return this.activeStreams.get(reqId);
+    }
+    requireClient() {
+        if (!this.client)
+            throw new Error('WeCom client is not connected');
+        return this.client;
+    }
+    async sendProactiveMarkdown(chatId, content) {
+        const client = this.requireClient();
+        for (const chunk of splitUtf8Bytes(content, 20_480)) {
+            await client.sendMessage(chatId, {
+                msgtype: 'markdown',
+                markdown: { content: chunk },
+            });
+        }
+    }
     // ── Inbound message handling ──────────────────────────────────────────────
     async handleIncoming(frame) {
         const body = frame?.body;
         if (!body)
             return;
+        if (body.aibotid && body.aibotid !== this.config.botId) {
+            logger.warn(`[WeCom] Ignoring callback for unexpected Bot ID: ${body.aibotid}`);
+            return;
+        }
         const msgId = body.msgid;
         const chattype = body.chattype || 'single';
         const chatid = body.chatid;
@@ -132,12 +853,12 @@ export class WecomChannel {
             return;
         }
         const channelId = this.resolveChatId(chattype, chatid, userid);
+        if (!channelId) {
+            logger.warn(`[WeCom] Ignoring ${chattype} message without a routable ${chattype === 'group' ? 'chatid' : 'userid'}`);
+            return;
+        }
         const chatTypeNorm = chattype === 'group' ? 'group' : 'private';
-        // Store frame for stream replies
-        this.activeStreams.set(channelId, {
-            streamId: crypto.randomUUID(),
-            frame: { headers: frame.headers },
-        });
+        const replyContext = this.createReplyContext(frame, channelId, msgId);
         if (!this.messageHandler)
             return;
         // 首次交互欢迎消息（使用共享帮助函数）
@@ -146,85 +867,143 @@ export class WecomChannel {
             const text = body.text?.content?.trim();
             if (!text)
                 return;
-            // Handle quote/reference
-            let content = text;
-            if (body.quote) {
-                const quoteText = body.quote.text?.content || '';
-                if (quoteText) {
-                    content = `[引用: ${quoteText}]\n${text}`;
-                }
-            }
+            const quote = await this.processQuote(body.quote, channelId);
+            const content = quote.prefix ? `${quote.prefix}\n${text}` : text;
             await this.messageHandler({
                 channelId, content, chatType: chatTypeNorm,
                 peerId: userid, messageId: msgId,
+                images: quote.images.length > 0 ? quote.images : undefined,
+                replyContext,
             });
         }
         else if (msgtype === 'image') {
-            await this.handleImageMessage(body, channelId, chatTypeNorm, userid, msgId, frame);
+            await this.handleImageMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
         }
         else if (msgtype === 'voice') {
             const voiceText = body.voice?.content?.trim();
             if (voiceText) {
                 await this.messageHandler({
                     channelId, content: voiceText, chatType: chatTypeNorm,
-                    peerId: userid, messageId: msgId,
+                    peerId: userid, messageId: msgId, replyContext,
                 });
             }
         }
         else if (msgtype === 'file') {
-            await this.handleFileMessage(body, channelId, chatTypeNorm, userid, msgId, frame);
+            await this.handleFileMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
         }
         else if (msgtype === 'video') {
-            await this.handleVideoMessage(body, channelId, chatTypeNorm, userid, msgId, frame);
+            await this.handleVideoMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
         }
         else if (msgtype === 'mixed') {
-            await this.handleMixedMessage(body, channelId, chatTypeNorm, userid, msgId, frame);
+            await this.handleMixedMessage(body, channelId, chatTypeNorm, userid, msgId, replyContext);
         }
         else {
             await this.messageHandler({
                 channelId,
                 content: `[不支持的消息类型: ${msgtype}]`,
-                chatType: chatTypeNorm, peerId: userid, messageId: msgId,
+                chatType: chatTypeNorm, peerId: userid, messageId: msgId, replyContext,
             });
         }
     }
     // ── Inbound media handling ────────────────────────────────────────────────
-    async handleImageMessage(body, channelId, chatType, peerId, msgId, frame) {
+    async downloadInboundMedia(url, aesKey) {
+        if (!this.client)
+            throw new Error('WeCom client is unavailable');
+        validateWecomMediaUrl(url);
+        const result = await this.client.downloadFile(url, aesKey);
+        const maxBytes = 20 * 1024 * 1024;
+        if (result.buffer.length > maxBytes) {
+            throw new Error(`WeCom media exceeds ${maxBytes} bytes`);
+        }
+        return result;
+    }
+    async processQuote(quote, channelId) {
+        const result = { prefix: '', images: [] };
+        if (!quote?.msgtype)
+            return result;
+        try {
+            if (quote.msgtype === 'text') {
+                const text = String(quote.text?.content ?? '').trim();
+                if (text)
+                    result.prefix = `[引用文本]\n${text}`;
+                return result;
+            }
+            if (quote.msgtype === 'voice') {
+                const text = String(quote.voice?.content ?? '').trim();
+                if (text)
+                    result.prefix = `[引用语音转写]\n${text}`;
+                return result;
+            }
+            if (quote.msgtype === 'image' && quote.image?.url) {
+                const media = await this.downloadInboundMedia(quote.image.url, quote.image.aeskey);
+                const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+                if (!image)
+                    throw new Error('引用图片格式不受支持');
+                result.images.push(image);
+                result.prefix = '[引用图片]';
+                return result;
+            }
+            if (quote.msgtype === 'file' && quote.file?.url) {
+                const media = await this.downloadInboundMedia(quote.file.url, quote.file.aeskey);
+                const fileName = sanitizeFileName(quote.file.filename || media.filename || 'quoted-file');
+                const projectPath = this.projectPathProvider
+                    ? await this.projectPathProvider(channelId)
+                    : process.cwd();
+                const saved = saveToUploads(media.buffer, fileName, projectPath);
+                result.prefix = `[引用文件: ${saved.fileName}]\n文件已保存到：${saved.filePath}\n请使用 Read 工具读取并分析文件内容。`;
+                return result;
+            }
+            if (quote.msgtype === 'mixed' && Array.isArray(quote.mixed?.msg_item)) {
+                const textParts = [];
+                for (const item of quote.mixed.msg_item) {
+                    if (item.msgtype === 'text' && item.text?.content) {
+                        textParts.push(String(item.text.content));
+                    }
+                    else if (item.msgtype === 'image' && item.image?.url) {
+                        const media = await this.downloadInboundMedia(item.image.url, item.image.aeskey);
+                        const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+                        if (image)
+                            result.images.push(image);
+                    }
+                }
+                result.prefix = `[引用图文]\n${textParts.join('')}`.trim();
+                return result;
+            }
+            result.prefix = `[引用了暂不支持的消息类型: ${quote.msgtype}]`;
+        }
+        catch (error) {
+            logger.warn(`[WeCom] Failed to process quote (${quote.msgtype}): ${String(error)}`);
+            result.prefix = `[引用内容读取失败: ${quote.msgtype}]`;
+        }
+        return result;
+    }
+    async handleImageMessage(body, channelId, chatType, peerId, msgId, replyContext) {
         const imageUrl = body.image?.url;
         const aeskey = body.image?.aeskey;
         if (!imageUrl) {
             logger.warn('[WeCom] Image message without url');
             await this.messageHandler({
                 channelId, content: '[图片下载失败：缺少下载链接]',
-                chatType, peerId, messageId: msgId,
+                chatType, peerId, messageId: msgId, replyContext,
             });
             return;
         }
         try {
-            let buffer;
-            if (this.client && aeskey) {
-                const result = await this.client.downloadFile(imageUrl, aeskey);
-                buffer = result.buffer;
-            }
-            else {
-                const { safeFetch } = await import('../utils/media-cache.js');
-                buffer = await safeFetch(imageUrl, { skipSsrfCheck: true });
-            }
-            const { validateImage } = await import('../utils/media-cache.js');
-            const result = await validateImage(buffer);
-            if (result.mime) {
+            const media = await this.downloadInboundMedia(imageUrl, aeskey);
+            const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+            if (image) {
                 await this.messageHandler({
                     channelId,
                     content: '用户发送了一张图片，请分析这张图片的内容。',
                     chatType, peerId, messageId: msgId,
-                    images: [{ data: buffer.toString('base64'), mimeType: result.mime }],
+                    images: [image], replyContext,
                 });
             }
             else {
                 logger.warn(`[WeCom] Image validation failed`);
                 await this.messageHandler({
                     channelId, content: '[图片验证失败]',
-                    chatType, peerId, messageId: msgId,
+                    chatType, peerId, messageId: msgId, replyContext,
                 });
             }
         }
@@ -232,97 +1011,83 @@ export class WecomChannel {
             logger.error('[WeCom] Failed to download image:', error);
             await this.messageHandler({
                 channelId, content: '[图片下载失败]',
-                chatType, peerId, messageId: msgId,
+                chatType, peerId, messageId: msgId, replyContext,
             });
         }
     }
-    async handleFileMessage(body, channelId, chatType, peerId, msgId, frame) {
+    async handleFileMessage(body, channelId, chatType, peerId, msgId, replyContext) {
         const fileUrl = body.file?.url;
         const aeskey = body.file?.aeskey;
-        const fileName = body.file?.filename || 'unknown';
+        const callbackFileName = body.file?.filename
+            ? sanitizeFileName(body.file.filename)
+            : undefined;
+        const displayFileName = callbackFileName || 'file';
         if (!fileUrl) {
             logger.warn('[WeCom] File message without url');
             await this.messageHandler({
-                channelId, content: `[文件下载失败：缺少下载链接] ${fileName}`,
-                chatType, peerId, messageId: msgId,
+                channelId, content: `[文件下载失败：缺少下载链接] ${displayFileName}`,
+                chatType, peerId, messageId: msgId, replyContext,
             });
             return;
         }
         try {
-            let buffer;
-            if (this.client && aeskey) {
-                const result = await this.client.downloadFile(fileUrl, aeskey);
-                buffer = result.buffer;
-            }
-            else {
-                const { safeFetch } = await import('../utils/media-cache.js');
-                buffer = await safeFetch(fileUrl, { skipSsrfCheck: true });
-            }
-            const { saveToUploads, sanitizeFileName } = await import('../utils/media-cache.js');
+            const media = await this.downloadInboundMedia(fileUrl, aeskey);
+            const fileName = sanitizeFileName(callbackFileName || media.filename || 'file');
             const projectPath = this.projectPathProvider
                 ? await this.projectPathProvider(channelId)
                 : process.cwd();
-            const { filePath } = saveToUploads(buffer, sanitizeFileName(fileName), projectPath);
+            const { filePath } = saveToUploads(media.buffer, fileName, projectPath);
             await this.messageHandler({
                 channelId,
                 content: `用户发送了文件：${fileName}\n文件已保存到：${filePath}\n请使用 Read 工具读取并分析文件内容。`,
-                chatType, peerId, messageId: msgId,
+                chatType, peerId, messageId: msgId, replyContext,
             });
         }
         catch (error) {
             logger.error('[WeCom] Failed to download file:', error);
             await this.messageHandler({
-                channelId, content: `[文件下载失败] ${fileName}`,
-                chatType, peerId, messageId: msgId,
+                channelId, content: `[文件下载失败] ${displayFileName}`,
+                chatType, peerId, messageId: msgId, replyContext,
             });
         }
     }
-    async handleVideoMessage(body, channelId, chatType, peerId, msgId, frame) {
+    async handleVideoMessage(body, channelId, chatType, peerId, msgId, replyContext) {
         const videoUrl = body.video?.url;
         const aeskey = body.video?.aeskey;
         if (!videoUrl) {
             await this.messageHandler({
                 channelId, content: '[视频下载失败：缺少下载链接]',
-                chatType, peerId, messageId: msgId,
+                chatType, peerId, messageId: msgId, replyContext,
             });
             return;
         }
         try {
-            let buffer;
-            if (this.client && aeskey) {
-                const result = await this.client.downloadFile(videoUrl, aeskey);
-                buffer = result.buffer;
-            }
-            else {
-                const { safeFetch } = await import('../utils/media-cache.js');
-                buffer = await safeFetch(videoUrl, { skipSsrfCheck: true });
-            }
-            const { saveToUploads } = await import('../utils/media-cache.js');
+            const media = await this.downloadInboundMedia(videoUrl, aeskey);
             const projectPath = this.projectPathProvider
                 ? await this.projectPathProvider(channelId)
                 : process.cwd();
             const fileName = `video_${Date.now()}.mp4`;
-            const { filePath } = saveToUploads(buffer, fileName, projectPath);
+            const { filePath } = saveToUploads(media.buffer, fileName, projectPath);
             await this.messageHandler({
                 channelId,
                 content: `用户发送了视频：${fileName}\n文件已保存到：${filePath}`,
-                chatType, peerId, messageId: msgId,
+                chatType, peerId, messageId: msgId, replyContext,
             });
         }
         catch (error) {
             logger.error('[WeCom] Failed to download video:', error);
             await this.messageHandler({
                 channelId, content: '[视频下载失败]',
-                chatType, peerId, messageId: msgId,
+                chatType, peerId, messageId: msgId, replyContext,
             });
         }
     }
-    async handleMixedMessage(body, channelId, chatType, peerId, msgId, frame) {
+    async handleMixedMessage(body, channelId, chatType, peerId, msgId, replyContext) {
         const msgItems = body.mixed?.msg_item;
         if (!Array.isArray(msgItems)) {
             await this.messageHandler({
                 channelId, content: '[不支持的图文混排格式]',
-                chatType, peerId, messageId: msgId,
+                chatType, peerId, messageId: msgId, replyContext,
             });
             return;
         }
@@ -334,20 +1099,10 @@ export class WecomChannel {
             }
             else if (item.msgtype === 'image' && item.image?.url) {
                 try {
-                    let buffer;
-                    if (this.client && item.image.aeskey) {
-                        const result = await this.client.downloadFile(item.image.url, item.image.aeskey);
-                        buffer = result.buffer;
-                    }
-                    else {
-                        const { safeFetch } = await import('../utils/media-cache.js');
-                        buffer = await safeFetch(item.image.url, { skipSsrfCheck: true });
-                    }
-                    const { validateImage } = await import('../utils/media-cache.js');
-                    const result = await validateImage(buffer);
-                    if (result.mime) {
-                        images.push({ data: buffer.toString('base64'), mimeType: result.mime });
-                    }
+                    const media = await this.downloadInboundMedia(item.image.url, item.image.aeskey);
+                    const image = await bufferToInboundImage(media.buffer, { filename: media.filename });
+                    if (image)
+                        images.push(image);
                 }
                 catch (error) {
                     logger.warn('[WeCom] Failed to download mixed image:', error);
@@ -359,81 +1114,132 @@ export class WecomChannel {
             channelId, content: prompt, chatType,
             peerId, messageId: msgId,
             images: images.length > 0 ? images : undefined,
+            replyContext,
         });
     }
     // ── Outbound: text ────────────────────────────────────────────────────────
-    async sendMessage(chatId, content) {
+    async sendMessage(chatId, content, replyContext) {
+        return this.sendStreamText(chatId, content, true, replyContext);
+    }
+    async sendStreamText(chatId, content, isFinal, replyContext) {
         if (!content || content.trim() === '') {
             logger.warn('[WeCom] Attempted to send empty message, skipping');
             return;
         }
-        if (!this.client) {
-            logger.error('[WeCom] Client not connected, cannot send message');
-            return;
-        }
+        const client = this.requireClient();
         try {
-            // Try stream reply first (responds to a specific user message)
-            const stream = this.activeStreams.get(chatId);
-            if (stream) {
-                await this.client.replyStream(stream.frame, stream.streamId, content, true);
-                this.activeStreams.delete(chatId);
-                logger.debug(`[WeCom] Sent stream reply to ${chatId}`);
+            const stream = this.streamFromReplyContext(replyContext);
+            if (stream && !stream.finished) {
+                stream.accumulatedText += content;
+                stream.lastUpdatedAt = Date.now();
+                const visibleText = truncateUtf8Bytes(stream.accumulatedText, 20_480);
+                if (!stream.expired) {
+                    try {
+                        if (isFinal) {
+                            await client.replyStream(stream.frame, stream.streamId, visibleText, true);
+                        }
+                        else {
+                            const result = await client.replyStreamNonBlocking(stream.frame, stream.streamId, visibleText, false);
+                            if (result === 'skipped')
+                                return;
+                        }
+                        stream.started = true;
+                    }
+                    catch (error) {
+                        if (wecomErrorCode(error) === 846608) {
+                            stream.expired = true;
+                            logger.warn(`[WeCom] Stream expired for reqId=${stream.reqId}; final reply will use proactive send`);
+                        }
+                        else {
+                            throw error;
+                        }
+                    }
+                }
+                if (isFinal) {
+                    stream.finished = true;
+                    if (stream.expired) {
+                        await this.sendProactiveMarkdown(chatId, stream.accumulatedText);
+                    }
+                    else {
+                        const chunks = splitUtf8Bytes(stream.accumulatedText, 20_480);
+                        for (const continuation of chunks.slice(1))
+                            await this.sendProactiveMarkdown(chatId, continuation);
+                    }
+                    logger.debug(`[WeCom] Finished stream reply reqId=${stream.reqId} chatId=${chatId}`);
+                }
                 return;
             }
-            // Fallback: proactive send (markdown)
-            await this.client.sendMessage(chatId, {
-                msgtype: 'markdown',
-                markdown: { content },
-            });
+            await this.sendProactiveMarkdown(chatId, content);
             logger.debug(`[WeCom] Sent proactive message to ${chatId}`);
         }
         catch (error) {
             logger.error(`[WeCom] sendMessage failed for ${chatId}:`, error.message);
+            throw error;
         }
     }
-    // ── Outbound: image ───────────────────────────────────────────────────────
-    async sendImage(chatId, png) {
-        if (!this.client) {
-            logger.warn('[WeCom] Client not connected for sendImage');
+    async finishStream(replyContext, fallbackText = '已完成') {
+        const stream = this.streamFromReplyContext(replyContext);
+        if (!stream || stream.finished)
             return;
+        const client = this.requireClient();
+        const content = stream.accumulatedText || fallbackText;
+        if (stream.expired) {
+            stream.finished = true;
+            await this.sendProactiveMarkdown(stream.chatId, content);
+            return;
+        }
+        try {
+            await client.replyStream(stream.frame, stream.streamId, truncateUtf8Bytes(content, 20_480), true);
+            stream.finished = true;
+            stream.lastUpdatedAt = Date.now();
+            const chunks = splitUtf8Bytes(content, 20_480);
+            for (const continuation of chunks.slice(1))
+                await this.sendProactiveMarkdown(stream.chatId, continuation);
+        }
+        catch (error) {
+            if (wecomErrorCode(error) !== 846608)
+                throw error;
+            stream.expired = true;
+            stream.finished = true;
+            await this.sendProactiveMarkdown(stream.chatId, content);
         }
+    }
+    // ── Outbound: image ───────────────────────────────────────────────────────
+    async sendImage(chatId, png, replyContext) {
+        const client = this.requireClient();
         try {
-            const result = await this.client.uploadMedia(png, {
+            const result = await client.uploadMedia(png, {
                 type: 'image',
                 filename: 'image.png',
             });
             const mediaId = result?.media_id;
             if (!mediaId) {
-                logger.error('[WeCom] Media upload failed: no media_id');
-                return;
+                throw new Error('WeCom media upload failed: no media_id');
             }
-            // Try reply media if we have an active frame, else proactive send
-            const stream = this.activeStreams.get(chatId);
-            if (stream) {
-                await this.client.replyMedia(stream.frame, 'image', mediaId);
-                this.activeStreams.delete(chatId);
+            const stream = this.streamFromReplyContext(replyContext);
+            if (stream && !stream.finished && !stream.started) {
+                await client.replyMedia(stream.frame, 'image', mediaId);
+                stream.finished = true;
             }
             else {
-                await this.client.sendMediaMessage(chatId, 'image', mediaId);
+                await this.finishStream(replyContext);
+                await client.sendMediaMessage(chatId, 'image', mediaId);
             }
             logger.debug(`[WeCom] Sent image to ${chatId}`);
         }
         catch (error) {
             logger.error(`[WeCom] sendImage failed for ${chatId}:`, error.message);
+            throw error;
         }
     }
     // ── Outbound: file ────────────────────────────────────────────────────────
-    async sendFile(chatId, filePath) {
-        if (!this.client) {
-            logger.warn('[WeCom] Client not connected for sendFile');
-            return;
-        }
+    async sendFile(chatId, filePath, replyContext) {
+        const client = this.requireClient();
         try {
             const fs = await import('fs');
             const path = await import('path');
             if (!fs.existsSync(filePath)) {
-                logger.error(`[WeCom] File not found: ${filePath}`);
-                return;
+                throw new Error(`WeCom file not found: ${filePath}`);
             }
             // Detect image files → route to sendImage
             const header = Buffer.alloc(12);
@@ -444,31 +1250,159 @@ export class WecomChannel {
             const ftype = await fileTypeFromBuffer(header);
             if (ftype && ftype.mime.startsWith('image/')) {
                 const buf = fs.readFileSync(filePath);
-                return this.sendImage(chatId, buf);
+                return this.sendImage(chatId, buf, replyContext);
             }
             const buf = fs.readFileSync(filePath);
             const fileName = path.basename(filePath);
-            const result = await this.client.uploadMedia(buf, {
+            const result = await client.uploadMedia(buf, {
                 type: 'file',
                 filename: fileName,
             });
             const mediaId = result?.media_id;
             if (!mediaId) {
-                logger.error('[WeCom] File upload failed: no media_id');
-                return;
+                throw new Error('WeCom file upload failed: no media_id');
             }
-            const stream = this.activeStreams.get(chatId);
-            if (stream) {
-                await this.client.replyMedia(stream.frame, 'file', mediaId);
-                this.activeStreams.delete(chatId);
+            const stream = this.streamFromReplyContext(replyContext);
+            if (stream && !stream.finished && !stream.started) {
+                await client.replyMedia(stream.frame, 'file', mediaId);
+                stream.finished = true;
             }
             else {
-                await this.client.sendMediaMessage(chatId, 'file', mediaId);
+                await this.finishStream(replyContext);
+                await client.sendMediaMessage(chatId, 'file', mediaId);
             }
             logger.debug(`[WeCom] Sent file ${fileName} to ${chatId}`);
         }
         catch (error) {
             logger.error(`[WeCom] sendFile failed for ${chatId}:`, error.message);
+            throw error;
+        }
+    }
+    async sendInteraction(chatId, interaction, replyContext) {
+        if (!this.cardStore)
+            return false;
+        return this.withInteractionSendLock(chatId, async () => {
+            const client = this.requireClient();
+            const superseded = this.cardStore.listPendingByChat(chatId)
+                .filter(record => record.interaction.id !== interaction.id);
+            const taskId = createWecomCardTaskId(this.channelKey, interaction.id);
+            const card = buildWecomInteractionCard(interaction, taskId);
+            const record = {
+                taskId,
+                interaction,
+                chatId,
+                createdAt: Date.now(),
+                updatedAt: Date.now(),
+                expiresAt: interaction.expiresAt,
+                status: 'pending',
+            };
+            const stream = this.streamFromReplyContext(replyContext);
+            try {
+                if (stream && !stream.finished) {
+                    if (stream.started) {
+                        await client.replyStreamWithCard(stream.frame, stream.streamId, truncateUtf8Bytes(stream.accumulatedText, 20_480), true, { templateCard: card });
+                        const chunks = splitUtf8Bytes(stream.accumulatedText, 20_480);
+                        for (const continuation of chunks.slice(1))
+                            await this.sendProactiveMarkdown(chatId, continuation);
+                    }
+                    else {
+                        await client.replyTemplateCard(stream.frame, card);
+                    }
+                    stream.finished = true;
+                }
+                else {
+                    await client.sendMessage(chatId, {
+                        msgtype: 'template_card',
+                        template_card: card,
+                    });
+                }
+                this.cardStore.set(record);
+                await this.invalidateSupersededCards(superseded);
+                logger.info(`[WeCom] Sent interaction card interaction=${interaction.id} taskId=${taskId}`);
+                return taskId;
+            }
+            catch (error) {
+                logger.error(`[WeCom] Failed to send interaction card ${interaction.id}: ${String(error)}`);
+                throw error;
+            }
+        });
+    }
+    async handleTemplateCardEvent(frame) {
+        const body = frame.body;
+        const client = this.client;
+        if (!body || !client || !this.cardStore)
+            return;
+        if (body.aibotid && body.aibotid !== this.config.botId) {
+            logger.warn(`[WeCom] Ignoring card callback for unexpected Bot ID: ${body.aibotid}`);
+            return;
+        }
+        const duplicate = body.msgid ? this.isDuplicate(body.msgid) : false;
+        if (duplicate)
+            logger.debug(`[WeCom] Replaying terminal response for duplicate card callback: ${body.msgid}`);
+        const rawEvent = body.event;
+        const event = (rawEvent?.template_card_event ?? rawEvent);
+        const taskId = String(event?.task_id ?? '').trim();
+        if (!taskId)
+            return;
+        const record = this.cardStore.get(taskId);
+        if (!record) {
+            logger.warn(`[WeCom] Card callback has no local record: taskId=${taskId}`);
+            await client.updateTemplateCard(frame, buildWecomUnknownCard(taskId), body.from?.userid ? [body.from.userid] : undefined);
+            return;
+        }
+        const operatorId = body.from?.userid;
+        if (record.interaction.initiatorId && operatorId !== record.interaction.initiatorId) {
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'rejected'), operatorId ? [operatorId] : undefined);
+            return;
+        }
+        if (record.status !== 'pending' || (record.expiresAt && Date.now() > record.expiresAt)) {
+            const reason = record.invalidationReason || (record.status === 'resolved' ? '已处理' : '已过期');
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'invalidated', reason), operatorId ? [operatorId] : undefined);
+            return;
+        }
+        if (this.cardCallbacksInFlight.has(taskId)) {
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'unavailable', '正在处理'), operatorId ? [operatorId] : undefined);
+            return;
+        }
+        this.cardCallbacksInFlight.add(taskId);
+        try {
+            const parsed = parseWecomCardResponse(record, event, operatorId);
+            if (!parsed) {
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'invalidated', '无法识别操作'), operatorId ? [operatorId] : undefined);
+                return;
+            }
+            if (parsed.command) {
+                if (!this.messageHandler) {
+                    await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'unavailable'), operatorId ? [operatorId] : undefined);
+                    return;
+                }
+                await this.messageHandler({
+                    channelId: record.chatId,
+                    content: parsed.command,
+                    chatType: body.chattype === 'group' ? 'group' : 'private',
+                    peerId: operatorId || '',
+                    messageId: `card-trigger-${body.msgid || Date.now()}`,
+                    source: 'card-trigger',
+                });
+                this.cardStore.resolve(taskId, parsed.command);
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'resolved', parsed.command));
+                return;
+            }
+            if (!parsed.response || !this.interactionCallback) {
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'unavailable'), operatorId ? [operatorId] : undefined);
+                return;
+            }
+            const accepted = (await this.interactionCallback(parsed.response)) !== false;
+            if (!accepted) {
+                const invalidated = this.cardStore.invalidateByInteractionId(record.interaction.id, 'backend_rejected') || record;
+                await client.updateTemplateCard(frame, buildWecomTerminalCard(invalidated, 'invalidated', '请求已失效'));
+                return;
+            }
+            this.cardStore.resolve(taskId, parsed.response.action);
+            await client.updateTemplateCard(frame, buildWecomTerminalCard(record, 'resolved', parsed.response.action));
+        }
+        finally {
+            this.cardCallbacksInFlight.delete(taskId);
         }
     }
 }
@@ -491,45 +1425,77 @@ export class WecomChannelPlugin {
         const adapter = {
             channelName: inst.name,
             channelKey: inst.name,
-            capabilities: { file: true, image: true, interaction: false, markdown: true, thought: false, status: false, thread: false, authenticatedApproval: true },
+            capabilities: { file: true, image: true, interaction: true, markdown: true, thought: false, status: true, thread: false, authenticatedApproval: true },
             send: async (envelope, payload) => {
                 const channelId = envelope.channelId;
                 switch (payload.kind) {
                     case 'result.text':
+                        await channel.sendStreamText(channelId, payload.text, payload.isFinal, envelope.replyContext);
+                        return;
                     case 'command.result':
                     case 'command.error':
                     case 'system.notice':
                     case 'system.error':
                     case 'result.error':
-                        await channel.sendMessage(channelId, payload.text);
+                        await channel.sendMessage(channelId, payload.text, envelope.replyContext);
                         return;
                     case 'result.file':
-                        await channel.sendFile(channelId, payload.filePath);
+                        await channel.sendFile(channelId, payload.filePath, envelope.replyContext);
                         return;
                     case 'result.image':
-                        await channel.sendImage(channelId, payload.data);
+                        await channel.sendImage(channelId, payload.data, envelope.replyContext);
                         return;
                     case 'activity.batch': {
                         const filtered = payload.items.filter((i) => !(i.kind === 'tool_result' && i.ok));
                         const text = formatItemsAsText(filtered);
                         if (text)
-                            await channel.sendMessage(channelId, text);
+                            await channel.sendStreamText(channelId, text, false, envelope.replyContext);
                         return;
                     }
+                    case 'status.completed':
+                        await channel.finishStream(envelope.replyContext);
+                        return;
+                    case 'status.interrupted':
+                        await channel.finishStream(envelope.replyContext, payload.metadata?.reason === 'daemon_restart' ? '服务正在重启，将继续处理…' : '任务已中止');
+                        return;
+                    case 'status.timeout':
+                        await channel.finishStream(envelope.replyContext, '任务已中止');
+                        return;
+                    case 'status.started':
+                    case 'status.queued':
+                    case 'status.progress': return;
                     case 'status.requires_action':
-                        await channel.sendMessage(channelId, '等待 owner 审批');
+                        await channel.sendMessage(channelId, '等待 owner 审批', envelope.replyContext);
                         return;
                     case 'status.error':
-                        if (payload.metadata?.message)
-                            await channel.sendMessage(channelId, payload.metadata.message);
-                        return;
-                    case 'interaction':
-                        if (payload.fallbackText)
-                            await channel.sendMessage(channelId, payload.fallbackText);
+                        if (payload.metadata?.message) {
+                            await channel.sendMessage(channelId, payload.metadata.message, envelope.replyContext);
+                        }
+                        else {
+                            await channel.finishStream(envelope.replyContext, '任务执行失败');
+                        }
                         return;
+                    case 'interaction': {
+                        try {
+                            const taskId = await channel.sendInteraction(channelId, payload.interaction, envelope.replyContext);
+                            if (taskId)
+                                return;
+                        }
+                        catch (error) {
+                            logger.warn(`[WeCom] Interaction card delivery failed, using text fallback: ${error instanceof Error ? error.message : String(error)}`);
+                        }
+                        if (payload.fallbackText) {
+                            await channel.sendMessage(channelId, payload.fallbackText, envelope.replyContext);
+                            return;
+                        }
+                        throw new Error('WeCom interaction delivery failed and no fallback text was provided');
+                    }
                     default: return;
                 }
             },
+            onInteraction: (callback) => channel.onInteraction(callback),
+            onInteractionInvalidated: (callback) => channel.onInteractionInvalidated(callback),
+            invalidateInteraction: (interactionId, reason) => channel.invalidateInteraction(interactionId, reason),
         };
         const policy = {
             canSwitchProject: (_, identity) => identity === 'owner' || identity === 'admin',
@@ -546,19 +1512,21 @@ export class WecomChannelPlugin {
         return {
             channelType: 'wecom', adapter, channel,
             policy,
-            options: { fileMarkerPattern: /\[SEND_FILE:(?:(\w+):)?([^\]]+)\]/g, supportsImages: true, flushDelay: inst.flushDelay },
+            options: { fileMarkerPattern: createSendFileMarkerPattern(), supportsImages: true, flushDelay: inst.flushDelay },
             connect: () => channel.connect(),
             disconnect: () => channel.disconnect(),
             onProjectPathRequest: () => Promise.resolve(ctx.defaultProjectPath),
             registerBridge(bridge, channelType) {
                 bridge.register(adapter.channelName, (handler) => channel.onMessage(async (event) => {
-                    handler({
+                    await handler({
                         channel: adapter.channelName, channelType, channelId: event.channelId,
                         selfAID: ctx.agentName, content: event.content, images: event.images,
                         chatType: event.chatType || 'private', peerId: event.peerId || '',
                         peerName: event.peerName, messageId: event.messageId,
+                        replyContext: event.replyContext,
+                        source: event.source,
                     });
-                }), (channelId, text) => channel.sendMessage(channelId, text), adapter, channelType);
+                }), (channelId, text, replyContext) => channel.sendMessage(channelId, text, replyContext), adapter, channelType);
             },
         };
     }