shennian 0.2.72 → 0.2.74

package/dist/src/channels/runtime.js

@@ -1,16 +1,23 @@
 // @arch docs/features/manager-agent.md
 // @test src/__tests__/manager-runtime.test.ts
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
 import { ChannelConfigRegistry } from './registry.js';
 import { ChannelSecretRegistry } from './secret-registry.js';
 import { WeComChannelAdapter } from './wecom.js';
+import { WeChatRpaChannelAdapter } from './wechat-rpa.js';
 import { ExternalWebSocketChannelAdapter } from './websocket.js';
 import { splitExternalReplyText } from './reply-split.js';
+import { loadConfig } from '../config/index.js';
+import { SERVERS } from '../region.js';
 export class ChannelRuntime {
     onExternalMessage;
     createReplyTarget;
     configs = new ChannelConfigRegistry();
     secrets = new ChannelSecretRegistry();
     adapters = new Map();
+    completedReplyKeys = new Map();
     constructor(onExternalMessage, createReplyTarget) {
         this.onExternalMessage = onExternalMessage;
         this.createReplyTarget = createReplyTarget;
@@ -18,6 +25,8 @@ export class ChannelRuntime {
         this.adapters.set(wecom.type, wecom);
         const websocket = new ExternalWebSocketChannelAdapter((event) => this.ingest({ type: 'external.message', ...event }));
         this.adapters.set(websocket.type, websocket);
+        const wechatRpa = new WeChatRpaChannelAdapter((event) => this.ingest({ type: 'external.message', ...event }));
+        this.adapters.set(wechatRpa.type, wechatRpa);
     }
     async start() {
         for (const config of this.configs.list().filter((channel) => channel.enabled)) {
@@ -53,24 +62,55 @@ export class ChannelRuntime {
         if (!adapter)
             return { ok: false, error: `Unsupported channel type: ${config.type}` };
         try {
-            const parts = splitExternalReplyText(input.text);
-            if (!parts.length)
-                return { ok: false, error: 'Reply text is required' };
-            for (const [index, text] of parts.entries()) {
-                await adapter.send(config, {
+            const sends = planExternalReplySends(config.type, input);
+            if (!sends.length)
+                return { ok: false, error: 'Reply text or attachment is required' };
+            let pending = false;
+            for (const send of sends) {
+                const idempotencyKey = send.idempotencyKey;
+                if (idempotencyKey && this.isReplyCompleted(config, input.conversationId, idempotencyKey))
+                    continue;
+                const result = await adapter.send(config, {
                     ...input,
-                    text,
-                    idempotencyKey: parts.length > 1 && input.idempotencyKey
-                        ? `${input.idempotencyKey}:${index + 1}`
-                        : input.idempotencyKey,
+                    ...send,
                 });
+                if (result?.status === 'queued') {
+                    pending = true;
+                    continue;
+                }
+                if (idempotencyKey)
+                    this.markReplyCompleted(config, input.conversationId, idempotencyKey);
             }
-            return { ok: true };
+            return pending ? { ok: true, pending: true } : { ok: true };
         }
         catch (err) {
             return { ok: false, error: err instanceof Error ? err.message : String(err) };
         }
     }
+    isReplyCompleted(config, conversationId, idempotencyKey) {
+        const set = this.loadReplyCompletionSet(config);
+        return set.has(replyCompletionKey(config.id, conversationId, idempotencyKey));
+    }
+    markReplyCompleted(config, conversationId, idempotencyKey) {
+        const set = this.loadReplyCompletionSet(config);
+        set.add(replyCompletionKey(config.id, conversationId, idempotencyKey));
+        try {
+            persistReplyCompletionSet(config.workDir, set);
+        }
+        catch {
+            // Some tests and diagnostic channels use virtual workDirs. In-memory idempotency
+            // still protects the current daemon; persistence resumes when workDir is writable.
+        }
+    }
+    loadReplyCompletionSet(config) {
+        const cacheKey = path.resolve(config.workDir);
+        const cached = this.completedReplyKeys.get(cacheKey);
+        if (cached)
+            return cached;
+        const set = readReplyCompletionSet(config.workDir);
+        this.completedReplyKeys.set(cacheKey, set);
+        return set;
+    }
     async getDefaultReplyTarget(sessionId) {
         const config = this.configs.list().find((channel) => (channel.sessionId ?? channel.managerSessionId) === sessionId && channel.enabled);
         if (!config)
@@ -91,6 +131,7 @@ export class ChannelRuntime {
         if (!config)
             return null;
         const secret = this.secrets.get(config.secretRef);
+        const adapterStatus = this.adapters.get(config.type)?.runtimeStatus?.(config) ?? {};
         return {
             id: config.id,
             type: config.type,
@@ -107,6 +148,8 @@ export class ChannelRuntime {
             tokenConfigured: Boolean(secret?.token),
             canReply: Boolean(secret?.canReply),
             systemPrompt: typeof secret?.systemPrompt === 'string' ? secret.systemPrompt : '',
+            ...wechatRpaViewFields(secret, opts.includeSecret),
+            ...adapterStatus,
         };
     }
     getChannelById(channelId, opts = {}) {
@@ -114,6 +157,7 @@ export class ChannelRuntime {
         if (!config)
             return null;
         const secret = this.secrets.get(config.secretRef);
+        const adapterStatus = this.adapters.get(config.type)?.runtimeStatus?.(config) ?? {};
         return {
             id: config.id,
             type: config.type,
@@ -130,6 +174,26 @@ export class ChannelRuntime {
             tokenConfigured: Boolean(secret?.token),
             canReply: Boolean(secret?.canReply),
             systemPrompt: typeof secret?.systemPrompt === 'string' ? secret.systemPrompt : '',
+            ...wechatRpaViewFields(secret, opts.includeSecret),
+            ...adapterStatus,
+        };
+    }
+    getChannelStatusById(channelId) {
+        const config = this.configs.get(channelId);
+        if (!config)
+            return null;
+        const secret = this.secrets.get(config.secretRef);
+        const adapterStatus = this.adapters.get(config.type)?.runtimeStatus?.(config) ?? {};
+        return {
+            configured: true,
+            connected: isChannelSecretConfigured(config, secret),
+            type: config.type,
+            channelId: config.id,
+            name: config.name,
+            canReply: Boolean(secret?.canReply),
+            systemPrompt: typeof secret?.systemPrompt === 'string' ? secret.systemPrompt : '',
+            ...wechatRpaStatusFields(secret),
+            ...adapterStatus,
         };
     }
     getManagerChannelStatus(managerSessionId) {
@@ -137,14 +201,17 @@ export class ChannelRuntime {
         if (!config)
             return null;
         const secret = this.secrets.get(config.secretRef);
+        const adapterStatus = this.adapters.get(config.type)?.runtimeStatus?.(config) ?? {};
         return {
             configured: true,
-            connected: Boolean(secret?.token),
+            connected: isChannelSecretConfigured(config, secret),
             type: config.type,
             channelId: config.id,
             name: config.name,
             canReply: Boolean(secret?.canReply),
             systemPrompt: typeof secret?.systemPrompt === 'string' ? secret.systemPrompt : '',
+            ...wechatRpaStatusFields(secret),
+            ...adapterStatus,
         };
     }
     listManagerChannelStatuses() {
@@ -156,11 +223,24 @@ export class ChannelRuntime {
         }))
             .filter((entry) => Boolean(entry.status));
     }
-    listManagerChannelSystemPrompts(managerSessionId) {
+    listManagerExternalChannels(managerSessionId) {
         return this.configs.list()
             .filter((channel) => channel.enabled && (channel.sessionId ?? channel.managerSessionId) === managerSessionId)
-            .map((channel) => this.secrets.get(channel.secretRef)?.systemPrompt)
-            .filter((prompt) => typeof prompt === 'string' && prompt.trim().length > 0);
+            .map((channel) => {
+            const secret = this.secrets.get(channel.secretRef);
+            const adapterStatus = this.adapters.get(channel.type)?.runtimeStatus?.(channel) ?? {};
+            return {
+                configured: true,
+                connected: isChannelSecretConfigured(channel, secret),
+                type: channel.type,
+                channelId: channel.id,
+                name: channel.name,
+                canReply: Boolean(secret?.canReply),
+                systemPrompt: typeof secret?.systemPrompt === 'string' ? secret.systemPrompt : '',
+                ...wechatRpaStatusFields(secret),
+                ...adapterStatus,
+            };
+        });
     }
     async upsertManagerChannel(input) {
         const previous = this.configs.get(input.id);
@@ -214,4 +294,210 @@ export class ChannelRuntime {
         }
         return this.getManagerChannel(boundSessionId, input.type, { includeSecret: true });
     }
+    async upsertManagerWeChatRpaChannel(input) {
+        const previous = this.configs.get(input.id);
+        const allConfigs = this.configs.list();
+        const boundSessionId = input.sessionId || input.managerSessionId;
+        const groups = normalizeWeChatRpaGroups(input.groups);
+        if (input.enabled && !groups.length)
+            throw new Error('WeChat RPA 至少需要配置一个群');
+        const nextConfig = {
+            id: input.id,
+            type: 'wechat-rpa',
+            name: input.name?.trim() || previous?.name || '本机微信 RPA',
+            sessionId: boundSessionId,
+            managerSessionId: boundSessionId,
+            workDir: input.workDir,
+            agentType: input.agentType || previous?.agentType,
+            agentSessionId: input.agentSessionId ?? previous?.agentSessionId ?? null,
+            modelId: input.modelId ?? previous?.modelId ?? null,
+            enabled: input.enabled,
+            secretRef: previous?.secretRef || `channel:${input.id}`,
+        };
+        const priorSecret = this.secrets.get(nextConfig.secretRef);
+        const source = input.source || (priorSecret?.source === 'macos-probe' || priorSecret?.source === 'fixture-jsonl' || priorSecret?.source === 'macos-flow' ? priorSecret.source : 'macos-flow');
+        const configs = allConfigs
+            .filter((channel) => channel.id !== nextConfig.id)
+            .map((channel) => (channel.sessionId ?? channel.managerSessionId) === boundSessionId && channel.type === 'wechat-rpa'
+            ? { ...channel, enabled: false }
+            : channel);
+        configs.push(nextConfig);
+        this.configs.replaceAll(configs);
+        const cloudOcrMode = normalizeCloudOcrMode(input.cloudOcrMode ?? priorSecret?.cloudOcrMode);
+        const cloudOcrDefaults = cloudOcrMode === 'off' ? {} : defaultWeChatRpaCloudOcrConfig();
+        this.secrets.upsert(nextConfig.secretRef, {
+            type: 'wechat-rpa',
+            source,
+            groups,
+            pollIntervalMs: clampOptionalNumber(input.pollIntervalMs, priorSecret?.pollIntervalMs),
+            recentLimit: clampOptionalNumber(input.recentLimit, priorSecret?.recentLimit),
+            idleSeconds: clampOptionalNumber(input.idleSeconds, priorSecret?.idleSeconds),
+            forceForeground: input.forceForeground ?? Boolean(priorSecret?.forceForeground),
+            noRestore: input.noRestore ?? (priorSecret?.noRestore === undefined ? true : Boolean(priorSecret.noRestore)),
+            downloadAttachments: input.downloadAttachments ?? (priorSecret?.downloadAttachments === undefined ? true : Boolean(priorSecret.downloadAttachments)),
+            downloadAttachmentsDir: input.downloadAttachmentsDir?.trim() || stringOrUndefined(priorSecret?.downloadAttachmentsDir),
+            flowScriptPath: input.flowScriptPath?.trim() || stringOrUndefined(priorSecret?.flowScriptPath),
+            cloudOcrUrl: input.cloudOcrUrl?.trim() || stringOrUndefined(priorSecret?.cloudOcrUrl) || cloudOcrDefaults.cloudOcrUrl,
+            cloudOcrToken: input.cloudOcrToken?.trim() || stringOrUndefined(priorSecret?.cloudOcrToken) || cloudOcrDefaults.cloudOcrToken,
+            cloudOcrMode,
+            canReply: input.canReply ?? priorSecret?.canReply ?? false,
+            systemPrompt: input.systemPrompt ?? (typeof priorSecret?.systemPrompt === 'string' ? priorSecret.systemPrompt : ''),
+        });
+        const adapter = this.adapters.get(nextConfig.type);
+        for (const config of allConfigs) {
+            if ((config.sessionId ?? config.managerSessionId) === boundSessionId && config.type === 'wechat-rpa' && config.enabled) {
+                await this.adapters.get(config.type)?.disconnect(config).catch(() => { });
+            }
+        }
+        if (nextConfig.enabled) {
+            void adapter?.connect(nextConfig).catch(() => { });
+        }
+        return this.getManagerChannel(boundSessionId, 'wechat-rpa', { includeSecret: true });
+    }
+}
+function isChannelSecretConfigured(config, secret) {
+    if (!secret || secret.type !== config.type)
+        return false;
+    if (config.type === 'wechat-rpa')
+        return true;
+    if (config.type === 'websocket')
+        return Boolean(secret.wsUrl && secret.token);
+    if (config.type === 'wecom')
+        return Boolean(secret.token || secret.botId || secret.secret);
+    return Boolean(secret.token);
+}
+function wechatRpaViewFields(secret, includeSecret) {
+    if (!secret || secret.type !== 'wechat-rpa')
+        return {};
+    return {
+        wechatRpaSource: typeof secret.source === 'string' ? secret.source : '',
+        wechatRpaGroups: normalizeWeChatRpaGroups(Array.isArray(secret.groups) ? secret.groups : []),
+        pollIntervalMs: Number.isFinite(secret.pollIntervalMs) ? Number(secret.pollIntervalMs) : undefined,
+        recentLimit: Number.isFinite(secret.recentLimit) ? Number(secret.recentLimit) : undefined,
+        idleSeconds: Number.isFinite(secret.idleSeconds) ? Number(secret.idleSeconds) : undefined,
+        forceForeground: Boolean(secret.forceForeground),
+        noRestore: secret.noRestore === undefined ? undefined : Boolean(secret.noRestore),
+        downloadAttachments: secret.downloadAttachments === undefined ? true : Boolean(secret.downloadAttachments),
+        downloadAttachmentsDir: typeof secret.downloadAttachmentsDir === 'string' ? secret.downloadAttachmentsDir : '',
+        cloudOcrUrl: typeof secret.cloudOcrUrl === 'string' ? secret.cloudOcrUrl : '',
+        cloudOcrToken: includeSecret && typeof secret.cloudOcrToken === 'string' ? secret.cloudOcrToken : '',
+        cloudOcrMode: typeof secret.cloudOcrMode === 'string' ? secret.cloudOcrMode : 'off',
+    };
+}
+function wechatRpaStatusFields(secret) {
+    if (!secret || secret.type !== 'wechat-rpa')
+        return {};
+    return {
+        wechatRpaSource: typeof secret.source === 'string' ? secret.source : null,
+        wechatRpaGroups: normalizeWeChatRpaGroups(Array.isArray(secret.groups) ? secret.groups : []),
+        pollIntervalMs: Number.isFinite(secret.pollIntervalMs) ? Number(secret.pollIntervalMs) : null,
+        recentLimit: Number.isFinite(secret.recentLimit) ? Number(secret.recentLimit) : null,
+        idleSeconds: Number.isFinite(secret.idleSeconds) ? Number(secret.idleSeconds) : null,
+        forceForeground: Boolean(secret.forceForeground),
+        noRestore: secret.noRestore === undefined ? null : Boolean(secret.noRestore),
+        downloadAttachments: secret.downloadAttachments === undefined ? true : Boolean(secret.downloadAttachments),
+        downloadAttachmentsDir: typeof secret.downloadAttachmentsDir === 'string' ? secret.downloadAttachmentsDir : null,
+        cloudOcrUrl: typeof secret.cloudOcrUrl === 'string' ? secret.cloudOcrUrl : null,
+        cloudOcrMode: typeof secret.cloudOcrMode === 'string' ? secret.cloudOcrMode : 'off',
+    };
+}
+function normalizeWeChatRpaGroups(groups) {
+    const seen = new Set();
+    const result = [];
+    for (const group of groups) {
+        const name = String(group?.name || '').replace(/\s+/g, ' ').trim();
+        if (!name || seen.has(name))
+            continue;
+        seen.add(name);
+        result.push({ name });
+    }
+    return result;
+}
+function normalizeCloudOcrMode(value) {
+    return value === 'fallback' || value === 'always' ? value : 'off';
+}
+function defaultWeChatRpaCloudOcrConfig() {
+    const config = loadConfig();
+    const serverUrl = (config.serverUrl || SERVERS.cn.url).replace(/\/+$/, '');
+    const token = config.machineToken?.trim() || config.accessToken?.trim();
+    return {
+        cloudOcrUrl: `${serverUrl}/integrations/wechat-rpa/ocr`,
+        ...(token ? { cloudOcrToken: token } : {}),
+    };
+}
+export function planExternalReplySends(channelType, input) {
+    const parts = splitExternalReplyText(input.text);
+    if (!parts.length && !input.attachment)
+        return [];
+    if (channelType === 'wechat-rpa' && input.attachment && parts.length <= 1) {
+        return [{
+                text: parts[0] ?? '',
+                attachment: input.attachment,
+                idempotencyKey: input.idempotencyKey,
+            }];
+    }
+    const sends = parts.map((text, index) => ({
+        text,
+        attachment: undefined,
+        idempotencyKey: parts.length > 1 && input.idempotencyKey
+            ? `${input.idempotencyKey}:${index + 1}`
+            : input.idempotencyKey,
+    }));
+    if (input.attachment) {
+        sends.push({
+            text: '',
+            attachment: input.attachment,
+            idempotencyKey: parts.length && input.idempotencyKey
+                ? `${input.idempotencyKey}:attachment`
+                : input.idempotencyKey,
+        });
+    }
+    return sends;
+}
+function replyCompletionKey(channelId, conversationId, idempotencyKey) {
+    return crypto.createHash('sha256')
+        .update(`${channelId}\n${conversationId}\n${idempotencyKey}`)
+        .digest('hex')
+        .slice(0, 32);
+}
+function replyCompletionFile(workDir) {
+    return path.join(workDir, '.shennian', 'external-reply-idempotency.json');
+}
+function readReplyCompletionSet(workDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(replyCompletionFile(workDir), 'utf8'));
+        const rows = Array.isArray(parsed.completed) ? parsed.completed : [];
+        return new Set(rows
+            .map((row) => {
+            if (typeof row === 'string')
+                return row;
+            if (row && typeof row === 'object' && typeof row.key === 'string') {
+                return row.key;
+            }
+            return '';
+        })
+            .filter(Boolean));
+    }
+    catch {
+        return new Set();
+    }
+}
+function persistReplyCompletionSet(workDir, set) {
+    const filePath = replyCompletionFile(workDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const keys = Array.from(set).slice(-500);
+    fs.writeFileSync(filePath, JSON.stringify({
+        updatedAt: new Date().toISOString(),
+        completed: keys.map((key) => ({ key })),
+    }, null, 2));
+    set.clear();
+    for (const key of keys)
+        set.add(key);
+}
+function clampOptionalNumber(value, fallback) {
+    const number = Number(value ?? fallback);
+    return Number.isFinite(number) && number >= 0 ? number : undefined;
+}
+function stringOrUndefined(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }

package/dist/src/channels/secret-registry.d.ts

@@ -1,11 +1,27 @@
 type ChannelSecretRecord = {
-    type: 'wecom' | 'websocket';
+    type: 'wecom' | 'websocket' | 'wechat-rpa';
     botId?: string;
     secret?: string;
     wsUrl?: string;
     token?: string;
     canReply?: boolean;
     systemPrompt?: string;
+    source?: 'macos-probe' | 'macos-flow' | 'fixture-jsonl';
+    fixturePath?: string;
+    pollIntervalMs?: number;
+    groups?: Array<{
+        name: string;
+    }>;
+    forceForeground?: boolean;
+    noRestore?: boolean;
+    downloadAttachments?: boolean;
+    downloadAttachmentsDir?: string;
+    idleSeconds?: number;
+    recentLimit?: number;
+    flowScriptPath?: string;
+    cloudOcrUrl?: string;
+    cloudOcrToken?: string;
+    cloudOcrMode?: 'off' | 'fallback' | 'always';
     updatedAt: string;
 };
 export declare class ChannelSecretRegistry {

package/dist/src/channels/websocket.d.ts

@@ -44,6 +44,9 @@ export declare class ExternalWebSocketChannelAdapter implements ExternalChannelA
     private sendAwaitAck;
     private handlePayload;
     private buildVisibleText;
+    private batchMessageKey;
+    private hasSeenBatchMessage;
+    private rememberBatchMessage;
     private normalizeAttachments;
     private formatAttachment;
     private formatMessageTime;

package/dist/src/channels/websocket.js

@@ -120,6 +120,8 @@ export class ExternalWebSocketChannelAdapter {
                 pingTimer: null,
                 dedup: new Set(),
                 dedupQueue: [],
+                seenBatchMessageKeys: new Set(),
+                seenBatchMessageQueue: [],
                 pendingAcks: new Map(),
             };
             this.connections.set(config.id, conn);
@@ -232,8 +234,10 @@ export class ExternalWebSocketChannelAdapter {
         if (!messageId || this.isDuplicate(conn, messageId))
             return;
         const attachments = this.normalizeAttachments(payload);
-        const text = this.buildVisibleText(payload, attachments);
+        const text = this.buildVisibleText(conn, payload, attachments);
         const conversationId = String(payload.conversationId || '').trim();
+        if (Array.isArray(payload.messages) && !text)
+            return;
         if ((!text && attachments.length === 0) || !conversationId)
             return;
         this.onMessage?.({
@@ -252,7 +256,7 @@ export class ExternalWebSocketChannelAdapter {
             replyTarget: '',
         });
     }
-    buildVisibleText(payload, attachments) {
+    buildVisibleText(conn, payload, attachments) {
         const text = String(payload.text || '').trim();
         if (text)
             return text;
@@ -262,6 +266,9 @@ export class ExternalWebSocketChannelAdapter {
                 if (!item || typeof item !== 'object')
                     return '';
                 const message = item;
+                const messageKey = this.batchMessageKey(message, payload);
+                if (messageKey && this.hasSeenBatchMessage(conn, messageKey))
+                    return '';
                 const isGroupMessage = String(message.conversationType || payload.conversationType || '') === 'group';
                 const sender = String(message.senderName || (isGroupMessage ? '群友' : message.senderExternalId || message.senderId || 'unknown'));
                 const time = this.formatMessageTime(message.timestampIso || message.timestamp);
@@ -269,6 +276,8 @@ export class ExternalWebSocketChannelAdapter {
                 const messageAttachments = this.normalizeAttachments(message);
                 const attachmentText = messageAttachments.map((attachment) => this.formatAttachment(attachment)).join(' ');
                 const content = [messageText, attachmentText].filter(Boolean).join(' ').trim() || `[${String(message.contentType || 'message')}]`;
+                if (messageKey)
+                    this.rememberBatchMessage(conn, messageKey);
                 return `${index + 1}. ${time} ${sender}: ${content}`;
             })
                 .filter(Boolean)
@@ -277,6 +286,34 @@ export class ExternalWebSocketChannelAdapter {
         }
         return attachments.map((attachment) => this.formatAttachment(attachment)).join('\n');
     }
+    batchMessageKey(message, payload) {
+        const explicitId = String(message.messageId || message.msgid || message.id || message.rawId || '').trim();
+        if (explicitId)
+            return `id:${explicitId}`;
+        const sender = String(message.senderExternalId || message.senderId || message.senderName || '').trim();
+        const timestamp = String(message.timestampIso || message.timestamp || message.receivedAt || '').trim();
+        const text = String(message.text || '').trim();
+        const contentType = String(message.contentType || '').trim();
+        const conversationId = String(message.conversationId || payload.conversationId || '').trim();
+        const attachmentKey = this.normalizeAttachments(message)
+            .map((attachment) => [attachment.type, attachment.name || '', attachment.url || '', attachment.size ?? ''].join(':'))
+            .join('|');
+        return `content:${conversationId}\n${sender}\n${timestamp}\n${contentType}\n${text}\n${attachmentKey}`;
+    }
+    hasSeenBatchMessage(conn, key) {
+        return conn.seenBatchMessageKeys.has(key);
+    }
+    rememberBatchMessage(conn, key) {
+        if (conn.seenBatchMessageKeys.has(key))
+            return;
+        conn.seenBatchMessageKeys.add(key);
+        conn.seenBatchMessageQueue.push(key);
+        while (conn.seenBatchMessageQueue.length > 2_000) {
+            const removed = conn.seenBatchMessageQueue.shift();
+            if (removed)
+                conn.seenBatchMessageKeys.delete(removed);
+        }
+    }
     normalizeAttachments(payload) {
         const direct = Array.isArray(payload.attachments) ? payload.attachments : [];
         const nested = Array.isArray(payload.messages)

package/dist/src/channels/wechat-rpa/macos-flow.d.ts

@@ -0,0 +1,77 @@
+export type MacWeChatRpaFlowOptions = {
+    groupName: string;
+    replyText?: string;
+    attachmentPath?: string;
+    scriptPath?: string;
+    workDir?: string;
+    forceForeground?: boolean;
+    noRestore?: boolean;
+    idleSeconds?: number;
+    recentLimit?: number;
+    downloadAttachmentsDir?: string;
+    timeoutMs?: number;
+    cloudOcrUrl?: string;
+    cloudOcrToken?: string;
+    cloudOcrMode?: 'off' | 'fallback' | 'always';
+    cloudOcrChannelId?: string;
+};
+export type MacWeChatRpaFlowResult = {
+    ok: boolean;
+    groupName: string;
+    interrupted?: boolean;
+    reason?: string;
+    screenshotPath?: string;
+    recentMessages?: MacWeChatRpaFlowMessage[];
+    newMessages?: MacWeChatRpaFlowMessage[];
+    sentReply?: boolean;
+    sentReplyObserved?: boolean;
+    sentAttachment?: boolean;
+    sentAttachmentObserved?: boolean;
+    postSendScreenshotPath?: string;
+    cloudOcrPurpose?: MacWeChatRpaCloudOcrPurpose;
+    cloudOcrObservations?: MacWeChatRpaCloudOcrObservation[];
+    cloudOcrRequestId?: string;
+    cloudOcrImageHash?: string;
+    cloudOcrUsage?: MacWeChatRpaCloudOcrUsage;
+    error?: string;
+};
+export type MacWeChatRpaCloudOcrPurpose = 'message-read' | 'attachment-localization' | 'send-confirmation';
+export type MacWeChatRpaFlowMessage = {
+    id?: string;
+    text?: string;
+    confidence?: number;
+    attachments?: MacWeChatRpaAttachment[];
+};
+export type MacWeChatRpaAttachment = {
+    type: string;
+    name?: string;
+    mimeType?: string;
+    size?: number;
+    url?: string;
+    localPath?: string;
+    thumbnailPath?: string;
+    hash?: string;
+    availability?: 'edge-local' | 'server-url' | 'pending-download' | 'metadata-only' | 'unavailable-large';
+    machineId?: string;
+    expiresAt?: string;
+    providerError?: string;
+};
+export type MacWeChatRpaCloudOcrObservation = {
+    text: string;
+    confidence?: number;
+    role?: string;
+    attachment?: MacWeChatRpaAttachment;
+};
+export type MacWeChatRpaCloudOcrUsage = {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+};
+export declare function runMacWeChatRpaFlow(options: MacWeChatRpaFlowOptions): Promise<MacWeChatRpaFlowResult>;
+export declare function selectCloudOcrRequest(result: Pick<MacWeChatRpaFlowResult, 'newMessages' | 'recentMessages' | 'screenshotPath' | 'postSendScreenshotPath' | 'sentReply' | 'sentAttachment'>, mode: 'off' | 'fallback' | 'always'): {
+    screenshotPath: string;
+    purpose: MacWeChatRpaCloudOcrPurpose;
+} | null;
+export declare function shouldUseCloudOcr(result: Pick<MacWeChatRpaFlowResult, 'newMessages' | 'recentMessages'>, mode: 'off' | 'fallback' | 'always'): boolean;
+export declare function mergeCloudMessages(localMessages: MacWeChatRpaFlowMessage[], cloudMessages: MacWeChatRpaFlowMessage[]): MacWeChatRpaFlowMessage[];
+export declare function messagesFromCloudOcrObservations(groupName: string, observations: MacWeChatRpaCloudOcrObservation[]): MacWeChatRpaFlowMessage[];