shennian 0.2.88 → 0.2.89

package/dist/src/channels/wechat-channel/helper-protocol.js

@@ -0,0 +1,115 @@
+// @arch docs/features/wechat-rpa-helper-runtime.md
+// @test src/__tests__/wechat-channel-helper-protocol.test.ts
+export const WECHAT_CHANNEL_HELPER_PROTOCOL_VERSION = 1;
+export const WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS = {
+    healthCheck: 2_000,
+    ocrRecognize: 10_000,
+    windowsCapture: 5_000,
+    mouseKeyboard: 3_000,
+    clipboard: 5_000,
+    menuPickItem: 5_000,
+};
+export const WECHAT_CHANNEL_REQUIRED_HELPER_CAPABILITIES = [
+    'screenCapture',
+    'visionOcr',
+    'windowList',
+    'windowFocus',
+    'mouseKeyboard',
+    'clipboard',
+    'contextMenu',
+    'imageCropHash',
+];
+export function createWeChatChannelHelperHello(expectedHelperVersion) {
+    const version = String(expectedHelperVersion || '').trim();
+    if (!version)
+        throw new Error('WeChat channel helper expected version is required');
+    return {
+        type: 'hello',
+        protocolVersion: WECHAT_CHANNEL_HELPER_PROTOCOL_VERSION,
+        expectedHelperVersion: version,
+        capabilities: [...WECHAT_CHANNEL_REQUIRED_HELPER_CAPABILITIES],
+    };
+}
+export function validateWeChatChannelHelperReady(ready, expectedHelperVersion) {
+    if (!ready || ready.type !== 'ready') {
+        return { ok: false, errorCode: 'helper_invalid_response', errorSummary: 'Helper did not send a ready frame' };
+    }
+    if (ready.protocolVersion !== WECHAT_CHANNEL_HELPER_PROTOCOL_VERSION) {
+        return {
+            ok: false,
+            errorCode: 'helper_protocol_mismatch',
+            errorSummary: `Helper protocol ${ready.protocolVersion} does not match ${WECHAT_CHANNEL_HELPER_PROTOCOL_VERSION}`,
+        };
+    }
+    if (ready.helperVersion !== expectedHelperVersion) {
+        return {
+            ok: false,
+            errorCode: 'helper_version_mismatch',
+            errorSummary: `Helper version ${ready.helperVersion} does not match ${expectedHelperVersion}`,
+        };
+    }
+    const missing = WECHAT_CHANNEL_REQUIRED_HELPER_CAPABILITIES.filter((capability) => !ready.capabilities.includes(capability));
+    if (missing.length) {
+        return {
+            ok: false,
+            errorCode: 'helper_capability_missing',
+            errorSummary: `Helper missing capabilities: ${missing.join(', ')}`,
+        };
+    }
+    return { ok: true };
+}
+export function extractWeChatChannelHelperWarmupSnapshot(value) {
+    if (!value || typeof value !== 'object')
+        return null;
+    const record = value;
+    if (!isWeChatChannelHelperWarmState(record.warmState))
+        return null;
+    const metrics = normalizeWeChatChannelHelperWarmupMetrics(record.warmup);
+    return metrics ? { warmState: record.warmState, metrics } : { warmState: record.warmState };
+}
+export function timeoutForWeChatChannelHelperCommand(command) {
+    if (command === 'health.check')
+        return WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS.healthCheck;
+    if (command === 'ocr.recognize')
+        return WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS.ocrRecognize;
+    if (command === 'windows.capture')
+        return WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS.windowsCapture;
+    if (command.startsWith('mouse.') || command.startsWith('keyboard.'))
+        return WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS.mouseKeyboard;
+    if (command.startsWith('clipboard.'))
+        return WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS.clipboard;
+    if (command === 'menu.pickItem')
+        return WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS.menuPickItem;
+    return WECHAT_CHANNEL_HELPER_COMMAND_TIMEOUT_MS.healthCheck;
+}
+function isWeChatChannelHelperWarmState(value) {
+    return value === 'cold' || value === 'warming' || value === 'warm' || value === 'failed';
+}
+function normalizeWeChatChannelHelperWarmupMetrics(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const source = value;
+    const metrics = {};
+    copyStringField(source, metrics, 'startedAt');
+    copyStringField(source, metrics, 'readyAt');
+    copyStringField(source, metrics, 'warmupStartedAt');
+    copyStringField(source, metrics, 'warmupCompletedAt');
+    copyNumberField(source, metrics, 'coldStartMs');
+    copyNumberField(source, metrics, 'warmupMs');
+    copyNumberField(source, metrics, 'firstOcrMs');
+    copyNumberField(source, metrics, 'warmOcrMs');
+    copyNumberField(source, metrics, 'lastOcrMs');
+    copyNumberField(source, metrics, 'ocrSampleCount');
+    copyStringField(source, metrics, 'errorCode');
+    copyStringField(source, metrics, 'errorSummary');
+    return Object.keys(metrics).length > 0 ? metrics : undefined;
+}
+function copyStringField(source, target, key) {
+    if (typeof source[key] === 'string')
+        target[key] = source[key];
+}
+function copyNumberField(source, target, key) {
+    const value = source[key];
+    if (typeof value === 'number' && Number.isFinite(value) && value >= 0)
+        target[key] = value;
+}

package/dist/src/channels/wechat-channel/index.d.ts

@@ -0,0 +1,16 @@
+export * from './runtime.js';
+export * from './helper-protocol.js';
+export * from './helper-client.js';
+export * from './helper-assets.js';
+export * from './client.js';
+export * from './ledger.js';
+export * from './scheduler.js';
+export * from './fingerprint.js';
+export * from './observer.js';
+export * from './anchor.js';
+export * from './outbound-ledger.js';
+export * from './media-resolver.js';
+export * from './preflight.js';
+export * from './cooldown.js';
+export * from './message-key.js';
+export * from './runner.js';

package/dist/src/channels/wechat-channel/index.js

@@ -0,0 +1,19 @@
+// @arch docs/features/wechat-rpa-productization-plan.md
+// @test src/__tests__/wechat-channel-runtime.test.ts
+// @test src/__tests__/wechat-channel-helper-protocol.test.ts
+export * from './runtime.js';
+export * from './helper-protocol.js';
+export * from './helper-client.js';
+export * from './helper-assets.js';
+export * from './client.js';
+export * from './ledger.js';
+export * from './scheduler.js';
+export * from './fingerprint.js';
+export * from './observer.js';
+export * from './anchor.js';
+export * from './outbound-ledger.js';
+export * from './media-resolver.js';
+export * from './preflight.js';
+export * from './cooldown.js';
+export * from './message-key.js';
+export * from './runner.js';

package/dist/src/channels/wechat-channel/ledger.d.ts

@@ -0,0 +1,33 @@
+import type { WeChatChannelObservedMessage } from './client.js';
+import type { WeChatChannelCooldownState } from './cooldown.js';
+export type WeChatChannelLedger = {
+    version: 1;
+    runtimeId: string;
+    bindings: Record<string, WeChatChannelBindingLedger>;
+};
+export type WeChatChannelBindingLedger = {
+    bindingId: string;
+    baselineEstablished: boolean;
+    disabledSince?: string | null;
+    revision: number;
+    recent: WeChatChannelObservedMessage[];
+    pendingSendKeys: string[];
+    cooldown?: WeChatChannelCooldownState;
+};
+export declare function loadWeChatChannelLedger(filePath: string, runtimeId: string): WeChatChannelLedger;
+export declare function saveWeChatChannelLedger(filePath: string, ledger: WeChatChannelLedger): void;
+export declare function updateWeChatChannelBindingLedger(input: {
+    ledger: WeChatChannelLedger;
+    bindingId: string;
+    observedMessages: WeChatChannelObservedMessage[];
+    baselineOnly?: boolean;
+}): {
+    binding: WeChatChannelBindingLedger;
+    newMessages: WeChatChannelObservedMessage[];
+};
+export declare function markWeChatChannelBindingDisabled(input: {
+    ledger: WeChatChannelLedger;
+    bindingId: string;
+    disabledAt?: Date;
+}): WeChatChannelBindingLedger;
+export declare function filterDeliverableWeChatMessages(previous: WeChatChannelObservedMessage[], current: WeChatChannelObservedMessage[]): WeChatChannelObservedMessage[];

package/dist/src/channels/wechat-channel/ledger.js

@@ -0,0 +1,54 @@
+// @arch docs/features/wechat-rpa-productization-plan.md
+// @test src/__tests__/wechat-channel-ledger.test.ts
+import fs from 'node:fs';
+import path from 'node:path';
+import { WECHAT_CHANNEL_RECENT_MESSAGE_WINDOW } from './runtime.js';
+import { filterNewWeChatMessagesByAnchor } from './anchor.js';
+import { normalizeWeChatObservedWindowForLedger } from './message-key.js';
+export function loadWeChatChannelLedger(filePath, runtimeId) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        if (parsed?.version === 1 && parsed.runtimeId === runtimeId && parsed.bindings && typeof parsed.bindings === 'object')
+            return parsed;
+    }
+    catch { }
+    return { version: 1, runtimeId, bindings: {} };
+}
+export function saveWeChatChannelLedger(filePath, ledger) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(ledger, null, 2));
+}
+export function updateWeChatChannelBindingLedger(input) {
+    const existing = input.ledger.bindings[input.bindingId];
+    const retained = normalizeWeChatObservedWindowForLedger(input.observedMessages).slice(-WECHAT_CHANNEL_RECENT_MESSAGE_WINDOW);
+    const baselineOnly = input.baselineOnly || !existing?.baselineEstablished || Boolean(existing?.disabledSince);
+    const newMessages = baselineOnly ? [] : filterDeliverableWeChatMessages(existing?.recent ?? [], retained);
+    const binding = {
+        bindingId: input.bindingId,
+        baselineEstablished: true,
+        disabledSince: null,
+        revision: (existing?.revision ?? 0) + (newMessages.length > 0 ? 1 : 0),
+        recent: retained,
+        pendingSendKeys: existing?.pendingSendKeys ?? [],
+        cooldown: existing?.cooldown,
+    };
+    input.ledger.bindings[input.bindingId] = binding;
+    return { binding, newMessages };
+}
+export function markWeChatChannelBindingDisabled(input) {
+    const existing = input.ledger.bindings[input.bindingId];
+    const binding = {
+        bindingId: input.bindingId,
+        baselineEstablished: false,
+        disabledSince: (input.disabledAt ?? new Date()).toISOString(),
+        revision: existing?.revision ?? 0,
+        recent: existing?.recent ?? [],
+        pendingSendKeys: existing?.pendingSendKeys ?? [],
+        cooldown: existing?.cooldown,
+    };
+    input.ledger.bindings[input.bindingId] = binding;
+    return binding;
+}
+export function filterDeliverableWeChatMessages(previous, current) {
+    return filterNewWeChatMessagesByAnchor({ previous, current }).filter((message) => message.senderRole !== 'self');
+}

package/dist/src/channels/wechat-channel/media-resolver.d.ts

@@ -0,0 +1,32 @@
+import type { ExternalMessageAttachment } from '../base.js';
+import type { WeChatChannelHelperTransport } from './observer.js';
+export type WeChatChannelVisibleMediaCandidate = {
+    messageKey: string;
+    kind: 'image' | 'video' | 'file' | 'link' | 'card' | string;
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        coordinateSpace?: string;
+    };
+    fileName?: string | null;
+    mimeType?: string | null;
+    size?: number | null;
+    mediaStatus?: 'available' | 'not_downloaded' | 'metadata_only' | 'unsupported' | string | null;
+};
+export type WeChatChannelMediaResolveResult = {
+    messageKey: string;
+    attachment: ExternalMessageAttachment;
+    reasonCode: string;
+};
+export declare function defaultWeChatChannelAttachmentDir(workDir: string, runtimeId: string, bindingId: string): string;
+export declare function resolveVisibleWeChatChannelMedia(input: {
+    helper: WeChatChannelHelperTransport;
+    candidates: WeChatChannelVisibleMediaCandidate[];
+    attachmentsDir: string;
+    windowId?: string;
+    traceId?: string;
+}): Promise<WeChatChannelMediaResolveResult[]>;
+export declare function materializeLocalAttachment(candidate: WeChatChannelVisibleMediaCandidate, sourcePath: string, attachmentsDir: string): ExternalMessageAttachment;
+export declare function metadataOnlyResult(candidate: WeChatChannelVisibleMediaCandidate, reasonCode: string): WeChatChannelMediaResolveResult;

package/dist/src/channels/wechat-channel/media-resolver.js

@@ -0,0 +1,181 @@
+// @arch docs/features/wechat-rpa-productization-plan.md
+// @arch docs/features/wechat-rpa-helper-runtime.md
+// @test src/__tests__/wechat-channel-media-resolver.test.ts
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_INBOUND_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+export function defaultWeChatChannelAttachmentDir(workDir, runtimeId, bindingId) {
+    const key = crypto.createHash('sha256').update(`${runtimeId}:${bindingId}`).digest('hex').slice(0, 16);
+    return path.join(workDir, '.uploads', 'wechat-channel', 'inbound', key);
+}
+export async function resolveVisibleWeChatChannelMedia(input) {
+    const results = [];
+    for (const candidate of input.candidates) {
+        if (!isDownloadableCandidate(candidate)) {
+            results.push(metadataOnlyResult(candidate, 'unsupported_media_kind'));
+            continue;
+        }
+        if (!candidate.bbox) {
+            results.push(metadataOnlyResult(candidate, 'media_bbox_missing'));
+            continue;
+        }
+        const snapshot = await input.helper.request('clipboard.snapshot', {}, input.traceId);
+        assertHelperOk(snapshot, 'clipboard.snapshot');
+        try {
+            const center = bboxCenter(candidate.bbox);
+            const rightClick = await input.helper.request('mouse.rightClick', {
+                x: center.x,
+                y: center.y,
+                coordinateSpace: center.coordinateSpace,
+                windowId: input.windowId,
+            }, input.traceId);
+            assertHelperOk(rightClick, 'mouse.rightClick');
+            const picked = await input.helper.request('menu.pickItem', {
+                labels: menuLabelsForCandidate(candidate),
+                disallowLabels: ['保存', '另存为', 'Save As', 'Save to Downloads'],
+            }, input.traceId);
+            assertHelperOk(picked, 'menu.pickItem');
+            const fileUrls = await input.helper.request('clipboard.readFileUrls', {}, input.traceId);
+            assertHelperOk(fileUrls, 'clipboard.readFileUrls');
+            const localPath = firstClipboardPath(fileUrls.result);
+            if (!localPath) {
+                results.push(metadataOnlyResult(candidate, 'clipboard_file_url_unavailable'));
+                continue;
+            }
+            results.push({
+                messageKey: candidate.messageKey,
+                attachment: materializeLocalAttachment(candidate, localPath, input.attachmentsDir),
+                reasonCode: 'edge_local',
+            });
+        }
+        finally {
+            const restore = await input.helper.request('clipboard.restore', snapshot.result && typeof snapshot.result === 'object' ? snapshot.result : {}, input.traceId);
+            if (!restore.ok) {
+                results.push(metadataOnlyResult(candidate, restore.errorCode || 'clipboard_restore_failed'));
+            }
+        }
+    }
+    return results;
+}
+export function materializeLocalAttachment(candidate, sourcePath, attachmentsDir) {
+    const stat = fs.statSync(sourcePath);
+    if (!stat.isFile())
+        throw new Error('wechat_channel_attachment_not_file');
+    if (stat.size > MAX_INBOUND_ATTACHMENT_BYTES) {
+        return {
+            type: normalizeAttachmentType(candidate.kind),
+            name: safeFileName(candidate.fileName || path.basename(sourcePath)),
+            size: stat.size,
+            mimeType: candidate.mimeType || mimeFromPath(sourcePath),
+            availability: 'unavailable-large',
+            providerError: 'attachment_too_large',
+        };
+    }
+    fs.mkdirSync(attachmentsDir, { recursive: true });
+    const buffer = fs.readFileSync(sourcePath);
+    const hash = crypto.createHash('sha256').update(buffer).digest('hex');
+    const name = safeFileName(candidate.fileName || path.basename(sourcePath));
+    const ext = path.extname(name) || path.extname(sourcePath);
+    const stem = ext ? name.slice(0, -ext.length) : name;
+    const targetPath = path.join(attachmentsDir, `${stem}-${hash.slice(0, 12)}${ext}`);
+    if (!fs.existsSync(targetPath))
+        fs.writeFileSync(targetPath, buffer);
+    return {
+        type: normalizeAttachmentType(candidate.kind),
+        name,
+        mimeType: candidate.mimeType || mimeFromPath(sourcePath),
+        size: buffer.byteLength,
+        localPath: targetPath,
+        hash,
+        availability: 'edge-local',
+    };
+}
+export function metadataOnlyResult(candidate, reasonCode) {
+    return {
+        messageKey: candidate.messageKey,
+        reasonCode,
+        attachment: {
+            type: normalizeAttachmentType(candidate.kind),
+            name: safeFileName(candidate.fileName || `${candidate.kind || 'attachment'}`),
+            ...(candidate.mimeType ? { mimeType: candidate.mimeType } : {}),
+            ...(Number.isFinite(candidate.size) ? { size: Number(candidate.size) } : {}),
+            availability: candidate.mediaStatus === 'not_downloaded' ? 'pending-download' : 'metadata-only',
+            providerError: reasonCode,
+        },
+    };
+}
+function isDownloadableCandidate(candidate) {
+    return candidateMediaType(candidate.kind) !== null;
+}
+function candidateMediaType(kind) {
+    const normalized = String(kind || '').toLowerCase();
+    if (normalized.includes('video'))
+        return 'video';
+    if (normalized.includes('image') || normalized.includes('photo'))
+        return 'image';
+    if (normalized.includes('file') || normalized.includes('document'))
+        return 'file';
+    return null;
+}
+function normalizeAttachmentType(kind) {
+    const mediaType = candidateMediaType(kind);
+    if (mediaType)
+        return mediaType;
+    return 'file';
+}
+function menuLabelsForCandidate(candidate) {
+    const type = normalizeAttachmentType(candidate.kind);
+    if (type === 'image')
+        return ['复制图片', '复制', 'Copy Image', 'Copy'];
+    if (type === 'video')
+        return ['复制', 'Copy'];
+    return ['复制', 'Copy'];
+}
+function firstClipboardPath(result) {
+    const raw = result?.filePaths?.[0] || result?.fileUrls?.[0];
+    if (!raw)
+        return null;
+    if (raw.startsWith('file://'))
+        return decodeURIComponent(new URL(raw).pathname);
+    return raw;
+}
+function bboxCenter(bbox) {
+    return {
+        x: bbox.x + bbox.width / 2,
+        y: bbox.y + bbox.height / 2,
+        coordinateSpace: bbox.coordinateSpace,
+    };
+}
+function safeFileName(name) {
+    return path.basename(name || 'attachment')
+        .normalize('NFKC')
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, '_')
+        .replace(/\s+/g, ' ')
+        .replace(/^[ ._]+|[ ._]+$/g, '')
+        || 'attachment';
+}
+function mimeFromPath(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.png')
+        return 'image/png';
+    if (ext === '.jpg' || ext === '.jpeg')
+        return 'image/jpeg';
+    if (ext === '.gif')
+        return 'image/gif';
+    if (ext === '.webp')
+        return 'image/webp';
+    if (ext === '.mp4')
+        return 'video/mp4';
+    if (ext === '.mov')
+        return 'video/quicktime';
+    if (ext === '.pdf')
+        return 'application/pdf';
+    if (ext === '.txt')
+        return 'text/plain';
+    return 'application/octet-stream';
+}
+function assertHelperOk(response, command) {
+    if (!response.ok)
+        throw new Error(`${response.errorCode || 'helper_command_failed'}: ${response.errorSummary || command}`);
+}

package/dist/src/channels/wechat-channel/message-key.d.ts

@@ -0,0 +1,19 @@
+import type { WeChatChannelObservedMessage } from './client.js';
+export type WeChatChannelMessageKeyInput = Omit<WeChatChannelObservedMessage, 'stableMessageKey'> & {
+    stableMessageKey?: string | null;
+};
+export type WeChatChannelNormalizedMessage = WeChatChannelObservedMessage & {
+    stableKeyVersion: 1;
+};
+export declare function normalizeWeChatObservedWindowForLedger(messages: WeChatChannelMessageKeyInput[]): WeChatChannelNormalizedMessage[];
+export declare function buildStableWeChatMessageKey(message: WeChatChannelMessageKeyInput, windowIndex?: number, occurrence?: number): string;
+export declare function buildAnchorMetadata(message: WeChatChannelMessageKeyInput, windowIndex: number, occurrence: number): {
+    stableKeyVersion: number;
+    windowIndex: number;
+    occurrence: number;
+    senderRole: "unknown" | "self" | "system" | "contact";
+    kind: string;
+    anchorText: string;
+    bboxBand: string | null;
+    mediaSignature: string | null;
+};

package/dist/src/channels/wechat-channel/message-key.js

@@ -0,0 +1,105 @@
+// @arch docs/features/wechat-rpa-productization-plan.md
+// @test src/__tests__/wechat-channel-message-key.test.ts
+import crypto from 'node:crypto';
+import { normalizeWeChatAnchorText } from './anchor.js';
+export function normalizeWeChatObservedWindowForLedger(messages) {
+    const baseCounts = new Map();
+    return messages.map((message, windowIndex) => {
+        const base = stableMessageBase(message, windowIndex);
+        const occurrence = baseCounts.get(base) ?? 0;
+        baseCounts.set(base, occurrence + 1);
+        const anchorMetadata = buildAnchorMetadata(message, windowIndex, occurrence);
+        const stableMessageKey = normalizeExplicitKey(message.stableMessageKey) || hashStableMessageKey({ base, occurrence });
+        const anchorText = message.anchorText || message.normalizedText || message.textExcerpt || '';
+        return {
+            ...message,
+            stableMessageKey,
+            stableKeyVersion: 1,
+            anchorText,
+            anchorMetadata: {
+                ...(isRecord(message.anchorMetadata) ? message.anchorMetadata : {}),
+                ...anchorMetadata,
+            },
+        };
+    });
+}
+export function buildStableWeChatMessageKey(message, windowIndex = 0, occurrence = 0) {
+    return normalizeExplicitKey(message.stableMessageKey) || hashStableMessageKey({
+        base: stableMessageBase(message, windowIndex),
+        occurrence,
+    });
+}
+export function buildAnchorMetadata(message, windowIndex, occurrence) {
+    return {
+        stableKeyVersion: 1,
+        windowIndex,
+        occurrence,
+        senderRole: message.senderRole,
+        kind: message.kind,
+        anchorText: normalizeWeChatAnchorText(message.anchorText || message.normalizedText || message.textExcerpt || ''),
+        bboxBand: bboxBand(message.bbox),
+        mediaSignature: mediaSignature(message),
+    };
+}
+function stableMessageBase(message, windowIndex) {
+    return JSON.stringify({
+        senderRole: message.senderRole || 'unknown',
+        senderName: normalizeWeChatAnchorText(message.senderName || ''),
+        kind: message.kind || 'text',
+        anchorText: normalizeWeChatAnchorText(message.anchorText || message.normalizedText || message.textExcerpt || ''),
+        bboxBand: bboxBand(message.bbox),
+        mediaSignature: mediaSignature(message),
+        neighborSignature: neighborSignature(message.neighborContext),
+        orderBand: Math.floor(windowIndex / 4),
+    });
+}
+function hashStableMessageKey(input) {
+    return `wk1_${crypto.createHash('sha256').update(`${input.base}|${input.occurrence}`).digest('hex').slice(0, 24)}`;
+}
+function normalizeExplicitKey(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed || null;
+}
+function bboxBand(value) {
+    if (!isRecord(value))
+        return null;
+    const x = numberPart(value.x);
+    const y = numberPart(value.y);
+    const width = numberPart(value.width);
+    const height = numberPart(value.height);
+    if ([x, y, width, height].some((part) => part === null))
+        return null;
+    return [x, y, width, height].map((part) => Math.round((part ?? 0) / 20) * 20).join(',');
+}
+function mediaSignature(message) {
+    const metadata = isRecord(message.mediaMetadata) ? message.mediaMetadata : {};
+    const visualBlocks = Array.isArray(message.visualBlocks) ? message.visualBlocks : [];
+    const parts = [
+        stringPart(metadata.fileName),
+        stringPart(metadata.mimeType),
+        stringPart(metadata.size),
+        ...visualBlocks.map((block) => `${block.blockKind}:${block.blockId}`),
+    ].filter(Boolean);
+    return parts.length ? parts.join('|') : null;
+}
+function neighborSignature(value) {
+    if (!isRecord(value))
+        return null;
+    const before = normalizeWeChatAnchorText(value.beforeText || value.previousText || value.prev);
+    const after = normalizeWeChatAnchorText(value.afterText || value.nextText || value.next);
+    return before || after ? `${before.slice(0, 24)}|${after.slice(0, 24)}` : null;
+}
+function numberPart(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
+function stringPart(value) {
+    if (value === undefined || value === null)
+        return null;
+    return String(value).trim() || null;
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}

package/dist/src/channels/wechat-channel/observer.d.ts

@@ -0,0 +1,64 @@
+import type { WeChatChannelHelperCommandName, WeChatChannelHelperResponse } from './helper-protocol.js';
+import type { WeChatChannelRuntime, WeChatChannelBindingConfig } from './runtime.js';
+import type { WeChatChannelApiClient, WeChatChannelObservedMessage } from './client.js';
+import { type WeChatConversationListFingerprint } from './fingerprint.js';
+export type WeChatChannelHelperTransport = {
+    request<T = unknown>(command: WeChatChannelHelperCommandName, params?: Record<string, unknown>, traceId?: string): Promise<WeChatChannelHelperResponse<T>>;
+};
+export type WeChatChannelWindowInfo = {
+    windowId: string;
+    appName?: string | null;
+    title?: string | null;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        coordinateSpace?: string;
+    };
+};
+export type WeChatChannelScreenshot = {
+    mimeType: string;
+    dataBase64: string;
+    width: number;
+    height: number;
+    windowId?: string | null;
+};
+export type WeChatChannelOcrBlock = {
+    text?: string;
+    bbox?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        coordinateSpace?: string;
+    };
+    confidence?: number;
+};
+export type WeChatChannelOcrResult = {
+    blocks?: WeChatChannelOcrBlock[];
+    visibleConversationFingerprints?: WeChatConversationListFingerprint[];
+};
+export type WeChatChannelObserveApi = Pick<WeChatChannelApiClient, 'observe'>;
+export type HelperBackedObserveOptions = {
+    runtime: WeChatChannelRuntime;
+    binding: WeChatChannelBindingConfig;
+    helper: WeChatChannelHelperTransport;
+    api: WeChatChannelObserveApi;
+    traceId?: string;
+    localLedgerTailAnchors?: unknown[];
+};
+export declare function observeWeChatChannelBindingViaHelper(options: HelperBackedObserveOptions): Promise<WeChatChannelObservedMessage[]>;
+export declare function ensureHelperPreflight(helper: WeChatChannelHelperTransport, traceId?: string): Promise<void>;
+export declare function focusWeChatWindow(helper: WeChatChannelHelperTransport, traceId?: string): Promise<WeChatChannelWindowInfo>;
+export declare function openConversationInVisibleList(input: {
+    helper: WeChatChannelHelperTransport;
+    window: WeChatChannelWindowInfo;
+    binding: WeChatChannelBindingConfig;
+    traceId?: string;
+}): Promise<{
+    opened: boolean;
+    reason: string;
+}>;
+export declare function captureWeChatWindow(helper: WeChatChannelHelperTransport, windowId: string, traceId?: string): Promise<WeChatChannelScreenshot>;
+export declare function recognizeWeChatScreenshot(helper: WeChatChannelHelperTransport, screenshot: WeChatChannelScreenshot, traceId?: string): Promise<WeChatChannelOcrResult>;