shennian 0.2.75 → 0.2.77

package/dist/src/channels/wechat-rpa/windows-visual-flow.js

@@ -0,0 +1,182 @@
+// @arch docs/features/wechat-rpa-channel.md
+// @test src/__tests__/wechat-rpa-normalizer.test.ts
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export function buildWindowsVisualFlowExec(options) {
+    const scriptPath = resolveWindowsVisualScriptPath(options.scriptPath, options.workDir);
+    const args = [
+        scriptPath,
+        '--group',
+        options.groupName,
+        '--recent-limit',
+        String(Number.isFinite(options.recentLimit) ? options.recentLimit : 5),
+    ];
+    if (options.replyText)
+        args.push('--reply-text', options.replyText);
+    const attachmentPaths = normalizeAttachmentPaths(options);
+    for (const attachmentPath of attachmentPaths)
+        args.push('--file', attachmentPath);
+    if (options.downloadAttachmentsDir)
+        args.push('--download-attachments-dir', options.downloadAttachmentsDir);
+    if (options.cloudOcrUrl)
+        args.push('--ocr-url', options.cloudOcrUrl);
+    if (options.cloudOcrToken)
+        args.push('--token', options.cloudOcrToken);
+    if (options.cloudOcrChannelId)
+        args.push('--channel-id', options.cloudOcrChannelId);
+    if (options.helperPath)
+        args.push('--helper', options.helperPath);
+    if (options.ocrFixturePath)
+        args.push('--ocr-fixture', options.ocrFixturePath);
+    return {
+        command: process.execPath,
+        args,
+        execOptions: {
+            cwd: options.workDir || process.cwd(),
+            timeout: options.timeoutMs ?? 120_000,
+            maxBuffer: 20 * 1024 * 1024,
+            windowsHide: true,
+        },
+    };
+}
+export async function runWindowsWeChatRpaVisualFlow(options) {
+    if (process.platform !== 'win32') {
+        throw new Error('WeChat RPA Windows visual flow can only run on Windows');
+    }
+    const exec = buildWindowsVisualFlowExec(options);
+    let stdout = '';
+    let stderr = '';
+    try {
+        const result = await execFileAsync(exec.command, exec.args, exec.execOptions);
+        stdout = String(result.stdout);
+        stderr = String(result.stderr);
+    }
+    catch (error) {
+        const execError = error;
+        stdout = execError.stdout ? String(execError.stdout) : '';
+        stderr = execError.stderr ? String(execError.stderr) : '';
+        const parsed = parseWindowsVisualStdout(stdout);
+        if (parsed)
+            return windowsSummaryToFlowResult(options, parsed);
+        throw new Error(stderr.trim() || stdout.slice(0, 1_000) || execError.message || 'WeChat RPA Windows visual flow failed');
+    }
+    const parsed = parseWindowsVisualStdout(stdout);
+    if (!parsed)
+        throw new Error(stderr.trim() || stdout.slice(0, 1_000) || 'WeChat RPA Windows visual flow returned invalid JSON');
+    const flow = windowsSummaryToFlowResult(options, parsed);
+    if (!flow.ok)
+        throw new Error(flow.error || 'WeChat RPA Windows visual flow failed');
+    return flow;
+}
+function parseWindowsVisualStdout(stdout) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        return null;
+    }
+}
+export function windowsSummaryToFlowResult(options, summary) {
+    const recentMessages = observationsToMessages(options.groupName, summary.recentMessages);
+    const sentText = Boolean(options.replyText && summary.sent?.some(item => item.type === 'text'));
+    const attachmentPaths = normalizeAttachmentPaths(options);
+    const sentAttachment = Boolean(attachmentPaths.length > 0 && summary.sent?.some(item => item.type === 'files'));
+    const postSendScreenshotPath = selectPostSendScreenshot(summary.artifacts);
+    return {
+        ok: Boolean(summary.ok),
+        groupName: summary.group || options.groupName,
+        screenshotPath: selectReadScreenshot(summary.artifacts),
+        recentMessages,
+        newMessages: recentMessages,
+        sentReply: Boolean(options.replyText),
+        sentReplyObserved: sentText,
+        sentAttachment: attachmentPaths.length > 0,
+        sentAttachmentObserved: sentAttachment,
+        ...(postSendScreenshotPath ? { postSendScreenshotPath } : {}),
+        ...(summary.error ? { error: summary.error } : {}),
+    };
+}
+function normalizeAttachmentPaths(options) {
+    const result = [];
+    if (options.attachmentPath)
+        result.push(options.attachmentPath);
+    for (const item of options.attachmentPaths || []) {
+        if (item && !result.includes(item))
+            result.push(item);
+    }
+    return result;
+}
+function observationsToMessages(groupName, observations) {
+    const messages = [];
+    for (const item of Array.isArray(observations) ? observations : []) {
+        const attachment = normalizeAttachment(item.attachment);
+        if (!shouldIncludeObservation(item, attachment))
+            continue;
+        const rawText = String(item.text || '').trim();
+        const text = attachment && shouldUseAttachmentNameAsMessageText(rawText, attachment) ? attachment.name || rawText : rawText;
+        if (!text && !attachment)
+            continue;
+        messages.push({
+            id: `win:${stableId(`${groupName}\n${text}\n${attachment?.name || ''}`)}`,
+            text,
+            confidence: item.confidence,
+            attachments: attachment ? [attachment] : [],
+        });
+    }
+    return messages;
+}
+function shouldUseAttachmentNameAsMessageText(text, attachment) {
+    const name = String(attachment.name || '').trim();
+    if (!name)
+        return false;
+    if (/^\[(图片|视频|语音|文件)\]$/u.test(name))
+        return true;
+    return Boolean(text && !text.includes(name) && (attachment.type === 'image' || attachment.type === 'video' || attachment.type === 'audio'));
+}
+function shouldIncludeObservation(item, attachment) {
+    const role = String(item.role || '').toLowerCase();
+    if (role === 'title' || role === 'sender' || role === 'timestamp' || role === 'system')
+        return false;
+    return Boolean(String(item.text || '').trim() || attachment);
+}
+function normalizeAttachment(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const type = String(value.type || '').trim();
+    if (!type)
+        return null;
+    return {
+        ...value,
+        type,
+        availability: value.availability || (value.localPath ? 'edge-local' : 'metadata-only'),
+    };
+}
+function selectReadScreenshot(artifacts) {
+    return artifacts?.find(item => /messages-before-send\.png$/i.test(item)) || artifacts?.find(item => /opened-conversation\.png$/i.test(item));
+}
+function selectPostSendScreenshot(artifacts) {
+    return artifacts?.find(item => /after-file-send\.png$/i.test(item)) || artifacts?.find(item => /after-text-send\.png$/i.test(item));
+}
+function resolveWindowsVisualScriptPath(scriptPath, workDir) {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        scriptPath,
+        process.env.SHENNIAN_WECHAT_RPA_WIN_VISUAL_SCRIPT,
+        path.resolve(moduleDir, '../../../scripts/wechat-rpa-win-visual.mjs'),
+        workDir ? path.join(workDir, 'scripts/wechat-rpa-win-visual.mjs') : '',
+        path.resolve(process.cwd(), 'scripts/wechat-rpa-win-visual.mjs'),
+    ].filter(Boolean);
+    const found = candidates.find((candidate) => fs.existsSync(candidate));
+    if (!found) {
+        throw new Error('WeChat RPA Windows visual script is missing; set SHENNIAN_WECHAT_RPA_WIN_VISUAL_SCRIPT or channel flowScriptPath');
+    }
+    return path.resolve(found);
+}
+function stableId(value) {
+    return crypto.createHash('sha256').update(value).digest('hex').slice(0, 24);
+}

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

@@ -1,29 +1,18 @@
-import type { ExternalChannelAdapter, ExternalChannelConfig, ExternalChannelRuntimeStatus, ExternalMessageAttachment, ExternalReply } from './base.js';
+import type { ExternalChannelAdapter, ExternalChannelConfig, ExternalChannelRuntimeStatus, ExternalMessageEvent, ExternalReply } from './base.js';
 import { type WeChatRpaObservedMessage } from './wechat-rpa/normalizer.js';
-type WeChatRpaEvent = {
+type WeChatRpaEvent = ExternalMessageEvent & {
+    type: 'external.message';
     managerSessionId: string;
-    channelId: string;
-    channelType: 'wechat-rpa';
-    conversationId: string;
-    messageId: string;
-    sender: {
-        id: string;
-        name?: string | null;
-    };
-    text: string;
-    attachments: ExternalMessageAttachment[];
-    receivedAt: string;
-    replyTarget: string;
-    rawRef?: string | null;
 };
 export declare class WeChatRpaChannelAdapter implements ExternalChannelAdapter {
     private onMessage?;
     readonly type: "wechat-rpa";
     private secrets;
     private connections;
-    constructor(onMessage?: ((event: WeChatRpaEvent) => void) | undefined);
+    constructor(onMessage?: ((event: WeChatRpaEvent) => ExternalMessageEvent | void) | undefined);
     connect(config: ExternalChannelConfig): Promise<void>;
     disconnect(config: ExternalChannelConfig): Promise<void>;
+    syncNow(config: ExternalChannelConfig): Promise<ExternalMessageEvent[]>;
     send(config: ExternalChannelConfig, reply: ExternalReply): Promise<{
         status: 'sent' | 'queued';
         reason?: string;
@@ -46,6 +35,14 @@ export declare class WeChatRpaChannelAdapter implements ExternalChannelAdapter {
     private seedConfiguredConversations;
     private resolveConversationName;
 }
+export declare function windowsVisualFlowHealth(secret: {
+    groups?: Array<{
+        name: string;
+    }>;
+}, platform?: NodeJS.Platform): {
+    ok: boolean;
+    message?: string;
+};
 export declare function materializeWeChatRpaOutboundAttachment(workDir: string, attachment: NonNullable<ExternalReply['attachment']>): Promise<string>;
 export declare function annotateWeChatRpaInboundAttachments(attachments: WeChatRpaObservedMessage['attachments']): WeChatRpaObservedMessage['attachments'];
 export {};

package/dist/src/channels/wechat-rpa.js

@@ -1,11 +1,13 @@
 // @arch docs/features/wechat-rpa-channel.md
 // @test src/__tests__/wechat-rpa-normalizer.test.ts
+// @test src/__tests__/wechat-rpa-health.test.ts
 import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { ChannelSecretRegistry } from './secret-registry.js';
 import { probeMacWeChat, observedMessageFromProbe } from './wechat-rpa/macos.js';
 import { runMacWeChatRpaFlow } from './wechat-rpa/macos-flow.js';
+import { runWindowsWeChatRpaVisualFlow } from './wechat-rpa/windows-visual-flow.js';
 import { normalizeWeChatRpaMessage, WeChatRpaDeduper, weChatRpaConversationId, } from './wechat-rpa/normalizer.js';
 const DEFAULT_POLL_INTERVAL_MS = 5_000;
 const DEFAULT_RECENT_LIMIT = 5;
@@ -28,6 +30,7 @@ export class WeChatRpaChannelAdapter {
         conn.stopped = false;
         conn.config = config;
         hydratePendingReplyState(conn, config);
+        hydrateMessageState(conn, config);
         this.seedConfiguredConversations(conn, secret);
         if (conn.timer)
             return;
@@ -46,16 +49,29 @@ export class WeChatRpaChannelAdapter {
             clearInterval(conn.timer);
         this.connections.delete(config.id);
     }
+    async syncNow(config) {
+        if (!config.enabled)
+            throw new Error('WeChat RPA channel is disabled');
+        const secret = this.readSecret(config);
+        const conn = this.ensureConnection(config);
+        conn.stopped = false;
+        conn.config = config;
+        hydratePendingReplyState(conn, config);
+        hydrateMessageState(conn, config);
+        this.seedConfiguredConversations(conn, secret);
+        return this.enqueueOperation(conn, () => this.pollOnce(conn, this.readSecret(conn.config)));
+    }
     async send(config, reply) {
         const secret = this.readSecret(config);
         if (secret.canReply === false)
             throw new Error('WeChat RPA channel does not allow replies');
-        if ((secret.source ?? 'macos-probe') !== 'macos-flow') {
-            throw new Error('WeChat RPA reply requires source=macos-flow');
+        if (!isFlowSource(secret.source)) {
+            throw new Error('WeChat RPA reply requires source=macos-flow or windows-visual-flow');
         }
         const conn = this.ensureConnection(config);
         conn.config = config;
         hydratePendingReplyState(conn, config);
+        hydrateMessageState(conn, config);
         this.seedConfiguredConversations(conn, secret);
         const conversationName = this.resolveConversationName(config, secret, reply.conversationId);
         if (!conversationName)
@@ -94,6 +110,21 @@ export class WeChatRpaChannelAdapter {
             conn.lastError = error instanceof Error ? error.message : String(error);
             throw error;
         }
+        const partial = applyPartialSendProgress(flow, { text, attachmentPath });
+        if (partial.status === 'queued') {
+            const reason = partial.reason;
+            enqueuePendingReply(conn, {
+                key: pendingKey,
+                conversationId: reply.conversationId,
+                conversationName,
+                text: partial.text,
+                attachmentPath: partial.attachmentPath,
+                reason,
+                skipText: partial.skipText,
+            });
+            conn.lastError = reason;
+            return { status: 'queued', reason };
+        }
         if (flow.interrupted) {
             const reason = flow.error || 'WeChat RPA send was interrupted by user activity';
             noteInterruption(conn, flow, reason);
@@ -101,12 +132,15 @@ export class WeChatRpaChannelAdapter {
                 key: pendingKey,
                 conversationId: reply.conversationId,
                 conversationName,
-                text,
+                text: partial.text,
                 attachmentPath,
                 reason,
+                skipText: partial.skipText,
             });
             return { status: 'queued', reason };
         }
+        if (!flow.ok)
+            throw new Error(flow.error || 'WeChat RPA send failed');
         recordCloudOcrRuntime(conn, flow);
         noteSuccessfulRun(conn);
         conn.lastError = null;
@@ -125,6 +159,9 @@ export class WeChatRpaChannelAdapter {
             if (!configuredGroups(secret).length)
                 return { ok: false, message: 'WeChat RPA macOS flow requires at least one group' };
         }
+        if (secret.source === 'windows-visual-flow') {
+            return windowsVisualFlowHealth(secret, process.platform);
+        }
         const probe = await probeMacWeChat();
         return probe.ok
             ? { ok: true, message: probe.wechatRunning ? 'WeChat detected' : 'WeChat is not running' }
@@ -167,6 +204,7 @@ export class WeChatRpaChannelAdapter {
                 pendingReplies: new Map(),
                 completedPendingReplyKeys: new Set(),
                 pendingStatePath: undefined,
+                messageStatePath: undefined,
                 operation: Promise.resolve(),
                 runtimeState: 'idle_waiting',
                 consecutiveInterruptions: 0,
@@ -189,16 +227,17 @@ export class WeChatRpaChannelAdapter {
     }
     async pollOnce(conn, secret) {
         if (conn.stopped)
-            return;
+            return [];
+        const emitted = [];
         conn.lastRunAt = new Date().toISOString();
         try {
             if (isInterruptionCooldownActive(conn, secret)) {
                 conn.runtimeState = 'cooldown';
-                return;
+                return [];
             }
             const pendingInterrupted = await this.drainPendingReplies(conn, secret);
             if (pendingInterrupted)
-                return;
+                return [];
             let interrupted = false;
             conn.runtimeState = 'syncing';
             const observed = await this.readObservedMessages(conn.config, secret, (flow) => {
@@ -213,9 +252,11 @@ export class WeChatRpaChannelAdapter {
                 const message = normalizeWeChatRpaMessage(item);
                 if (!message || !conn.deduper.accept(message.messageId))
                     continue;
+                persistMessageState(conn);
                 conn.conversations.set(message.conversationId, message.conversationName);
                 conn.lastMessageAt = message.receivedAt;
-                this.onMessage?.({
+                const event = {
+                    type: 'external.message',
                     managerSessionId: conn.config.managerSessionId,
                     channelId: conn.config.id,
                     channelType: 'wechat-rpa',
@@ -227,10 +268,12 @@ export class WeChatRpaChannelAdapter {
                     receivedAt: message.receivedAt,
                     replyTarget: '',
                     rawRef: message.rawRef,
-                });
+                };
+                emitted.push(this.onMessage?.(event) ?? event);
             }
             if (!interrupted)
                 noteSuccessfulRun(conn);
+            return emitted;
         }
         catch (error) {
             conn.lastError = error instanceof Error ? error.message : String(error);
@@ -245,15 +288,33 @@ export class WeChatRpaChannelAdapter {
             pending.attempts += 1;
             pending.lastAttemptAt = new Date().toISOString();
             persistPendingReplyState(conn);
-            const flow = await runSendFlow(conn.config, secret, pending.conversationName, pending.text, pending.attachmentPath);
+            const flow = await runSendFlow(conn.config, secret, pending.conversationName, pending.skipText ? '' : pending.text, pending.attachmentPath);
             recordCloudOcrRuntime(conn, flow);
+            const partial = applyPartialSendProgress(flow, {
+                text: pending.skipText ? '' : pending.text,
+                attachmentPath: pending.attachmentPath,
+            });
+            if (partial.status === 'queued') {
+                pending.text = partial.text;
+                pending.attachmentPath = partial.attachmentPath;
+                pending.skipText = partial.skipText;
+                pending.lastInterruptedReason = partial.reason;
+                conn.lastError = partial.reason;
+                persistPendingReplyState(conn);
+                return true;
+            }
             if (flow.interrupted) {
                 const reason = flow.error || 'WeChat RPA pending send was interrupted by user activity';
+                pending.text = partial.text;
+                pending.attachmentPath = partial.attachmentPath;
+                pending.skipText = partial.skipText;
                 pending.lastInterruptedReason = reason;
                 noteInterruption(conn, flow, reason);
                 persistPendingReplyState(conn);
                 return true;
             }
+            if (!flow.ok)
+                throw new Error(flow.error || 'WeChat RPA pending send failed');
             conn.pendingReplies.delete(pending.key);
             conn.completedPendingReplyKeys.add(pending.key);
             persistPendingReplyState(conn);
@@ -269,6 +330,9 @@ export class WeChatRpaChannelAdapter {
         if (secret.source === 'macos-flow') {
             return readMacFlowMessages(config, secret, onFlow);
         }
+        if (secret.source === 'windows-visual-flow') {
+            return readWindowsVisualFlowMessages(config, secret, onFlow);
+        }
         const probe = await probeMacWeChat();
         const message = observedMessageFromProbe(probe);
         return message ? [message] : [];
@@ -296,6 +360,14 @@ function configuredGroups(secret) {
         ? secret.groups.map((group) => String(group?.name || '').trim()).filter(Boolean)
         : [];
 }
+export function windowsVisualFlowHealth(secret, platform = process.platform) {
+    if (platform !== 'win32')
+        return { ok: false, message: 'WeChat RPA Windows visual flow requires Windows' };
+    if (!configuredGroups({ type: 'wechat-rpa', groups: secret.groups, updatedAt: '' }).length) {
+        return { ok: false, message: 'WeChat RPA Windows visual flow requires at least one group' };
+    }
+    return { ok: true, message: 'WeChat RPA Windows visual flow configured' };
+}
 async function readMacFlowMessages(config, secret, onFlow) {
     const result = [];
     for (const name of configuredGroups(secret)) {
@@ -333,7 +405,56 @@ async function readMacFlowMessages(config, secret, onFlow) {
     }
     return result;
 }
+async function readWindowsVisualFlowMessages(config, secret, onFlow) {
+    const result = [];
+    for (const name of configuredGroups(secret)) {
+        const flow = await runWindowsWeChatRpaVisualFlow({
+            groupName: name,
+            scriptPath: secret.flowScriptPath,
+            workDir: config.workDir,
+            recentLimit: clampNumber(secret.recentLimit, DEFAULT_RECENT_LIMIT, 0, 50),
+            downloadAttachmentsDir: resolveInboundAttachmentDir(config.workDir, secret),
+            cloudOcrUrl: typeof secret.cloudOcrUrl === 'string' ? secret.cloudOcrUrl : undefined,
+            cloudOcrToken: typeof secret.cloudOcrToken === 'string' ? secret.cloudOcrToken : undefined,
+            cloudOcrMode: normalizeCloudOcrMode(secret.cloudOcrMode),
+            cloudOcrChannelId: config.id,
+        });
+        onFlow?.(flow);
+        if (flow.interrupted)
+            continue;
+        for (const message of flow.newMessages ?? []) {
+            const text = String(message.text || '').trim();
+            const attachments = Array.isArray(message.attachments) ? message.attachments : [];
+            if (!text && attachments.length === 0)
+                continue;
+            result.push({
+                conversationName: name,
+                senderName: null,
+                text,
+                attachments: annotateWeChatRpaInboundAttachments(attachments),
+                observedAt: new Date().toISOString(),
+                rawId: String(message.id || `${name}:${text}`),
+            });
+        }
+    }
+    return result;
+}
 async function runSendFlow(config, secret, conversationName, text, attachmentPath) {
+    if (secret.source === 'windows-visual-flow') {
+        return runWindowsWeChatRpaVisualFlow({
+            groupName: conversationName,
+            replyText: text || undefined,
+            attachmentPath,
+            scriptPath: secret.flowScriptPath,
+            workDir: config.workDir,
+            recentLimit: clampNumber(secret.recentLimit, DEFAULT_RECENT_LIMIT, 0, 50),
+            downloadAttachmentsDir: resolveInboundAttachmentDir(config.workDir, secret),
+            cloudOcrUrl: typeof secret.cloudOcrUrl === 'string' ? secret.cloudOcrUrl : undefined,
+            cloudOcrToken: typeof secret.cloudOcrToken === 'string' ? secret.cloudOcrToken : undefined,
+            cloudOcrMode: normalizeCloudOcrMode(secret.cloudOcrMode),
+            cloudOcrChannelId: config.id,
+        });
+    }
     return runMacWeChatRpaFlow({
         groupName: conversationName,
         replyText: text || undefined,
@@ -351,6 +472,26 @@ async function runSendFlow(config, secret, conversationName, text, attachmentPat
         cloudOcrChannelId: config.id,
     });
 }
+function isFlowSource(source) {
+    return source === 'macos-flow' || source === 'windows-visual-flow';
+}
+function applyPartialSendProgress(flow, input) {
+    if (input.text && input.attachmentPath && flow.sentReplyObserved && !flow.sentAttachmentObserved) {
+        return {
+            status: flow.interrupted ? 'continue' : 'queued',
+            text: '',
+            attachmentPath: input.attachmentPath,
+            skipText: true,
+            reason: flow.error || 'WeChat RPA sent the text but did not confirm the attachment; queued attachment-only retry',
+        };
+    }
+    return {
+        status: 'continue',
+        text: input.text,
+        attachmentPath: input.attachmentPath,
+        reason: flow.error || '',
+    };
+}
 function pendingReplyKey(config, reply) {
     if (reply.idempotencyKey)
         return reply.idempotencyKey;
@@ -367,6 +508,7 @@ function enqueuePendingReply(conn, input) {
         conversationName: input.conversationName,
         text: input.text,
         attachmentPath: input.attachmentPath,
+        skipText: input.skipText,
         queuedAt: existing?.queuedAt ?? new Date().toISOString(),
         attempts: existing?.attempts ?? 0,
         lastAttemptAt: existing?.lastAttemptAt,
@@ -424,12 +566,45 @@ function isPendingReplyRecord(value) {
         && typeof record.queuedAt === 'string'
         && typeof record.attempts === 'number'
         && Number.isFinite(record.attempts)
-        && (record.attachmentPath === undefined || typeof record.attachmentPath === 'string');
+        && (record.attachmentPath === undefined || typeof record.attachmentPath === 'string')
+        && (record.skipText === undefined || typeof record.skipText === 'boolean');
 }
 function pendingReplyStatePath(config) {
     const id = crypto.createHash('sha256').update(config.id).digest('hex').slice(0, 16);
     return path.join(config.workDir, '.shennian', 'wechat-rpa-pending-replies', `${id}.json`);
 }
+function hydrateMessageState(conn, config) {
+    const filePath = messageStatePath(config);
+    if (conn.messageStatePath === filePath)
+        return;
+    conn.messageStatePath = filePath;
+    const store = readMessageSeenStore(filePath);
+    conn.deduper = new WeChatRpaDeduper((store.messageIds ?? []).filter((id) => typeof id === 'string' && id.length > 0));
+}
+function persistMessageState(conn) {
+    if (!conn.messageStatePath)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(conn.messageStatePath), { recursive: true });
+        fs.writeFileSync(conn.messageStatePath, JSON.stringify({ version: 1, messageIds: conn.deduper.snapshot() }, null, 2));
+    }
+    catch {
+        // Best-effort only; in-memory dedupe still protects the current daemon.
+    }
+}
+function readMessageSeenStore(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return parsed && parsed.version === 1 ? parsed : { version: 1, messageIds: [] };
+    }
+    catch {
+        return { version: 1, messageIds: [] };
+    }
+}
+function messageStatePath(config) {
+    const id = crypto.createHash('sha256').update(config.id).digest('hex').slice(0, 16);
+    return path.join(config.workDir, '.shennian', 'wechat-rpa-seen-messages', `${id}.json`);
+}
 function noteInterruption(conn, flow, reason) {
     conn.lastInterruptedAt = new Date().toISOString();
     conn.lastError = null;
@@ -489,13 +664,10 @@ export async function materializeWeChatRpaOutboundAttachment(workDir, attachment
             throw new Error(`WeChat RPA local attachment does not exist: ${attachment.localPath}`);
         return attachment.localPath;
     }
-    if (attachment.dataBase64) {
-        return writeOutboundAttachmentBuffer(workDir, attachment, Buffer.from(attachment.dataBase64, 'base64'));
-    }
     if (attachment.url) {
         return downloadOutboundAttachment(workDir, attachment);
     }
-    throw new Error('WeChat RPA attachment requires dataBase64, localPath, or url');
+    throw new Error('WeChat RPA attachment requires localPath or url; dataBase64 is not accepted over Manager IPC');
 }
 async function downloadOutboundAttachment(workDir, attachment) {
     if (!attachment.url || !/^https?:\/\//i.test(attachment.url))

package/dist/src/commands/external.js

@@ -49,6 +49,7 @@ function processExists(pid) {
 }
 async function sendExternal(input) {
     const ctx = requireExternalContext(input.sessionId);
+    const replyTarget = input.replyTarget?.trim() || process.env.SHENNIAN_EXTERNAL_REPLY_TARGET || undefined;
     const response = await fetch(`${ctx.url}/external/reply`, {
         method: 'POST',
         headers: {
@@ -61,6 +62,7 @@ async function sendExternal(input) {
             text: input.text,
             attachment: input.attachment,
             idempotencyKey: input.idempotencyKey,
+            replyTarget,
         }),
     });
     const data = await response.json().catch(() => ({ ok: false, error: response.statusText }));
@@ -76,9 +78,10 @@ export function registerExternalCommand(program) {
         .description('Send a message to the external channel bound to this conversation')
         .requiredOption('--text <text>', 'Message text')
         .option('--session-id <id>', 'Shennian conversation/session id; defaults to injected current-session env')
+        .option('--reply-target <id>', 'Daemon-generated reply target; defaults to SHENNIAN_EXTERNAL_REPLY_TARGET or latest external message')
         .option('--idempotency-key <key>', 'Idempotency key')
         .action(async (opts) => {
-        await sendExternal({ text: opts.text, idempotencyKey: opts.idempotencyKey, sessionId: opts.sessionId });
+        await sendExternal({ text: opts.text, replyTarget: opts.replyTarget, idempotencyKey: opts.idempotencyKey, sessionId: opts.sessionId });
     });
     external
         .command('send-image')
@@ -86,11 +89,13 @@ export function registerExternalCommand(program) {
         .requiredOption('--path <path>', 'Image file path')
         .option('--caption <text>', 'Optional text to send before the image')
         .option('--session-id <id>', 'Shennian conversation/session id; defaults to injected current-session env')
+        .option('--reply-target <id>', 'Daemon-generated reply target; defaults to SHENNIAN_EXTERNAL_REPLY_TARGET or latest external message')
         .option('--idempotency-key <key>', 'Idempotency key')
         .action(async (opts) => {
         await sendExternal({
             text: opts.caption,
             attachment: readExternalAttachment(opts.path, 'image'),
+            replyTarget: opts.replyTarget,
             idempotencyKey: opts.idempotencyKey,
             sessionId: opts.sessionId,
         });
@@ -101,11 +106,13 @@ export function registerExternalCommand(program) {
         .requiredOption('--path <path>', 'Video file path')
         .option('--caption <text>', 'Optional text to send before the video')
         .option('--session-id <id>', 'Shennian conversation/session id; defaults to injected current-session env')
+        .option('--reply-target <id>', 'Daemon-generated reply target; defaults to SHENNIAN_EXTERNAL_REPLY_TARGET or latest external message')
         .option('--idempotency-key <key>', 'Idempotency key')
         .action(async (opts) => {
         await sendExternal({
             text: opts.caption,
             attachment: readExternalAttachment(opts.path, 'video'),
+            replyTarget: opts.replyTarget,
             idempotencyKey: opts.idempotencyKey,
             sessionId: opts.sessionId,
         });
@@ -116,11 +123,13 @@ export function registerExternalCommand(program) {
         .requiredOption('--path <path>', 'File path')
         .option('--caption <text>', 'Optional text to send before the file')
         .option('--session-id <id>', 'Shennian conversation/session id; defaults to injected current-session env')
+        .option('--reply-target <id>', 'Daemon-generated reply target; defaults to SHENNIAN_EXTERNAL_REPLY_TARGET or latest external message')
         .option('--idempotency-key <key>', 'Idempotency key')
         .action(async (opts) => {
         await sendExternal({
             text: opts.caption,
             attachment: readExternalAttachment(opts.path, 'file'),
+            replyTarget: opts.replyTarget,
             idempotencyKey: opts.idempotencyKey,
             sessionId: opts.sessionId,
         });